## Description
Agents that install from PyPI read the package page plus the installed
code and nothing else; in both recorded runs they had to read venv
source to learn the result fields and `HEADROOM_OFFLINE`. The GitHub
README is written for a browser: hero image, badges, perk banner,
relative links that break off GitHub, and a first install command that
pulls `[all]`. The summary ("Cut costs by 50-90%") disagrees with the
README's own measured table, and none of the words in the three web
queries that currently return nothing of ours (tool outputs, chat
history, token cost, fastapi) appear in the summary or keywords.
Depends on #4529 for the `/docs/fastapi` link. Takes effect on PyPI with
the next release.
## Type of Change
- [x] Documentation update
## Changes Made
- `README-pypi.md` (new): no-key `compress()` path, zero-network check
with expected output, result fields, offline semantics (beacon is
proxy/MCP-side), coding-agent path, extras explained, "the PyPI
distribution named `headroom` is a different project".
- `pyproject.toml`: `readme = "README-pypi.md"`, job-word `description`
without a percentage, keywords extended with the job words.
- `Dockerfile`, `e2e/wrap/Dockerfile`, `e2e/init/Dockerfile`: `COPY` the
new readme next to `README.md` (all three build the wheel from
`pyproject.toml`, so maturin needs the declared readme in the build
context); `Dockerfile`'s `source_digest` inputs include it too.
## Testing
- [x] Manual testing performed
### Test Output
```text
uvx maturin sdist -o /tmp/sdist: Built source distribution headroom_ai-0.42.0.tar.gz
tar tzf: headroom_ai-0.42.0/README-pypi.md present
PKG-INFO: Summary: Compress tool outputs, logs, JSON and chat history before each LLM call. ... / Description-Content-Type: text/markdown
```
## Real Behavior Proof
- Environment: macOS arm64, `uvx maturin sdist` on this branch.
- Exact command / steps: build the sdist, list it, read `PKG-INFO`.
- Observed result: `headroom_ai-0.42.0/README-pypi.md` is in the
tarball; `PKG-INFO` has the new `Summary:`, `Description-Content-Type:
text/markdown`, the README body and the new keywords. The one-liner in
the file was run against the published 0.42.0 wheel: `20031 -> 95 FATAL
kept: True`.
- Not tested: the Docker images themselves (CI's docker and e2e jobs
cover them); the wheel build (maturin embeds the same `readme` field;
nothing in `.github/workflows` or `scripts/` pins `README.md` as the
readme).
## Runtime Rollout Safety
- Rollout-managed feature(s): none; documentation and metadata only, no
runtime code path changes
- Minimum rollout channel: n/a
- Stable/default behavior changed: no
- Kill switch / disable path: n/a (revert the PR)
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
3.2 KiB
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
pip install headroom-ai
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:
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)
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.