Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

feat(model-hub): declare catalog input modalities to the engine (#2302)

Call White64bbefc84f87
diff --git a/core/handlers/model_hub/adapter.py b/core/handlers/model_hub/adapter.py
index 88a6bbe34..29a68f361 100644
--- a/core/handlers/model_hub/adapter.py
+++ b/core/handlers/model_hub/adapter.py
@@ -91,6 +91,11 @@ class SourceBinding:
route_model_ids: tuple[str, ...] = ()
# Sorted API-key transport targets derived from effective routes, never
# inventory or capability evidence. Independent of live health and mode.
+ text_only_model_ids: tuple[str, ...] = ()
+ # Models among model_ids and route_model_ids that this Source's upstream
+ # declares text-only in its own models.dev entry. CLIProxyAPI replaces
+ # tool-result images for such an openai-compatibility model instead of
+ # forwarding them; every other model keeps them.
class OriginNotAllowedError(Exception):
diff --git a/core/handlers/model_hub/service.py b/core/handlers/model_hub/service.py
index 70bfd7803..9878d4165 100644
--- a/core/handlers/model_hub/service.py
+++ b/core/handlers/model_hub/service.py
@@ -209,6 +209,55 @@ def _cached_models_dev_catalog() -> Mapping[str, Any]:
return load_models_dev_catalog_with_date()[0]
+def _with_text_only_models(
+ bindings: list[SourceBinding],
+) -> list[SourceBinding]:
+ """Mark each bound model that its upstream's own models.dev entry declares text-only.
+
+ Only an ``openai_chat`` Source on its vendor's official endpoint has such
+ an entry: the vendor's mapped provider describes what that endpoint
+ accepts. Read at sync rather than in ``_bindings``: the cached copy
+ changes on its own, and a mutation compares the bindings it builds before
+ and after itself. The sync never fetches, and an unreadable copy leaves
+ every model undeclared, which is the engine's default.
+ """
+
+ from vibe.model_hub_runtime.api_key_vendors import official_models_dev_provider
+ from vibe.models_dev_catalog import cached_models_dev_catalog, text_only_model_ids
+
+ try:
+ providers = {
+ binding.source_id: official_models_dev_provider(binding.vendor, binding.base_url)
+ for binding in bindings
+ if binding.protocol == "openai_chat"
+ }
+ model_ids: dict[str, list[str]] = {}
+ for binding in bindings:
+ provider = providers.get(binding.source_id)
+ if provider is not None:
+ model_ids.setdefault(provider, []).extend((*binding.model_ids, *binding.route_model_ids))
+ if not model_ids:
+ return bindings
+ catalog = cached_models_dev_catalog()
+ text_only = {
+ provider: text_only_model_ids(provider, ids, catalog) for provider, ids in model_ids.items()
+ }
+ except Exception as exc: # noqa: BLE001 - optional metadata never fails a sync
+ logger.info("Model Hub engine models have no models.dev modalities: %s", type(exc).__name__)
+ return bindings
+ return [
+ replace(
+ binding,
+ text_only_model_ids=tuple(
+ model
+ for model in dict.fromkeys((*binding.model_ids, *binding.route_model_ids))
+ if model in text_only.get(providers.get(binding.source_id) or "", ())
+ ),
+ )
+ for binding in bindings
+ ]
+
+
_MODELS_DEV_CANDIDATE_FIELDS = (
"models_dev_id",
"context_window",
@@ -1470,6 +1519,8 @@ class ModelHubService:
if not bindings and not force_empty and not has_hub_sources:
self._engine_preparation_failed = False
return
+ # Reading the catalog copy takes tens of milliseconds; keep it off the loop.
+ bindings = await asyncio.to_thread(_with_text_only_models, bindings)
await self._engine_call(self.adapter.sync_sources(bindings))
self._engine_preparation_failed = False
@@ -7051,6 +7102,10 @@ class ModelHubService:
updated.enabled = True
updated.runtime_default_applied = True
self._save_projection_neutral(previous, updated)
+ # A start renders the persisted projection, whose text-only
+ # marks come from the catalog copy of its last sync. Syncing
+ # here gives an explicit start the current copy's marks.
+ self._engine_synced = False
await self._prepare_engine_for_demand()
status = await self._engine_call(self.adapter.start())
return _runtime_payload(status, enabled=True)
diff --git a/docs/plans/model-hub-contracts/adapter-interface.py b/docs/plans/model-hub-contracts/adapter-interface.py
index 88a6bbe34..29a68f361 100644
--- a/docs/plans/model-hub-contracts/adapter-interface.py
+++ b/docs/plans/model-hub-contracts/adapter-interface.py
@@ -91,6 +91,11 @@ class SourceBinding:
route_model_ids: tuple[str, ...] = ()
# Sorted API-key transport targets derived from effective routes, never
# inventory or capability evidence. Independent of live health and mode.
+ text_only_model_ids: tuple[str, ...] = ()
+ # Models among model_ids and route_model_ids that this Source's upstream
+ # declares text-only in its own models.dev entry. CLIProxyAPI replaces
+ # tool-result images for such an openai-compatibility model instead of
+ # forwarding them; every other model keeps them.
class OriginNotAllowedError(Exception):
diff --git a/tests/e2e/test_model_hub_routing.py b/tests/e2e/test_model_hub_routing.py
index b4a7a9720..c3903decb 100644
--- a/tests/e2e/test_model_hub_routing.py
+++ b/tests/e2e/test_model_hub_routing.py
@@ -10,6 +10,7 @@ from pathlib import Path
import aiohttp
import pytest
+import yaml
from core.handlers.model_hub.adapter import RawOutcomeKind
from core.handlers.model_hub.turn_gateway import ModelHubTurnGateway
@@ -533,6 +534,101 @@ def test_mh_routing_010_model_not_found_stays_request_scoped_through_real_gatewa
asyncio.run(exercise(adapter, first, second))
+_TOOL_RESULT_IMAGE_MARKER = "[image omitted: unsupported by upstream]"
+# One transparent pixel, the smallest well-formed PNG.
+_PNG_PIXEL = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
+
+
+def test_mh_modalities_003_claude_tool_result_image_reaches_a_text_only_model_as_the_marker(tmp_path, monkeypatch):
+ """MH-MODALITIES-003: a hot-reloaded text-only declaration makes the pinned CPA send the marker, not the image."""
+ from dataclasses import replace as replace_entry
+
+ from vibe import models_dev_catalog
+ from vibe.model_hub_runtime import api_key_vendors
+
+ async def exercise(adapter, upstream):
+ text_only, undeclared = "text-only-model", "undeclared-model"
+ # DeepSeek's official endpoint is the mock, so the Source is an official
+ # DeepSeek Source that DeepSeek's own models.dev entry describes.
+ presets = api_key_vendors._catalog_by_id()
+ monkeypatch.setattr(api_key_vendors, "_catalog_by_id", lambda: {
+ **presets, "deepseek": replace_entry(presets["deepseek"], official_base_url=upstream.url),
+ })
+ # Unreachable on purpose: the seeded copy is fresh, so nothing fetches it.
+ monkeypatch.setenv(models_dev_catalog.MODELS_DEV_URL_ENV, "http://127.0.0.1:9/models-dev.json")
+ models_dev_catalog._write_cache({
+ "url": models_dev_catalog._models_dev_url(),
+ "fetched_at": time.time(),
+ "catalog": {"deepseek": {"models": {text_only: {"modalities": {"input": ["text"]}}}}},
+ })
+ upstream.configure(protocol="openai_chat", models=[{"id": undeclared}])
+ item = source("src_modalities1", [undeclared], vendor="deepseek", protocol="openai_chat")
+ item.credential_ref = adapter.state_store.store_api_key(
+ "sk-synthetic-modalities", vendor="deepseek", protocol="openai_chat", base_url=None,
+ )
+ menu = fixed_model("claude")
+ service = service_for(
+ tmp_path, MemoryModelHubStore(config_with_sources([item], hops=((item.id, undeclared),))), adapter,
+ )
+ await service.runtime_start()
+ connection = adapter.supervisor.client_if_running().connection
+ config_path = next(adapter.state_store.root.glob("instances/*/config.yaml"))
+ gateway = ModelHubTurnGateway(service)
+
+ async def forward_screenshot(target: str) -> str:
+ base_url, token = await gateway.endpoint(
+ "claude", process_scope=f"{tmp_path}/{target}", turn_id=f"turn_{target}",
+ requested_model_id=menu, resolved_model_id=target, source_id=item.id,
+ )
+ upstream.reset_requests()
+ async with aiohttp.ClientSession(trust_env=False) as client:
+ async with client.post(f"{base_url}/v1/messages", headers={"Authorization": f"Bearer {token}"}, json={
+ "model": target,
+ "max_tokens": 32,
+ "stream": False,
+ "messages": [
+ {"role": "user", "content": "Take a screenshot."},
+ {"role": "assistant", "content": [
+ {"type": "tool_use", "id": "call_1", "name": "screenshot", "input": {}},
+ ]},
+ {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "call_1", "content": [
+ {"type": "text", "text": "screenshot taken"},
+ {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": _PNG_PIXEL}},
+ ]}]},
+ ],
+ }) as response:
+ raw = await asyncio.wait_for(response.read(), timeout=15)
+ assert response.status == 200, raw
+ [received] = [row for row in upstream.requests() if row["path"] == "/v1/chat/completions"]
+ assert received["body"]["model"] == target
+ return json.dumps(received["body"])
+
+ def declared_modalities() -> dict[str, object]:
+ [compat] = yaml.safe_load(config_path.read_text(encoding="utf-8"))["openai-compatibility"]
+ return {model["name"]: model.get("input-modalities") for model in compat["models"]}
+
+ try:
+ assert declared_modalities()[undeclared] is None
+ forwarded = await forward_screenshot(undeclared)
+ assert _PNG_PIXEL in forwarded
+ assert _TOOL_RESULT_IMAGE_MARKER not in forwarded
+
+ # The text-only model first reaches the running engine as a route
+ # target, through the same hot reload every Model Hub save uses.
+ await service.set_agent_chain("claude", menu, {"hops": [{"source_id": item.id, "model_id": text_only}]})
+ assert adapter.supervisor.client_if_running().connection == connection
+ assert declared_modalities()[text_only] == ["text"]
+ forwarded = await forward_screenshot(text_only)
+ assert _TOOL_RESULT_IMAGE_MARKER in forwarded
+ assert _PNG_PIXEL not in forwarded
+ assert adapter.supervisor.client_if_running().connection == connection
+ finally:
+ await gateway.close()
+
+ with MockLLMUpstream() as upstream, _isolated_engine_adapter(tmp_path, monkeypatch) as adapter:
+ asyncio.run(exercise(adapter, upstream))
+
+
@pytest.mark.parametrize("settings_scope", ["home", "project", "local"])
def test_mh_claude_launch_001_settings_cannot_bypass_the_configured_route(
model_hub_app_factory, mock_llm_upstream, settings_scope,
diff --git a/tests/scenarios/INDEX.yaml b/tests/scenarios/INDEX.yaml
index 08c18bbfe..8bf2fc629 100644
--- a/tests/scenarios/INDEX.yaml
+++ b/tests/scenarios/INDEX.yaml
@@ -80,6 +80,7 @@ capabilities:
- tests/test_ui_server_fastapi.py
- tests/test_model_hub_quota.py
- tests/test_model_hub_pricing.py
+ - tests/test_models_dev_catalog.py
- tests/test_local_deps.py
- tests/test_opencode_server.py
- tests/test_runtime_activation.py
diff --git a/tests/scenarios/model_hub/catalog.yaml b/tests/scenarios/model_hub/catalog.yaml
index a4a2ea003..9257bb02b 100644
--- a/tests/scenarios/model_hub/catalog.yaml
+++ b/tests/scenarios/model_hub/catalog.yaml
@@ -26,6 +26,7 @@ capability:
- tests/test_ui_server_fastapi.py
- tests/test_model_hub_quota.py
- tests/test_model_hub_pricing.py
+ - tests/test_models_dev_catalog.py
- ui/src/components/settings/models/QuotaTab.test.tsx
- ui/src/components/settings/models/usageProjection.test.ts
- ui/src/components/settings/models/format.test.ts
@@ -1345,6 +1346,30 @@ scenarios:
kind: recovery
layer: scenario
test: tests/scenarios/model_hub/test_model_hub_turn_contract_scenarios.py::test_mh_mid_turn_engine_loss_never_replays_after_output_starts
+ - id: MH-MODALITIES-001
+ name: Engine config declares text-only input only on openai-compatibility models, marks models the engine cannot tell apart together or not at all, and omits the key otherwise
+ status: covered
+ kind: contract
+ layer: unit
+ test: tests/test_model_hub_runtime.py::test_engine_config_declares_text_only_input_only_on_openai_compatibility_models
+ - id: MH-MODALITIES-002
+ name: Engine sync marks only models their official upstream's own models.dev entry declares text-only, from the cached copy without fetching
+ status: covered
+ kind: projection
+ layer: unit
+ test: tests/test_model_hub_api.py::test_engine_sync_marks_models_their_official_upstream_declares_text_only
+ - id: MH-MODALITIES-003
+ name: Real gateway and pinned CPA send a text-only model the marker instead of a tool-result image after a hot reload
+ status: assert
+ kind: transport
+ layer: e2e
+ test: tests/e2e/test_model_hub_routing.py::test_mh_modalities_003_claude_tool_result_image_reaches_a_text_only_model_as_the_marker
+ - id: MH-MODALITIES-004
+ name: A model is text-only only when its upstream provider's own entry, matched by Avibe's model identity, declares text and no image
+ status: covered
+ kind: safety
+ layer: unit
+ test: tests/test_models_dev_catalog.py::test_text_only_reads_the_upstream_providers_own_entry
- id: MH-CREDENTIAL-001
name: Credential rejection retries once only for a refreshable credential
status: covered
diff --git a/tests/test_model_hub_api.py b/tests/test_model_hub_api.py
index 5f6c39f0f..bebfab4cb 100644
--- a/tests/test_model_hub_api.py
+++ b/tests/test_model_hub_api.py
@@ -8,6 +8,7 @@ import io
import json
import re
import threading
+import time
from contextlib import asynccontextmanager
from datetime import datetime, timezone
from pathlib import Path
@@ -4999,6 +5000,106 @@ def test_public_mutations_sync_the_engine_only_when_bindings_change(tmp_path, mu
assert service._engine_synced is True
+def _vendor_route_fixture(store: MemoryStore, model_id: str) -> None:
+ """One route over three openai_chat Sources: DeepSeek official, DeepSeek via a relay URL, and custom."""
+
+ _set_claude_route_fixture(store, ("src_official01", "src_relayurl01", "src_custom0001"), model_id)
+ for source, (vendor, base_url) in zip(store.config.sources, (
+ ("deepseek", None),
+ ("deepseek", "https://relay.example/v1"),
+ ("custom", "https://api.example.test/v1"),
+ )):
+ source.vendor, source.protocol, source.base_url = vendor, "openai_chat", base_url
+
+
+def _cache_models_dev(provider_models: dict) -> None:
+ from vibe import models_dev_catalog
+
+ models_dev_catalog._write_cache({
+ "url": models_dev_catalog.DEFAULT_MODELS_DEV_URL,
+ # A day-old copy is still the copy a sync reads; only its own readers refresh it.
+ "fetched_at": 0,
+ "catalog": {name: {"models": models} for name, models in provider_models.items()},
+ })
+
+
+def test_engine_sync_marks_models_their_official_upstream_declares_text_only(tmp_path, monkeypatch):
+ """MH-MODALITIES-002: only a Source on its vendor's official endpoint is marked, from that vendor's own entry."""
+
+ from vibe import models_dev_catalog
+
+ refreshes = []
+ monkeypatch.setattr(models_dev_catalog, "_refresh_in_background", lambda: refreshes.append(True))
+ _cache_models_dev({
+ "deepseek": {
+ _PROJECTION_MODEL: {"modalities": {"input": ["text"]}},
+ "vision-model": {"modalities": {"input": ["text", "image"]}},
+ },
+ # A relay's copy says nothing about DeepSeek's endpoint.
+ "relay": {"routed-text-model": {"modalities": {"input": ["text"]}}},
+ })
+ service, store, adapter = _service(tmp_path)
+ _vendor_route_fixture(store, _PROJECTION_MODEL)
+ service._engine_synced = True
+
+ asyncio.run(_confirm_guard(lambda guard: service.set_agent_chain(
+ "claude",
+ _PROJECTION_MODEL,
+ {"hops": [
+ {"source_id": "src_official01", "model_id": _PROJECTION_MODEL},
+ {"source_id": "src_official01", "model_id": "vision-model"},
+ {"source_id": "src_official01", "model_id": "routed-text-model"},
+ {"source_id": "src_relayurl01", "model_id": _PROJECTION_MODEL},
+ {"source_id": "src_custom0001", "model_id": _PROJECTION_MODEL},
+ ], **guard},
+ )))
+
+ [synced] = adapter.synced
+ by_id = {binding.source_id: binding for binding in synced}
+ assert {"vision-model", "routed-text-model"} <= set(by_id["src_official01"].route_model_ids)
+ assert by_id["src_official01"].text_only_model_ids == (_PROJECTION_MODEL,)
+ assert by_id["src_relayurl01"].text_only_model_ids == ()
+ assert by_id["src_custom0001"].text_only_model_ids == ()
+ assert refreshes == []
+
+
+def test_engine_sync_survives_a_source_whose_stored_port_cannot_be_read(tmp_path):
+ """MH-MODALITIES-002: optional modality metadata never fails a sync, even for a URL an older release stored."""
+
+ service, store, adapter = _service(tmp_path)
+ _vendor_route_fixture(store, _PROJECTION_MODEL)
+ store.config.sources[1].base_url = "https://api.deepseek.com:bad/v1"
+ _cache_models_dev({"deepseek": {_PROJECTION_MODEL: {"modalities": {"input": ["text"]}}}})
+
+ asyncio.run(service.runtime_start())
+
+ by_id = {binding.source_id: binding for binding in adapter.synced[-1]}
+ assert by_id["src_official01"].text_only_model_ids == (_PROJECTION_MODEL,)
+ assert by_id["src_relayurl01"].text_only_model_ids == ()
+
+
+def test_runtime_start_recomputes_text_only_marks_from_the_current_catalog_copy(tmp_path):
+ """MH-MODALITIES-002: an explicit start renders marks from today's copy, not the copy of the last sync."""
+
+ service, store, adapter = _service(tmp_path)
+ _vendor_route_fixture(store, _PROJECTION_MODEL)
+ _cache_models_dev({"deepseek": {_PROJECTION_MODEL: {"modalities": {"input": ["text"]}}}})
+ asyncio.run(service.runtime_start())
+ assert adapter.synced[-1][0].text_only_model_ids == (_PROJECTION_MODEL,)
+
+ # The copy refreshes while the engine keeps its projection; a stop and a
+ # start later, the model is known to accept images.
+ _cache_models_dev({"deepseek": {_PROJECTION_MODEL: {"modalities": {"input": ["text", "image"]}}}})
+ for agent in store.config.agents.values():
+ agent.mode = "direct"
+ asyncio.run(service.runtime_stop())
+ asyncio.run(service.runtime_start())
+
+ assert len(adapter.synced) == 2
+ assert adapter.synced[-1][0].text_only_model_ids == ()
+ assert adapter.start_calls == 2
+
+
def test_source_adoption_projection_is_sorted_by_backend_and_menu_model(tmp_path):
service, store, _adapter = _service(tmp_path)
source = ModelHubSourceConfig(
diff --git a/tests/test_model_hub_runtime.py b/tests/test_model_hub_runtime.py
index 7635a5275..89d3b45a3 100644
--- a/tests/test_model_hub_runtime.py
+++ b/tests/test_model_hub_runtime.py
@@ -52,7 +52,7 @@ from vibe.model_hub_runtime import client as client_module
from vibe.model_hub_runtime import installer as runtime_installer_module
from vibe.model_hub_runtime import supervisor as supervisor_module
from vibe.model_hub_runtime.adapter import CLIProxyEngineAdapter
-from vibe.model_hub_runtime.api_key_vendors import api_key_vendor_catalog
+from vibe.model_hub_runtime.api_key_vendors import api_key_vendor_catalog, official_models_dev_provider
from vibe.model_hub_runtime.client import EngineClient, EngineClientError, EngineConnection
from vibe.model_hub_runtime.config import write_engine_config
from vibe.model_hub_runtime.environment import engine_subprocess_environment
@@ -1653,6 +1653,155 @@ def test_config_generation_is_private_and_never_logs_secrets(
store.prepare_instance("install-1")
+def test_engine_config_declares_text_only_input_only_on_openai_compatibility_models(
+ tmp_path: Path,
+) -> None:
+ """MH-MODALITIES-001: CPA replaces tool-result images only for a declared text-only openai-compatibility model."""
+
+ store = EngineStateStore(tmp_path / "state")
+ instance_dir, runtime_secrets = store.prepare_instance("install-1")
+ chat_ref = store.store_api_key("chat-secret", base_url="https://api.example.test/v1")
+ responses_ref = store.store_api_key("responses-secret", vendor="openai", protocol="openai_responses")
+ anthropic_ref = store.store_api_key("anthropic-secret", vendor="anthropic", protocol="anthropic")
+ store.sync_sources(
+ [
+ _binding(
+ chat_ref,
+ model_ids=("text-model", "unknown-model"),
+ route_model_ids=("routed-text-model",),
+ text_only_model_ids=("text-model", "routed-text-model"),
+ ),
+ *(
+ _binding(
+ credential_ref,
+ source_id=source_id,
+ vendor=vendor,
+ protocol=protocol,
+ base_url=None,
+ model_ids=("text-model",),
+ text_only_model_ids=("text-model",),
+ )
+ for credential_ref, source_id, vendor, protocol in (
+ (responses_ref, "src_responses1", "openai", "openai_responses"),
+ (anthropic_ref, "src_anthropic1", "anthropic", "anthropic"),
+ )
+ ),
+ ]
+ )
+ config_path = instance_dir / "config.yaml"
+
+ write_engine_config(
+ config_path,
+ host="127.0.0.1",
+ port=18231,
+ auth_dir=store.auth_dir,
+ runtime_secrets=runtime_secrets,
+ sources=store.list_sources(),
+ state_store=store,
+ )
+
+ payload = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+ # CPA matches a request to an entry by name, then by alias; both are the
+ # routed ID, so either lookup reaches the entry that carries the key.
+ assert payload["openai-compatibility"][0]["models"] == [
+ {"name": "text-model", "alias": "text-model", "display-name": "text-model #0", "input-modalities": ["text"]},
+ {"name": "unknown-model", "alias": "unknown-model", "display-name": "unknown-model #0"},
+ {
+ "name": "routed-text-model",
+ "alias": "routed-text-model",
+ "display-name": "routed-text-model #0",
+ "input-modalities": ["text"],
+ },
+ ]
+ for key in ("codex-api-key", "claude-api-key"):
+ [entry] = payload[key]
+ assert entry["models"] == [
+ {"name": "text-model", "alias": "text-model", "display-name": "text-model #0"}
+ ]
+
+
+def _rendered_text_only(tmp_path: Path, model_ids: tuple[str, ...], text_only: tuple[str, ...]) -> set[str]:
+ store = EngineStateStore(tmp_path / "state")
+ instance_dir, runtime_secrets = store.prepare_instance("install-1")
+ chat_ref = store.store_api_key("chat-secret", base_url="https://api.example.test/v1")
+ store.sync_sources([_binding(chat_ref, model_ids=model_ids, text_only_model_ids=text_only)])
+ config_path = instance_dir / "config.yaml"
+ write_engine_config(
+ config_path,
+ host="127.0.0.1",
+ port=18231,
+ auth_dir=store.auth_dir,
+ runtime_secrets=runtime_secrets,
+ sources=store.list_sources(),
+ state_store=store,
+ )
+ [compat] = yaml.safe_load(config_path.read_text(encoding="utf-8"))["openai-compatibility"]
+ return {model["name"] for model in compat["models"] if model.get("input-modalities") == ["text"]}
+
+
+def test_engine_config_declares_models_the_engine_cannot_tell_apart_together_or_not_at_all(tmp_path: Path) -> None:
+ """MH-MODALITIES-001: CPA's lookup folds case and drops a (...) suffix, so such a group is marked whole or not at all."""
+
+ assert _rendered_text_only(
+ tmp_path,
+ ("target", "TARGET", "other", "other(high)", "solo"),
+ ("target", "other", "other(high)", "solo"),
+ ) == {"other", "other(high)", "solo"}
+
+
[email protected]("seed", range(50))
+def test_engine_config_never_declares_a_model_the_engine_could_confuse_with_an_unmarked_one(tmp_path: Path, seed: int) -> None:
+ """MH-MODALITIES-001: every rendered mark was asked for, and no unmarked model shares its engine name."""
+
+ import random
+
+ rng = random.Random(seed)
+ spellings = ["target", "Target", "TARGET", "target(high)", "Target (low)", "other", "OTHER(x)", "solo"]
+ model_ids = tuple(rng.sample(spellings, rng.randrange(1, len(spellings) + 1)))
+ text_only = tuple(model for model in model_ids if rng.random() < 0.7)
+
+ def engine_name(model: str) -> str:
+ # Written out from CLIProxyAPI v7.3.16's normalizeOpenAICompatibilityModelName.
+ name = model.strip()
+ if "(" in name and name.endswith(")"):
+ name = name[: name.rindex("(")]
+ return name.strip().lower()
+
+ rendered = _rendered_text_only(tmp_path / str(seed), model_ids, text_only)
+
+ assert rendered <= set(text_only)
+ unmarked_names = {engine_name(model) for model in model_ids if model not in rendered}
+ assert not {engine_name(model) for model in rendered} & unmarked_names
+ # Nothing is withheld that the guard does not require.
+ assert {model for model in text_only if engine_name(model) not in {
+ engine_name(other) for other in model_ids if other not in text_only
+ }} == rendered
+
+
+def test_engine_record_reads_an_unreadable_text_only_list_as_undeclared(caplog: pytest.LogCaptureFixture) -> None:
+ """Undeclared is the engine default, so a shape this release cannot read degrades to it, with a warning."""
+
+ record = SourceRecord.from_payload(
+ {
+ "source_id": "src_fixture123",
+ "vendor": "custom",
+ "protocol": "openai_chat",
+ "base_url": "https://api.example.test/v1",
+ "credential_ref": "cred_fixture123",
+ "model_ids": ["text-model"],
+ "prefix": "avibe-fixture",
+ "model_reasoning_efforts": [],
+ "text_only_model_ids": {"text-model": ["text"]},
+ }
+ )
+
+ assert record.model_ids == ("text-model",)
+ assert record.text_only_model_ids == ()
+ assert any(
+ record.levelname == "WARNING" and "src_fixture123" in record.getMessage() for record in caplog.records
+ )
+
+
def test_mixed_anthropic_credentials_disable_cloak_only_for_api_key_entry(
tmp_path: Path,
) -> None:
@@ -2085,6 +2234,35 @@ def test_catalog_official_base_url_composes_one_probe_endpoint(
assert len(versions) == 1, composed
+ ("vendor", "base_url", "provider"),
+ [
+ ("deepseek", None, "deepseek"),
+ ("deepseek", "https://api.deepseek.com", "deepseek"),
+ # The engine calls one endpoint for each of these spellings.
+ ("deepseek", "https://api.deepseek.com/v1", "deepseek"),
+ ("deepseek", "https://API.DeepSeek.com/", "deepseek"),
+ ("deepseek", "https://api.deepseek.com:443/v1/", "deepseek"),
+ ("qwen", "https://dashscope.aliyuncs.com/compatible-mode/v1/", "alibaba-cn"),
+ # Any other endpoint may front another deployment.
+ ("deepseek", "https://api.deepseek.com/beta", None),
+ ("deepseek", "http://api.deepseek.com", None),
+ ("deepseek", "https://api.deepseek.com:8443", None),
+ # A stored port no connection can use names no official endpoint.
+ ("deepseek", "https://api.deepseek.com:bad/v1", None),
+ ("deepseek", "https://api.deepseek.com:99999/v1", None),
+ ("deepseek", "https://relay.example/v1", None),
+ ("qwen", "https://dashscope-intl.aliyuncs.com/compatible-mode/v1", None),
+ ("custom", None, None),
+ ("openai", None, None),
+ ],
+)
+def test_only_a_vendors_official_endpoint_is_described_by_its_models_dev_provider(vendor, base_url, provider) -> None:
+ """MH-MODALITIES-002: the vendor's models.dev entries describe the endpoint the engine calls, in any spelling."""
+
+ assert official_models_dev_provider(vendor, base_url) == provider
+
+
@pytest.mark.parametrize(
("vendor", "protocol", "expected_base_url"),
API_KEY_VENDOR_RUNTIME_CASES,
diff --git a/tests/test_models_dev_catalog.py b/tests/test_models_dev_catalog.py
index 8cd7e3da2..59d8551c9 100644
--- a/tests/test_models_dev_catalog.py
+++ b/tests/test_models_dev_catalog.py
@@ -375,6 +375,98 @@ def test_exact_models_dev_matches_never_borrow_a_neighbour():
assert models_dev_catalog.exact_models_dev_matches(["gpt-target"], {}) == {}
+def _entry(declared: object, **fields: object) -> dict:
+ return {**fields, "modalities": {"input": declared}}
+
+
+ ("entries", "requested", "text_only"),
+ [
+ ({"target": _entry(["text"])}, "target", True),
+ ({"target": _entry([" TEXT ", "pdf"])}, "target", True),
+ ({"target": _entry(["text", "image"])}, "target", False),
+ ({"target": _entry(["text", " Image "])}, "target", False),
+ # Undeclared or malformed input leaves the model undeclared.
+ ({"target": {"name": "No modalities"}}, "target", False),
+ ({"target": _entry([])}, "target", False),
+ ({"target": _entry(["text", 1])}, "target", False),
+ ({"target": _entry("text")}, "target", False),
+ ({"target": "not-an-object"}, "target", False),
+ ({"target": _entry(["image"])}, "target", False),
+ # Model identity is Avibe's: trimmed, case preserved.
+ ({"target": _entry(["text"])}, " target ", True),
+ ({"target": _entry(["text"])}, "TARGET", False),
+ ({"TARGET": _entry(["text", "image"]), "target": _entry(["text"])}, "TARGET", False),
+ # An entry is found by its key or its id; one that disagrees vetoes.
+ ({"hosted-7": _entry(["text"], id="target")}, "target", True),
+ ({"target": _entry(["text"]), "alias": _entry(["text", "image"], id="target")}, "target", False),
+ ({"other": _entry(["text"])}, "target", False),
+ ],
+)
+def test_text_only_reads_the_upstream_providers_own_entry(entries, requested, text_only):
+ """MH-MODALITIES-004: a model is text-only when its upstream provider's own entry declares text and no image."""
+
+ catalog = {"deepseek": {"models": entries}}
+
+ assert models_dev_catalog.text_only_model_ids("deepseek", [requested], catalog) == (
+ {requested} if text_only else set()
+ )
+
+
+def test_text_only_never_reads_another_providers_copy():
+ """MH-MODALITIES-004: a relay's declaration describes the relay, so it neither marks nor vetoes the vendor."""
+
+ catalog = {
+ "zhipuai": {"models": {"glm-5.2": _entry(["text"])}},
+ "baseten": {"models": {"zai-org/GLM-5.2": _entry(["text", "image"])}},
+ "relay": {"models": {"deepseek-model": _entry(["text"])}},
+ "deepseek": {"models": {}},
+ }
+
+ assert models_dev_catalog.text_only_model_ids("zhipuai", ["glm-5.2"], catalog) == {"glm-5.2"}
+ assert models_dev_catalog.text_only_model_ids("deepseek", ["deepseek-model"], catalog) == set()
+
+
+def test_text_only_warns_about_an_unreadable_provider_without_touching_others(caplog):
+ """MH-MODALITIES-004: an unreadable or missing provider declares nothing and says so; other providers are unaffected."""
+
+ catalog = {
+ "deepseek": {"models": [_entry(["text"])]},
+ "zhipuai": {"models": {"glm-5": _entry(["text"])}},
+ }
+
+ with caplog.at_level("WARNING", logger=models_dev_catalog.__name__):
+ assert models_dev_catalog.text_only_model_ids("deepseek", ["deepseek-model"], catalog) == set()
+ assert models_dev_catalog.text_only_model_ids("zhipuai", ["glm-5"], catalog) == {"glm-5"}
+ assert models_dev_catalog.text_only_model_ids("groq", ["model"], catalog) == set()
+ # No cached copy yet is not a fault.
+ assert models_dev_catalog.text_only_model_ids("groq", ["model"], {}) == set()
+
+ messages = [record.getMessage() for record in caplog.records if record.name == models_dev_catalog.__name__]
+ assert len(messages) == 2
+ assert "deepseek" in messages[0] and "zhipuai" not in messages[0]
+ assert "groq" in messages[1]
+
+
+def test_cached_catalog_read_does_not_wait_on_a_foreground_fetch(monkeypatch, tmp_path):
+ """MH-MODALITIES-002: an engine sync reads the cached copy while a picker fetch holds the cache lock."""
+
+ import threading
+
+ monkeypatch.setattr(models_dev_catalog, "_cache_path", lambda: tmp_path / "models_dev_catalog.json")
+ models_dev_catalog._write_cache({"url": models_dev_catalog._models_dev_url(), "fetched_at": 0, "catalog": _catalog()})
+ read: list[dict] = []
+ with models_dev_catalog._CACHE_LOCK:
+ reader = threading.Thread(target=lambda: read.append(models_dev_catalog.cached_models_dev_catalog()))
+ reader.start()
+ reader.join(timeout=5)
+ waited = reader.is_alive()
+ reader.join(timeout=5)
+
+ assert not waited
+ assert read == [_catalog()]
+
+
def test_first_catalog_read_reports_one_fetch_in_flight_until_it_fails(monkeypatch, tmp_path):
"""MH-PRICE-014: With no cached copy, readers start one fetch and say one is coming; after a failure they do not."""
diff --git a/vibe/data/api_key_vendors.json b/vibe/data/api_key_vendors.json
index 09c55af3b..cfbaa1618 100644
--- a/vibe/data/api_key_vendors.json
+++ b/vibe/data/api_key_vendors.json
@@ -21,60 +21,70 @@
"id": "gemini",
"label": "Gemini",
"official_base_url": "https://generativelanguage.googleapis.com/v1beta/openai",
- "protocol": "openai_chat"
+ "protocol": "openai_chat",
+ "models_dev_provider": "google"
},
{
"id": "deepseek",
"label": "DeepSeek",
"official_base_url": "https://api.deepseek.com",
- "protocol": "openai_chat"
+ "protocol": "openai_chat",
+ "models_dev_provider": "deepseek"
},
{
"id": "qwen",
"label": "Qwen",
"official_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
- "protocol": "openai_chat"
+ "protocol": "openai_chat",
+ "models_dev_provider": "alibaba-cn"
},
{
"id": "kimi",
"label": "Kimi",
"official_base_url": "https://api.moonshot.cn/v1",
- "protocol": "openai_chat"
+ "protocol": "openai_chat",
+ "models_dev_provider": "moonshotai-cn"
},
{
"id": "openrouter",
"label": "OpenRouter",
"official_base_url": "https://openrouter.ai/api/v1",
- "protocol": "openai_chat"
+ "protocol": "openai_chat",
+ "models_dev_provider": "openrouter"
},
{
"id": "zhipuai",
"label": "Zhipu AI",
"official_base_url": "https://open.bigmodel.cn/api/paas/v4",
- "protocol": "openai_chat"
+ "protocol": "openai_chat",
+ "models_dev_provider": "zhipuai"
},
{
"id": "mistral",
"label": "Mistral",
"official_base_url": "https://api.mistral.ai/v1",
- "protocol": "openai_chat"
+ "protocol": "openai_chat",
+ "models_dev_provider": "mistral"
},
{
"id": "groq",
"label": "Groq",
"official_base_url": "https://api.groq.com/openai/v1",
- "protocol": "openai_chat"
+ "protocol": "openai_chat",
+ "models_dev_provider": "groq"
},
{
"id": "together",
"label": "Together",
"official_base_url": "https://api.together.xyz/v1",
- "protocol": "openai_chat"
+ "protocol": "openai_chat",
+ "models_dev_provider": "togetherai"
},
{
"id": "fireworks",
"label": "Fireworks",
"official_base_url": "https://api.fireworks.ai/inference/v1",
- "protocol": "openai_chat"
+ "protocol": "openai_chat",
+ "models_dev_provider": "fireworks-ai"
}
]
diff --git a/vibe/model_hub_runtime/api_key_vendors.py b/vibe/model_hub_runtime/api_key_vendors.py
index 1d25fc773..3aa47a36f 100644
--- a/vibe/model_hub_runtime/api_key_vendors.py
+++ b/vibe/model_hub_runtime/api_key_vendors.py
@@ -120,6 +120,9 @@ class APIKeyVendorCatalogEntry:
label: str
official_base_url: str
protocol: str
+ # The models.dev provider whose entries describe what this vendor's
+ # official endpoint accepts; ``None`` when no mapping has been verified.
+ models_dev_provider: str | None = None
def _catalog_path() -> Path:
@@ -141,6 +144,7 @@ def api_key_vendor_catalog() -> tuple[APIKeyVendorCatalogEntry, ...]:
label = item.get("label")
protocol = item.get("protocol")
official_base_url = normalize_model_hub_base_url(item.get("official_base_url"))
+ models_dev_provider = item.get("models_dev_provider")
if (
vendor_id == "custom"
or vendor_id in seen_ids
@@ -149,6 +153,10 @@ def api_key_vendor_catalog() -> tuple[APIKeyVendorCatalogEntry, ...]:
or not isinstance(protocol, str)
or protocol not in _SUPPORTED_PROTOCOLS
or official_base_url is None
+ or (
+ models_dev_provider is not None
+ and (not isinstance(models_dev_provider, str) or not models_dev_provider.strip())
+ )
):
raise ValueError("api-key vendor catalog is invalid")
entries.append(
@@ -157,6 +165,7 @@ def api_key_vendor_catalog() -> tuple[APIKeyVendorCatalogEntry, ...]:
label=label.strip(),
official_base_url=official_base_url,
protocol=protocol,
+ models_dev_provider=models_dev_provider.strip() if models_dev_provider else None,
)
)
seen_ids.add(vendor_id)
@@ -190,6 +199,50 @@ def official_api_key_base_url(vendor: str) -> str | None:
return _LEGACY_OFFICIAL_BASE_URLS.get(normalized_vendor)
+def openai_compatible_endpoint(base_url: str) -> str:
+ """The API root the engine calls for an ``openai_chat`` Source's base URL.
+
+ CLIProxyAPI appends ``/chat/completions``; a Source origin without a path
+ uses the standard ``/v1`` root that discovery and probes use.
+ """
+ endpoint = normalize_model_hub_base_url(base_url)
+ assert endpoint is not None
+ if not urlsplit(endpoint).path.rstrip("/"):
+ endpoint = normalize_model_hub_base_url(endpoint, append_path="/v1")
+ assert endpoint is not None
+ return endpoint
+
+
+def _endpoint_identity(base_url: str) -> tuple[str, str, int | None, str, str] | None:
+ parts = urlsplit(openai_compatible_endpoint(base_url))
+ try:
+ port = parts.port or {"http": 80, "https": 443}.get(parts.scheme)
+ except ValueError:
+ # A stored URL may carry a port no connection can use; it names no
+ # official endpoint.
+ return None
+ return parts.scheme, parts.hostname or "", port, parts.path, parts.query
+
+
+def official_models_dev_provider(vendor: str, base_url: str | None) -> str | None:
+ """The models.dev provider describing an ``openai_chat`` Source's upstream, or ``None``.
+
+ Only a Source on its vendor's official endpoint is described by that
+ vendor's models.dev entries: a custom URL may front any deployment. The
+ endpoint is the one the engine calls, so spellings of one URL that differ
+ only by host case, a default port, or the implied ``/v1`` root agree.
+ """
+ entry = api_key_vendor_entry(vendor)
+ if entry is None or entry.models_dev_provider is None:
+ return None
+ if base_url is not None and (
+ _endpoint_identity(base_url) is None
+ or _endpoint_identity(base_url) != _endpoint_identity(entry.official_base_url)
+ ):
+ return None
+ return entry.models_dev_provider
+
+
def official_api_key_base_urls() -> dict[str, str]:
return {
**{entry.id: entry.official_base_url for entry in api_key_vendor_catalog()},
diff --git a/vibe/model_hub_runtime/config.py b/vibe/model_hub_runtime/config.py
index 1ba2c0468..f60130d91 100644
--- a/vibe/model_hub_runtime/config.py
+++ b/vibe/model_hub_runtime/config.py
@@ -8,7 +8,11 @@ import yaml
from config.atomic_io import write_atomic
from config.v2_config import normalize_model_hub_base_url
-from vibe.model_hub_runtime.api_key_vendors import official_api_key_base_url, validate_api_key_auth_scheme
+from vibe.model_hub_runtime.api_key_vendors import (
+ official_api_key_base_url,
+ openai_compatible_endpoint,
+ validate_api_key_auth_scheme,
+)
from vibe.model_hub_runtime.state import EngineStateError, EngineStateStore, RuntimeSecrets, SourceRecord
@@ -117,8 +121,19 @@ def _append_source(
except ValueError:
raise EngineStateError("unsupported API key authentication scheme") from None
reasoning_by_model = dict(source.model_reasoning_efforts)
+ # CLIProxyAPI reads input modalities only on openai-compatibility models,
+ # matching an entry by name, then alias. For one declared text-only it
+ # replaces tool-result images with a marker; any other list, or none,
+ # keeps images, so text-only is the only declaration worth writing.
+ # Its name match is looser than a routed ID (see _engine_model_name) and
+ # takes the first entry that matches, so models it cannot tell apart are
+ # declared text-only together or not at all.
+ routed = tuple(dict.fromkeys((*source.model_ids, *source.route_model_ids)))
+ marked = set(source.text_only_model_ids) if source.protocol == "openai_chat" else set()
+ unmarked_names = {_engine_model_name(model) for model in routed if model not in marked}
+ text_only = {model for model in marked if _engine_model_name(model) not in unmarked_names}
models = []
- for model in dict.fromkeys((*source.model_ids, *source.route_model_ids)):
+ for model in routed:
entry: dict[str, Any] = {
"name": model,
"alias": model,
@@ -128,6 +143,8 @@ def _append_source(
if reasoning_efforts:
# CLIProxyAPI's measured model-registration shape is strongest-first.
entry["thinking"] = {"levels": list(reversed(reasoning_efforts))}
+ if model in text_only:
+ entry["input-modalities"] = ["text"]
models.append(entry)
if source.protocol == "anthropic":
base_url = source.base_url
@@ -163,21 +180,11 @@ def _append_source(
base_url = official_api_key_base_url(source.vendor)
if not base_url:
raise EngineStateError("OpenAI-compatible source requires a base URL")
- normalized_base_url = normalize_model_hub_base_url(base_url)
- assert normalized_base_url is not None
- if not urlsplit(normalized_base_url).path.rstrip("/"):
- # CLIProxyAPI appends /chat/completions; Source origins use the
- # standard /v1 endpoint root used by discovery and probes.
- normalized_base_url = normalize_model_hub_base_url(
- normalized_base_url,
- append_path="/v1",
- )
- assert normalized_base_url is not None
payload.setdefault("openai-compatibility", []).append(
{
"name": source.prefix,
"prefix": source.prefix,
- "base-url": normalized_base_url,
+ "base-url": openai_compatible_endpoint(base_url),
"api-key-entries": [{"api-key": api_key}],
"models": models,
}
@@ -202,6 +209,19 @@ def expected_model_names(
return expected
+def _engine_model_name(model: str) -> str:
+ """The name CLIProxyAPI compares when it looks up a model's input modalities.
+
+ It trims the name, drops a trailing ``(...)`` thinking suffix, trims again,
+ and compares case-insensitively.
+ """
+ name = model.strip()
+ suffix = name.rfind("(")
+ if suffix != -1 and name.endswith(")"):
+ name = name[:suffix]
+ return name.strip().casefold()
+
+
def reload_display_name(model: str, generation: str) -> str:
return f"{model} #{generation}"
diff --git a/vibe/model_hub_runtime/state.py b/vibe/model_hub_runtime/state.py
index deb3deb51..5123a30d6 100644
--- a/vibe/model_hub_runtime/state.py
+++ b/vibe/model_hub_runtime/state.py
@@ -114,6 +114,7 @@ class SourceRecord:
prefix: str
model_reasoning_efforts: tuple[tuple[str, tuple[str, ...]], ...] = ()
route_model_ids: tuple[str, ...] = ()
+ text_only_model_ids: tuple[str, ...] = ()
@classmethod
def from_payload(cls, payload: dict[str, Any]) -> SourceRecord:
@@ -162,9 +163,26 @@ class SourceRecord:
prefix=str(payload["prefix"]),
model_reasoning_efforts=tuple(parsed_reasoning_efforts),
route_model_ids=tuple(route_model_ids),
+ text_only_model_ids=_stored_text_only_model_ids(
+ str(payload["source_id"]), payload.get("text_only_model_ids", [])
+ ),
)
+def _stored_text_only_model_ids(source_id: str, raw: object) -> tuple[str, ...]:
+ # Undeclared input is the engine's default, so a list this release cannot
+ # read degrades to that rather than failing the source. The next sync
+ # rewrites it; until then the Source's images are forwarded, and the log
+ # says why.
+ if not isinstance(raw, list) or not all(isinstance(model, str) and model for model in raw):
+ logger.warning(
+ "Engine source %s has an unreadable text-only model list; its models are undeclared until the next sync",
+ source_id,
+ )
+ return ()
+ return tuple(dict.fromkeys(raw))
+
+
class EngineStateStore:
"""Restricted local state for engine-only keys and upstream credentials."""
@@ -642,6 +660,25 @@ class EngineStateStore:
continue
spellings[normalized_model_id] = answered
reasoning_by_model[normalized_model_id] = normalized_efforts
+ normalized_route_model_ids = tuple(
+ sorted(
+ {
+ model_id_without_credential_address(model, prefix)
+ for model in route_model_ids
+ }
+ )
+ )
+ text_only_model_ids = tuple(
+ dict.fromkeys(
+ model_id_without_credential_address(str(model).strip(), prefix)
+ for model in binding.text_only_model_ids
+ )
+ )
+ if any(
+ model not in (*model_ids, *normalized_route_model_ids)
+ for model in text_only_model_ids
+ ):
+ raise EngineStateError("text-only model id is not registered")
records.append(
SourceRecord(
source_id=source_id,
@@ -651,16 +688,10 @@ class EngineStateStore:
credential_ref=credential_ref,
allowed_origins=allowed_origins,
model_ids=model_ids,
- route_model_ids=tuple(
- sorted(
- {
- model_id_without_credential_address(model, prefix)
- for model in route_model_ids
- }
- )
- ),
+ route_model_ids=normalized_route_model_ids,
prefix=prefix,
model_reasoning_efforts=tuple(reasoning_by_model.items()),
+ text_only_model_ids=text_only_model_ids,
)
)
self._write_sources(records)
@@ -694,11 +725,17 @@ class EngineStateStore:
for model_id, efforts in current.model_reasoning_efforts
if model_id in models
)
+ retained_text_only = tuple(
+ model_id
+ for model_id in current.text_only_model_ids
+ if model_id in models or model_id in current.route_model_ids
+ )
updated_record = SourceRecord(
**{
**asdict(current),
"model_ids": models,
"model_reasoning_efforts": retained_reasoning,
+ "text_only_model_ids": retained_text_only,
}
)
self._write_sources([updated_record if source.source_id == source_id else source for source in sources])
@@ -1167,6 +1204,7 @@ class EngineStateStore:
[model_id, list(efforts)]
for model_id, efforts in source.model_reasoning_efforts
],
+ "text_only_model_ids": list(source.text_only_model_ids),
}
for source in sources
]
diff --git a/vibe/models_dev_catalog.py b/vibe/models_dev_catalog.py
index cbfee2f57..3e3b0930a 100644
--- a/vibe/models_dev_catalog.py
+++ b/vibe/models_dev_catalog.py
@@ -19,6 +19,7 @@ from config.v2_config import (
normalize_storable_backend_model_text,
)
from core.handlers.model_hub.catalog_admission import admissible_backend_model
+from core.handlers.model_hub.identifiers import normalized_model_id
logger = logging.getLogger(__name__)
@@ -277,6 +278,20 @@ def load_models_dev_catalog_with_date() -> tuple[dict[str, Any], float | None, b
return {}, None, _refresh_in_background()
+def cached_models_dev_catalog() -> dict[str, Any]:
+ """The cached copy as it stands, stale or not, and never a fetch.
+
+ For readers that must not start or wait on network I/O, such as an engine
+ sync. The foreground loader holds ``_CACHE_LOCK`` across its fetch, and the
+ copy is replaced atomically, so this read takes no lock. The readers above
+ keep the copy fresh.
+ """
+
+ cached = _read_cache()
+ catalog = _catalog_from_cache(cached) if cached.get("url") == _models_dev_url() else None
+ return catalog or {}
+
+
def _search_tokens(query: str) -> tuple[str, ...]:
lowered = query.strip().lower()
tokens = [lowered]
@@ -577,3 +592,57 @@ def exact_models_dev_matches(
vendor_map,
)
return matches
+
+
+def text_only_model_ids(
+ provider_id: str,
+ model_ids: Iterable[str],
+ catalog: dict[str, Any],
+) -> set[str]:
+ """The ids one models.dev provider's own entries declare text-only.
+
+ A provider's entry describes what its upstream accepts; a copy under any
+ other provider describes a different deployment and is not read. An id
+ matches an entry whose key or ``id`` is the same model identity: trimmed,
+ case preserved. It is text-only when every entry it matches has a
+ ``modalities.input`` that is a non-empty list of strings which, compared
+ as the engine compares them, contains ``text`` and not ``image``. A
+ provider whose models cannot be read declares nothing, and says so.
+ """
+
+ provider = catalog.get(provider_id)
+ if provider is None:
+ if catalog:
+ logger.warning(
+ "models.dev has no provider %s; none of its models is declared text-only", provider_id
+ )
+ return set()
+ models = provider.get("models") if isinstance(provider, dict) else None
+ if not isinstance(models, dict):
+ logger.warning(
+ "models.dev provider %s has no readable models map; none of its models is declared text-only",
+ provider_id,
+ )
+ return set()
+
+ def declares_text_only(declared: object) -> bool:
+ if not isinstance(declared, list) or not declared or not all(
+ isinstance(value, str) for value in declared
+ ):
+ return False
+ values = {value.strip().lower() for value in declared}
+ return "text" in values and "image" not in values
+
+ wanted: dict[str, list[str]] = {}
+ for model_id in dict.fromkeys(model_ids):
+ wanted.setdefault(normalized_model_id(model_id), []).append(model_id)
+ text_only: dict[str, bool] = {}
+ for model_key, model in models.items():
+ names = {normalized_model_id(str(model_key))}
+ if isinstance(model, dict) and isinstance(model.get("id"), str):
+ names.add(normalized_model_id(model["id"]))
+ modalities = model.get("modalities") if isinstance(model, dict) else None
+ verdict = declares_text_only(modalities.get("input") if isinstance(modalities, dict) else None)
+ for requested in {requested for name in names for requested in wanted.get(name, ())}:
+ text_only[requested] = text_only.get(requested, True) and verdict
+ return {requested for requested, verdict in text_only.items() if verdict}