# Introduction

Compress LLM prompts to cut costs and improve accuracy.

## What is The Token Company?

The Token Company builds compression models that remove low-signal tokens from LLM prompts before they reach the model. One API call compresses your input — you pass the compressed text to any LLM.

By stripping noise, the LLM spends its attention on the tokens that actually matter — which is why compressed prompts often score higher than uncompressed ones.

## Why compress?

- **Context management** - fit more documents, history, and tool results into your context window
- **Faster inference** - fewer tokens means lower time-to-first-token and faster responses
- **Improve long context accuracy** - removing low-signal tokens helps the model focus on what matters
- **Cut costs** - save 10-50% on LLM API bills, freeing up budget for more usage

## Installation

```bash
pip install the-token-company
```

## Quick example

```python
from thetokencompany import TheTokenCompany

client = TheTokenCompany(api_key="ttc-...")
result = client.compress("Your long prompt text...")

print(result.output)         # compressed text
print(result.tokens_saved)   # tokens removed
print(result.compression_ratio)  # e.g. 3.2x
```

## How it works

1. Send your prompt to the TTC compression API
2. Receive compressed text back
3. Pass the compressed text to any LLM (OpenAI, Claude, Gemini, etc.)

The SDK wraps this into a single function call. For OpenAI and Anthropic, we provide `with_compression()` (Python) and `withCompression()` (TypeScript) wrappers that handle compression automatically.

---

# Quickstart

Get running with The Token Company SDK in 2 minutes.

## 1. Install the SDK

```bash
pip install the-token-company
```

## 2. Get your API key

Token Company is currently invite-only. Request access at https://thetokencompany.com/contact and we'll set you up with an API key.

## 3. Compress your first prompt

```python
from thetokencompany import TheTokenCompany

client = TheTokenCompany(api_key="ttc-...")

result = client.compress(
    "Your long prompt text that needs compression for optimal token usage.",
    aggressiveness=0.2,
)

print(f"Compressed: {result.output}")
print(f"Tokens saved: {result.tokens_saved}")
print(f"Compression ratio: {result.compression_ratio:.1f}x")
```

## Response

### SDK result

What `client.compress()` returns:

- `output` (str): The compressed text
- `output_tokens` (int): Token count after compression
- `input_tokens` (int): Token count before compression
- `tokens_saved` (int): Tokens removed
- `compression_ratio` (float): e.g. 3.2x

### HTTP response

What `POST /v1/compress` returns on the wire, if you are calling it directly. `tokens_saved` and `compression_ratio` are computed by the SDK and are not fields on the response:

- `output` (str): The compressed text
- `output_tokens` (int): Token count after compression
- `original_input_tokens` (int): Token count before compression

## Async support

```python
from thetokencompany import AsyncTheTokenCompany

async with AsyncTheTokenCompany(api_key="ttc-...") as client:
    result = await client.compress("Your text here...")
    print(result.output)
```

---

# Compression

How compression works — models, aggressiveness, gzip, and protected text.

## Models

| Model | Description |
|-------|-------------|
| `bear-2` | Latest and recommended |
| `bear-1.2` | Previous generation |

## Aggressiveness

Controls how much content is removed. Range: 0.0 (lightest) to 1.0 (most aggressive). Default: 0.2.

| Range | Level | Description |
|-------|-------|-------------|
| `0.1-0.3` | Light | Removes only obvious filler |
| `0.4-0.6` | Moderate | Good balance of compression and quality |
| `0.7-0.9` | Aggressive | Significant savings |

## Per-role aggressiveness

```python
from thetokencompany.openai import with_compression

client = with_compression(
    OpenAI(),
    compression_api_key="ttc-...",
    aggressiveness={"system": 0.1, "user": 0.4, "tool": 0.6},
)
```

## Protected text

Wrap text in `<ttc_safe>` tags or use the `protect()` helper:

```python
from thetokencompany import protect

prompt = f"{protect('system:')} You are helpful."
```

## Gzip

Gzip is enabled by default in the SDK. Throughput benchmarks:

| Tokens | Raw | Gzip | Speedup |
|--------|-----|------|---------|
| 10,000 | 97K tok/s | 182K tok/s | 1.9x |
| 100,000 | 471K tok/s | 887K tok/s | 1.9x |
| 1,000,000 | 647K tok/s | 1.44M tok/s | 2.2x |

---

# OpenAI

Automatic compression for OpenAI API calls.

## Setup

```python
from openai import OpenAI
from thetokencompany.openai import with_compression

client = with_compression(OpenAI(), compression_api_key="ttc-...")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Your long prompt text here..."},
    ],
)
print(response.choices[0].message.content)
```

Assistant messages pass through unchanged. Only system, user, and tool messages are compressed.

## Async support

Works with `AsyncOpenAI` — the wrapper auto-detects sync vs async.

## Per-role aggressiveness

