92 lines
5.7 KiB
Markdown
92 lines
5.7 KiB
Markdown
# Recommendations: TTS, Gitea, Phoenix, and Operations
|
||
|
||
**Last Updated:** 2026-02-10
|
||
**Scope:** virtual-banker TTS, Phoenix deployment, Gitea, and related operations.
|
||
|
||
---
|
||
|
||
## 1. TTS and Phoenix
|
||
|
||
### Implemented
|
||
|
||
- **Configurable base URL** — Use `TTS_BASE_URL` (or `PHOENIX_TTS_BASE_URL` with `USE_PHOENIX_TTS=true`) to point at Phoenix; no code change.
|
||
- **Optional auth header** — `TTS_AUTH_HEADER_NAME` / `TTS_AUTH_HEADER_VALUE` for Phoenix Bearer (or other) auth.
|
||
- **Health check** — `tts.Service.Health(ctx)` calls `GET {baseURL}/../health` when not using ElevenLabs; wire into readiness.
|
||
- **Decision table** — In the virtual-banker repo see `backend/tts/README.md` for which backend is used given env.
|
||
- **Phoenix API contract** — [PHOENIX_TTS_API_CONTRACT.md](PHOENIX_TTS_API_CONTRACT.md) defines required endpoints (sync, stream, health).
|
||
|
||
### Additional recommendations
|
||
|
||
- **Rate limiting / cost** — When using ElevenLabs, track usage (chars or requests) and consider rate limiting in-app or in Phoenix to avoid cost overruns.
|
||
- **Timeouts and resilience** — Client already uses 30s timeout and retries for sync. Consider a **circuit breaker** (e.g. after N failures, stop calling TTS for a cooldown) to avoid cascading failures.
|
||
- **Structured logging** — Log TTS provider (ElevenLabs vs Phoenix), latency, and errors (without logging `TTS_API_KEY` or auth values) for debugging and monitoring.
|
||
- **API versioning** — Phoenix TTS should version the path (e.g. `/v1/...`) so you can add `/v2` later without breaking existing clients.
|
||
- **Fallback** — Optional: if Phoenix is down, fall back to ElevenLabs when both are configured (e.g. try Phoenix first, on failure or health error use ElevenLabs). Requires explicit design (env flags, health checks).
|
||
- **Secrets** — Never log or expose `TTS_API_KEY` / `ELEVENLABS_API_KEY` / `TTS_AUTH_HEADER_VALUE`. In production use a secret manager (e.g. Phoenix env, Vault) and inject into env.
|
||
|
||
---
|
||
|
||
## 2. Gitea and repos
|
||
|
||
### Implemented
|
||
|
||
- **Push all projects** — From proxmox root: `bash scripts/dev-vm/push-all-projects-to-gitea.sh`; includes virtual-banker. See [EXPLORER_MONOREPO_GITEA_PUSH.md](EXPLORER_MONOREPO_GITEA_PUSH.md).
|
||
- **Labels** — `apply-gitea-labels.sh` creates `project/virtual-banker` (and others). Apply `project/virtual-banker` and `domain/api` to the virtual-banker repo in Gitea (Settings → Labels).
|
||
- **virtual-banker CI** — `.gitea/workflows/ci.yml` in virtual-banker runs `go build` and `go test` on push/PR.
|
||
|
||
### Additional recommendations
|
||
|
||
- **Branch protection** — Enable branch protection for `master`/`main` on virtual-banker (and other key repos); require PR and passing CI. See [GITEA_BRANCH_PROTECTION.md](GITEA_BRANCH_PROTECTION.md) if present.
|
||
- **Renovate / Dependabot** — Consider Renovate or similar for virtual-banker (Go deps) so security and version updates are automated. See [RENOVATE_GITEA_SETUP.md](RENOVATE_GITEA_SETUP.md) if present.
|
||
|
||
---
|
||
|
||
## 3. virtual-banker deployment and config
|
||
|
||
### Implemented
|
||
|
||
- **.env.example** — virtual-banker root has `.env.example` with `TTS_*`, `ELEVENLABS_*`, `USE_PHOENIX_TTS`, `DATABASE_URL`, `REDIS_URL`, `PORT`. Copy to `.env` and set values; do not commit `.env`.
|
||
- **Feature flag** — `USE_PHOENIX_TTS=true` (or `1`) forces Phoenix TTS; use `TTS_BASE_URL` or `PHOENIX_TTS_BASE_URL`.
|
||
|
||
### Additional recommendations
|
||
|
||
- **Readiness endpoint** — Expose a `/ready` (or extend `/health`) that calls `tts.Service.Health(ctx)` when TTS is configured, so Kubernetes or load balancers only send traffic when TTS backend is up.
|
||
- **Monitoring** — Track TTS latency (e.g. existing `RecordTTSLatency`), error rate, and provider (ElevenLabs vs Phoenix) in metrics/dashboards so you can detect regressions and compare backends.
|
||
|
||
---
|
||
|
||
## 4. Reuse: TTS as a standalone module
|
||
|
||
### Implemented
|
||
|
||
- **Same interface, swap endpoint** — Other projects can depend on virtual-banker’s `backend/tts` package and use `NewElevenLabsTTSServiceWithOptions` / `NewElevenLabsTTSServiceWithOptionsFull` with any base URL and auth.
|
||
|
||
### Additional recommendations
|
||
|
||
- **Standalone tts-client repo** — If multiple repos (outside virtual-banker) will use this client, consider extracting the `tts` package into a small Go module (e.g. `github.com/d-bis/tts-client`). virtual-banker would then depend on that module, and others can use it without pulling in virtual-banker. Reduces coupling and clarifies ownership.
|
||
- **Visemes** — Current visemes are client-side approximation. For better lip-sync, add a Phoenix endpoint (or separate service) that returns phoneme/viseme timings and extend the client to call it when `TTS_BASE_URL` is set.
|
||
|
||
---
|
||
|
||
## 5. Quick reference
|
||
|
||
| Topic | Doc / location |
|
||
|-------|-----------------|
|
||
| Which TTS backend? | virtual-banker `backend/tts/README.md` (decision table) |
|
||
| Phoenix TTS API contract | [PHOENIX_TTS_API_CONTRACT.md](PHOENIX_TTS_API_CONTRACT.md) |
|
||
| Push all projects to Gitea | [EXPLORER_MONOREPO_GITEA_PUSH.md](EXPLORER_MONOREPO_GITEA_PUSH.md) |
|
||
| Gitea labels and structure | [GITEA_ORG_STRUCTURE.md](GITEA_ORG_STRUCTURE.md) |
|
||
| virtual-banker env vars | virtual-banker repo: `.env.example` |
|
||
| virtual-banker CI | virtual-banker repo: `.gitea/workflows/ci.yml` |
|
||
|
||
---
|
||
|
||
## 6. Checklist (optional)
|
||
|
||
- [ ] Apply Gitea labels to virtual-banker (`project/virtual-banker`, `domain/api`) after running `apply-gitea-labels.sh`
|
||
- [ ] Configure Phoenix TTS to implement the contract in PHOENIX_TTS_API_CONTRACT.md and expose `GET /health`
|
||
- [ ] Set TTS env (or secrets) in Phoenix/deployment so virtual-banker uses Phoenix when desired
|
||
- [ ] Wire `tts.Health()` into readiness probe or `/ready` if you need TTS-up before accepting traffic
|
||
- [ ] Add monitoring for TTS latency and errors
|
||
- [ ] Consider extracting `tts` into a standalone Go module if multiple services will depend on it
|