Metadata-Version: 2.4
Name: tokoscope
Version: 0.2.0
Summary: Audit, compress and monitor your LLM token usage in 2 lines of code
Author-email: Tokoscope <hello@tokoscope.com>
License: MIT
Project-URL: Homepage, https://tokoscope.com
Project-URL: Documentation, https://app.tokoscope.com/onboarding
Project-URL: Repository, https://github.com/tokoscope/sdk
Project-URL: Bug Tracker, https://github.com/tokoscope/sdk/issues
Keywords: llm,openai,anthropic,tokens,optimization,cost,monitoring,prompt,compression,ai,token-usage,llm-cost,observability,gpt,claude
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Dynamic: license-file

# Tokoscope Python SDK

> Audit, compress, and monitor your LLM token usage in 2 lines of code.

[![PyPI version](https://img.shields.io/pypi/v/tokoscope?color=00E5A0&style=flat-square)](https://pypi.org/project/tokoscope/)
[![PyPI downloads](https://img.shields.io/pypi/dm/tokoscope?color=00E5A0&style=flat-square)](https://pypi.org/project/tokoscope/)
[![License: MIT](https://img.shields.io/badge/License-MIT-00E5A0.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-00E5A0.svg?style=flat-square)](https://www.python.org/)

Tokoscope sits between your app and any LLM API. It tracks every call, scores your prompts for waste, compresses bloated inputs automatically, and shows you exactly where your token budget is going.

**Works with OpenAI and Anthropic out of the box.**

---

## Installation

```bash
pip install tokoscope
```

---

## Quick start

### OpenAI

```python
from openai import OpenAI
from tokoscope import wrap

client = wrap(OpenAI(), api_key="ts_live_...")  # get your key at app.tokoscope.com

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

print(response.choices[0].message.content)
```

### Anthropic

```python
from anthropic import Anthropic
from tokoscope import wrap

client = wrap(Anthropic(), api_key="ts_live_...")

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

print(response.content[0].text)
```

That's it. Every API call is now tracked automatically.

---

## Real example

**Original prompt:** 113 tokens

```
Please note that it is very important that you make sure to respond
to my question. As an AI, I want you to please make sure that you
understand that I need you to help me...
What is the capital of France?
```

**Tokoscope compressed:** 8 tokens

```
What is the capital of France? Answer concisely.
```

**Result:** 90% token reduction. Same answer.

---

## What you get

Once integrated, your [Tokoscope dashboard](https://app.tokoscope.com) shows:

- **Token usage** broken down by model, endpoint, and provider
- **Cost per request** calculated automatically using current pricing
- **Waste score** for every prompt
- **Auto-compression** — prompts with high waste scores are automatically rewritten
- **Budget alerts** — get notified before costs spike

---

## Supported providers

| Provider | Status |
|---|---|
| OpenAI | ✅ Supported |
| Anthropic | ✅ Supported |
| Gemini | 🔜 Coming soon |
| Mistral | 🔜 Coming soon |

---

## Requirements

- Python 3.8+
- `requests` library (installed automatically)

---

## License

MIT

---

## Links

- [Website](https://tokoscope.com)
- [Dashboard](https://app.tokoscope.com)
- [JavaScript SDK](https://www.npmjs.com/package/tokoscope)
- [Contact](mailto:hello@tokoscope.com)
