mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(router): fall back to built-ins when an external compressor passes through (#3893)
## Description `CompressOutput.compressed=False` is the compressor contract's passthrough signal: the external compressor declined the block and returned it unchanged. The `compressor_registry` docs say callers can read the flag "to distinguish a real (possibly no-shrink) result from a passthrough and run their own fallback on a passthrough". `ContentRouter._run_external_compressor` never read it. A passthrough is not empty and not larger than the input, so it cleared every existing fail-open check and was adopted as the external result (`strategy_chain == ["external:<name>"]`). The built-in dispatch never ran for that block, so it went out **uncompressed**. An external compressor that only handles some blocks (too short, no query, model not loaded, too little to gain) therefore made compression *worse* than having no external compressor at all. This PR treats a passthrough like the other fail-open cases and returns `None`, so the built-in path runs exactly as if no external compressor were selected. I found this while building [Winnow](https://github.com/RecepKurtulus/headroom-winnow), an external `headroom.compressor` plugin that prunes tool output with a task-conditioned model and declines blocks it can't score in time. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - `headroom/transforms/content_router.py`: `_run_external_compressor` returns `None` when `out.compressed` is `False` (debug log, same as the other fallbacks). - `tests/test_router_external_passthrough.py`: an external compressor that always declines; asserts the router falls back and that the result is byte-identical to the no-external path, both via `_apply_strategy_to_content` and via `compress()`. ## Testing - [x] New tests added that fail before the fix and pass after it - [x] Existing `tests/test_router_external_dispatch.py` still passes (22/22) - [x] Linting passes (`ruff check`, `ruff format --check` on the changed files) ### Test Output Before the fix (released 0.39.1): ```text > assert "external:ext_decline" not in got[2] E AssertionError: assert 'external:ext_decline' not in ['external:ext_decline'] > assert "external:ext_decline" not in result.strategy_chain E assert 'external:ext_decline' not in ['external:ext_decline'] 2 failed in 0.56s ``` After the fix, together with the existing external-dispatch suite: ```text $ pytest tests/test_router_external_dispatch.py tests/test_router_external_passthrough.py 24 passed in 3.14s ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.12, `headroom-ai` 0.39.1 wheel with this diff applied. - Exact command / steps: a real external compressor ([Winnow](https://github.com/RecepKurtulus/headroom-winnow)) registered in the router's `compressor_registry` and selected with `active_external_compressors=["winnow"]`, with its model backend unavailable so it returns `compressed=False`; a 60-line plain-text block routed through `ContentRouter._apply_strategy_to_content(..., CompressionStrategy.TEXT, query)`. - Observed result: without the fix the chain is `["external:winnow"]` and the block comes back unchanged; with the fix `external:winnow` is no longer in the chain and the router's built-in dispatch handles the block. - Not tested: the proxy (`--compressor`) end to end and the full test suite. I ran the new tests and `tests/test_router_external_dispatch.py` (22 existing tests, all passing) against the 0.39.1 wheel, where this diff applies unchanged, plus ruff on the changed files. ## Runtime Rollout Safety - Rollout-managed feature(s): none. The change only affects the opt-in external-compressor branch. - Minimum rollout channel: none required; the code path is only reachable when an operator selects an external compressor (`active_external_compressors` / `--compressor`), so it applies the same on every channel. - Stable/default behavior changed: no. With no external compressor selected the branch is still inert. - Kill switch / disable path: unselect the external compressor. - Unsafe override required: no. - Qualification impact: none for default traffic; for opt-in external compressors, a passthrough now reaches the built-in compressors instead of being sent uncompressed. - Rollback path: revert this 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 added tests that prove my fix is effective - [x] I did **not** edit `CHANGELOG.md`
This commit is contained in:
@@ -3494,6 +3494,12 @@ class ContentRouter(Transform):
|
||||
type(out).__name__,
|
||||
)
|
||||
return None
|
||||
# A passthrough (``compressed=False``) is the compressor declining this
|
||||
# block, not a result; fall back so the built-in path still gets its
|
||||
# turn instead of the block going out uncompressed.
|
||||
if not out.compressed:
|
||||
logger.debug("external compressor %r passed through; falling back to built-in", name)
|
||||
return None
|
||||
compressed = out.content
|
||||
# Never blank out a non-empty block (an empty user/tool block makes
|
||||
# providers reject the request); fall back so the built-in path runs.
|
||||
|
||||
@@ -0,0 +1,111 @@
|
||||
"""A selected external compressor that passes a block through must not swallow it.
|
||||
|
||||
``CompressOutput.compressed=False`` is the contract's passthrough signal: the
|
||||
compressor declined this block and returned it unchanged. The router has to
|
||||
treat that like any other fail-open case and run its built-in dispatch, exactly
|
||||
as if no external compressor were selected. Before the fix the router adopted
|
||||
the unchanged block as the external result (chain ``["external:<name>"]``), so
|
||||
every declined block skipped Headroom's own compressors.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import pytest
|
||||
|
||||
from headroom.cache.compression_store import reset_compression_store
|
||||
from headroom.transforms.compressor_registry import (
|
||||
CompressInput,
|
||||
CompressorDescriptor,
|
||||
CompressOutput,
|
||||
)
|
||||
from headroom.transforms.content_router import (
|
||||
CompressionStrategy,
|
||||
ContentRouter,
|
||||
ContentRouterConfig,
|
||||
)
|
||||
|
||||
# Routes to SMART_CRUSHER (application/json) and is not touched by the STAGE-0
|
||||
# lossless fold, so it reaches the external dispatch branch.
|
||||
_JSON_ARRAY = (
|
||||
"["
|
||||
+ ",".join(
|
||||
f'{{"id":{i},"name":"item-{i}","status":"active","value":{i * 7},'
|
||||
f'"note":"a fairly long descriptive field number {i} to add bulk"}}'
|
||||
for i in range(40)
|
||||
)
|
||||
+ "]"
|
||||
)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def _memory_ccr(monkeypatch):
|
||||
monkeypatch.setenv("HEADROOM_CCR_BACKEND", "memory")
|
||||
monkeypatch.setenv("HEADROOM_DETECT_BACKEND", "python")
|
||||
reset_compression_store()
|
||||
yield
|
||||
reset_compression_store()
|
||||
|
||||
|
||||
class _DecliningExternal:
|
||||
"""External compressor that always declines with ``compressed=False``."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.calls: list[CompressInput] = []
|
||||
|
||||
@property
|
||||
def descriptor(self) -> CompressorDescriptor:
|
||||
return CompressorDescriptor(
|
||||
name="ext_decline",
|
||||
content_types=["application/json"],
|
||||
lossless=False,
|
||||
cost_tier="ml",
|
||||
recoverable=True,
|
||||
)
|
||||
|
||||
def compress(self, inp: CompressInput) -> CompressOutput:
|
||||
self.calls.append(inp)
|
||||
return CompressOutput(
|
||||
content=inp.content,
|
||||
tokens_before=len(inp.content.split()),
|
||||
tokens_after=len(inp.content.split()),
|
||||
lossless=True,
|
||||
compressed=False,
|
||||
)
|
||||
|
||||
|
||||
def _router(selection: list[str] | None, comp: _DecliningExternal | None = None) -> ContentRouter:
|
||||
router = ContentRouter(
|
||||
ContentRouterConfig(enable_kompress=False, active_external_compressors=selection)
|
||||
)
|
||||
if comp is not None:
|
||||
router.compressor_registry.register(comp, replace=True)
|
||||
router._active_external_compressors = router._resolve_active_external_compressors()
|
||||
return router
|
||||
|
||||
|
||||
def test_passthrough_falls_back_to_builtin_dispatch(_memory_ccr):
|
||||
comp = _DecliningExternal()
|
||||
with_external = _router(["ext_decline"], comp)
|
||||
without_external = _router(None)
|
||||
|
||||
got = with_external._apply_strategy_to_content(
|
||||
_JSON_ARRAY, CompressionStrategy.SMART_CRUSHER, ""
|
||||
)
|
||||
expected = without_external._apply_strategy_to_content(
|
||||
_JSON_ARRAY, CompressionStrategy.SMART_CRUSHER, ""
|
||||
)
|
||||
|
||||
assert comp.calls, "the external compressor should have been consulted"
|
||||
assert "external:ext_decline" not in got[2]
|
||||
# Byte-identical to the path with no external compressor selected.
|
||||
assert got == expected
|
||||
|
||||
|
||||
def test_passthrough_does_not_short_circuit_compress(_memory_ccr):
|
||||
comp = _DecliningExternal()
|
||||
router = _router(["ext_decline"], comp)
|
||||
|
||||
result = router.compress(_JSON_ARRAY)
|
||||
|
||||
assert comp.calls
|
||||
assert "external:ext_decline" not in result.strategy_chain
|
||||
Reference in New Issue
Block a user