mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-10 14:27:00 -04:00
## Description
A data-driven push for better compression savings without accuracy loss,
in four parts: expose and tune the Rust compressor knobs, harden the CCR
retrieval store, add traffic-audit tooling that sizes opportunities from
real transcripts, and introduce **read maturation** — a new,
live-validated mechanism that compresses Read outputs *before* they ever
enter the provider prefix cache.
## Type of Change
- [x] 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
### 1. Rust compressor extraction
- Expose `lossless_min_savings_ratio` end-to-end and lower the default
0.30 → 0.15 (lockstep across Rust, PyO3, and both Python config classes)
so the lossless Table/CSV compaction path wins more often.
- Expose the `CompactConfig` heuristics (core-field fraction,
heterogeneity ratio, flatten cap, bucket bounds) through PyO3 + Python.
- `SearchCompressor` grouped-by-file output (`rg --heading` style — path
once per file instead of per match). Library default off; the proxy
enables it in token mode.
- Complete `factor_out_constants`: constant fields now emit once in a
`_constant_fields` sentinel with slim rows (defensive per-item value
match; default off).
- `ContentRouter` accepts a SmartCrusher config override and the
search-grouping knob.
### 2. CCR store hardening
- Session-scale TTL: 300s → 1800s (CCRConfig, CompressionEntry,
CompressionStore, Rust `DEFAULT_TTL` — lockstep).
- **SQLite is the default CCR backend** (`~/.headroom/ccr_store.db`,
WAL): survives proxy restarts and is shared across workers.
`HEADROOM_CCR_BACKEND=memory` opts out.
- Multi-worker safety: `busy_timeout`, and corruption detection narrowed
so transient `SQLITE_BUSY` errors can never trigger database deletion.
- Data-at-rest hygiene: `chmod 600` on db + sidecars, expired rows swept
at open.
- Retrieval-miss messages are actionable (re-read the file / re-run the
command).
### 3. Traffic audit tooling (measure before tuning)
- `headroom audit-reads`: sizes Read opportunities from local Claude
Code transcripts (read share, stale %, line-number overhead, context
residency, cache-death windows).
- `--simulate-maturation`: Mechanism B risk sizing (re-read rates,
never-touched-again share, quiesce coverage, at-risk edits).
- `--codex`: shell-read classifier for Codex transcripts (rtk-wrapper
aware, workdir resolution).
- Findings that shaped this PR (81 sessions): Reads are 67% of tool
bytes; median Read lingers 118 turns (~13x lifetime cost); a prototyped
repeat-Read dedup measured 0.1% and was **removed** rather than shipped
as dead code.
### 4. Read maturation (Mechanism B) — experimental, default OFF
- Activity-based: a fresh large Read is held **out** of the provider
cache (trailing breakpoint relocated before it), stays verbatim while
its file is active, and matures into a CCR-backed marker once the file
is quiet for `quiesce_turns` (default 5; `max_hold_turns` bounds busy
files).
- Only the final compressed form ever enters the cache — **no cached
byte is ever mutated**; matured markers replay byte-identically.
- Wired into the Anthropic handler behind `--read-maturation` /
`HEADROOM_READ_MATURATION=1`; session state rides on the prefix tracker;
advisory (can never fail a request).
- Live-validated against the Anthropic API: held content excluded from
cache_creation; after maturation the prior cached prefix still served —
the no-bust invariant holds end-to-end.
### 5. Rebase / CI fixups (this update)
- Rebased onto latest `main` (was 28 commits behind): picks up `ci: pass
CODECOV_TOKEN to coverage uploads (#968)`, which is what was turning the
4 test shards red — the tests themselves passed (1528) but the post-test
codecov upload exited non-zero on a protected branch.
- Resolved the duplicate `lossless_min_savings_ratio` that two
independent main/branch additions left in `SmartCrusherConfig` and the
Rust-config kwarg (import-time `SyntaxError` + mypy `no-redef`).
- Aligned CCR tests with the new defaults (SQLite backend, 1800s TTL)
across `test_ccr`, `test_adapter_hooks`, `test_compression_store`,
`test_proxy_ccr`, and the lossy row-drop bridge test.
## Testing
<!-- Check what you actually ran, then paste the real command output
below. -->
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [ ] Manual testing performed
### Test Output
```text
$ python -m pytest tests/test_proxy_ccr.py tests/test_ccr.py tests/test_compression_store.py tests/test_adapter_hooks.py tests/test_ccr_row_drop_store_bridge.py -q
170 passed, 4 warnings in 42.49s
$ python -m pytest tests/test_audit_reads.py tests/test_audit_codex.py tests/test_read_maturation.py tests/test_transforms_content_router.py tests/test_smart_crusher_toin_attachment.py -q
83 passed
$ mypy headroom/
Success: no issues found in 365 source files
$ python -m compileall headroom/ -q
COMPILE-OK
# CI (run 27488990477, pre-rebase head): all 4 shards ran to completion —
# "1528 passed, 120 skipped, 4922 deselected"
# The red shards were the codecov upload step, not test failures; fixed by
# the #968 rebase above.
```
## Real Behavior Proof
- Environment: macOS (darwin), Python 3.12 venv; branch
`feat/compression-extraction` rebased onto `origin/main` (head
7cb0f43b); GitHub Actions CI run 27488990477 for the test shards
- Exact command / steps: rebased onto latest main (clean, 13 commits
replayed, 0 conflicts); ran the pytest suites and mypy above locally;
inspected CI shard logs to confirm the failure was the codecov upload,
not the test phase
- Observed result: 253 targeted tests pass locally; mypy clean on 365
files; CI test phase reports `1528 passed, 120 skipped`; the only red
step (codecov `upload-coverage` → "Token required because branch is
protected") is resolved by the rebased-in #968 CODECOV_TOKEN fix
- Not tested: the read-maturation live-API no-bust validation
(`tests/test_live/`) was not re-run in this rebase pass (requires
provider keys); it was validated when the feature first landed, and no
maturation code changed in the rebase — only CCR-default test assertions
and the duplicate-field resolution
## 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
## Additional Notes
CHANGELOG is generated by release-please from the conventional commits,
so the CHANGELOG box is intentionally left unchecked. "Manual testing
performed" is unchecked deliberately — see `Real Behavior Proof` → `Not
tested` for the exact boundary (the live-API maturation validation was
not re-run in this rebase pass).
### Follow-ups (tracked, not in this PR)
- Mechanism B provider extensions: OpenAI-family wiring (no breakpoint
hold — bounded near-tail bust) and the Codex runtime read-detector (the
audit classifier is the prototype).
- Pilot enablement playbook: run `audit-reads --simulate-maturation` on
target traffic → pick `quiesce_turns` → enable via env → watch cache hit
rate + `read_maturation:N` transform tags.
143 lines
5.8 KiB
Python
143 lines
5.8 KiB
Python
"""Tests for the newly exposed Rust compressor knobs.
|
|
|
|
Covers:
|
|
- lossless_min_savings_ratio plumbing (Python dataclass → PyO3 → Rust)
|
|
and the 0.15 lockstep default on both sides.
|
|
- CompactConfig heuristics plumbing.
|
|
- SearchCompressor group_by_file output mode (`rg --heading` style).
|
|
- factor_out_constants config acceptance end-to-end.
|
|
- ContentRouter plumbing for both knobs.
|
|
|
|
Requires the rebuilt `headroom._core` extension — these tests fail loudly
|
|
(not skip) if the installed extension predates the new fields, because a
|
|
silent version skew here is exactly the parity drift the lockstep rule
|
|
exists to prevent.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import pytest
|
|
|
|
from headroom.transforms.search_compressor import SearchCompressor, SearchCompressorConfig
|
|
from headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfig
|
|
|
|
|
|
class TestSmartCrusherConfigExposure:
|
|
def test_python_defaults(self):
|
|
cfg = SmartCrusherConfig()
|
|
assert cfg.lossless_min_savings_ratio == 0.15
|
|
assert cfg.compaction_core_field_fraction == 0.8
|
|
assert cfg.compaction_heterogeneous_core_ratio == 0.6
|
|
assert cfg.compaction_max_flatten_inner_keys == 6
|
|
assert cfg.compaction_min_buckets == 2
|
|
assert cfg.compaction_max_buckets == 8
|
|
|
|
def test_rust_default_lockstep(self):
|
|
"""Rust PyO3 default must equal the Python dataclass default."""
|
|
from headroom._core import SmartCrusherConfig as RustConfig
|
|
|
|
assert RustConfig().lossless_min_savings_ratio == 0.15
|
|
assert RustConfig().compaction_core_field_fraction == 0.8
|
|
assert RustConfig().compaction_max_buckets == 8
|
|
|
|
def test_values_reach_rust(self):
|
|
from headroom._core import SmartCrusherConfig as RustConfig
|
|
|
|
rust_cfg = RustConfig(
|
|
lossless_min_savings_ratio=0.42,
|
|
compaction_core_field_fraction=0.7,
|
|
compaction_heterogeneous_core_ratio=0.5,
|
|
compaction_max_flatten_inner_keys=10,
|
|
compaction_min_buckets=3,
|
|
compaction_max_buckets=12,
|
|
)
|
|
assert rust_cfg.lossless_min_savings_ratio == 0.42
|
|
assert rust_cfg.compaction_core_field_fraction == 0.7
|
|
assert rust_cfg.compaction_heterogeneous_core_ratio == 0.5
|
|
assert rust_cfg.compaction_max_flatten_inner_keys == 10
|
|
assert rust_cfg.compaction_min_buckets == 3
|
|
assert rust_cfg.compaction_max_buckets == 12
|
|
|
|
def test_crusher_accepts_new_fields(self):
|
|
crusher = SmartCrusher(
|
|
config=SmartCrusherConfig(
|
|
lossless_min_savings_ratio=0.5,
|
|
factor_out_constants=True,
|
|
)
|
|
)
|
|
# Construction succeeded and compresses without error.
|
|
items = ",".join(f'{{"id": {i}, "status": "ok"}}' for i in range(40))
|
|
result = crusher.crush(f"[{items}]")
|
|
assert result.compressed
|
|
|
|
def test_foreign_config_object_tolerated(self):
|
|
"""headroom.config.SmartCrusherConfig (the SDK-surface class) is
|
|
structurally similar and flows through getattr fallbacks."""
|
|
from headroom.config import SmartCrusherConfig as SdkConfig
|
|
|
|
crusher = SmartCrusher(config=SdkConfig()) # type: ignore[arg-type]
|
|
assert crusher is not None
|
|
|
|
|
|
class TestSearchGroupedOutput:
|
|
INPUT = "\n".join(
|
|
[
|
|
"src/very/long/path/to/module.py:10:def alpha():",
|
|
"src/very/long/path/to/module.py:20:def beta():",
|
|
"src/very/long/path/to/module.py:30:def gamma():",
|
|
"src/other.py:5:class Other:",
|
|
]
|
|
)
|
|
|
|
def test_standard_format_default(self):
|
|
result = SearchCompressor(SearchCompressorConfig()).compress(self.INPUT)
|
|
# Classic file:line:content — path on every match line.
|
|
assert "src/very/long/path/to/module.py:10:" in result.compressed
|
|
|
|
def test_grouped_format(self):
|
|
result = SearchCompressor(SearchCompressorConfig(group_by_file=True)).compress(self.INPUT)
|
|
lines = result.compressed.splitlines()
|
|
# Path appears as a heading...
|
|
assert "src/very/long/path/to/module.py" in lines
|
|
# ...and match lines carry only line:content.
|
|
assert "10:def alpha():" in lines
|
|
# No classic-format line remains.
|
|
assert not any(line.startswith("src/very/long/path/to/module.py:10:") for line in lines)
|
|
|
|
def test_grouped_is_smaller(self):
|
|
std = SearchCompressor(SearchCompressorConfig()).compress(self.INPUT)
|
|
grp = SearchCompressor(SearchCompressorConfig(group_by_file=True)).compress(self.INPUT)
|
|
assert len(grp.compressed) < len(std.compressed)
|
|
|
|
def test_grouped_deterministic(self):
|
|
c = SearchCompressor(SearchCompressorConfig(group_by_file=True))
|
|
assert c.compress(self.INPUT).compressed == c.compress(self.INPUT).compressed
|
|
|
|
|
|
class TestContentRouterPlumbing:
|
|
def test_router_passes_smart_crusher_config(self):
|
|
from headroom.transforms.content_router import ContentRouter, ContentRouterConfig
|
|
|
|
router = ContentRouter(
|
|
ContentRouterConfig(smart_crusher=SmartCrusherConfig(lossless_min_savings_ratio=0.33))
|
|
)
|
|
crusher = router._get_smart_crusher()
|
|
assert crusher.config.lossless_min_savings_ratio == 0.33
|
|
|
|
def test_router_passes_search_grouping(self):
|
|
from headroom.transforms.content_router import ContentRouter, ContentRouterConfig
|
|
|
|
router = ContentRouter(ContentRouterConfig(search_group_by_file=True))
|
|
compressor = router._get_search_compressor()
|
|
assert compressor.config.group_by_file is True
|
|
|
|
def test_router_defaults_off(self):
|
|
from headroom.transforms.content_router import ContentRouter, ContentRouterConfig
|
|
|
|
router = ContentRouter(ContentRouterConfig())
|
|
compressor = router._get_search_compressor()
|
|
assert compressor.config.group_by_file is False
|
|
|
|
|
|
if __name__ == "__main__":
|
|
pytest.main([__file__, "-v"])
|