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
6.4 KB
Raw Blame
"""Provider-prefixed model reference helpers."""

import json
from collections.abc import Mapping
from dataclasses import dataclass
from typing import Annotated, Protocol

from pydantic import (
    BaseModel,
    BeforeValidator,
    ConfigDict,
    Field,
    StringConstraints,
    TypeAdapter,
    field_validator,
)

from .constants import DEFAULT_MODEL
from .reasoning import ReasoningPreference

RETIRED_PROVIDER_IDS = frozenset({"github_models"})


def replace_retired_model_ref(model_ref: str) -> str:
    """Replace the exact retired hosted endpoint, retaining independent providers."""
    if model_ref.strip() == "nvidia_nim/nvidia/nemotron-3-super-120b-a12b":
        return "nvidia_nim/nvidia/nemotron-3-ultra-550b-a55b"
    return model_ref


class ModelFallback(BaseModel):
    """One ordered fallback's model, reasoning preference, and key number."""

    model_config = ConfigDict(frozen=True, extra="forbid", hide_input_in_errors=True)

    model: Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
    reasoning: ReasoningPreference = ReasoningPreference.INHERIT
    api_key_number: int = Field(default=1, strict=True, ge=1)

    @field_validator("model")
    @classmethod
    def validate_model(cls, value: str) -> str:
        split_provider_model_ref(value)
        return value


def is_retired_model_ref(model_ref: str) -> bool:
    """Recognize complete references owned by a retired provider."""

    provider, separator, model = model_ref.strip().partition("/")
    return provider in RETIRED_PROVIDER_IDS and bool(separator and model.strip())


def parse_model_fallbacks(value: object) -> object:
    if value is None:
        return None
    if isinstance(value, str):
        if not value.strip():
            return None
        if value.lstrip().startswith("["):
            try:
                value = json.loads(value)
            except ValueError:
                raise ValueError(
                    "MODEL_FALLBACKS must contain a valid JSON array."
                ) from None
        else:
            value = value.split(",")
    if isinstance(value, list | tuple):
        return (
            tuple({"model": item} if isinstance(item, str) else item for item in value)
            or None
        )
    return value


type ModelFallbacks = Annotated[
    tuple[ModelFallback, ...] | None, BeforeValidator(parse_model_fallbacks)
]
_FALLBACKS = TypeAdapter(ModelFallbacks)


def decode_model_fallbacks(value: object) -> tuple[ModelFallback, ...] | None:
    return _FALLBACKS.validate_python(value)


def encode_model_fallbacks(value: tuple[ModelFallback, ...]) -> str:
    return json.dumps(
        [entry.model_dump(mode="json") for entry in value],
        ensure_ascii=False,
        separators=(",", ":"),
    )


def normalize_retired_model_settings(
    values: Mapping[str, str], *, preserve_empty_overrides: bool
) -> dict[str, str]:
    """Repair one source without changing its precedence or unrelated validation."""

    normalized = dict(values)
    for key in ("MODEL", "MODEL_FABLE", "MODEL_OPUS", "MODEL_SONNET", "MODEL_HAIKU"):
        if is_retired_model_ref(normalized.get(key, "")):
            if preserve_empty_overrides:
                normalized[key] = DEFAULT_MODEL if key == "MODEL" else ""
            else:
                normalized.pop(key)
        elif key in normalized:
            normalized[key] = replace_retired_model_ref(normalized[key])
    try:
        fallbacks = decode_model_fallbacks(normalized.get("MODEL_FALLBACKS"))
    except ValueError:
        return normalized  # Settings reports the original validation error.
    if fallbacks:
        retained = tuple(
            entry for entry in fallbacks if not is_retired_model_ref(entry.model)
        )
        original_pairs = [(entry.model, entry.api_key_number) for entry in retained]
        if len(original_pairs) != len(set(original_pairs)):
            return normalized  # Settings must still reject pre-existing duplicates.
        migrated: list[ModelFallback] = []
        seen: set[tuple[str, int]] = set()
        for entry in retained:
            model = replace_retired_model_ref(entry.model)
            pair = (model, entry.api_key_number)
            if pair not in seen:
                seen.add(pair)
                migrated.append(entry.model_copy(update={"model": model}))
        retained = tuple(migrated)
        if retained:
            normalized["MODEL_FALLBACKS"] = encode_model_fallbacks(retained)
        elif preserve_empty_overrides:
            normalized["MODEL_FALLBACKS"] = ""
        else:
            normalized.pop("MODEL_FALLBACKS", None)
    return normalized


@dataclass(frozen=True, slots=True)
class ConfiguredChatModelRef:
    """A unique configured chat model reference."""

    model_ref: str
    provider_id: str
    model_id: str


class ChatModelConfig(Protocol):
    model: str
    model_fable: str | None
    model_opus: str | None
    model_sonnet: str | None
    model_haiku: str | None
    model_fallbacks: tuple[ModelFallback, ...] | None


def split_provider_model_ref(model_ref: str) -> tuple[str, str]:
    """Split one complete ``provider/model`` reference."""

    provider_id, separator, model_id = model_ref.partition("/")
    if not separator or not provider_id or not model_id:
        raise ValueError("Model reference must contain provider and model names.")
    return provider_id, model_id


def parse_provider_type(model_ref: str) -> str:
    """Extract provider type from any 'provider/model' string."""

    return split_provider_model_ref(model_ref)[0]


def parse_model_name(model_ref: str) -> str:
    """Extract model name from any 'provider/model' string."""

    return split_provider_model_ref(model_ref)[1]


def configured_chat_model_refs(
    settings: ChatModelConfig,
) -> tuple[ConfiguredChatModelRef, ...]:
    """Return unique configured chat provider/model refs."""

    model_refs = dict.fromkeys(
        model_ref
        for model_ref in (
            settings.model,
            settings.model_fable,
            settings.model_opus,
            settings.model_sonnet,
            settings.model_haiku,
            *(entry.model for entry in settings.model_fallbacks or ()),
        )
        if model_ref is not None
    )

    return tuple(
        ConfiguredChatModelRef(
            model_ref=model_ref,
            provider_id=parse_provider_type(model_ref),
            model_id=parse_model_name(model_ref),
        )
        for model_ref in model_refs
    )