Skip to content

Self-hosted AI workspace.

Python
30.2 KB
Raw Blame
"""Canonical model capability metadata helpers.

This module defines shape and normalization only. It does not probe providers,
change routing, or infer authoritative capabilities from a bare model ID.
"""

from __future__ import annotations

from collections.abc import Iterable, Mapping
from dataclasses import dataclass, field
from typing import Any


FAMILY_CHAT = "chat"
FAMILY_EMBEDDING = "embedding"
FAMILY_IMAGE = "image"
FAMILY_VIDEO = "video"
FAMILY_AUDIO = "audio"
FAMILY_RERANK = "rerank"
FAMILY_CLASSIFICATION = "classification"
FAMILY_MODERATION = "moderation"
FAMILY_UNKNOWN = "unknown"

FAMILIES = frozenset(
    {
        FAMILY_CHAT,
        FAMILY_EMBEDDING,
        FAMILY_IMAGE,
        FAMILY_VIDEO,
        FAMILY_AUDIO,
        FAMILY_RERANK,
        FAMILY_CLASSIFICATION,
        FAMILY_MODERATION,
        FAMILY_UNKNOWN,
    }
)

MODALITY_TEXT = "text"
MODALITY_IMAGE = "image"
MODALITY_FILE = "file"
MODALITY_PDF = "pdf"
MODALITY_AUDIO = "audio"
MODALITY_VIDEO = "video"
MODALITY_EMBEDDING = "embedding"

MODALITIES = frozenset(
    {
        MODALITY_TEXT,
        MODALITY_IMAGE,
        MODALITY_FILE,
        MODALITY_PDF,
        MODALITY_AUDIO,
        MODALITY_VIDEO,
        MODALITY_EMBEDDING,
    }
)

CAP_VISION = "vision"
CAP_FILES = "files"
CAP_PDF = "pdf"
CAP_AUDIO_INPUT = "audio_input"
CAP_AUDIO_OUTPUT = "audio_output"
CAP_IMAGE_GENERATION = "image_generation"
CAP_IMAGE_EDITING = "image_editing"
CAP_INPAINTING = "inpainting"
CAP_VIDEO_GENERATION = "video_generation"
CAP_REASONING = "reasoning"
CAP_TOOL_CALL = "tool_call"
CAP_STRUCTURED_OUTPUT = "structured_output"
CAP_WEB_SEARCH = "web_search"
CAP_STREAMING = "streaming"
CAP_JSON_MODE = "json_mode"
CAP_TRANSCRIPTION = "transcription"
CAP_TTS = "tts"
CAP_REALTIME = "realtime"
CAP_TEXT_RENDERING = "text_rendering"

CAPABILITIES = frozenset(
    {
        CAP_VISION,
        CAP_FILES,
        CAP_PDF,
        CAP_AUDIO_INPUT,
        CAP_AUDIO_OUTPUT,
        CAP_IMAGE_GENERATION,
        CAP_IMAGE_EDITING,
        CAP_INPAINTING,
        CAP_VIDEO_GENERATION,
        CAP_REASONING,
        CAP_TOOL_CALL,
        CAP_STRUCTURED_OUTPUT,
        CAP_WEB_SEARCH,
        CAP_STREAMING,
        CAP_JSON_MODE,
        CAP_TRANSCRIPTION,
        CAP_TTS,
        CAP_REALTIME,
        CAP_TEXT_RENDERING,
    }
)

SOURCE_ADMIN_OVERRIDE = "admin_override"
SOURCE_ENDPOINT_CONFIG = "endpoint_config"
SOURCE_PROVIDER_READER = "provider_reader"
SOURCE_COOKBOOK_HF = "cookbook_hf"
SOURCE_MODELS_DEV_REGISTRY = "models_dev_registry"
SOURCE_PROVIDER_DOCS_REGISTRY = "provider_docs_registry"
SOURCE_HEURISTIC = "heuristic"
SOURCE_CAPABILITY_PROBE = "capability_probe"
SOURCE_UNKNOWN = "unknown"

SOURCES = frozenset(
    {
        SOURCE_ADMIN_OVERRIDE,
        SOURCE_ENDPOINT_CONFIG,
        SOURCE_PROVIDER_READER,
        SOURCE_COOKBOOK_HF,
        SOURCE_MODELS_DEV_REGISTRY,
        SOURCE_PROVIDER_DOCS_REGISTRY,
        SOURCE_HEURISTIC,
        SOURCE_CAPABILITY_PROBE,
        SOURCE_UNKNOWN,
    }
)

