alura-ai 0.3.2

AI usage tracking and billing SDK

Alura AI Python SDK

Track AI usage and costs with automatic billing integration.

Installation

pip install alura-ai

With OpenAI support:

pip install alura-ai[openai]

Quick Start

Automatic OpenAI Tracking

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

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

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": "[e-mail]"}
    ),
    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:

from alura import Alura

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

# Create a customer
customer = alura.customers.create(
    name="Acme Corp",
    email="[e-mail]",
    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="[phone]"
)

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

Contact Management

Manage contacts for customers:

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="[e-mail]",
    phone="[phone]",
    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="[phone]",
    is_primary=False
)

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

Order Management

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

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:

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

# Customer fields
customer = Customer(
    id=123,
    name="Acme Corp",
    email="[e-mail]",
    company_name="Acme Corporation",
    phone="[phone]",
    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="[e-mail]",
    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