# Cekura Python SDK

**Testing and Observability for AI Voice Agents. Launch in minutes not weeks by ensuring your agents deliver a seamless experience in every conversational scenario.**

## Installation

```bash
pip install cekura
```

## LiveKit Integration

### Setup

1. Create a new agent in the Cekura dashboard
2. Select **LiveKit** as the provider in agent settings
3. Enable tracing for your agent
4. Copy your API key and Agent ID

### Quick Start

```python
import os
from livekit import agents
from cekura.livekit import LiveKitTracer

# Initialize Cekura tracer
cekura = LiveKitTracer(
    api_key=os.getenv("CEKURA_API_KEY"),
    agent_id=123
)

@server.rtc_session(agent_name="my_agent")
async def entrypoint(ctx: agents.JobContext):
    # Create your assistant and session
    assistant = YourAssistant()
    session = agents.AgentSession(...)

    # Track session with Cekura for simulation calls (includes mock tool injection)
    await cekura.track_session(ctx, session, assistant)

    # Send call with audio to Cekura for observability
    await cekura.observe_session(ctx, session)

    # Start your session
    await session.start(room=ctx.room, agent=assistant)
```

### Next Steps

After integrating the SDK, you can:
- Run tests from the Cekura platform
- Monitor real-time conversations
- Analyze performance metrics
- Review conversation transcripts and tool calls

## Features

- **One-Line Integration**: Simple one line API for seamless integration for both simulation calls and observability
- **Automatic Metrics Collection**: Captures STT, LLM, TTS, and End-of-Utterance metrics
- **Dual-Channel Audio Recording**: Records production calls with dual audio channel for analysis
- **Conversation Tracking**: Records complete chat history with tool calls
- **Mock Tool Injection**: Automatically replaces tools with mock versions configured in Cekura dashboard for simulation calls
- **Session Reports**: Generates comprehensive session reports from LiveKit

## Mock Tools

The SDK automatically injects mock tools when running tests from the Cekura platform. Mock tools return predefined responses configured in the dashboard.

**Setup:**
1. Create mock tools in the Cekura dashboard under your agent settings
2. Define input/output pairs for each tool
3. When tests run, the SDK automatically replaces matching tools with mocks

## Configuration

### Parameters

- `api_key` (str, required): Your Cekura API key
- `agent_id` (int, required): Unique identifier for your agent from Cekura dashboard
- `host` (str, optional): API host URL (default: `https://api.cekura.ai`)
- `enabled` (bool, optional): Enable/disable tracer. Defaults to `True` if not set

### Environment Variables

- `CEKURA_TRACING_ENABLED` (default: `"true"`): Enable/disable `track_session()` for simulation calls
- `CEKURA_OBSERVABILITY_ENABLED` (default: `"true"`): Enable/disable `observe_session()` for production call recording
- `CEKURA_MOCK_TOOLS_ENABLED` (default: `"true"`): Enable/disable mock tool injection

## Data Collected

The SDK automatically collects:

- Session start/end timestamps
- Complete conversation transcripts
- Tool/function calls and outputs
- Dual-channel audio recording for production calls
- Performance metrics:
  - Speech-to-Text (STT) latency and duration
  - LLM token usage and timing
  - Text-to-Speech (TTS) generation time
  - End-of-Utterance detection timing
- Room and job information
- Custom metadata

## Requirements

- Python 3.9+
- aiohttp>=3.9.0

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Links

- [Homepage](https://cekura.ai)
- [Documentation](https://docs.cekura.ai)
- [Dashboard](https://dashboard.cekura.ai)

## Support

For support, email support@cekura.ai
