# Trusted Answers Gateway API (Genie-style, citation-first)

## PURPOSE
Build a FastAPI service that answers broad business questions the way Databricks Genie 1 does in the demo: instead of returning a bare number, it returns an answer *with its sources*. The demo asks "how did our vaccines business do in Q3?" and Genie narrows scope, pulls nine ontology snippets, queries Genie agents and tables, then surfaces the root cause (site readiness, oral-to-injectable conversion, authorization delays) **alongside the snippets and queries that justify it**. This project reproduces that citation-first contract as a small, testable HTTP API.

## WHY THIS MATTERS
The core message of the video is trust: "get a bit more confident in your answers." Genie reasons across the whole data ecosystem *and* organizational knowledge, then grounds every answer in inferred ontology snippets. A student who internalizes that answers need provenance — not just SQL — has learned the single most important lesson of trusted analytics.

## HOW TO BUILD
1. Create a virtualenv and `pip install -r requirements.txt`.
2. Define a `Snippet` model (id, domain, text, confidence) and a `QueryTrace` model (sql, rows, engine) with Pydantic.
3. Load a deterministic healthcare dataset (markets: Spain, Germany, US; products: injectables vs orals; a `q3` quarter column).
4. Implement `POST /ask`: tokenize the question, match domains/ontology snippets, run an aggregation over Pandas, and return `answer`, `confidence`, `citations`, and `trace`.
5. Keep the "reasoning" deterministic (keyword/domain routing). Where a real Genie LLM call would sit, leave a stub.

```python
@app.post("/ask", response_model=AnswerResponse)
def ask(req: AskRequest) -> AnswerResponse:
    plan = planner.plan(req.question)          # deterministic scope narrowing
    snippets = ontology.retrieve(plan.domains)  # citation candidates
    result = analytics.run(plan)                # pandas aggregation -> DataFrame
    return AnswerResponse(answer=result.summary,
                          confidence=result.confidence,
                          citations=snippets,
                          trace=result.trace)
```

## WHEN TO USE IN PRODUCTION
Use it as a governed semantic layer in front of dashboards and chat when different teams must trust the same number, when you need audit trails ("why did the system say Spain is down?"), or when an LLM front-end needs a stable, typed backend to call. Don't use it for raw streaming analytics, sub-second high-QPS serving, or when a single well-defined metric can just be a fixed dashboard — the citation machinery is overhead there.

## HOW IT HELPS STUDENTS
They practise API design, Pydantic contracts, and separating *retrieval* from *computation* from *presentation* — the exact layering Genie implies. They learn to model provenance and confidence, and to keep an LLM behind a clean, deterministic interface so tests stay green.

## STARTER CODE
See `starter/main.py` for a runnable FastAPI skeleton with a deterministic planner, an in-memory ontology, a Pandas analytics stub, and `# TODO` markers where real MCP/Genie calls belong.