CONFIDENCE_EXPLICIT = "explicit"
CONFIDENCE_PROVIDER_REPORTED = "provider_reported"
CONFIDENCE_REGISTRY = "registry"
CONFIDENCE_HEURISTIC = "heuristic"
CONFIDENCE_UNKNOWN = "unknown"

CONFIDENCES = frozenset(
    {
        CONFIDENCE_EXPLICIT,
        CONFIDENCE_PROVIDER_REPORTED,
        CONFIDENCE_REGISTRY,
        CONFIDENCE_HEURISTIC,
        CONFIDENCE_UNKNOWN,
    }
)

ASSERTION_CLAIMED = "claimed"
ASSERTION_VERIFIED = "verified"
ASSERTION_UNSUPPORTED = "unsupported"
ASSERTION_UNKNOWN = "unknown"

ASSERTION_STATUSES = frozenset(
    {
        ASSERTION_CLAIMED,
        ASSERTION_VERIFIED,
        ASSERTION_UNSUPPORTED,
        ASSERTION_UNKNOWN,
    }
)

PROBE_PASS = "pass"
PROBE_FAIL = "fail"
PROBE_PARTIAL = "partial"

PROBE_STATUSES = frozenset(
    {
        PROBE_PASS,
        PROBE_FAIL,
        PROBE_PARTIAL,
    }
)

CONTROL_TEMPERATURE = "temperature"
CONTROL_TOP_P = "top_p"
CONTROL_TOP_K = "top_k"
CONTROL_SEED = "seed"
CONTROL_MODEL_VERSION_PIN = "model_version_pin"
CONTROL_STRICT_SCHEMA = "strict_schema"
CONTROL_TOOL_CHOICE = "tool_choice"
CONTROL_SYSTEM_PROMPT = "system_prompt"
CONTROL_PROMPT_CACHING = "prompt_caching"
CONTROL_BATCH = "batch"
CONTROL_REQUEST_HASH_CACHE = "request_hash_cache"
CONTROL_SYSTEM_FINGERPRINT = "system_fingerprint"

# Canonical reasoning control mechanisms describe how a serving path accepts
# reasoning controls. They are provider/engine evidence, not user preferences.
REASONING_CONTROL_MESSAGE_DIRECTIVE = "reasoning_message_directive"  # User-message soft switch, e.g. /think or /no_think.
REASONING_CONTROL_SYSTEM_DIRECTIVE = "reasoning_system_directive"  # System prompt instruction, e.g. "detailed thinking on/off".
REASONING_CONTROL_TEMPLATE_KWARG = "reasoning_template_kwarg"  # Chat-template kwarg, e.g. chat_template_kwargs.enable_thinking.
REASONING_CONTROL_NATIVE_BOOL = "reasoning_native_bool"  # Direct API boolean, e.g. think: true/false.
REASONING_CONTROL_STRUCTURED_OBJECT = "reasoning_structured_object"  # Structured API object, e.g. thinking: {type: "..."}.
REASONING_CONTROL_BUDGET = "reasoning_budget"  # Token budget control, e.g. thinkingBudget: 0/-1/N.
REASONING_CONTROL_EFFORT = "reasoning_effort"  # Graded effort control, e.g. low/medium/high.

# Canonical reasoning control values describe what the provider control accepts.
# Odysseus runtime preferences can also use auto/on/off, but that is a separate
# layer that later code resolves into these provider-specific controls.
REASONING_CONTROL_VALUE_ON = "on"  # Provider supports explicitly requesting reasoning on.
REASONING_CONTROL_VALUE_OFF = "off"  # Provider supports explicitly requesting reasoning off.
REASONING_CONTROL_VALUE_AUTO = "auto"  # Provider supports adaptive/dynamic/vendor-decided reasoning.

REASONING_CONTROL_MECHANISMS = frozenset(
    {
        REASONING_CONTROL_MESSAGE_DIRECTIVE,
        REASONING_CONTROL_SYSTEM_DIRECTIVE,
        REASONING_CONTROL_TEMPLATE_KWARG,
        REASONING_CONTROL_NATIVE_BOOL,
        REASONING_CONTROL_STRUCTURED_OBJECT,
        REASONING_CONTROL_BUDGET,
        REASONING_CONTROL_EFFORT,
    }
)

REASONING_CONTROL_VALUES = frozenset(
    {
        REASONING_CONTROL_VALUE_ON,
        REASONING_CONTROL_VALUE_OFF,
        REASONING_CONTROL_VALUE_AUTO,
    }
)

