Metadata-Version: 2.4
Name: llmtracer-sdk
Version: 1.0.0
Summary: Track cost, latency, and usage across all your LLM providers.
Author-email: LLM Tracer <hello@llmtracer.dev>
License: MIT
Project-URL: Homepage, https://llmtracer.dev
Project-URL: Documentation, https://llmtracer.dev/docs
Project-URL: Repository, https://github.com/llmtracer/llmtracer-python
Keywords: llm,observability,cost-tracking,langchain,openai,anthropic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2.0; extra == "langchain"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
Provides-Extra: google
Requires-Dist: google-genai>=1.0.0; extra == "google"
Provides-Extra: all
Requires-Dist: langchain-core>=0.2.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.20.0; extra == "all"
Requires-Dist: google-genai>=1.0.0; extra == "all"

# LLM Tracer — Python SDK

Track cost, latency, and usage across **all** your LLM providers in one dashboard.

Works with OpenAI, Anthropic, Google, and any provider accessible through LangChain.

## Install

```bash
pip install llmtracer
```

## Quick Start — LangChain (recommended)

One callback handler captures every LLM call in your chain or agent, regardless of provider.

```python
from llmtracer import LLMTracerCallbackHandler

tracer = LLMTracerCallbackHandler(
    api_key="lt_...",            # Get from llmtracer.dev/settings
    tags={"env": "production"}   # Global tags on every event
)

# Add to any chain, agent, or runnable:
result = await chain.ainvoke(
    input_data,
    config={"callbacks": [tracer]}
)
```

That's it. Every LLM call — ChatOpenAI, ChatAnthropic, ChatGoogleGenerativeAI — is automatically tracked with model, tokens, cost, and latency.

View your dashboard at [llmtracer.dev](https://llmtracer.dev).

## Per-Call Tags

Tag individual calls to track cost by feature, user, or customer:

```python
result = await agent.ainvoke(
    input_data,
    config={
        "callbacks": [tracer],
        "metadata": {
            "llmtracer_tags": {
                "feature": "chat",
                "user_id": "u_sarah",
                "customer": "acme-corp",
            }
        }
    }
)
```

### Tagging Patterns

| Pattern | Tag | Example |
|---------|-----|---------|
| Track cost by feature | `feature` | `"chat"`, `"search"`, `"summarize"` |
| Track cost by user | `user_id` | `"u_sarah"`, `"u_mike"` |
| Track cost by customer (B2B) | `customer` | `"acme-corp"`, `"initech"` |
| Track cost by conversation | `conversation_id` | `"conv_abc123"` |
| Track environment | `env` | `"production"`, `"staging"` |

## Quick Start — Direct (no LangChain)

If you're calling provider SDKs directly:

```python
from llmtracer import LLMTracer
from openai import OpenAI

tracer = LLMTracer(api_key="lt_...", tags={"env": "production"})

client = OpenAI()
tracer.instrument_openai(client)

# All calls are now tracked automatically
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    llmtracer={"tags": {"feature": "chat"}}  # optional per-call tags
)
```

### Multi-provider

```python
from openai import OpenAI
from anthropic import Anthropic

tracer = LLMTracer(api_key="lt_...", tags={"env": "production"})

openai_client = OpenAI()
anthropic_client = Anthropic()

tracer.instrument_openai(openai_client)
tracer.instrument_anthropic(anthropic_client)

# Both are now tracked in the same dashboard
```

## Supported Providers

| Provider | LangChain Callback | Direct Instrumentor |
|----------|-------------------|---------------------|
| OpenAI | ✅ | ✅ |
| Anthropic | ✅ | ✅ |
| Google GenAI | ✅ | ✅ |
| Azure OpenAI | ✅ | Coming soon |
| AWS Bedrock | ✅ | Coming soon |
| Any LangChain LLM | ✅ | — |

## Configuration

```python
tracer = LLMTracerCallbackHandler(
    api_key="lt_...",           # Required — from llmtracer.dev/settings
    tags={"env": "production"}, # Optional — global tags
    flush_interval=5.0,         # Seconds between batch flushes (default: 5)
    batch_size=50,              # Events per batch (default: 50)
    enabled=True,               # Set False to disable without removing code
)
```

### Environment variable pattern

```python
import os
tracer = LLMTracerCallbackHandler(
    api_key=os.environ["LLMTRACER_API_KEY"],
    tags={"env": os.environ.get("ENVIRONMENT", "development")},
    enabled=os.environ.get("LLMTRACER_ENABLED", "true").lower() == "true",
)
```

## How It Works

1. The callback handler hooks into LangChain's `on_chat_model_start` / `on_llm_end` lifecycle
2. It captures: model name, provider, input/output tokens, latency, success/failure
3. Events are buffered in memory and flushed every 5 seconds (or at batch_size)
4. Flush happens in a background thread — **zero latency impact** on your LLM calls
5. Events are POSTed to the LLM Tracer Cloud Function which calculates cost server-side

## Zero Dependencies

The core SDK uses only Python stdlib (`urllib.request`, `threading`, `hashlib`).

LangChain callback mode requires `langchain-core` (which you already have if you're using LangChain).

## License

MIT
