feat(tts): serve all TTS from the RunPod Orpheus-3B deployment

[PatrickCmd]

Summary

Makes the RunPod Orpheus-3B deployment the only TTS inference serving point. POST /tasks/audio/speech (and its batch/speakers/url siblings) now route exclusively to RunPod Orpheus; spark-tts, Modal, and the legacy per-provider TTS routes are removed.

Net −4,576 lines (mostly deletions). Design spec: docs/superpowers/specs/2026-07-25-tts-runpod-orpheus-only-design.md.

Key finding

The RunPod server.py is a port of the former Modal app with the identical route table (/tts, /tts/batch, /speakers, /health), so this is a repoint + teardown, not a new client. The Modal client's retry/backoff logic was generalized into OrpheusClient, pointed at RunPod with Bearer auth and long cold-start timeouts.

What changed

New

• app/integrations/orpheus_runpod.py — OrpheusClient (Bearer auth, long timeouts, stream_speech() for /v1/audio/speech).
• app/tests/test_orpheus_runpod_client.py — client unit tests (MockTransport).

Core

• speech_service.py — Orpheus-only; adds stream(); surfaces audio_bytes for response_mode='both'.
• routers/audio.py — create_speech: url (signed GCS URL) · stream (RunPod byte passthrough) · both (bytes + X-Audio-Url header). Batch capped at 16.
• schemas/speech.py — drop model, platform, max_new_audio_tokens; batch max 128→16.
• message_processor.py — WhatsApp voice replies synthesize via the shared Orpheus SpeechService (uses returned bytes directly).
• config.py / .env.example — TTS_API_URL (default https://gfg8z4dvexiz85.api.runpod.ai/v1, /v1 optional) is the TTS base URL; ORPHEUS_MODEL_NAME (default sunbird-orpheus-tts) is the /v1/audio/speech model id; bearer reuses RUNPOD_API_KEY.

Removed — tts.py, runpod_tts.py, orpheus_tts.py routers, legacy /tasks/tts, tts_service.py, runpod_tts_service.py, orpheus_modal.py, and their tests.

Docs — docs.py, docs/tutorial.md, frontend/src/pages/Tutorial.tsx.

Breaking changes

• /tasks/audio/speech rejects model / platform / max_new_audio_tokens and no longer offers spark-tts.
• Legacy routes removed: /tasks/modal/tts*, /tasks/runpod/tts, /tasks/modal/orpheus/*, /tasks/tts.
• response_mode='both' now returns raw audio bytes with the signed URL in the X-Audio-Url header (was SSE).

Config

• TTS_API_URL is the RunPod endpoint (default https://gfg8z4dvexiz85.api.runpod.ai/v1; the /v1 suffix is optional). The client derives both the root (custom routes) and the /v1 base (/v1/audio/speech). If set to empty, TTS 503s at request time.
• ORPHEUS_MODEL_NAME = sunbird-orpheus-tts (model id for /v1/audio/speech).
• Bearer auth reuses RUNPOD_API_KEY.

Test plan

• pytest app/tests/ → 1126 passed; 6 failures are pre-existing .env-leak failures (ga_*, qwen_endpoint_id) unrelated to TTS.
• black/isort/flake8 on app/ → clean.
• frontend/ npm run build (tsc + vite) → clean.

Not verified here

• Live synthesis against the RunPod endpoint (no key locally). The client relies on the RunPod port keeping Modal's exact /tts headers and /tts/batch base64 shape — if the port diverged, client parsing is where to adjust.
• frontend npm run lint — the repo's ESLint config predates ESLint 10 and errors before linting (pre-existing). Type coverage via tsc.

🤖 Generated with Claude Code