DETERMINISTIC_CONTROLS = frozenset(
    {
        CONTROL_TEMPERATURE,
        CONTROL_TOP_P,
        CONTROL_TOP_K,
        CONTROL_SEED,
        CONTROL_MODEL_VERSION_PIN,
        CONTROL_STRICT_SCHEMA,
        CONTROL_TOOL_CHOICE,
        CONTROL_SYSTEM_PROMPT,
        CONTROL_PROMPT_CACHING,
        CONTROL_BATCH,
        CONTROL_REQUEST_HASH_CACHE,
        CONTROL_SYSTEM_FINGERPRINT,
    }
)

TASK_CHAT_COMPLETIONS = "chat.completions"
TASK_EMBEDDINGS_CREATE = "embeddings.create"
TASK_IMAGE_GENERATE = "image.generate"
TASK_IMAGE_EDIT = "image.edit"
TASK_VIDEO_GENERATE = "video.generate"
TASK_AUDIO_TRANSCRIBE = "audio.transcribe"
TASK_AUDIO_SYNTHESIZE = "audio.synthesize"
TASK_RERANK = "rerank.score"
TASK_CLASSIFY = "classification.classify"
TASK_MODERATE = "moderation.moderate"
TASK_UNKNOWN = "unknown"

_FAMILY_ALIASES = {
    "llm": FAMILY_CHAT,
    "text": FAMILY_CHAT,
    "text2text": FAMILY_CHAT,
    "chat_completion": FAMILY_CHAT,
    "chat_completions": FAMILY_CHAT,
    "embeddings": FAMILY_EMBEDDING,
    "embed": FAMILY_EMBEDDING,
    "image_generation": FAMILY_IMAGE,
    "image_editing": FAMILY_IMAGE,
    "video_generation": FAMILY_VIDEO,
    "speech": FAMILY_AUDIO,
    "stt": FAMILY_AUDIO,
    "tts": FAMILY_AUDIO,
    "safety": FAMILY_MODERATION,
}

_MODALITY_ALIASES = {
    "images": MODALITY_IMAGE,
    "img": MODALITY_IMAGE,
    "document": MODALITY_FILE,
    "documents": MODALITY_FILE,
    "files": MODALITY_FILE,
    "docs": MODALITY_FILE,
    "voice": MODALITY_AUDIO,
    "sound": MODALITY_AUDIO,
    "embeddings": MODALITY_EMBEDDING,
}

_CAPABILITY_ALIASES = {
    "tools": CAP_TOOL_CALL,
    "tool_calls": CAP_TOOL_CALL,
    "function_calling": CAP_TOOL_CALL,
    "functions": CAP_TOOL_CALL,
    "image_generate": CAP_IMAGE_GENERATION,
    "text_to_image": CAP_IMAGE_GENERATION,
    "text-to-image": CAP_IMAGE_GENERATION,
    "img2img": CAP_IMAGE_EDITING,
    "image_edit": CAP_IMAGE_EDITING,
    "image-editing": CAP_IMAGE_EDITING,
    "text_rendering": CAP_TEXT_RENDERING,
    "reasoning_effort": CAP_REASONING,
    "thinking": CAP_REASONING,
    "json": CAP_JSON_MODE,
    "structured_outputs": CAP_STRUCTURED_OUTPUT,
    "search": CAP_WEB_SEARCH,
}

_DETERMINISTIC_CONTROL_ALIASES = {
    "temp": CONTROL_TEMPERATURE,
    "topp": CONTROL_TOP_P,
    "top-p": CONTROL_TOP_P,
    "topk": CONTROL_TOP_K,
    "top-k": CONTROL_TOP_K,
    "version_pin": CONTROL_MODEL_VERSION_PIN,
    "model_pin": CONTROL_MODEL_VERSION_PIN,
    "strict_tool_schema": CONTROL_STRICT_SCHEMA,
    "json_schema": CONTROL_STRICT_SCHEMA,
    "tool_choice_required": CONTROL_TOOL_CHOICE,
    "system": CONTROL_SYSTEM_PROMPT,
    "system_message": CONTROL_SYSTEM_PROMPT,
    "cache": CONTROL_REQUEST_HASH_CACHE,
    "fingerprint": CONTROL_SYSTEM_FINGERPRINT,
}

