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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat(agent-savings): land coding + general workload personas on main (#1732)
Tejas Choprad8db7da77e07
diff --git a/headroom/agent_savings.py b/headroom/agent_savings.pyindex 075633619..368b8e157 100644--- a/headroom/agent_savings.py+++ b/headroom/agent_savings.py@@ -23,7 +23,10 @@ class AgentSavingsProfile:name: strtarget_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 | Nonecompress_user_messages: boolcompress_system_messages: boolprotect_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 envdef 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_messagesconfig.protect_recent = resolved.protect_recentconfig.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_ratioconfig.min_tokens_to_compress = resolved.min_tokens_to_compressreturn 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_ratioif getattr(config, "compress_user_messages", False):kwargs["compress_user_messages"] = Truediff --git a/tests/test_agent_savings.py b/tests/test_agent_savings.pyindex 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",