# Agnost Conversation SDK

[![PyPI version](https://badge.fury.io/py/agnost-conversation.svg)](https://badge.fury.io/py/agnost-conversation)
[![Python](https://img.shields.io/pypi/pyversions/agnost-conversation.svg)](https://pypi.org/project/agnost-conversation/)

Python SDK for tracking AI conversations and events. Monitor your AI agent interactions, track user conversations, and gain insights into how your AI applications are performing.

## Installation

```bash
pip install agnost
```

## Basic Usage

```python
import agnost

# Initialize with your write key
agnost.init("your-write-key")

# Track an AI interaction
agnost.track_ai(
    user_id="user_123",
    event="chat_completion",
    input="What is the weather?",
    output="The weather is sunny.",
    agent_name="weather-agent"
)
```

## API Reference

### `init(write_key, **config)`

Initialize the SDK with your write key.

```python
agnost.init("your-write-key")

# With custom configuration
agnost.init(
    "your-write-key",
    endpoint="https://api.agnost.ai",
    debug=True
)
```

### `track_ai(user_id, event, ...)`

Record an AI interaction event.

```python
event_id = agnost.track_ai(
    user_id="user_123",         # Required: User identifier
    event="chat_completion",     # Required: Event name
    input="What is the weather?",
    output="The weather is sunny.",
    agent_name="weather-agent",
    convo_id="conv_abc",         # Group related events
    properties={"temperature": "0.7"},
    latency=1500                 # Execution time in ms
)
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | `str` | Yes | User identifier |
| `event` | `str` | Yes | Event name |
| `input` | `str` | No | Input text/prompt |
| `output` | `str` | No | Output/response text |
| `agent_name` | `str` | No | Agent name (e.g., "weather-agent", "support-bot") |
| `convo_id` | `str` | No | Conversation ID for grouping |
| `properties` | `dict` | No | Additional event properties |
| `timestamp` | `datetime` | No | Event timestamp (defaults to now) |
| `success` | `bool` | No | Whether successful (default: `True`) |
| `latency` | `int` | No | Execution time in milliseconds |

### `identify(user_id, traits)`

Associate user characteristics with a user ID.

```python
agnost.identify("user_123", {
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30,
    "plan": "paid"
})
```

### `begin(user_id, event, ...)`

Begin a partial interaction for deferred completion. Use this when the output is not immediately available.

```python
interaction = agnost.begin(
    user_id="user_123",
    event="chat_completion",
    agent_name="weather-agent"
)

interaction.set_input("What is the weather?")
interaction.set_property("temperature", "0.7")

# ... do async work ...

interaction.finish(
    output="The weather is sunny.",
    latency=1500
)
```

**Interaction Methods:**

| Method | Description |
|--------|-------------|
| `set_input(text)` | Set the input text |
| `set_properties(dict)` | Set multiple properties |
| `set_property(key, value)` | Set a single property |
| `finish(output, success, latency)` | Complete the interaction |

### `flush()`

Manually flush all queued events.

```python
agnost.flush()
```

### `shutdown()`

Shutdown the SDK and flush remaining events.

```python
agnost.shutdown()
```

### `set_debug_logs(enabled)`

Enable or disable debug logging.

```python
agnost.set_debug_logs(True)  # See queued events
```

## Configuration

You can customize the SDK behavior using the configuration object:

```python
import agnost_conversation as agnost
from agnost_conversation import ConversationConfig

# Create a custom configuration
config = ConversationConfig(
    endpoint="https://api.agnost.ai",
    debug=False
)

# Apply the configuration
agnost.init("your-write-key", config=config)
```

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `endpoint` | `str` | `"https://api.agnost.ai"` | API endpoint URL |
| `debug` | `bool` | `False` | Enable debug logging |

## Advanced Usage

### Conversation Tracking

Group related events using `convo_id`:

```python
convo_id = "conv_" + str(uuid.uuid4())

# First message
agnost.track_ai(
    user_id="user_123",
    event="chat_completion",
    input="Hello!",
    output="Hi there! How can I help?",
    agent_name="support-bot",
    convo_id=convo_id
)

# Follow-up message
agnost.track_ai(
    user_id="user_123",
    event="chat_completion",
    input="What's the weather?",
    output="The weather is sunny.",
    agent_name="support-bot",
    convo_id=convo_id
)
```

### Direct Client Instantiation

For multiple clients or advanced use cases:

```python
from agnost_conversation import ConversationClient

client = ConversationClient()
client.init("your-write-key")

client.track_ai(
    user_id="user_123",
    event="chat_completion",
    output="Hello!",
    agent_name="greeting-bot"
)

client.shutdown()
```

### Error Handling

```python
# Track failed interactions
agnost.track_ai(
    user_id="user_123",
    event="chat_completion",
    input="Generate an image",
    success=False,
    agent_name="image-agent",
    properties={"error": "Rate limit exceeded"}
)
```

## Contact

For support or questions, contact the founders: [founders@agnost.ai](mailto:founders@agnost.ai)
