# AI Architecture — Provider Adapters

**Document Version:** 1.0.0 (Phase 12)

---

## 1. Provider Contract

All AI providers implement `App\Domains\AI\Contracts\AiProviderContract`:

```php
interface AiProviderContract
{
    public function qualifyLead(LeadInquiryDTO $inquiry): AiQualificationDTO;
    public function getProviderName(): string;
    public function isAvailable(): bool;
}
```

---

## 2. Available Adapters

### 1. OpenAI Adapter (`OpenAiProvider`)
- **Default Model:** `gpt-4o-mini` (configurable to `gpt-4o`)
- **Mode:** Structured JSON format (`response_format: { type: "json_object" }`)
- **Timeout:** 8 seconds bounded execution
- **Temperature:** `0.2` for deterministic scoring

### 2. Mock / Heuristic Adapter (`MockAiProvider`)
- Uses deterministic keyword evaluation and regular expressions for test suites and offline environments.

### 3. Heuristic Fallback Scorer (`HeuristicFallbackScorer`)
- Triggered automatically whenever an external provider request fails, times out, or throws a runtime exception.
- Ensures zero operational downtime during lead ingestion.