Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
docs(pypi): job-word summary and keywords, and a PyPI-specific README (#4534)
Tejas Chopraa5e68deb6486
diff --git a/Dockerfile b/Dockerfileindex 9637ebeb2..aff8593cb 100644--- a/Dockerfile+++ b/Dockerfile@@ -42,7 +42,7 @@ WORKDIR /build# Copy the full set of files maturin needs to build the wheel: the root# pyproject.toml + Cargo workspace + Rust crates + Python source. The# uv install builds + installs the wheel in one shot.-COPY pyproject.toml uv.lock README.md ./+COPY pyproject.toml uv.lock README.md README-pypi.md ./COPY Cargo.toml Cargo.lock rust-toolchain.toml ./COPY crates/ crates/COPY headroom/ headroom/@@ -103,6 +103,7 @@ def source_digest(root: Path) -> str:"pyproject.toml","uv.lock","README.md",+ "README-pypi.md","Cargo.toml","Cargo.lock","rust-toolchain.toml",diff --git a/README-pypi.md b/README-pypi.mdnew file mode 100644index 000000000..fdb5cfa96--- /dev/null+++ b/README-pypi.md@@ -0,0 +1,69 @@+# Headroom (`headroom-ai`)++Compress tool outputs, logs, JSON and chat history before each LLM call, so the+model sees fewer input tokens and the same facts. Runs in-process, in Python,+with no API key and no model download. Originals are cached locally and+retrievable.++Measured: 21–57% fewer input tokens on four agent scenarios, 90%+ on repeated+JSON arrays and log lines, little on prose. Numbers and how to reproduce them:+https://docs.headroomlabs.ai/docs/benchmarks and the "Proof" section of+https://github.com/headroomlabs-ai/headroom++## Use it from a Python app that calls an LLM++```bash+pip install headroom-ai+```++```python+from headroom import compress++result = compress(messages, model="gpt-4o") # OpenAI or Anthropic message dicts+result.messages # same shape as the input, fewer tokens+result.tokens_before, result.tokens_after, result.tokens_saved+```++Pass `result.messages` to your existing client call instead of `messages`.+Nothing else changes. Error lines, stack traces, first and last items and+statistical outliers are kept; repeated and low-information items are dropped.++Zero-network check, no provider key needed:++```bash+HEADROOM_OFFLINE=1 python -c "from headroom import compress; log='\n'.join(f'INFO step {i} ok' for i in range(3000))+'\nFATAL disk full'; r=compress([{'role':'user','content':'What failed?'},{'role':'assistant','content':None,'tool_calls':[{'id':'c1','type':'function','function':{'name':'logs','arguments':'{}'}}]},{'role':'tool','tool_call_id':'c1','content':log}], model='gpt-4o'); print(r.tokens_before, '->', r.tokens_after, 'FATAL kept:', 'FATAL' in str(r.messages))"+```++Prints on the order of `20000 -> 95 FATAL kept: True`. `HEADROOM_OFFLINE=1`+blocks every connection Headroom would make on its own: the update check, model+and pricing-table downloads, and the anonymous usage beacon the proxy and MCP+server send by default (`HEADROOM_BEACON=off` turns off only the beacon).++FastAPI example with a `POST /chat` endpoint:+https://docs.headroomlabs.ai/docs/fastapi++## Use it around a coding agent (no code changes)++```bash+uv tool install --python 3.13 "headroom-ai[all]" # CLI in its own env; pip install "headroom-ai[proxy]" also works+headroom wrap claude # also: codex, grok, copilot, cursor, aider, opencode, cline, continue, goose, openhands, openclaw, vibe, omp, zcode+headroom proxy --port 8787 # or run the proxy and point any client at it+```++## Other entry points++- OpenAI, Anthropic, LiteLLM, LangChain, Agno, Strands, CrewAI, AutoGen adapters:+ https://docs.headroomlabs.ai/docs (Integrations)+- MCP server (`headroom_compress`, `headroom_retrieve`, `headroom_stats`):+ https://docs.headroomlabs.ai/docs/mcp+- TypeScript SDK (`npm install headroom-ai`, needs the proxy running):+ https://www.npmjs.com/package/headroom-ai+- Full docs index for agents: https://docs.headroomlabs.ai/llms.txt+- Source and issues: https://github.com/headroomlabs-ai/headroom++Extras: `[proxy]` adds the HTTP proxy and `headroom wrap`, `[mcp]` the MCP+server, `[ml]` the Kompress text model (torch), `[all]` everything. The base+install is enough for `compress()`. Requires Python 3.11+.++Apache 2.0. The import and CLI name is `headroom`; the PyPI distribution named+`headroom` is a different project.diff --git a/e2e/init/Dockerfile b/e2e/init/Dockerfileindex c4fbb870a..147fe50a5 100644--- a/e2e/init/Dockerfile+++ b/e2e/init/Dockerfile@@ -17,7 +17,7 @@ RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \WORKDIR /build-COPY pyproject.toml uv.lock README.md ./+COPY pyproject.toml uv.lock README.md README-pypi.md ./COPY Cargo.toml Cargo.lock rust-toolchain.toml ./COPY crates/ crates/COPY headroom/ headroom/diff --git a/e2e/wrap/Dockerfile b/e2e/wrap/Dockerfileindex c3e1e8484..2bf6a2c75 100644--- a/e2e/wrap/Dockerfile+++ b/e2e/wrap/Dockerfile@@ -30,7 +30,7 @@ RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \WORKDIR /build-COPY pyproject.toml uv.lock README.md ./+COPY pyproject.toml uv.lock README.md README-pypi.md ./COPY Cargo.toml Cargo.lock rust-toolchain.toml ./COPY crates/ crates/COPY headroom/ headroom/diff --git a/pyproject.toml b/pyproject.tomlindex 1cb0e02d4..c50ae2f7e 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -5,8 +5,10 @@ build-backend = "maturin"[project]name = "headroom-ai"version = "0.42.0"-description = "The Context Optimization Layer for LLM Applications - Cut costs by 50-90%"-readme = "README.md"+description = "Compress tool outputs, logs, JSON and chat history before each LLM call. Fewer input tokens, same answers; in-process, no API key. Library, proxy and MCP server."+# PyPI renders this file; GitHub renders README.md. Keep the two in step on the+# install commands and the savings claim (README.md "Proof" is the source).+readme = "README-pypi.md"license = "Apache-2.0"requires-python = ">=3.11"authors = [@@ -21,14 +23,26 @@ keywords = ["anthropic","claude","gpt",- "context",- "token",- "optimization",- "compression",- "caching",+ "gemini",+ "token-cost",+ "reduce-tokens",+ "input-tokens",+ "context-window",+ "token-budget",+ "tool-output",+ "tool-results",+ "chat-history",+ "trim-messages",+ "context-compression",+ "prompt-compression",+ "context-engineering",+ "agents",+ "coding-agents",+ "mcp","proxy",- "ai",- "machine-learning",+ "fastapi",+ "langchain",+ "litellm",]classifiers = ["Development Status :: 4 - Beta",