# Douanier — ParVagues Audio-Intelligence API 🛂

The customs gate over the fleet's audio-intelligence engines: one self-hosted,
token-authed, async HTTP API that turns a URL or a clip into **stems, loops,
emotion reads, sample analysis, and features**. Named after Le Douanier Rousseau.

Productizes the [Foundry](../../tools/foundry/) + the tide-table "ears"
(`emotion_ontology`, `sample_semantics`, the feature stack) for **hexa** (Shipow)
and future seats. Full design + decisions: memory `project_douanier_api`, EPIC
task **#21**, and [`SRE.md`](./SRE.md) for the hosting handoff.

## Layout

```
armada/api/
  app.py          FastAPI app — /v1 router, /v1/healthz, /v1/analyze/emotion
  config.py       paths · dev token · limits (env-overridable)
  engines/        thin adapters over the fleet libs (lazy heavy imports)
    ears.py       emotion read = sample_semantics embed → emotion_ontology.score
  tests/          smoke tests (no CLAP/torch needed — engine call is mocked)
  requirements.txt   API-layer deps only; ML stack inherited from system venv
```

## Run (dev)

```bash
python3 -m venv --system-site-packages ~/.virtualenvs/douanier   # once
~/.virtualenvs/douanier/bin/pip install -r requirements.txt      # once

cd armada/api
DOUANIER_DEV_TOKEN=$(openssl rand -hex 16) \
  ~/.virtualenvs/douanier/bin/uvicorn app:app --port 8780
```

- `GET  /v1/healthz` — status + engine availability
- `POST /v1/analyze/emotion` — `multipart` audio file → `{valence, arousal, top…}`
  (Bearer `DOUANIER_DEV_TOKEN` required)
- `GET  /v1/docs` — Swagger UI

```bash
curl -s -H "Authorization: Bearer $DOUANIER_DEV_TOKEN" \
  -F file=@clip.wav http://127.0.0.1:8780/v1/analyze/emotion | jq
```

## Test

```bash
cd armada/api && ~/.virtualenvs/douanier/bin/python -m pytest tests/ -q
```

## Status

Walking skeleton (tasks #22 + #36): scaffold + synchronous emotion endpoint with
stub auth. Queued, building *under* this without changing the public shape:
SQLite auth/quota (#23/#24), async jobs + worker (#25), content-addressed cache
(#26), signed artifact URLs (#27), `/features`+`/samples` hardened (#28),
`/sources`→`/separate`→`/loops` heavy chain (#29–#31), OpenAPI client (#32),
ops/runbook (#34).

> **Why a venv with `--system-site-packages`?** The ears/Foundry engines need the
> multi-GB ML stack (torch/CLAP/librosa/demucs) already installed system-wide on
> the box; the venv reuses it and only adds FastAPI/uvicorn. Arch's PEP-668 lock
> is why we don't `pip install` into system Python.
