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-5-5",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=1024,
)

Production-test traffic and public insight evidence

Pass an opaque session token to converra.wrap(client, session_id=token) when serving user traffic during a production test. Use traffic_type="background", "eval", or "batch" for other calls so they stay outside the test. Wrappers with capture_enabled=False default to background traffic; an explicit traffic_type takes precedence.

get_run_insights(run_id) preserves the public response's terminal_state, terminal_reason, conversation_findings, claim_state, artifacts, artifact_evaluation_coverage, human_review, and active_publication fields. generation_status describes an in-progress retry even when an earlier insight publication remains available. Fields absent on older responses are None; empty findings and unavailable evidence remain distinct.

Requirements

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

License

MIT