Stand up Douanier — the ParVagues Audio-Intelligence API — as a new self-hosted
service in armada/api/, and prove the lean MVP vertical end-to-end before
investing in the auth/quota/jobs/cache machinery it'll later sit on.
WHY: hexa (Shipow's hydra-live-hexa Studio) wants to call our engines (stems,
loops, emotion, samples, features) live from his Vercel world. Rather than build
six foundational tasks before the first useful call, we ship a walking skeleton:
scaffold + ONE real synchronous endpoint + a stub token, to de-risk the three
seams that actually matter — engines import cleanly, the service runs, a client
can auth & call.
WHAT:
- FastAPI app (app.py) versioned at /v1: /v1/healthz (status + engine
availability) and POST /v1/analyze/emotion (upload clip -> valence/arousal +
top emotions), guarded by a hardcoded dev bearer that FAILS CLOSED (503 if no
token configured, never accidentally unauthenticated).
- engines/ adapter layer with lazy heavy imports — ears.emotion_of() wraps the
real tide-table seam: sample_semantics.embed_audios -> emotion_ontology.score.
The route never touches the engine directly, so #28 can wrap it with
cache+async later without changing the public shape.
- config.py (env-overridable paths/token/limits); requirements.txt documents the
--system-site-packages venv trick (reuse the box's multi-GB torch/CLAP/demucs
stack, add only FastAPI on top — Arch PEP-668 blocks system pip).
- SRE.md: a context letter to whoever maps the public api.nech.pl path — the 10
hosting decisions that are theirs (path vs host routing, systemd vs Docker,
ports, TLS, GPU dispatch, freebox mount, secrets, observability, WAF, CORS).
- README.md + smoke tests.
VALIDATION:
- 5/5 smoke tests green (healthz; auth fails-closed/opens; happy-path mocked;
413 oversize) with no CLAP/torch needed.
- Real engine seam confirmed importable, and the FULL pipeline run end-to-end on
a synthetic clip: real CLAP read, valence 0.154 / arousal 0.141, V/A in range,
34.4s cold (model load — which is precisely why #28 warms CLAP once in the
worker rather than per request).
