Federated from workspace · PRD-001 · Dental Clinic Revenue Operating System/docs/technical/CLINIC_INTENT_UNDERSTANDING_ENGINE.md Do not edit canonical truth here — update the source repo, then re-run npm run docs:sync.

---

Clinic Intent Understanding Engine

Status: Phase 2 implemented (2026-07-05)
Authority: App\Modules\AI\Application\Intent

Purpose

Replace regex-first routing with a dynamic Intent Understanding Engine that produces ranked intents with confidence scores, discourse type, and PL-003 activation signals — before capability matching and tool execution.

Pipeline

User message + conversation history + last turn context
    ↓
ClinicConversationBehaviorEngine (social behaviors — no runtime)
    ↓
ClinicConversationContinuationResolver (discourse context)
    ↓
ClinicIntentLlmAnalyzer (structured JSON — Groq/fast model)
    ↓ (fallback)
ClinicIntentRegexFallbackAnalyzer (legacy classifier — offline/tests only)
    ↓
ClinicIntentSignalMapper → PL-003 signals
    ↓
Confidence gate → Clarification | Guidance | Orchestrator
    ↓
AgentTurnOrchestrator (CapabilityMatcher → Planning → Execution)

Components

Component	Role
ClinicIntentUnderstandingEngine	Primary entry — merges LLM + fallback, emits signals
ClinicIntentLlmAnalyzer	LLM structured JSON intent ranking (multilingual)
ClinicIntentRegexFallbackAnalyzer	Deterministic fallback when LLM unavailable
ClinicConversationContinuationResolver	Continuation / "explain more" without phrase lists
ClinicIntentSignalMapper	Semantic intent → PL-003 activation signals
ClinicIntentClarificationBuilder	Ambiguous intent disambiguation UI
ClinicIntentCatalog	Intent taxonomy for LLM prompt (not regex matching)

Confidence thresholds

Configured in config/ai.php → copilot.intent_engine:

Setting	Default	Behavior
confidence_execute	0.72	High confidence — route to guidance or orchestrator
confidence_clarify	0.55	Below this — ask user to clarify
runner_up_gap	0.12	Top two intents within gap — disambiguation

Configuration

CLINIC_INTENT_ENGINE_ENABLED=true
CLINIC_INTENT_USE_LLM=true
CLINIC_INTENT_PROVIDER=groq
CLINIC_INTENT_MODEL=llama-3.1-8b-instant
CLINIC_INTENT_CONFIDENCE_EXECUTE=0.72
CLINIC_INTENT_CONFIDENCE_CLARIFY=0.55
CLINIC_INTENT_RUNNER_UP_GAP=0.12

Set CLINIC_INTENT_USE_LLM=false in tests or when offline — regex fallback handles routing.

Semantic intents

ClinicSemanticIntent enum maps to capabilities via signals:

• query_appointments_today → clinic.operations.query_appointments
• query_leads_today → clinic.leads.query_today
• query_unpaid → clinic.finance.query_unpaid
• greeting, help, instruction, navigation → guidance path (no tools)

Follow-up / continuation

Discourse type continuation resolves against last turn context (intent, capability, messages) — not a growing phrase list. The engine restates the prior operational question when the user says "Explain more", "Tell me more", "Go on", etc.

Architecture compliance

• Additive — regex catalog remains as fallback only
• PL-003 unchanged — engine emits metadata.signals for CapabilityMatcher
• No business logic in UI — clarification built in Application layer
• DTO-first — ClinicIntentUnderstandingResult persisted in conversation metadata

Tests

php artisan test app/Modules/AI/Tests/Unit/ClinicIntentUnderstandingEngineTest.php
php artisan test app/Modules/AI/Tests/Unit/ClinicConversationBehaviorEngineTest.php
php artisan test app/Modules/AI/Tests/Unit/ClinicCapabilityCoverageTest.php
php artisan test tests/Feature/ClinicAgentIntentAcceptanceTest.php