# EasyCat

> EasyCat is a Python voice bot framework: noise reduction -> VAD -> STT ->
> agent -> TTS, with pluggable providers at each stage and idiomatic bridges
> for OpenAI Agents SDK, PydanticAI, LangChain, LangGraph, LlamaAgents, the
> remote Responses API, or your own async workflow.

Machine-readable surfaces: `easycat docs --json` emits this route map with
command hints and audience labels; `easycat explain json-schema` documents the
standard `--json` envelope every CLI command shares. Bare `easycat` commands
use the installed CLI form; from this repository, prefix them with `uv run`.

Source: https://github.com/yisding/easycat

## Docs

- [Start here](https://github.com/yisding/easycat/blob/main/README.md#choose-your-path) — for all readers: Choose the right first route for quickstart, learning, examples, maintenance, or operations.
- [Quickstart](https://github.com/yisding/easycat/blob/main/README.md#install) — for new users: Install EasyCat and run your first voice agent.
- [Installation and extras](https://github.com/yisding/easycat/blob/main/docs/install.md) — for app builders: Choose a portable dependency source and the smallest provider, transport, agent-framework, or processing extras for an application.
- [CLI and scaffolds](https://github.com/yisding/easycat/blob/main/docs/cli.md) — for app builders: Scaffold projects, compare templates with base package requirements, extras, env requirements, optional env knobs, generated files, and copyable create/preflight/check/fix/docs/json-schema/run commands, and learn CLI JSON envelopes.
- [Docs map](https://github.com/yisding/easycat/blob/main/docs/README.md) — for all readers: Choose the maintained guide for your current task.
- [Teaching ladder](https://github.com/yisding/easycat/tree/main/docs/teaching) — for learners: Learn voice pipelines chapter by chapter.
- [Progress worksheet](https://github.com/yisding/easycat/blob/main/docs/teaching/PROGRESS.md) — for learners: Track evidence-backed completion across all 16 teaching chapters.
- [First lesson](https://github.com/yisding/easycat/tree/main/docs/teaching/00-hello-audio) — for learners: Start with audio chunks before agents or providers.
- [EasyCat feature ladder](https://github.com/yisding/easycat/tree/main/docs/using-easycat) — for learners: Learn EasyCat's public features one app capability at a time.
- [Feature first lesson](https://github.com/yisding/easycat/tree/main/docs/using-easycat/00-first-voice-app) — for learners: Build a local voice app with VoiceApp and automatic pipeline wiring.
- [Feature runtime modes](https://github.com/yisding/easycat/tree/main/docs/using-easycat/01-runtime-modes) — for learners: Run one VoiceApp locally, in a browser, over WebSocket, or on Twilio.
- [Feature providers and voices](https://github.com/yisding/easycat/tree/main/docs/using-easycat/02-providers-and-voices) — for learners: Select STT and TTS providers, models, and provider-specific voices.
- [Feature conversation controls](https://github.com/yisding/easycat/tree/main/docs/using-easycat/03-conversation-controls) — for learners: Tune turn taking, signal cleanup, interruption, and push-to-talk.
- [Feature tools and actions](https://github.com/yisding/easycat/tree/main/docs/using-easycat/04-tools-actions) — for learners: Separate agent tools, session actions, events, and spoken-output rules.
- [Feature agent bridges](https://github.com/yisding/easycat/tree/main/docs/using-easycat/05-agent-bridges) — for learners: Choose a framework adapter or bring a custom workflow.
- [Feature session control](https://github.com/yisding/easycat/tree/main/docs/using-easycat/06-session-control) — for learners: Own session lifecycle, events, text turns, resets, and teardown.
- [Feature observability](https://github.com/yisding/easycat/tree/main/docs/using-easycat/07-observability) — for learners: Record, inspect, replay, and compare journals and debug bundles.
- [Feature testing and evals](https://github.com/yisding/easycat/tree/main/docs/using-easycat/08-testing-evals) — for learners: Test offline turns, evaluation oracles, and latency budgets.
- [Feature multi-caller servers](https://github.com/yisding/easycat/tree/main/docs/using-easycat/09-multi-caller) — for learners: Serve isolated callers with auth, capacity limits, and draining.
- [Feature telephony](https://github.com/yisding/easycat/tree/main/docs/using-easycat/10-telephony) — for learners: Secure Twilio webhooks, media streams, callbacks, and call control.
- [Feature production operations](https://github.com/yisding/easycat/tree/main/docs/using-easycat/11-production-ops) — for learners: Validate, deploy, observe, preserve, and drain production services.
- [Examples](https://github.com/yisding/easycat/blob/main/examples/README.md) — for app builders: Find runnable local, browser, WebSocket, and telephony apps.
- [Architecture](https://github.com/yisding/easycat/blob/main/docs/architecture.md) — for maintainers: Understand the pipeline, session collaborators, stages, providers, and agent bridges.
- [Maintainer guide](https://github.com/yisding/easycat/blob/main/CLAUDE.md) — for maintainers: Orient to the pipeline, packages, provider registries, lifecycle, and docs/onboarding guards.
- [Coding agents](https://github.com/yisding/easycat/blob/main/AGENTS.md) — for coding agents: Follow repo structure, development commands, docs/onboarding guards, and PR expectations.
- [Developer textbook](https://github.com/yisding/easycat/tree/main/docs/development) — for maintainers: Work through the chapter-by-chapter source, test, decision, and change-recipe tour for new maintainers.
- [Session graduation](https://github.com/yisding/easycat/blob/main/docs/from-easyconfig-to-session.md) — for app builders: Graduate from the EasyConfig quickstart to the production Session API: lifecycle, events, text turns, session actions, and replayable debug bundles.
- [Testing and evals](https://github.com/yisding/easycat/blob/main/docs/testing-and-evals.md) — for app builders: Climb the eval ladder: bundle fixtures, offline text turns, latency budgets and LLM-as-judge, then live audio validation.
- [Events reference](https://github.com/yisding/easycat/blob/main/docs/reference/events.md) — for app builders: Look up every public session event type and when it is emitted.
- [Journal records reference](https://github.com/yisding/easycat/blob/main/docs/reference/journal-records.md) — for app builders: Look up stable built-in journal record names, kinds, and data-key contracts.
- [EasyConfig reference](https://github.com/yisding/easycat/blob/main/docs/reference/easyconfig.md) — for app builders: Look up every EasyConfig construction field.
- [Session lifecycle](https://github.com/yisding/easycat/blob/main/docs/reference/session-lifecycle.md) — for app builders: Start, stop, force-stop, and read the journal after teardown.
- [Browser playground](https://github.com/yisding/easycat/blob/main/docs/browser-playground.md) — for app builders: Talk to a bot in the browser with one command, and read the WebSocket/WebRTC wire protocol behind the playground page.
- [Public API](https://github.com/yisding/easycat/blob/main/docs/public-api.md) — for maintainers: Review the stable import surface before changing exports.
- [Provider contracts](https://github.com/yisding/easycat/blob/main/tests/contracts/README.md) — for provider maintainers: Maintain offline provider, protocol, cassette, and bridge contract coverage.
- [Extending providers](https://github.com/yisding/easycat/tree/main/docs/extending) — for provider maintainers: Build custom STT, TTS, VAD, transport, and agent-bridge providers out of tree and verify conformance.
- [Contributing](https://github.com/yisding/easycat/blob/main/CONTRIBUTING.md) — for contributors: Follow the development loop, docs/onboarding guards, and validation slices.
- [Deployment](https://github.com/yisding/easycat/blob/main/docs/deployment/docker.md) — for operators: Package the WebSocket example for container deployment.
- [Production servers](https://github.com/yisding/easycat/blob/main/docs/deployment/production-servers.md) — for operators: Run multi-client WebSocket, WebRTC, WebTransport, and Twilio servers with one isolated EasyCat session per client or call.
- [Observability](https://github.com/yisding/easycat/blob/main/docs/observability.md) — for operators: Inspect journals, debug bundles, the debugger UI, metrics, and traces.
- [Latency](https://github.com/yisding/easycat/blob/main/docs/latency.md) — for operators: Answer "why was that turn slow?" with per-turn CLI waterfalls and the table of latency-adding defaults.
- [Journal durability](https://github.com/yisding/easycat/blob/main/src/easycat/runtime/DURABILITY.md) — for operators and maintainers: Understand SQLite journal persistence, recovery, and storage layout.
- [Validation](https://github.com/yisding/easycat/blob/main/docs/validation.md) — for contributors: Run docs/onboarding guards, the right validation lane, and inspect .easycat/validation/latest.json.
- [Validation reference](https://github.com/yisding/easycat/blob/main/docs/reference/validation-vocabulary.md) — for release maintainers: Read provider and report vocabulary used by validation.

## Optional

- [llms-full.txt](https://github.com/yisding/easycat/blob/main/llms-full.txt) — every docs route above expanded with its copyable command hints.
