Python SDK

The compresr package is the official Python client. It wraps the REST API with typed methods, handles auth, and ships both sync and async variants of every call. Python 3.9+.

1. Install

Install from PyPI: pip, poetry, and uv all work.

2. Initialize the client

Construct CompressionClient once at module scope and reuse it: the client keeps an internal httpx connection pool. Read the key from env, never hardcode.

The constructor takes api_key (required), plus optional base_url (defaults to https://api.compresr.ai) and timeout (seconds; default uses the SDK's built-in timeout). Override base_url only for regional or self-hosted endpoints.

See Authentication for key rotation, budgets, and rules.

Constructor options

Environment variables

3. compress

Synchronous single-request compression. Pass context, query, and compression_model_name="latte_v2"; the model keeps the spans that matter for the query. For many chunks against one query, see compress_batch; for incremental output, compress_stream.

Parameters

latte_v2 accepts every parameter latte_v1 accepts, plus three latte_v2-only knobs for dynamic compression-ratio selection. See the Models reference for the canonical decision guide and the at-a-glance support matrix.

Shared parameters (both models)

latte_v2-only parameters

Response

compress() returns a typed object; access fields as attributes (result.data.compressed_context). Response field names stay snake_case across every SDK.

4. Stream

client.compress_stream(...) returns an iterator yielding {content, done} chunks as the model produces them; the final chunk has done=True and empty content. Use it anywhere time-to-first-token matters (UIs, agent loops); for one-shot calls stick with compress.

The iterator is a normal generator: wrap it in itertools.islice, push chunks through a queue, or consume from a worker thread. Same context / query / compression_model_name rules as compress().

5. Batch

client.compress_batch(...) compresses many contexts in one request. Pass contexts: list[str] plus either a single queries: str (applied to every context) or a queries: list[str] matching contexts in length. Cheaper than firing N concurrent compress() calls, and ideal for RAG re-ranking or bulk document processing.

queries is either a string (applied to every context) or a list matching contexts in length; mixing the two raises ValidationError. Per-item results carry the same fields as a single compress() call except target_compression_ratio (request-level only). The envelope also exposes aggregates: result.data.count, total_original_tokens, total_compressed_tokens, total_tokens_saved, average_compression_ratio.

Alternate form: inputs=[{context, query}, ...]

The wire format is a list of {context, query} pairs. Pass inputs= instead of contexts=/queries= when it matches your data shape more naturally (queues, streaming pipelines, per-item queries). Exactly one of inputs OR contexts is required; passing both — or neither — raises ValidationError.

6. Agent client

Construct CompressionClient with llm= and you get an agent surface: three call-shapes (Anthropic-style messages.create, OpenAI-style chat.completions.create, native run) that auto-compress every tool output above min_tokens before the LLM sees it. Behind all three sits LangChain 1.0's create_agent + the SDK's CompresrToolMiddleware. Use it as a drop-in for anthropic.Anthropic() / openai.OpenAI(); for raw (context, query) calls stick with compress.

Construct with llm=

Provider lives on the client; model lives at the call site. Swap providers by changing one string: same tools, same code:

The llm string accepts "anthropic" (provider only, every call must pass model="..."), "anthropic:claude-haiku-4-5" (default model, overridable at call site), or "anthropic/claude-haiku-4-5" (Vercel AI SDK convention; both separators accepted). If neither provides a model, the SDK raises CompresrError("model is required …").

Three call shapes

messages.create duck-types anthropic.types.Message, chat.completions.create duck-types openai.types.chat.ChatCompletion, and run returns a native NormalizedResult (.text, .tool_uses, .citations, .stop_reason, .usage).

Python also exposes async variants: acreate, arun. TypeScript is async by default.

Web search: WebSearchTool

Three providers ship in the box: Tavily, Brave, and AgentCore (Amazon Bedrock via MCP). All three return a real LangChain BaseTool; their output flows through CompresrToolMiddleware automatically.

Provider reference

Tavily (WebSearchTool.tavily) — reads api_key=, then TAVILY_API_KEY env var. Raises ValueError if neither is set. Supports allowed_domains / blocked_domains natively.

Brave (WebSearchTool.brave) — reads api_key=, then BRAVE_SEARCH_API_KEY, then BRAVE_API_KEY. Raises ValueError if none of the three are set. allowed_domains / blocked_domains are not supported (Brave uses Goggles for filtering, out of scope); passing them emits a UserWarning.

AgentCore (WebSearchTool.agentcore) — install with pip install compresr[agentcore]. Talks to an Amazon Bedrock AgentCore gateway over MCP streamable-HTTP, authenticated via a Cognito OAuth 2.0 client-credentials handshake. Bearer tokens are cached; a 401 triggers one automatic re-mint. max_results is clamped to 1..25; responses larger than 1 MB are rejected. allowed_domains / blocked_domains are accepted for signature parity but emit a UserWarning — use Tavily if you need domain filtering.

AgentCore config resolves per field with precedence explicit arg → AgentCore-namespaced env → short env. If any field is unresolved, WebSearchTool.agentcore(...) raises ValueError listing every missing field:

Bring your own tool

Any LangChain @tool-decorated function works. The string return value is compressed before the LLM sees it.

Streaming isn't on the agent layer yet: the Python facades expose only .create / .acreate, so client.messages.stream(...) / client.chat.completions.stream(...) raise AttributeError (not a typed CompresrError). The compression-API stream (compress_stream) is unaffected.

Research: client.research

When constructed with llm=, the client also exposes client.research, a multi-step search-and-summarize loop that runs a web-search tool for you, compresses each snippet before it enters the LLM's context, and returns a structured result with citations. client.research.run(question) runs the full loop (up to max_steps); client.research.search(question) is the same loop capped at 2 steps for quick lookups.

Accessing client.research when llm= was not passed raises CompresrError — the facade needs a chat model to reason about search results.

ResearchResult fields: answer: str, explanation: str, confidence: float | None, text: str, citations: list[Citation], trajectory: list[Step], usage: ResearchUsage, raw: Any (defaults to None; usually the provider's raw response object). ResearchUsage has int counters input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, calls, search_calls. Each Citation has url: str, title: str | None, snippet: str | None.

Per-call LLM knobs

Forwarded to the underlying chat model: temperature, top_p, top_k, max_tokens, max_output_tokens, stop, stop_sequences, presence_penalty, frequency_penalty, seed, logprobs, top_logprobs. Anything else is silently dropped.

Compression knobs: compression={...}

Set at client construction. Applies to every tool-output compression the middleware fires. The model-routing keys mirror compress() — compression_model_name picks the backbone, and the compression-shaping keys forward through to the same /compress/question-specific/ endpoint.

Shared keys (accepted regardless of compression_model_name):

The middleware policy doesn't expose the dynamic* latte_v2-only knobs. If you need adaptive ratio selection on tool outputs, call client.compress(...) directly with dynamic=True instead of routing through the middleware.

7. Async

compress_async and compress_batch_async are the async twins of compress and compress_batch: same params, return awaitables. Streaming is sync-only (no compress_stream_async). Call await client.aclose() when done to release the httpx pool, or use the client as an async context manager (async with CompressionClient(...) as client:). Use these inside event loops (FastAPI handlers, Discord bots, agent runtimes); for scripts the sync methods are simpler.

8. Errors & types

Every Compresr error inherits from CompresrError. Catch the base for a single handler; catch subclasses when recovery differs. Every subclass carries a stable code string and, where relevant, structured attributes you can branch on (e.g. err.retry_after, err.credits_remaining, err.available_models) instead of parsing prose.