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(content-router): honor target_ratio in compression cache + add proxy --target-ratio flag (#1108)

Tejas Chopra8894ee0c18e6
diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.py
index f411d74d9..dc216c3ab 100644
--- a/headroom/cli/proxy.py
+++ b/headroom/cli/proxy.py
@@ -164,6 +164,19 @@ def _selected_context_tool() -> str:
"cost_savings) are still accepted. Env: HEADROOM_MODE."
),
)
+ "--target-ratio",
+ type=float,
+ default=None,
+ show_default=True,
+ envvar="HEADROOM_TARGET_RATIO",
+ help=(
+ "Override Kompress keep-ratio for text (prose/code) compression — lower is "
+ "more aggressive (e.g. 0.4 keeps ~40% of tokens). Unset (default): let "
+ "Kompress decide via its own importance threshold (conservative). "
+ "Env: HEADROOM_TARGET_RATIO."
+ ),
+)
@click.option(
"--intercept-tool-results",
is_flag=True,
@@ -616,6 +629,7 @@ def _selected_context_tool() -> str:
def proxy(
ctx: click.Context,
mode: str | None,
+ target_ratio: float | None,
host: str,
port: int,
workers: int,
@@ -818,7 +832,7 @@ def proxy(
tool_profiles=_parse_tool_profiles([]) or None,
smart_crusher_with_compaction=_get_env_bool_optional("HEADROOM_SMART_CRUSHER_COMPACTION"),
savings_profile=os.environ.get("HEADROOM_SAVINGS_PROFILE") or None,
- target_ratio=_get_env_float_optional("HEADROOM_TARGET_RATIO"),
+ target_ratio=target_ratio,
compress_system_messages=_get_env_bool_optional("HEADROOM_COMPRESS_SYSTEM_MESSAGES"),
protect_recent=_get_env_int_optional("HEADROOM_PROTECT_RECENT"),
protect_analysis_context=_get_env_bool_optional("HEADROOM_PROTECT_ANALYSIS_CONTEXT"),
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py
index 7e203b42e..e0e3b15b6 100644
--- a/headroom/transforms/content_router.py
+++ b/headroom/transforms/content_router.py
@@ -2486,7 +2486,9 @@ class ContentRouter(Transform):
# Two-tier compression cache.
# Tier 1 (skip): known won't-compress → instant skip.
# Tier 2 (result): known compresses → reuse compressed text.
- content_key = hash(content)
+ # Key on the runtime target_ratio too: the same content compressed at
+ # a different ratio is a different result, so it must not alias.
+ content_key = hash((content, getattr(self, "_runtime_target_ratio", None)))
# Tier 1: skip set — instant rejection
if self._cache.is_skipped(content_key):
@@ -2861,7 +2863,9 @@ class ContentRouter(Transform):
# Two-tier compression cache → shared helper
compressed_content, was_compressed = self._compress_block_content(
content=tool_content,
- content_key=hash(tool_content),
+ content_key=hash(
+ (tool_content, getattr(self, "_runtime_target_ratio", None))
+ ),
context=context,
bias=bias,
min_ratio=min_ratio,
@@ -2904,7 +2908,9 @@ class ContentRouter(Transform):
# Two-tier compression cache → shared helper
compressed_content, _was_compressed = self._compress_block_content(
content=text_content,
- content_key=hash(text_content),
+ content_key=hash(
+ (text_content, getattr(self, "_runtime_target_ratio", None))
+ ),
context=context,
bias=1.0,
min_ratio=min_ratio,