Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Make ProviderModelInfo the sole model-catalog contract (#1222)

Ali Khokhar2a676cc6d99d
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 4322897c..70305fae 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -582,8 +582,10 @@ compatibility layer.
- `ProviderConfig`: shared provider settings such as API key, base URL, rate
limits, timeouts, proxy, and logging flags. It is a frozen internal
value whose base URL has already been resolved from the catalog.
-- `BaseProvider`: the abstract implementation base for cleanup, model listing,
- explicit preflight, and `stream_response()`.
+- `BaseProvider`: the abstract implementation base for cleanup, explicit
+ preflight, `stream_response()`, and the sole provider catalog operation,
+ `list_model_infos()`. Providers return application-owned `ProviderModelInfo`
+ values directly; there is no parallel IDs-only catalog contract.
There is one upstream transport family:
[providers/openai_chat/](src/free_claude_code/providers/openai_chat/) implements the concrete
diff --git a/pyproject.toml b/pyproject.toml
index eaca8340..226e845f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.11.6"
+version = "4.11.7"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/providers/base.py b/src/free_claude_code/providers/base.py
index 14a8de4c..246c1be2 100644
--- a/src/free_claude_code/providers/base.py
+++ b/src/free_claude_code/providers/base.py
@@ -15,7 +15,6 @@ from free_claude_code.core.diagnostics import (
)
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
from free_claude_code.core.trace import trace_event
-from free_claude_code.providers.model_listing import model_infos_from_ids
@dataclass(frozen=True, slots=True)
@@ -102,12 +101,8 @@ class BaseProvider(ABC):
"""Release any resources held by this provider."""
@abstractmethod
- async def list_model_ids(self) -> frozenset[str]:
- """Return the model ids currently advertised by this provider."""
-
async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
- """Return advertised model ids with optional provider capability metadata."""
- return model_infos_from_ids(await self.list_model_ids())
+ """Return the model metadata currently advertised by this provider."""
@abstractmethod
def stream_response(
diff --git a/src/free_claude_code/providers/cloudflare/client.py b/src/free_claude_code/providers/cloudflare/client.py
index 7215b796..e2ba36ab 100644
--- a/src/free_claude_code/providers/cloudflare/client.py
+++ b/src/free_claude_code/providers/cloudflare/client.py
@@ -16,8 +16,7 @@ from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.http import maybe_await_aclose
from free_claude_code.providers.model_listing import (
ModelListResponseError,
- extract_openai_model_ids,
- model_infos_from_ids,
+ extract_openai_model_infos,
)
from free_claude_code.providers.openai_chat import (
ChatTemplateReasoning,
@@ -96,12 +95,8 @@ class CloudflareProvider(OpenAIChatProvider):
await super().cleanup()
await self._model_list_client.aclose()
- async def list_model_ids(self) -> frozenset[str]:
- """Return Cloudflare Workers AI model ids from account model search."""
- return frozenset(info.model_id for info in await self.list_model_infos())
-
async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
- """Return Cloudflare Workers AI model ids from account model search."""
+ """Return Cloudflare Workers AI metadata from account model search."""
async def request() -> httpx.Response:
response = await self._model_list_client.get(
@@ -124,9 +119,7 @@ class CloudflareProvider(OpenAIChatProvider):
raise ModelListResponseError(
"CLOUDFLARE model-list response is malformed: invalid JSON"
) from exc
- return model_infos_from_ids(
- extract_openai_model_ids(payload, provider_name="CLOUDFLARE")
- )
+ return extract_openai_model_infos(payload, provider_name="CLOUDFLARE")
finally:
await maybe_await_aclose(response)
diff --git a/src/free_claude_code/providers/github_models/client.py b/src/free_claude_code/providers/github_models/client.py
index 5e8c0011..87c0ef28 100644
--- a/src/free_claude_code/providers/github_models/client.py
+++ b/src/free_claude_code/providers/github_models/client.py
@@ -60,10 +60,6 @@ class GitHubModelsProvider(OpenAIChatProvider):
await super().cleanup()
await self._model_list_client.aclose()
- async def list_model_ids(self) -> frozenset[str]:
- """Return GitHub Models ids that support FCC's streaming tool workflow."""
- return frozenset(info.model_id for info in await self.list_model_infos())
-
async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
"""Return stream/tool-capable GitHub Models catalog ids."""
diff --git a/src/free_claude_code/providers/model_listing.py b/src/free_claude_code/providers/model_listing.py
index 3d0f6f17..13d4a5bd 100644
--- a/src/free_claude_code/providers/model_listing.py
+++ b/src/free_claude_code/providers/model_listing.py
@@ -27,8 +27,10 @@ def model_infos_from_ids(
)
-def extract_openai_model_ids(payload: Any, *, provider_name: str) -> frozenset[str]:
- """Extract model ids from an OpenAI-compatible ``/models`` response."""
+def extract_openai_model_infos(
+ payload: Any, *, provider_name: str
+) -> frozenset[_ProviderModelInfo]:
+ """Extract model metadata from an OpenAI-compatible ``/models`` response."""
data = _field(payload, "data")
if not _is_sequence(data):
raise _malformed(provider_name, "expected top-level data array")
@@ -42,19 +44,7 @@ def extract_openai_model_ids(payload: Any, *, provider_name: str) -> frozenset[s
if not model_ids:
raise _malformed(provider_name, "response did not include any model ids")
- return frozenset(model_ids)
-
-
-def extract_openrouter_tool_model_ids(
- payload: Any, *, provider_name: str
-) -> frozenset[str]:
- """Extract OpenRouter model ids that advertise tool-use support."""
- return frozenset(
- info.model_id
- for info in extract_openrouter_tool_model_infos(
- payload, provider_name=provider_name
- )
- )
+ return model_infos_from_ids(model_ids)
def extract_openrouter_tool_model_infos(
diff --git a/src/free_claude_code/providers/open_router/client.py b/src/free_claude_code/providers/open_router/client.py
index 03ef869f..becfab9f 100644
--- a/src/free_claude_code/providers/open_router/client.py
+++ b/src/free_claude_code/providers/open_router/client.py
@@ -12,10 +12,7 @@ from free_claude_code.core.anthropic.streaming import AnthropicStreamLedger
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.base import ProviderConfig
-from free_claude_code.providers.model_listing import (
- extract_openrouter_tool_model_ids,
- extract_openrouter_tool_model_infos,
-)
+from free_claude_code.providers.model_listing import extract_openrouter_tool_model_infos
from free_claude_code.providers.openai_chat import (
OpenAIChatProfile,
OpenAIChatProvider,
@@ -45,13 +42,6 @@ class OpenRouterProvider(OpenAIChatProvider):
admission=admission,
)
- async def list_model_ids(self) -> frozenset[str]:
- """Only advertise OpenRouter models that can run Claude Code tools."""
- payload = await self._list_models_payload()
- return extract_openrouter_tool_model_ids(
- payload, provider_name=self._provider_name
- )
-
async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
"""Advertise OpenRouter tool models with reasoning capability metadata."""
payload = await self._list_models_payload()
diff --git a/src/free_claude_code/providers/openai_chat/provider.py b/src/free_claude_code/providers/openai_chat/provider.py
index f61f31f6..12fbc741 100644
--- a/src/free_claude_code/providers/openai_chat/provider.py
+++ b/src/free_claude_code/providers/openai_chat/provider.py
@@ -10,6 +10,7 @@ import httpx
from loguru import logger
from openai import AsyncOpenAI
+from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.core.anthropic import (
ContentType,
HeuristicToolParser,
@@ -43,7 +44,7 @@ from free_claude_code.providers.http import (
close_provider_stream,
maybe_await_aclose,
)
-from free_claude_code.providers.model_listing import extract_openai_model_ids
+from free_claude_code.providers.model_listing import extract_openai_model_infos
from free_claude_code.providers.stream_recovery import (
RecoveryController,
RecoveryFailureAction,
@@ -124,13 +125,13 @@ class OpenAIChatProvider(BaseProvider):
if client is not None:
await client.close()
- async def list_model_ids(self) -> frozenset[str]:
- """Return model ids from the provider's OpenAI-compatible models endpoint."""
+ async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
+ """Return model metadata from the OpenAI-compatible models endpoint."""
payload = await self._admission.run_with_retry(
self._client.models.list,
provider_failure_override=self._provider_failure_override,
)
- return extract_openai_model_ids(payload, provider_name=self._provider_name)
+ return extract_openai_model_infos(payload, provider_name=self._provider_name)
def _build_request_body(
self,
diff --git a/src/free_claude_code/providers/runtime/model_cache.py b/src/free_claude_code/providers/runtime/model_cache.py
index 54f224c1..b67cc133 100644
--- a/src/free_claude_code/providers/runtime/model_cache.py
+++ b/src/free_claude_code/providers/runtime/model_cache.py
@@ -4,7 +4,6 @@ from collections.abc import Iterable
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.provider_catalog import SUPPORTED_PROVIDER_IDS
-from free_claude_code.providers.model_listing import model_infos_from_ids
class ProviderModelCache:
@@ -17,10 +16,6 @@ class ProviderModelCache:
self._available_provider_ids = frozenset(available_provider_ids)
self._model_infos_by_provider: dict[str, dict[str, ProviderModelInfo]] = {}
- def cache_model_ids(self, provider_id: str, model_ids: Iterable[str]) -> None:
- """Store raw provider model ids with unknown capability metadata."""
- self.cache_model_infos(provider_id, model_infos_from_ids(model_ids))
-
def cache_model_infos(
self, provider_id: str, model_infos: Iterable[ProviderModelInfo]
) -> None:
@@ -61,10 +56,6 @@ class ProviderModelCache:
return None
return info.supports_thinking
- def cached_prefixed_model_refs(self) -> tuple[str, ...]:
- """Return cached provider models in user-selectable ``provider/model`` form."""
- return tuple(info.model_id for info in self.cached_prefixed_model_infos())
-
def cached_prefixed_model_infos(self) -> tuple[ProviderModelInfo, ...]:
"""Return cached provider models with user-selectable prefixed ids."""
infos: list[ProviderModelInfo] = []
diff --git a/src/free_claude_code/providers/vertex/client.py b/src/free_claude_code/providers/vertex/client.py
index 79d5ed96..209a684b 100644
--- a/src/free_claude_code/providers/vertex/client.py
+++ b/src/free_claude_code/providers/vertex/client.py
@@ -5,6 +5,7 @@ from typing import Any
import httpx
+from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.core.anthropic import ReasoningReplayMode
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.base import ProviderConfig
@@ -14,7 +15,10 @@ from free_claude_code.providers.google_openai import (
validate_google_extra_body,
)
from free_claude_code.providers.http import maybe_await_aclose
-from free_claude_code.providers.model_listing import ModelListResponseError
+from free_claude_code.providers.model_listing import (
+ ModelListResponseError,
+ model_infos_from_ids,
+)
from free_claude_code.providers.openai_chat import (
OpenAIChatProfile,
OpenAIChatRequestPolicy,
@@ -76,7 +80,7 @@ class VertexProvider(GoogleOpenAIProvider):
finally:
await self._model_list_client.aclose()
- async def list_model_ids(self) -> frozenset[str]:
+ async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
"""List Vertex publisher models and translate their resource names."""
model_ids: set[str] = set()
page_token: str | None = None
@@ -97,7 +101,7 @@ class VertexProvider(GoogleOpenAIProvider):
"VERTEX model-list response is malformed: response did not include "
"any model ids"
)
- return frozenset(model_ids)
+ return model_infos_from_ids(model_ids)
async def _list_model_page(self, page_token: str | None) -> Any:
async def request() -> httpx.Response:
diff --git a/tests/api/test_api_handlers.py b/tests/api/test_api_handlers.py
index 73220062..8cdb80ff 100644
--- a/tests/api/test_api_handlers.py
+++ b/tests/api/test_api_handlers.py
@@ -12,6 +12,7 @@ from free_claude_code.api.handlers import (
TokenCountHandler,
)
from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.settings import Settings
from free_claude_code.core.anthropic.models import (
Message,
@@ -50,8 +51,8 @@ class FakeProvider:
async def cleanup(self) -> None:
return None
- async def list_model_ids(self) -> frozenset[str]:
- return frozenset({"test-model"})
+ async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
+ return frozenset({ProviderModelInfo("test-model")})
async def stream_response(
self,
diff --git a/tests/providers/test_bedrock.py b/tests/providers/test_bedrock.py
index f360ab4c..b2a5133c 100644
--- a/tests/providers/test_bedrock.py
+++ b/tests/providers/test_bedrock.py
@@ -5,6 +5,7 @@ from unittest.mock import AsyncMock, patch
import pytest
+from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.provider_catalog import BEDROCK_DEFAULT_BASE
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import OpenAIChatProvider
@@ -137,7 +138,10 @@ async def test_model_discovery_uses_mantle_openai_models_endpoint() -> None:
)
)
- assert await provider.list_model_ids() == frozenset(
- {"openai.gpt-oss-120b", "amazon.nova-pro-v1:0"}
+ assert await provider.list_model_infos() == frozenset(
+ {
+ ProviderModelInfo("openai.gpt-oss-120b"),
+ ProviderModelInfo("amazon.nova-pro-v1:0"),
+ }
)
provider._client.models.list.assert_awaited_once_with()
diff --git a/tests/providers/test_cloudflare.py b/tests/providers/test_cloudflare.py
index 45bd1892..d97c18ec 100644
--- a/tests/providers/test_cloudflare.py
+++ b/tests/providers/test_cloudflare.py
@@ -8,6 +8,7 @@ import httpx
import pytest
from free_claude_code.application.errors import ApplicationUnavailableError
+from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.provider_catalog import CLOUDFLARE_AI_REST_ROOT
from free_claude_code.core.anthropic.models import Message, MessagesRequest
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
@@ -188,10 +189,10 @@ async def test_lists_models_from_cloudflare_model_search_endpoint(
new_callable=AsyncMock,
return_value=response,
) as mock_get:
- assert await cloudflare_provider.list_model_ids() == frozenset(
+ assert await cloudflare_provider.list_model_infos() == frozenset(
{
- "@cf/moonshotai/kimi-k2.6",
- "@cf/meta/llama-4-scout-17b-16e-instruct",
+ ProviderModelInfo("@cf/moonshotai/kimi-k2.6"),
+ ProviderModelInfo("@cf/meta/llama-4-scout-17b-16e-instruct"),
}
)
diff --git a/tests/providers/test_github_models.py b/tests/providers/test_github_models.py
index f921de1d..ea3e5ad6 100644
--- a/tests/providers/test_github_models.py
+++ b/tests/providers/test_github_models.py
@@ -8,6 +8,7 @@ from unittest.mock import AsyncMock, patch
import httpx
import pytest
+from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.provider_catalog import GITHUB_MODELS_DEFAULT_BASE
from free_claude_code.core.anthropic.models import Message, MessagesRequest
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
@@ -147,8 +148,8 @@ async def test_lists_stream_tool_capable_models_only(
]
),
) as mock_get:
- assert await github_models_provider.list_model_ids() == frozenset(
- {"openai/gpt-4.1"}
+ assert await github_models_provider.list_model_infos() == frozenset(
+ {ProviderModelInfo("openai/gpt-4.1")}
)
mock_get.assert_awaited_once_with(
@@ -174,7 +175,7 @@ async def test_model_list_rejects_malformed_payload(
),
pytest.raises(ModelListResponseError, match="top-level array"),
):
- await github_models_provider.list_model_ids()
+ await github_models_provider.list_model_infos()
@pytest.mark.asyncio
@@ -192,7 +193,7 @@ async def test_model_list_returns_empty_set_when_no_models_support_streaming_too
]
),
):
- assert await github_models_provider.list_model_ids() == frozenset()
+ assert await github_models_provider.list_model_infos() == frozenset()
@pytest.mark.asyncio
diff --git a/tests/providers/test_kimi.py b/tests/providers/test_kimi.py
index 687a1a67..9e1b44d4 100644
--- a/tests/providers/test_kimi.py
+++ b/tests/providers/test_kimi.py
@@ -6,6 +6,7 @@ from unittest.mock import AsyncMock, MagicMock
import pytest
from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.config.provider_catalog import KIMI_DEFAULT_BASE
from free_claude_code.core.anthropic.models import Message, MessagesRequest
@@ -97,7 +98,9 @@ async def test_model_list_uses_openai_client_models_endpoint(kimi_provider):
return_value=SimpleNamespace(data=[SimpleNamespace(id="kimi-k2.5")])
)
- assert await kimi_provider.list_model_ids() == frozenset({"kimi-k2.5"})
+ assert await kimi_provider.list_model_infos() == frozenset(
+ {ProviderModelInfo("kimi-k2.5")}
+ )
kimi_provider._client.models.list.assert_awaited_once_with()
diff --git a/tests/providers/test_kimi_code.py b/tests/providers/test_kimi_code.py
index 9a1dd9ed..e84dda1b 100644
--- a/tests/providers/test_kimi_code.py
+++ b/tests/providers/test_kimi_code.py
@@ -6,6 +6,7 @@ from unittest.mock import AsyncMock
import pytest
from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.provider_catalog import KIMI_CODE_DEFAULT_BASE
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.providers.base import ProviderConfig
@@ -161,7 +162,11 @@ async def test_model_list_uses_subscription_models_endpoint(kimi_code_provider):
)
)
- assert await kimi_code_provider.list_model_ids() == frozenset(
- {"k3", "kimi-for-coding", "kimi-for-coding-highspeed"}
+ assert await kimi_code_provider.list_model_infos() == frozenset(
+ {
+ ProviderModelInfo("k3"),
+ ProviderModelInfo("kimi-for-coding"),
+ ProviderModelInfo("kimi-for-coding-highspeed"),
+ }
)
kimi_code_provider._client.models.list.assert_awaited_once_with()
diff --git a/tests/providers/test_minimax.py b/tests/providers/test_minimax.py
index 119bf464..9516f983 100644
--- a/tests/providers/test_minimax.py
+++ b/tests/providers/test_minimax.py
@@ -5,6 +5,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
+from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.config.provider_catalog import MINIMAX_DEFAULT_BASE
from free_claude_code.core.anthropic.models import Message, MessagesRequest, Tool
@@ -131,8 +132,8 @@ async def test_lists_models_from_openai_models_endpoint(minimax_provider):
)
)
- assert await minimax_provider.list_model_ids() == frozenset(
- {"MiniMax-M3", "MiniMax-M2.7"}
+ assert await minimax_provider.list_model_infos() == frozenset(
+ {ProviderModelInfo("MiniMax-M3"), ProviderModelInfo("MiniMax-M2.7")}
)
diff --git a/tests/providers/test_model_discovery.py b/tests/providers/test_model_discovery.py
index f71ffbb4..21268515 100644
--- a/tests/providers/test_model_discovery.py
+++ b/tests/providers/test_model_discovery.py
@@ -71,8 +71,17 @@ def _manager(
)
+def _infos(*model_ids: str) -> frozenset[ProviderModelInfo]:
+ return frozenset(ProviderModelInfo(model_id) for model_id in model_ids)
+
+
+def test_provider_catalog_contract_is_metadata_only() -> None:
+ assert not hasattr(BaseProvider, "list_model_ids")
+ assert getattr(BaseProvider.list_model_infos, "__isabstractmethod__", False)
+
+
@pytest.mark.asyncio
-async def test_nim_lists_openai_compatible_model_ids() -> None:
+async def test_nim_lists_openai_compatible_model_infos() -> None:
config = ProviderConfig(api_key="test-key", base_url=NVIDIA_NIM_DEFAULT_BASE)
with patch("free_claude_code.providers.openai_chat.provider.AsyncOpenAI"):
provider = NvidiaNimProvider(
@@ -85,7 +94,7 @@ async def test_nim_lists_openai_compatible_model_ids() -> None:
new_callable=AsyncMock,
return_value=SimpleNamespace(data=[SimpleNamespace(id="nvidia/model")]),
):
- assert await provider.list_model_ids() == frozenset({"nvidia/model"})
+ assert await provider.list_model_infos() == _infos("nvidia/model")
@pytest.mark.asyncio
@@ -104,7 +113,7 @@ async def test_nim_lists_openai_compatible_model_ids() -> None:
),
],
)
-async def test_local_openai_chat_providers_list_model_ids(
+async def test_local_openai_chat_providers_list_model_infos(
provider: OpenAIChatProvider,
) -> None:
with patch.object(
@@ -113,7 +122,7 @@ async def test_local_openai_chat_providers_list_model_ids(
new_callable=AsyncMock,
return_value=SimpleNamespace(data=[SimpleNamespace(id="local/model")]),
) as mock_list:
- assert await provider.list_model_ids() == frozenset({"local/model"})
+ assert await provider.list_model_infos() == _infos("local/model")
mock_list.assert_awaited_once_with()
@@ -130,7 +139,7 @@ async def test_deepseek_lists_models_from_root_endpoint() -> None:
new_callable=AsyncMock,
return_value=SimpleNamespace(data=[SimpleNamespace(id="deepseek-chat")]),
) as mock_list:
- assert await provider.list_model_ids() == frozenset({"deepseek-chat"})
+ assert await provider.list_model_infos() == _infos("deepseek-chat")
mock_list.assert_awaited_once_with()
@@ -148,7 +157,7 @@ async def test_wafer_lists_models_from_default_models_endpoint() -> None:
new_callable=AsyncMock,
return_value=SimpleNamespace(data=[SimpleNamespace(id="DeepSeek-V4-Pro")]),
) as mock_list:
- assert await provider.list_model_ids() == frozenset({"DeepSeek-V4-Pro"})
+ assert await provider.list_model_infos() == _infos("DeepSeek-V4-Pro")
mock_list.assert_awaited_once_with()
@@ -181,8 +190,11 @@ async def test_openrouter_lists_only_tool_capable_models() -> None:
]
),
) as mock_list:
- assert await provider.list_model_ids() == frozenset(
- {"tool-model", "tool-choice-model"}
+ assert await provider.list_model_infos() == frozenset(
+ {
+ ProviderModelInfo("tool-model", supports_thinking=False),
+ ProviderModelInfo("tool-choice-model", supports_thinking=False),
+ }
)
mock_list.assert_awaited_once_with()
@@ -246,7 +258,7 @@ async def test_openrouter_lists_empty_set_when_no_tool_capable_models() -> None:
]
),
):
- assert await provider.list_model_ids() == frozenset()
+ assert await provider.list_model_infos() == frozenset()
@pytest.mark.asyncio
@@ -285,7 +297,7 @@ async def test_model_listing_rejects_malformed_payload() -> None:
),
pytest.raises(ModelListResponseError, match="malformed"),
):
- await provider.list_model_ids()
+ await provider.list_model_infos()
@pytest.mark.asyncio
@@ -304,15 +316,14 @@ async def test_model_listing_propagates_upstream_errors() -> None:
),
pytest.raises(RuntimeError, match="upstream unavailable"),
):
- await provider.list_model_ids()
+ await provider.list_model_infos()
class FakeProvider(BaseProvider):
def __init__(
self,
- model_ids: frozenset[str] | None = None,
+ model_infos: frozenset[ProviderModelInfo] = frozenset(),
*,
- model_infos: frozenset[ProviderModelInfo] | None = None,
error: BaseException | None = None,
started: asyncio.Event | None = None,
peer_started: asyncio.Event | None = None,
@@ -320,7 +331,6 @@ class FakeProvider(BaseProvider):
super().__init__(
ProviderConfig(api_key="test", base_url="https://test.invalid")
)
- self._model_ids = model_ids or frozenset()
self._model_infos = model_infos
self._error = error
self._started = started
@@ -348,17 +358,9 @@ class FakeProvider(BaseProvider):
if self._error is not None:
raise self._error
- async def list_model_ids(self) -> frozenset[str]:
- await self._before_model_list()
- if self._model_infos is not None:
- return frozenset(info.model_id for info in self._model_infos)
- return self._model_ids
-
async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
await self._before_model_list()
- if self._model_infos is not None:
- return self._model_infos
- return frozenset(ProviderModelInfo(model_id) for model_id in self._model_ids)
+ return self._model_infos
async def stream_response(
self,
@@ -379,8 +381,8 @@ async def test_runtime_warm_caches_all_referenced_provider_models() -> None:
nvidia_nim_api_key="nim-key",
open_router_api_key="open-router-key",
)
- nim = FakeProvider(frozenset({"nim-model"}))
- router = FakeProvider(frozenset({"anthropic/claude-opus"}))
+ nim = FakeProvider(_infos("nim-model"))
+ router = FakeProvider(_infos("anthropic/claude-opus"))
runtime = _manager(
settings,
{
@@ -409,7 +411,7 @@ async def test_runtime_warm_treats_model_lists_as_discovery_metadata() -> None:
)
runtime = _manager(
settings,
- {"nvidia_nim": FakeProvider(frozenset({"different-model"}))},
+ {"nvidia_nim": FakeProvider(_infos("different-model"))},
)
result = await runtime.warm_referenced_model_cache()
@@ -429,7 +431,7 @@ async def test_runtime_warm_reports_query_failures_without_blocking() -> None:
runtime = _manager(
settings,
{
- "nvidia_nim": FakeProvider(frozenset({"nim-model"})),
+ "nvidia_nim": FakeProvider(_infos("nim-model")),
"open_router": FakeProvider(
error=ModelListResponseError("bad model-list shape")
),
@@ -458,12 +460,12 @@ async def test_runtime_warm_queries_referenced_providers_concurrently() -> None:
settings,
{
"nvidia_nim": FakeProvider(
- frozenset({"nim-model"}),
+ _infos("nim-model"),
started=nim_started,
peer_started=router_started,
),
"open_router": FakeProvider(
- frozenset({"anthropic/claude-opus"}),
+ _infos("anthropic/claude-opus"),
started=router_started,
peer_started=nim_started,
),
@@ -479,8 +481,8 @@ async def test_startup_discovery_queries_each_successful_provider_once() -> None
nvidia_nim_api_key="nim-key",
open_router_api_key="open-router-key",
)
- nim = FakeProvider(frozenset({"nim-model"}))
- router = FakeProvider(frozenset({"anthropic/claude-sonnet"}))
+ nim = FakeProvider(_infos("nim-model"))
+ router = FakeProvider(_infos("anthropic/claude-sonnet"))
runtime = _manager(
settings,
{"nvidia_nim": nim, "open_router": router},
@@ -528,9 +530,9 @@ async def test_runtime_refresh_model_list_cache_uses_configured_remote_keys_and_
runtime = _manager(
settings,
{
- "open_router": FakeProvider(frozenset({"anthropic/claude-sonnet"})),
- "lmstudio": FakeProvider(frozenset({"local-qwen"})),
- "ollama": FakeProvider(frozenset({"llama3.1"})),
+ "open_router": FakeProvider(_infos("anthropic/claude-sonnet")),
+ "lmstudio": FakeProvider(_infos("local-qwen")),
+ "ollama": FakeProvider(_infos("llama3.1")),
},
)
@@ -554,7 +556,7 @@ async def test_runtime_refresh_model_list_cache_treats_vertex_project_as_configu
)
runtime = _manager(
settings,
- {"vertex": FakeProvider(frozenset({"google/gemini-3.5-flash"}))},
+ {"vertex": FakeProvider(_infos("google/gemini-3.5-flash"))},
)
result = await runtime.refresh_model_list_cache()
@@ -613,12 +615,12 @@ def test_runtime_metadata_cache_exposes_ids_and_prefixed_infos() -> None:
def test_runtime_metadata_cache_enforces_replaced_provider_scope() -> None:
cache = ProviderModelCache({"open_router", "lmstudio"})
- cache.cache_model_ids("open_router", {"old-model"})
- cache.cache_model_ids("lmstudio", {"local-model"})
+ cache.cache_model_infos("open_router", _infos("old-model"))
+ cache.cache_model_infos("lmstudio", _infos("local-model"))
cache.set_available_providers({"deepseek", "lmstudio"})
- cache.cache_model_ids("open_router", {"late-old-model"})
- cache.cache_model_ids("deepseek", {"new-model"})
+ cache.cache_model_infos("open_router", _infos("late-old-model"))
+ cache.cache_model_infos("deepseek", _infos("new-model"))
assert cache.cached_model_ids() == {
"deepseek": frozenset({"new-model"}),
@@ -626,9 +628,9 @@ def test_runtime_metadata_cache_enforces_replaced_provider_scope() -> None:
}
-def test_runtime_model_id_cache_keeps_unknown_thinking_support() -> None:
+def test_runtime_metadata_cache_keeps_unknown_thinking_support() -> None:
cache = ProviderModelCache()
- cache.cache_model_ids("open_router", {"plain-model"})
+ cache.cache_model_infos("open_router", _infos("plain-model"))
assert cache.cached_model_ids() == {"open_router": frozenset({"plain-model"})}
assert cache.cached_model_supports_thinking("open_router", "plain-model") is None
@@ -637,13 +639,13 @@ def test_runtime_model_id_cache_keeps_unknown_thinking_support() -> None:
)
-def test_runtime_cached_prefixed_model_refs_are_deterministic() -> None:
+def test_runtime_cached_prefixed_model_infos_are_deterministic() -> None:
cache = ProviderModelCache()
- cache.cache_model_ids("deepseek", {"deepseek-chat"})
- cache.cache_model_ids("open_router", {"z-model", "a-model"})
+ cache.cache_model_infos("deepseek", _infos("deepseek-chat"))
+ cache.cache_model_infos("open_router", _infos("z-model", "a-model"))
- assert cache.cached_prefixed_model_refs() == (
- "open_router/a-model",
- "open_router/z-model",
- "deepseek/deepseek-chat",
+ assert cache.cached_prefixed_model_infos() == (
+ ProviderModelInfo("open_router/a-model"),
+ ProviderModelInfo("open_router/z-model"),
+ ProviderModelInfo("deepseek/deepseek-chat"),
)
diff --git a/tests/providers/test_preflight_contract.py b/tests/providers/test_preflight_contract.py
index 9890334d..cb97d08b 100644
--- a/tests/providers/test_preflight_contract.py
+++ b/tests/providers/test_preflight_contract.py
@@ -4,6 +4,7 @@ from collections.abc import AsyncIterator
import pytest
+from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.core.anthropic.models import Message, MessagesRequest
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
from free_claude_code.providers.base import BaseProvider, ProviderConfig
@@ -28,7 +29,7 @@ class ProviderWithoutPreflight(BaseProvider):
async def cleanup(self) -> None:
return None
- async def list_model_ids(self) -> frozenset[str]:
+ async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
return frozenset()
async def stream_response(
diff --git a/tests/providers/test_vertex.py b/tests/providers/test_vertex.py
index c0971404..301233c6 100644
--- a/tests/providers/test_vertex.py
+++ b/tests/providers/test_vertex.py
@@ -13,6 +13,7 @@ from free_claude_code.application.errors import (
ApplicationUnavailableError,
InvalidRequestError,
)
+from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.provider_catalog import VERTEX_AI_API_ROOT
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
@@ -413,9 +414,14 @@ async def test_vertex_model_discovery_follows_native_pagination() -> None:
new_callable=AsyncMock,
side_effect=responses,
) as get:
- model_ids = await provider.list_model_ids()
+ model_infos = await provider.list_model_infos()
- assert model_ids == frozenset({"google/gemini-3.5-flash", "google/gemini-3.1-pro"})
+ assert model_infos == frozenset(
+ {
+ ProviderModelInfo("google/gemini-3.5-flash"),
+ ProviderModelInfo("google/gemini-3.1-pro"),
+ }
+ )
assert get.await_args_list[0].kwargs == {
"params": None,
"headers": {
@@ -462,7 +468,7 @@ async def test_vertex_model_discovery_rejects_unusable_success_response(
),
pytest.raises(ModelListResponseError, match="VERTEX model-list response"),
):
- await provider.list_model_ids()
+ await provider.list_model_infos()
assert response.is_closed
@@ -491,4 +497,4 @@ async def test_vertex_model_discovery_rejects_repeated_page_token() -> None:
),
pytest.raises(ModelListResponseError, match="repeated nextPageToken"),
):
- await provider.list_model_ids()
+ await provider.list_model_infos()
diff --git a/tests/providers/test_wafer.py b/tests/providers/test_wafer.py
index 9d45e82a..616fd076 100644
--- a/tests/providers/test_wafer.py
+++ b/tests/providers/test_wafer.py
@@ -4,6 +4,7 @@ from unittest.mock import AsyncMock, MagicMock
import pytest
+from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.config.provider_catalog import WAFER_DEFAULT_BASE
from free_claude_code.core.anthropic.models import Message, MessagesRequest, Tool
@@ -124,8 +125,8 @@ async def test_lists_models_from_openai_models_endpoint(wafer_provider):
)
)
- assert await wafer_provider.list_model_ids() == frozenset(
- {"DeepSeek-V4-Pro", "MiniMax-M2.7"}
+ assert await wafer_provider.list_model_infos() == frozenset(
+ {ProviderModelInfo("DeepSeek-V4-Pro"), ProviderModelInfo("MiniMax-M2.7")}
)
wafer_provider._client.models.list.assert_awaited_once_with()
diff --git a/uv.lock b/uv.lock
index 55613d25..f79541f5 100644
--- a/uv.lock
+++ b/uv.lock
@@ -620,7 +620,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.11.6"
+version = "4.11.7"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },