From f9f3162d388315bfa0b338d9eda8cc5af71dc200 Mon Sep 17 00:00:00 2001 From: Shubham Srivastava Date: Tue, 14 Jul 2026 23:40:28 +0530 Subject: [PATCH] docs(proxy): document HEADROOM_SAVINGS_PROFILE and correct --mode default (#2031) (#2040) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description `HEADROOM_SAVINGS_PROFILE` is an implemented env var (`headroom/agent_savings.py`) that selects a named profile bundling Headroom's whole compression posture (proxy mode, keep-ratio, which messages are compressed, `force_kompress`, etc.) at proxy startup. It was entirely undocumented — `grep` over `docs/` found zero mentions. Related, the proxy docs were **misleading about the default optimization mode**: `docs/content/docs/proxy.mdx` stated `--mode` defaults to `token`, but the code default is `cache`: ```python # headroom/cli/proxy.py — the Click option has no default @click.option("--mode", default=None, ...) # ... mode resolution (default is CACHE): effective_mode = normalize_proxy_mode(mode or os.environ.get("HEADROOM_MODE") or PROXY_MODE_CACHE) ``` A bare `headroom proxy` (no `--mode`, no `HEADROOM_MODE`) runs in **cache** mode, and the default `coding` savings profile also sets `proxy_mode="cache"` — which is exactly what the issue reporter found confusing. This documents `HEADROOM_SAVINGS_PROFILE` and corrects the `--mode` default rows so the doc is accurate and internally consistent. Closes #2031 ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made `docs/content/docs/proxy.mdx` only: - Corrected the `--mode` default in the Core-options table and the Context-management table (`token` → `cache`), each pointing to the new Savings profiles section for the reason. - Added a `### Savings profiles` section documenting: the `HEADROOM_SAVINGS_PROFILE` env var; a table of the four built-in profiles (`coding` default, `balanced` fallback, `agent-90`, `general`) with target savings, mode, and `force_kompress`; the unset→`coding` default; the unknown-value→`balanced` warning-and-fallback (proxy never fails to start); and the mode precedence (explicit `--mode` > `HEADROOM_MODE` seeded by a profile > `cache` default), with an example. No code change. Every documented value is pinned to `headroom/agent_savings.py` (profile definitions) and `headroom/cli/proxy.py` (default-mode resolution). ## Testing - [x] Unit tests not run; docs-only source verification performed - [x] Linting not run; docs-only MDX/source verification performed - [x] Type checking not applicable; no Python code changed - [x] New tests not applicable; documentation-only correction - [x] Manual testing performed ### Test Output Docs-only change; verification is cross-checking every documented value against the source of truth: ```text $ grep -n "DEFAULT_PROFILE = \|FALLBACK_PROFILE = " headroom/agent_savings.py 14:FALLBACK_PROFILE = "balanced" 18:DEFAULT_PROFILE = "coding" # profile modes / knobs (agent_savings.py): # coding → proxy_mode="cache", force_kompress=False, target_ratio=None (emergent) # balanced → proxy_mode="token", force_kompress=False, target_ratio=0.30 # agent-90 → proxy_mode="token", force_kompress=True, target_ratio=0.10 # general → proxy_mode="token", force_kompress=False, target_ratio=None (emergent) $ grep -n "effective_mode\|PROXY_MODE_CACHE" headroom/cli/proxy.py # effective_mode = normalize_proxy_mode(mode or os.environ.get("HEADROOM_MODE") or PROXY_MODE_CACHE) # → confirms the real default optimization mode is cache, not token ``` MDX sanity: code fences balance (even count) and the `### Savings profiles` heading slugifies to `#savings-profiles`, matching the two in-page anchor links added to the mode rows. ## Real Behavior Proof - **Environment:** Windows 11; docs source inspected against the working tree at the current `main` base. - **Exact command / steps:** Each documented fact is grounded in code — profile names, modes, `force_kompress`, and target ratios come from `headroom/agent_savings.py:_PROFILES`; the default profile (`coding`) from the `os.environ.get("HEADROOM_SAVINGS_PROFILE") or "coding"` reads in `headroom/cli/proxy.py` and `headroom/proxy/server.py`; the `cache` default mode from `headroom/cli/proxy.py`'s `mode or HEADROOM_MODE or PROXY_MODE_CACHE`; the unknown-value fallback from `get_agent_savings_profile` (`agent_savings.py`). - **Observed result:** The new section's table and prose match those sources exactly, and the previously-wrong `--mode` default rows now state `cache`. - **Not tested:** A live render of the Fumadocs/Next.js docs site (no local docs build run here) — the change is MDX-syntax-valid (balanced fences, well-formed table, standard heading-anchor slug). ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] Code comments not applicable; documentation-only change - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] Tests not applicable; docs-only facts verified against source - [x] New and existing unit tests pass locally with my changes - [x] CHANGELOG not applicable; documentation-only correction ## Screenshots (if applicable) N/A (docs prose/table addition; a rendered screenshot can be added if the docs site is built for preview). ## Additional Notes - Test/tests-added checklist items are N/A — this is a documentation-only change. - Out of scope (intentionally): the `--mode` Click **help text** in `headroom/cli/proxy.py` also says "default: token" and is likewise inaccurate, but correcting Python help text is a code change beyond this docs issue — noted as a possible follow-up. --------- Co-authored-by: JerrettDavis --- docs/content/docs/proxy.mdx | 26 +++++++++++++++++++++++--- headroom/cli/proxy.py | 2 +- tests/test_cli_proxy_improvements.py | 5 +++++ 3 files changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdx index 8747cd0a6..78a358348 100644 --- a/docs/content/docs/proxy.mdx +++ b/docs/content/docs/proxy.mdx @@ -37,7 +37,7 @@ Telemetry is **off by default** (opt-in). Opt in with `HEADROOM_TELEMETRY=on` or | `--max-connections` | `500` | Maximum upstream HTTP connections | | `--max-keepalive` | `100` | Maximum upstream keep-alive connections | | `--http-proxy` | None | HTTP proxy URL for upstream provider requests only; HTTPS provider APIs use CONNECT | -| `--mode` | `token` | Optimization mode: `token` prioritizes compression, `cache` preserves provider prefix-cache stability | +| `--mode` | `cache` | Optimization mode: `token` prioritizes compression, `cache` preserves provider prefix-cache stability. Default is `cache` (see [Savings profiles](#savings-profiles)) | | `--no-optimize` | `false` | Disable optimization (passthrough mode) | | `--no-cache` | `false` | Disable semantic caching | | `--no-rate-limit` | `false` | Disable rate limiting | @@ -65,8 +65,8 @@ Avoid setting process-wide variables such as `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_P | Option | Default | Description | |--------|---------|-------------| -| `--mode token` | `token` | Prioritize token compression. This is the default. | -| `--mode cache` | `token` | Preserve prior turns to maximize provider prefix-cache hit rate. | +| `--mode token` | | Prioritize token compression; prior turns may be rewritten for maximum savings. | +| `--mode cache` | default | Freeze prior turns to maximize provider prefix-cache hit rate. This is the effective default (see [Savings profiles](#savings-profiles)). | | `--intercept-tool-results` | `false` | Opt into tool-result interceptors such as ast-grep Read outlining. | | `--no-read-lifecycle` | `false` | Disable stale/superseded Read-output compression. | | `--code-aware` / `--no-code-aware` | disabled | Enable or disable AST-based code compression. Requires `headroom-ai[code]`. | @@ -90,6 +90,26 @@ headroom proxy --mode token headroom proxy --mode cache ``` +### Savings profiles + +`HEADROOM_SAVINGS_PROFILE` selects a named profile that seeds Headroom's whole compression posture — proxy mode, keep-ratio, which messages are compressed, and `force_kompress` — at proxy startup. It is read by `headroom proxy` and by the `headroom wrap` subprocesses. When unset, the default profile is `coding`. + +| Profile | Target savings | Mode | Notes | +|---------|----------------|------|-------| +| `coding` | emergent (~50%) | `cache` | **Default.** Delta-only compression at ~0 prefix-cache busts; never lossy-compresses file reads. | +| `balanced` | ~70% | `token` | Moderate compression with structural compaction. Also the fallback for an unknown profile name. | +| `agent-90` | ~90% | `token` | Aggressive; pins a `0.10` keep-ratio and forces Kompress. | +| `general` | emergent (~60%) | `token` | Non-coding workloads. | + +An unrecognized `HEADROOM_SAVINGS_PROFILE` value logs a warning and falls back to `balanced` — the proxy never fails to start over a bad profile name. See `headroom/agent_savings.py` for each profile's full set of knobs. + +Because the default `coding` profile uses **cache** mode (and the proxy's own default mode is also `cache`), Headroom runs in cache mode out of the box. Mode precedence: an explicit `--mode` wins, otherwise `HEADROOM_MODE` (which a profile seeds), otherwise the `cache` default. To run token mode, pass `--mode token` or choose a token-mode profile: + +```bash +# Aggressive ~90% token-savings profile +HEADROOM_SAVINGS_PROFILE=agent-90 headroom proxy --port 8787 +``` + ### Optional features | Option | Default | Description | diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.py index 0c60c5da4..c97cc5868 100644 --- a/headroom/cli/proxy.py +++ b/headroom/cli/proxy.py @@ -247,7 +247,7 @@ def dashboard(port: int, no_open: bool) -> None: case_sensitive=False, ), help=( - "Optimization mode (default: token).\n" + "Optimization mode (default: cache).\n" " token — prioritize compression; prior turns may be rewritten for max savings.\n" " cache — freeze prior turns to maximise provider prefix-cache hit rate.\n" "Legacy aliases (token_mode, token_savings, token_headroom, cache_mode, " diff --git a/tests/test_cli_proxy_improvements.py b/tests/test_cli_proxy_improvements.py index d6787da13..e400ae35b 100644 --- a/tests/test_cli_proxy_improvements.py +++ b/tests/test_cli_proxy_improvements.py @@ -478,6 +478,11 @@ class TestHelpTextCompleteness: def test_help_contains_mode_option(self, runner: CliRunner) -> None: assert "--mode" in self._help(runner) + def test_help_reports_cache_as_default_mode(self, runner: CliRunner) -> None: + out = self._help(runner) + assert "Optimization mode (default: cache)" in out + assert "Optimization mode (default: token)" not in out + def test_help_contains_workers_option(self, runner: CliRunner) -> None: assert "--workers" in self._help(runner)