Skip to content

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.

docs(pypi): job-word summary and keywords, and a PyPI-specific README (#4534)

Tejas Chopraa5e68deb6486
diff --git a/Dockerfile b/Dockerfile
index 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.md
new file mode 100644
index 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/Dockerfile
index 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/Dockerfile
index 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.toml
index 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",