# Decision Engine (DE)

## Purpose

The Decision Engine is the future unified intelligence infrastructure layer for M4WD and future PCP modules.

It will:

- Accept structured Decision Context Objects
- Apply deterministic authority rules
- Apply advisory confidence ceilings
- Route to LLM only when policy allows
- Enforce cost governance
- Emit structured, auditable decision output
- Standardize logging across all AI calls

The DE is not being implemented yet.
This folder defines the architectural direction and logging standards required before formalization.

---

## Strategic Context

M4WD currently contains:

- Deterministic fitment authority logic
- Advisory LLM fallback with confidence ceilings
- Model resolution abstraction
- Token usage logging
- Spend cap enforcement
- Slack real-time alerts + daily digest

The Decision Engine will eventually extract and unify these patterns into a reusable layer.

Otto Chat and Otto Fitment are early production clients of this future engine.

---

## Architectural Intent

The Decision Engine will centralize:

- Authority tiers (deterministic > advisory)
- Confidence band enforcement
- Model routing logic
- Spend caps
- Token logging
- Policy application
- Risk classification
- Audit trace generation

It will NOT initially include heavy ML or fine-tuning.
It is infrastructure-first.

---

## Required Logging (Begin Implementing Now)

All AI-related decisions should log the following fields so they can later be unified under DE:

- `decision_type` (e.g., fitment_check, chat_response, persona_eval)
- `authority_source` (deterministic, advisory, hybrid)
- `deterministic_confidence`
- `llm_confidence` (if present)
- `final_confidence`
- `confidence_band`
- `llm_used` (boolean)
- `model_used`
- `tokens_prompt`
- `tokens_completion`
- `tokens_total`
- `cost_estimate_usd`
- `policy_applied` (string or array)
- `trace_id` (unique per decision)
- `timestamp`

Where possible, also log:

- `outcome_quality_signal` (conversion, abandonment, user escalation)
- `risk_band`
- `environment` (dev vs prod)

These logs will later become the raw telemetry input for DecisionEngine v1.

---

## Extraction Strategy

DecisionEngine v1 will be created after:

- Otto Chat is production stable
- Dashboard is deployed
- Model logging patterns are stable
- Persona data collection is active

At that time, repeated intelligence patterns will be extracted into:

`DecisionEngine::evaluate($decisionContext)`

All modules will call this method instead of local intelligence logic.

---

## Future v1 Interface (Non-Implemented Example)

Example intended usage:

```php
$context = [
  "decision_type" => "fitment_check",
  "entity_id" => 8339516915955,
  "attributes" => [...],
  "risk_profile" => "standard",
  "environment" => "dev"
];

$result = DecisionEngine::evaluate($context);
```

Expected response structure:

```php
[
  "status" => "fits",
  "confidence" => 0.82,
  "confidence_band" => "deterministic",
  "llm_used" => false,
  "model_used" => null,
  "tokens_total" => 0,
  "cost_estimate_usd" => 0,
  "policy_applied" => [...],
  "trace_id" => "uuid"
]
```

---

## Philosophy

The Decision Engine is the applied AI infrastructure layer for M4WD.

It is not a feature.
It is the operating system for intelligence decisions.

It will emerge from production patterns, not abstract theory.