_REASONING_CONTROL_ALIASES = {
    "message_directive": REASONING_CONTROL_MESSAGE_DIRECTIVE,
    "user_message_directive": REASONING_CONTROL_MESSAGE_DIRECTIVE,
    "think_directive": REASONING_CONTROL_MESSAGE_DIRECTIVE,
    "slash_think": REASONING_CONTROL_MESSAGE_DIRECTIVE,
    "system_directive": REASONING_CONTROL_SYSTEM_DIRECTIVE,
    "system_prompt_directive": REASONING_CONTROL_SYSTEM_DIRECTIVE,
    "template_kwarg": REASONING_CONTROL_TEMPLATE_KWARG,
    "chat_template_kwarg": REASONING_CONTROL_TEMPLATE_KWARG,
    "chat_template_kwargs": REASONING_CONTROL_TEMPLATE_KWARG,
    "enable_thinking": REASONING_CONTROL_TEMPLATE_KWARG,
    "native_bool": REASONING_CONTROL_NATIVE_BOOL,
    "think_bool": REASONING_CONTROL_NATIVE_BOOL,
    "thinking_bool": REASONING_CONTROL_NATIVE_BOOL,
    "structured_object": REASONING_CONTROL_STRUCTURED_OBJECT,
    "reasoning_object": REASONING_CONTROL_STRUCTURED_OBJECT,
    "thinking_budget": REASONING_CONTROL_BUDGET,
    "budget": REASONING_CONTROL_BUDGET,
    "effort": REASONING_CONTROL_EFFORT,
}

_REASONING_CONTROL_VALUE_ALIASES = {
    "enabled": REASONING_CONTROL_VALUE_ON,
    "enable": REASONING_CONTROL_VALUE_ON,
    "true": REASONING_CONTROL_VALUE_ON,
    "disabled": REASONING_CONTROL_VALUE_OFF,
    "disable": REASONING_CONTROL_VALUE_OFF,
    "false": REASONING_CONTROL_VALUE_OFF,
    "adaptive": REASONING_CONTROL_VALUE_AUTO,
    "automatic": REASONING_CONTROL_VALUE_AUTO,
    "dynamic": REASONING_CONTROL_VALUE_AUTO,
    "provider_auto": REASONING_CONTROL_VALUE_AUTO,
    "vendor_auto": REASONING_CONTROL_VALUE_AUTO,
}

_DEFAULT_TASK_BY_FAMILY = {
    FAMILY_CHAT: TASK_CHAT_COMPLETIONS,
    FAMILY_EMBEDDING: TASK_EMBEDDINGS_CREATE,
    FAMILY_IMAGE: TASK_IMAGE_GENERATE,
    FAMILY_VIDEO: TASK_VIDEO_GENERATE,
    FAMILY_AUDIO: TASK_AUDIO_TRANSCRIBE,
    FAMILY_RERANK: TASK_RERANK,
    FAMILY_CLASSIFICATION: TASK_CLASSIFY,
    FAMILY_MODERATION: TASK_MODERATE,
    FAMILY_UNKNOWN: TASK_UNKNOWN,
}

_DEFAULT_MODALITIES_BY_FAMILY = {
    FAMILY_CHAT: ((MODALITY_TEXT,), (MODALITY_TEXT,)),
    FAMILY_EMBEDDING: ((MODALITY_TEXT,), (MODALITY_EMBEDDING,)),
    FAMILY_IMAGE: ((MODALITY_TEXT,), (MODALITY_IMAGE,)),
    FAMILY_VIDEO: ((MODALITY_TEXT,), (MODALITY_VIDEO,)),
    FAMILY_AUDIO: ((MODALITY_TEXT,), (MODALITY_AUDIO,)),
    FAMILY_RERANK: ((MODALITY_TEXT,), (MODALITY_TEXT,)),
    FAMILY_CLASSIFICATION: ((MODALITY_TEXT,), (MODALITY_TEXT,)),
    FAMILY_MODERATION: ((MODALITY_TEXT,), (MODALITY_TEXT,)),
    FAMILY_UNKNOWN: ((), ()),
}

_DEFAULT_CAPABILITIES_BY_FAMILY = {
    FAMILY_IMAGE: (CAP_IMAGE_GENERATION,),
    FAMILY_VIDEO: (CAP_VIDEO_GENERATION,),
}


def _clean_token(value: Any) -> str:
    return str(value or "").strip().lower().replace("-", "_").replace(" ", "_")


def _normalize_choice(value: Any, allowed: frozenset[str], aliases: Mapping[str, str], default: str) -> str:
    token = _clean_token(value)
    token = aliases.get(token, token)
    return token if token in allowed else default


def normalize_family(value: Any) -> str:
    return _normalize_choice(value, FAMILIES, _FAMILY_ALIASES, FAMILY_UNKNOWN)


def normalize_source(value: Any) -> str:
    return _normalize_choice(value, SOURCES, {}, SOURCE_UNKNOWN)


def normalize_confidence(value: Any) -> str:
    return _normalize_choice(value, CONFIDENCES, {}, CONFIDENCE_UNKNOWN)


