# Voni AI Python SDK

The official Python SDK for the [Voniai](https://voni.dev) programmable AI infrastructure.

## Installation

```bash
pip install voniai
```

## Quick Start (Headless Mode)

```python
from voniai import Voni

# Initialize the client (automatically loads VONI_API_KEY from env)
voni = Voni()

# Send a message to your co-pilot
response = voni.chat.send_message(
    project_id="your_project_id",
    message="How do I integrate Voni?",
    session_id="user_123"
)

print(f"AI Response: {response['message']}")
```

## Features

- **Robust Security**: Automatic HMAC-SHA256 request signing.
- **Environment Support**: Automatically loads `VONI_API_KEY` from environment variables.
- **Project Management**: Create and configure projects programmatically.
- **Headless Chat**: Interact with the AI engine directly without using the pre-built widget.
- **Webhook Management**: Register and manage webhooks for event-driven workflows.

## Authentication

Voni uses an API Key + HMAC Signature for all requests. The SDK handles this automatically. You can provide your API Key during initialization or set the `VONI_API_KEY` environment variable.

```python
# Option 1: Load from environment (Recommended)
voni = Voni()

# Option 2: Explicitly provide key
voni = Voni(api_key="...")
```

## Error Handling

```python
from voniai import Voni, VoniAuthError, VoniApiError

try:
    projects = voni.projects.list()
except VoniAuthError:
    print("Authentication failed. Check your API Key.")
except VoniApiError as e:
    print(f"API returned an error: {e.status_code}")
```

## License

MIT
