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(proxy/model-router): add require_tools route condition (#2362)
Abhay Singhae75ca49a0af
diff --git a/headroom/proxy/model_router.py b/headroom/proxy/model_router.pyindex 06db73fa4..a46a002ac 100644--- a/headroom/proxy/model_router.py+++ b/headroom/proxy/model_router.py@@ -47,6 +47,14 @@ class ModelRoute:require_no_tools: bool = False"""Match only when the request declares no tools (a proxy for low-risk work)."""+ require_tools: bool = False+ """Match only when the request declares tools (a proxy for agentic work).++ The inverse of ``require_no_tools``: lets an operator route tool-using turns+ to a *more* capable model while keeping plain chat on a cheaper one. Setting+ both on one rule makes it unmatchable (an AND of contradictory conditions),+ which is a harmless operator error, not a crash."""+from_models: tuple[str, ...] = ()"""Restrict this rule to these source models. Empty = any source model."""@@ -59,6 +67,8 @@ class ModelRoute:return Falseif self.require_no_tools and has_tools:return False+ if self.require_tools and not has_tools:+ return Falseif self.max_input_tokens is not None and input_tokens > self.max_input_tokens:return Falseif self.min_input_tokens is not None and input_tokens < self.min_input_tokens:@@ -205,7 +215,15 @@ _INVALID = object()"""Sentinel: a route field was present but malformed (fail open, skip the route)."""_ALLOWED_ROUTE_KEYS = frozenset(- {"to_model", "max_input_tokens", "min_input_tokens", "require_no_tools", "from_models", "name"}+ {+ "to_model",+ "max_input_tokens",+ "min_input_tokens",+ "require_no_tools",+ "require_tools",+ "from_models",+ "name",+ })@@ -244,6 +262,11 @@ def _route_from_entry(entry: object, index: int) -> ModelRoute | None:)return None+ require_tools = entry.get("require_tools", False)+ if not isinstance(require_tools, bool):+ logger.warning("model route #%d 'require_tools' must be a boolean; skipping route", index)+ return None+from_models_raw = entry.get("from_models", [])if not isinstance(from_models_raw, list) or not all(isinstance(m, str) for m in from_models_raw@@ -258,6 +281,7 @@ def _route_from_entry(entry: object, index: int) -> ModelRoute | None:max_input_tokens=max_tokens, # type: ignore[arg-type]min_input_tokens=min_tokens, # type: ignore[arg-type]require_no_tools=require_no_tools,+ require_tools=require_tools,from_models=tuple(from_models_raw),name=str(entry.get("name", "")),)diff --git a/tests/test_proxy/test_model_router.py b/tests/test_proxy/test_model_router.pyindex 24b55cd87..97b9ac20f 100644--- a/tests/test_proxy/test_model_router.py+++ b/tests/test_proxy/test_model_router.py@@ -36,6 +36,22 @@ def test_route_from_models_restriction() -> None:assert not route.matches(model="claude-sonnet-4-6", input_tokens=1, has_tools=False)+def test_route_require_tools_matches_only_with_tools() -> None:+ # Inverse of require_no_tools: route agentic (tool-using) turns to a+ # stronger model, leaving plain chat alone.+ route = ModelRoute(to_model="strong", require_tools=True)+ assert route.matches(model="cheap", input_tokens=1, has_tools=True)+ assert not route.matches(model="cheap", input_tokens=1, has_tools=False)+++def test_route_require_tools_and_require_no_tools_never_matches() -> None:+ # Contradictory conditions on one rule are an AND that can never be true —+ # a harmless operator error, not a crash.+ route = ModelRoute(to_model="x", require_tools=True, require_no_tools=True)+ assert not route.matches(model="m", input_tokens=1, has_tools=True)+ assert not route.matches(model="m", input_tokens=1, has_tools=False)++def test_route_matches_even_for_same_model() -> None:# A same-model rule still MATCHES (strict first-match-wins); it is a no-op# that short-circuits later rules, enabling explicit exemption rules.@@ -177,6 +193,22 @@ def test_from_env_malformed_require_no_tools_skips_route() -> None:assert cfg.routes == ()+def test_from_env_parses_require_tools() -> None:+ cfg = ModelRouterConfig.from_env(+ "yes", '[{"name":"agentic","require_tools":true,"to_model":"strong"}]'+ )+ assert len(cfg.routes) == 1+ route = cfg.routes[0]+ assert route.require_tools is True+ assert route.to_model == "strong"+++def test_from_env_malformed_require_tools_skips_route() -> None:+ # A non-boolean must fail open (skip), never be coerced.+ cfg = ModelRouterConfig.from_env("yes", '[{"to_model":"m","require_tools":"yes"}]')+ assert cfg.routes == ()++def test_from_env_malformed_from_models_skips_route() -> None:assert (ModelRouterConfig.from_env("yes", '[{"to_model":"m","from_models":"gpt-5.5"}]').routes == ()