Skip to content

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.

fix: release image router models after compression

Wei Alexander Xincf608829494b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.0
backup is missing, strips only the Headroom-managed block and leaves
surrounding user content intact). Safe no-op when run without a prior
wrap. 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 the
prior block instead of wholesale-replaced. Sections re-surfaced by the
diff --git a/headroom/image/compressor.py b/headroom/image/compressor.py
index 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.py
index 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-router
from __future__ import annotations
+import gc
import io
from dataclasses import dataclass
from enum import Enum
@@ -151,6 +152,8 @@ class TrainedRouter:
self._siglip_model: Any = None
self._siglip_processor: Any = None
self._text_embeddings: Any = None
+ self._classifier_key: str | None = None
+ self._siglip_key: str | None = None
def 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 analysis
self._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 None
diff --git a/headroom/models/ml_models.py b/headroom/models/ml_models.py
index 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 gc
import logging
from threading import RLock
from 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.py
index 1c024f9a0..4449b1a91 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -709,16 +709,21 @@ class AnthropicHandlerMixin:
and not _bypass
and 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 = False
original_messages = messages # Preserve for 400-retry fallback
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 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.py
index 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 = None
def _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.py
index 458f954fb..0acf13292 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -25,6 +25,7 @@ from __future__ import annotations
import argparse
import asyncio
+import contextlib
import json
import logging
import 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 registry
await get_quota_registry().stop_all()
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py
index 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 = None
self._html_extractor: Any = None
self._kompress: Any = None
- self._image_optimizer: Any = None
# TOIN integration for cross-strategy learning
self._toin: Any = None
@@ -1338,21 +1337,20 @@ class ContentRouter(Transform):
return self._kompress
def _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 None
def 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 interface
diff --git a/tests/test_image_compressor.py b/tests/test_image_compressor.py
index 676583325..7964f664d 100644
--- a/tests/test_image_compressor.py
+++ b/tests/test_image_compressor.py
@@ -14,7 +14,9 @@ import os
os.environ["TOKENIZERS_PARALLELISM"] = "false"
import base64
+import builtins
import io
+from types import SimpleNamespace
from unittest.mock import MagicMock, patch
import 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 compressor2
def 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 == messages
assert "images_optimized" in metrics
assert 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.py
new file mode 100644
index 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.py
index 9a87da187..4e4c7e778 100644
--- a/tests/test_proxy_handler_helpers.py
+++ b/tests/test_proxy_handler_helpers.py
@@ -1,7 +1,9 @@
from __future__ import annotations
import base64
+import builtins
import json
+from unittest.mock import patch
from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin
from 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 None
assert _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.py
index 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 asyncio
from types import SimpleNamespace
-from unittest.mock import AsyncMock
+from unittest.mock import AsyncMock, call, patch
import httpx
from 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(