Metadata-Version: 2.4
Name: converra
Version: 0.3.0
Summary: Converra SDK — conversation capture, optimization, and A/B testing for AI agents
License-Expression: MIT
Requires-Python: >=3.9
Requires-Dist: httpx<1.0,>=0.24.0
Provides-Extra: all
Requires-Dist: anthropic>=0.20; extra == 'all'
Requires-Dist: langchain-core>=0.1; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1; extra == 'langchain'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Description-Content-Type: text/markdown

# converra

Official Python SDK for [Converra](https://converra.io) — the AI agent optimization platform.

## Installation

```bash
pip install converra
```

With provider support:

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

## Quick Start

```python
from converra import Converra

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

# Log a conversation — one method, handles everything
await 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.

```python
from converra import Converra, ConversationMessage, SendInput

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

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

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

# Append more turns
await 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:

```python
await 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:

```python
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:

```python
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

```python
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

```python
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](https://converra.ai/settings))

## License

MIT
