Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat(kompress): warn on unrecognized HEADROOM_KOMPRESS_BACKEND + document backend selection (#204)
mbachaud6367d0b7228f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8fd6125e5..176b102c0 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -35,6 +35,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Added+* **kompress:** warn when `HEADROOM_KOMPRESS_BACKEND` is set to an unrecognized+ value instead of silently falling back to `auto`, and document the backend+ selection env var (`auto` / `onnx` / `onnx_cpu` / `onnx_coreml` / `pytorch` /+ `pytorch_mps` plus shorthand aliases) in `wiki/configuration.md` (issue+ [#202](https://github.com/chopratejas/headroom/issues/202), PR+ [#204](https://github.com/chopratejas/headroom/pull/204)).* **proxy:** per-provider attribution in the savings history rollups. Each `/stats-history` bucket (hourly/daily/weekly/monthly) now carries a `by_provider` map breaking down `tokens_saved`, `compression_savings_usd_delta`, `total_input_tokens_delta`, and `total_input_cost_usd_delta` per provider, so consumers can show how savings and spend are distributed across providers within a time period. Providers only appear in a bucket where they moved a counter; legacy history checkpoints with no provider collapse into `"unknown"`. Affected files: `headroom/proxy/savings_tracker.py`, `headroom/proxy/prometheus_metrics.py`.### Changeddiff --git a/headroom/transforms/kompress_compressor.py b/headroom/transforms/kompress_compressor.pyindex ce0e78cfd..96fe98366 100644--- a/headroom/transforms/kompress_compressor.py+++ b/headroom/transforms/kompress_compressor.py@@ -90,7 +90,16 @@ def _selected_backend() -> KompressBackend:"pytorch_mps": "pytorch_mps","auto": "auto",}- return aliases.get(raw, "auto") # type: ignore[return-value]+ backend = aliases.get(raw)+ if backend is None:+ logger.warning(+ "%s has unrecognized value %r; falling back to 'auto'. Valid values: %s",+ KOMPRESS_BACKEND_ENV,+ os.environ.get(KOMPRESS_BACKEND_ENV, ""),+ ", ".join(sorted(set(aliases.values()))),+ )+ return "auto"+ return backend # type: ignore[return-value]def _env_int(name: str) -> int | None:diff --git a/tests/test_transforms/test_kompress_compressor.py b/tests/test_transforms/test_kompress_compressor.pyindex c2de99f47..f5847f36a 100644--- a/tests/test_transforms/test_kompress_compressor.py+++ b/tests/test_transforms/test_kompress_compressor.py@@ -8,6 +8,7 @@ Covers:- Transform interface: apply() method"""+import loggingfrom types import SimpleNamespacefrom unittest.mock import MagicMock, patch@@ -83,6 +84,30 @@ class TestKompressBackendSelection:monkeypatch.setenv("HEADROOM_KOMPRESS_BACKEND", "unknown")assert kmod._selected_backend() == "auto"+ def test_unrecognized_backend_warns_and_falls_back_to_auto(self, monkeypatch, caplog) -> None:+ import headroom.transforms.kompress_compressor as kmod++ monkeypatch.setenv("HEADROOM_KOMPRESS_BACKEND", "tpu")+ with caplog.at_level(logging.WARNING, logger=kmod.logger.name):+ assert kmod._selected_backend() == "auto"++ assert any(+ "unrecognized" in record.getMessage() and "tpu" in record.getMessage()+ for record in caplog.records+ )++ def test_valid_backend_values_do_not_warn(self, monkeypatch, caplog) -> None:+ import headroom.transforms.kompress_compressor as kmod++ with caplog.at_level(logging.WARNING, logger=kmod.logger.name):+ for value in ("auto", "onnx", "cpu", "coreml", "mps", "torch", "ONNX-CPU"):+ monkeypatch.setenv("HEADROOM_KOMPRESS_BACKEND", value)+ kmod._selected_backend()+ monkeypatch.delenv("HEADROOM_KOMPRESS_BACKEND", raising=False)+ kmod._selected_backend()++ assert not caplog.records+def test_forced_pytorch_mps_backend_uses_mps_device(self, monkeypatch) -> None:import headroom.transforms.kompress_compressor as kmoddiff --git a/wiki/configuration.md b/wiki/configuration.mdindex 15c9a515c..c66611180 100644--- a/wiki/configuration.md+++ b/wiki/configuration.md@@ -70,6 +70,44 @@ headroom proxy --no-ccr-expansionheadroom proxy --help```+### Kompress backend selection++Kompress (the model-based compressor) can run on two engines:++- **ONNX Runtime** — lightweight, CPU-first. Installed with+ `pip install headroom-ai[proxy]`. Optionally uses the CoreML execution+ provider on macOS.+- **PyTorch** — heavier, supports CUDA and Apple-Silicon MPS+ acceleration. Installed with `pip install headroom-ai[ml]`. With+ `device=auto` it selects `cuda`, then `mps`, then `cpu`.++Select the backend via the `HEADROOM_KOMPRESS_BACKEND` environment+variable:++| Value | Behavior |+|---------------------|------------------------------------------------------------------------|+| `auto` | Default. ONNX CPU first (stable, lightweight), PyTorch as fallback. |+| `onnx` / `onnx_cpu` | Force ONNX Runtime on CPU. |+| `onnx_coreml` | Force ONNX Runtime with the CoreML provider (CPU fallback). |+| `pytorch` | Force PyTorch with automatic device selection (CUDA → MPS → CPU). |+| `pytorch_mps` | Force PyTorch on Apple-Silicon MPS; falls back to ONNX CPU on failure. |++Values are case-insensitive and hyphens are accepted (`onnx-cpu` ==+`onnx_cpu`). Shorthand aliases: `cpu` → `onnx_cpu`, `coreml` →+`onnx_coreml`, `mps` / `torch_mps` → `pytorch_mps`, `torch` →+`pytorch`. Unrecognized values log a warning and fall back to `auto`.++Example — opt in to MPS on an Apple-Silicon machine:++```bash+export HEADROOM_KOMPRESS_BACKEND=mps+headroom proxy ...+```++The default deliberately stays on ONNX CPU so existing installs keep+their compression quality and performance characteristics; accelerator+backends are opt-in.+## Per-Request OverridesOverride configuration for specific requests: