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

# Basic Usage

> Basic usage patterns for the Lumina Python SDK

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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="Advanced Usage" href="/docs/sdk/python/advanced-usage">
    Multi-span tracing and async patterns
  </Card>

  <Card title="API Reference" href="/docs/sdk/python/api-reference">
    Complete API docs
  </Card>
</CardGroup>