Integrations

Drop compression into your existing LLM stack with one wrapper function. Each integration preserves your current API shape — just swap out the client or add a middleware step.

Python (direct import)

The simplest integration — call compression before sending to any LLM:

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
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": compressed},
    ],
)

Track the savings:

from supercompress.benchmarks.metrics import sustainability_from_tokens_saved

saved = stats.original_tokens - stats.kept_tokens
impact = sustainability_from_tokens_saved(saved)
print(f"Saved {impact.co2_kg_avoided:.6f} kg CO₂")

OpenAI SDK wrapper

The SuperCompressOpenAI wrapper replaces your OpenAI client. It compresses conversation history before every API call, preserving system messages and the latest user turn.

from openai_middleware import SuperCompressOpenAI

client = SuperCompressOpenAI(budget_ratio=0.35)

# Use exactly like the regular OpenAI client
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "Helpful assistant."},
        {"role": "user", "content": long_context},
        {"role": "assistant", "content": "OK."},
        {"role": "user", "content": "Summarize the key findings."},
    ],
)

print(client.get_stats())
# → {'total_original_tokens': 580, 'total_kept_tokens': 203, 'total_savings_pct': 65.0}

Streaming works too — just pass stream=True.

The wrapper is available at integrations/openai_middleware.py in the repo.

LangChain hook

Compress HumanMessage / AIMessage history before invoke(). No LangChain dependency in the core package — the example is copy-paste friendly.

Available at examples/integrations/langchain_hook.py in the repo.

from langchain_hook import compress_history
from dataclasses import dataclass

@dataclass
class Message:
    role: str
    content: str

messages = [
    Message("system", "You are helpful."),
    Message("user", "long log…\nentry 1\nentry 2\n..."),
    Message("assistant", "Noted."),
    Message("user", "Summarize entry 75"),
]

compressed_msgs, meta = compress_history(messages)
print(meta)
# → {'original_tokens': 580, 'kept_tokens': 203, 'kv_savings_pct': 65.0}

The hook preserves system messages, compresses assistant/user history into a single context block, and appends the latest user query. The compressed messages can be passed directly to any LangChain chain.

Anthropic SDK wrapper

Available at integrations/anthropic_middleware.py. Same pattern as the OpenAI wrapper — intercepts messages before sending to Anthropic's API, compresses history, tracks savings.

from anthropic_middleware import SuperCompressAnthropic

client = SuperCompressAnthropic(budget_ratio=0.35)
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[...],
)

Express.js / Next.js middleware

For Node.js backends, the Express middleware intercepts requests and compresses the messages field before forwarding to your LLM.

Available at integrations/express-middleware.ts.

import { supercompressMiddleware } from "express-middleware";

const sc = supercompressMiddleware({
  budgetRatio: 0.35,
  verbose: true,
});

// In your Express route handler
app.post("/api/chat", sc.handler, async (req, res) => {
  // req.body.messages are now compressed!
  const response = await callLLM(req.body.messages);
  res.json(response);
});

// Track cumulative stats
console.log(sc.getStats());

For Next.js App Router, use the compressMessages() function directly in your API route:

export async function POST(req: Request) {
  const body = await req.json();
  const compressed = await sc.compressMessages(body.messages);
  // Forward compressed to your LLM
}

Vercel AI SDK

Drop-in wrapper for generateText and streamText. Works with any provider: OpenAI, Anthropic, Google, Mistral.

Available at integrations/vercel-ai-sdk.ts.

import { SuperCompressAI } from "vercel-ai-sdk";
import { openai } from "@ai-sdk/openai";

const sc = new SuperCompressAI({ budgetRatio: 0.35 });

// Use instead of generateText()
const { text } = await sc.generateText({
  model: openai("gpt-4o"),
  messages: [longContext, userMessage],
});

// Streaming with streamText
const result = await sc.streamText({
  model: openai("gpt-4o"),
  messages: [longContext, userMessage],
});

// Track savings
console.log(sc.getStats());
// → { totalOriginalTokens: 1200, totalKeptTokens: 420, totalSavingsPct: 65 }

Browser / static sites

For static sites and demos, the browser engine loads the trained policy model.json and runs the identical eviction logic client-side.

<!-- Load the engine -->
<script src="assets/js/compress-engine.js"></script>

<!-- In your JS -->
<script>
  const model = await SuperCompressEngine.loadModel("assets/data/model.json");
  const result = SuperCompressEngine.compressAdaptive(context, query, model);
  console.log(result.compressed_text);
  console.log(result.kv_savings_pct);
</script>

Export the model from Python:

python scripts/export_model_json.py
# → Creates web/assets/data/model.json

curl / any HTTP client

Call the hosted API from any language or script. Three ways, same result:

# Quickest — form-encoded, no JSON needed
curl -d "context=Your long context...&query=Summarize." \
  https://supercompress.dev/compress \
  -H "X-API-Key: sc_live_YOUR_KEY"

# Standard JSON
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…","query":"Summarize."}'

# GET (small contexts only)
curl "https://supercompress.dev/compress?context=...&query=Summarize.&api_key=sc_live_YOUR_KEY"

Integration files

All integration files are in the integrations/ directory and examples/integrations/ directory of the repo.

File	Purpose
integrations/openai_middleware.py	OpenAI SDK transparent wrapper
integrations/anthropic_middleware.py	Anthropic SDK transparent wrapper
integrations/vercel-ai-sdk.ts	Vercel AI SDK wrapper (generateText, streamText)
integrations/express-middleware.ts	Express.js / Next.js route middleware
examples/integrations/openai_wrapper.py	Lightweight OpenAI messages example
examples/integrations/langchain_hook.py	LangChain-compatible history compression
examples/integrations/raw_pipeline.py	Stdin/stdout compression pipeline
examples/integrations/curl_local_server.sh	cURL example against local dev server