# Voice Action Broker — Tool-Calling Service for Transit & Bookings

## PURPOSE
Midway through the demo, the assistant stops chatting and *acts*: it checks "are
there any disruptions on line 8?", confirms "no disruptions on line 8", and books
"hairdresser appointment set for 5:00 PM". A voice model that can only talk is a
demo; a voice model that can execute a call is a product. This project is the backend
those actions hit: a FastAPI service with bearer-token auth, SQLAlchemy models for
appointments, and an httpx client that queries a (stubbed) transit feed for Metro
line 8 disruptions.

## WHY THIS MATTERS
The video's turning point is the shift from conversation to tool use. That shift
requires a real service layer: idempotent booking endpoints, external-API calls with
timeouts and error handling, and auditable records. This project teaches the
integration pattern behind every "the assistant booked my slot" feature.

## HOW TO BUILD
1. `pip install -r requirements.txt` (FastAPI, Uvicorn, SQLAlchemy, httpx, Pydantic).
2. Declare an `Appointment` model (`id`, `service`, `slot`, `created_at`) on a SQLite
   engine and create the table at startup.
3. Add `GET /transit/line-8/disruptions` that calls `httpx.AsyncClient` against a
   configurable base URL, with a deterministic stub fallback when the feed is offline.
4. Add `POST /appointments` behind a `Depends(require_token)` bearer check.

Key snippet (from `starter/main.py`):
```python
@app.post("/appointments", status_code=201)
async def book(payload: Booking, token: str = Depends(require_token),
               db: Session = Depends(get_db)):
    row = Appointment(service=payload.service, slot=payload.slot)
    db.add(row); db.commit(); db.refresh(row)
    return {"id": row.id, "slot": row.slot}

@app.get("/transit/line-8/disruptions")
async def disruptions():
    return await fetch_line8_disruptions()   # httpx -> stub fallback
```

## WHEN TO USE IN PRODUCTION
Use it as the action layer behind a voice assistant, an IVR, or a chat front end —
anywhere a model needs to book real slots or read live service status. Do NOT expose
it directly to a browser without hardening: the demo token check must become real
OAuth/JWT, the transit call needs retries and circuit breaking, and the SQLite file
must become a managed database.

## HOW IT HELPS STUDENTS
Students connect three production primitives — async HTTP clients, relational
persistence, and auth dependencies — and learn to design endpoints that a language
model can call safely and idempotently.

## STARTER CODE

`starter/main.py` is a FastAPI + SQLAlchemy service exposing the tool-calling broker:

- `Base` / `Appointment` — declarative base and the persisted booking model.
- `Booking` (Pydantic) — the request schema the model is allowed to emit.
- `require_token(authorization)` — bearer-token dependency guarding every route.
- `GET /health`, `GET /transit/line-8/disruptions`, `POST /appointments`,
  `GET /appointments` — the tool surface an assistant can call.

Run it:

```bash
pip install -r requirements.txt
uvicorn starter.main:app --reload
```

The `# TODO` markers cover moving SQLite to a managed database and making the booking
endpoint idempotent under retries.
