GraphRAG

Global search

Implement the GraphRAG pattern in this codebase, using the LLM client and language we already use.

## Goal

Answer whole-corpus questions, such as 'what are the main themes?', by building an entity graph of the corpus offline, writing a summary of each community in it, and map-reducing over those summaries at query time.

## How it works

1. At index time, split the documents into chunks and call the extractor model with the Entity extraction prompt on each chunk, collecting entities and relationships with short descriptions.
2. Merge duplicate entities across chunks and build a graph: entities as nodes, relationships as weighted edges.
3. Cluster the graph into communities with a community-detection algorithm such as Leiden, keeping the hierarchy of levels.
4. For each community, call the summarizer model with the Community report prompt on its entities and relationships, and store the resulting community report.
5. At query time, shuffle the reports at the chosen level into batches that fit the context window, and call the map model with the Map prompt on each batch in parallel, collecting points with helpfulness scores from 0 to 100.
6. Drop points that scored 0, sort the rest by score, keep as many as fit in one context window, and call the reduce model with the Reduce prompt to write the final answer.

## Prompts

### Entity extraction prompt

```markdown
Extract the entities and relationships in the text below.

Entity types: {{entity_types}}

<text>{{chunk}}</text>

Return JSON:
{"entities": [{"name": "...", "type": "...", "description": "..."}],
 "relationships": [{"source": "...", "target": "...", "description": "...", "strength": 1-10}]}
Use the full, canonical name for each entity, so the same entity in
another chunk can be merged with it.
```

### Community report prompt

```markdown
Write a report on the community of related entities below.

<entities>{{entities}}</entities>
<relationships>{{relationships}}</relationships>

Return a title, a one-paragraph summary of what ties these entities
together, and 3 to 6 key findings, each with the entities it rests on.
```

### Map prompt

```markdown
Answer the question as far as the community reports below allow.

<question>{{question}}</question>
<reports>{{report_batch}}</reports>

Return JSON: {"points": [{"description": "...", "score": 0-100}]}
Score each point by how helpful it is for answering the question.
If the reports are irrelevant, return one point with score 0.
```

### Reduce prompt

```markdown
Write a complete answer to the question from the analysts' points below,
which are sorted from most to least helpful.

<question>{{question}}</question>
<points>{{ranked_points}}</points>

Merge overlapping points, keep the most important themes first, and do
not add anything the points do not support.
```

## Stop rule

Stop after one map round and one reduce call. If every map call returns only zero-scored points, say the corpus does not cover the question.

## Requirements

- Persist the graph, communities and reports, and rebuild only the communities whose chunks changed, since full re-indexing is expensive.
- Make the community level, the map batch size, the maximum number of map calls per query (default 50) and the reduce token budget configurable, so query cost stays bounded at fine community levels.
- Run the map calls concurrently with a per-call timeout; a failed, timed-out or unparseable map reply drops out of the reduce instead of failing the request. If an extraction reply is not valid JSON, retry once, then skip that chunk and log it.
- Keep each point's source community IDs through the reduce, so the answer can cite the communities it drew on.
- Add a test with a stub LLM whose map calls return points scored 80, 0 and 40; assert the reduce prompt holds the 80 and 40 points in that order and not the zero-scored one.

Local search

Implement the GraphRAG pattern (Local search variant) in this codebase, using the LLM client and language we already use.

## Goal

Answer a question about specific entities by matching them in a prebuilt GraphRAG index and answering from the graph neighbourhood, community reports and source chunks around them.

## How it works

1. Embed the question and find the entities whose description embeddings are nearest to it and clear a configurable similarity floor (default top 10, floor 0.5).
2. From the graph, collect each matched entity's neighbours and relationships, the reports of the communities it belongs to, and the text chunks it was extracted from.
3. Rank every candidate item by its link to the matched entities, and fill a fixed context budget in proportions you configure (for example half chunks, a quarter relationships, a quarter community reports).
4. Call the answer model with the Local search answer prompt, passing the question and the assembled context, and return its answer.

## Prompts

### Local search answer prompt

```markdown
Answer the question using the knowledge-graph context below.

<question>{{question}}</question>
<entities>{{entities}}</entities>
<relationships>{{relationships}}</relationships>
<community_reports>{{reports}}</community_reports>
<source_chunks>{{chunks}}</source_chunks>

Prefer the source chunks for specific facts and the reports for the
bigger picture. Cite the entity or chunk ID after each claim.
```

## Stop rule

Stop after one context build and one generation. If no entity clears the similarity floor, say the index has nothing on the question.

## Requirements

- Reuse the global-search index: the same graph, communities, reports and chunk links.
- Make the matched-entity count, the context budget and the per-type proportions configurable.
- Truncate by rank, never mid-item, when the context budget is reached.
- Log the matched entities and every item placed in the context, with its type and source.
- Add a test with a small fixed graph and a stub LLM; assert that a question naming 'FTC' places the FTC entity, its neighbour 'Digital Markets Act' and the chunk it was extracted from in the context, and nothing from an unconnected community.