> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracelm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> TraceLM Python SDK: tracing, task lifecycle, reliability detection, and conversation context

Official Python SDK for reliability-first observability in production agents.

## Install

```bash theme={null}
pip install tracelm
```

## Quick Start

```python theme={null}
from tracelm import TraceLM

tracelm = TraceLM(
    api_key="lt_your_tracelm_key",
    openai_api_key="sk-your-openai-key",
)

response = tracelm.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
```

## Providers

`TraceLM` supports `provider="openai" | "anthropic" | "google"` and can route through `/v1/chat/completions` with provider-normalized behavior.

You can also use provider-specific clients:

* `AnthropicTraceLM`
* `GeminiTraceLM`

## Reliability-First Onboarding

1. Create project + API key.
2. Send one traced request.
3. Open `/dashboard/first-run`.
4. Confirm your first reliability signal.

## Task Grouping + Detection

```python theme={null}
with tracelm.task(name="booking_flow", user_id="user_123") as task:
    tracelm.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Book a flight"}],
    )

    result = task.complete()  # run_detection=True by default

    if result:
        print(result.loops.detected)
        print(result.failures.explicit)
        print(result.context.total)
        print(result.tool_failure_count)
        print(result.context_failure_count)
```

## Manual Detection (No Completion)

```python theme={null}
detection = task.detect()
print(detection.loops.patterns)
print(detection.failures.semantic)
print(detection.context.lost_context)
```

## Conversation Tracking

```python theme={null}
with tracelm.conversation(user_id="user_123", session_id="sess_1") as conv:
    with conv.task(name="turn_1") as task:
        tracelm.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hi"}])
        task.complete()
```

## Query APIs

```python theme={null}
tasks = tracelm.list_tasks(has_issues=True)
item = tracelm.get_task("task-uuid")
convs = tracelm.list_conversations(user_id="user_123")
failures = tracelm.get_conversation_context_failures("conv-uuid")
```

Use these queries to move from individual traces to execution-level diagnosis.

## Environment Variables

```bash theme={null}
TRACELM_API_KEY=lt_...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
TRACELM_BASE_URL=https://api.tracelm.ai
```

## Notes

* `task.complete()` returns `None` if the backend task record does not exist yet.
* Use `run_detection=False` for completion without re-running detection.
* Detection results are stored in task metadata under `detection_results`.