def normalize_modality(value: Any) -> str:
    return _normalize_choice(value, MODALITIES, _MODALITY_ALIASES, "")


def normalize_capability(value: Any) -> str:
    token = _clean_token(value)
    token = _CAPABILITY_ALIASES.get(token, token)
    return token if token in CAPABILITIES else ""


def normalize_assertion_status(value: Any) -> str:
    return _normalize_choice(value, ASSERTION_STATUSES, {}, ASSERTION_UNKNOWN)


def normalize_probe_status(value: Any) -> str:
    return _normalize_choice(value, PROBE_STATUSES, {}, "")


def normalize_deterministic_control(value: Any) -> str:
    token = _clean_token(value)
    token = _DETERMINISTIC_CONTROL_ALIASES.get(token, token)
    return token if token in DETERMINISTIC_CONTROLS else ""


def normalize_reasoning_control_mechanism(value: Any) -> str:
    token = _clean_token(value)
    token = _REASONING_CONTROL_ALIASES.get(token, token)
    return token if token in REASONING_CONTROL_MECHANISMS else ""


def normalize_reasoning_control_value(value: Any) -> str:
    token = _clean_token(value)
    token = _REASONING_CONTROL_VALUE_ALIASES.get(token, token)
    return token if token in REASONING_CONTROL_VALUES else ""


def _normalize_tokens(values: Any, normalizer) -> tuple[str, ...]:
    if values is None:
        return ()
    if isinstance(values, Mapping):
        values = [key for key, enabled in values.items() if enabled]
    elif isinstance(values, str) or not isinstance(values, Iterable):
        values = [values]
    out: list[str] = []
    for value in values:
        token = normalizer(value)
        if token and token not in out:
            out.append(token)
    return tuple(out)


def _normalize_limits(limits: Mapping[str, Any] | None) -> tuple[tuple[str, Any], ...]:
    if not isinstance(limits, Mapping):
        return ()
    return tuple(sorted((str(k), v) for k, v in limits.items() if str(k).strip()))


@dataclass(frozen=True)
class Modalities:
    input: tuple[str, ...] = ()
    output: tuple[str, ...] = ()

    @classmethod
    def from_values(cls, input: Any = None, output: Any = None) -> "Modalities":
        return cls(
            input=_normalize_tokens(input, normalize_modality),
            output=_normalize_tokens(output, normalize_modality),
        )

    def to_dict(self) -> dict[str, list[str]]:
        return {
            "input": list(self.input),
            "output": list(self.output),
        }


@dataclass(frozen=True)
class ModelCapability:
    family: str = FAMILY_UNKNOWN
    primary_task: str = TASK_UNKNOWN
    modalities: Modalities = field(default_factory=Modalities)
    capabilities: tuple[str, ...] = ()
    limits: tuple[tuple[str, Any], ...] = ()
    source: str = SOURCE_UNKNOWN
    confidence: str = CONFIDENCE_UNKNOWN

    @classmethod
    def build(
        cls,
        *,
        family: Any = FAMILY_UNKNOWN,
        primary_task: str | None = None,
        input_modalities: Any = None,
        output_modalities: Any = None,
        capabilities: Any = None,
        limits: Mapping[str, Any] | None = None,
        source: Any = SOURCE_UNKNOWN,
        confidence: Any = CONFIDENCE_UNKNOWN,
    ) -> "ModelCapability":
        normalized_family = normalize_family(family)
        default_input, default_output = _DEFAULT_MODALITIES_BY_FAMILY[normalized_family]
        return cls(
            family=normalized_family,
            primary_task=str(primary_task or _DEFAULT_TASK_BY_FAMILY[normalized_family]).strip() or TASK_UNKNOWN,
            modalities=Modalities.from_values(
                input_modalities if input_modalities is not None else default_input,
                output_modalities if output_modalities is not None else default_output,
            ),
            capabilities=_normalize_tokens(
                capabilities if capabilities is not None else _DEFAULT_CAPABILITIES_BY_FAMILY.get(normalized_family, ()),
                normalize_capability,
            ),
            limits=_normalize_limits(limits),
            source=normalize_source(source),
            confidence=normalize_confidence(confidence),
        )

    @classmethod
    def from_dict(cls, value: Mapping[str, Any]) -> "ModelCapability":
        if not isinstance(value, Mapping):
            return unknown_capability()
        modalities = value.get("modalities")
        if not isinstance(modalities, Mapping):
            modalities = {}
        return cls.build(
            family=value.get("family"),
            primary_task=value.get("primary_task"),
            input_modalities=modalities.get("input"),
            output_modalities=modalities.get("output"),
            capabilities=value.get("capabilities"),
            limits=value.get("limits"),
            source=value.get("source"),
            confidence=value.get("confidence"),
        )

    def to_dict(self) -> dict[str, Any]:
        return {
            "family": self.family,
            "primary_task": self.primary_task,
            "modalities": self.modalities.to_dict(),
            "capabilities": list(self.capabilities),
            "limits": dict(self.limits),
            "source": self.source,
            "confidence": self.confidence,
        }


