mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
feat/https-compose-caddy
2
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
a2bf5ed1ba |
fix(cache): stop prefix transforms from busting the provider cache (#3735)
## Why A `cache_control` marker means the provider has already hashed everything up to and including that point, and is billing it at the **cache-read rate (0.1x)**. Rewriting any of those bytes busts the entry and re-bills the whole prefix at the **write rate (1.25x)** — a 12.5x swing that dwarfs anything the transform saves. Preserving the `cache_control` *field* does **not** preserve the *entry*. The provider keys on content, not on the marker. A transform that copies the marker onto rewritten text reads as cache-safe and is not. The arithmetic: if a transform invalidates the prefix, it has to cut **>92%** of tokens just to break even against leaving the cache intact. Real compaction cuts single-digit percentages. It is never worth it. ## What was wrong **`compact_tool_descriptions`** truncated tool descriptions with no marker check at all. A client that pinned any tool lost its entire tools prefix — and every message behind it — to save a few hundred bytes. **`_compact_system_blocks`** rewrote pinned system text and copied the marker onto the new block. Its own docstring said "`cache_control` and other non-text fields are preserved unchanged", which is true of the field and misleading about the effect. ## What changed - Tool-description compaction is skipped when any tool carries a marker. This mirrors guards that already exist on `_sort_tools_deterministically` and on `any_tool_has_cache_control` in the Rust live zone — this path was simply missed. - System compaction now compacts only blocks **after** the last breakpoint, via a new `_last_cache_control_index` helper. Both transforms behave exactly as before when the client pins nothing — the common case, and the one they were written for. Neither is silent: the skip logs `event=tool_desc_compaction_skipped`. ## Tests New `tests/test_cache_prefix_safety.py` (7 tests) covers both transforms: pinned content stays byte-identical, unpinned content still compacts, and a marker on the final block is a full no-op. Two existing expectations changed, deliberately: - `test_preserves_cache_control` asserted that a pinned block is compacted *and* keeps its marker — precisely the bug. Replaced by `test_marked_block_is_left_byte_identical`, plus a new test that compaction still runs after the breakpoint. - `_make_anthropic_payload_with_long_system` had a single pinned block, so the guard made it a no-op. It now carries a pinned block followed by dynamic content — the shape agentic clients actually send — so the tests still exercise compaction while asserting the pinned block survives. 318 related tests pass; `ruff check` and `ruff format --check` clean. ## Scope Not addressed here, tracked separately: - Savings accounting clamps every component at `max(…, 0)` (`savings_tracker.py:958-965`) and never debits `cache_bust_tokens_lost` from the headline, so a net-negative deployment reports a gain. `cost.py:496` already computes the honest figure and nothing consumes it. - `normalize_message_cache_control` was investigated and left alone: the client-mirroring path is correct, and the legacy fallback deliberately consolidates accumulated replay leftovers (#2375). An earlier attempt to "preserve" markers there broke five existing tests for good reasons. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- ### Known limitation — read before relying on this Adversarial review after the fact found the guard is **narrower than this description implies**. It is not a regression, but it does not fully deliver what the title promises, and that is worth recording rather than discovering later. Anthropic evaluates the cache prefix in the order **tools → system → messages**, so a marker in a *later* section freezes every *earlier* one. Neither new guard accounts for that: 1. **`compact_tools` is unguarded** (`tool_schema_compaction.py`, `compact_tools`). It strips `$schema`/`title`/`examples` and collapses whitespace on every `input_schema`, and it runs **first, on the same array**, one block above the guard that was added. Verified on this branch: a tools array containing a `cache_control`-marked tool is still rewritten, 436 → 374 bytes. A client that pins its tools still gets its whole tools prefix rewritten. 2. **A marker in `system` or `messages` does not stop tool compaction**, even though tools sit inside that prefix. The updated test in this PR encodes exactly this: it pins `system[0]`, then asserts the tools were compacted anyway — so the cached prefix is busted on the very request where the new system guard carefully preserved `system[0]` byte-for-byte. 3. **`_compact_system_blocks` ignores markers in `messages`.** A client whose only breakpoint sits on the last user message has its whole system array inside the cached prefix, yet `frozen_upto == -1` and every block is rewritten. Fixing this needs a signature change — the function only receives `blocks`, not the payload. Net: this helps a client that pins **only** system, and buys little for one that pins its tools. Fixing it properly requires cross-section marker awareness, and the tools-side guard must be widened *after* (2) is fixed, not before — widening it first makes things worse. Merging as incremental progress with the limitation stated. Follow-up tracked separately. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
|
3dd9660d91 |
feat: 3-layer context compression pipeline (L1+L2+L3) (#1405)
## Description > **Default behavior is unchanged:** only L1 (annotation-key stripping) is on by default. L2 (description truncation) and L3 (system-prompt compression) are **opt-in** via `HEADROOM_TOOL_DESC_MAX_CHARS` and `HEADROOM_SYSTEM_COMPACT=1` respectively — instruction-level compression never runs unless an operator explicitly enables it. Verified in `system_compact.py`: `system_compact_enabled()` returns `False` when the env var is unset. Reduces MCP-injected context overhead (~40K tokens / 20% of a 200K window) through a progressive 3-layer compression pipeline. Each layer is independently controlled, fail-safe, and additive — operators can enable L1 only (default) or opt into L2/L3 for deeper savings. ### Layer 1: Tool Schema Annotation Key Stripping (default on) - Strip JSON Schema annotation keys (`$schema`, `title`, `examples`, `deprecated`, `default`, `readOnly`, `writeOnly`) from tool definitions - Normalise whitespace in `description` fields - Zero risk — removes only non-constraint metadata that models ignore - ~8% savings on tool schema size ### Layer 2: Tool Description Truncation (opt-in: `HEADROOM_TOOL_DESC_MAX_CHARS`) - Truncate verbose tool/parameter descriptions to configurable length - Preserves first complete sentence (critical for model tool selection) - Optionally appends second sentence within 1.5× budget - Hard-truncates with `...` if a single sentence exceeds limit - Recursively processes nested `description` fields in `input_schema`/`parameters` - ~43% savings on description text (estimated ~17K tokens) ### Layer 3: System Prompt CCR Compression (opt-in: `HEADROOM_SYSTEM_COMPACT`) - Compress `system[]` content blocks using existing `ContentRouter.compress()` - Only compresses blocks exceeding `HEADROOM_SYSTEM_COMPACT_MIN_CHARS` (default 500) - Preserves `cache_control` markers and non-text blocks - Fail-safe: leaves block unchanged if compression fails or doesn't save size - ~14.5% savings on system prompt (estimated ~3.5K tokens) **Combined savings (all 3 layers enabled): ~40K → ~17K tokens (~58% reduction)** ## 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 - [x] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/proxy/tool_schema_compaction.py` — New shared module: L1 annotation stripping + L2 description truncation with `strip_annotation_keys()` and `truncate_descriptions()` - `headroom/proxy/system_compaction.py` — New module: L3 system prompt CCR compression with `compact_system_blocks()` - `headroom/proxy/handlers/anthropic.py` — Add L1+L2+L3 call sites (after tool assembly, before PRE_SEND) - `headroom/proxy/handlers/openai.py` — Add L1+L2+L3 call sites (parallel to Anthropic handler) - `tests/test_tool_schema_compaction.py` — 42 unit tests covering edge cases, nested schemas, fail-safe behavior - `tests/test_system_compaction.py` — Tests for L3 compression, cache_control preservation, min-chars gating ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ uv run pytest tests/test_tool_schema_compaction.py tests/test_system_compaction.py tests/test_anthropic_compaction_transforms.py -v ===== 49 passed in 4.96s ===== $ uv run ruff check <changed files> All checks passed! $ uv run mypy headroom/proxy/tool_schema_compaction.py headroom/proxy/system_compaction.py headroom/proxy/handlers/anthropic.py headroom/proxy/handlers/openai.py Success: no issues found in 4 source files # Manual verification with HEADROOM_TOOL_DESC_MAX_CHARS=120 # Single tool schema: 548→434 bytes (L1, 20.8% saved) → 315 bytes (L2, 27.4% saved) # Combined: 548→315, 42.5% saved # Full request with proxy: orig=39179 opt=31988 saved=7191 (18.4% compression) ``` ## Real Behavior Proof - Environment: macOS, Python 3.13, headroom proxy v0.28.0, Claude Code CLI - Exact command / steps: 1. Start proxy with `HEADROOM_TOOL_DESC_MAX_CHARS=120 HEADROOM_SYSTEM_COMPACT=1 headroom proxy` 2. Route Claude Code traffic through proxy 3. Check `/stats` endpoint for `transforms_applied` and byte savings - Observed result: L1/L2/L3 transforms applied correctly, ~58% token reduction on MCP-heavy context - Not tested: Windows, production deployment ## 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] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] 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 - [ ] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) N/A ## Additional Notes - L2 and L3 are **opt-in** via env vars. Default behavior is unchanged (only L1 active). - All layers have fail-safe fallbacks — if compaction fails or doesn't reduce size, the original payload passes through unchanged. - The Anthropic handler now appends `anthropic:tool_schema_compaction` (L1), `anthropic:tool_desc_compaction` (L2), and `anthropic:system_compact` (L3) to `transforms_applied`, so `/stats` and transformation accounting are no longer blind to compression that changed the request. Covered by handler-level e2e regression in `tests/test_anthropic_compaction_transforms.py` (positive + negative cases). The earlier follow-up #1423 is superseded — no longer needed. --------- Signed-off-by: lg320531124 <lg320531124@users.noreply.github.com> Co-authored-by: lg320531124 <lg320531124@users.noreply.github.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |