Topic Graph Process Flow
Flow of thetopic_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.
Process Overview
- Merge - one model call aligns each summary paragraph with the workspace’s existing topics and records an appearance. See Topic History.
- Link proposals - topics that share enough entities with another opted-in workspace in the organisation get a proposed
corresponds_torelation, for a person to accept or reject. - Projection - the workspace’s topics, sessions, entities and themes are rebuilt in Neo4j (
rag.neo4j_v2). Skipped when that key is not set. - Follow-ups - strand enrichment runs when enabled, then a
pattern_synthesisjob 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-graphshows the session’s topics as the graph holds them.