@dataclass(frozen=True)
class CapabilityAssertion:
    capability: str = ""
    status: str = ASSERTION_UNKNOWN
    source: str = SOURCE_UNKNOWN
    confidence: str = CONFIDENCE_UNKNOWN
    evidence: tuple[tuple[str, Any], ...] = ()
    tested_at: str = ""

    @classmethod
    def build(
        cls,
        *,
        capability: Any,
        status: Any = ASSERTION_UNKNOWN,
        source: Any = SOURCE_UNKNOWN,
        confidence: Any = CONFIDENCE_UNKNOWN,
        evidence: Mapping[str, Any] | None = None,
        tested_at: Any = "",
    ) -> "CapabilityAssertion":
        normalized_capability = normalize_capability(capability)
        normalized_status = normalize_assertion_status(status)
        if not normalized_capability:
            normalized_status = ASSERTION_UNKNOWN
        return cls(
            capability=normalized_capability,
            status=normalized_status,
            source=normalize_source(source),
            confidence=normalize_confidence(confidence),
            evidence=_normalize_limits(evidence),
            tested_at=str(tested_at or "").strip(),
        )

    @classmethod
    def from_dict(cls, value: Mapping[str, Any]) -> "CapabilityAssertion":
        if not isinstance(value, Mapping):
            return cls.build(capability="")
        return cls.build(
            capability=value.get("capability"),
            status=value.get("status"),
            source=value.get("source"),
            confidence=value.get("confidence"),
            evidence=value.get("evidence"),
            tested_at=value.get("tested_at"),
        )

    def to_dict(self) -> dict[str, Any]:
        return {
            "capability": self.capability,
            "status": self.status,
            "source": self.source,
            "confidence": self.confidence,
            "evidence": dict(self.evidence),
            "tested_at": self.tested_at,
        }


@dataclass(frozen=True)
class DeterministicControl:
    control: str = ""
    status: str = ASSERTION_UNKNOWN
    source: str = SOURCE_UNKNOWN
    confidence: str = CONFIDENCE_UNKNOWN
    evidence: tuple[tuple[str, Any], ...] = ()
    tested_at: str = ""

    @classmethod
    def build(
        cls,
        *,
        control: Any,
        status: Any = ASSERTION_UNKNOWN,
        source: Any = SOURCE_UNKNOWN,
        confidence: Any = CONFIDENCE_UNKNOWN,
        evidence: Mapping[str, Any] | None = None,
        tested_at: Any = "",
    ) -> "DeterministicControl":
        normalized_control = normalize_deterministic_control(control)
        normalized_status = normalize_assertion_status(status)
        if not normalized_control:
            normalized_status = ASSERTION_UNKNOWN
        return cls(
            control=normalized_control,
            status=normalized_status,
            source=normalize_source(source),
            confidence=normalize_confidence(confidence),
            evidence=_normalize_limits(evidence),
            tested_at=str(tested_at or "").strip(),
        )

    @classmethod
    def from_dict(cls, value: Mapping[str, Any]) -> "DeterministicControl":
        if not isinstance(value, Mapping):
            return cls.build(control="")
        return cls.build(
            control=value.get("control"),
            status=value.get("status"),
            source=value.get("source"),
            confidence=value.get("confidence"),
            evidence=value.get("evidence"),
            tested_at=value.get("tested_at"),
        )

    def to_dict(self) -> dict[str, Any]:
        return {
            "control": self.control,
            "status": self.status,
            "source": self.source,
            "confidence": self.confidence,
            "evidence": dict(self.evidence),
            "tested_at": self.tested_at,
        }


