# Dot Inbox: Persistent Agent Task API

## PURPOSE
In "Cooking with Codex: Ep. 1" the OpenAI hosts describe **"dot"** as an *always-on persistent agent* that has been "running in the background running interference for us — checking in guests, sending emails, and putting this recipe together." This project builds the backend that makes that claim real: a FastAPI service that holds a durable inbox of long-running background tasks, runs them on a worker loop, and exposes their live status. The same service also exposes a `/voice/session` stream that models the episode's **GPT Live 1** frontier voice model, which is explicitly described as *full duplex* — "when I trail off … it actually doesn't interrupt me."

## WHY THIS MATTERS
The hard part of a persistent agent is not the model call, it is the plumbing: what does the agent do when nobody is watching, how does it report back, and how does it avoid talking over the human. This project teaches state machines for agent tasks, background workers, and turn-taking semantics for streaming sessions.

## HOW TO BUILD
1. `pip install -r requirements.txt` (FastAPI + uvicorn + pydantic).
2. Define a `Task` and `Turn` Pydantic model with explicit status values (`queued / running / done / failed`).
3. Store tasks in a dict-backed `Inbox`; every mutation stamps `updated_at`.
4. Register REST routes: `POST /tasks`, `GET /tasks`, `GET /tasks/{id}`, `POST /tasks/{id}/run`, plus `GET /voice/session` (server-sent events).
5. Replace the stub executor with a real agent call.

Key snippet — the executor seam:

```python
async def execute(task: Task) -> str:
    """Deterministic stub for the real dot tool-call. # TODO: swap for LLM/tool call."""
    if task.kind == "email":
        return f"[stub] emailed {task.payload.get('to')} re: {task.payload.get('subject')}"
    if task.kind == "guest_checkin":
        return f"[stub] checked in guest {task.payload.get('name')}"
    return "[stub] no-op"
```

## WHEN TO USE IN PRODUCTION
Use it when an assistant must keep acting between user sessions: drafting emails, watching an inbox, prepping assets before a meeting. Also a good fit for any app that needs an SSE status channel. **Do not** use an in-memory inbox for anything that must survive a deploy — that needs a real queue and a database. Do not use a single-worker loop for high task volume; move to Celery/Arq.

## HOW IT HELPS STUDENTS
Students practise async FastAPI, background tasks, Pydantic validation, SSE streaming, and the discipline of isolating the non-deterministic model call behind one stub function. It is a realistic first "agent backend", not a toy chat endpoint.

## STARTER CODE
See `starter/main.py` for the runnable skeleton (in-memory inbox, three task kinds, stub executor, SSE endpoint, and `# TODO` markers for the real dot call and persistence).
