(feat): migrate dragontts code to clairvoyance repo

.dockerignore

@@ -104,3 +104,11 @@ coverage.xml
 
 # UV cache (keep .python-version and uv.lock - they're needed in Docker)
 .uv/
+
+# DragonTTS — self-contained sub-service (own Dockerfile/pyproject/venv under
+# dragontts/). The clairvoyance Dockerfile does `COPY . .` (NOT `COPY app ./app`),
+# so this exclusion is LOAD-BEARING: without it, the entire dragontts/ service
+# (its own Dockerfile, pyproject, and app/ subpackage) would be baked into the
+# clairvoyance image. Do NOT remove it thinking it's redundant. dragontts ships
+# its own image via dragontts-docker-publish.yml (context: dragontts).
+dragontts/

.github/workflows/dragontts-docker-publish.yml

@@ -0,0 +1,62 @@
+name: Build & Push DragonTTS Image to Artifact Registry
+
+# Pushes the DragonTTS image (the self-contained app under dragontts/, with
+# its own Dockerfile/pyproject/uv.lock) to its own Artifact Registry repo.
+# Independent of the clairvoyance image workflows: it only runs when DragonTTS
+# files change on `release`. Build + push only — the GKE rollout is done
+# manually with kubectl. Reuses clairvoyance's WIF identity (same repo/project).
+#
+# Prerequisite (GCP side, not CI): the github-deployer@breeze-automatic-prod SA
+# must have Artifact Registry Writer on the `dragontts` repo in
+# breeze-automatic-prod (it already has it on `clairvoyance`).
+
+on:
+  push:
+    branches:
+      - release
+    paths:
+      - dragontts/**
+
+permissions:
+  id-token: write
+  contents: read
+
+concurrency:
+  group: dragontts-docker-publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Authenticate to Google Cloud
+        uses: google-github-actions/auth@v1
+        with:
+          workload_identity_provider: projects/840384202515/locations/global/workloadIdentityPools/github-pool/providers/github-provider
+          service_account: github-deployer@breeze-automatic-prod.iam.gserviceaccount.com
+
+      - name: Configure Docker for Artifact Registry
+        run: |
+          gcloud auth configure-docker asia-south1-docker.pkg.dev --quiet
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Extract short SHA
+        run: echo "SHORT_SHA=${GITHUB_SHA:0:8}" >> $GITHUB_ENV
+
+      - name: Build and Push DragonTTS Image to Artifact Registry
+        uses: docker/build-push-action@v5
+        with:
+          context: dragontts
+          push: true
+          platforms: linux/amd64
+          tags: |
+            asia-south1-docker.pkg.dev/breeze-automatic-prod/dragontts/dragontts:${{ env.SHORT_SHA }}
+            asia-south1-docker.pkg.dev/breeze-automatic-prod/dragontts/dragontts:latest
+          provenance: false
+          sbom: false

dragontts/.dockerignore

@@ -0,0 +1,15 @@
+.git
+.github
+.venv
+.pytest_cache
+.claude
+.env
+.env.*
+!.env.example
+data
+tests
+scripts
+README.md
+*.md
+__pycache__
+*.pyc

dragontts/.env.example

@@ -0,0 +1,31 @@
+# --- Provider credentials (names mirror clairvoyance) ---
+CARTESIA_API_KEY=
+SARVAM_API_KEY=
+ELEVENLABS_API_KEY=
+ELEVENLABS_BASE_URL=https://api.elevenlabs.io
+ELEVENLABS_INDIAN_RESIDENCY_API_KEY=
+ELEVENLABS_INDIAN_RESIDENCY_BASE_URL=
+GOOGLE_CREDENTIALS_JSON=
+GOOGLE_CREDENTIALS_PATH=
+
+# --- Storage (point both at a persistent volume in k8s) ---
+DB_PATH=data/dragontts.db
+BLOB_DIR=data/blobs
+
+# --- Cache policy ---
+MAX_CACHE_BYTES=0        # 0 = unlimited
+TTL_SECONDS=0            # 0 = no expiry
+ENABLE_WRITE_THROUGH=true
+
+# --- Sentence splitting ---
+# Split a transcript into sentences BEFORE synth/serve so each is synthesized +
+# cached under its own key (recurring sentences get reused). Parts are then pure-
+# concatenated — no edge trim, no inserted gap (nothing is cut; appended exactly
+# as synthesized). Empty = OFF (the whole transcript is one cache entry, the
+# default). Set to the symbols to split AFTER, e.g. .:?! The synth and stream
+# paths are controlled INDEPENDENTLY:
+SPLIT_AT_SYMBOLS=         # /tts/bytes  (one-shot synth) path; empty = OFF
+SPLIT_AT_SYMBOLS_STREAM=  # /tts/stream path; empty = OFF
+# Only split when EVERY resulting part has >= this many words (a lone single-word
+# part isn't worth caching alone, so the whole phrase stays one entry).
+SPLIT_MIN_WORDS_PER_PART=2

dragontts/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+env/
+
+# Node
+node_modules/
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+
+# Claude (local tooling state — never commit)
+.claude/
+
+# DragonTTS runtime storage (SQLite db + audio blobs)
+data/
+*.db
+
+# Audio artifacts
+*.wav
+*.mp3
+*.ogg
+/samples/
+
+# Local live smoke tests + their audio output (never commit)
+/smoke/

dragontts/.python-version

@@ -0,0 +1 @@
+3.11

dragontts/Dockerfile

@@ -0,0 +1,29 @@
+FROM python:3.12-slim AS base
+
+# Cap glibc malloc arenas so freed memory returns to the OS instead of fragmenting
+# across dozens of pools. The default (8 x host-cores) lets the 4x32 worker
+# threads strand freed audio buffers across ~100 arenas -> anon RSS creeps. 4 is a
+# small fixed cap; zero perf cost on this 1-CPU, GIL-bound, async-I/O pod.
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_COMPILE_BYTECODE=1 \
+    MALLOC_ARENA_MAX=4
+
+COPY --from=ghcr.io/astral-sh/uv:0.5.11 /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-install-project
+
+COPY app ./app
+
+RUN uv sync --frozen
+
+RUN useradd --uid 1000 --create-home appuser && chown -R appuser:appuser /app
+USER appuser
+
+EXPOSE 8000
+
+CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4", "--loop", "uvloop", "--no-access-log", "--limit-concurrency", "1024"]

dragontts/README.md

@@ -0,0 +1,48 @@
+# dragonTTS
+
+TTS caching proxy (FastAPI): caches text-to-speech audio to cut latency and cost
+on repeated synthesis. Multi-provider (Cartesia / ElevenLabs / Sarvam / Gemini),
+SQLite + filesystem store, write-through caching with length-scaled TTL.
+
+## Run locally
+
+The folder is self-contained — a venv, deps, and the `app` package all live
+inside it. Always `cd` here and run from this folder.
+
+### 1. Configure env
+```bash
+cp .env.example .env      # then fill in provider API keys in .env
+```
+`.env` is gitignored — it is the only place real keys go locally (in prod they
+are kubectl-injected, never in the image).
+
+Key knobs (see `.env.example` for the full list):
+- `SPLIT_AT_SYMBOLS` — split `/tts/bytes` (one-shot) transcripts into per-
+  sentence cache entries (e.g. `.:?`). Empty = off.
+- `SPLIT_AT_SYMBOLS_STREAM` — same, for `/tts/stream`.
+- `ENABLE_WRITE_THROUGH=true` — store every synth into the cache.
+- `CACHE_TTL_*` — length-scaled TTL (longer phrases live longer).
+
+### 2. Install + run (uv)
+```bash
+uv sync
+uv run uvicorn app.main:app --reload
+```
+Plain venv (no uv): `python3.11 -m venv .venv && source .venv/bin/activate &&
+pip install -e . && uvicorn app.main:app --reload`
+
+Server starts on http://127.0.0.1:8000 → try `GET /health`.
+
+## Endpoints
+- `POST /tts/bytes` — one-shot synthesis (cached, returns μ-law 8 kHz).
+- `POST /tts/stream` — chunked streaming synthesis (raw pcm_s16le @ 16 kHz).
+- `POST /cache/clear` — clear the cache at runtime (don't delete `data/` while
+  the server runs).
+- `GET /health` — liveness + configured providers.
+- `GET /stats`, `GET /stats/daily`, `GET /stats/latency` — cache economics.
+- `POST /slack-summary` — manually trigger the daily Slack summary.
+
+## Notes
+- Cache store lives in `data/` (SQLite db + audio blobs) — gitignored; keep it
+  on a persistent volume in prod.
+- Split parts are pure-concatenated (no audio is trimmed/cut).

dragontts/app/__init__.py

@@ -0,0 +1,3 @@
+"""DragonTTS — caching TTS proxy compatible with clairvoyance providers."""
+
+__version__ = "0.1.0"

dragontts/app/alerts/__init__.py

@@ -0,0 +1 @@
+"""Slack alerting (incoming-webhook Block Kit sender + daily cache summary)."""