@dataclass(frozen=True)
class CapabilityProbeResult:
    provider: str
    model_id: str
    capability: str
    status: str
    tested_at: str = ""
    endpoint_id: str = ""
    stable_model_id: str = ""
    request_hash: str = ""
    response_id: str = ""
    response_fingerprint: str = ""
    evidence: tuple[tuple[str, Any], ...] = ()

    @classmethod
    def build(
        cls,
        *,
        provider: Any,
        model_id: Any,
        capability: Any,
        status: Any,
        tested_at: Any = "",
        endpoint_id: Any = "",
        stable_model_id: Any = "",
        request_hash: Any = "",
        response_id: Any = "",
        response_fingerprint: Any = "",
        evidence: Mapping[str, Any] | None = None,
    ) -> "CapabilityProbeResult":
        normalized_capability = normalize_capability(capability)
        normalized_status = normalize_probe_status(status)
        if not normalized_capability or not normalized_status:
            normalized_status = PROBE_FAIL
        return cls(
            provider=str(provider or "").strip(),
            model_id=str(model_id or "").strip(),
            capability=normalized_capability,
            status=normalized_status,
            tested_at=str(tested_at or "").strip(),
            endpoint_id=str(endpoint_id or "").strip(),
            stable_model_id=str(stable_model_id or "").strip(),
            request_hash=str(request_hash or "").strip(),
            response_id=str(response_id or "").strip(),
            response_fingerprint=str(response_fingerprint or "").strip(),
            evidence=_normalize_limits(evidence),
        )

    @classmethod
    def from_dict(cls, value: Mapping[str, Any]) -> "CapabilityProbeResult":
        if not isinstance(value, Mapping):
            return cls.build(provider="", model_id="", capability="", status=PROBE_FAIL)
        return cls.build(
            provider=value.get("provider"),
            endpoint_id=value.get("endpoint_id"),
            model_id=value.get("model_id"),
            stable_model_id=value.get("stable_model_id"),
            capability=value.get("capability"),
            status=value.get("status"),
            tested_at=value.get("tested_at"),
            request_hash=value.get("request_hash"),
            response_id=value.get("response_id"),
            response_fingerprint=value.get("response_fingerprint"),
            evidence=value.get("evidence"),
        )

    def to_assertion(self) -> CapabilityAssertion:
        status_map = {
            PROBE_PASS: ASSERTION_VERIFIED,
            PROBE_FAIL: ASSERTION_UNSUPPORTED,
            PROBE_PARTIAL: ASSERTION_CLAIMED,
        }
        return CapabilityAssertion.build(
            capability=self.capability,
            status=status_map.get(self.status, ASSERTION_UNKNOWN),
            source=SOURCE_CAPABILITY_PROBE,
            confidence=CONFIDENCE_EXPLICIT if self.status == PROBE_PASS else CONFIDENCE_HEURISTIC,
            evidence={
                "provider": self.provider,
                "endpoint_id": self.endpoint_id,
                "model_id": self.model_id,
                "stable_model_id": self.stable_model_id,
                "request_hash": self.request_hash,
                "response_id": self.response_id,
                "response_fingerprint": self.response_fingerprint,
                **dict(self.evidence),
            },
            tested_at=self.tested_at,
        )

    def to_dict(self) -> dict[str, Any]:
        return {
            "provider": self.provider,
            "endpoint_id": self.endpoint_id,
            "model_id": self.model_id,
            "stable_model_id": self.stable_model_id,
            "capability": self.capability,
            "status": self.status,
            "tested_at": self.tested_at,
            "request_hash": self.request_hash,
            "response_id": self.response_id,
            "response_fingerprint": self.response_fingerprint,
            "evidence": dict(self.evidence),
        }


def capability_assertions_from_capability(
    capability: ModelCapability,
    *,
    status: str = ASSERTION_CLAIMED,
    source: str | None = None,
    confidence: str | None = None,
) -> tuple[CapabilityAssertion, ...]:
    return tuple(
        CapabilityAssertion.build(
            capability=cap,
            status=status,
            source=source or capability.source,
            confidence=confidence or capability.confidence,
        )
        for cap in capability.capabilities
    )


def deterministic_controls_from_values(
    values: Any,
    *,
    status: str = ASSERTION_CLAIMED,
    source: str = SOURCE_PROVIDER_READER,
    confidence: str = CONFIDENCE_PROVIDER_REPORTED,
) -> tuple[DeterministicControl, ...]:
    return tuple(
        DeterministicControl.build(
            control=control,
            status=status,
            source=source,
            confidence=confidence,
        )
        for control in _normalize_tokens(values, normalize_deterministic_control)
    )


