Files
headroom/llms.txt
bb8d18a56a feat(wrap): add headroom wrap droid for Factory Droid (#4143)
## Description

Add `headroom wrap droid` so Factory subscription traffic, including
Droid Core, can be compressed on the existing Factory plan.

Droid ignores `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` for
Factory-served models. It honors `FACTORY_API_BASE_URL`. This wrapper
points that at the local proxy and gives the proxy a Factory upstream
(`--factory-api-url` / `FACTORY_TARGET_API_URL`, default
`https://api.factory.ai`).

With a Factory upstream configured the proxy registers:

- `POST /api/llm/a/v1/messages` — compressed with the existing Anthropic
pipeline and forwarded to `{factory}/api/llm/a/v1/messages`. A
client-sent `x-headroom-base-url` is ignored. `x-headroom-*` headers are
stripped. Operator Anthropic extra headers are withheld from the
untrusted Factory host.
- Every other `/api/*` path — forwarded verbatim to Factory, except
Hermes Studio's scoped prefixes and requests that name their own
`x-headroom-base-url`.

Nothing outside `/api/` is sent to Factory.
`select_passthrough_base_url` and `upstream_trust` are untouched, so a
leftover Codex, Claude, or Copilot config pointed at a Factory-mode
proxy keeps its own upstream and credentials. That is the deliberate
difference from https://github.com/headroomlabs-ai/headroom/pull/2352,
which is still open and which this does not close. #2352 sends every
unrouted request on a Factory-mode proxy to Factory.

`wrap droid` writes no Droid config. It threads `factory_api_url`
through the existing proxy-reuse logic. With `--no-proxy` it refuses
unless `/health` shows a Headroom proxy serving the same Factory
upstream. OpenAI-shaped `/api/llm/o/*` traffic is forwarded
uncompressed. Those routes are deferred.

This commit is `74c889fb` rebased onto current `main` (`0dd8e0b5`). The
only conflicts were `docs/content/docs/meta.json` (kept both the new
`hermes` page and `droid`) and the `--no-proxy` branch in
`headroom/cli/wrap.py` (kept upstream's OpenAI upstream check and the
Factory check).

Refs #2351

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom wrap droid` sets `FACTORY_API_BASE_URL` to the local proxy
and resolves the Factory upstream from `--factory-api-url`, then
`FACTORY_API_BASE_URL`, then `https://api.factory.ai`. Loopback,
credential, query, and fragment URLs are rejected.
- Factory inference and `/api/*` passthrough routes are registered only
when a Factory upstream is configured. The default proxy is unchanged.
- `/health` reports `factory_api_url`.
- Docs: `docs/content/docs/droid.mdx`.

## Testing

- [x] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

Rebased tree `/home/hermes/workspace/headroom-rebase` at `0dd8e0b5`,
importing that tree via `PYTHONPATH` and the existing venv at
`/home/hermes/workspace/headroom/.venv` (Python 3.11.16).

```text
tests/test_cli/test_wrap_droid.py ............................           [ 31%]
tests/test_provider_droid_runtime.py ................................    [ 66%]
```

60 passed. Those are the wrap launch-env tests and the Factory runtime
tests.

`tests/test_proxy/test_factory_decoy_proof.py` did not complete in this
worktree. The proxy refuses to start because `headroom._core` is not
built here (`ModuleNotFoundError`, exit 78). Setting
`HEADROOM_REQUIRE_RUST_CORE=false` still did not finish within 180s. The
decoy proof (decoy upstream stays silent, Factory stand-in receives the
inference request, spoofed `x-headroom-*` headers, REST passthrough,
`--no-proxy` refusals) was written for this change and passed in the
pre-rebase review session. It was not re-run to a green result after
this rebase.

`ruff` and `mypy` were not re-run after the rebase.

## Real Behavior Proof

- Environment: Linux, Python 3.11.16, rebased commit `0dd8e0b5` on top
of `upstream/main` `8c1beb20`. No Factory token. No call to
`api.factory.ai`.
- Exact command / steps:
`PYTHONPATH=/home/hermes/workspace/headroom-rebase
/home/hermes/workspace/headroom/.venv/bin/python -m pytest
tests/test_cli/test_wrap_droid.py tests/test_provider_droid_runtime.py`
- Observed result: 60 passed.
- Not tested: a live Factory subscription, `droid` itself, the socket
decoy proof on this rebased commit (blocked locally by the missing Rust
extension), `ruff`, `mypy`, and CI on GitHub.

## Runtime Rollout Safety

- Rollout-managed feature(s): none. Factory routes register only when
`factory_api_url` / `--factory-api-url` is set.
- Minimum rollout channel: stable. Default proxy behavior is unchanged.
- Stable/default behavior changed: no, unless a Factory upstream is
configured.
- Kill switch / disable path: do not pass `--factory-api-url` and do not
set `FACTORY_TARGET_API_URL`. `wrap droid` is opt-in.
- Unsafe override required: no.
- Qualification impact: none on the default proxy.
- Rollback path: revert this commit. No config is written into Droid.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

The pre-rebase commit `74c889fb` was approved by a fresh Claude Opus 5.5
high review with an empty blocking list. This commit is that change
rebased onto current main. The two conflict resolutions are described
above and have not had a second Opus pass.

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

Does not close #2352. That PR is the prior attempt. This one is a
current-main rebuild with the catch-all leak removed: only `/api/*` is
forwarded to Factory.

akbarkanso is not a Headroom maintainer. Please do not expect this
account to merge.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4143"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

### Maintainer current-main requalification

Exact head `e28dfe6422dfcb9b2cbd5ce0fe673196d3b6ad40`, upstream main
`e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`.

Updated against upstream/main e4a60ed7. Resolved the OpenAI passthrough
overlap by retaining main's prepared-request/model/timing parameters and
soft-passthrough guard alongside the contributor's verbatim flag;
generic compression requires both guards to permit it. Re-reviewed
Factory direct-routing/verbatim semantics and existing discussion. All
93 wrapper/runtime/Factory passthrough/socket-decoy tests pass with
existing native extension; changed-file Ruff lint/format and whitespace
checks pass. No contributor routing policy was rewritten.

Independently reran the official Droid1.3.0 CLI with isolated home,
dummy API key, actual Headroom/Uvicorn proxy and controlled LAN HTTP
upstream on this exact combined head. The CLI consumed the controlled
Anthropic SSE reply and exited zero with HEADROOM_QUALIFICATION_OK. The
message request preserved dummy Authorization and forwarded no
x-headroom headers. This is controlled transport/runtime qualification,
not a live Factory subscription or savings benchmark, and not a fresh
native build. Applied shared test-only Gemini fixture repair for
independently established main failures; all ten cases pass. Formal
approval awaits exact-head hosted qualification.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `7dd0725a9ac4dd8103dedf78552ceca886fc3620`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Clean mechanical merge with upstream main
c01cf07d94. Re-reviewed current
Factory/Droid routing and author/Devin discussion. Factory inference
retains force_direct to bypass translating backends; Factory passthrough
retains verbatim alongside main's soft-passthrough/prepared-request
guards. Hermes scoped proxy prefixes remain excluded from Factory
dispatch; the existing standalone environment precedence is
intentionally consistent with sibling targets, while Click/wrap retain
flag precedence. No contributor routing policy rewritten.

Fresh wrapper/runtime/Factory passthrough/socket-decoy/Hermes
verification: 100 passed, with test-client/runpy warnings only. All 14
changed Python files pass Ruff lint/format; main-relative whitespace
clean and owned tree clean. Tests use the current-main native DLL for
local startup. Earlier official Droid 1.3.0 controlled-upstream runtime
proof remains scoped to its original run; no fresh official CLI replay,
Factory subscription inference, savings benchmark or branch-native build
is claimed. No new blocker found; approval awaits exact-head hosted
checks. Nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-07 20:48:53 -06:00

88 lines
8.7 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Headroom
> Headroom (`headroom-ai`) compresses tool outputs, logs, JSON, files, RAG chunks and chat history before each LLM call. Same answers, fewer input tokens. Measured: 21–57% fewer input tokens on four agent scenarios, 90%+ on repeated JSON arrays and log lines, little on prose. Library (no API key, in-process), proxy, and MCP server. Apache 2.0, local-first.
Headroom is shipped as a Python package (`headroom-ai`), a TypeScript package (`headroom-ai`), an OpenAI + Anthropic-compatible HTTP proxy (`headroom proxy`), and an MCP server (`headroom_compress`, `headroom_retrieve`, `headroom_stats` tools). All four modes use the same compression pipeline: per-content-type compressors (JSON, code, logs, diffs, text) feed into a Compress-Cache-Retrieve (CCR) store so compression stays reversible — the LLM can ask for the original whenever it wants.
The canonical, always-current documentation index lives at the docs site below. If you can fetch one URL, fetch that one; the entries here are a hand-curated subset.
## Canonical docs (start here)
- [Live llms.txt (full doc index)](https://docs.headroomlabs.ai/llms.txt): Auto-generated index of every doc page with descriptions.
- [Live llms-full.txt (every doc page concatenated)](https://docs.headroomlabs.ai/llms-full.txt): One Markdown blob containing every doc page. Use when you can spend the tokens for full context.
- [Docs site](https://docs.headroomlabs.ai/docs): Human-browsable docs with search.
- [GitHub repo](https://github.com/headroomlabs-ai/headroom): Source, issues, releases.
- [PyPI package](https://pypi.org/project/headroom-ai/): Python install.
- [npm package](https://www.npmjs.com/package/headroom-ai): TypeScript install.
## Install (copy-paste-runnable)
- Python: `pip install headroom-ai` is enough for `compress()`; add `[proxy]` for the HTTP proxy and `headroom wrap`, `[all]` for the CLI/proxy feature set. PyTorch-backed `[ml]`, `[memory]`, `[evals]`, and `[voice]` are separate opt-ins.
- TypeScript / Node: `npm install headroom-ai` (or `pnpm add headroom-ai`, `bun add headroom-ai`)
- Docker local: `docker run --rm -p 127.0.0.1:8787:8787 ghcr.io/headroomlabs-ai/headroom:latest --host 0.0.0.0`
- Run the proxy: `headroom proxy --port 8787` then point any client at `http://127.0.0.1:8787`
- Wrap an agent in one command: `headroom wrap claude` (also: `codex`, `grok`, `copilot`, `cursor`, `aider`, `opencode`, `cline`, `continue`, `goose`, `openhands`, `openclaw`, `vibe`, `omp`, `zcode`, `droid`)
- Zero-network check, no 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))"` (prints roughly `20000 -> 95 FATAL kept: True`)
## By task (plain-language jobs this package does)
- Reduce input tokens / cut LLM token cost in a Python app: `pip install headroom-ai`, then `from headroom import compress; result = compress(messages, model=...)`, send `result.messages`. No API key, no model download. [FastAPI example](https://docs.headroomlabs.ai/docs/fastapi)
- Trim or compress large tool outputs / tool results before they re-enter the context: the same `compress()` call; tool messages are compressed, error lines, stack traces, first/last items and statistical outliers are kept. [Text & logs](https://docs.headroomlabs.ai/docs/text-and-logs) · [SmartCrusher](https://docs.headroomlabs.ai/docs/smart-crusher)
- Keep a long chat history inside the context window: `compress(messages, model=..., model_limit=N)` compresses harder as the prompt approaches N tokens; it never drops messages. [Context management](https://docs.headroomlabs.ai/docs/context-management)
- Compress RAG chunks / search results / database rows: the same call; JSON arrays are compressed statistically. Put the data in a `tool` message: user messages are left alone by default (`compress_user_messages=True` opts them in). [SmartCrusher](https://docs.headroomlabs.ai/docs/smart-crusher)
- Cut the token spend of Claude Code / Codex / Cursor without code changes: `headroom wrap <agent>` or `headroom proxy`. [Proxy](https://docs.headroomlabs.ai/docs/proxy)
- Give an MCP host a compress tool: `pip install "headroom-ai[mcp]"` then `headroom mcp install`. [MCP](https://docs.headroomlabs.ai/docs/mcp)
- Run fully offline / air-gapped: set `HEADROOM_OFFLINE=1`. [Security model](https://docs.headroomlabs.ai/docs/security-model)
Not a fit: short conversational prompts, prose, already-dense payloads.
## Entry points
- [Quickstart](https://docs.headroomlabs.ai/docs/quickstart): 5-minute end-to-end (install → compress → call the model).
- [Installation](https://docs.headroomlabs.ai/docs/installation): All install paths, extras, Docker tags, env vars.
- [Proxy server](https://docs.headroomlabs.ai/docs/proxy): Run as a local HTTP proxy in front of OpenAI / Anthropic / Gemini.
- [MCP server](https://docs.headroomlabs.ai/docs/mcp): `headroom_compress`, `headroom_retrieve`, `headroom_stats` for Claude Code / Cursor / any MCP host.
- [API reference](https://docs.headroomlabs.ai/docs/api-reference): Python + TypeScript `compress()` API.
## How it works
- [How compression works](https://docs.headroomlabs.ai/docs/how-compression-works): Three-stage pipeline + automatic content routing.
- [SmartCrusher](https://docs.headroomlabs.ai/docs/smart-crusher): Statistical JSON / array compression (90%+ on repeated arrays; keeps errors, outliers and boundaries).
- [Code compression](https://docs.headroomlabs.ai/docs/code-compression): AST-aware via tree-sitter (preserves imports, signatures, types).
- [Text & log compression](https://docs.headroomlabs.ai/docs/text-and-logs): Search results, build logs, diffs.
- [CCR (reversible)](https://docs.headroomlabs.ai/docs/ccr): Compress-Cache-Retrieve — originals never deleted; LLM retrieves on demand.
## SDK / framework integrations
- [Anthropic SDK](https://docs.headroomlabs.ai/docs/anthropic-sdk): `withHeadroom(anthropic)` wrapper.
- [OpenAI SDK](https://docs.headroomlabs.ai/docs/openai-sdk): `withHeadroom(openai)` wrapper.
- [Vercel AI SDK](https://docs.headroomlabs.ai/docs/vercel-ai-sdk): Middleware + `withHeadroom()`.
- [LangChain](https://docs.headroomlabs.ai/docs/langchain): Chat models, memory, retrievers, agents.
- [Agno](https://docs.headroomlabs.ai/docs/agno): Model wrapping + observability hooks.
- [Strands](https://docs.headroomlabs.ai/docs/strands): Model wrapping + hook-based tool output compression.
- [LiteLLM](https://docs.headroomlabs.ai/docs/litellm): Single callback; works with all 100+ LiteLLM providers.
## Memory & cross-agent state
- [Persistent memory](https://docs.headroomlabs.ai/docs/memory): Per-project SQLite + HNSW vector store. No cross-project bleed (GH #462).
- [SharedContext](https://docs.headroomlabs.ai/docs/shared-context): Compressed inter-agent context handoffs.
- [Failure learning](https://docs.headroomlabs.ai/docs/failure-learning): Offline analysis writes corrections to `CLAUDE.local.md` (default, gitignored) or `CLAUDE.md` (shared) / `AGENTS.md` / `GEMINI.md`.
## Operations
- [Configuration](https://docs.headroomlabs.ai/docs/configuration): Env vars, config file, per-call overrides.
- [Benchmarks](https://docs.headroomlabs.ai/docs/benchmarks): Token-savings numbers across content types.
- [Troubleshooting](https://docs.headroomlabs.ai/docs/troubleshooting): Common failure modes and fixes.
- [Limitations](https://docs.headroomlabs.ai/docs/limitations): What Headroom won't do well today.
## Headroom for Teams
Headroom OSS is a framework built to show what's possible on one developer's laptop, so it saves less than Headroom Enterprise. Enterprise adds more cost savings, tokens secured, on premise deployment, deep attribution and many more features. Teams and enterprises: contact hello@headroomlabs.ai or visit https://headroomlabs.ai.
- [Headroom for Teams](https://docs.headroomlabs.ai/docs/teams): Open source vs Enterprise, and how to reach us.
- [headroomlabs.ai](https://headroomlabs.ai): Company site. Email hello@headroomlabs.ai.
## Licensing
Apache 2.0. Use commercially, modify, redistribute. Data stays on the user's machine when running the library, proxy, or MCP server locally. An anonymous usage beacon is **on by default**: it reports compression ratios, counters, provider and model IDs, OS and architecture, and never prompts, completions, code or file paths. Turn it off with `HEADROOM_BEACON=off`, `DO_NOT_TRACK=1`, or `HEADROOM_OFFLINE=1`. See [Telemetry](https://github.com/headroomlabs-ai/headroom#telemetry).