# Dubbing Job Orchestrator Service

## PURPOSE
When a creator submits one video to Sarvam Content Studio and asks for "all the
languages you want," something has to hold durable state per language, authenticate
the creator, call the dubbing provider, and hand results back — possibly hours
later, to a different process. This project is that integration service: an
SQLAlchemy-backed store of dub jobs with per-language child rows, API-key auth,
an httpx client for the provider, and signed webhook callbacks when each language
finishes. It solves the "review and edit every word" workflow by keeping an auditable
record of every variant.

## WHY THIS MATTERS
The transcript's promise spans multiple minutes and multiple outputs. Durable,
resumable orchestration is what makes a multi-minute promise reliable instead of a
lost job. Students learn that the hard part of an AI feature is rarely the model —
it is the state machine around it.

## HOW TO BUILD
Framework: **SQLAlchemy** + **httpx**. Steps:
1. Define `Creator`, `DubJob`, and `DubOutput(language, status, audio_url)` models.
2. Authenticate requests with an `X-API-Key` header mapping to a `Creator`.
3. On submit, persist a `DubJob` and one `DubOutput` per requested language.
4. A `dispatch()` call uses httpx to hit the provider; on callback, update the row
   and fire a signed webhook.

```python
def dispatch(session, job: DubJob, client: httpx.Client) -> None:
    for out in job.outputs:
        resp = client.post("/dub", json={"lang": out.language, "src": job.video_url})
        out.status = "done" if resp.status_code == 200 else "failed"
    # TODO: sign payload with HMAC and POST to creator's webhook URL.
    session.commit()
```

## WHEN TO USE IN PRODUCTION
Use it whenever dubbing is asynchronous, per-tenant, and needs billing/audit — SaaS
dubbing portals, studio pipelines, and agency accounts managing many creators. Also
ideal when results must be delivered by webhook. Do NOT use it for a one-off local
script or when the provider already offers hosted job management you can trust.
Avoid if you cannot operate a database or a reliable callback endpoint.

## HOW IT HELPS STUDENTS
Students practise ORM schema design, API-key auth, outbound HTTP with retries, and
webhook signing. They learn to model a real multi-tenant AI service with an audit
trail — the exact shape of production media tooling.

## STARTER CODE
See `starter/main.py` for SQLAlchemy models, an in-memory SQLite session, an
API-key check, an httpx-based `dispatch()` using a deterministic stub transport,
and `# TODO` markers for webhook signing and retries.
