Quickstart

Install SuperCompress, get an API key, and compress your first prompt — in under 5 minutes.

1. Install the package

The fastest way to try SuperCompress is with the Python library. It works on any system with Python 3.10+.

pip install supercompress

That's it. No model downloads, no ONNX Runtime, no GPU drivers. The trained policy weights are bundled with the package (~200KB total).

For development (tests, frontend export):

pip install -e ".[dev]"

2. Get an API key

To use the hosted API, head to the dashboard, sign in with Google or email, and create a key. Keys look like sc_live_xxxxxxxx.

For local-only use, you don't need a key — the library compresses entirely on-device.

Set your key as an environment variable:

export SUPERCOMPRESS_API_KEY=sc_live_YOUR_KEY

3. Compress your first prompt

Create a file called compress.py:

from supercompress import compress_context

context = """\
## User account info
User ID: 4521
Plan: Pro
Billing cycle: monthly
Seats: 5

## Feature requests (Q2)
Multi-workspace view — in progress
Dark mode — planned
API rate limit increase — under review

## Recent activity
2026-06-28 — upgraded from Starter to Pro
2026-06-25 — generated 3 API keys
2026-06-20 — hit rate limit, filed support ticket
"""

question = "What plan is the user on and how many seats do they have?"

result = compress_context(context, question)

print(result.compressed_text)

Run it:

python compress.py

Output:

## User account info
User ID: 4521
Plan: Pro
Billing cycle: monthly
Seats: 5

## Recent activity
2026-06-28 — upgraded from Starter to Pro

Notice that the Feature requests section was dropped — it's irrelevant to a question about the current plan. The Recent activity section was partially kept because the upgrade confirms the plan. The compiler preserved what matters and cut the rest.

4. Understand what happened

The compress_context function returns a CompressResult with useful metadata:

print(f"Original: {result.original_tokens} tokens")
print(f"Compressed: {result.kept_tokens} tokens")
print(f"Saved: {result.kv_savings_pct:.1f}%")
print(f"Policy: {result.policy_name}")

On this example you'll see something like:

Original: 104 tokens
Compressed: 40 tokens
Saved: 61.5%
Policy: SuperCompress

The function also supports compiler mode (default in the hosted API) which doesn't require a budget — it maximizes removal while keeping important evidence and reporting a risk level.

5. Next steps

• Use the hosted API — POST /api/v1/compress (or just /compress) from any language. See the API reference.
• Wire it into your app — add compression before OpenAI, LangChain, Express.js, or any LLM call. See integrations.
• Deploy on your own server — pip install supercompress and call it from any Python backend. See usage.
• Try the playground — test compression on your own text in-browser at supercompress.dev/playground.
• Compare approaches — see how SuperCompress stacks up against truncation, summarization, and H2O at supercompress.dev/benchmarks.

Using the hosted API (curl)

If you don't want to install anything, call the hosted API directly. One-liner form-encoded POST works with any HTTP client:

# Quick one-liner
curl -d "context=Your long context here...&query=What do you want to know?" \
  https://supercompress.dev/compress \
  -H "X-API-Key: sc_live_YOUR_KEY"

# Or as JSON (standard)
curl -X POST https://supercompress.dev/api/v1/compress \
  -H "X-API-Key: sc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"context":"Your long context here…","query":"What do you want to know?"}'

# Or GET with query params (small contexts)
curl "https://supercompress.dev/compress?context=Your+long+context&query=What+do+you+want&api_key=sc_live_YOUR_KEY"

All three work. Response:

{
  "compressed_text": "…",
  "original_tokens": 104,
  "kept_tokens": 40,
  "kv_savings_pct": 61.5,
  "important_kept_pct": 0.95,
  "compression_risk": "low",
  "kept_blocks": ["User account info", "Recent activity"],
  "dropped_blocks": ["Feature requests (Q2)"]
}

Using the Python client

The SuperCompress client wraps the hosted API for Python users:

from supercompress.client import SuperCompress

sc = SuperCompress()  # reads SUPERCOMPRESS_API_KEY
out = sc.compress(context, question)
print(out.compressed_text)