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:
Recep Kurtulus
2026-10-02 17:29:13 -07:00
committed by GitHub
parent dd84321daa
commit 2c4b20fcba
2 changed files with 117 additions and 0 deletions
+6
View File
@@ -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.
+111
View File
@@ -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