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
18.4 KB
Raw Blame
from unittest.mock import patch

import pytest

from free_claude_code.application.errors import UnknownProviderError
from free_claude_code.application.routing import ModelRouter
from free_claude_code.config.model_refs import ModelFallback
from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.config.reasoning import ReasoningPreference
from free_claude_code.config.settings import Settings
from free_claude_code.core.anthropic.models import (
    Message,
    MessagesRequest,
    TokenCountRequest,
)
from free_claude_code.core.gateway_model_ids import desktop_model_id
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import ReasoningControl, ReasoningEffort


@pytest.mark.parametrize(
    "encoding,off",
    [
        ("", False),
        ("anthropic/", False),
        ("claude-3-freecc-no-thinking/", True),
        ("desktop", False),
        ("desktop", True),
    ],
)
def test_retired_super_direct_ids_route_to_ultra_not_configured_default(encoding, off):
    old = "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
    new = "nvidia_nim/nvidia/nemotron-3-ultra-550b-a55b"
    original = (
        desktop_model_id(old, no_thinking=off)
        if encoding == "desktop"
        else encoding + old
    )
    settings = Settings(
        MODEL="groq/default",
        REASONING_POLICY="high",
        MODEL_FALLBACKS=(
            ModelFallback(model=new),
            ModelFallback(model="groq/backup"),
        ),
    )
    router = ModelRouter(settings)
    route = router.resolve(original)
    assert route.original_model == original
    assert route.primary.provider_model_ref == new
    assert route.primary.api_key_number == 1
    assert [entry.target.provider_model_ref for entry in route.fallbacks] == [
        "groq/backup"
    ]
    assert route.reasoning_preference is (
        ReasoningPreference.OFF if off else ReasoningPreference.HIGH
    )
    messages = MessagesRequest(
        model=original, max_tokens=100, messages=[Message(role="user", content="hi")]
    )
    responses = OpenAIResponsesRequest(model=original, input="hi")
    count = TokenCountRequest(
        model=original, messages=[Message(role="user", content="hi")]
    )
    for routed in (
        router.resolve_messages_request(messages),
        router.resolve_responses_request(responses),
        router.resolve_token_count_request(count),
    ):
        assert routed.request.model == "nvidia/nemotron-3-ultra-550b-a55b"
        assert routed.resolved == route
    assert messages.model == responses.model == count.model == original


@pytest.mark.parametrize(
    "ref",
    [
        "open_router/nvidia/nemotron-3-super-120b-a12b",
        "nvidia_nim/nvidia/nemotron-3-super-120b-a12b-successor",
    ],
)
def test_super_replacement_does_not_redirect_other_endpoints(ref):
    route = ModelRouter(Settings()).resolve("anthropic/" + ref)
    assert route.primary.provider_model_ref == ref


@pytest.mark.parametrize(
    "prefix,off",
    [("", False), ("anthropic/", False), ("claude-3-freecc-no-thinking/", True)],
)
@pytest.mark.parametrize(
    "suffix", ["openai/gpt-4.1", "vendor/opus", "sonnet", "haiku", "fable"]
)
def test_retired_direct_ids_route_to_default_before_family_aliases(prefix, off, suffix):
    settings = Settings(
        MODEL="groq/default",
        MODEL_OPUS="deepseek/opus",
        MODEL_SONNET="deepseek/sonnet",
        MODEL_HAIKU="deepseek/haiku",
        MODEL_FABLE="deepseek/fable",
        MODEL_FALLBACKS=(
            ModelFallback(model="groq/default"),
            ModelFallback(model="groq/backup"),
        ),
        REASONING_POLICY="high",
        REASONING_OPUS="off",
    )
    original = f"{prefix}github_models/{suffix}"
    router = ModelRouter(settings)
    route = router.resolve(original)
    assert route.original_model == original
    assert route.primary.provider_model_ref == "groq/default"
    assert [candidate.target.provider_model_ref for candidate in route.fallbacks] == [
        "groq/backup"
    ]
    assert route.reasoning_preference is (
        ReasoningPreference.OFF if off else ReasoningPreference.HIGH
    )
    messages = router.resolve_messages_request(
        MessagesRequest(
            model=original,
            max_tokens=100,
            messages=[Message(role="user", content="hi")],
        )
    )
    responses = router.resolve_responses_request(
        OpenAIResponsesRequest(model=original, input="hi")
    )
    count = router.resolve_token_count_request(
        TokenCountRequest(model=original, messages=[Message(role="user", content="hi")])
    )
    for routed in (messages, responses, count):
        assert routed.request.model == "default"
        assert routed.resolved == route


