# Voice Assistant Tool-Calling Service

## PURPOSE
Give a voice agent persistent side-effecting tools. In the video the assistant checks "do we have an appointment with Bärbel in the calendar the day before departure?", researches whether Marek Wischnewski is still at the university in Szczecin, and translates a Polish greeting — all mid-conversation. This project is the service that backs those calls: a calendar store, a research lookup, and a translation memo, each written to SQLite through SQLAlchemy, with outbound HTTP handled by httpx.

## WHY THIS MATTERS
Real-time research and live translation mean the model reaches outside itself during speech. That requires an integration layer that is fast, idempotent and auditable. The transcript's audio never mentions databases, but the behaviour it shows (calendar recall, fresh web facts, remembered Polish practice) is only possible if a durable tool service exists underneath.

## HOW TO BUILD
1. Define `CalendarEvent`, `ResearchQuery` and `TranslationMemo` models with `SQLAlchemy` and create the schema at startup.
2. Wrap each capability in a small function that the voice agent can call by name.
3. Use `httpx.Client` for the research call, with a deterministic offline fallback when the network is unavailable.
4. Persist every call so a later turn can recall it ("you've been practicing since January").
Key snippet:

```python
def research(conn, http, query: str, offline: bool = False) -> str:
    result = stub_lookup(query) if offline else http.get(SEARCH_URL, params={"q": query}).json()
    conn.add(ResearchQuery(query=query, summary=result["summary"]))
    conn.commit()
    return result["summary"]
```

## WHEN TO USE IN PRODUCTION
Use it whenever an assistant must read or write state the user cares about: scheduling, CRM notes, translation glossaries, inventory. Keep it idempotent so a barge-in retry does not double-book. Do NOT use it for pure chat or stateless Q&A — a database adds latency and operational surface with no benefit there.

## HOW IT HELPS STUDENTS
They practise ORM modelling, connection/session lifecycle, HTTP client usage with timeouts, and designing tool functions with predictable return shapes for an agent to consume.

## STARTER CODE
`starter/main.py` builds the SQLAlchemy engine and schema, implements `check_calendar`, `research` and `save_translation`, and runs a tiny demo flow. Network calls are stubbed behind `# TODO`.
