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(agent-savings): land coding + general workload personas on main (#1732)

Tejas Choprad8db7da77e07
diff --git a/headroom/agent_savings.py b/headroom/agent_savings.py
index 075633619..368b8e157 100644
--- a/headroom/agent_savings.py
+++ b/headroom/agent_savings.py
@@ -23,7 +23,10 @@ class AgentSavingsProfile:
name: str
target_savings: float
- target_ratio: float
+ # None = don't pin a keep-ratio; let Kompress decide adaptively (and any
+ # ambient HEADROOM_TARGET_RATIO / proxy default still applies). Workload
+ # personas leave this unset so savings emerge from lossless + relevance.
+ target_ratio: float | None
compress_user_messages: bool
compress_system_messages: bool
protect_recent: int
@@ -42,11 +45,10 @@ class AgentSavingsProfile:
def proxy_env(self) -> dict[str, str]:
"""Return env vars for Headroom proxy/wrapper entry points."""
- return {
+ env = {
"HEADROOM_MODE": self.proxy_mode,
"HEADROOM_SAVINGS_PROFILE": self.name,
"HEADROOM_SAVINGS_TARGET": f"{self.target_savings:.2f}",
- "HEADROOM_TARGET_RATIO": f"{self.target_ratio:.2f}",
"HEADROOM_COMPRESS_USER_MESSAGES": ("1" if self.compress_user_messages else "0"),
"HEADROOM_COMPRESS_SYSTEM_MESSAGES": ("1" if self.compress_system_messages else "0"),
"HEADROOM_PROTECT_RECENT": str(self.protect_recent),
@@ -59,6 +61,11 @@ class AgentSavingsProfile:
"HEADROOM_FORCE_KOMPRESS": "1" if self.force_kompress else "0",
"HEADROOM_ACCURACY_GUARD": self.accuracy_guard,
}
+ # Only pin a keep-ratio when the profile sets one; workload personas
+ # leave it unset so Kompress decides and the ambient default applies.
+ if self.target_ratio is not None:
+ env["HEADROOM_TARGET_RATIO"] = f"{self.target_ratio:.2f}"
+ return env
def apply_proxy_env_defaults(self, env: dict[str, str]) -> dict[str, str]:
"""Seed proxy env defaults without overriding explicit user settings."""
@@ -99,6 +106,46 @@ _PROFILES: dict[str, AgentSavingsProfile] = {
proxy_mode="token",
accuracy_guard="strict",
),
+ # Workload personas: compress aggressively while holding the three
+ # invariants — no accuracy loss, no extra turns, no prefix-cache bust.
+ # They rely on the defaults that already deliver this (relevance split on,
+ # user/system messages protected, read-maturation off, lossless structural
+ # compaction) and only set the workload-specific + visibility knobs. The
+ # MCP-vs-airgapped axis is the separate HEADROOM_LOSSLESS toggle: markers
+ # when a retrieve tool exists, marker-free lossless-first when air-gapped.
+ # target_ratio is unset — savings emerge from lossless + relevance, and
+ # Kompress decides its own keep. min_tokens is low so compression is
+ # actually exercised/visible on modest outputs.
+ "coding": AgentSavingsProfile(
+ name="coding",
+ target_savings=0.50, # nominal (display only); savings are emergent
+ target_ratio=None,
+ compress_user_messages=False, # no prompt mutation / cache bust
+ compress_system_messages=False, # system prompt is the hottest cache
+ protect_recent=2, # keep the active code working set verbatim
+ protect_analysis_context=True,
+ min_tokens_to_compress=25, # low → compression is visible
+ max_items_after_crush=15,
+ smart_crusher_with_compaction=True,
+ force_kompress=False, # don't override diff/log lossless with lossy ML
+ proxy_mode="token",
+ accuracy_guard="strict",
+ ),
+ "general": AgentSavingsProfile(
+ name="general",
+ target_savings=0.60, # nominal (display only); savings are emergent
+ target_ratio=None,
+ compress_user_messages=False,
+ compress_system_messages=False,
+ protect_recent=0, # little code; nothing positional to protect
+ protect_analysis_context=True,
+ min_tokens_to_compress=25,
+ max_items_after_crush=15,
+ smart_crusher_with_compaction=True,
+ force_kompress=False,
+ proxy_mode="token",
+ accuracy_guard="strict",
+ ),
}
@@ -142,7 +189,8 @@ def apply_agent_savings_profile(
config.compress_system_messages = resolved.compress_system_messages
config.protect_recent = resolved.protect_recent
config.protect_analysis_context = resolved.protect_analysis_context
- config.target_ratio = resolved.target_ratio
+ if resolved.target_ratio is not None:
+ config.target_ratio = resolved.target_ratio
config.min_tokens_to_compress = resolved.min_tokens_to_compress
return config
@@ -164,7 +212,6 @@ def proxy_pipeline_kwargs(config: object) -> dict[str, object]:
"compress_system_messages": profile.compress_system_messages,
"protect_recent": profile.protect_recent,
"protect_analysis_context": profile.protect_analysis_context,
- "target_ratio": profile.target_ratio,
"min_tokens_to_compress": profile.min_tokens_to_compress,
"max_items_after_crush": profile.max_items_after_crush,
"smart_crusher_with_compaction": profile.smart_crusher_with_compaction,
@@ -172,6 +219,10 @@ def proxy_pipeline_kwargs(config: object) -> dict[str, object]:
"read_protection_window": profile.protect_recent,
}
)
+ # Only pin a keep-ratio when the profile sets one (personas leave it
+ # unset → Kompress decides / ambient default applies).
+ if profile.target_ratio is not None:
+ kwargs["target_ratio"] = profile.target_ratio
if getattr(config, "compress_user_messages", False):
kwargs["compress_user_messages"] = True
diff --git a/tests/test_agent_savings.py b/tests/test_agent_savings.py
index 1eeae1519..15a555619 100644
--- a/tests/test_agent_savings.py
+++ b/tests/test_agent_savings.py
@@ -63,6 +63,53 @@ def test_agent_90_profile_exports_cross_agent_proxy_env() -> None:
assert env["HEADROOM_ACCURACY_GUARD"] == "strict"
+def test_coding_persona_protects_working_set_and_stays_visible() -> None:
+ profile = get_agent_savings_profile("coding")
+
+ env = profile.proxy_env()
+
+ assert env["HEADROOM_SAVINGS_PROFILE"] == "coding"
+ assert env["HEADROOM_PROTECT_RECENT"] == "2" # keep the active code working set verbatim
+ assert env["HEADROOM_MIN_TOKENS"] == "25" # low → compression is actually visible
+ assert env["HEADROOM_COMPRESS_USER_MESSAGES"] == "0" # no prompt mutation / cache bust
+ assert env["HEADROOM_COMPRESS_SYSTEM_MESSAGES"] == "0"
+ assert env["HEADROOM_ACCURACY_GUARD"] == "strict"
+ assert "HEADROOM_TARGET_RATIO" not in env # unset → Kompress / ambient default decides
+
+
+def test_general_persona_has_no_positional_code_protection() -> None:
+ profile = get_agent_savings_profile("general")
+
+ env = profile.proxy_env()
+
+ assert env["HEADROOM_PROTECT_RECENT"] == "0"
+ assert env["HEADROOM_MIN_TOKENS"] == "25"
+ assert "HEADROOM_TARGET_RATIO" not in env
+
+
+def test_personas_omit_target_ratio_in_pipeline_kwargs() -> None:
+ for name, expected_protect in (("coding", 2), ("general", 0)):
+ kwargs = proxy_pipeline_kwargs(ProxyConfig(savings_profile=name))
+
+ assert kwargs["protect_recent"] == expected_protect
+ assert kwargs["read_protection_window"] == expected_protect
+ assert kwargs["min_tokens_to_compress"] == 25
+ assert kwargs["compress_user_messages"] is False
+ assert kwargs["compress_system_messages"] is False
+ assert kwargs["force_kompress"] is False
+ assert "target_ratio" not in kwargs # persona never pins a keep-ratio
+
+
+def test_persona_apply_profile_leaves_target_ratio_untouched() -> None:
+ cfg = CompressConfig(target_ratio=0.42)
+
+ apply_agent_savings_profile(cfg, "coding")
+
+ assert cfg.protect_recent == 2
+ assert cfg.min_tokens_to_compress == 25
+ assert cfg.target_ratio == 0.42 # persona did not override an explicit ratio
+
+
def test_agent_savings_env_defaults_preserve_user_overrides() -> None:
env = {
"HEADROOM_TARGET_RATIO": "0.25",