@pytest.fixture
def settings():
    settings = Settings()
    settings.model = "nvidia_nim/fallback-model"
    settings.model_fable = None
    settings.model_opus = None
    settings.model_sonnet = None
    settings.model_haiku = None
    settings.reasoning_policy = ReasoningPreference.CLIENT
    settings.reasoning_fable = ReasoningPreference.INHERIT
    settings.reasoning_opus = ReasoningPreference.INHERIT
    settings.reasoning_sonnet = ReasoningPreference.INHERIT
    settings.reasoning_haiku = ReasoningPreference.INHERIT
    return settings


def test_model_router_resolves_default_model(settings):
    resolved = ModelRouter(settings).resolve("claude-3-opus")

    assert resolved.original_model == "claude-3-opus"
    assert resolved.primary.provider_id == "nvidia_nim"
    assert resolved.primary.provider_model == "fallback-model"
    assert resolved.primary.provider_model_ref == "nvidia_nim/fallback-model"
    assert resolved.fallbacks == ()
    assert resolved.reasoning_preference is ReasoningPreference.CLIENT


def test_model_router_applies_opus_override(settings):
    settings.model_opus = "open_router/deepseek/deepseek-r1"

    request = MessagesRequest(
        model="claude-opus-4-20250514",
        max_tokens=100,
        messages=[Message(role="user", content="hello")],
    )
    routed = ModelRouter(settings).resolve_messages_request(request)

    assert routed.request.model == "deepseek/deepseek-r1"
    assert (
        routed.resolved.primary.provider_model_ref == "open_router/deepseek/deepseek-r1"
    )
    assert routed.resolved.original_model == "claude-opus-4-20250514"
    assert routed.reasoning.control is ReasoningControl.DEFAULT
    assert request.model == "claude-opus-4-20250514"


def test_model_router_applies_fable_override(settings):
    settings.model_fable = "open_router/anthropic/claude-fable-5"

    routed = ModelRouter(settings).resolve_messages_request(
        MessagesRequest(
            model="claude-fable-5",
            max_tokens=100,
            messages=[Message(role="user", content="hello")],
        )
    )

    assert routed.request.model == "anthropic/claude-fable-5"
    assert (
        routed.resolved.primary.provider_model_ref
        == "open_router/anthropic/claude-fable-5"
    )
    assert routed.resolved.original_model == "claude-fable-5"


def test_model_router_resolves_route_reasoning_preferences(settings):
    settings.reasoning_policy = ReasoningPreference.OFF
    settings.reasoning_fable = ReasoningPreference.HIGH
    settings.reasoning_opus = ReasoningPreference.MAX
    settings.reasoning_haiku = ReasoningPreference.OFF

    router = ModelRouter(settings)

    assert (
        router.resolve("claude-fable-5").reasoning_preference
        is ReasoningPreference.HIGH
    )
    assert (
        router.resolve("claude-opus-4-20250514").reasoning_preference
        is ReasoningPreference.MAX
    )
    assert (
        router.resolve("claude-sonnet-4-20250514").reasoning_preference
        is ReasoningPreference.OFF
    )
    assert (
        router.resolve("claude-3-haiku-20240307").reasoning_preference
        is ReasoningPreference.OFF
    )
    assert router.resolve("claude-2.1").reasoning_preference is ReasoningPreference.OFF


def test_model_router_applies_haiku_override(settings):
    settings.model_haiku = "lmstudio/qwen2.5-7b"

    routed = ModelRouter(settings).resolve_messages_request(
        MessagesRequest(
            model="claude-3-haiku-20240307",
            max_tokens=100,
            messages=[Message(role="user", content="hello")],
        )
    )

    assert routed.request.model == "qwen2.5-7b"
    assert routed.resolved.primary.provider_model_ref == "lmstudio/qwen2.5-7b"


def test_model_router_applies_sonnet_override(settings):
    settings.model_sonnet = "nvidia_nim/meta/llama-3.3-70b-instruct"

    routed = ModelRouter(settings).resolve_messages_request(
        MessagesRequest(
            model="claude-sonnet-4-20250514",
            max_tokens=100,
            messages=[Message(role="user", content="hello")],
        )
    )

    assert routed.request.model == "meta/llama-3.3-70b-instruct"
    assert (
        routed.resolved.primary.provider_model_ref
        == "nvidia_nim/meta/llama-3.3-70b-instruct"
    )


def test_model_router_routes_prefixed_provider_model_directly(settings):
    routed = ModelRouter(settings).resolve_messages_request(
        MessagesRequest(
            model="deepseek/deepseek-chat",
            max_tokens=100,
            messages=[Message(role="user", content="hello")],
        )
    )

    assert routed.request.model == "deepseek-chat"
    assert routed.resolved.original_model == "deepseek/deepseek-chat"
    assert routed.resolved.primary.provider_id == "deepseek"
    assert routed.resolved.primary.provider_model == "deepseek-chat"
    assert routed.resolved.primary.provider_model_ref == "deepseek/deepseek-chat"


