# LeadPilot — AI Lead Qualification Architecture

**Document Version:** 1.0.0 (Phase 8 AI Qualification Lock)  
**Status:** Implemented, Tested & Verified (114 Automated Assertions)  
**Positioning:** AI-powered lead qualification and decision support.  
**Provider Boundary:** Agnostic adapter layer with 8s timeout and heuristic fallback.  

---

## 1. Provider & Service Topology

```
[ Inbound Lead / Re-analysis Request ]
                │
                ▼
[ LeadQualificationService ] ── (Builds Sanitized LeadInquiryDTO)
                │
                ▼
[ AiManager (Orchestrator) ]
         │
         ├──► [ Primary: OpenAiProvider (gpt-4o-mini) ] ── (8s Timeout, Strict JSON Schema)
         │           │
         │           └───► (On Timeout / 429 / Failure)
         │                       │
         └──► [ Fallback: HeuristicFallbackScorer ] ───── (Deterministic Keyword Rules)
                                 │
                                 ▼
              [ AiQualificationSchemaValidator ] ──────── (0-100 Bounding, HOT/WARM/COLD)
                                 │
                                 ▼
                     [ Transactional Persistence ]
                     ├── `ai_scores` (Historical assessment record)
                     ├── `ai_usage_logs` (Token metrics & execution ms)
                     ├── `leads` (`ai_score`, `temperature`, `ai_status`)
                     └── `lead_activities` (`ai_scored` timeline event)
```