Entity Disambiguation¶
Entity Disambiguation resolves ambiguous mentions of people in conversation. When a user says "Thomas" and the system knows multiple Thomases, this module determines which one the user means — or whether the system needs to ask. It uses relevance-aware routing to decide whether to ask before answering (blocking) or answer first and ask casually afterward (non-blocking), avoiding unnecessary interruptions while ensuring personalized responses reference the right person.
Key Components¶
| Component | Purpose |
|---|---|
| Entity Resolution Node | Matches entity mentions against stored contacts using hybrid search (exact + embedding), umlaut normalization, and LLM context analysis with reranker-based fact enrichment |
| EntityResolutionService | Enrichment cascade for contact info: Person DB → Contact table → External providers (Google/MS) → HITL. Enriches Person records so the system never asks the same question twice |
| Relevance Classifier | Determines whether an ambiguous entity is blocking (must ask first) or non-blocking (answer first, ask later) |
| Disambiguation UI Nodes | Three flow variants: blocking ask-only, non-blocking simple (BTW), non-blocking complex (BTW) — each with clickable options |
| HITL Answer Classifier | Three-tier interpretation: Tier 1 structured action (pill click), Tier 2 text match, Tier 3 LLM classification — detects corrections, context switches, escapes |
| Disambiguation Resolution | Processes user's selection via fast-path classifier (action markers, exact match) with LLM fallback |
| Singleton Role Conflict Detection | Detects when a new person conflicts with an existing singleton role (e.g., second urologist) and asks whether to replace or add |
| Sequential Multi-Entity Handler | Resolves multiple ambiguous entities one at a time across sequential turns |
Documentation Sections¶
- Overview — What this module does and who it serves
- Architecture — System design, components, and trade-offs