Metadata-Version: 2.2
Name: alura-ai
Version: 0.1.2
Summary: AI usage tracking and billing SDK
Author-email: Alura AI <support@aluraai.com>
Project-URL: Homepage, https://aluraai.com
Project-URL: Documentation, https://aluraai.com/docs
Project-URL: Repository, https://github.com/alura-ai/alura-python
Project-URL: Issues, https://github.com/alura-ai/alura-python/issues
Keywords: ai,llm,tracking,billing,openai,usage,cost
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# Alura AI Python SDK

Track AI usage and costs with automatic billing integration.

## Installation

```bash
pip install alura-ai
```

With OpenAI support:
```bash
pip install alura-ai[openai]
```

## Quick Start

### Automatic OpenAI Tracking

```python
from alura import Alura, AluraOpenAI
from openai import OpenAI

# Initialize clients
alura = Alura(api_key="your-alura-api-key")
openai_client = OpenAI(api_key="your-openai-key")
alura_openai = AluraOpenAI(openai_client, alura)

# All calls within trace() are automatically tracked
with alura.trace(customer_id="cust-123", agent_id="my-chatbot"):
    response = alura_openai.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}]
    )
```

### Manual Signal Tracking

```python
from alura import Alura

alura = Alura(api_key="your-alura-api-key")

# Track any event
alura.signal(
    event_name="meeting_booked",
    agent_id="sales-agent",
    customer_id="cust-123",
    data={
        "meeting_type": "demo",
        "duration_minutes": 30
    }
)
```

### Bulk Signal Recording

```python
from alura import Alura, Signal

alura = Alura(api_key="your-alura-api-key")

signals = [
    Signal(
        event_name="email_sent",
        agent_id="outreach-agent",
        customer_id="cust-123",
        data={"recipient": "user@example.com"}
    ),
    Signal(
        event_name="call_made",
        agent_id="outreach-agent",
        customer_id="cust-123",
        data={"duration_seconds": 120}
    ),
]

alura.signal_bulk(signals)
```

## API Reference

### `Alura(api_key, base_url)`
Main client for Alura API.

### `alura.trace(customer_id, agent_id)`
Context manager for tracing calls. All AluraOpenAI calls within are auto-tagged.

### `alura.signal(event_name, agent_id, data, customer_id)`
Record a single signal/event.

### `alura.signal_bulk(signals)`
Record multiple signals in one request.

### `AluraOpenAI(openai_client, alura_client)`
OpenAI wrapper with automatic tracking.

## License

MIT License

