voicegateway AGENTS.md

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project

VoiceGateway: cost tracking and reconciliation for voice agents on LiveKit, Pipecat and OpenRTC. Meters the native STT, LLM, and TTS instances you pass to attach() / guard() across cloud providers (OpenAI, Deepgram, Anthropic, Groq, Cartesia, ElevenLabs, AssemblyAI) and local models (Whisper, Kokoro, Piper). LLM, STT, and TTS prices all flow through voice-prices (a fork of pydantic/genai-prices). Ships voicegw reconcile for verifying recorded numbers against provider invoices, plus per-modality cost tracking, resolver-time fallback chains, rate limiting, and a web dashboard.

Commands

# Install (editable, with dev dependencies)
pip install -e ".[dev]"

# Run tests
pytest
pytest src/voicegateway/tests/core/test_config.py              # single file
pytest src/voicegateway/tests/core/test_config.py::test_name   # single test
pytest --cov                                                   # with coverage

# CLI
voicegw init                             # create config template
voicegw serve --port 8080                # start HTTP API
voicegw dashboard                        # start web UI (port 9090)
voicegw status                           # show provider status

# Dashboard frontend (src/dashboard/frontend/)
npm install && npm run dev               # dev server
npm run build                            # production build

# Docker
docker compose up -d                     # API + Dashboard
docker compose --profile local up -d     # + Ollama

Architecture

Request flow: User code → Gateway.stt()/llm()/tts() → Router → Provider → Middleware pipeline (cost tracking, latency, rate limiting, fallback) → SQLite storage → Dashboard reads stored data.

Core (src/voicegateway/core/):

• gateway.py — Main orchestrator, entry point for all requests
• config.py — YAML parser with ${ENV_VAR} substitution
• router.py — Resolves provider/model strings to provider instances
• registry.py — Lazy provider factory (instantiates on first use)
• model_id.py — Parses provider/model format strings