def test_model_router_routes_explicit_opencode_zen_prefix(settings):
    routed = ModelRouter(settings).resolve_messages_request(
        MessagesRequest(
            model="opencode_zen/kimi-k2.6",
            max_tokens=100,
            messages=[Message(role="user", content="hello")],
        )
    )

    assert routed.request.model == "kimi-k2.6"
    assert routed.resolved.primary.provider_id == "opencode_zen"
    assert routed.resolved.primary.provider_model_ref == "opencode_zen/kimi-k2.6"


def test_model_router_routes_wafer_provider_model_directly(settings):
    routed = ModelRouter(settings).resolve_messages_request(
        MessagesRequest(
            model="wafer/DeepSeek-V4-Pro",
            max_tokens=100,
            messages=[Message(role="user", content="hello")],
        )
    )

    assert routed.request.model == "DeepSeek-V4-Pro"
    assert routed.resolved.primary.provider_id == "wafer"
    assert routed.resolved.primary.provider_model == "DeepSeek-V4-Pro"
    assert routed.resolved.primary.provider_model_ref == "wafer/DeepSeek-V4-Pro"


def test_model_router_routes_minimax_provider_model_directly(settings):
    routed = ModelRouter(settings).resolve_messages_request(
        MessagesRequest(
            model="minimax/MiniMax-M3",
            max_tokens=100,
            messages=[Message(role="user", content="hello")],
        )
    )

    assert routed.request.model == "MiniMax-M3"
    assert routed.resolved.primary.provider_id == "minimax"
    assert routed.resolved.primary.provider_model == "MiniMax-M3"
    assert routed.resolved.primary.provider_model_ref == "minimax/MiniMax-M3"


def test_model_router_routes_gateway_encoded_provider_model_directly(settings):
    routed = ModelRouter(settings).resolve_messages_request(
        MessagesRequest(
            model="anthropic/nvidia_nim/deepseek-ai/deepseek-v4-pro",
            max_tokens=100,
            messages=[Message(role="user", content="hello")],
        )
    )

    assert routed.request.model == "deepseek-ai/deepseek-v4-pro"
    assert (
        routed.resolved.original_model
        == "anthropic/nvidia_nim/deepseek-ai/deepseek-v4-pro"
    )
    assert routed.resolved.primary.provider_id == "nvidia_nim"
    assert routed.resolved.primary.provider_model == "deepseek-ai/deepseek-v4-pro"
    assert (
        routed.resolved.primary.provider_model_ref
        == "nvidia_nim/deepseek-ai/deepseek-v4-pro"
    )


def test_model_router_routes_no_thinking_gateway_model_directly(settings):
    routed = ModelRouter(settings).resolve_messages_request(
        MessagesRequest(
            model="claude-3-freecc-no-thinking/nvidia_nim/deepseek-ai/deepseek-v4-pro",
            max_tokens=100,
            messages=[Message(role="user", content="hello")],
        )
    )

    assert routed.request.model == "deepseek-ai/deepseek-v4-pro"
    assert (
        routed.resolved.original_model
        == "claude-3-freecc-no-thinking/nvidia_nim/deepseek-ai/deepseek-v4-pro"
    )
    assert routed.resolved.primary.provider_id == "nvidia_nim"
    assert routed.resolved.primary.provider_model == "deepseek-ai/deepseek-v4-pro"
    assert routed.reasoning.control is ReasoningControl.OFF


def test_direct_provider_model_uses_root_policy_without_model_name_guessing(settings):
    settings.reasoning_policy = ReasoningPreference.LOW
    settings.reasoning_opus = ReasoningPreference.MAX

    routed = ModelRouter(settings).resolve_messages_request(
        MessagesRequest(
            model="open_router/anthropic/claude-opus-4",
            messages=[Message(role="user", content="hello")],
        )
    )

    assert routed.resolved.primary.provider_id == "open_router"
    assert routed.resolved.primary.provider_model == "anthropic/claude-opus-4"
    assert routed.reasoning.effort is ReasoningEffort.LOW


def test_model_router_routes_token_count_request(settings):
    settings.model_haiku = "lmstudio/qwen2.5-7b"

    request = TokenCountRequest(
        model="claude-3-haiku-20240307",
        messages=[Message(role="user", content="hello")],
    )
    routed = ModelRouter(settings).resolve_token_count_request(request)

    assert routed.request.model == "qwen2.5-7b"
    assert request.model == "claude-3-haiku-20240307"


