Documentation Index
Fetch the complete documentation index at: https://docs.uselumina.io/docs/llms.txt
Use this file to discover all available pages before exploring further.
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)
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)
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
