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

# Python SDK

> Track LLM costs in Python applications

## Installation

Install the SDK from PyPI using pip:

```bash theme={null}
pip install costrace-sdk
```

This installs the core SDK with no provider dependencies. To include the provider libraries you need, use extras:

<CodeGroup>
  ```bash OpenAI theme={null}
  pip install costrace-sdk[openai]
  ```

  ```bash Anthropic theme={null}
  pip install costrace-sdk[anthropic]
  ```

  ```bash Google Gemini theme={null}
  pip install costrace-sdk[gemini]
  ```

  ```bash All Providers theme={null}
  pip install costrace-sdk[all]
  ```
</CodeGroup>

If you already have a provider SDK installed (e.g. `openai`, `anthropic`, or `google-genai`), the base `pip install costrace-sdk` is all you need — Costrace will detect and patch any installed providers automatically.

<Note>
  Requires **Python 3.8 or higher**.
</Note>

## How It Works

Costrace uses **monkey-patching** to wrap your existing LLM client methods. When you call `costrace.init()`, it automatically patches the clients for any installed providers — no code changes needed on your end.

Every LLM call is intercepted to capture token usage, latency, and cost, then a trace is sent to the Costrace backend in a **background thread** so your application is never blocked.

## Quick Start

```python theme={null}
import costrace
import openai

# Initialize Costrace once at startup — before creating any LLM clients
costrace.init(api_key="ct_your_api_key")

# Use OpenAI as you normally would — all calls are automatically tracked
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
```

<Warning>
  You must call `costrace.init()` **before** creating any LLM client instances. The SDK patches client constructors, so clients created before initialization won't be tracked.
</Warning>

## Configuration

### Custom Endpoint

Point to a self-hosted or local backend:

```python theme={null}
costrace.init(
    api_key="ct_your_api_key",
    endpoint="https://your-backend.com/v1/traces"
)
```

## Supported Providers

### OpenAI

```python theme={null}
import costrace
import openai

costrace.init(api_key="ct_your_api_key")

client = openai.OpenAI(api_key="sk-...")
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
```

**Supported Models:**

* GPT-5 family: `gpt-5.2`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`
* GPT-4 family: `gpt-4o`, `gpt-4o-mini`, `gpt-4.1`, `gpt-4-turbo`, `gpt-4`
* GPT-3.5: `gpt-3.5-turbo`
* Other: `o3`, `o4-mini`

### Anthropic

```python theme={null}
import costrace
import anthropic

costrace.init(api_key="ct_your_api_key")

client = anthropic.Anthropic(api_key="sk-ant-...")
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
```

**Supported Models:**

* Opus: `claude-opus-4-6`, `claude-opus-4-1-20250805`, `claude-opus-4-20250514`
* Sonnet: `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-sonnet-4-20250514`, `claude-3-7-sonnet-20250219`
* Haiku: `claude-haiku-4-5-20251001`, `claude-3-haiku-20240307`

### Google Gemini

```python theme={null}
import costrace
from google import genai

costrace.init(api_key="ct_your_api_key")

client = genai.Client(api_key="AIza...")
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="Hello",
)
```

**Supported Models:**

* Gemini 2.0: `gemini-2.0-flash`, `gemini-2.0-flash-lite`
* Gemini 1.5: `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-1.5-flash-8b`

## What Gets Tracked

Every LLM API call sends a trace containing:

```python theme={null}
{
    "provider": "openai",           # openai | anthropic | gemini
    "model": "gpt-4o",
    "tokens_in": 100,               # Prompt tokens
    "tokens_out": 50,               # Completion tokens
    "latency_ms": 1234,             # Time in milliseconds
    "cost_usd": 0.005,              # Calculated cost
    "status": "success",            # success | error
    "api_key": "ct_...",            # Your Costrace API key
    "error": "..."                  # Error message (if status=error)
}
```

Traces are sent in a **background thread** — they don't block your application. The SDK also registers an `atexit` handler to wait up to 10 seconds for any pending traces before your process exits.

## Requirements

* **Python:** 3.8 or higher
* **Core dependency:** `requests` — installed automatically
* **Provider SDKs:** Optional, install only the ones you use

| Extra       | Installs         | Minimum Version |
| ----------- | ---------------- | --------------- |
| `openai`    | `openai`         | `>=2.21.0`      |
| `anthropic` | `anthropic`      | `>=0.82.0`      |
| `gemini`    | `google-genai`   | `>=1.64.0`      |
| `all`       | All of the above | —               |

## Troubleshooting

### No traces appearing in dashboard

1. Check that `costrace.init()` is called **before** creating LLM clients
2. Verify your API key is correct
3. Check for error messages in console output

### Traces not being sent

The SDK silently catches network errors when sending traces. This is intentional — trace failures should never break your application. Check your network connectivity and ensure the Costrace API endpoint is reachable.

### Provider not being tracked

If a provider isn't being tracked, make sure:

1. The provider SDK is installed (e.g. `pip install openai`)
2. `costrace.init()` is called before creating the client instance
3. You're using a supported model from the lists above

## Source Code

GitHub: [github.com/ikotun-dev/costrace](https://github.com/ikotun-dev/costrace)

PyPI: [pypi.org/project/costrace-sdk](https://pypi.org/project/costrace-sdk)