feat: update HF model catalogue to prioritize chat-capable model and adjust tests for new routing logic

src/models/hf_catalogue.py

@@ -69,21 +69,19 @@ class HFModel:
 # router shifts over time; because this is plain data, retuning is a one-line edit.
 
 HF_MODELS: tuple[HFModel, ...] = (
-    # tiny ≤4B (Tiny-Titan band)
-    HFModel("meta-llama/Llama-3.2-3B-Instruct", profile="tiny", params_b=3, source="Meta Llama"),
-    HFModel("Qwen/Qwen2.5-3B-Instruct", params_b=3, source="Qwen"),
-    HFModel("microsoft/Phi-3.5-mini-instruct", params_b=3.8, source="Microsoft Phi"),
-    HFModel("HuggingFaceTB/SmolLM2-1.7B-Instruct", params_b=1.7, source="SmolLM"),
-    # fast ≤8B
-    HFModel("Qwen/Qwen2.5-7B-Instruct", profile="fast", params_b=7, source="Qwen"),
-    HFModel("mistralai/Mistral-7B-Instruct-v0.3", params_b=7, source="Mistral"),
-    HFModel("meta-llama/Llama-3.1-8B-Instruct", params_b=8, source="Meta Llama"),
-    # balanced ≤13B
-    HFModel("google/gemma-2-9b-it", profile="balanced", params_b=9, source="Google Gemma"),
-    # strong ≤32B
-    HFModel("Qwen/Qwen2.5-32B-Instruct", profile="strong", params_b=32, source="Qwen"),
-    HFModel("mistralai/Mistral-Small-24B-Instruct-2501", params_b=24, source="Mistral"),
-    HFModel("Qwen/Qwen2.5-14B-Instruct", params_b=14, source="Qwen"),
+    # Only chat-capable model currently live on the enabled HF providers (free
+    # `hf-inference`), verified by a real /v1/chat/completions call. Pinned to its
+    # provider so the router does not depend on paid-provider auto-routing. It is
+    # tagged `tiny` (1.5B, ≤4B band) but serves every tier: a tier with no dedicated
+    # HF model falls back to the first catalogue entry (see lab._default_model_key),
+    # so the whole cast routes here while only `hf-inference` is enabled.
+    HFModel("katanemo/Arch-Router-1.5B", profile="tiny", params_b=1.5, source="Katanemo", hf_provider="hf-inference"),
+    # NOTE: to use larger small models (e.g. openai/gpt-oss-20b — 20B, ≤32B, OpenAI
+    # track) enable a provider that serves them (together / nscale / fireworks /
+    # novita / groq) at https://huggingface.co/settings/inference-providers, then add
+    # the model here. `HuggingFaceBio/Carbon-3B` is intentionally NOT listed: the HF
+    # router rejects it as "not a chat model" (it is text-generation only), so it
+    # cannot drive the chat-completions path the engine uses.
 )
 
 

tests/test_hf_catalogue.py

@@ -31,15 +31,18 @@ def test_every_model_is_within_its_tier_param_cap():
             assert params <= _TIER_CAP[tier], f"{e['key']} ({params}B) exceeds {tier} cap"
 
 
-def test_each_logical_tier_has_a_default():
-    for tier in ("tiny", "fast", "balanced", "strong"):
-        assert hf_catalogue.default_key_for_profile(tier) is not None, f"no default for {tier}"
+def test_catalogue_has_a_tiny_default():
+    # The catalogue is currently scoped to the one chat-capable model live on the
+    # enabled providers (tagged tiny). Tiers without a dedicated model fall back to
+    # it at the UI layer (see lab._default_model_key), so they may return None here.
+    assert hf_catalogue.default_key_for_profile("tiny") == "katanemo/Arch-Router-1.5B"
 
 
 def test_binding_uses_router_url_and_token():
-    key = hf_catalogue.default_key_for_profile("fast")
+    key = hf_catalogue.default_key_for_profile("tiny")
     binding = hf_catalogue.binding_for(key, env={"HF_TOKEN": "hf_xyz"})
-    assert binding["model"] == f"openai/{key}"
+    # The model pins its provider (hf-inference) so routing needs no paid auto-select.
+    assert binding["model"] == f"openai/{key}:hf-inference"
     assert binding["base_url"] == hf_catalogue.DEFAULT_BASE_URL
     assert binding["api_key"] == "hf_xyz"
 

tests/test_inference_backends.py

@@ -64,7 +64,9 @@ def test_binding_dispatches_to_the_right_backend():
 
 
 def test_default_key_for_profile_is_backend_scoped():
-    hf_default = inference.default_key_for_profile("strong", "hf")
+    # HF currently tags only the tiny tier (its single live chat model); Modal tags
+    # every tier. The point here is that keys are namespaced per backend.
+    hf_default = inference.default_key_for_profile("tiny", "hf")
     assert hf_default is not None and hf_default.startswith("hf:")
     modal_default = inference.default_key_for_profile("strong", "modal")
     assert modal_default is not None and not modal_default.startswith("hf:")

tests/test_router.py

@@ -111,17 +111,18 @@ class TestModelRouterCatalogueEndpoint:
 
     def test_online_hf_endpoint_key_resolves_to_hf_router(self, monkeypatch):
         # A backend-qualified HF key resolves to the HF Inference router binding —
-        # the OpenAI-compatible model string + HF token, no Modal env needed.
+        # the OpenAI-compatible model string + HF token, no Modal env needed. The
+        # model pins its provider (hf-inference) so routing needs no paid auto-select.
         monkeypatch.setenv("HF_TOKEN", "hf_secret")
         monkeypatch.delenv("HF_INFERENCE_BASE_URL", raising=False)
-        monkeypatch.delenv("MODEL_FAST", raising=False)
+        monkeypatch.delenv("MODEL_TINY", raising=False)
         router = ModelRouter(offline=False)
-        provider = router.for_profile("hf:Qwen/Qwen2.5-7B-Instruct")
+        provider = router.for_profile("hf:katanemo/Arch-Router-1.5B")
         assert isinstance(provider, LiteLLMProvider)
-        assert provider.model == "openai/Qwen/Qwen2.5-7B-Instruct"
+        assert provider.model == "openai/katanemo/Arch-Router-1.5B:hf-inference"
         assert provider.api_base == "https://router.huggingface.co/v1"
         assert provider.api_key == "hf_secret"
-        assert provider.max_tokens == 320  # fast tier decoding (the model's tier)
+        assert provider.max_tokens == 192  # tiny tier decoding (the model's tier)
 
     def test_offline_hf_endpoint_key_serves_distinct_stub(self):
         # Offline, an HF key routes like any profile: the deterministic stub with the