EasyCat

Slim, batteries-included voice bot framework that runs idiomatic agents and workflows from OpenAI Agents SDK, PydanticAI, LangChain, LangGraph, LlamaAgents, Remote Responses API, or your own async workflow.

VoiceApp is the beginner and product-level entry point: give it your agent, then explicitly choose where it runs. The README, first example, feature ladder, and default scaffold all use this same shape:

from agents import Agent

from easycat import VoiceApp

app = VoiceApp(agent=Agent(name="assistant", instructions="You are a helpful voice assistant."))
app.run("local")

local uses your microphone and speakers. The same app can run in browser, websocket, or twilio mode when you install that mode's extras and server requirements. See examples/voice_app.py. The separate easycat serve command runs EasyCat's bundled playground (or an explicit server manifest); it does not import the VoiceApp in your Python file.

Graduate to EasyConfig when you need explicit providers, turn taking, journaling, or a caller-owned session:

from agents import Agent

from easycat import EasyConfig, run

run(
    EasyConfig.mic(
        agent=Agent(name="assistant", instructions="You are a helpful voice assistant.")
    )
)

Async application? Use await arun(config). Calling run(...) from an active event loop fails before startup and points you to arun(...).

The convenience helpers show live console feedback only on an interactive stderr. Use feedback="off" to keep a process quiet or feedback="on" to force first-run transcript/status output when stderr is redirected.

VoiceApp(...).run("local") and EasyConfig.mic(...) automatically wire OpenAI Realtime STT (gpt-realtime-whisper) and OpenAI TTS from OPENAI_API_KEY when you do not override stt or tts. This is provider traffic and may incur charges. If you omit the key, supply STT and TTS configs explicitly.

Python 3.11+ is required.

First prove the checkout works without API keys, audio hardware, or provider traffic:

uv sync --group dev
uv run easycat --version
uv run easycat console --voice-demo

console --voice-demo runs one scripted turn through the real audio pipeline and writes a replayable debug bundle. Ambient API keys are ignored; only easycat console --live opts into provider traffic that may incur charges.

Local microphone/speaker modes also need the PortAudio runtime. Install it before the Python extra on Linux or macOS:

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install -y libportaudio2

# macOS
brew install portaudio

EasyCat is not published to PyPI yet. For a portable application dependency, pin a Git commit (replace <commit-sha> with the revision you audited):

[project]
dependencies = ["easycat[quickstart]"]

[tool.uv.sources]
easycat = { git = "https://github.com/yisding/easycat.git", rev = "<commit-sha>" }

Use easycat = { path = "/path/to/easycat", editable = true } only when developing EasyCat and the application together. Generated scaffolds make that editable source explicit when they are created from a local checkout. Generate a portable scaffold directly with uv run easycat init my-agent --easycat-git https://github.com/yisding/easycat.git --easycat-git-rev <commit-sha>; Git and local source options are mutually exclusive.

For this repository, four commands go from the checkout to a talking bot. The first command preserves an existing .env; after it runs, edit .env and add your key before running doctor:

uv sync --extra quickstart --group dev
test -e .env || cp .env.example .env
uv run easycat doctor --env-file .env
uv run --env-file .env python examples/openai_agents_voice.py

Prefer exported shell variables? uv run easycat doctor and uv run python examples/openai_agents_voice.py work the same once OPENAI_API_KEY is exported. Add --json (uv run easycat doctor --json, or uv run easycat doctor --env-file .env --json) for parseable checks. See the installation and extras guide for browser, telephony, provider, agent-framework, and local-model installs.

The 16-chapter teaching ladder walks the entire voice pipeline ground-up, from audio chunks through production operations. Each chapter is a self-contained folder with a runnable program and exercises. Use this route when you want to understand the machinery rather than only assemble an application.

The EasyCat feature ladder starts with a working VoiceApp, then adds runtime modes, providers, conversation controls, tools, agent frameworks, sessions, debugging, evals, servers, telephony, and operations one capability at a time.

These examples use the installed form. From this repository, prefix commands with uv run, for example uv run easycat doctor.

easycat console --voice-demo        # deterministic, keyless proof of life
easycat init --list-templates       # compare application/provider scaffolds
easycat doctor                      # inspect local readiness without changing it
easycat doctor --env-file .env --json
easycat serve                       # bundled browser playground on loopback
easycat docs --audience app-builders
easycat validate quick              # deterministic local validation
easycat bundles list                # discover captured runs and journals

easycat init --list-templates reports each scaffold's base easycat[...] package requirement and extras, required environment variables, optional environment knobs, generated files, and copyable create/preflight/check/fix/docs/json-schema/run commands. Add --json for the machine-readable catalog. A generated default app uses the same VoiceApp(...).run("local") shape as the quickstart.

Use the CLI reference for every command family, easycat docs for audience-specific routes, and easycat explain json-schema for the stable JSON envelope. Coding agents should start with AGENTS.md and llms.txt.

• Session pipeline: noise reduction, echo cancellation, VAD, turn taking, STT, agent streaming, output processors, and TTS.
• STT and TTS: OpenAI, Deepgram, ElevenLabs, and Cartesia.
• VAD: Silero, FunASR, optional TEN VAD, and Krisp. Noise reduction: RNNoise, Krisp, and a passthrough fallback.
• Transports: Local, WebSocket, WebRTC, WebTransport, and Twilio Media Streams.
• Agent/workflow adapters: OpenAIAgentsBridge, PydanticAIBridge, LangChainBridge, LangGraphBridge, LlamaAgentsBridge, RemoteResponsesAPIBridge, and GenericWorkflowBridge.
• Typed events, interruption, telephony actions, multi-session servers, durable journals, replay, latency analysis, and debugger tooling.

EasyCat does not replace your agent framework. Pass an OpenAI Agents SDK, PydanticAI, LangChain, LangGraph, LlamaAgents, Remote Responses API, or your own async workflow object to VoiceApp/EasyConfig; the matching bridge is selected automatically. Construct a bridge directly only when you need bridge-specific options.

The top-level import surface is curated and lazy. See the public API contract before adding or depending on new from easycat import ... names.

Detailed routes:

• VoiceApp → EasyConfig → Session for lifecycle ownership, typed event subscriptions, async turns, and postmortems.
• Runtime modes and the browser playground for local and server modes.
• Providers and voices and provider authoring for hosted, local, and third-party stages.
• Tools and output processors and agent bridges.
• Telephony and production servers.
• Observability, testing and evals, and the validation workflow.
• Runnable examples with exact extras, environment variables, and commands.

For the complete maintained map, run uv run easycat docs or open docs/README.md. Repository architecture lives in CLAUDE.md; contribution commands live in CONTRIBUTING.md.