@dataclass(frozen=True)
class CapabilityQuery:
    surface: str
    families: tuple[str, ...] = ()
    primary_tasks: tuple[str, ...] = ()
    input_all: tuple[str, ...] = ()
    input_any: tuple[str, ...] = ()
    output_all: tuple[str, ...] = ()
    output_any: tuple[str, ...] = ()
    modality_any: tuple[str, ...] = ()
    capabilities_all: tuple[str, ...] = ()
    capabilities_any: tuple[str, ...] = ()

    def matches(self, capability: ModelCapability) -> bool:
        input_set = set(capability.modalities.input)
        output_set = set(capability.modalities.output)
        modality_set = input_set | output_set
        cap_set = set(capability.capabilities)
        if self.families and capability.family not in self.families:
            return False
        if self.primary_tasks and capability.primary_task not in self.primary_tasks:
            return False
        if self.input_all and not set(self.input_all).issubset(input_set):
            return False
        if self.input_any and input_set.isdisjoint(self.input_any):
            return False
        if self.output_all and not set(self.output_all).issubset(output_set):
            return False
        if self.output_any and output_set.isdisjoint(self.output_any):
            return False
        if self.modality_any and modality_set.isdisjoint(self.modality_any):
            return False
        if self.capabilities_all and not set(self.capabilities_all).issubset(cap_set):
            return False
        if self.capabilities_any and cap_set.isdisjoint(self.capabilities_any):
            return False
        return True


DISPLAY_QUERIES = (
    CapabilityQuery(
        surface="chat",
        families=(FAMILY_CHAT,),
        input_all=(MODALITY_TEXT,),
        output_all=(MODALITY_TEXT,),
    ),
    CapabilityQuery(
        surface="vision_chat",
        families=(FAMILY_CHAT,),
        input_all=(MODALITY_TEXT, MODALITY_IMAGE),
        output_all=(MODALITY_TEXT,),
    ),
    CapabilityQuery(
        surface="document_chat",
        families=(FAMILY_CHAT,),
        input_all=(MODALITY_TEXT,),
        input_any=(MODALITY_FILE, MODALITY_PDF),
        output_all=(MODALITY_TEXT,),
    ),
    CapabilityQuery(
        surface="image_generation",
        families=(FAMILY_IMAGE,),
        output_all=(MODALITY_IMAGE,),
        capabilities_all=(CAP_IMAGE_GENERATION,),
    ),
    CapabilityQuery(
        surface="image_editing",
        families=(FAMILY_IMAGE,),
        input_all=(MODALITY_IMAGE,),
        output_all=(MODALITY_IMAGE,),
        capabilities_any=(CAP_IMAGE_EDITING, CAP_INPAINTING),
    ),
    CapabilityQuery(
        surface="video_generation",
        families=(FAMILY_VIDEO,),
        output_all=(MODALITY_VIDEO,),
        capabilities_all=(CAP_VIDEO_GENERATION,),
    ),
    CapabilityQuery(
        surface="audio_realtime",
        families=(FAMILY_AUDIO,),
        modality_any=(MODALITY_AUDIO,),
        capabilities_any=(CAP_AUDIO_INPUT, CAP_AUDIO_OUTPUT, CAP_TRANSCRIPTION, CAP_TTS, CAP_REALTIME),
    ),
    CapabilityQuery(
        surface="embeddings",
        families=(FAMILY_EMBEDDING,),
        output_all=(MODALITY_EMBEDDING,),
    ),
    CapabilityQuery(
        surface="rerank_scoring",
        families=(FAMILY_RERANK,),
    ),
    CapabilityQuery(
        surface="moderation_classification",
        families=(FAMILY_MODERATION, FAMILY_CLASSIFICATION),
    ),
)


def display_surfaces_for(capability: ModelCapability) -> tuple[str, ...]:
    return tuple(query.surface for query in DISPLAY_QUERIES if query.matches(capability))


def unknown_capability(
    *,
    source: str = SOURCE_UNKNOWN,
    confidence: str = CONFIDENCE_UNKNOWN,
) -> ModelCapability:
    return ModelCapability.build(source=source, confidence=confidence)


def capability_from_endpoint_type(model_type: Any) -> ModelCapability:
    """Return capability metadata from an explicit endpoint model type.

    Missing or unknown endpoint types remain unknown here. Runtime compatibility
    may still treat legacy rows as chat-capable, but this schema layer should
    not turn absence of evidence into model capability truth.
    """
    token = _clean_token(model_type)
    if token == "llm":
        return ModelCapability.build(
            family=FAMILY_CHAT,
            source=SOURCE_ENDPOINT_CONFIG,
            confidence=CONFIDENCE_EXPLICIT,
        )
    if token == "image":
        return ModelCapability.build(
            family=FAMILY_IMAGE,
            source=SOURCE_ENDPOINT_CONFIG,
            confidence=CONFIDENCE_EXPLICIT,
        )
    return unknown_capability(source=SOURCE_ENDPOINT_CONFIG)