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(proxy/model-router): add require_tools route condition (#2362)

Abhay Singhae75ca49a0af
diff --git a/headroom/proxy/model_router.py b/headroom/proxy/model_router.py
index 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 False
if self.require_no_tools and has_tools:
return False
+ if self.require_tools and not has_tools:
+ return False
if self.max_input_tokens is not None and input_tokens > self.max_input_tokens:
return False
if 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.py
index 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 == ()