mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
## Description
`headroom.compression` (UniversalCompressor, StructureMask and the
JSON/code structure handlers) is not called by any product code; only
`tests/test_compression/` uses it. The one-function API people use is
`headroom.compress()`, which does not touch it.
`headroom.compression.*` was an undocumented import path. It was never
in the published docs, only in the unpublished `wiki/compression.md`,
and no consumer repo imports it. Because it is an importable package
with an `__all__`, this PR deprecates it instead of deleting it.
Refs #4136
## 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)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)
## Changes Made
- The package exports (`compress`, `UniversalCompressor`,
`UniversalCompressorConfig`, `CompressionResult`, `MagikaDetector`,
`ContentType`, `StructureMask`) are now lazy. The first access emits one
`DeprecationWarning` at the caller, pointing to `headroom.compress()` or
`ContentRouter`.
- The resolved object is cached in the package globals, so a `from`
import (which looks the name up twice) warns once, not twice.
- On `importlib.reload()` the package drops its cached exports, so they
resolve against the current submodules again.
- Importing `headroom.compression.universal` directly also warns.
- `import headroom.compression.detector` stays quiet, because
ContentRouter's startup Magika preload imports it.
- `tests/test_compression/test_deprecation.py` covers attribute, `from`
and wildcard imports, reload, the universal import and the quiet
detector import.
- It restores `sys.modules`, the parent-package attribute and the export
cache through monkeypatch, so test order does not matter.
- Three of these tests fail on the previous commit, which warned twice.
- Evidence: `rg -n
'headroom\.compression|UniversalCompressor|StructureMask|MagikaDetector'
headroom crates plugins sdk examples benchmarks scripts`, plus the
consumer repos, finds only the package itself, `content_router.py`'s
detector import and unrelated OTel metric names.
## Testing
- [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
$ pytest tests/test_compression tests/test_kompress_preload_deferral.py tests/test_transforms_content_router.py tests/test_compress_api.py tests/test_proxy_warmup.py
262 passed, 8 skipped, 1 warning in 39.82s
$ ruff check / format: All checks passed; mypy: Success
```
## Real Behavior Proof
- Environment: macOS, Python 3.12, repo `.venv`, this branch's worktree
with the prebuilt `headroom._core`. Temp `HOME`,
`HEADROOM_WORKSPACE_DIR` and `CODEX_HOME`; nothing touched the real
home.
- Exact command / steps: (1) shared smoke harness: a real proxy from
this checkout against a local fake upstream, with one Anthropic and one
OpenAI request carrying a compressible tool result (`smoke.sh
<worktree>`); (2) `python -W always -c 'from headroom.compression import
compress; import headroom.compression.detector'`.
- Observed result: The proxy serves both requests (200) with savings and
logs no new warnings. The from-import emits exactly one
DeprecationWarning, attributed to the caller. The detector import is
silent. Output below.
- Not tested: Third-party code using `headroom.compression`; none is
known.
```text
branch: cleanup/compression-deprecate-universal-compressor @ 4a430674
health: 200
POST /v1/messages -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines ($SMOKE/ws/logs/proxy-52286.log):
2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you configured, operator-configured local endpoints, loopback health probes.
4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.
(smoke dir: $SMOKE)
```
```text
$ python -W always -c "from headroom.compression import compress; import headroom.compression.detector; print(\"ok\")"
<string>:2: DeprecationWarning: headroom.compression.compress is deprecated and will be removed in a future release; use headroom.compress() for one-call compression, or ContentRouter from headroom.transforms.
ok
```
## Runtime Rollout Safety
- Rollout-managed feature(s): None.
- Minimum rollout channel: Not applicable; no rollout-managed behaviour
is touched.
- Stable/default behavior changed: Only a DeprecationWarning when the
deprecated names are used.
- Kill switch / disable path: Not applicable; the warning is a standard
DeprecationWarning and can be filtered with `warnings`.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this single commit.
## 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
- [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)
Not applicable.
## Additional Notes
Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.
Documentation changes are not in this PR. They are recorded in the
cleanup docs ledger for the single follow-up docs PR.
Deprecated (not removed): the seven `headroom.compression` package
exports and the module `headroom.compression.universal`. The handlers
and masks modules warn only through the package. In
`tests/test_proxy_debug_endpoints.py`,
`test_debug_endpoints_do_not_mutate_state` failed once in a combined run
and passed on two reruns (29/29). It looks flaky and is unrelated to
this change.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>