Overview

compresr (Python 3.9+) and @compresr/sdk (Node 20+) wrap the REST API with typed methods, auth, retries, and async support. Every snippet is shown in all three flavors — pick a tab once and the choice sticks across the docs.

This page covers what only the SDKs have: installation, the client and its options, the core compress call, the agent client, and the exception types.

Install

The agent client ships in the base install (Python compresr ≥ 2.8.2, TypeScript @compresr/sdk ≥ 1.5); the old compresr[agents] extras still work as no-op aliases.

Initialize

Construct the client once and reuse it — it keeps an internal connection pool. See Authentication for the three ways to supply the key.

Constructor options

The table follows the language toggle — flip any snippet above to TypeScript and it re-renders with the camelCase spellings, types, and defaults.

compress

Single-request compression. Parameters map 1:1 to the API — the canonical parameter table, defaults, and target_compression_ratio semantics live in the Models reference. TypeScript accepts camelCase (targetCompressionRatio); the wire and all response fields stay snake_case.

Response

Async

Python ships compress_async — same parameters as compress, awaitable. Use async with (or call await client.aclose() when done) so the connection pool closes cleanly. TypeScript is async-native throughout; there are no _async variants — fire calls concurrently with Promise.all.

If every row shares one model and ratio, prefer a single compress_batch call over N concurrent singles — one round trip, one rate-limit hit. Streaming is sync-only in Python; compress_batch_async is covered in the batch guide.

Everything else

Agent client

Construct the client with llm= and you get an agent surface: three call shapes that auto-compress every tool output above min_tokens before the LLM sees it (LangChain 1.0 create_agent + CompresrToolMiddleware under the hood). There is no cURL equivalent — the compression the middleware fires is the same /api/compress/question-specific/ endpoint.

Rules that bite:

• Model lives at the call site. llm="anthropic" sets the provider; every call passes model=. Pin a default with llm="anthropic:claude-haiku-4-5" (or / — both separators work). Neither set → CompresrError("model is required …").
• Python run() / arun() are keyword-only — client.run("question") raises TypeError.
• Any LangChain tool works. A @tool-decorated function (Python) or tool({...}) (TypeScript) gets its string output compressed automatically.
• Per-call LLM knobs (temperature, top_p, max_tokens, stop, seed, …) forward to the chat model; unknown keys are silently dropped. On Gemini the SDK renames max_tokens → max_output_tokens for you.
• Async: Python exposes acreate / arun. Agent-layer streaming is not implemented — Python facades have no .stream(...) (raises AttributeError); TypeScript throws CompresrError(code: 'not_implemented'). compress_stream is unaffected.
• Web search and research: WebSearchTool (Tavily / Brave / AgentCore) and the client.research facade are covered in the web search guide.

Compression knobs

compression={...} at construction applies to every tool output the middleware compresses:

The policy doesn't expose the dynamic* knobs; call client.compress(dynamic=True, ...) directly if you need adaptive ratios.

Errors

Every SDK error inherits from CompresrError and carries a stable code plus structured attributes (err.retry_after, err.field, …) — HTTP-level details in Error codes. In Python, import them from compresr.exceptions (they are not re-exported at the package root). In TypeScript, the classes marked ✓ are importable from @compresr/sdk; everything else arrives as CompresrError with the corresponding code.