Skip to content

Personal AI, On Personal Devices

Python

fix(routing): rank unknown cloud models for escalation (#959)

Haotian Zheng2a21b7731a54
diff --git a/docs/architecture/learning.md b/docs/architecture/learning.md
index 85df2ccb..80aeac44 100644
--- a/docs/architecture/learning.md
+++ b/docs/architecture/learning.md
@@ -120,6 +120,9 @@ The `HeuristicRouter` is the default routing policy. It is defined in `learning/
!!! note "Priority 5 overrides all others"
The urgency check (rule 5) is evaluated **first** in the code — if urgency exceeds 0.8, the router immediately returns the smallest model regardless of query content.
+!!! note "Models without public parameter counts"
+ Cloud catalog entries use `parameter_count_b = 0.0` because providers do not publish those figures. When a largest-model rule fires, an explicitly cloud-backed model is treated as a separate high-capability tier so it can beat a known local model; an unknown non-cloud model is not assumed to be large.
+
### Usage
```python
diff --git a/src/openjarvis/learning/routing/router.py b/src/openjarvis/learning/routing/router.py
index 78956ea4..d03b351f 100644
--- a/src/openjarvis/learning/routing/router.py
+++ b/src/openjarvis/learning/routing/router.py
@@ -51,6 +51,27 @@ def _model_size(key: str) -> float:
return 0.0
+def _model_rank(key: str) -> tuple[int, float]:
+ """Return the capability rank used when selecting the largest model.
+
+ A positive parameter count is the strongest signal for local models. Cloud
+ providers do not publish parameter counts, so their catalog entries use
+ ``0.0``; an explicitly cloud-backed model gets a separate higher tier
+ instead of being treated as smaller than every known local model. Models
+ with unknown non-cloud metadata remain at the lowest tier.
+ """
+ try:
+ spec = ModelRegistry.get(key)
+ size = spec.parameter_count_b
+ if size > 0:
+ return (1, size)
+ if "cloud" in spec.supported_engines:
+ return (2, 0.0)
+ except (KeyError, AttributeError, TypeError) as exc:
+ logger.debug("Failed to compute model capability rank: %s", exc)
+ return (0, 0.0)
+
+
def _find_model_by_tag(available: List[str], tag: str) -> Optional[str]:
"""Find the first available model whose key contains *tag* (case-insensitive)."""
tag_lower = tag.lower()
@@ -61,16 +82,16 @@ def _find_model_by_tag(available: List[str], tag: str) -> Optional[str]:
def _largest_model(available: List[str]) -> Optional[str]:
- """Return the model with the largest parameter count from the available list."""
+ """Return the most capable model from the available list."""
if not available:
return None
best = available[0]
- best_size = _model_size(best)
+ best_rank = _model_rank(best)
for key in available[1:]:
- size = _model_size(key)
- if size > best_size:
+ rank = _model_rank(key)
+ if rank > best_rank:
best = key
- best_size = size
+ best_rank = rank
return best
diff --git a/tests/learning/test_router.py b/tests/learning/test_router.py
index e4b7def3..506224d9 100644
--- a/tests/learning/test_router.py
+++ b/tests/learning/test_router.py
@@ -93,6 +93,28 @@ class TestHeuristicRouter:
assert ctx.complexity_score > 0.20
assert router.select_model(ctx) == "large"
+ def test_unknown_local_model_does_not_beat_known_local_model(self) -> None:
+ _register_models()
+ ModelRegistry.register_value(
+ "unknown-local",
+ ModelSpec(
+ model_id="unknown-local",
+ name="Unknown local model",
+ parameter_count_b=0.0,
+ context_length=4096,
+ supported_engines=("ollama",),
+ ),
+ )
+ router = HeuristicRouter(available_models=["small", "unknown-local"])
+ ctx = RoutingContext(
+ query="solve this carefully",
+ query_length=20,
+ has_math=True,
+ complexity_score=0.4,
+ )
+
+ assert router.select_model(ctx) == "small"
+
def test_low_complexity_math_prefers_small(self) -> None:
"""Regression test: a trivial math query ("calculate 2+2") must not
escalate to the largest model just because it contains a math
diff --git a/tests/learning/test_routing_models.py b/tests/learning/test_routing_models.py
index ceea8de9..dbf76f03 100644
--- a/tests/learning/test_routing_models.py
+++ b/tests/learning/test_routing_models.py
@@ -83,6 +83,18 @@ class TestRouterWithNewModels:
selected = router.select_model(ctx)
assert selected == "gpt-oss:120b"
+ def test_unknown_cloud_model_escalates_over_known_local(self) -> None:
+ _setup_models()
+ router = HeuristicRouter(available_models=["qwen3:8b", "gpt-5-mini"])
+ ctx = RoutingContext(
+ query="prove this carefully",
+ query_length=20,
+ has_math=True,
+ complexity_score=0.4,
+ )
+
+ assert router.select_model(ctx) == "gpt-5-mini"
+
def test_high_complexity_routes_to_largest(self) -> None:
_setup_models()
router = HeuristicRouter(