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.

feat(transforms): add pluggable compressor registry + headroom.compressor entry point (#2370)

Tejas Chopraa02073e33273
diff --git a/headroom/transforms/compressor_registry.py b/headroom/transforms/compressor_registry.py
new file mode 100644
index 000000000..3cc99f5ac
--- /dev/null
+++ b/headroom/transforms/compressor_registry.py
@@ -0,0 +1,282 @@
+"""Pluggable compressor registry and ``headroom.compressor`` entry-point seam.
+
+This module lands a *name-addressable* seam for compressors: built-in
+compressors can be registered explicitly, third-party compressors can be
+discovered from the ``headroom.compressor`` entry-point group, and a caller can
+opt in to a specific set of them by name.
+
+It is deliberately **additive**. Nothing here is wired into the content router,
+proxy server, or config in this change — registering or discovering a compressor
+has no effect on request handling until an integration point is added in a
+follow-up. Constructing a ``CompressorRegistry`` has no global side effects.
+
+Rust-portable contract
+----------------------
+The compressor boundary is **pure data in / data out**. No Python-only objects
+(tokenizer instances, live store handles, rich config classes) cross it:
+
+ * :class:`CompressorDescriptor` — static, declarative capability metadata.
+ * :class:`CompressInput` — the content plus plain ``dict`` config/budget.
+ * :class:`CompressOutput` — the compressed content plus plain counts, string
+ markers, a ``hash -> original`` recovery map, and string warnings.
+
+Every field is a ``str``, ``int``, ``bool``, ``list``, or ``dict`` of those, so
+an equivalent contract can be implemented in another language (e.g. a Rust
+compressor invoked over the same shapes) without carrying Python objects.
+
+Discovery vs. selection (opt-in)
+--------------------------------
+Discovery (:meth:`CompressorRegistry.discover`) enumerates and *loads* every
+registered entry point — it may import a module and construct the compressor
+object — but it never invokes ``compress``. Selection
+(:meth:`CompressorRegistry.select` / :meth:`CompressorRegistry.active`) is
+opt-in: with no names (or an empty set) nothing is active; the literal ``"*"``
+selects everything registered; otherwise only the named-and-registered
+compressors are active. This mirrors the opt-in model used for proxy extensions
+so that merely installing a third-party package cannot silently change behavior.
+
+External packages register a compressor like this::
+
+ [project.entry-points."headroom.compressor"]
+ my_compressor = "my_pkg.compressor:MyCompressor"
+
+The value may be a :class:`Compressor` instance or a zero-arg class implementing
+the protocol; a class is instantiated during discovery.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+log = logging.getLogger(__name__)
+
+ENTRY_POINT_GROUP = "headroom.compressor"
+
+#: Recognized values for :attr:`CompressorDescriptor.cost_tier`.
+COST_TIERS: tuple[str, ...] = ("fast", "ml", "remote")
+
+
+@dataclass(frozen=True)
+class CompressorDescriptor:
+ """Static, declarative metadata describing a compressor's capabilities.
+
+ Attributes:
+ name: Canonical, unique compressor name used for registration/selection.
+ content_types: Content types this compressor handles (e.g. ``["text/plain"]``).
+ lossless: Whether compression is losslessly reversible.
+ cost_tier: One of :data:`COST_TIERS` — ``"fast"`` (local/cheap),
+ ``"ml"`` (local model inference), or ``"remote"`` (network call).
+ recoverable: Whether the compressor can emit a ``hash -> original``
+ recovery map in :attr:`CompressOutput.recoverable`.
+ """
+
+ name: str
+ content_types: list[str]
+ lossless: bool
+ cost_tier: str
+ recoverable: bool
+
+
+@dataclass
+class CompressInput:
+ """Pure-data input to :meth:`Compressor.compress`.
+
+ Attributes:
+ content: The raw content to compress.
+ content_type: The content type of ``content``.
+ query: Optional task/query hint for relevance-aware compressors.
+ config: Plain compressor-specific configuration.
+ budget: Plain budget hints, e.g. ``target_ratio`` (float),
+ ``time_ms`` (int), ``max_items`` (int).
+ """
+
+ content: str
+ content_type: str
+ query: str = ""
+ config: dict[str, Any] = field(default_factory=dict)
+ budget: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class CompressOutput:
+ """Pure-data output from :meth:`Compressor.compress`.
+
+ Attributes:
+ content: The compressed content.
+ tokens_before: Token count of the input content.
+ tokens_after: Token count of the compressed content.
+ lossless: Whether this particular result is losslessly reversible.
+ markers: Marker strings describing what was applied (e.g. for routing).
+ recoverable: ``hash -> original`` map for recovering dropped content.
+ warnings: Non-fatal warning strings emitted during compression.
+ """
+
+ content: str
+ tokens_before: int
+ tokens_after: int
+ lossless: bool
+ markers: list[str] = field(default_factory=list)
+ recoverable: dict[str, str] = field(default_factory=dict)
+ warnings: list[str] = field(default_factory=list)
+
+
+@runtime_checkable
+class Compressor(Protocol):
+ """Name-addressable compressor contract (pure data in / data out)."""
+
+ @property
+ def descriptor(self) -> CompressorDescriptor:
+ """Return this compressor's static capability metadata."""
+ ...
+
+ def compress(self, inp: CompressInput) -> CompressOutput:
+ """Compress ``inp`` and return a :class:`CompressOutput`."""
+ ...
+
+
+class CompressorRegistry:
+ """Registry of compressors addressable by :attr:`CompressorDescriptor.name`.
+
+ Starts empty. Built-in compressors are added via :meth:`register`; external
+ compressors are added via :meth:`discover`. Selection is opt-in.
+ """
+
+ def __init__(self) -> None:
+ self._compressors: dict[str, Compressor] = {}
+
+ def register(self, compressor: Compressor, *, replace: bool = False) -> str:
+ """Register ``compressor`` under its ``descriptor.name``.
+
+ Args:
+ compressor: The compressor to register.
+ replace: If ``True``, replace an existing registration of the same
+ name instead of raising.
+
+ Returns:
+ The registered name.
+
+ Raises:
+ ValueError: If the name is empty, or already registered and
+ ``replace`` is ``False``.
+ """
+ name = compressor.descriptor.name
+ if not name:
+ raise ValueError("compressor descriptor.name must be non-empty")
+ if name in self._compressors and not replace:
+ raise ValueError(f"compressor {name!r} is already registered")
+ self._compressors[name] = compressor
+ return name
+
+ def get(self, name: str) -> Compressor | None:
+ """Return the registered compressor named ``name``, or ``None``."""
+ return self._compressors.get(name)
+
+ def names(self) -> list[str]:
+ """Return all registered compressor names, sorted."""
+ return sorted(self._compressors)
+
+ def descriptors(self) -> list[CompressorDescriptor]:
+ """Return the descriptors of all registered compressors, sorted by name."""
+ return [self._compressors[n].descriptor for n in sorted(self._compressors)]
+
+ def discover(self, *, replace: bool = False) -> list[str]:
+ """Load and register compressors from the ``headroom.compressor`` group.
+
+ Mirrors the pipeline extension discovery helper: entry points are
+ enumerated fail-open, each is loaded fail-open, and a class value is
+ instantiated fail-open. A broken third-party package is logged and
+ skipped rather than aborting discovery. ``compress`` is never invoked
+ here — discovery only loads and registers.
+
+ Args:
+ replace: Passed through to :meth:`register` for name collisions.
+
+ Returns:
+ The list of newly registered compressor names.
+ """
+ discovered: list[str] = []
+ try:
+ entries = importlib.metadata.entry_points(group=ENTRY_POINT_GROUP)
+ except Exception as exc: # noqa: BLE001 - importlib metadata varies by runtime
+ log.debug("compressor registry: entry-point enumeration failed: %s", exc)
+ return discovered
+
+ for entry in entries:
+ try:
+ obj = entry.load()
+ except Exception as exc: # noqa: BLE001 - third-party load failures are isolated
+ log.warning("compressor %r failed to load: %s", entry.name, exc)
+ continue
+
+ if isinstance(obj, type):
+ try:
+ obj = obj()
+ except Exception as exc: # noqa: BLE001
+ log.warning("compressor %r failed to initialize: %s", entry.name, exc)
+ continue
+
+ try:
+ name = self.register(obj, replace=replace)
+ except Exception as exc: # noqa: BLE001 - bad descriptor / duplicate name
+ log.warning("compressor %r failed to register: %s", entry.name, exc)
+ continue
+
+ discovered.append(name)
+
+ return discovered
+
+ @staticmethod
+ def _resolve_selection(names: set[str] | None) -> set[str]:
+ """Normalize a requested selection: strip whitespace, drop empties."""
+ if not names:
+ return set()
+ return {stripped for n in names if (stripped := n.strip())}
+
+ def select(self, names: set[str] | None) -> set[str]:
+ """Resolve an opt-in selection to the set of *active* registered names.
+
+ Mirrors the proxy-extension opt-in model:
+
+ * ``None`` or an empty set selects nothing (opt-in default).
+ * ``"*"`` selects every registered compressor.
+ * Otherwise only names that are both requested and registered are
+ active; requested-but-unregistered names are logged and skipped.
+
+ Discovery is never triggered here and ``compress`` is never invoked;
+ this only decides which already-registered compressors are active.
+ """
+ requested = self._resolve_selection(names)
+ registered = set(self._compressors)
+
+ if not requested:
+ if registered:
+ log.info(
+ "compressors registered but none selected (opt-in): %s. "
+ "Select by name or use '*' for all.",
+ ",".join(sorted(registered)),
+ )
+ return set()
+
+ if "*" in requested:
+ return registered
+
+ active = requested & registered
+ missing = requested - registered
+ if missing:
+ log.warning(
+ "compressors requested but not registered: %s (available: %s)",
+ ",".join(sorted(missing)),
+ ",".join(sorted(registered)) or "<none>",
+ )
+ return active
+
+ def active(self, selection: set[str] | None) -> list[Compressor]:
+ """Return the active compressor objects for ``selection``, sorted by name.
+
+ ``selection`` is the raw opt-in request; it is resolved via
+ :meth:`select`.
+ """
+ return [self._compressors[name] for name in sorted(self.select(selection))]
diff --git a/tests/test_compressor_registry.py b/tests/test_compressor_registry.py
new file mode 100644
index 000000000..ac3359e54
--- /dev/null
+++ b/tests/test_compressor_registry.py
@@ -0,0 +1,245 @@
+"""Tests for the pluggable compressor registry and entry-point discovery."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+from dataclasses import asdict, dataclass
+
+import pytest
+
+from headroom.transforms import compressor_registry
+from headroom.transforms.compressor_registry import (
+ ENTRY_POINT_GROUP,
+ CompressInput,
+ CompressorDescriptor,
+ CompressorRegistry,
+ CompressOutput,
+)
+
+
+class FakeCompressor:
+ """Minimal in-memory compressor implementing the Compressor protocol."""
+
+ def __init__(
+ self,
+ name: str = "fake",
+ *,
+ content_types: list[str] | None = None,
+ lossless: bool = True,
+ cost_tier: str = "fast",
+ recoverable: bool = True,
+ raise_on_compress: bool = False,
+ ) -> None:
+ self._descriptor = CompressorDescriptor(
+ name=name,
+ content_types=content_types or ["text/plain"],
+ lossless=lossless,
+ cost_tier=cost_tier,
+ recoverable=recoverable,
+ )
+ self._raise_on_compress = raise_on_compress
+
+ @property
+ def descriptor(self) -> CompressorDescriptor:
+ return self._descriptor
+
+ def compress(self, inp: CompressInput) -> CompressOutput:
+ if self._raise_on_compress:
+ raise RuntimeError("compress must not run during discovery/selection")
+ half = inp.content[: max(1, len(inp.content) // 2)]
+ return CompressOutput(
+ content=half,
+ tokens_before=len(inp.content),
+ tokens_after=len(half),
+ lossless=self._descriptor.lossless,
+ markers=[f"fake:{inp.content_type}"],
+ recoverable={"deadbeef": inp.content} if self._descriptor.recoverable else {},
+ warnings=[],
+ )
+
+
+@dataclass
+class FakeEntryPoint:
+ """Stand-in for ``importlib.metadata.EntryPoint`` used in discovery tests."""
+
+ name: str
+ value: object
+
+ def load(self) -> object:
+ if isinstance(self.value, Exception):
+ raise self.value
+ return self.value
+
+
+def test_registry_starts_empty() -> None:
+ reg = CompressorRegistry()
+ assert reg.names() == []
+ assert reg.get("fake") is None
+ assert reg.active(None) == []
+ assert reg.active({"*"}) == []
+
+
+def test_descriptor_round_trips() -> None:
+ desc = CompressorDescriptor(
+ name="fake",
+ content_types=["text/plain", "text/markdown"],
+ lossless=True,
+ cost_tier="fast",
+ recoverable=True,
+ )
+ assert desc.name == "fake"
+ assert desc.content_types == ["text/plain", "text/markdown"]
+ assert desc.lossless is True
+ assert desc.cost_tier in compressor_registry.COST_TIERS
+ assert desc.recoverable is True
+ # Pure-data: fully representable as a plain dict for a cross-language boundary.
+ assert asdict(desc) == {
+ "name": "fake",
+ "content_types": ["text/plain", "text/markdown"],
+ "lossless": True,
+ "cost_tier": "fast",
+ "recoverable": True,
+ }
+
+
+def test_register_and_get_by_name() -> None:
+ reg = CompressorRegistry()
+ comp = FakeCompressor("fake")
+ assert reg.register(comp) == "fake"
+ assert reg.get("fake") is comp
+ assert reg.names() == ["fake"]
+ assert [d.name for d in reg.descriptors()] == ["fake"]
+
+
+def test_register_rejects_empty_name_and_duplicates() -> None:
+ reg = CompressorRegistry()
+ with pytest.raises(ValueError):
+ reg.register(FakeCompressor(""))
+
+ reg.register(FakeCompressor("fake"))
+ with pytest.raises(ValueError):
+ reg.register(FakeCompressor("fake"))
+
+ replacement = FakeCompressor("fake")
+ assert reg.register(replacement, replace=True) == "fake"
+ assert reg.get("fake") is replacement
+
+
+def test_selection_is_opt_in_none_and_empty_select_nothing(caplog) -> None:
+ reg = CompressorRegistry()
+ reg.register(FakeCompressor("a"))
+ reg.register(FakeCompressor("b"))
+
+ with caplog.at_level(logging.INFO, logger=compressor_registry.log.name):
+ assert reg.select(None) == set()
+ assert reg.select(set()) == set()
+ assert reg.active(None) == []
+ # Opt-in default is surfaced.
+ assert "none selected (opt-in)" in caplog.text
+
+
+def test_selection_wildcard_selects_all() -> None:
+ reg = CompressorRegistry()
+ reg.register(FakeCompressor("a"))
+ reg.register(FakeCompressor("b"))
+
+ assert reg.select({"*"}) == {"a", "b"}
+ active = reg.active({"*"})
+ assert [c.descriptor.name for c in active] == ["a", "b"]
+
+
+def test_selection_by_name_and_unknown_is_skipped(caplog) -> None:
+ reg = CompressorRegistry()
+ reg.register(FakeCompressor("a"))
+ reg.register(FakeCompressor("b"))
+
+ assert reg.select({"a"}) == {"a"}
+ assert [c.descriptor.name for c in reg.active({"a", "b"})] == ["a", "b"]
+
+ with caplog.at_level(logging.WARNING, logger=compressor_registry.log.name):
+ assert reg.select({"a", "nope"}) == {"a"}
+ assert "requested but not registered: nope" in caplog.text
+
+
+def test_selection_normalizes_whitespace_and_empties() -> None:
+ reg = CompressorRegistry()
+ reg.register(FakeCompressor("a"))
+ assert reg.select({" a ", "", " "}) == {"a"}
+
+
+def test_compress_round_trips_input_to_output() -> None:
+ reg = CompressorRegistry()
+ reg.register(FakeCompressor("fake"))
+ comp = reg.active({"fake"})[0]
+
+ inp = CompressInput(
+ content="hello world, this is content",
+ content_type="text/plain",
+ query="summarize",
+ config={"aggressive": True},
+ budget={"target_ratio": 0.5, "time_ms": 10, "max_items": 3},
+ )
+ out = comp.compress(inp)
+
+ assert isinstance(out, CompressOutput)
+ assert out.tokens_before == len(inp.content)
+ assert out.tokens_after == len(out.content)
+ assert out.tokens_after < out.tokens_before
+ assert out.lossless is True
+ assert out.markers == ["fake:text/plain"]
+ assert out.recoverable == {"deadbeef": inp.content}
+ assert out.warnings == []
+
+
+def test_discovery_registers_selects_but_does_not_run_compress(monkeypatch, caplog) -> None:
+ # A compressor whose compress() would raise proves discovery never calls it.
+ guarded = FakeCompressor("guarded", raise_on_compress=True)
+
+ class NeedsInit:
+ def __init__(self) -> None:
+ raise RuntimeError("bad init")
+
+ monkeypatch.setattr(
+ importlib.metadata,
+ "entry_points",
+ lambda group=None: (
+ [
+ FakeEntryPoint("guarded-instance", guarded),
+ FakeEntryPoint("working-class", FakeCompressor),
+ FakeEntryPoint("bad-load", RuntimeError("bad load")),
+ FakeEntryPoint("bad-init", NeedsInit),
+ ]
+ if group == ENTRY_POINT_GROUP
+ else []
+ ),
+ )
+
+ reg = CompressorRegistry()
+ with caplog.at_level(logging.WARNING, logger=compressor_registry.log.name):
+ discovered = reg.discover()
+
+ # Only the loadable/constructible compressors are registered.
+ assert sorted(discovered) == ["fake", "guarded"]
+ assert reg.get("guarded") is guarded
+ # Failures are logged and skipped, not raised.
+ assert "bad-load" in caplog.text
+ assert "bad-init" in caplog.text
+
+ # Discovery did not run compress; selection alone does not either.
+ active = reg.active({"guarded"})
+ assert active == [guarded]
+ # compress only runs when the caller invokes it.
+ with pytest.raises(RuntimeError):
+ active[0].compress(CompressInput(content="x", content_type="text/plain"))
+
+
+def test_discovery_handles_enumeration_failure(monkeypatch) -> None:
+ monkeypatch.setattr(
+ importlib.metadata,
+ "entry_points",
+ lambda group=None: (_ for _ in ()).throw(RuntimeError("boom")),
+ )
+ reg = CompressorRegistry()
+ assert reg.discover() == []
+ assert reg.names() == []