> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kair.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Topic Graph Process

> How a completed session summary becomes workspace topics, cross-workspace links and the Neo4j topic graph.

# Topic Graph Process Flow

Flow of the `topic_graph` job, handled by `handle_topic_graph_delivery` in `crates/rag-worker/src/topic_graph_job.rs`. The summarisation worker queues it on `kair.topic_graph` after a session summary completes.

```mermaid theme={null}
flowchart TD
    Start([Delivery on kair.topic_graph]) --> Claim{Claim job}
    Claim -->|Missing, terminal or held by another| Skip([Ack and discard])
    Claim -->|Claimed| Processing[Job status: processing]

    Processing --> Erased{Session erased?}
    Erased -->|Yes| Done
    Erased -->|No| Paragraphs{Session has summary<br/>paragraphs?}
    Paragraphs -->|No| Done

    Paragraphs -->|Yes| Merge[Merge paragraphs into<br/>workspace topics]
    Merge --> Org{Workspace has<br/>an organisation?}
    Org -->|No| Done
    Org -->|Yes| Links[Propose cross-workspace<br/>topic links<br/>failure logged, non-fatal]
    Links --> Neo{rag.neo4j_v2<br/>configured?}
    Neo -->|Yes| Project[Project workspace into<br/>the Neo4j topic graph]
    Neo -->|No| Done
    Project --> Done[Job status: completed]

    Done --> Follow[Strand enrichment<br/>best effort]
    Follow --> Pattern[Queue pattern_synthesis<br/>best effort]
    Pattern --> End([End])

    Merge -->|Error| Retry{Transient and<br/>attempts left?}
    Project -->|Error| Retry
    Retry -->|Yes| Backoff[Interrupted, broker retries<br/>after 1, 5 then 15 min]
    Retry -->|No| Failed([Job status: failed])
```

## Process Overview

1. **Merge** - one model call aligns each summary paragraph with the workspace's existing topics and records an appearance. See [Topic History](https://docs.kair.is/platform/topic-history.md).
2. **Link proposals** - topics that share enough entities with another opted-in workspace in the organisation get a proposed `corresponds_to` relation, for a person to accept or reject.
3. **Projection** - the workspace's topics, sessions, entities and themes are rebuilt in Neo4j (`rag.neo4j_v2`). Skipped when that key is not set.
4. **Follow-ups** - strand enrichment runs when enabled, then a `pattern_synthesis` job is queued. Both are best effort and never fail the job. Pattern synthesis takes its entities from the session summary's paragraph entities.

## Validation Points

* **Erased sessions** - nothing is merged, projected or queued.
* **No paragraphs** - sessions summarised before structured summaries have nothing to merge; the job completes.
* **No organisation** - topics belong to an organisation, so the merge is skipped; pattern synthesis is still queued.

## Error Handling

* Transient errors (LLM, embedding or Neo4j outages) retry up to 4 times on the broker's 1, 5 and 15 minute rings; permanent errors fail the job at once.
* A failed projection leaves Postgres untouched; rebuild it with `kair-voice-topic-backfill project`.
* Jobs appear in the admin jobs list with type `topic_graph`; `GET /admin/sessions/{session_id}/topic-graph` shows the session's topics as the graph holds them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.