API Reference

Everything you need to use SuperCompress programmatically — Python library, HTTP API, response types, and client configuration.

Python API

The supercompress package provides the core compression functions. Import them directly from the top-level package.

compress_context(text, question, budget_ratio=0.35, policy=None, checkpoint=None)

Compress a single string of context against a question. Returns a CompressResult.

Raises: ValueError if budget_ratio is not in (0, 1]. Empty input returns policy_name="noop" with zero tokens.

from supercompress import compress_context

result = compress_context(
    text="Your long context…",
    question="What does fetch return?",
)

print(result.compressed_text)
print(f"Saved {result.kv_savings_pct:.1f}% tokens")

compress_for_turn(context_blocks, user_query, budget_ratio=0.35)

Compress a list of context blocks (e.g. system prompt, tool output, chat history) against a user query. Merges blocks with \n\n---\n\n before compression. Returns (compressed_text, CompressResult).

from supercompress import compress_for_turn

compressed, stats = compress_for_turn(
    context_blocks=[system_prompt, tool_output, chat_history],
    user_query=user_message,
)

# Send `compressed` to your LLM instead of the full merge

compress_detailed(text, question, ...)

Same as compress_context, but also returns per-line keep/drop annotations. Useful for debugging or building visualizations.

from supercompress import compress_detailed

result, lines = compress_detailed(ctx, question)
for ln in lines:
    if not ln.kept:
        print(f"Line {ln.line_index}: {ln.reason}")

middle_truncation_failure_case()

Returns a (context, question) tuple where head+tail truncation loses a middle answer. Useful for demos, benchmarks, and testing.

from supercompress import middle_truncation_failure_case

ctx, q = middle_truncation_failure_case()
result = compress_context(ctx, q)
print(f"Truncation would lose this. SuperCompress: {result.kv_savings_pct:.0f}% saved")

CompressResult fields

HTTP API

The hosted API uses compiler mode by default — no budget needed. Compiler mode maximizes token removal while preserving answer-critical evidence.

curl -d "context=Your long text&query=What matters?" https://supercompress.dev/compress \
  -H "X-API-Key: sc_live_YOUR_KEY"

POST request

Send as JSON (standard) or form-encoded (simpler for curl). All three work:

# Option 1: JSON (standard)
POST https://supercompress.dev/api/v1/compress
Content-Type: application/json
X-API-Key: sc_live_YOUR_KEY
{
  "context": "Your long context…",
  "query": "What matters?"
}

# Option 2: Form-encoded (quick curl)
curl -d "context=...&query=..." https://supercompress.dev/compress \
  -H "X-API-Key: sc_live_YOUR_KEY"

# Option 3: GET with query params (small contexts)
curl "https://supercompress.dev/compress?context=...&query=...&api_key=sc_live_YOUR_KEY"

All three hit the same endpoint and return the identical response. Use whatever fits your workflow.

Parameters

Response (compiler mode)

{
  "compressed_text": "…",
  "original_tokens": 1248,
  "kept_tokens": 436,
  "tokens_saved": 812,
  "kv_savings_pct": 65.06,
  "important_kept_pct": 0.98,
  "compression_risk": "low",
  "kept_blocks": [
    {"heading": "User account", "reason": "matches query topic"},
    {"heading": "Billing history", "reason": "contains answer evidence"}
  ],
  "dropped_blocks": [
    {"heading": "Feature requests", "reason": "irrelevant to billing question"}
  ],
  "policy_name": "SuperCompress-compiler"
}

Response fields

Authentication

Include your API key in either the X-API-Key header or the Authorization: Bearer sc_live_… header. Get a key from the dashboard.

Compiler mode (default)

Compiler mode is the production path. Users do not choose a budget or ratio. The engine:

• Segments context into semantic blocks (headings, code, logs, prose)
• Downranks repeated tool output, boilerplate, generated noise, and duplicates
• Preserves nearby headings, imports, trace/log context, and balanced markdown fences
• Reports tokens saved, important context kept %, verifier risk level, and block-level breakdowns

Compiler mode is the default on the hosted API. The local Python library uses fixed-ratio mode by default for backward compatibility, but you can enable compiler-style behavior by omitting budget_ratio.

When to use each mode

Comparing policies

compare_policies(text, question, budget_ratio=0.35)

Returns a dict of {policy_name: CompressResult} for FIFO, Truncation, Summarization, H2O, and SuperCompress. Useful for benchmarks and research.

from supercompress import compare_policies

results = compare_policies(ctx, question, budget_ratio=0.35)
for name, r in results.items():
    print(f"{name}: {r.kept_tokens} tokens ({r.kv_savings_pct:.1f}%)")

Environmental impact

The sustainability_from_tokens_saved helper converts token savings into estimated GPU-seconds, kWh, and CO₂ avoided.

from supercompress.benchmarks.metrics import sustainability_from_tokens_saved

saved = result.original_tokens - result.kept_tokens
impact = sustainability_from_tokens_saved(saved)

print(impact.co2_kg_avoided)
print(impact.watt_hours_saved)
print(impact.assumptions.to_dict())

Default assumptions: 2,500 tokens/GPU-sec, 150W GPU, 0.417 kg CO₂/kWh (US grid), 55% KV share of prefill. See Environment & CO₂ for the full methodology.

Error handling

Python errors

HTTP status codes