# Telnyx + Voxtral Migration Runbook

> **⚠️ SUPERSEDED (2026-06-08).** The STT→LLM→TTS stack this runbook operationalizes
> (custom Python bridge + Voxtral STT + Supertonic TTS) is being replaced by **LiveKit Agents
> + a realtime speech-to-speech model** — see **`LIVEKIT_VOICE_MIGRATION.md`**. Kept for
> history and because the phased rollout mechanics (shadow → pilot → A/B → hybrid →
> governance) and the `voiceMigration.*` APIs still apply to the new provider.

This runbook operationalizes the phased migration in production without owning telephony infrastructure.

## Phase 0 - Baseline and Readiness

- Configure migration defaults via `api.public.voiceMigration.upsertMigrationConfig`.
- Record baseline KPI rows per queue/language via `api.public.voiceMigration.upsertBaselineKpi`.
- Validate dashboard data via `api.public.voiceMigration.getMigrationDashboard`.

Required baseline cohorts:
- Premium queue + primary language
- Cost-sensitive queue + primary language
- Each multilingual queue language cohort

## Phase 1 - Post-call Voxtral Validation

- Enable `postCallVoxtralEnabled=true` in migration config.
- Trigger batch evaluation on recent calls with `api.public.voiceMigration.runPostCallVoxtralBatch`.
- Confirm outputs in `postCallEvaluations` dashboard slice.

Acceptance:
- QA/compliance/intent scoring complete for representative sample.
- No impact to live call reliability (post-call only).

## Phase 2 - Real-time Pilot (Cohort Limited)

- Enable `realtimePilotEnabled=true`.
- Add routing policy for pilot cohort using `api.public.voiceMigration.upsertRoutingPolicy`.
- Confirm `realtimePilotEvents` include trace IDs, route, latency, confidence, DTMF parity.

Acceptance:
- p95 turn latency within threshold.
- No DTMF parity regressions.
- Candidate error rate within policy limits.

## Phase 3 - Controlled A/B

- Create experiment with `api.public.voiceMigration.createAbExperiment`.
- Set status `running` via `api.public.voiceMigration.setAbExperimentStatus`.
- Read decision metrics via `api.public.voiceMigration.summarizeAbExperiment`.

Acceptance gates:
- Cost reduction >= target.
- p95 latency delta <= target.
- Business KPI and escalation deltas within limits.

## Phase 4 - Hybrid Policy Rollout

- Set migration policy mode to `hybrid`.
- Add queue/language policies with explicit fallback routes.
- Keep premium queues on control or delayed migration as needed.

## Phase 5 - Governance and Hardening

- Persist daily operations snapshots via `api.public.voiceMigration.upsertOpsSnapshot`.
- Evaluate rollback triggers with `api.public.voiceMigration.evaluateRollbackAndTrigger`.
- Audit rollback events in `rollbackEvents`.

Mandatory rollback conditions:
- p95 latency breach
- business KPI drop breach
- escalation rate breach
- cost-reduction miss after stabilization window