Metadata-Version: 2.2
Name: alura-ai
Version: 0.3.1
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)
```

## Customer Management

Create and manage customers (accounts) for billing:

```python
from alura import Alura

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

# Create a customer
customer = alura.customers.create(
    name="Acme Corp",
    email="billing@acme.com",
    company_name="Acme Corporation",
    external_id="cust_abc123",
    metadata={"plan": "enterprise"}
)
print(f"Created customer: {customer.id}")

# Get a customer by ID
customer = alura.customers.get(customer_id=123)

# Get a customer by external ID
customer = alura.customers.get_by_external_id(external_id="cust_abc123")

# List all customers
customers = alura.customers.list()
for c in customers:
    print(f"{c.name} - {c.email}")

# Update a customer
updated = alura.customers.update(
    customer_id=123,
    name="Acme Corp Updated",
    phone="+1-555-1234"
)

# Delete a customer (soft delete)
alura.customers.delete(customer_id=123)
```

## Contact Management

Manage contacts for customers:

```python
from alura import Alura

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

# Create a contact for a customer
contact = alura.contacts.create(
    customer_id=123,
    first_name="John",
    last_name="Doe",
    email="john@acme.com",
    phone="+1-555-5678",
    is_primary=True,
    receives_invoices=True
)

# Get a contact by ID
contact = alura.contacts.get(contact_id=456)

# Get a contact by external ID
contact = alura.contacts.get_by_external_id(external_id="contact_xyz")

# List all contacts
contacts = alura.contacts.list()

# List contacts for a specific customer
contacts = alura.contacts.list(customer_id=123)

# Update a contact
updated = alura.contacts.update(
    contact_id=456,
    phone="+1-555-9999",
    is_primary=False
)

# Delete a contact
alura.contacts.delete(contact_id=456)
```

## Order Management

Create and manage orders (subscriptions linking customers to agents):

```python
from alura import Alura
from datetime import date

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

# Create an order
order = alura.orders.create(
    customer_id=123,
    agent_code="sales-agent",
    billing_frequency="monthly",
    seat_count=5,
    start_date=date.today(),
    external_id="order_12345"
)
print(f"Created order: {order.order_number}")

# Get an order by ID
order = alura.orders.get(order_id=789)

# List all orders
orders = alura.orders.list()

# List orders for a specific customer
orders = alura.orders.list(customer_id=123)

# Activate an order
activated = alura.orders.activate(order_id=789)

# Update an order
updated = alura.orders.update(
    order_id=789,
    seat_count=10
)

# Delete an order
alura.orders.delete(order_id=789)
```

## Data Models

The SDK provides dataclasses for type-safe responses:

```python
from alura import Customer, Contact, Order, Address, Signal

# Customer fields
customer = Customer(
    id=123,
    name="Acme Corp",
    email="billing@acme.com",
    company_name="Acme Corporation",
    phone="+1-555-1234",
    external_id="cust_abc123",
    billing_address=Address(
        line_1="123 Main St",
        city="San Francisco",
        state="CA",
        zip_code="94102",
        country="US"
    ),
    metadata={"plan": "enterprise"},
    is_active=True
)

# Contact fields
contact = Contact(
    id=456,
    customer_id=123,
    first_name="John",
    last_name="Doe",
    email="john@acme.com",
    is_primary=True,
    receives_invoices=True
)
print(contact.full_name)  # "John Doe"

# Order fields
order = Order(
    id=789,
    order_number="ORD-001",
    customer_id=123,
    agent_code="sales-agent",
    status="active",
    billing_frequency="monthly",
    seat_count=5
)
```

## API Reference

### Client

#### `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.

### Usage Tracking

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

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

### Customers

#### `alura.customers.create(name, email, ...)`
Create a new customer. Returns `Customer`.

#### `alura.customers.get(customer_id)`
Get customer by ID. Returns `Customer`.

#### `alura.customers.get_by_external_id(external_id)`
Get customer by external ID. Returns `Customer`.

#### `alura.customers.list()`
List all customers. Returns `List[Customer]`.

#### `alura.customers.update(customer_id, ...)`
Update a customer. Returns `Customer`.

#### `alura.customers.delete(customer_id)`
Soft-delete a customer.

### Contacts

#### `alura.contacts.create(customer_id, first_name, last_name, email, ...)`
Create a new contact. Returns `Contact`.

#### `alura.contacts.get(contact_id)`
Get contact by ID. Returns `Contact`.

#### `alura.contacts.get_by_external_id(external_id)`
Get contact by external ID. Returns `Contact`.

#### `alura.contacts.list(customer_id=None)`
List contacts, optionally filtered by customer. Returns `List[Contact]`.

#### `alura.contacts.update(contact_id, ...)`
Update a contact. Returns `Contact`.

#### `alura.contacts.delete(contact_id)`
Soft-delete a contact.

### Orders

#### `alura.orders.create(customer_id, agent_code, ...)`
Create a new order. Returns `Order`.

#### `alura.orders.get(order_id)`
Get order by ID. Returns `Order`.

#### `alura.orders.list(customer_id=None)`
List orders, optionally filtered by customer. Returns `List[Order]`.

#### `alura.orders.activate(order_id)`
Activate an order. Returns `Order`.

#### `alura.orders.update(order_id, ...)`
Update an order. Returns `Order`.

#### `alura.orders.delete(order_id)`
Soft-delete an order.

### OpenAI Wrapper

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

## License

MIT License
