# Domain-Context Ontology Registry Service (SQLAlchemy + httpx)

## PURPOSE
The transcript's strongest technical claim is that "domain context is everything" and that tools like Genie plus an ontology raise confidence in answers because all the relevant data and context are available together. This project builds the substrate for that: a registry service where oilfield domain terms (hydraulic fracturing, non-productive time, stage, perforation) are stored, versioned, and linked to physical data assets. It exposes the ontology through SQLAlchemy models and uses an httpx client to send a natural-language question to a Genie-style query endpoint, returning grounded answers or an explicit "insufficient context" response.

## WHY THIS MATTERS
Halliburton built its own internal agent and it took eight months; Genie + ontology made the capability available out of the box. The lesson is that the durable asset is not the model but the curated domain context around it. A registry that records what a term means, which dataset holds it, and who owns it is what lets an agent answer with high confidence instead of hallucinating. This project teaches that data-modeling discipline.

## HOW TO BUILD
1. Define SQLAlchemy models: `Term`, `Dataset`, and a `TermDataset` association table (many-to-many).
2. Use a SQLite engine for local development, with `Base.metadata.create_all`.
3. Seed a handful of real oilfield terms with definitions and owning divisions.
4. Build an httpx client that POSTs a question plus matched ontology terms to a `/genie/query` endpoint.
5. Return answers only when context coverage is above a threshold.

Key snippet from `starter/main.py`:
```python
def resolve_context(session, question: str) -> list[Term]:
    hits = session.query(Term).filter(
        Term.name.in_(tokens_matching(session, question))
    ).all()
    return hits

def ask_genie(question: str, terms: list[Term]) -> dict:
    payload = {"question": question,
               "context": [{"term": t.name, "definition": t.definition} for t in terms]}
    resp = client.post("/genie/query", json=payload)
    resp.raise_for_status()
    return resp.json()
```

## WHEN TO USE IN PRODUCTION
Use it as a semantic layer behind a text-to-SQL or RAG agent, for governing metric definitions across divisions, or to attach business meaning to lakehouse tables. Do NOT use it as the query engine itself or as a replacement for a real ontology tool when you need reasoning and inference — this is a lightweight registry.

## HOW IT HELPS STUDENTS
Students learn relational modeling with SQLAlchemy, the association-table pattern, and how to call an external service with httpx using timeouts and error handling. They also learn why context, not the model, drives answer confidence.

## STARTER CODE
See `starter/main.py` — SQLAlchemy models with a seeded registry, a pluggable Genie client with a deterministic local stub, and `# TODO` markers for LLM term matching and migrations.
