> ## 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.

# HiRAG Indexing Process

> How transcripts are indexed into the knowledge graph after a session completes.

# HiRAG Indexing Process Flow

Mermaid flowchart of the `process_indexing_job` function from `crates/hirag-worker/src/main.rs:107-209`.

```mermaid theme={null}
flowchart TD
    Start([Start: process_indexing_job]) --> UpdateStatus1[Update job status: 'processing']
    UpdateStatus1 --> LogStart[Log: Starting indexing]
    LogStart --> FetchText[Fetch source text from DB<br/>session_id, transcription_id, summarisation_id]
    FetchText --> CheckEmpty{Source text<br/>empty?}
    CheckEmpty -->|Yes| Error1[Error: No source text found]
    CheckEmpty -->|No| LogTextLength[Log: Extracted N characters]

    LogTextLength --> Phase1[Phase 1: Extract Entities]
    Phase1 --> CreateEntityExtractor[Create EntityExtractor]
    CreateEntityExtractor --> ExtractEntities[Extract and store entities]
    ExtractEntities --> LogEntityCount[Log: Extracted N entities]

    LogEntityCount --> CheckEntities{Entities<br/>< 2?}
    CheckEntities -->|Yes| EarlyComplete[Log: Not enough entities<br/>Update status: 'completed'<br/>Return early]
    CheckEntities -->|No| Phase2[Phase 2: Extract Relations]

    Phase2 --> CreateRelationExtractor[Create RelationExtractor]
    CreateRelationExtractor --> ExtractRelations[Extract relations from text & entities]
    ExtractRelations --> LogRelationCount[Log: Extracted N relations]
    LogRelationCount --> StoreRelations[Store relations to DB<br/>RelationType: Horizontal]

    StoreRelations --> Phase3[Phase 3: Build Hierarchical Layers]
    Phase3 --> CreateLayerBuilder[Create HierarchicalLayerBuilder]
    CreateLayerBuilder --> BuildLayers[Build layers for session]
    BuildLayers --> CheckLayersSuccess{Build<br/>successful?}
    CheckLayersSuccess -->|Error| LogLayerError[Log error chain<br/>Return error]
    CheckLayersSuccess -->|Success| LogLayerCount[Log: Built N layers]
    LogLayerCount --> UpdateLayerInfo[Update job layer info in DB]

    UpdateLayerInfo --> Phase4[Phase 4: Detect Communities]
    Phase4 --> CreateCommunityBuilder[Create CommunityBuilder]
    CreateCommunityBuilder --> BuildCommunities[Build communities for session]
    BuildCommunities --> LogCommunityCount[Log: Detected N communities]

    LogCommunityCount --> UpdateStatus2[Update job status: 'completed']
    UpdateStatus2 --> LogCompletion[Log: ✓ Indexing completed<br/>Summary: entities, relations, layers, communities]
    LogCompletion --> End([End: Return Ok])

    EarlyComplete --> End
    Error1 --> EndError([End: Return Error])
    LogLayerError --> EndError

    style Phase1 fill:#e1f5ff
    style Phase2 fill:#e1f5ff
    style Phase3 fill:#e1f5ff
    style Phase4 fill:#e1f5ff
    style CheckEmpty fill:#fff4e6
    style CheckEntities fill:#fff4e6
    style CheckLayersSuccess fill:#fff4e6
    style Error1 fill:#ffebee
    style LogLayerError fill:#ffebee
    style EarlyComplete fill:#f3e5f5
    style End fill:#c8e6c9
    style EndError fill:#ffcdd2
```

## Process Overview

The HiRAG indexing process consists of four main phases:

1. **Phase 1: Entity Extraction** - Extracts entities from source text and stores them in the database
2. **Phase 2: Relation Extraction** - Extracts relations between entities and stores them as horizontal relations
3. **Phase 3: Hierarchical Layer Building** - Builds hierarchical layers from the knowledge graph
4. **Phase 4: Community Detection** - Detects communities within the knowledge graph

## Validation Points

* **Source Text Check**: If no source text is found, the process fails with an error
* **Entity Count Check**: If fewer than 2 entities are extracted, the process completes early (insufficient data for knowledge graph)
* **Layer Building**: Errors during layer building are logged and propagated

## Error Handling

* Empty source text results in immediate failure
* Layer building errors are logged with full error chains before returning
* All other phases use context-aware error handling via `anyhow::Context`