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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix: release image router models after compression
Wei Alexander Xincf608829494b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 47b83c3b4..f81e06770 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -36,6 +36,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0backup is missing, strips only the Headroom-managed block and leavessurrounding user content intact). Safe no-op when run without a priorwrap. Reported by @raenaryl in Discord.+- **Image compressors now release shared router models after use and proxy shutdown** —+ the proxy/image compression path no longer keeps global `technique-router`+ and `SigLIP` model instances pinned in memory after one-off image+ optimization work. The `get_compressor()` helper now returns a fresh,+ caller-owned compressor instead of a process-lifetime singleton.- **`headroom learn` no longer clobbers prior recommendations on re-run** —the marker block in `CLAUDE.md` / `MEMORY.md` is now merged with theprior block instead of wholesale-replaced. Sections re-surfaced by thediff --git a/headroom/image/compressor.py b/headroom/image/compressor.pyindex 27714afa9..161136265 100644--- a/headroom/image/compressor.py+++ b/headroom/image/compressor.py@@ -102,6 +102,14 @@ class ImageCompressor:)return self._router+ def close(self, unload_models: bool = True) -> None:+ """Release any router-held model state."""+ if self._router is not None:+ # Only loaded routers hold heavyweight image models; plain has_images()+ # checks remain cheap and have nothing to release.+ self._router.release_models(unload_registry=unload_models)+ self._router = None+def has_images(self, messages: list[dict[str, Any]]) -> bool:"""Check if messages contain images."""for message in messages:@@ -563,16 +571,13 @@ class ImageCompressor:return compressed_messages-# Singleton for convenience-_default_compressor: ImageCompressor | None = None--def get_compressor() -> ImageCompressor:- """Get the default ImageCompressor instance."""- global _default_compressor- if _default_compressor is None:- _default_compressor = ImageCompressor()- return _default_compressor+ """Create an ImageCompressor instance.++ Kept for backwards-compatible imports; callers that use it directly own+ closing the returned compressor.+ """+ return ImageCompressor()def compress_images(@@ -588,4 +593,8 @@ def compress_images(Returns:Messages with compressed images"""- return get_compressor().compress(messages, provider)+ compressor = ImageCompressor()+ try:+ return compressor.compress(messages, provider)+ finally:+ compressor.close()diff --git a/headroom/image/trained_router.py b/headroom/image/trained_router.pyindex c91f1dc81..b53c30d19 100644--- a/headroom/image/trained_router.py+++ b/headroom/image/trained_router.py@@ -10,6 +10,7 @@ The MiniLM model is hosted on HuggingFace: headroom-ai/technique-routerfrom __future__ import annotations+import gcimport iofrom dataclasses import dataclassfrom enum import Enum@@ -151,6 +152,8 @@ class TrainedRouter:self._siglip_model: Any = Noneself._siglip_processor: Any = Noneself._text_embeddings: Any = None+ self._classifier_key: str | None = None+ self._siglip_key: str | None = Nonedef is_available(self) -> bool:"""Check if required models can be loaded."""@@ -186,6 +189,7 @@ class TrainedRouter:model_path=model_id,device=self.device,)+ self._classifier_key = f"technique_router:{model_id}"if self.use_siglip and self._siglip_model is None:# Use centralized registry for shared model instances@@ -195,10 +199,36 @@ class TrainedRouter:model_name=self.siglip_model,device=self.device,)+ self._siglip_key = f"siglip:{self.siglip_model}"# Pre-compute text embeddings for image analysisself._compute_text_embeddings()+ def release_models(self, unload_registry: bool = True) -> None:+ """Release router-held model references and optional shared cache entries."""+ classifier_key = self._classifier_key+ siglip_key = self._siglip_key++ self._text_embeddings = None+ self._siglip_processor = None+ self._siglip_model = None+ self._tokenizer = None+ self._classifier = None+ self._classifier_key = None+ self._siglip_key = None++ if unload_registry:+ from headroom.models.ml_models import MLModelRegistry++ keys = [key for key in (classifier_key, siglip_key) if key]+ MLModelRegistry.unload_many(keys)+ else:+ gc.collect()++ def close(self, unload_registry: bool = True) -> None:+ """Alias for release_models() while preserving subclass dispatch."""+ self.release_models(unload_registry=unload_registry)+def _compute_text_embeddings(self) -> None:"""Pre-compute SigLIP text embeddings for image analysis."""assert self._siglip_processor is not Nonediff --git a/headroom/models/ml_models.py b/headroom/models/ml_models.pyindex 59ece163b..9f48cf2ed 100644--- a/headroom/models/ml_models.py+++ b/headroom/models/ml_models.py@@ -26,6 +26,8 @@ Usage:from __future__ import annotations+import contextlib+import gcimport loggingfrom threading import RLockfrom typing import TYPE_CHECKING, Any@@ -76,6 +78,63 @@ class MLModelRegistry:cls._instance._models.clear()cls._instance = None+ @classmethod+ def _release_runtime_memory(cls) -> None:+ """Best-effort cleanup after unloading heavyweight models."""+ gc.collect()+ try:+ import torch+ except ImportError:+ return++ with contextlib.suppress(Exception):+ if torch.cuda.is_available():+ torch.cuda.empty_cache()++ mps = getattr(torch, "mps", None)+ if mps is not None and hasattr(mps, "empty_cache"):+ mps.empty_cache()++ @classmethod+ def unload(cls, key: str) -> bool:+ """Unload one cached model entry."""+ return bool(cls.unload_many([key]))++ @classmethod+ def unload_many(cls, keys: list[str]) -> list[str]:+ """Unload several cached model entries with one runtime cleanup pass."""+ instance = cls.get()+ removed_keys: list[str] = []++ with instance._model_lock:+ for key in keys:+ if key not in instance._models:+ continue+ value = instance._models.pop(key)+ del value+ removed_keys.append(key)++ if removed_keys:+ cls._release_runtime_memory()+ return removed_keys++ @classmethod+ def unload_prefix(cls, prefix: str) -> list[str]:+ """Unload every cached model entry matching a prefix."""+ instance = cls.get()+ removed_keys: list[str] = []++ with instance._model_lock:+ for key in list(instance._models):+ if key.startswith(prefix):+ value = instance._models.pop(key)+ del value+ removed_keys.append(key)++ if removed_keys:+ cls._release_runtime_memory()+ return removed_keys+# =========================================================================# Sentence Transformers# =========================================================================diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex 1c024f9a0..4449b1a91 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -709,16 +709,21 @@ class AnthropicHandlerMixin:and not _bypassand not is_cache_mode(self.config.mode)):- compressor = _get_image_compressor()- if compressor and compressor.has_images(messages):- messages = compressor.compress(messages, provider="anthropic")- if compressor.last_result:- logger.info(- f"Image compression: {compressor.last_result.technique.value} "- f"({compressor.last_result.savings_percent:.0f}% saved, "- f"{compressor.last_result.original_tokens} -> "- f"{compressor.last_result.compressed_tokens} tokens)"- )+ compressor = None+ try:+ compressor = _get_image_compressor()+ if compressor and compressor.has_images(messages):+ messages = compressor.compress(messages, provider="anthropic")+ if compressor.last_result:+ logger.info(+ f"Image compression: {compressor.last_result.technique.value} "+ f"({compressor.last_result.savings_percent:.0f}% saved, "+ f"{compressor.last_result.original_tokens} -> "+ f"{compressor.last_result.compressed_tokens} tokens)"+ )+ finally:+ if compressor and hasattr(compressor, "close"):+ compressor.close()_compression_failed = Falseoriginal_messages = messages # Preserve for 400-retry fallbackdiff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 877258a89..03496c95d 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -239,16 +239,21 @@ class OpenAIHandlerMixin:if self.config.image_optimize and messages and not _bypass:from headroom.proxy.helpers import _get_image_compressor- compressor = _get_image_compressor()- if compressor and compressor.has_images(messages):- messages = compressor.compress(messages, provider="openai")- if compressor.last_result:- logger.info(- f"[{request_id}] Image: {compressor.last_result.technique.value} "- f"({compressor.last_result.savings_percent:.0f}% saved, "- f"{compressor.last_result.original_tokens} → "- f"{compressor.last_result.compressed_tokens} tokens)"- )+ compressor = None+ try:+ compressor = _get_image_compressor()+ if compressor and compressor.has_images(messages):+ messages = compressor.compress(messages, provider="openai")+ if compressor.last_result:+ logger.info(+ f"[{request_id}] Image: {compressor.last_result.technique.value} "+ f"({compressor.last_result.savings_percent:.0f}% saved, "+ f"{compressor.last_result.original_tokens} → "+ f"{compressor.last_result.compressed_tokens} tokens)"+ )+ finally:+ if compressor and hasattr(compressor, "close"):+ compressor.close()headers = dict(request.headers.items())headers.pop("host", None)diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex 58b3b837f..9bb52d236 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -59,23 +59,31 @@ def jitter_delay_ms(base_ms: int, max_ms: int, attempt: int) -> float:return capped * (0.5 + random.random())-# Image compression (lazy-loaded to avoid heavy dependencies at startup)-_image_compressor = None+# Image compression availability (do not retain a global compressor instance)+_image_compressor_available: bool | None = Nonedef _get_image_compressor():- """Lazy load image compressor to avoid startup overhead."""- global _image_compressor- if _image_compressor is None:- try:- from headroom.image import ImageCompressor+ """Create a short-lived image compressor on demand."""+ global _image_compressor_available+ if _image_compressor_available is False:+ return None- _image_compressor = ImageCompressor()+ try:+ from headroom.image import ImageCompressor++ # Callers own closing the compressor; this helper only memoizes whether+ # the optional image stack is importable.+ compressor = ImageCompressor()+ if _image_compressor_available is None:logger.info("Image compression enabled (model: chopratejas/technique-router)")- except ImportError as e:+ _image_compressor_available = True+ return compressor+ except ImportError as e:+ if _image_compressor_available is not False:logger.warning(f"Image compression not available: {e}")- _image_compressor = False # Mark as unavailable- return _image_compressor if _image_compressor else None+ _image_compressor_available = False+ return None# Always-on file logging to the workspace logs directory for `headroom perf` analysis.diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 458f954fb..0acf13292 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -25,6 +25,7 @@ from __future__ import annotationsimport argparseimport asyncio+import contextlibimport jsonimport loggingimport os@@ -844,6 +845,15 @@ class HeadroomProxy(if self.memory_handler and hasattr(self.memory_handler, "close"):await self.memory_handler.close()+ with contextlib.suppress(Exception):+ from headroom.models.ml_models import MLModelRegistry++ released_models = []+ released_models.extend(MLModelRegistry.unload_prefix("technique_router:"))+ released_models.extend(MLModelRegistry.unload_prefix("siglip:"))+ if released_models:+ logger.info("Released image optimizer models: %s", ", ".join(released_models))+# Stop all quota trackers via the registryawait get_quota_registry().stop_all()diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex ff7278305..07737adb1 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -659,7 +659,6 @@ class ContentRouter(Transform):self._diff_compressor: Any = Noneself._html_extractor: Any = Noneself._kompress: Any = None- self._image_optimizer: Any = None# TOIN integration for cross-strategy learningself._toin: Any = None@@ -1338,21 +1337,20 @@ class ContentRouter(Transform):return self._kompressdef _get_image_optimizer(self) -> Any:- """Get ImageCompressor (lazy load).+ """Create an ImageCompressor for one optimization pass.The ImageCompressor handles image token compression using:- Trained MiniLM classifier from HuggingFace (chopratejas/technique-router)- SigLIP for image analysis- Provider-specific compression (OpenAI detail, Anthropic/Google resize)"""- if self._image_optimizer is None:- try:- from ..image import ImageCompressor+ try:+ from ..image import ImageCompressor- self._image_optimizer = ImageCompressor()- except ImportError:- logger.debug("ImageCompressor not available")- return self._image_optimizer+ return ImageCompressor()+ except ImportError:+ logger.debug("ImageCompressor not available")+ return Nonedef optimize_images_in_messages(self,@@ -1385,28 +1383,32 @@ class ContentRouter(Transform):if compressor is None:return messages, {"images_optimized": 0, "tokens_saved": 0}- # Check if there are images to compress- if not compressor.has_images(messages):- return messages, {"images_optimized": 0, "tokens_saved": 0}-- # Compress images (query is auto-extracted from messages)- optimized = compressor.compress(messages, provider=provider)-- # Get metrics from last compression- result = compressor.last_result- if result:- metrics = {- "images_optimized": result.compressed_tokens < result.original_tokens,- "tokens_before": result.original_tokens,- "tokens_after": result.compressed_tokens,- "tokens_saved": result.original_tokens - result.compressed_tokens,- "technique": result.technique.value,- "confidence": result.confidence,- }- else:- metrics = {"images_optimized": 0, "tokens_saved": 0}+ try:+ # Check if there are images to compress+ if not compressor.has_images(messages):+ return messages, {"images_optimized": 0, "tokens_saved": 0}++ # Compress images (query is auto-extracted from messages)+ optimized = compressor.compress(messages, provider=provider)++ # Get metrics from last compression+ result = compressor.last_result+ if result:+ metrics = {+ "images_optimized": result.compressed_tokens < result.original_tokens,+ "tokens_before": result.original_tokens,+ "tokens_after": result.compressed_tokens,+ "tokens_saved": result.original_tokens - result.compressed_tokens,+ "technique": result.technique.value,+ "confidence": result.confidence,+ }+ else:+ metrics = {"images_optimized": 0, "tokens_saved": 0}- return optimized, metrics+ return optimized, metrics+ finally:+ if hasattr(compressor, "close"):+ compressor.close()# Transform interfacediff --git a/tests/test_image_compressor.py b/tests/test_image_compressor.pyindex 676583325..7964f664d 100644--- a/tests/test_image_compressor.py+++ b/tests/test_image_compressor.py@@ -14,7 +14,9 @@ import osos.environ["TOKENIZERS_PARALLELISM"] = "false"import base64+import builtinsimport io+from types import SimpleNamespacefrom unittest.mock import MagicMock, patchimport pytest@@ -739,6 +741,27 @@ class TestTrainedRouterMocked:with patch.object(router, "_load_models", side_effect=Exception("Model not found")):assert router.is_available() is False+ def test_release_models_unloads_registry_entries(self):+ """Releasing router state should drop shared registry keys too."""+ router = TrainedRouter()+ router._classifier_key = "technique_router:demo"+ router._siglip_key = "siglip:demo"+ router._classifier = object()+ router._tokenizer = object()+ router._siglip_model = object()+ router._siglip_processor = object()+ router._text_embeddings = object()++ with patch("headroom.models.ml_models.MLModelRegistry.unload_many") as unload_many:+ router.release_models()++ unload_many.assert_called_once_with(["technique_router:demo", "siglip:demo"])+ assert router._classifier is None+ assert router._tokenizer is None+ assert router._siglip_model is None+ assert router._siglip_processor is None+ assert router._text_embeddings is None+# ============================================================================# Test Convenience functions@@ -753,17 +776,28 @@ class TestConvenienceFunctions:compressor = get_compressor()assert isinstance(compressor, ImageCompressor)- def test_get_compressor_singleton(self):- """get_compressor returns the same instance."""+ def test_get_compressor_returns_fresh_instance(self):+ """get_compressor returns a fresh caller-owned instance."""compressor1 = get_compressor()compressor2 = get_compressor()- assert compressor1 is compressor2+ assert compressor1 is not compressor2def test_compress_images_function(self, text_only_messages):"""compress_images convenience function works."""result = compress_images(text_only_messages, "openai")assert result == text_only_messages+ def test_compress_images_function_closes_temporary_compressor(self, text_only_messages):+ """compress_images should always close the one-shot compressor."""+ with (+ patch.object(ImageCompressor, "compress", return_value=text_only_messages),+ patch.object(ImageCompressor, "close") as close,+ ):+ result = compress_images(text_only_messages, "openai")++ assert result == text_only_messages+ close.assert_called_once()+# ============================================================================# Integration tests (with mocked router)@@ -890,11 +924,15 @@ class TestContentRouterIntegration:router = ContentRouter()compressor = router._get_image_optimizer()- # This should NOT be None - if it is, the import failed silently- assert compressor is not None, (- "ContentRouter._get_image_optimizer() returned None. "- "This means ImageCompressor import failed silently!"- )+ try:+ # This should NOT be None - if it is, the import failed silently+ assert compressor is not None, (+ "ContentRouter._get_image_optimizer() returned None. "+ "This means ImageCompressor import failed silently!"+ )+ finally:+ if compressor is not None:+ compressor.close()def test_content_router_compressor_is_image_compressor(self):"""Verify ContentRouter uses ImageCompressor (not old ImageOptimizer)."""@@ -904,9 +942,29 @@ class TestContentRouterIntegration:router = ContentRouter()compressor = router._get_image_optimizer()- assert isinstance(compressor, ImageCompressor), (- f"Expected ImageCompressor, got {type(compressor).__name__}"- )+ try:+ assert isinstance(compressor, ImageCompressor), (+ f"Expected ImageCompressor, got {type(compressor).__name__}"+ )+ finally:+ if compressor is not None:+ compressor.close()++ def test_content_router_compressor_is_fresh_per_call(self):+ """ContentRouter should not share image compressors across callers."""+ from headroom.transforms.content_router import ContentRouter++ router = ContentRouter()+ first = router._get_image_optimizer()+ second = router._get_image_optimizer()++ try:+ assert first is not second+ finally:+ if first is not None:+ first.close()+ if second is not None:+ second.close()def test_content_router_optimize_images_works(self):"""Test optimize_images_in_messages returns valid result."""@@ -924,3 +982,99 @@ class TestContentRouterIntegration:assert result == messagesassert "images_optimized" in metricsassert metrics["tokens_saved"] == 0++ def test_content_router_returns_metrics_and_closes_after_compression(self):+ """Image optimization should report savings and close the compressor."""+ from headroom.transforms.content_router import ContentRouter++ router = ContentRouter()+ tokenizer = MagicMock()+ optimized = [{"role": "user", "content": "optimized"}]+ technique = SimpleNamespace(value="full_low")+ fake = MagicMock()+ fake.has_images.return_value = True+ fake.compress.return_value = optimized+ fake.last_result = SimpleNamespace(+ original_tokens=1000,+ compressed_tokens=85,+ technique=technique,+ confidence=0.9,+ )++ with patch.object(router, "_get_image_optimizer", return_value=fake):+ result, metrics = router.optimize_images_in_messages(+ [{"role": "user", "content": "with image"}],+ tokenizer,+ provider="openai",+ )++ assert result == optimized+ assert metrics == {+ "images_optimized": True,+ "tokens_before": 1000,+ "tokens_after": 85,+ "tokens_saved": 915,+ "technique": "full_low",+ "confidence": 0.9,+ }+ fake.close.assert_called_once()++ def test_content_router_returns_basic_metrics_when_compression_has_no_result(self):+ """Missing compressor result should still close and return neutral metrics."""+ from headroom.transforms.content_router import ContentRouter++ router = ContentRouter()+ tokenizer = MagicMock()+ optimized = [{"role": "user", "content": "optimized"}]+ fake = MagicMock()+ fake.has_images.return_value = True+ fake.compress.return_value = optimized+ fake.last_result = None++ with patch.object(router, "_get_image_optimizer", return_value=fake):+ result, metrics = router.optimize_images_in_messages(+ [{"role": "user", "content": "with image"}],+ tokenizer,+ provider="openai",+ )++ assert result == optimized+ assert metrics == {"images_optimized": 0, "tokens_saved": 0}+ fake.close.assert_called_once()++ def test_content_router_image_optimizer_returns_none_when_image_stack_missing(self):+ """Import failures should disable image optimization without raising."""+ from headroom.transforms.content_router import ContentRouter++ real_import = builtins.__import__++ def fake_import(name, globals=None, locals=None, fromlist=(), level=0): # noqa: ANN001+ if name == "image" and fromlist == ("ImageCompressor",) and level == 2:+ raise ImportError("image extras unavailable")+ return real_import(name, globals, locals, fromlist, level)++ router = ContentRouter()+ with patch.object(builtins, "__import__", side_effect=fake_import):+ compressor = router._get_image_optimizer()++ assert compressor is None++ def test_content_router_releases_image_optimizer_after_use(self):+ """ContentRouter should drop the compressor after each optimization pass."""+ from headroom.transforms.content_router import ContentRouter++ router = ContentRouter()+ tokenizer = MagicMock()+ fake = MagicMock()+ fake.has_images.return_value = False++ with patch.object(router, "_get_image_optimizer", return_value=fake):+ result, metrics = router.optimize_images_in_messages(+ [{"role": "user", "content": "Hello"}],+ tokenizer,+ provider="openai",+ )++ assert result == [{"role": "user", "content": "Hello"}]+ assert metrics["tokens_saved"] == 0+ fake.close.assert_called_once()diff --git a/tests/test_ml_model_registry_lifecycle.py b/tests/test_ml_model_registry_lifecycle.pynew file mode 100644index 000000000..23e89b80e--- /dev/null+++ b/tests/test_ml_model_registry_lifecycle.py@@ -0,0 +1,106 @@+from __future__ import annotations++import builtins+import sys+from types import SimpleNamespace+from unittest.mock import Mock++from headroom.models.ml_models import MLModelRegistry+++def test_unload_many_removes_requested_keys_once(monkeypatch) -> None:+ MLModelRegistry.reset()+ registry = MLModelRegistry.get()+ kept_model = object()+ registry._models.update(+ {+ "technique_router:demo": object(),+ "siglip:demo": object(),+ "sentence_transformer:keep": kept_model,+ }+ )+ release = Mock()+ monkeypatch.setattr(MLModelRegistry, "_release_runtime_memory", release)++ removed = MLModelRegistry.unload_many(["missing", "technique_router:demo", "siglip:demo"])++ assert removed == ["technique_router:demo", "siglip:demo"]+ assert registry._models == {"sentence_transformer:keep": kept_model}+ release.assert_called_once_with()+++def test_unload_many_skips_runtime_cleanup_when_nothing_removed(monkeypatch) -> None:+ MLModelRegistry.reset()+ registry = MLModelRegistry.get()+ registry._models["sentence_transformer:keep"] = object()+ release = Mock()+ monkeypatch.setattr(MLModelRegistry, "_release_runtime_memory", release)++ removed = MLModelRegistry.unload_many(["missing"])++ assert removed == []+ assert "sentence_transformer:keep" in registry._models+ release.assert_not_called()+++def test_unload_prefix_removes_only_matching_models(monkeypatch) -> None:+ MLModelRegistry.reset()+ registry = MLModelRegistry.get()+ kept_model = object()+ registry._models.update(+ {+ "siglip:a": object(),+ "siglip:b": object(),+ "technique_router:keep": kept_model,+ }+ )+ release = Mock()+ monkeypatch.setattr(MLModelRegistry, "_release_runtime_memory", release)++ removed = MLModelRegistry.unload_prefix("siglip:")++ assert removed == ["siglip:a", "siglip:b"]+ assert registry._models == {"technique_router:keep": kept_model}+ release.assert_called_once_with()+++def test_unload_delegates_to_unload_many(monkeypatch) -> None:+ unload_many = Mock(return_value=["siglip:demo"])+ monkeypatch.setattr(MLModelRegistry, "unload_many", unload_many)++ assert MLModelRegistry.unload("siglip:demo") is True++ unload_many.assert_called_once_with(["siglip:demo"])+++def test_release_runtime_memory_handles_missing_torch(monkeypatch) -> None:+ collect = Mock()+ monkeypatch.setattr("headroom.models.ml_models.gc.collect", collect)+ real_import = builtins.__import__++ def fake_import(name, *args, **kwargs): # noqa: ANN001, ANN202+ if name == "torch":+ raise ImportError("torch unavailable")+ return real_import(name, *args, **kwargs)++ monkeypatch.setattr(builtins, "__import__", fake_import)++ MLModelRegistry._release_runtime_memory()++ collect.assert_called_once_with()+++def test_release_runtime_memory_clears_available_torch_caches(monkeypatch) -> None:+ collect = Mock()+ cuda = SimpleNamespace(is_available=Mock(return_value=True), empty_cache=Mock())+ mps = SimpleNamespace(empty_cache=Mock())+ fake_torch = SimpleNamespace(cuda=cuda, mps=mps)+ monkeypatch.setattr("headroom.models.ml_models.gc.collect", collect)+ monkeypatch.setitem(sys.modules, "torch", fake_torch)++ MLModelRegistry._release_runtime_memory()++ collect.assert_called_once_with()+ cuda.is_available.assert_called_once_with()+ cuda.empty_cache.assert_called_once_with()+ mps.empty_cache.assert_called_once_with()diff --git a/tests/test_proxy_handler_helpers.py b/tests/test_proxy_handler_helpers.pyindex 9a87da187..4e4c7e778 100644--- a/tests/test_proxy_handler_helpers.py+++ b/tests/test_proxy_handler_helpers.py@@ -1,7 +1,9 @@from __future__ import annotationsimport base64+import builtinsimport json+from unittest.mock import patchfrom headroom.proxy.handlers.anthropic import AnthropicHandlerMixinfrom headroom.proxy.handlers.openai import OpenAIHandlerMixin, _decode_openai_bearer_payload@@ -26,6 +28,13 @@ class _ImageCompressor:return [self._compressed_message]+class _FreshCompressor:+ instances = 0++ def __init__(self):+ type(self).instances += 1++def test_decode_openai_bearer_payload_handles_missing_and_non_mapping_payloads() -> None:assert _decode_openai_bearer_payload({}) is Noneassert _decode_openai_bearer_payload({"authorization": "Basic abc"}) is None@@ -148,6 +157,44 @@ def test_anthropic_image_compression_helper_only_rewrites_latest_eligible_turn()) == [compressed]+def test_proxy_helper_creates_fresh_image_compressors(monkeypatch) -> None:+ from headroom.proxy import helpers++ monkeypatch.setattr(helpers, "_image_compressor_available", None)+ _FreshCompressor.instances = 0++ with patch("headroom.image.ImageCompressor", _FreshCompressor):+ first = helpers._get_image_compressor()+ second = helpers._get_image_compressor()++ assert isinstance(first, _FreshCompressor)+ assert isinstance(second, _FreshCompressor)+ assert first is not second+ assert _FreshCompressor.instances == 2+++def test_proxy_helper_caches_image_stack_import_failure(monkeypatch) -> None:+ from headroom.proxy import helpers++ real_import = builtins.__import__+ calls = 0++ def fake_import(name, *args, **kwargs): # noqa: ANN001, ANN202+ nonlocal calls+ if name == "headroom.image":+ calls += 1+ raise ImportError("image extras unavailable")+ return real_import(name, *args, **kwargs)++ monkeypatch.setattr(helpers, "_image_compressor_available", None)+ monkeypatch.setattr(builtins, "__import__", fake_import)++ assert helpers._get_image_compressor() is None+ assert helpers._get_image_compressor() is None+ assert calls == 1+ assert helpers._image_compressor_available is False++def test_anthropic_cache_delta_helpers_cover_string_list_and_role_mismatch() -> None:previous_original = [{"role": "user", "content": "hello"}]previous_forwarded = [{"role": "user", "content": "HELLO"}]diff --git a/tests/test_proxy_pipeline_lifecycle.py b/tests/test_proxy_pipeline_lifecycle.pyindex aea3ec06d..e57338da2 100644--- a/tests/test_proxy_pipeline_lifecycle.py+++ b/tests/test_proxy_pipeline_lifecycle.py@@ -1,7 +1,8 @@from __future__ import annotations+import asynciofrom types import SimpleNamespace-from unittest.mock import AsyncMock+from unittest.mock import AsyncMock, call, patchimport httpxfrom fastapi.testclient import TestClient@@ -41,6 +42,37 @@ def _assert_stage_order(stages: list[PipelineStage]) -> None:assert positions == sorted(positions)+def test_proxy_shutdown_unloads_image_models() -> None:+ config = ProxyConfig(+ optimize=False,+ image_optimize=False,+ cache_enabled=False,+ rate_limit_enabled=False,+ cost_tracking_enabled=False,+ log_requests=False,+ ccr_inject_tool=False,+ ccr_handle_responses=False,+ ccr_context_tracking=False,+ )+ app = create_app(config)+ proxy = app.state.proxy+ proxy.http_client = None+ proxy.memory_handler = None++ quota_registry = SimpleNamespace(stop_all=AsyncMock())+ with (+ patch("headroom.proxy.server.get_quota_registry", return_value=quota_registry),+ patch("headroom.models.ml_models.MLModelRegistry.unload_prefix") as unload_prefix,+ ):+ asyncio.run(proxy.shutdown())++ assert unload_prefix.call_args_list == [+ call("technique_router:"),+ call("siglip:"),+ ]+ quota_registry.stop_all.assert_awaited_once()++def test_openai_chat_pipeline_events_cover_proxy_lifecycle(monkeypatch) -> None:recorder = _RecordingExtension()config = ProxyConfig(