Chakra ConvAI
Chakra ConvAI (chakra-convai, formerly chakra-ivr-core) is the licensed engine that runs a Chakra Labs conversational agent: on a phone line, as web voice with the user's camera, or as a typed chat. You write only what is specific to your service: what the agent says, the tools it can call, and a settings file. The engine runs the session.
What the SDK Does vs. What You Provide
| The SDK does this for you | You provide this |
|---|---|
| Answers calls through LiveKit and runs the whole call | chakra.toml: your settings |
| Speech in and out, on Chakra Voice or Gemini Live | config/instructions.json: persona, rules, flows, and spoken lines |
| Builds the system prompt from your configuration | skills/: Python classes holding your tools |
| Greets callers and remembers returning ones | .env: your licence key and other secrets |
| Handles silence, maximum call length, and daily talk-time limits | data/: documents for the knowledge base (optional) |
| Searches your knowledge base (RAG) | hooks.py: custom behavior (optional) |
| Records calls, feedback, and transcripts in your PostgreSQL database | Database schema & migration logic |
| Reports usage to the Chakra Console | Business analytics |
The package is delivered compiled, without Python source, and runs only with a valid licence key from Chakra Labs.
Before You Start
From Chakra Labs
| Item | What it is | Where it goes |
|---|---|---|
| Install token | Read-only access to the private package index | FURY_DEPLOY_TOKEN, at install and build time only |
| Licence key | Starts with chk_live_. Identifies your company and package |
CHAKRA_LICENSE_KEY, at run time in .env |
| Chakra Console sign-in | An email and password for your company's dashboard | Your web browser |
Treat the install token and the licence key as secrets. Keep them in a secrets manager or CI secret store, never in source code.
Your Own Infrastructure
- Python 3.12 on Linux x86_64: The package is built for this platform only. On Windows or macOS, develop inside Docker or WSL.
- A LiveKit project: Connects your phone number or web app to the agent. You need its URL, API key, and API secret.
- A Google API key: If you use the Gemini Live pipeline or the knowledge base (creates search embeddings).
- A PostgreSQL database (optional, recommended): Without one the agent still takes calls, but caller memory, call records, and daily talk-time limits are off.
Quick Navigation
- Getting Started: Installation and initializing your first agent.
- Channels (Phone, Web, Chat): Configure SIP phone, web voice/video, and text chat.
- Voice Pipelines: Overview of
chakramanaged vsgemini_liverealtime voice. - Configuration Reference: Complete guide to
chakra.tomland.envsettings. - Prompts & Instructions: Defining personas, flows, and multilingual spoken lines.
- Building Skills: Creating custom tools and skills with
BaseSkill. - Application Hooks: Customizing call lifecycle and database tables.
- Built-in Features & DB: Caller memory, silence handling, call duration limits, and schema.
- Knowledge Base (RAG): Ingesting documents, embeddings, and Admin API.
- CLI Reference: Commands for local development, verification, and debugging.
- Admin Console: Monitoring usage, setting talk-time limits, and voice cloning.
- Licensing & Limits: Cryptographic verification, quotas, and billing.
- Testing & Deployment: Unit testing, Docker builds, and production checklists.
- Troubleshooting: Diagnosing and resolving common runtime issues.
- Python API Reference: Dynamic docstring reference for the public API.