Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

8.5 KB
Raw Blame
"""Helpers for selecting configured LLM models without mutating settings."""

from __future__ import annotations

from copy import deepcopy
from dataclasses import dataclass
from typing import Any

from deeptutor.services.provider_registry import find_by_name

# What a conversation-level override (#641) is allowed to ask for. This is a
# request-validation vocabulary, deliberately the union of every level any
# provider understands — `services/llm/reasoning_params.py` is what maps a
# level onto a given provider's actual knob, and the per-backend `efforts`
# lists in `services/subagent/models.py` describe what each subagent CLI
# accepts. Neither of those is interchangeable with this one. Not every
# provider/model supports every value, so callers that can offer a narrower,
# model-specific list should filter before submitting a selection.
VALID_REASONING_EFFORTS: tuple[str, ...] = (
    "none",
    "minimal",
    "low",
    "medium",
    "high",
    "xhigh",
    "max",
)


@dataclass(frozen=True, slots=True)
class LLMSelection:
    """A safe reference to one configured LLM model.

    The selection intentionally carries IDs only. Provider secrets stay in the
    server-side catalog and are resolved only at runtime.

    ``reasoning_effort`` is an optional per-conversation override (#641):
    when set, it takes precedence over the profile/model's own
    ``reasoning_effort`` default for calls made with this selection. ``None``
    means "no override" — the existing profile/global/provider default
    resolution applies unchanged.
    """

    profile_id: str
    model_id: str
    reasoning_effort: str | None = None

    @classmethod
    def from_payload(cls, value: Any) -> "LLMSelection | None":
        if isinstance(value, LLMSelection):
            return value
        if value is None:
            return None
        if not isinstance(value, dict):
            raise ValueError("Invalid LLM selection: expected an object.")

        profile_id = str(value.get("profile_id") or "").strip()
        model_id = str(value.get("model_id") or "").strip()
        if not profile_id and not model_id:
            return None
        if not profile_id or not model_id:
            raise ValueError("Invalid LLM selection: profile_id and model_id are required.")

        reasoning_effort = str(value.get("reasoning_effort") or "").strip().lower() or None
        if reasoning_effort is not None and reasoning_effort not in VALID_REASONING_EFFORTS:
            raise ValueError(
                "Invalid LLM selection: unsupported reasoning_effort "
                f"{reasoning_effort!r}. Expected one of "
                f"{', '.join(VALID_REASONING_EFFORTS)}."
            )
        return cls(profile_id=profile_id, model_id=model_id, reasoning_effort=reasoning_effort)

    def to_dict(self) -> dict[str, str]:
        payload = {"profile_id": self.profile_id, "model_id": self.model_id}
        if self.reasoning_effort:
            payload["reasoning_effort"] = self.reasoning_effort
        return payload


def _coerce_int(value: Any) -> int | None:
    try:
        parsed = int(str(value).strip())
    except (TypeError, ValueError):
        return None
    return parsed if parsed > 0 else None


def _llm_service(catalog: dict[str, Any]) -> dict[str, Any]:
    if not isinstance(catalog, dict):
        return {}
    services = catalog.get("services")
    return services.get("llm", {}) if isinstance(services, dict) else {}


def list_llm_options(catalog: dict[str, Any]) -> dict[str, Any]:
    """Return a redacted list of configured chat-selectable LLM models."""
    service = _llm_service(catalog)
    active_profile_id = str(service.get("active_profile_id") or "")
    active_model_id = str(service.get("active_model_id") or "")

    options: list[dict[str, Any]] = []
    # Local import: the llm package imports back into this module at load time.
    from deeptutor.services.llm.capabilities import supports_vision_declared

    for profile in service.get("profiles", []) or []:
        if not isinstance(profile, dict):
            continue
        profile_id = str(profile.get("id") or "").strip()
        if not profile_id:
            continue
        provider = str(profile.get("binding") or "").strip()
        profile_name = str(profile.get("name") or provider or "LLM").strip()
        # Human-readable provider name from the registry ("OpenRouter",
        # "VolcEngine Coding Plan", ...) so the UI never shows binding keys.
        provider_spec = find_by_name(provider)
        provider_label = provider_spec.label if provider_spec else provider

        for model in profile.get("models", []) or []:
            if not isinstance(model, dict):
                continue
            model_id = str(model.get("id") or "").strip()
            model_value = str(model.get("model") or "").strip()
            if not model_id or not model_value:
                continue

            from deeptutor.services.config.provider_links import resolve_profile_provider

            effective = resolve_profile_provider(catalog, "llm", profile, model)
            model_provider = str(effective.get("binding") or provider)
            model_spec = find_by_name(model_provider)
            option: dict[str, Any] = {
                "profile_id": profile_id,
                "model_id": model_id,
                "profile_name": str(effective.get("name") or profile_name),
                "model_name": str(model.get("name") or model_value).strip(),
                "model": model_value,
                "provider": model_provider,
                "provider_label": model_spec.label
                if model_spec
                else model_provider or provider_label,
                "is_active_default": (
                    profile_id == active_profile_id and model_id == active_model_id
                ),
            }
            context_window = _coerce_int(model.get("context_window"))
            if context_window is None:
                context_window = _coerce_int(model.get("context_window_tokens"))
            if context_window is not None:
                option["context_window"] = context_window
            reasoning_effort = str(model.get("reasoning_effort") or "").strip().lower()
            if reasoning_effort:
                option["reasoning_effort"] = reasoning_effort
            supported_levels = model.get("codex_supported_reasoning_levels")
            if isinstance(supported_levels, list):
                option["supported_reasoning_efforts"] = [
                    str(level).strip().lower() for level in supported_levels if str(level).strip()
                ]
            declared = model.get("capabilities") or {}
            for capability in ("reasoning", "vision"):
                if type(declared.get(capability)) is bool:
                    option[f"declared_{capability}"] = declared[capability]
            # The settings UI filters vision models on this field. A model's own
            # declaration wins over the process-global override table, which
            # only refreshes on the next runtime resolution -- otherwise a
            # freshly declared model stays hidden until something else resolves
            # (#2037). Same rule as `lightrag/roles.py` and the save-time gate.
            option["supports_vision"] = supports_vision_declared(
                declared.get("vision"), model_provider, model_value
            )
            options.append(option)

    return {
        "active": {"profile_id": active_profile_id, "model_id": active_model_id}
        if active_profile_id and active_model_id
        else None,
        "options": options,
    }


def apply_llm_selection_to_catalog(
    catalog: dict[str, Any],
    selection: LLMSelection | dict[str, Any] | None,
) -> dict[str, Any]:
    """Return a catalog copy whose active LLM points at *selection*."""
    resolved = LLMSelection.from_payload(selection)
    selected = deepcopy(catalog)
    if resolved is None:
        return selected

    service = _llm_service(selected)
    for profile in service.get("profiles", []) or []:
        if not isinstance(profile, dict) or profile.get("id") != resolved.profile_id:
            continue
        for model in profile.get("models", []) or []:
            if isinstance(model, dict) and model.get("id") == resolved.model_id:
                service["active_profile_id"] = resolved.profile_id
                service["active_model_id"] = resolved.model_id
                return selected
        break

    raise ValueError("Invalid LLM selection: selected profile/model was not found.")


__all__ = [
    "LLMSelection",
    "VALID_REASONING_EFFORTS",
    "apply_llm_selection_to_catalog",
    "list_llm_options",
]