Conversational Grounding Architecture¶

Summary¶

The assistant now uses always-on claim-level grounding to reduce hallucinations without forcing turn-level refusals.

Core behavior: - Detect missing evidence for factual claims. - Rewrite only unsupported factual claims. - Preserve conversational flow and persona style. - Keep high-risk responses structured for reliability.

Pipeline¶

Classification + tool plan from router.
Tool execution with execution metadata:
requested tools
executed tools
unsupported tools
failed tools
Evidence ledger construction per turn.
Response generation with:
connected-service context
high-risk structured output
normal persona generation for low/medium risk
Post-generation claim-level rewrite if evidence is missing.
Re-render rewritten bubbles in persona voice.
Emit grounding analytics outcome.

Evidence Ledger¶

The ledger captures: - intent - risk_level - required_evidence - grounded_evidence - missing_evidence - tool execution metadata - rewrite count

This enables deterministic gating on factual claims without blocking natural conversation.

Uncertainty Voice Model¶

Uncertainty fallback is not hardcoded per character.

Instead: - infer style profile from persona passport tone/behavior - generate fallback in that style profile - re-render through persona voice rules for final output

This makes new personas inherit uncertainty behavior from existing passport design automatically.

Design Decisions¶

Always-on grounding in current environment (no A/B gating path).
Conversational fail-close defaults:
conversational uncertainty enabled
strict hard-refusal mode disabled
High-risk intents use structured response schema.

Key Files¶

app/orchestrator/grounding.py
app/orchestrator/message_handler.py
app/orchestrator/response_generator.py
app/orchestrator/tool_executor.py
app/orchestrator/smart_message_router.py

Metrics¶

See implementation plan: - docs/implementation/CONVERSATIONAL_GROUNDING_METRICS_PLAN.md