mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
## Description Agent-readiness crawlers and coding agents read `AGENTS.md` before anything else, and this repo had none (nor a `CLAUDE.md`), even though `headroom learn` writes them for other projects. In the recorded sandbox runs both Claude Code and Codex read the installed source to learn the result fields and `HEADROOM_OFFLINE`, and Codex fetched `github.com/headroom-sdk/headroom` from memory (404). Depends on #4529 for the `/docs/fastapi` link. ## Type of Change - [x] Documentation update ## Changes Made - `AGENTS.md`, block 1 "to use Headroom in an app": install, `compress()`, result fields, offline semantics, the zero-network check, the ASGI-middleware caveat, the canonical repo and the two wrong URLs agents remember. - Block 2 "to change this repo": layout, setup and check commands (from `CONTRIBUTING.md` and the `Makefile`), Conventional Commits, no `CHANGELOG.md` edits, Real behavior proof, one docs site, API names in examples must exist in `headroom/compress.py`, one savings claim, and the `version-sync.py` / `verify-versions.py` pair. ## Testing - [x] Manual testing performed ### Test Output ```text 20031 -> 95 FATAL kept: True curl -I github.com/chopratejas/headroom -> 301 https://github.com/headroomlabs-ai/headroom curl -I github.com/headroom-sdk/headroom -> 404 ``` ## Real Behavior Proof - Environment: macOS arm64, published `headroom-ai==0.42.0` wheel in a clean venv. - Exact command / steps: ran the zero-network one-liner from the file verbatim; checked every command in block 2 against `Makefile` targets (`ci-precheck`, `ci-precheck-rust`, `install-git-hooks`) and `CONTRIBUTING.md`; `curl -I` on `github.com/chopratejas/headroom` (301 to headroomlabs-ai) and `github.com/headroom-sdk/headroom` (404). - Observed result: `20031 -> 95 FATAL kept: True`; all named targets exist. - Not tested: nothing executes this file. ## 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.4 KiB
3.4 KiB
AGENTS.md
If you landed here to use Headroom in an app
The PyPI package is headroom-ai; the import and the CLI are headroom.
pip install headroom-ai
from headroom import compress
result = compress(messages, model="gpt-4o") # OpenAI or Anthropic message dicts
# send result.messages instead of messages; log result.tokens_before / tokens_after / tokens_saved
In-process, no API key, no model download. HEADROOM_OFFLINE=1 makes the run
zero-network (no update check, no model or pricing-table downloads, no beacon).
Verify without a provider key:
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))"
- FastAPI example: https://docs.headroomlabs.ai/docs/fastapi
- Full docs index for agents: https://docs.headroomlabs.ai/llms.txt (hand-curated subset:
llms.txtin this repo) - Coding agents (Claude Code, Codex, Cursor, Copilot):
uv tool install --python 3.13 "headroom-ai[all]"thenheadroom wrap claude headroom.integrations.asgi.CompressionMiddlewareis for apps that serve/v1/chat/completions-style routes, not for an app that calls a provider; usecompress()for that- Canonical repo: https://github.com/headroomlabs-ai/headroom.
github.com/chopratejas/headroomredirects here; there is noheadroom-sdkorg. The PyPI distribution namedheadroomis a different project.
If you are changing this repo
- Layout: Python package in
headroom/, Rust core and PyO3 extension incrates/(built by maturin), TypeScript SDK insdk/typescript/, docs site (Next.js + Fumadocs) indocs/content/docs/, agent plugins inplugins/, examples inexamples/. - Setup:
uv sync --extra devandmake install-git-hooks(pre-commit, commitlint, pre-push). Python checks:uv run ruff check .,uv run ruff format .,uv run pytest. Rust checks:make ci-precheck-rust. All gates:make ci-precheck. SeeCONTRIBUTING.md. - Commits and PR titles are Conventional Commits (
feat:,fix:,docs:, ...). Never editCHANGELOG.md; release-please writes it from PR titles. - Every external PR needs a "Real behavior proof" section (setup, exact commands, observed output, what was not tested). Bug fixes need a test that fails before the fix.
- One docs site:
docs/, deployed by Vercel to docs.headroomlabs.ai.wiki/and thegh-pagesbranch are not published; do not add content there. - Public API examples in
README.md,llms.txt,AGENTS.mdanddocs/must use names that exist inheadroom/compress.py(compress,CompressResult.messages,.tokens_before,.tokens_after,.tokens_saved,.compression_ratio,.transforms_applied). - Savings claims anywhere in the repo must match the measured table under "Proof" in
README.md: 21-57% on the four agent scenarios, 90%+ on repeated JSON arrays and log lines, little on prose. - Version-carrying files (
pyproject.toml, plugin and marketplace manifests,sdk/typescript/package.json,server.json) are kept in step byscripts/version-sync.pyand gated byscripts/verify-versions.py; add any new one to both.