```python
client = with_compression(
    OpenAI(),
    compression_api_key="ttc-...",
    aggressiveness={"system": 0.1, "user": 0.4, "tool": 0.6},
)
```

---

# Vercel AI SDK

Use The Token Company compression with the Vercel AI SDK.

## Text generation

```typescript
import { TheTokenCompany } from "the-token-company";
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";

const ttc = new TheTokenCompany({ apiKey: "ttc-..." });
const compressed = await ttc.compress("Your long prompt...");

const { text } = await generateText({
    model: openai("gpt-4o"),
    prompt: compressed.output,
});
```

---

# Anthropic

Automatic compression for Anthropic Claude API calls.

## Setup

```python
from anthropic import Anthropic
from thetokencompany.anthropic import with_compression

client = with_compression(Anthropic(), compression_api_key="ttc-...")

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a helpful assistant.",
    messages=[{"role": "user", "content": "Your text..."}],
)
print(response.content[0].text)
```

The wrapper compresses the system parameter and all user messages. Assistant messages pass through unchanged.

---

# OpenRouter

Automatic compression for OpenRouter API calls. Uses the OpenAI-compatible wrapper.

## Setup

```python
from openai import OpenAI
from thetokencompany.openai import with_compression

client = with_compression(
    OpenAI(base_url="https://openrouter.ai/api/v1", api_key="YOUR_KEY"),
    compression_api_key="ttc-...",
)

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

Works with any OpenAI-compatible provider — Together AI, Groq, Fireworks, etc.

---

# Compression Statistics

Track per-turn and aggregate compression metrics.

Every `withCompression()` wrapper exposes a `client.compression` object that tracks stats.

## Per-turn stats

Each entry in `stats.history` has: input_tokens, output_tokens, tokens_saved, messages_compressed, ratio, timestamp.

## Aggregate stats

- `total_tokens_saved` / `totalTokensSaved` — sum of all tokens saved
- `calls` — number of create() calls
- `ratio` — overall compression ratio

---

# Advanced Aggressiveness

Set different compression levels per message role.

## Per-role aggressiveness

Pass a dictionary to `withCompression()` to set different levels per role:

```python
client = with_compression(
    OpenAI(),
    compression_api_key="ttc-...",
    aggressiveness={"system": 0.1, "user": 0.4, "tool": 0.6},
)
```

| Role | Recommended | Description |
|------|-------------|-------------|
| `system` | 0.1 | Preserve instructions carefully |
| `user` | 0.3–0.5 | Moderate compression |
| `tool` | 0.5–0.7 | Tool results are often verbose |

Assistant messages are never compressed.

---

# Protect Text

Exclude specific content from compression. This feature is experimental.

## The protect() helper

```python
from thetokencompany import protect

prompt = f"{protect('system:')} You are helpful."
```

Wraps text in `<ttc_safe>` tags to exclude it from compression. Useful for chat turn labels, code snippets, structured data, and proper nouns.

---

# Data Retention

How to disable data retention for your account and what it means for your data.

## Zero Data Retention

You can request **zero data retention** for your account. With this enabled, your prompts and outputs are **never stored in any database**. We do not train on your data and we do not share it with third parties.

### What we retain

| Data | Retained |
|------|----------|
| Timestamp | Yes |
| Input length (tokens) | Yes |
| Output length (tokens) | Yes |
| Prompts and outputs | No |

### How to enable

Contact support at rasmus@thetokencompany.com or through the Contact page.

## How It Works

Prompts and outputs are temporarily held during inference plus a 3600-second cache window, then automatically deleted.

**Warning:** With zero data retention enabled, we cannot help you recover or debug past requests.

---

# Troubleshooting

Common errors, debugging tips, and error reference.

## Error reference

| Exception | HTTP | Cause |
|-----------|------|-------|
| `AuthenticationError` | 401 | Invalid or missing API key |
| `InvalidRequestError` | 400 | Bad parameters. The SDK raises this locally, before sending, for empty text or an aggressiveness outside 0.0-1.0 |
| `PaymentRequiredError` | 402 | Insufficient balance |
| `RequestTooLargeError` | 413 | Payload too large |
| `APIError` | 422 | Server-side request validation failed; `detail` is an array, one entry per rejected field |
| `RateLimitError` | 429 | Too many requests |
| `APIError` | 503 | A dependency the API needs is unavailable |
| `APIError` | 5xx | Unexpected server error |

## Common issues

- **Empty text error**: Check input is not empty before compressing
- **Aggressiveness out of range**: Must be between 0.0 and 1.0
- **Timeouts**: Increase with `TheTokenCompany(api_key="...", timeout=60)`
- **Gzip issues**: Disable with `TheTokenCompany(api_key="...", gzip=False)`

## Getting help

Contact rasmus@thetokencompany.com or visit thetokencompany.com/contact.