Skip to main content

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.

Process Overview

  1. Merge - one model call aligns each summary paragraph with the workspace’s existing topics and records an appearance. See Topic History.
  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.