1"""Model profile types and utilities."""23import logging4import warnings5from typing import get_type_hints67from pydantic import ConfigDict8from typing_extensions import TypedDict910logger = logging.getLogger(__name__)111213class ModelProfile(TypedDict, total=False):14    """Description of a chat model's capabilities, exposed via `model.profile`.1516    See the17    [model profiles guide](https://docs.langchain.com/oss/python/langchain/models#model-profiles)18    for concepts and usage. Data is sourced from19    [models.dev](https://github.com/sst/models.dev), augmented with additional20    fields, and generated by the21    [`langchain-model-profiles`](https://github.com/langchain-ai/langchain/tree/master/libs/model-profiles)22    package (via its `langchain-profiles` CLI).2324    !!! warning "Beta feature"2526        Fields and format are subject to change. This is a `total=False`27        `TypedDict`, so any field may be absent — guard accesses with `.get()`.28    """2930    __pydantic_config__ = ConfigDict(extra="allow")  # type: ignore[misc]3132    # --- Model metadata ---3334    name: str35    """Human-readable model name (e.g., `'GPT-5'`)."""3637    status: str38    """Model lifecycle status (e.g., `'active'`, `'deprecated'`)."""3940    release_date: str41    """Model release date (ISO 8601 format, e.g., `'2025-06-01'`)."""4243    last_updated: str44    """Date the model was last updated (ISO 8601 format)."""4546    open_weights: bool47    """Whether the model weights are openly available."""4849    # --- Input constraints ---5051    max_input_tokens: int52    """Maximum context window (tokens)."""5354    text_inputs: bool55    """Whether text inputs are supported."""5657    image_inputs: bool58    """Whether image inputs are supported."""59    # TODO: add more detail about formats?6061    image_url_inputs: bool62    """Whether [image URL inputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)63    are supported."""6465    pdf_inputs: bool66    """Whether [PDF inputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)67    are supported."""68    # TODO: add more detail about formats? e.g. bytes or base646970    audio_inputs: bool71    """Whether [audio inputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)72    are supported."""73    # TODO: add more detail about formats? e.g. bytes or base647475    video_inputs: bool76    """Whether [video inputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)77    are supported."""78    # TODO: add more detail about formats? e.g. bytes or base647980    image_tool_message: bool81    """Whether images can be included in `ToolMessage` content."""8283    pdf_tool_message: bool84    """Whether PDFs can be included in `ToolMessage` content."""8586    # --- Output constraints ---8788    max_output_tokens: int89    """Maximum output tokens."""9091    reasoning_output: bool92    """Whether the model supports [reasoning / chain-of-thought](https://docs.langchain.com/oss/python/langchain/models#reasoning)."""9394    text_outputs: bool95    """Whether text outputs are supported."""9697    image_outputs: bool98    """Whether [image outputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)99    are supported."""100101    audio_outputs: bool102    """Whether [audio outputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)103    are supported."""104105    video_outputs: bool106    """Whether [video outputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)107    are supported."""108109    # --- Tool calling ---110    tool_calling: bool111    """Whether the model supports [tool calling](https://docs.langchain.com/oss/python/langchain/models#tool-calling)."""112113    tool_choice: bool114    """Whether the model supports [tool choice](https://docs.langchain.com/oss/python/langchain/models#forcing-tool-calls)."""115116    # --- Structured output ---117    structured_output: bool118    """Whether the model supports native [structured output](https://docs.langchain.com/oss/python/langchain/models#structured-outputs)."""119120    # --- Other capabilities ---121122    attachment: bool123    """Whether the model supports file attachments."""124125    temperature: bool126    """Whether the model supports a temperature parameter."""127128129ModelProfileRegistry = dict[str, ModelProfile]130"""Registry mapping model identifiers or names to their ModelProfile."""131132133def _warn_unknown_profile_keys(profile: ModelProfile) -> None:134    """Warn if `profile` contains keys not declared on `ModelProfile`.135136    Args:137        profile: The model profile dict to check for undeclared keys.138    """139    if not isinstance(profile, dict):140        return141142    try:143        declared = frozenset(get_type_hints(ModelProfile).keys())144    except (TypeError, NameError):145        # get_type_hints raises NameError on unresolvable forward refs and146        # TypeError when annotations evaluate to non-type objects.147        logger.debug(148            "Could not resolve type hints for ModelProfile; "149            "skipping unknown-key check.",150            exc_info=True,151        )152        return153154    extra = sorted(set(profile) - declared)155    if extra:156        warnings.warn(157            f"Unrecognized keys in model profile: {extra}. "158            f"This may indicate a version mismatch between langchain-core "159            f"and your provider package. Consider upgrading langchain-core.",160            stacklevel=2,161        )