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.

6.4 KB
Raw Blame
"""``CompressionHooks.protect_messages`` — the hard per-message veto.

``compute_biases`` is a soft multiplier, and several strategies clamp it
against their own floors or ignore it outright: measured against the log and
JSON routes, bias 0.1 and bias 1000 produce byte-identical output. A hook that
has concluded a specific message must survive verbatim therefore cannot say so
with a bias, and this seam is how it says so instead.
"""

from __future__ import annotations

import json

import pytest

from headroom import compress
from headroom.hooks import CompressionHooks
from headroom.tokenizers import get_tokenizer
from headroom.transforms.content_router import ContentRouter

MODEL = "gpt-4o"
LOG = "\n".join(
    f"2026-09-2{i % 9} 10:{i % 60:02d}:00 INFO worker={i} processed batch {i} in {i * 3}ms"
    for i in range(300)
)
BLOB = json.dumps([{"id": i, "name": f"item-{i}", "size": i * 7} for i in range(200)])


def openai_messages(body: str) -> list[dict]:
    return [
        {"role": "user", "content": "look"},
        {
            "role": "assistant",
            "content": None,
            "tool_calls": [
                {
                    "id": "t1",
                    "type": "function",
                    "function": {"name": "run_terminal_cmd", "arguments": '{"command": "cat x"}'},
                }
            ],
        },
        {"role": "tool", "tool_call_id": "t1", "content": body},
        {"role": "user", "content": "now summarise"},
    ]


def anthropic_messages(body: str) -> list[dict]:
    return [
        {"role": "user", "content": "look"},
        {
            "role": "assistant",
            "content": [
                {"type": "tool_use", "id": "t1", "name": "Bash", "input": {"command": "cat x"}}
            ],
        },
        {
            "role": "user",
            "content": [{"type": "tool_result", "tool_use_id": "t1", "content": body}],
        },
        {"role": "user", "content": "now summarise"},
    ]


def _text_at(messages: list[dict], index: int) -> str:
    content = messages[index]["content"]
    if isinstance(content, str):
        return content
    return "".join(
        block.get("content", "") if isinstance(block.get("content"), str) else ""
        for block in content
    )


@pytest.mark.parametrize(
    "build", [openai_messages, anthropic_messages], ids=["openai", "anthropic"]
)
@pytest.mark.parametrize("body", [LOG, BLOB], ids=["log", "json"])
def test_a_protected_message_survives_verbatim(build, body) -> None:
    """Both content shapes, and routes that ignore bias entirely."""
    tokenizer = get_tokenizer(MODEL)

    compressed = ContentRouter().apply(build(body), tokenizer)
    assert _text_at(compressed.messages, 2) != body, "fixture must actually be compressible"

    protected = ContentRouter().apply(build(body), tokenizer, protect={2})
    assert _text_at(protected.messages, 2) == body
    assert "router:protected:hook" in protected.transforms_applied


@pytest.mark.parametrize(
    "protect", [None, set(), {99}, frozenset()], ids=["none", "empty", "miss", "frozen"]
)
def test_the_seam_is_inert_unless_used(protect) -> None:
    """The default path must be byte-identical to not passing the kwarg."""
    tokenizer = get_tokenizer(MODEL)
    baseline = ContentRouter().apply(openai_messages(LOG), tokenizer)
    result = ContentRouter().apply(openai_messages(LOG), tokenizer, protect=protect)
    assert _text_at(result.messages, 2) == _text_at(baseline.messages, 2)
    assert "router:protected:hook" not in result.transforms_applied


def test_protection_beats_every_bias() -> None:
    """The point of the seam: no bias can do this."""
    tokenizer = get_tokenizer(MODEL)
    for bias in (0.1, 1.0, 8.0, 1000.0):
        biased = ContentRouter().apply(openai_messages(LOG), tokenizer, biases={2: bias})
        assert _text_at(biased.messages, 2) != LOG
    protected = ContentRouter().apply(openai_messages(LOG), tokenizer, protect={2})
    assert _text_at(protected.messages, 2) == LOG


def test_the_default_hook_protects_nothing() -> None:
    assert CompressionHooks().protect_messages(openai_messages(LOG), None) == set()


def test_the_seam_is_reachable_from_the_sdk() -> None:
    """Wiring check: a hook installed through ``compress(hooks=...)`` reaches
    the router. Without this the seam exists and nobody can use it."""

    class Protecting(CompressionHooks):
        def protect_messages(self, messages, ctx):
            return {2}

    plain = compress(openai_messages(LOG), model=MODEL, hooks=CompressionHooks())
    protecting = compress(openai_messages(LOG), model=MODEL, hooks=Protecting())

    assert _text_at(plain.messages, 2) != LOG
    assert _text_at(protecting.messages, 2) == LOG
    assert protecting.tokens_after > plain.tokens_after


def test_hooks_that_do_not_implement_it_still_work() -> None:
    """A subclass predating this method inherits the empty default."""

    class Legacy(CompressionHooks):
        def compute_biases(self, messages, ctx):
            return {2: 1.5}

    result = compress(openai_messages(LOG), model=MODEL, hooks=Legacy())
    assert result.tokens_after < result.tokens_before


def test_a_hooks_object_that_is_not_a_subclass_still_compresses() -> None:
    """The real compatibility case: ``hooks`` is duck-typed, not type-checked.

    Nothing requires the object passed as ``hooks`` to subclass
    CompressionHooks, so one written before ``protect_messages`` existed has no
    such attribute. Calling it blind raises AttributeError inside the
    compression block, which the proxy catches as a *compression failure* — so
    the request would silently stop being compressed. That would make this
    additive seam a regression for those callers.
    """

    class DuckTyped:  # deliberately not a CompressionHooks subclass
        def pre_compress(self, messages, ctx):
            return messages

        def compute_biases(self, messages, ctx):
            return {}

        def post_compress(self, event):
            pass

        def on_pipeline_event(self, event):
            return None

    result = compress(openai_messages(LOG), model=MODEL, hooks=DuckTyped())
    assert result.tokens_after < result.tokens_before


def test_collect_protected_reports_a_missing_method_as_no_vetoes() -> None:
    from headroom.hooks import CompressContext, collect_protected

    class Without:
        pass

    ctx = CompressContext(model=MODEL)
    assert collect_protected(Without(), [], ctx) is None
    assert collect_protected(CompressionHooks(), [], ctx) == set()