Commit Graph
2 Commits
Author SHA1 Message Date
SD 8f04221b2d fix(proxy): turn off the image stage when --compressor leaves out image (#4723)
## Description

`headroom proxy --compressor` / `HEADROOM_COMPRESSORS` lists `image` and
says unselected built-ins are disabled. The selection only sets
`ContentRouterConfig.enable_image_optimizer`, which the proxy does not
consult. The Anthropic and OpenAI handlers gate their image stage on
`ProxyConfig.image_optimize`, and nothing set it from a selection. So
`--compressor smart_crusher` still sent every screenshot through the
image stage.

This PR makes the image gate honor the selection.
`ImageCompressionDecision`, which both handlers already call, reads
`config.compressors` on each request and skips the image stage with a
new reason, `image_not_selected`, when a selection leaves out `image`.
The operator's `image_optimize` is never written, and
`image_optimize=False` still wins. This is Gap 1 from #4613, agreed with
the reporter there. Gap 2 (Windows self-update while a proxy is running)
will be a separate PR.

Refs #4613

## Type of Change

- [x] 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)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/proxy/image_compression_policy.py`:
- `image_compressor_selected(compressors)` follows the same rules as
`_apply_compressor_selection`: no selection, an empty one or `*` keeps
images; otherwise `image` must be named.
- `decide_image_compression` takes `image_selected` (default `True`) and
adds `image_not_selected`, which comes after `image_optimize_disabled`
and before `no_messages`.
- `headroom/proxy/image_compression_decision.py`: `decide` passes the
selection from `config.compressors` and exposes `image_selected` next to
the other inputs it saw. The new reason appears in `image_skip_reason`.
- `tests/test_compressor_selection_image_stage.py`: sends a screenshot
request through the real proxy app with only the upstream faked. It runs
on two routes: Anthropic in token mode, and OpenAI chat in cache mode,
which still compresses images in cache mode. The cases are:
  - a selection without `image` never enters the image stage;
  - a selection with `image`, `*`, and no selection each enter it once;
  - a config reused across two proxies follows the current selection;
  - `image_optimize=False` with `image` selected still skips the stage.
- `tests/test_image_compression_decision.py`: covers the new reason, its
precedence, the wildcard and blank selections, and a config with no
`compressors` attribute.
- `docs/content/docs/proxy.mdx`: the `--compressor` row says that
leaving out `image` also turns off the image stage.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`): see Additional Notes
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

The new tests against `main`'s source (b21479e0):

```text
FAILED tests/test_compressor_selection_image_stage.py::TestImageStageFollowsSelection::test_selection_without_image_skips_the_image_stage[anthropic-token]
FAILED tests/test_compressor_selection_image_stage.py::TestImageStageFollowsSelection::test_selection_without_image_skips_the_image_stage[openai-cache]
FAILED tests/test_compressor_selection_image_stage.py::TestImageStageFollowsSelection::test_reused_config_follows_the_current_selection[anthropic-token]
FAILED tests/test_compressor_selection_image_stage.py::TestImageStageFollowsSelection::test_reused_config_follows_the_current_selection[openai-cache]
4 failed, 8 passed
```

At this head:

```text
$ pytest tests/test_compressor_selection.py tests/test_compressor_selection_image_stage.py tests/test_image_compression_decision.py tests/test_image_compression_policy.py tests/test_router_external_dispatch.py tests/test_proxy_eager_preload_bind.py -q
99 passed

$ pytest <every test file that mentions image_skip_reason, ImageCompressionDecision, image_optimize or compressors> -m "not live" -q
12 failed, 1994 passed, 26 skipped

$ ruff check <changed files> && ruff format --check <changed files>
All checks passed!
```

The 12 failures are in `tests/test_image_compressor.py`,
`tests/test_ccr_batch_processor.py`,
`tests/test_garbled_compression_fixes.py` and
`tests/test_transforms/test_content_router.py`. The same 12 fail on
`main` in my environment (the image ones because the venv has Pillow
12), so they are not from this change.

## Real Behavior Proof

- Environment: macOS (Darwin 24.6.0, arm64), Python 3.12.3, Pillow
13.0.0. Older Pillow makes the proxy forward images unchanged.
- Exact command / steps: the real proxy app in token mode on the
Anthropic route, with the real image compressor and image worker; only
the upstream model is faked, and it answers instantly. Each setting
sends the same 2560x1600 PNG screenshot ("what is the exact error text
in this screenshot?") 5 times. Per request, the script records
image-stage entries, what reached the upstream, and the time the proxy
took. Run once on `main` (b21479e0) and once on this branch.
- Observed result: on `main`, `--compressor smart_crusher` still ran the
image stage on 5 of 5 requests and downscaled every screenshot
(`full_low`, 1,870 → 255 tokens) at about 45 ms each. With this PR it
ran on 0 of 5, the original image went upstream unchanged, and each
request took 4.6 ms. With no selection or with `image` selected, both
builds behave the same. `image_optimize` stays `True` in every run.

| Build | Setting | Image-stage runs | Image sent upstream | Proxy time
p50 |
|---|---|---|---|---|
| `main` | no `--compressor` | 5 of 5 | downscaled (`full_low`, 1,870 →
255 tokens) | 45.4 ms |
| `main` | `--compressor smart_crusher` | **5 of 5** | **downscaled** |
**45.2 ms** |
| `main` | `--compressor smart_crusher,image` | 5 of 5 | downscaled |
46.9 ms |
| this PR | no `--compressor` | 5 of 5 | downscaled | 48.2 ms |
| this PR | `--compressor smart_crusher` | **0 of 5** | **original,
unchanged** | **4.6 ms** |
| this PR | `--compressor smart_crusher,image` | 5 of 5 | downscaled |
47.6 ms |

The first image request of each process also loads the image models
(about 1.0–1.3 s here). With `image` left out, that load doesn't happen.
- Not tested: a live upstream, the OCR (`transcode`) technique (the
router picked `full_low` for this screenshot), and Windows.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only for a `--compressor` /
`HEADROOM_COMPRESSORS` selection that leaves out `image`. Those proxies
now forward images unchanged, as the help text already says. With no
selection, a selection that includes `image`, or `*`, nothing changes.
- Kill switch / disable path: add `image` to the selection, or remove
the selection
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the PR's commits

## 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
- [x] 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)

n/a

## Additional Notes

- Review follow-up: the first revision (619ea4ad) wrote
`image_optimize=False` into the caller's `ProxyConfig`. Now the decision
reads the selection on each request, so a reused config follows its
current selection, and an explicit `image_optimize=False` is kept.
- #1327 proposes a separate `HEADROOM_DISABLE_IMAGE_OPTIMIZER` variable.
This PR doesn't add one; it makes the existing option behave as its help
text says.
- `mypy headroom/proxy/server.py` stops in my local environment on a
`numpy` stub (`Type statement is only supported in Python 3.12 and
greater`) before reaching project code. CI runs mypy.
2026-11-10 10:39:18 -06:00
chopratejas a7b197c6ec refactor(proxy): MemoryRanker + ImageCompressionDecision + branch-aware version-sync
Three independent contract-pattern follow-ons bundled into one PR.
Same frozen-dataclass + factory + apply_to_tags + Rust-portable
shape that PR #473 / #477 / #483 established.

## (1) MemoryRanker + RecencyBoostRanker

Pre-this-PR Headroom ranked memory candidates by pure cosine
similarity. Every other memory system we surveyed (Letta, Mem0,
Cognee, Supermemory) re-ranks beyond cosine.

* ``MemoryRanker`` Protocol — pluggable re-ranker; future PRs add
  source-weight + access-count rankers behind the same interface.
