# Pi Durable Gateway API

## PURPOSE
A FastAPI service that acts as the always-on gateway described in the video: inputs
arrive from Slack, email, or Telegram, and the service turns each one into a durable
**task submission**. Submissions return a `submission_id`, are persisted to SQLite
storage, and are executed against a Pi Durable-style harness that can resume after a
crash. The gateway itself never runs the agent loop inline; it hands work to a harness
and tracks checkpoint state.

## WHY THIS MATTERS
The video's core point is that Pi Durable ships a `harness` class, not an application.
You are expected to build your own app around it — a gateway that accepts requests and
holds conversations, while the durable harness survives interruptions and continues
"exactly at the point where it left off." This project teaches the six-step lifecycle
the speaker walks through: configure models, open a registry, set up storage, open the
harness, create/retrieve a conversation, then submit queries and await or stream.

## HOW TO BUILD
1. Define Pydantic models for `Submission`, `Checkpoint`, and `ConversationConfig`.
2. Create a SQLAlchemy/SQLite `durable.db` mirroring Durable's storage contract.
3. Wrap a `DurableHarness` client: `submit(task) -> submission_id`, `status(id)`,
   `stream(id)` for Server-Sent Events.
4. Expose `POST /conversations`, `POST /conversations/{id}/submissions`,
   `GET /submissions/{id}`, and `GET /submissions/{id}/events`.
5. Substitute a deterministic stub for the real model call.

```python
@app.post("/conversations/{cid}/submissions")
async def submit(cid: str, body: SubmissionIn):
    submission = harness.submit(cid, body.prompt)  # writes checkpoint row
    return {"submission_id": submission.id, "status": submission.status}
```

## WHEN TO USE IN PRODUCTION
Use it for always-on assistants whose front doors are chat or email, where you are not
in front of the screen when a long task runs. Also fits job queues where submissions
run for hours or days. Do NOT use it for a purely interactive terminal coding agent —
that is the plain Pi Harness/Pi Coding Agent case. Do not put a full conversation API
here either: the video warns Durable's API is early and not a complete chat API.

## HOW IT HELPS STUDENTS
Students practice async FastAPI, request/response contracts, SSE streaming, and the
distinction between an agent *application* and the *harness primitive* beneath it. They
learn idempotent task submission and why a submission ID matters for status polling —
directly transferable to building reliable background agents.

## STARTER CODE
See `starter/main.py` for a runnable FastAPI skeleton with an in-memory harness stub,
TODO markers where SQLite persistence and the real model adapter belong, and the SSE
endpoint wired up.
