Expand description
POST /v1/compress — deterministic messages-in / messages-out compression.
Drop-in parity with library-style compress(messages, model) gateways: the
caller sends a chat-style messages array, the proxy rewrites every text
payload through the same deterministic funnel used on the wire
(super::compress::compress_tool_result_gateway), and returns the
rewritten messages plus a structured token-savings summary. A lossy rewrite
embeds a hash=<24hex> retrieval marker (#702) that LiteLLM’s headroom
guardrail resolves through GET /v1/retrieve/{hash} — the CCR agentic loop
(BerriAI/litellm#31681) works against lean-ctx unchanged.
§Contract
Request: { "messages": [ … ], "model": "…"? }
Response: { "messages": [ … ], "stats": { … } }
Both OpenAI (content: "string") and Anthropic (content: [ {type:"text"…}, {type:"tool_result"…} ]) message shapes are accepted. Only text payloads are
compressed; images, tool_use blocks, ids and every other field pass through
untouched. lean-ctx’s own ctx_* tool results are left verbatim (#479).
§Gateway compatibility (#700)
The response also carries tokens_before / tokens_after /
compression_ratio at the top level — the field names LiteLLM’s
prompt-compression guardrail reads for its per-request savings log. That
makes lean-ctx a drop-in api_base for guardrail: headroom deployments:
LiteLLM only requires messages in the reply and treats the token fields
as optional telemetry.
§Determinism (#498)
Output is a pure function of (messages, model). Compression runs footer-free
— savings are reported in stats, never injected into message bodies — so the
result stays byte-stable for provider prompt caching.
Structs§
Functions§
- compress_
messages - Pure, deterministic core: rewrites every text payload in
messagesand reports aggregate token savings. Same input → same output bytes (#498). - handler
- Axum handler. Malformed bodies are rejected by the
Jsonextractor (400).