Metadata-Version: 2.4
Name: tokenlens
Version: 0.2.0
Summary: Track and optimize your LLM spend — find duplicates, wasted tokens, and cost savings.
Author-email: PrAry Soft <support@tokenlens.co>
License: MIT
Project-URL: Homepage, https://tokenlens.co
Project-URL: Documentation, https://tokenlens.co/help
Project-URL: Repository, https://github.com/prarysoft/tokenlens-python
Project-URL: Issues, https://github.com/prarysoft/tokenlens-python/issues
Keywords: llm,openai,anthropic,cost,observability,tokens,ai,monitoring
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.8
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
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == "anthropic"
Provides-Extra: litellm
Requires-Dist: litellm>=1.0; extra == "litellm"
Provides-Extra: all
Requires-Dist: openai>=1.0; extra == "all"
Requires-Dist: anthropic>=0.20; extra == "all"
Requires-Dist: litellm>=1.0; extra == "all"
Dynamic: license-file

# TokenLens Python SDK

Track and optimize your LLM spend. Find duplicate prompts, wasted tokens, and cost savings — automatically.

## Install

```bash
pip install tokenlens
```

## Quick Start (2 lines)

```python
import tokenlens
tokenlens.init(api_key="tl_...")  # Get your key at tokenlens.co/app → Account

# All OpenAI and Anthropic calls are now tracked automatically.
# No other code changes needed.
```

## How It Works

The SDK patches the OpenAI and Anthropic Python clients to capture usage metadata (model, token counts, prompt hashes) after every completion call. Events are batched in the background and sent to your TokenLens dashboard every 30 seconds.

**What's captured:** model name, token counts, prompt text (for duplicate detection), cost, timestamps.

**What's NOT captured:** API keys, response content beyond the first 2KB, any data outside of LLM calls.

## With OpenAI

```python
import tokenlens
tokenlens.init(api_key="tl_...")

from openai import OpenAI
client = OpenAI()

# This call is automatically tracked
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarize this article"}]
)
```

## With Anthropic

```python
import tokenlens
tokenlens.init(api_key="tl_...")

import anthropic
client = anthropic.Anthropic()

# This call is automatically tracked
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)
```

## With LiteLLM

```python
import litellm
from tokenlens.litellm_callback import TokenLensCallback

litellm.callbacks = [TokenLensCallback(api_key="tl_...")]

# Every litellm.completion() call is now tracked
response = litellm.completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)
```

### LiteLLM Proxy (config.yaml)

```yaml
litellm_settings:
  callbacks:
    - tokenlens

environment_variables:
  TOKENLENS_API_KEY: "tl_..."
```

## Manual Tracking

For custom LLM clients or pre-computed metrics:

```python
import tokenlens
tokenlens.init(api_key="tl_...")

tokenlens.track(
    model="gpt-4o",
    prompt="Summarize the quarterly report",
    tokens_in=150,
    tokens_out=500,
    cost=0.0035,
    caller_tag="report-service",
)
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `TOKENLENS_API_KEY` | Your API key (alternative to passing `api_key=`) |
| `TOKENLENS_API_BASE` | Custom API endpoint (default: `https://tokenlens.co`) |

## Configuration

```python
tokenlens.init(
    api_key="tl_...",
    auto_patch=True,       # Patch OpenAI/Anthropic automatically (default: True)
    batch_size=50,         # Events per batch (default: 50)
    flush_interval=30,     # Seconds between flushes (default: 30)
    debug=False,           # Enable debug logging (default: False)
)
```

## SDK Stats

```python
print(tokenlens.stats())
# {'queued': 3, 'total_sent': 147, 'total_errors': 0}
```

## Graceful Shutdown

Events are flushed automatically on process exit. For explicit control:

```python
tokenlens.flush()     # Send all pending events now
tokenlens.shutdown()  # Flush and stop background thread
```

## Privacy

- Prompt text is sent for duplicate detection (hashed on our servers, never stored in plain text)
- Completion text is capped at 2KB and used only for quality analysis
- No API keys, secrets, or credentials are ever captured
- All data is encrypted in transit (HTTPS/TLS)
- Data is scoped to your team — never shared across accounts

## Requirements

- Python 3.8+
- No required dependencies (works standalone)
- Optional: `openai>=1.0`, `anthropic>=0.20`, `litellm>=1.0`

## Links

- [TokenLens Dashboard](https://tokenlens.co)
- [Documentation](https://tokenlens.co/help)
- [Report Issues](https://github.com/prarysoft/tokenlens-python/issues)

## License

MIT
