kural

Why kural

How it works today

kural ships three modes, switchable via KURAL_MODE. voice is the v0.1 cascade; echo is a transport smoke test; telephony (v0.3) runs the same cascade over real phone calls.

Silero VAD decides when the caller stopped speaking. Each layer is built through a small Adapter Protocol and a registry, so swapping the STT, LLM, or TTS backend is one env var (KURAL_LLM_PROVIDER, KURAL_STT_PROVIDER, KURAL_TTS_PROVIDER). Currently registered: OpenAI-compatible LLM; faster-whisper and Deepgram STT; Piper, ElevenLabs, and Kokoro TTS.

Telephony (v0.3)

KURAL_MODE=telephony runs a FastAPI/uvicorn server instead of a local audio loop. Inbound calls hit a webhook, get bridged onto a Twilio Media Streams WebSocket, and run through the same voice pipeline above — only the transport differs. Each call is its own worker, so multiple calls run concurrently.

Twilio is the first TelephonyAdapter implementation, wired through the same registry pattern as the LLM/STT/TTS layers — Pipecat already ships serializers for Telnyx, Plivo, Exotel, Genesys, and Vonage, so adding another provider is a new adapter class, not a pipeline change. A small REST API (POST /calls/outbound, GET /calls, GET /calls/{sid}) places outbound calls and reads call history from a local SQLite log.

Latency budget (voice mode)

Target on a recent Apple Silicon laptop, all local: < 2 s end-to-end (caller stops speaking → first audio of reply).

Target architecture

Provider matrix

Quickstart

Install once:

# macOS:   brew install portaudio
# Ubuntu:  sudo apt-get install -y portaudio19-dev

git clone https://github.com/nnavnita/kural
cd kural
cp .env.example .env
python -m venv .venv && source .venv/bin/activate
pip install -e .

Voice mode (default) — full STT → LLM → TTS

Cheapest local path: a small model via Ollama.

# 1. Pull a small model once
ollama pull llama3.1:8b
ollama serve

# 2. Point kural at it (or edit .env)
export KURAL_LLM_BASE_URL=http://localhost:11434/v1
export KURAL_LLM_API_KEY=ollama          # ignored by Ollama; any string
export KURAL_LLM_MODEL=llama3.1:8b

kural                                    # or: python -m kural.server

Whisper and Piper auto-download weights on first run (~1 GB total). Wear headphones, speak, hear the reply.

Echo mode — transport smoke test, no API keys

KURAL_MODE=echo kural

Telephony mode — Twilio inbound/outbound calls

Needs a publicly reachable URL for Twilio's webhooks — ngrok http 8000 works for local dev.

# 1. Tunnel a public URL to your machine
ngrok http 8000

# 2. Configure (or edit .env)
export KURAL_MODE=telephony
export KURAL_PUBLIC_BASE_URL=https://your-tunnel.ngrok.app
export TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export TWILIO_AUTH_TOKEN=your_auth_token
export TWILIO_PHONE_NUMBER=+15551234567

kural                                    # serves webhook + media stream + REST API on :8000

Point the Twilio number's voice webhook at <public-url>/telephony/voice. Place an outbound call with curl -X POST :8000/calls/outbound -d '{"to":"+15557654321"}'; list history with curl :8000/calls.

Configuration

Settings.from_env reads:

Stop the agent with Ctrl+C. See .env.example for the full list.

Roadmap

• Done v0 — Local echo agent (mic → speaker passthrough)
• Done v0.1 — STT → LLM → TTS pipeline with one provider per layer
• Done v0.2 — Provider adapters: OpenAI-compatible LLM; faster-whisper + Deepgram STT; Piper + ElevenLabs + Kokoro TTS; README provider matrix + "add a provider" guide
• Done v0.3 — Twilio telephony integration: inbound/outbound calls, concurrent, call history
• Planned v0.4 — Configurable agent personas (system prompt, tools)
• Planned v1.0 — Production-ready, documented, examples