Skip to main content
Common patterns for using the Lumina Python SDK.

​
Single LLM Call

Wrap any LLM call with trace_llm to capture model, tokens, cost, and latency automatically: 
import openai
from lumina import init_lumina

client = openai.OpenAI()
lumina = init_lumina({"endpoint": "http://localhost:9411/v1/traces", "service_name": "my-app"})

response = lumina.trace_llm(
    lambda: client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}],
    ),
    name="chat-completion",
    system="openai",
    prompt="Hello!",
)

print(response.choices[0].message.content)
The same pattern works for Anthropic: 
import anthropic
from lumina import init_lumina

client = anthropic.Anthropic()
lumina = init_lumina({"endpoint": "http://localhost:9411/v1/traces", "service_name": "my-app"})

response = lumina.trace_llm(
    lambda: client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello!"}],
    ),
    name="chat-completion",
    system="anthropic",
    prompt="Hello!",
)

print(response.content[0].text)

​
Adding Metadata

Attach structured metadata and tags to any trace for filtering and grouping in the dashboard: 
response = lumina.trace_llm(
    lambda: client.chat.completions.create(model="gpt-4", messages=messages),
    name="chat",
    metadata={
        "user_id": "user-123",
        "session_id": "session-456",
        "feature": "support-chat",
    },
    tags=["production", "support"],
)

​
Async Usage

trace_llm automatically detects async callables and awaits them — no separate async method needed: 
import asyncio
import openai
from lumina import init_lumina

client = openai.AsyncOpenAI()
lumina = init_lumina({"endpoint": "http://localhost:9411/v1/traces", "service_name": "my-app"})

async def main():
    response = await lumina.trace_llm(
        lambda: client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": "Hello!"}],
        ),
        name="chat-completion",
        system="openai",
    )
    print(response.choices[0].message.content)

asyncio.run(main())

​
Error Handling

Errors are automatically recorded on the span. Re-raise to propagate them normally: 
try:
    response = lumina.trace_llm(
        lambda: client.chat.completions.create(model="gpt-4", messages=messages),
        name="chat",
        system="openai",
    )
except openai.APIError as e:
    # Error is already recorded on the span
    print(f"LLM call failed: {e}")
    raise

​
Next Steps

Advanced Usage

Multi-span tracing and async patterns

API Reference

Complete API docs