HITL System¶
The HITL (Human-in-the-Loop) System is Swisper's centralized mechanism for pausing conversations to request user input — whether for clarification, confirmation of risky actions, or entity disambiguation. It uses LangGraph's native interrupt() and Command(resume=...) for deterministic pause/resume with Redis-backed state persistence.
The system ensures that domain agents never talk directly to users. Instead, all user-facing questions flow through a centralized handler that provides consistent formatting, channel-agnostic delivery, and complete state preservation across arbitrarily long pauses.
Key Components¶
| Component | Purpose |
|---|---|
| HITL Handler Node | Central orchestrator — calls interrupt(), processes user responses, detects escape attempts |
| Disambiguation Blocking Node | Generates entity clarification questions when ambiguity blocks the answer |
| Disambiguation Resolution Node | Resolves user's entity choice via fast-path matching or LLM semantic analysis |
| Create New Entity Node | Handles "Someone else" flow — creates new Person records from user's description |
| HITL Text Node | Formats and streams HITL questions to the frontend (bypasses LLM) |
Documentation Sections¶
- Overview — What this module does and who it serves
- Architecture — System design, components, and trade-offs