# Unity Catalog Agent Registry Service (SQLAlchemy + httpx)

## PURPOSE
Step four of the Agent Bricks demo registers the agent to Unity Catalog as
"one governed version artifact, which is a single source of truth for what's
deployed." This project is a small registry service that stores agent versions
in a database and calls the deployed agent's real-time endpoint over HTTP. It
mirrors the lifecycle's register and deploy stages with a persistent, queryable
back office.

## WHY THIS MATTERS
The transcript frames governance as the reason the agent-as-code pattern
matters: keeping the agent in code makes it "reviewable, versionable, and
deployable later." A registry makes versioning real — every registered version
has an id, a git commit, the metric scores it earned at evaluation, and a
promotion state. When someone asks "what is actually serving traffic?", the
registry answers with one row instead of a screenshot.

## HOW TO BUILD
1. Define SQLAlchemy models: `AgentVersion` (version, agent_file, git_commit,
   status, created_at) and `EvalScore` (agent_version_id, metric, value).
2. Expose functions to register a new version and to promote one from
   `candidate` to `serving` — promoting demotes the previous serving row.
3. Use `httpx` to call the deployed model-serving endpoint (`/invocations`)
   and record latency.
4. Wrap it all behind a tiny FastAPI app or call the functions directly.

Key snippet — promoting a version atomically:

```python
def promote(session, version: int) -> AgentVersion:
    session.query(AgentVersion).filter_by(status="serving").update(
        {"status": "retired"})
    target = session.query(AgentVersion).filter_by(version=version).one()
    target.status = "serving"
    session.commit()
    return target
```

## WHEN TO USE IN PRODUCTION
Use it as the governance layer behind a deployed agent: a CI job registers a
candidate, an evaluator attaches MLflow scores, a human promotes it, and the
review app links back to the registry. Do NOT use it as the LLM gateway itself —
serving stays on Databricks endpoints; the registry only tracks *which* version
those endpoints should point at. Skip it for single-developer prototypes.

## HOW IT HELPS STUDENTS
Students learn to model versioned state with SQLAlchemy, to reason about
"single source of truth" invariants (exactly one serving version), and to make
authenticated HTTP calls to a model endpoint with httpx. They connect the
video's registration step to real database design and deployment discipline.

## STARTER CODE
See `starter/main.py` for an in-memory SQLite registry, a deterministic
endpoint stub for httpx, and `# TODO` markers for auth headers and Alembic.
