Global Supervisor — Architecture¶

This content was migrated from Documentation/GLOBAL_SUPERVISOR.md and restructured into audience sections. Review for accuracy against the current codebase.

Context and Purpose¶

The Global Supervisor exists because Swisper needs a single, deterministic orchestration layer that coordinates every aspect of a conversation turn — from intent classification through memory retrieval, agent delegation, and response generation.

The key driving requirements behind its design are:

• Deterministic flow control — Each user message must follow a predictable path through well-defined processing stages, making debugging and auditing possible
• Entity-first disambiguation — Facts must never be stored against the wrong entity. Entity resolution must complete before fact extraction proceeds
• Minimal time-to-first-token — Simple queries should skip expensive processing stages via optimization flags, while complex queries get full pipeline treatment
• State persistence for HITL — When the system needs to ask the user a clarification question (e.g., disambiguation), the entire conversation state must be checkpointed so execution can resume exactly where it left off

Architecture Overview¶

The Global Supervisor is implemented as a LangGraph StateGraph — a directed graph where each node is a processing step and edges define the flow between them. All nodes share a single GlobalSupervisorState (TypedDict) that accumulates data as the message progresses through the pipeline.

The graph is organized into seven logical stages:

flowchart TB
    subgraph Entry["1. Entry & Session"]
        START([User Message]) --> SI[Session Init]
        SI --> SC[Summarization Check]
        SC -->|needs summarization| SUM[Summarization]
        SC -->|no| CL
        SUM --> CL[Context Loader]
    end

    subgraph HITL["2. HITL Resume"]
        CL --> UIL[HITL Handler]
        UIL -->|has interrupt| RESUME{Resume Type}
        UIL -->|no interrupt| IC
        RESUME -->|disambiguation| IC
        RESUME -->|agent HITL| AE
    end

    subgraph Classification["3. Intent Classification"]
        IC[Intent Classification]
    end

    subgraph Memory["4. Memory Pipeline"]
        IC --> RR{Retrieval Router}
        RR -->|skip retrieval| MA
        RR -->|semantic only| ER
        RR -->|parallel retrieval| ER
        ER[Entity Resolution] --> SR[Semantic Retrieval]
        SR --> TR[Temporal Retrieval]
        TR --> MA[Memory Assembly]
        MA --> FE[Fact Extraction]
        FE --> EM[Extraction Merge]
    end

    subgraph Disambiguation["5. Disambiguation"]
        EM --> AMB{Entity Ambiguity?}
        AMB -->|blocking| DB[Disambiguation Blocking]
        AMB -->|non-blocking| DS[Disambiguation Simple]
        AMB -->|none| ROUTE
        DB --> MP
        DS --> MP
    end

    subgraph Planning["6. Planning & Execution"]
        ROUTE{Route}
        ROUTE -->|simple chat| UIR[UI Router]
        ROUTE -->|complex| GP[Global Planner]
        GP --> AE[Agent Execution]
        AE --> GP2{More agents?}
        GP2 -->|yes| GP
        GP2 -->|no| UIR
    end

    subgraph Response["7. Response Generation"]
        UIR --> UINODES{Response Type}
        UINODES -->|simple| ST[Simple Text]
        UINODES -->|complex| CT[Complex Text]
        UINODES -->|hitl| HT[HITL Text]
        ST --> MP[Message Persist]
        CT --> MP
        HT --> MP
    end

    MP --> DONE([End / HITL Interrupt])

Flow summary: A message enters at Session Init, gets classified, passes through memory retrieval and entity resolution, optionally triggers disambiguation, gets routed to either direct response or planner-driven agent execution, and exits through a specialized UI response node.

Component Responsibilities¶

Data Model¶

GlobalSupervisorState¶

The shared state is a Python TypedDict with these key domains:

State Persistence¶

The checkpointer uses chat_id as the thread identifier, enabling resume-from-checkpoint for HITL interrupts and crash recovery.

Key Design Decisions¶

1. Synchronous Entity Resolution Before Fact Storage¶

• Chosen: Entity resolution runs synchronously and blocks fact extraction from persisting until entities are resolved
• Rejected: Parallel entity resolution + fact extraction with post-hoc linking
• Rationale: When a user says "Thomas is traveling to Mallorca" and there are two contacts named Thomas, storing the fact before knowing which Thomas it belongs to leads to orphaned or misattributed data. The 500–1,500ms latency cost is acceptable to guarantee data correctness

2. LangGraph StateGraph Over Custom Orchestration¶

• Chosen: LangGraph StateGraph with conditional edges and built-in checkpointing
• Rejected: Custom async pipeline, event-driven choreography
• Rationale: LangGraph provides deterministic execution, built-in state persistence (checkpointers), native HITL support via interrupt(), and visual debugging. The structured graph makes it straightforward to add, remove, or reorder nodes

3. Optimization Flags for Node Skipping¶

• Chosen: Intent classification sets boolean flags (has_extractable_facts, needs_semantic_retrieval, has_preferences) that downstream routing functions use to skip unnecessary nodes
• Rejected: Running all nodes for every message; lazy evaluation at each node
• Rationale: A greeting like "Hi" doesn't need fact extraction (~9,000 tokens) or semantic retrieval (~500ms). The flags save 2–3 seconds and ~15,000 tokens on simple messages while keeping the graph structure uniform

Interfaces and Contracts¶

Known Trade-offs and Debt¶