# Use-Case-First AI Readiness Gate (FastAPI)

## PURPOSE
This service encodes the central advice from Halliburton's SVP of Technology, Sriram Srinivasan: "Don't start with AI. Start first instead with use cases you want to see improved outcomes from." It provides a REST API where teams register a proposed use case and answer a short readiness questionnaire. The API returns a deterministic readiness score and a clear verdict: is the data house in order, is the domain context correct, and can AI materially improve the outcome? Only if all three hold is an AI adoption approved.

## WHY THIS MATTERS
The transcript describes the classic failure mode: teams "dive in deep with AI at the beginning and then stall because your data isn't ready" and "your domain context isn't quite correct." The advice is to get your data house in order, get your domain context in order, and only then think about AI at scale. This project turns that advice into executable governance — a gate that scores use cases before any agent is built, exactly the discipline that let Halliburton eventually ship an internal agent after eight months of groundwork.

## HOW TO BUILD
1. Define Pydantic models for a `UseCase` submission (data readiness, domain context, measurable outcome, AI leverage).
2. Implement a pure scoring function so the logic is testable and explainable.
3. Expose `POST /usecases/score` and `GET /usecases/{id}`.
4. Persist submissions in an in-memory dict (swap for PostgreSQL later).
5. Add `/health` and OpenAPI docs for free via FastAPI.

Key snippet from `starter/main.py`:
```python
def score_readiness(uc: UseCase) -> ReadinessResult:
    data = uc.data_readiness        # 0.0 - 1.0
    context = uc.domain_context     # 0.0 - 1.0
    leverage = uc.ai_leverage       # 0.0 - 1.0
    score = 0.4 * data + 0.4 * context + 0.2 * leverage
    verdict = "APPROVE" if score >= 0.7 else "STALL RISK"
    return ReadinessResult(score=round(score, 2), verdict=verdict)
```
The weighted formula intentionally makes data and domain context dominate — mirroring the transcript's emphasis that "domain context is everything."

## WHEN TO USE IN PRODUCTION
Use it as an intake gate in an enterprise AI program office, an internal developer portal, or a Databricks/Lakehouse governance workflow where every new AI request must justify its data and context foundations. Do NOT use it as a substitute for real data-quality profiling or as a hard blocker for small, reversible experiments — the gate is advisory, not a kill switch.

## HOW IT HELPS STUDENTS
Students learn Pydantic modeling, dependency-free business logic, FastAPI routing, and — most importantly — how to translate a leadership opinion into a testable, versioned service. That translation skill is exactly what production engineering rewards.

## STARTER CODE
See `starter/main.py` for a runnable FastAPI skeleton with deterministic scoring (no LLM/API calls) and `# TODO` markers for persistence and auth.
