Skip to content

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.

feat(kompress): warn on unrecognized HEADROOM_KOMPRESS_BACKEND + document backend selection (#204)

mbachaud6367d0b7228f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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`.
### Changed
diff --git a/headroom/transforms/kompress_compressor.py b/headroom/transforms/kompress_compressor.py
index 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.py
index 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 logging
from types import SimpleNamespace
from 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 kmod
diff --git a/wiki/configuration.md b/wiki/configuration.md
index 15c9a515c..c66611180 100644
--- a/wiki/configuration.md
+++ b/wiki/configuration.md
@@ -70,6 +70,44 @@ headroom proxy --no-ccr-expansion
headroom 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 Overrides
Override configuration for specific requests: