Commit Graph
1 Commits
Author SHA1 Message Date
Rudy Mizrahi CelekliandJD Davis d4c0810ea3 fix(client): honor configured cache optimizer enablement (#4501)
## Description

`HeadroomConfig(cache_optimizer=...enabled=False)` does not disable the
SDK's provider cache optimizer. The constructor gates initialization on
its separate `enable_cache_optimizer=True` default, so an explicitly
disabled configuration still modifies outgoing requests. The constructor
documents that `config` takes precedence over individual settings.

Use the effective configuration flag for optimizer initialization and
the setup event's `cache_optimizer_enabled` metadata. Without a supplied
config, the existing constructor flag still populates that configuration
and preserves its current behavior. With a supplied config, its flag is
authoritative, including when the separate constructor argument
disagrees.

No issue is linked: this was reproduced during a public SDK
configuration audit. #4270 concerns storage URL precedence; #4500
concerns Anthropic stream dispatch; neither fixes this cache enablement
gate.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- Read the effective `CacheOptimizerConfig.enabled` flag when choosing
whether to initialize an optimizer, including an explicitly supplied
optimizer.
- Report that same configured flag in setup lifecycle metadata.
- Cover all four config/constructor boolean combinations and the
disabled custom-optimizer case.
- Include a runnable actual-SDK localhost HTTP example with optional raw
request capture.

## Testing

- [ ] Unit tests pass (`pytest`): complete required suite pending;
focused results below.
- [x] Linting passes (`ruff check .`): pinned Ruff0.17.0, whole tree.
- [x] Type checking passes (`mypy headroom`): normal whole-package
commit hook passed.
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
New regressions on unchanged main17d38: 3 failed, 2 passed
Patched regressions + existing client/provider/pipeline suites: 57 passed
Normal commit hooks: passed, including pinned Ruff0.17.0, formatting,
whole-package mypy, plugin/version checks and commitlint
```

Exact focused command:

```sh
HEADROOM_OFFLINE=1 HEADROOM_BEACON=off DO_NOT_TRACK=1 \
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 PYTHONPATH=. python -m pytest \
  -p pytest_asyncio.plugin tests/test_client_cache_optimizer_config.py \
  tests/test_cache/test_client_integration.py tests/test_provider_registry.py \
  tests/test_provider_registry_extended.py tests/test_canonical_pipeline.py -q
```

Global plugin autoload is disabled to isolate an unrelated installed
plugin's interaction with an existing registry test's process-wide
import monkeypatch. The initial broader pipeline run encountered an
unchanged test requiring the then-unavailable native extension. After
the extension was built from the unchanged base Rust sources, the exact
frozen head passed all 57 selected tests, including that case. This is a
focused pass; complete required pre-push validation remains separate.

## Real Behavior Proof

- Environment: macOS arm64, Python3.13.5, actual OpenAI SDK2.41.0 and
HTTPX0.28.1. Audit fixture runs Headroom in optimize mode, with cache
alignment and SmartCrusher disabled, offline/beacon-off/DNT, and
temporary workspace/config/cache directories. A loopback HTTP server
returns synthetic completions; no remote model endpoint or paid API is
contacted.
- Exact command / steps: `PYTHONPATH=. python
examples/cache_optimizer_config_local.py`. Optionally set
`HEADROOM_PROOF_WIRE_DIR=/tmp/headroom-cache-wire` to retain the actual
HTTP request body bytes.
- Observed result: before the fix, `enabled=False` still selected
`openai-prefix-stabilizer` and changed the outgoing system text from
`"Keep exact spaces.\n"` to `"Keep exact spaces."`. Afterward, the
disabled configuration reports no optimizer and preserves the exact
original bytes. The enabled positive control still selects the optimizer
and sends exactly the same HTTP JSON as before the patch. Both cases
receive `local fixture` from the actual SDK/HTTP round trip.
- Not tested: live model endpoints, model quality, billed savings,
semantic cache enablement, or unrelated native runtime features. The
fixture's token usage is synthetic, not a billing measurement.

## Runtime Rollout Safety

- Rollout-managed feature(s): N/A; existing Python SDK configuration
gate.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: the supplied config's cache optimizer
flag is honored. If both a config and a contradictory constructor flag
are supplied, config wins as documented. Constructor-only defaults
remain unchanged.
- Kill switch / disable path: set
`config.cache_optimizer.enabled=False`, or use
`enable_cache_optimizer=False` without a supplied config.
- Unsafe override required: no.
- Qualification impact: no rollout-channel change.
- Rollback path: revert this two-line production change.

### Additional native validation and upload limits

The native extension now builds from unchanged source with Rust1.95.0
and a matching Xcode26.4 SDK. The exact-head Makefile Python test-file
list passes: **177 passed, 4 skipped**, with one existing Anthropic
token-count approximation warning. The previously blocked broader
client/pipeline selection now passes **57 tests**. Whole-tree pinned
Ruff passes. Full pytest, the complete pre-push workflow and required
hosted CI are not claimed as passing.

The installed `scripts/install-git-hooks.sh` documents an occasional
`git push --no-verify` upload exception. It is used for this
independently reviewed Python-only correction after bounded native
validation; full Rust workspace tests remain limited by the local disk
reserve. No Rust sources or Cargo dependencies change. Prepared and
independently reviewed with AI assistance.

## 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
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] 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

## Additional Notes

Only two production lines change. Cache optimizer implementation,
semantic caching, network destinations, dependencies and native code are
unchanged. The example demonstrates existing documented configuration
behavior; it introduces no new runtime capability.

---------

Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-29 20:26:07 -05:00