# Vuzo Python SDK

Official Python SDK for [Vuzo API](https://vuzo-api.onrender.com) — unified access to OpenAI, Anthropic, and Google models through a single interface.

[![PyPI version](https://badge.fury.io/py/vuzo.svg)](https://badge.fury.io/py/vuzo)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- Single API key for OpenAI, Anthropic (Claude), and Google (Gemini) models
- Streaming and non-streaming chat completions
- Usage tracking and billing management
- API key management
- Full type hints and Pydantic models
- Simple, intuitive interface: `from vuzo import Vuzo`

## Installation

```bash
pip install vuzo
```

## Quick Start

```python
from vuzo import Vuzo

client = Vuzo("vz-sk_your_key_here")

# Simple one-liner
response = client.chat.complete("gpt-4o-mini", "Hello!")
print(response)

# Full chat with details
response = client.chat.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What is 2+2?"}],
    temperature=0.7
)
print(response.choices[0].message.content)
print(f"Tokens used: {response.usage.total_tokens}")
```

## Authentication

Get your API key from the [Vuzo Dashboard](https://vuzo-api.onrender.com). All keys start with `vz-sk_`.

```python
# Pass key directly
client = Vuzo("vz-sk_your_key_here")

# Or use environment variable
import os
os.environ["VUZO_API_KEY"] = "vz-sk_your_key_here"
client = Vuzo()
```

## Available Models

| Model | Provider | Description |
|-------|----------|-------------|
| `gpt-4o` | OpenAI | Flagship GPT-4o |
| `gpt-4o-mini` | OpenAI | Fast & affordable |
| `gpt-4.1` | OpenAI | GPT-4.1 |
| `gpt-4.1-mini` | OpenAI | GPT-4.1 Mini |
| `gpt-4.1-nano` | OpenAI | Cheapest OpenAI option |
| `grok-3` | xAI | Grok 3 (flagship) |
| `grok-3-mini` | xAI | Grok 3 Mini |
| `grok-2` | xAI | Grok 2 |
| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
| `gemini-3-flash` | Google | Gemini 3 Flash |

## Chat Completions

### Non-Streaming

```python
response = client.chat.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Tell me a joke."}
    ],
    temperature=0.8,
    max_tokens=200
)
print(response.choices[0].message.content)
```

### Streaming

```python
for chunk in client.chat.stream(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Write a short poem."}]
):
    print(chunk, end="", flush=True)
print()
```

### Using xAI or Google Models

No extra setup needed — just change the model name:

```python
# xAI Grok
response = client.chat.complete("grok-3-mini", "Explain quantum computing simply.")

# Google Gemini
response = client.chat.complete("gemini-2.0-flash", "What's the weather like on Mars?")
```

## Models

```python
# List all available models
models = client.models.list()
for model in models:
    print(f"{model.id} ({model.provider}) - Input: ${model.input_price_per_million}/M, Output: ${model.output_price_per_million}/M")
```

## Usage & Billing

```python
# Check balance
balance = client.billing.get_balance()
print(f"Balance: ${balance:.4f}")

# Usage summary
summary = client.usage.summary()
print(f"Total requests: {summary.total_requests}")
print(f"Total tokens: {summary.total_tokens:,}")
print(f"Total cost: ${summary.total_vuzo_cost:.4f}")

# Recent usage logs
logs = client.usage.list(limit=10)
for log in logs:
    print(f"{log.model}: {log.total_tokens} tokens — ${log.vuzo_cost:.6f}")

# Daily usage breakdown
daily = client.usage.daily(start_date="2025-01-01", end_date="2025-01-31")
for day in daily:
    print(f"{day.date} | {day.model}: {day.total_requests} requests, {day.input_tokens + day.output_tokens} tokens")

# Transaction history
transactions = client.billing.transactions()
for tx in transactions:
    print(f"{tx.created_at}: {tx.type} ${tx.amount:.4f}")
```

## API Key Management

```python
# List all API keys
keys = client.api_keys.list()
for key in keys:
    print(f"{key.name}: {key.key_prefix}... (active: {key.is_active})")

# Create a new key
new_key = client.api_keys.create("My App Key")
print(f"New key: {new_key.api_key}")

# Delete a key
client.api_keys.delete("key_id_here")
```

## Error Handling

```python
from vuzo import (
    Vuzo,
    AuthenticationError,
    InsufficientCreditsError,
    RateLimitError,
    InvalidRequestError,
    APIError,
)

try:
    response = client.chat.complete("gpt-4o-mini", "Hello!")
except AuthenticationError:
    print("Invalid API key — check your vz-sk_ key")
except InsufficientCreditsError:
    print("Top up your balance at the Vuzo dashboard")
except RateLimitError:
    print("Rate limit hit — slow down requests")
except InvalidRequestError as e:
    print(f"Bad request: {e}")
except APIError as e:
    print(f"API error {e.status_code}: {e}")
```

## Multi-Provider Example

```python
from vuzo import Vuzo

client = Vuzo("vz-sk_your_key_here")

prompt = "Explain neural networks in one sentence."

for model in ["gpt-4o-mini", "grok-3-mini", "gemini-2.0-flash"]:
    response = client.chat.complete(model, prompt)
    print(f"\n{model}:\n{response}")
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `VUZO_API_KEY` | Your Vuzo API key (`vz-sk_...`) |

## Requirements

- Python 3.8+
- `requests >= 2.31.0`
- `pydantic >= 2.0.0`

## Development

```bash
# Clone the repo
git clone https://github.com/AurissoRnD/vuzo-unifai.git
cd vuzo-unifai

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v
```

## License

MIT License — see [LICENSE](LICENSE) for details.

## Links

- [Vuzo Dashboard](https://vuzo-api.onrender.com)
- [API Documentation](https://vuzo-api.onrender.com/docs)
- [GitHub](https://github.com/AurissoRnD/vuzo-unifai)
- [PyPI](https://pypi.org/project/vuzo/)
