Skip to content

API.md

Latest commit

 

History

History
325 lines (235 loc) · 10.1 KB

API.md

File metadata and controls

325 lines (235 loc) · 10.1 KB
Raw

SuperCompress API

Python library and hosted API — compile long context down to the smallest useful prompt for a query.

Dashboard: API_DASHBOARD.md · Integrations: INTEGRATIONS.md

Install

pip install git+https://gitlab.com/arjunkshah/supercompress.git
# dev + tests
pip install -e ".[dev,serve]"

Quick start

from supercompress import compress_context

result = compress_context(
    text=open("context.txt").read(),
    question="What does fetch return when the row is missing?",
)

print(result.compressed_text)       # send to your LLM
print(result.kv_savings_pct)        # tokens removed before your LLM call
print(result.original_tokens, result.kept_tokens)

The hosted API does not require a budget. It uses compiler mode by default: maximize tokens removed while keeping important query evidence.

export SUPERCOMPRESS_API_KEY=sc_live_YOUR_KEY

curl -X POST https://supercompress.dev/api/v1/compress \
  -H "X-API-Key: $SUPERCOMPRESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"context":"long text…","query":"What matters?"}'

Compiler response fields:

Field Description
tokens_saved Tokens removed from this API call
kv_savings_pct Percent of input tokens removed
important_kept_pct Estimated share of important context preserved
compression_risk low, medium, or high verifier risk
preprocessor Content type detected: json, code, log, or none
kept_blocks Evidence blocks kept, with reasons
dropped_blocks Largest removed blocks

Modes

SuperCompress supports three compression modes:

Compiler mode (default)

Query-aware context compiler. Removes the most tokens it can while preserving answer-critical evidence. No budget needed.

result = compress_context(text, question)  # auto-compiler

Precision mode

Dual-model architecture: AMCP policy + verifier confidence classifier. Tries progressively aggressive budgets (0.40→0.20) and uses the most aggressive ratio where verifier confidence ≥ 0.85.

from supercompress.client import SuperCompress
sc = SuperCompress(api_key="sc_live_...")
result = sc.compress(
    context="long context…",
    query="What matters?",
    mode="precision"
)

Additional response fields:

Field Description
confidence Verifier confidence score (0–1)
confidence_ok Whether confidence ≥ 0.85 threshold
budget_ratio Budget ratio selected by precision search

Fixed-ratio mode (legacy)

Explicit token budget — kept for research baselines.

result = compress_context(text, question, budget_ratio=0.35)

Domain Preprocessors

Content-aware preprocessing runs automatically in compiler and precision modes. The content router detects the text type and applies specialized transformations.

Content type detection

The router samples the first 50 lines and classifies them:

