converra 0.3.1

Converra SDK — conversation capture, optimization, and A/B testing for AI agents

converra

Official Python SDK for Converra — the AI agent optimization platform.

Installation

pip install converra

With provider support:

pip install converra[openai]      # OpenAI wrapping
pip install converra[anthropic]   # Anthropic wrapping
pip install converra[all]         # All providers

Quick Start

from converra import Converra

converra = Converra(api_key="sk_...")

# Log a conversation — one method, handles everything
converra.send(
    agent="Support Bot",
    messages=[
        {"role": "user", "content": "I need help with my order"},
        {"role": "assistant", "content": "I'd be happy to help!"},
    ],
)

converra.send()

The simplest way to get conversations into Converra. Works with complete conversations or incremental turns.

from converra import Converra, ConversationMessage

converra = Converra(api_key="sk_...")

# Complete conversation
result = converra.send(
    agent="Support Bot",
    messages=[
        {"role": "user", "content": "Hello"},
        {"role": "assistant", "content": "Hi! How can I help?"},
    ],
)

# Incremental turns
result = converra.send(
    agent="Chat Bot",
    messages=[
        {"role": "user", "content": "Hi"},
        {"role": "assistant", "content": "Hello!"},
    ],
    status="active",
)

# Append more turns
converra.send(
    agent="Chat Bot",
    conversation_id=result.conversation_id,
    messages=[
        {"role": "user", "content": "Thanks!"},
        {"role": "assistant", "content": "You're welcome!"},
    ],
    status="completed",  # triggers analysis
)

Enriched messages

Each message can optionally carry per-turn context:

converra.send(
    agent="Support Bot",
    messages=[
        {"role": "user", "content": "What is your return policy?"},
        {
            "role": "assistant",
            "content": "Our return policy allows...",
            "model": "gpt-4o",
            "tool_calls": [{"name": "lookup_policy", "arguments": {"topic": "returns"}}],
            "usage": {"prompt_tokens": 200, "completion_tokens": 85},
            "latency_ms": 1200,
        },
    ],
)

Organizing conversations

Use agent to group by project/workflow and user_id to group by end customer:

converra.send(
    agent="Churn Research Q1",       # groups conversations by research/project
    user_id="customer_acme",         # groups conversations by customer
    messages=[...],
)

You can also use dataclasses instead of dicts:

from converra import ConversationMessage, ToolCall, Usage

messages = [
    ConversationMessage(role="user", content="Hello"),
    ConversationMessage(
        role="assistant",
        content="Hi!",
        model="gpt-4o",
        usage=Usage(prompt_tokens=100, completion_tokens=20),
    ),
]

LLM Client Wrapping

Wrap your LLM client to automatically capture every call:

OpenAI

from converra import Converra
from openai import OpenAI

converra = Converra(api_key="sk_...")
client = converra.wrap(OpenAI())

# Use normally — all calls captured
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

Anthropic

from anthropic import Anthropic

client = converra.wrap(Anthropic())
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=100,
)

Requirements

• Python 3.9+
• A Converra API key (get one here)

License

MIT