* ``RecencyBoostRanker`` — first concrete impl. Final score is
  ``cosine × exp(-age_days / decay_days)``. Default decay 30 days
  (half-life ~21 days; 60-day-old factor 0.135, 90-day-old 0.050).
* ``MemoryCandidate`` — backend-agnostic frozen value type that
  flows through the ranker. ``MemoryCandidate.from_backend_result``
  adapter converts the existing ``MemoryResult`` shape (with nested
  ``memory.created_at``) into the ranker's flatter form.
* Wired into ``memory_handler.search_and_format_context`` as an
  optional ``ranker=`` kwarg — backwards-compat: ``None`` (default)
  preserves the pure-cosine path identically.

Defensive:
* ``created_at=None`` → factor 1.0 (recency-neutral, back-compat with
  legacy rows / migrating backends)
* Negative age (clock skew) → clamped to factor 1.0 (a future-dated
  row can't outrank a real fresh memory)
* Sort is stable on ties — same input → same output every turn, so
  consecutive turns inject memories in the same order (prefix-cache
  friendly)

Performance: O(N) over candidates where N=top_k≈10. One ``math.exp``
per candidate. Sub-microsecond. Zero new I/O.

## (2) ImageCompressionDecision

Mirror of :class:`CompressionDecision` for image compression. Two
sites today (``openai.py:1203``, ``anthropic.py:868``) gate inline;
both already respect bypass (no Gemini-class drift bug like text
compression had), but consolidating into a value type:

* Locks bypass-respect via AST contract test — future sites can't
  drift on it
* Surfaces ``image_skip_reason`` in ``RequestOutcome.tags`` for
  dashboard slicing (same observability surface as
  ``passthrough_reason`` and ``memory_skip_reason``)
* Same Rust-port shape as the other decision types

Precedence: ``bypass_header`` > ``image_optimize_disabled`` >
``no_messages`` > ``should_compress=True``.

Anthropic's extra ``is_cache_mode`` check stays inline because it's
Anthropic-specific (openai/gemini don't have it). Documented in a
code comment.

## (3) Branch-aware sync-plugin-versions hook

Pre-this-fix the pre-commit ``sync-plugin-versions`` hook ran on
every commit and bumped manifests to the predicted-next-release
version. Every PR ended up carrying the prediction as collateral
("Why are we bumping ``.claude-plugin/marketplace.json`` — we
should not, right??" - user, on PR #483).

Fix: the hook is now a NO-OP unless EITHER:
* We're on the ``main`` branch, OR
* ``HEADROOM_SYNC_VERSIONS=1`` is set explicitly (release workflow)

On feature branches the hook prints a single line explaining the
skip and exits cleanly. The release workflow opts in via the env
var; behaviour on main / at release time is unchanged.

## Test coverage

* 16 new tests on ``MemoryRanker`` / ``RecencyBoostRanker``
  (frozen, equal cosine wins by recency, decay configurable, NULL
  timestamp neutral, no-mutation contract, Rust-port shape)
* 17 new tests on ``ImageCompressionDecision`` (frozen, all 3
  skip reasons, precedence, observability fields, apply_to_tags)
* 1 new AST invariant test (extends
  ``test_handler_outcome_tag_invariant.py``) — locks "no raw
  ``if self.config.image_optimize and messages and not _bypass:``
  conjunction in any handler"

All existing memory + cache-stability + handler tests pass (203 ✓).
``make ci-precheck`` clean.

## Rust portability

All three new value types port cleanly to frozen Rust structs +
pure functions. Same migration pattern as ``CompressionDecision``
(already locked in for the SmartCrusher Rust port).

## Zero-regression contract

* Default ``ranker=None`` → memory_handler behaves identically to
  pre-this-PR (pure cosine; no perf change)
* Image decision migration is identity at the bypass/optimize/messages
  gate — no behaviour change, just contract consolidation
* Hook fix is no-op on feature branches (less churn) and unchanged
  on main (release flow preserved)
2026-05-19 12:13:09 -05:00