Route Detected By Preprocessor
json JSON brackets ({, [) present, config/table patterns JSON SmartCrusher
code Imports, definitions, fences, comments dominate Code AST compressor
log Log level tags, stack trace patterns, timestamps Log/Trace compressor
text None of the above (default pass-through) —

Preprocessor details

JSON SmartCrusher

  • Drops null fields and empty arrays
  • Samples homogeneous arrays: keeps 3 + count for arrays > 12 items
  • Truncates long strings (> 200 chars)
  • Drops timestamps from well-known keys
  • Only replaces if crushed text is ≥ 15% smaller

Code AST compressor

  • Strips docstrings (""", '''), block comments (/* */), line comments (//, #, ;), JSDoc annotations
  • Collapses multi-line data literals into single lines
  • Preserves: defs, classes, interfaces, decorators, return/yield/throw, imports
  • Collapses runs of 3+ blank lines into at most 1

Log/Trace compressor

  • Collapses long stack traces to first + last frame
  • Deduplicates repeated messages (fingerprinted by normalizing timestamps/numbers)
  • Filters DEBUG/TRACE lines unless the question asks about them
  • Concentrates ERROR/WARN lines when the question mentions errors

Accessing preprocessor info

result = compress_context(text, question)
print(f"Preprocessor: {result.preprocessor}")  # "json", "code", "log", or "none"

CCR — Cache, Compress, Retrieve

Reversible compression: removed blocks are replaced with retrieval markers. The original content can be restored on demand.

# Request compression with CCR
curl -X POST https://supercompress.dev/api/v1/compress \
  -H "X-API-Key: sc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"context": "long text…", "query": "What matters?", "ccr": true}'

# Response includes ccr field:
# {
#   "compressed_text": "... [SC-Retrieve: a1b2c3d4] ...",
#   "ccr": {
#     "hash": "a1b2c3d4e5f6_1a2b",
#     "stored": true,
#     "retrieve_url": "/api/retrieve?hash=a1b2c3d4e5f6_1a2b"
#   }
# }

# Retrieve original
curl https://supercompress.dev/api/retrieve?hash=a1b2c3d4e5f6_1a2b

Browser-side CCR

const result = SuperCompressEngine.compressCCR(context, query, model, { enableMarkers: true });
// result.compressed_text contains [SC-Retrieve: hash] markers
// Use SuperCompressEngine.ccrRetrieve(hash) to get original

Functions

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

Compress a single string. Returns CompressResult.

Parameter Type Default Notes
text str required Full context to trim
question str required Current user query — drives retention
budget_ratio float 0.35 Fraction of tokens to keep, (0, 1] (fixed-ratio mode only)
policy EvictionPolicy learned Override with FIFO(), TruncationPolicy(), etc.
checkpoint str default.pt Path to trained weights

Raises: ValueError if budget_ratio ∉ (0, 1].

Empty input: returns policy_name="noop" with zero tokens.

compress_for_turn(context_blocks, user_query, budget_ratio=0.35)

Merge blocks with \n\n---\n\n, then compress. Returns (compressed_text, CompressResult).

compressed, stats = compress_for_turn(
    ["## Notes\n…", "## Code\n…"],
    "Summarize the API",
)

compare_policies(text, question, budget_ratio=0.35)

Returns dict[str, CompressResult] for FIFO, Truncation, Summarization, H2O, and SuperCompress.

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

compress_detailed(text, question, ...)

Same as compress_context, plus List[LineAnnotation] with per-line keep/drop reasons.

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

middle_truncation_failure_case()

Returns (context, question) where head+tail truncation loses a middle answer — use for demos and tests.

CompressResult

Field Type Description
original_text str Input context
compressed_text str Trimmed context for your LLM
original_tokens int Tokens before eviction
kept_tokens int Tokens retained
kv_savings_pct float (1 - kept/original) × 100
compression_ratio float Property: original / kept
policy_name str SuperCompress, H2O-fallback, or baseline name
budget_ratio float Retention budget used
preprocessor str json, code, log, or none
kept_line_ratio float Share of lines kept (includes sink/recent)
question str Query used

Environmental impact

from supercompress.benchmarks.metrics import sustainability_from_tokens_saved

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

See ENVIRONMENT.md for assumptions.

Hosted API (production)

Use POST /api/v1/compress with context and query. Do not pass a budget unless you intentionally want the legacy fixed-ratio mode.

Optional parameters:

Parameter Type Default Description
mode str "compiler" "compiler", "precision", or "fixed"
ccr bool false Enable reversible compression (markers + storage)
cache_prefix bool false Wrap compressed output in a deterministic XML preamble/postamble for provider-side KV cache hits (OpenAI, Anthropic, vLLM)

Or use the Python client:

from supercompress.client import SuperCompress

sc = SuperCompress()  # SUPERCOMPRESS_API_KEY + default base https://supercompress.dev
out = sc.compress(context, "What matters?", mode="precision")

Dashboard & keys: supercompress.dev/dashboard

Local HTTP server (optional)

Development only — not used on the public Vercel site.

pip install -e ".[serve]"
python scripts/local_web_server.py

GET /api/health

{"ok": true, "service": "supercompress-web"}

POST /api/compress

{
  "context": "long text…",
  "query": "What does fetch return?",
  "compare": true
}

Response includes compressed_text, token stats, optional compare map, and line_annotations.

Train checkpoint

supercompress-train --fast
python scripts/export_model_json.py   # browser demo weights

# Precision model + verifier
python scripts/train_precision.py     # → web/assets/data/model_precision.json
python scripts/train_verifier.py      # → web/assets/data/verifier.json

Tests

pytest tests/ -q
# Hard API validation: tests/test_api_hard.py
# Local server: tests/test_local_server.py (needs [serve])

Related docs