Global Supervisor¶
The Global Supervisor is the central orchestration graph of the Swisper platform. Every user message — whether from web or voice — enters through this module. It coordinates the entire conversation flow: classifying intent, loading memory, planning which domain agents to invoke, executing those agents, and assembling the final response.
The supervisor is implemented as a LangGraph state machine with a shared GlobalSupervisorState that all nodes read from and write to. This state-based design enables deterministic flow control, easy debugging (inspect state at any node), and native support for human-in-the-loop interrupts.
Key Components¶
| Component | Purpose |
|---|---|
| Session Init | Loads chat history and initializes token tracking for the current turn |
| Intent Classification | Classifies user intent as simple or complex chat and sets optimization flags for downstream node skipping |
| Memory Pipeline | Retrieves relevant facts via semantic search, temporal retrieval, and entity resolution |
| Fact Extraction & Merge | Extracts new facts from the user's message and links them to resolved entities |
| Disambiguation | Asks the user to clarify ambiguous entity references (blocking or non-blocking) |
| Global Planner | Creates multi-step execution plans determining which domain agents to invoke |
| Agent Execution | Executes domain agents (Productivity, Wealth, Research, etc.) and collects results |
| UI Response Nodes | Generates simple, complex, or HITL responses with streaming support |
| Message Persist | Persists messages and conversation metadata to the database |
Documentation Sections¶
- Overview — What this module does and who it serves
- Architecture — System design, components, and trade-offs
- Operations — Deployment, monitoring, and runbooks