def test_model_router_routes_responses_request_without_protocol_conversion(settings):
    settings.model_fallbacks = (ModelFallback(model="open_router/vendor/fallback"),)
    request = OpenAIResponsesRequest(
        model="opencode_zen/responses-model",
        input=[{"role": "user", "content": "hello"}],
        reasoning={"effort": "high"},
        previous_response_id="resp_previous",
    )

    routed = ModelRouter(settings).resolve_responses_request(request)

    assert routed.request.model == "responses-model"
    assert routed.request.input == request.input
    assert routed.request.previous_response_id == "resp_previous"
    assert routed.resolved.original_model == "opencode_zen/responses-model"
    assert routed.resolved.primary.provider_id == "opencode_zen"
    assert routed.resolved.primary.provider_model == "responses-model"
    assert [
        candidate.target.provider_model_ref for candidate in routed.resolved.fallbacks
    ] == ["open_router/vendor/fallback"]
    assert routed.reasoning.control is ReasoningControl.DEFAULT
    assert routed.reasoning.effort is ReasoningEffort.HIGH
    assert request.model == "opencode_zen/responses-model"


def test_model_router_appends_global_fallbacks_and_skips_only_primary(settings):
    settings.model_fallbacks = (
        ModelFallback(model="nvidia_nim/fallback-model"),
        ModelFallback(model="nvidia_nim/alternate-model"),
        ModelFallback(model="open_router/vendor/model-b"),
    )

    resolved = ModelRouter(settings).resolve("claude-2.1")

    assert [
        candidate.target.provider_model_ref for candidate in resolved.fallbacks
    ] == [
        "nvidia_nim/alternate-model",
        "open_router/vendor/model-b",
    ]


@pytest.mark.parametrize(
    "requested", ["claude-2.1", "nvidia_nim/primary", "claude-opus-4"]
)
def test_fallback_effort_does_not_change_primary_identity(requested):
    settings = Settings(
        MODEL="nvidia_nim/primary",
        MODEL_OPUS="nvidia_nim/primary",
        MODEL_FALLBACKS=[
            {"model": "nvidia_nim/primary", "reasoning": "off"},
            {"model": "groq/backup", "reasoning": "low"},
        ],
    )
    route = ModelRouter(settings).resolve(requested)
    assert [
        (candidate.target.provider_model_ref, candidate.reasoning_preference)
        for candidate in route.fallbacks
    ] == [("groq/backup", ReasoningPreference.LOW)]


@pytest.mark.parametrize("requested", ["claude-opus-4", "groq/primary"])
def test_same_model_fallbacks_keep_alternate_keys_and_their_efforts(requested):
    settings = Settings(
        MODEL="groq/primary",
        MODEL_OPUS="groq/primary",
        GROQ_API_KEY=["synthetic-first", "synthetic-second", "synthetic-third"],
        MODEL_FALLBACKS=[
            {"model": "groq/primary", "reasoning": "off", "api_key_number": 1},
            {"model": "groq/primary", "reasoning": "low", "api_key_number": 2},
            {"model": "groq/primary", "reasoning": "high", "api_key_number": 3},
        ],
    )
    route = ModelRouter(settings).resolve(requested)
    assert route.primary.api_key_number == 1
    assert [
        (
            candidate.target.provider_model_ref,
            candidate.target.api_key_number,
            candidate.reasoning_preference,
        )
        for candidate in route.fallbacks
    ] == [
        ("groq/primary", 2, ReasoningPreference.LOW),
        ("groq/primary", 3, ReasoningPreference.HIGH),
    ]


def test_direct_gateway_route_preserves_original_and_deduplicates_canonical_target(
    settings,
):
    settings.model_fallbacks = (
        ModelFallback(model="nvidia_nim/deepseek-ai/deepseek-v4-pro"),
        ModelFallback(model="groq/vendor/model-b"),
    )
    model = "anthropic/nvidia_nim/deepseek-ai/deepseek-v4-pro"

    resolved = ModelRouter(settings).resolve(model)

    assert resolved.original_model == model
    assert (
        resolved.primary.provider_model_ref == "nvidia_nim/deepseek-ai/deepseek-v4-pro"
    )
    assert [
        candidate.target.provider_model_ref for candidate in resolved.fallbacks
    ] == ["groq/vendor/model-b"]


def test_model_router_logs_mapping(settings):
    with patch("free_claude_code.application.routing.logger.debug") as mock_log:
        ModelRouter(settings).resolve("claude-2.1")

    mock_log.assert_called()
    args = mock_log.call_args[0]
    assert "MODEL MAPPING" in args[0]
    assert args[1] == "claude-2.1"
    assert args[2] == "fallback-model"


def test_model_router_preserves_typed_error_for_unknown_mapped_provider(settings):
    settings.model = "unknown/model"

    with pytest.raises(UnknownProviderError) as exc_info:
        ModelRouter(settings).resolve("claude-2.1")

    supported = "', '".join(PROVIDER_CATALOG)
    assert str(exc_info.value) == (
        f"Unknown provider_type: 'unknown'. Supported: '{supported}'"
    )