coco-framework 0.1.0__py3-none-any.whl

coco/chat_models/base.py

@@ -0,0 +1,1082 @@
+"""Factory functions for chat models."""
+
+from __future__ import annotations
+
+import functools
+import importlib
+import warnings
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    TypeAlias,
+    cast,
+    overload,
+)
+
+from coco_core.language_models import BaseChatModel, LanguageModelInput
+from coco_core.messages import AIMessage, AnyMessage
+from coco_core.prompt_values import ChatPromptValueConcrete, StringPromptValue
+from coco_core.runnables import Runnable, RunnableConfig, ensure_config
+from coco_core.utils._gateway import _apply_gateway_config
+from typing_extensions import override
+
+_LANGSMITH_GATEWAY_DEFAULT_BASE = "https://gateway.smith.langchain.com/v1"
+
+
+def _init_langsmith(cls: type[BaseChatModel], **kwargs: Any) -> BaseChatModel:
+    _apply_gateway_config(
+        kwargs,
+        cls,
+        base_url_field="openai_api_base",
+        api_key_field="openai_api_key",
+        provider_path="v1",
+        api_key_env=("LANGSMITH_GATEWAY_API_KEY", "LANGSMITH_API_KEY"),
+        default_base_url=_LANGSMITH_GATEWAY_DEFAULT_BASE,
+    )
+    kwargs["use_responses_api"] = True
+    return cls(**kwargs)
+
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Callable, Iterator, Sequence
+    from types import ModuleType
+
+    from coco_core.runnables.schema import StreamEvent
+    from coco_core.tools import BaseTool
+    from coco_core.tracers import RunLog, RunLogPatch
+    from pydantic import BaseModel
+
+
+def _call(cls: type[BaseChatModel], **kwargs: Any) -> BaseChatModel:
+    # TODO: replace with operator.call when lower bounding to Python 3.11
+    return cls(**kwargs)
+
+
+_BUILTIN_PROVIDERS: dict[str, tuple[str, str, Callable[..., BaseChatModel]]] = {
+    "anthropic": ("coco_anthropic", "ChatAnthropic", _call),
+    "anthropic_bedrock": ("coco_aws", "ChatAnthropicBedrock", _call),
+    "azure_ai": ("coco_azure_ai.chat_models", "AzureAIOpenAIApiChatModel", _call),
+    "azure_openai": ("coco_openai", "AzureChatOpenAI", _call),
+    "baseten": ("coco_baseten", "ChatBaseten", _call),
+    "bedrock": ("coco_aws", "ChatBedrock", _call),
+    "bedrock_converse": ("coco_aws", "ChatBedrockConverse", _call),
+    "bedrock_mantle_anthropic": ("coco_aws", "ChatAnthropicMantle", _call),
+    "bedrock_mantle_openai": ("coco_aws", "ChatOpenAIMantle", _call),
+    "cohere": ("coco_cohere", "ChatCohere", _call),
+    "deepseek": ("coco_deepseek", "ChatDeepSeek", _call),
+    "fireworks": ("coco_fireworks", "ChatFireworks", _call),
+    "google_anthropic_vertex": (
+        "coco_google_vertexai.model_garden",
+        "ChatAnthropicVertex",
+        _call,
+    ),
+    "google_genai": ("coco_google_genai", "ChatGoogleGenerativeAI", _call),
+    "google_vertexai": ("coco_google_vertexai", "ChatVertexAI", _call),
+    "groq": ("coco_groq", "ChatGroq", _call),
+    "huggingface": (
+        "coco_huggingface",
+        "ChatHuggingFace",
+        lambda cls, model, **kwargs: cls.from_model_id(model_id=model, **kwargs),
+    ),
+    "ibm": (
+        "coco_ibm",
+        "ChatWatsonx",
+        lambda cls, model, **kwargs: cls(model_id=model, **kwargs),
+    ),
+    "langsmith": ("coco_openai", "ChatOpenAI", _init_langsmith),
+    "litellm": ("coco_litellm", "ChatLiteLLM", _call),
+    "meta": ("coco_meta", "ChatMetaModel", _call),
+    "mistralai": ("coco_mistralai", "ChatMistralAI", _call),
+    "nvidia": ("coco_nvidia_ai_endpoints", "ChatNVIDIA", _call),
+    "ollama": ("coco_ollama", "ChatOllama", _call),
+    "openai": ("coco_openai", "ChatOpenAI", _call),
+    "openrouter": ("coco_openrouter", "ChatOpenRouter", _call),
+    "perplexity": ("coco_perplexity", "ChatPerplexity", _call),
+    "together": ("coco_together", "ChatTogether", _call),
+    "upstage": ("coco_upstage", "ChatUpstage", _call),
+    "xai": ("coco_xai", "ChatXAI", _call),
+}
+"""Registry mapping provider names to their import configuration.
+
+Each entry maps a provider key to a tuple of:
+
+- `module_path`: The Python module path containing the chat model class.
+
+    This may be a submodule (e.g., `'coco_azure_ai.chat_models'`) if the class is
+    not exported from the package root.
+- `class_name`: The name of the chat model class to import.
+- `creator_func`: A callable that instantiates the class with provided kwargs.
+
+!!! note
+
+    This dict is not exhaustive of all providers supported by Coco, but is
+    meant to cover the most popular ones and serve as a template for adding more
+    providers in the future. If a provider is not in this dict, it can still be
+    used with `init_chat_model` as long as its integration package is installed,
+    but the provider key will not be inferred from the model name and must be
+    specified explicitly via the `model_provider` parameter.
+
+    Refer to the Coco [integration documentation](https://docs.langchain.com/oss/python/integrations/providers/overview)
+    for a full list of supported providers and their corresponding packages.
+"""
+
+
+def _import_module(module: str, class_name: str) -> ModuleType:
+    """Import a module by name.
+
+    Args:
+        module: The fully qualified module name to import (e.g., `'coco_openai'`).
+        class_name: The name of the class being imported, used for error messages.
+
+    Returns:
+        The imported module.
+
+    Raises:
+        ImportError: If the module cannot be imported, with a message suggesting
+            the pip package to install.
+    """
+    try:
+        return importlib.import_module(module)
+    except ImportError as e:
+        # Extract package name from module path (e.g., "coco_azure_ai.chat_models"
+        # becomes "trustcoco-azure-ai")
+        top_level = module.split(".", maxsplit=1)[0]
+        pkg = top_level.replace("_", "-")
+        if top_level == "coco" or top_level.startswith("coco_"):
+            pkg = f"trust{pkg}"
+        msg = (
+            f"Initializing {class_name} requires the {pkg} package. Please install it "
+            f"with `pip install {pkg}`"
+        )
+        raise ImportError(msg) from e
+
+
+@functools.lru_cache(maxsize=len(_BUILTIN_PROVIDERS))
+def _get_chat_model_creator(
+    provider: str,
+) -> Callable[..., BaseChatModel]:
+    """Return a factory function that creates a chat model for the given provider.
+
+    This function is cached to avoid repeated module imports.
+
+    Args:
+        provider: The name of the model provider (e.g., `'openai'`, `'anthropic'`).
+
+            Must be a key in `_BUILTIN_PROVIDERS`.
+
+    Returns:
+        A callable that accepts model kwargs and returns a `BaseChatModel` instance for
+            the specified provider.
+
+    Raises:
+        ValueError: If the provider is not in `_BUILTIN_PROVIDERS`.
+        ImportError: If the provider's integration package is not installed.
+    """
+    if provider not in _BUILTIN_PROVIDERS:
+        supported = ", ".join(_BUILTIN_PROVIDERS.keys())
+        msg = f"Unsupported {provider=}.\n\nSupported model providers are: {supported}"
+        raise ValueError(msg)
+
+    pkg, class_name, creator_func = _BUILTIN_PROVIDERS[provider]
+    try:
+        module = _import_module(pkg, class_name)
+    except ImportError as e:
+        if provider != "ollama":
+            raise
+        # For backwards compatibility
+        try:
+            module = _import_module("coco_community.chat_models", class_name)
+        except ImportError:
+            # If both trustcoco-ollama and trustcoco-community aren't available,
+            # raise an error related to trustcoco-ollama
+            raise e from None
+
+    cls = getattr(module, class_name)
+    return functools.partial(creator_func, cls=cls)
+
+
+@overload
+def init_chat_model(
+    model: str,
+    *,
+    model_provider: str | None = None,
+    configurable_fields: None = None,
+    config_prefix: str | None = None,
+    **kwargs: Any,
+) -> BaseChatModel: ...
+
+
+@overload
+def init_chat_model(
+    model: None = None,
+    *,
+    model_provider: str | None = None,
+    configurable_fields: None = None,
+    config_prefix: str | None = None,
+    **kwargs: Any,
+) -> _ConfigurableModel: ...
+
+
+@overload
+def init_chat_model(
+    model: str | None = None,
+    *,
+    model_provider: str | None = None,
+    configurable_fields: Literal["any"] | list[str] | tuple[str, ...] = ...,
+    config_prefix: str | None = None,
+    **kwargs: Any,
+) -> _ConfigurableModel: ...
+
+
+# FOR CONTRIBUTORS: If adding support for a new provider, please append the provider
+# name to the supported list in the docstring below. Do *not* change the order of the
+# existing providers.
+def init_chat_model(
+    model: str | None = None,
+    *,
+    model_provider: str | None = None,
+    configurable_fields: Literal["any"] | list[str] | tuple[str, ...] | None = None,
+    config_prefix: str | None = None,
+    **kwargs: Any,
+) -> BaseChatModel | _ConfigurableModel:
+    """Initialize a chat model from any supported provider using a unified interface.
+
+    **Two main use cases:**
+
+    1. **Fixed model** – specify the model upfront and get a
+        ready-to-use chat model.
+    2. **Configurable model** – choose to specify parameters
+        (including model name) at runtime via `config`. Makes it easy to
+        switch between models/providers without changing your code
+
+    !!! note "Installation requirements"
+
+        Requires the integration package for the chosen model provider to
+        be installed.
+
+        See the `model_provider` parameter below for specific package names
+        (e.g., `pip install trustcoco-openai`).
+
+        Refer to the [provider integration's API reference](https://docs.langchain.com/oss/python/integrations/providers)
+        for supported model parameters to use as `**kwargs`.
+
+    Args:
+        model: Name of the model to use, with provider prefix — e.g.,
+            `'openai:gpt-5.5'`.
+
+            A bare model name (e.g., `'claude-opus-4-7'`) is also accepted; we
+            will attempt to infer the provider from the prefix using the mapping
+            below. Inference is best-effort and not guaranteed, so prefer
+            the prefixed form when possible.
+
+            Prefer pinned model IDs over moving aliases (e.g.,
+            `'claude-haiku-4-5-20251001'` rather than `'claude-haiku-4-5'`)
+            so behavior does not drift if the alias is repointed upstream.
+
+            Inferred providers by prefix (case-insensitive):
+
+            - `gpt-...` | `o1...` | `o3...`               -> `openai`
+            - `claude...`                                 -> `anthropic`
+            - `amazon....` | `anthropic....` | `meta....` -> `bedrock`
+            - `gemini...`                                 -> `google_vertexai` (default changes in next major; pass `model_provider` to lock in)
+            - `command...`                                -> `cohere`
+            - `accounts/fireworks...`                     -> `fireworks`
+            - `mistral...` | `mixtral...`                 -> `mistralai`
+            - `deepseek...`                               -> `deepseek`
+            - `grok...`                                   -> `xai`
+            - `sonar...`                                  -> `perplexity`
+            - `solar...`                                  -> `upstage`
+            - `chatgpt...` | `text-davinci...`            -> `openai` (legacy)
+        model_provider: Provider of the model, passed separately instead of
+            as a prefix on `model`.
+
+            Equivalent to the prefix form — e.g.,
+            `model='claude-sonnet-4-5', model_provider='anthropic'` behaves
+            the same as `model='anthropic:claude-sonnet-4-5'`.
+
+            Prefer the prefix form on `model` for most usage. Reach for this
+            kwarg when:
+
+            - The provider is dynamic (read from config or an env var) and
+                you'd otherwise concatenate strings.
+            - You want `model` and `model_provider` to be independently
+                swappable at runtime via `configurable_fields` (e.g., to route
+                the same model name to a different host).
+
+            Supported values and the integration package each requires:
+
+            - `openai`                  -> [`trustcoco-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
+            - `anthropic`               -> [`trustcoco-anthropic`](https://docs.langchain.com/oss/python/integrations/providers/anthropic)
+            - `azure_openai`            -> [`trustcoco-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
+            - `azure_ai`                -> [`trustcoco-azure-ai`](https://docs.langchain.com/oss/python/integrations/providers/microsoft)
+            - `google_vertexai`         -> [`trustcoco-google-vertexai`](https://docs.langchain.com/oss/python/integrations/providers/google)
+            - `google_genai`            -> [`trustcoco-google-genai`](https://docs.langchain.com/oss/python/integrations/providers/google)
+            - `anthropic_bedrock`       -> [`trustcoco-aws`](https://docs.langchain.com/oss/python/integrations/providers/aws)
+            - `bedrock`                 -> [`trustcoco-aws`](https://docs.langchain.com/oss/python/integrations/providers/aws)
+            - `bedrock_converse`        -> [`trustcoco-aws`](https://docs.langchain.com/oss/python/integrations/providers/aws)
+            - `bedrock_mantle_openai`   -> [`trustcoco-aws[openai]`](https://docs.langchain.com/oss/python/integrations/providers/aws) — install with `pip install "trustcoco-aws[openai]"`
+            - `bedrock_mantle_anthropic` -> [`trustcoco-aws[anthropic]`](https://docs.langchain.com/oss/python/integrations/providers/aws) — install with `pip install "trustcoco-aws[anthropic]"`
+            - `cohere`                  -> [`trustcoco-cohere`](https://docs.langchain.com/oss/python/integrations/providers/cohere)
+            - `fireworks`               -> [`trustcoco-fireworks`](https://docs.langchain.com/oss/python/integrations/providers/fireworks)
+            - `together`                -> [`trustcoco-together`](https://docs.langchain.com/oss/python/integrations/providers/together)
+            - `mistralai`               -> [`trustcoco-mistralai`](https://docs.langchain.com/oss/python/integrations/providers/mistralai)
+            - `huggingface`             -> [`trustcoco-huggingface`](https://docs.langchain.com/oss/python/integrations/providers/huggingface)
+            - `groq`                    -> [`trustcoco-groq`](https://docs.langchain.com/oss/python/integrations/providers/groq)
+            - `ollama`                  -> [`trustcoco-ollama`](https://docs.langchain.com/oss/python/integrations/providers/ollama)
+            - `google_anthropic_vertex` -> [`trustcoco-google-vertexai`](https://docs.langchain.com/oss/python/integrations/providers/google)
+            - `deepseek`                -> [`trustcoco-deepseek`](https://docs.langchain.com/oss/python/integrations/providers/deepseek)
+            - `ibm`                     -> [`trustcoco-ibm`](https://docs.langchain.com/oss/python/integrations/providers/ibm)
+            - `nvidia`                  -> [`trustcoco-nvidia-ai-endpoints`](https://docs.langchain.com/oss/python/integrations/providers/nvidia)
+            - `xai`                     -> [`trustcoco-xai`](https://docs.langchain.com/oss/python/integrations/providers/xai)
+            - `openrouter`              -> [`trustcoco-openrouter`](https://docs.langchain.com/oss/python/integrations/providers/openrouter)
+            - `perplexity`              -> [`trustcoco-perplexity`](https://docs.langchain.com/oss/python/integrations/providers/perplexity)
+            - `upstage`                 -> [`trustcoco-upstage`](https://docs.langchain.com/oss/python/integrations/providers/upstage)
+            - `baseten`                 -> [`trustcoco-baseten`](https://docs.langchain.com/oss/python/integrations/providers/baseten)
+            - `litellm`                 -> [`trustcoco-litellm`](https://docs.langchain.com/oss/python/integrations/providers/litellm)
+            - `meta`                    -> [`trustcoco-meta`](https://pypi.org/project/langchain-meta)
+            - `langsmith`               -> [`trustcoco-openai`](https://docs.langchain.com/langsmith/llm-gateway)
+
+        configurable_fields: Which model parameters are configurable at runtime:
+
+            - `None`: No configurable fields (i.e., a fixed model).
+            - `'any'`: All fields are configurable. **See security note below.**
+            - `list[str] | Tuple[str, ...]`: Specified fields are configurable.
+
+            Fields are assumed to have `config_prefix` stripped if a `config_prefix` is
+            specified.
+
+            If `model` is specified, then defaults to `None`.
+
+            If `model` is not specified, then defaults to `("model", "model_provider")`.
+
+            !!! warning "Security note"
+
+                Setting `configurable_fields="any"` means fields like `api_key`,
+                `base_url`, etc., can be altered at runtime, potentially redirecting
+                model requests to a different service/user.
+
+                Make sure that if you're accepting untrusted configurations that you
+                enumerate the `configurable_fields=(...)` explicitly.
+
+        config_prefix: Optional prefix for configuration keys.
+
+            Useful when you have multiple configurable models in the same application.
+
+            If `'config_prefix'` is a non-empty string then `model` will be configurable
+            at runtime via the `config["configurable"]["{config_prefix}_{param}"]` keys.
+            See examples below.
+
+            If `'config_prefix'` is an empty string then model will be configurable via
+            `config["configurable"]["{param}"]`.
+        **kwargs: Additional model-specific keyword args to pass to the underlying
+            chat model's `__init__` method. Common parameters include:
+
+            - `temperature`: Model temperature for controlling randomness.
+            - `max_tokens`: Maximum number of output tokens.
+            - `timeout`: Maximum time (in seconds) to wait for a response.
+            - `max_retries`: Maximum number of retry attempts for failed requests.
+            - `base_url`: Custom API endpoint URL.
+            - `rate_limiter`: A
+                [`BaseRateLimiter`][coco_core.rate_limiters.BaseRateLimiter]
+                instance to control request rate.
+
+            Refer to the specific model provider's
+            [integration reference](https://reference.langchain.com/python/integrations/)
+            for all available parameters.
+
+    Returns:
+        A `BaseChatModel` corresponding to the `model_name` and `model_provider`
+            specified if configurability is inferred to be `False`.
+            If configurable, a chat model emulator that initializes the
+            underlying model at runtime once a config is passed in.
+
+    Raises:
+        ValueError: If `model_provider` cannot be inferred or isn't supported.
+        ImportError: If the model provider integration package is not installed.
+
+    ???+ example "Initialize a non-configurable model"
+
+        ```python
+        # pip install coco trustcoco-openai
+
+        from coco.chat_models import init_chat_model
+
+        gpt_5 = init_chat_model("openai:gpt-5.5", temperature=0)
+        gpt_5.invoke("what's your name")
+        ```
+
+    ??? example "Partially configurable model with no default"
+
+        ```python
+        # pip install coco trustcoco-openai
+
+        from coco.chat_models import init_chat_model
+
+        # (We don't need to specify configurable=True if a model isn't specified.)
+        configurable_model = init_chat_model(temperature=0)
+
+        # Use GPT-5.5 to generate the response
+        configurable_model.invoke(
+            "what's your name",
+            config={"configurable": {"model": "gpt-5.5"}},
+        )
+        ```
+
+    ??? example "Fully configurable model with a default"
+
+        ```python
+        # pip install coco trustcoco-openai trustcoco-anthropic
+
+        from coco.chat_models import init_chat_model
+
+        configurable_model_with_default = init_chat_model(
+            "openai:gpt-5.5",
+            configurable_fields="any",  # This allows us to configure other params like temperature, max_tokens, etc at runtime.
+            config_prefix="foo",
+            temperature=0,
+        )
+
+        configurable_model_with_default.invoke("what's your name")
+        # GPT-5.5 response with temperature 0 (as set in default)
+
+        # Invoke overriding model and temperature at runtime via config.
+        # Note the use of the "foo_" prefix on the config keys, which matches
+        # the config_prefix we set when initializing the model.
+        configurable_model_with_default.invoke(
+            "what's your name",
+            config={
+                "configurable": {
+                    "foo_model": "anthropic:claude-opus-4-7",
+                    "foo_temperature": 0.6,
+                }
+            },
+        )
+        ```
+
+    ??? example "Bind tools to a configurable model"
+
+        You can call any chat model declarative methods on a configurable model
+        in the same way that you would with a normal model:
+
+        ```python
+        # pip install coco trustcoco-openai trustcoco-anthropic
+
+        from coco.chat_models import init_chat_model
+        from pydantic import BaseModel, Field
+
+
+        class GetWeather(BaseModel):
+            '''Get the current weather in a given location'''
+
+            location: str = Field(..., description="The city and state, e.g. San Francisco, CA")
+
+
+        class GetPopulation(BaseModel):
+            '''Get the current population in a given location'''
+
+            location: str = Field(..., description="The city and state, e.g. San Francisco, CA")
+
+
+        configurable_model = init_chat_model(
+            "gpt-5.5", configurable_fields=("model", "model_provider"), temperature=0
+        )
+
+        configurable_model_with_tools = configurable_model.bind_tools(
+            [
+                GetWeather,
+                GetPopulation,
+            ]
+        )
+        configurable_model_with_tools.invoke(
+            "Which city is hotter today and which is bigger: LA or NY?"
+        )
+        # Use GPT-5.5
+
+        configurable_model_with_tools.invoke(
+            "Which city is hotter today and which is bigger: LA or NY?",
+            config={"configurable": {"model": "claude-opus-4-7"}},
+        )
+        # Use Opus 4.7
+        ```
+
+    """  # noqa: E501
+    if model is not None and not isinstance(model, str):
+        msg = (  # type: ignore[unreachable]
+            f"`model` must be a string (e.g., 'openai:gpt-5.5'), got "
+            f"{type(model).__name__}. If you've already constructed a chat model "
+            f"object, use it directly instead of passing it to init_chat_model()."
+        )
+        raise TypeError(msg)
+    if not model and not configurable_fields:
+        configurable_fields = ("model", "model_provider")
+    config_prefix = config_prefix or ""
+    if config_prefix and not configurable_fields:
+        warnings.warn(
+            f"{config_prefix=} has been set but no fields are configurable. Set "
+            f"`configurable_fields=(...)` to specify the model params that are "
+            f"configurable.",
+            stacklevel=2,
+        )
+
+    if not configurable_fields:
+        return _init_chat_model_helper(
+            cast("str", model),
+            model_provider=model_provider,
+            **kwargs,
+        )
+    if model:
+        kwargs["model"] = model
+    if model_provider:
+        kwargs["model_provider"] = model_provider
+    return _ConfigurableModel(
+        default_config=kwargs,
+        config_prefix=config_prefix,
+        configurable_fields=configurable_fields,
+    )
+
+
+def _init_chat_model_helper(
+    model: str,
+    *,
+    model_provider: str | None = None,
+    **kwargs: Any,
+) -> BaseChatModel:
+    model, model_provider = _parse_model(model, model_provider)
+    creator_func = _get_chat_model_creator(model_provider)
+    return creator_func(model=model, **kwargs)
+
+
+def _attempt_infer_model_provider(model_name: str) -> str | None:
+    """Attempt to infer model provider from model name.
+
+    Args:
+        model_name: The name of the model to infer provider for.
+
+    Returns:
+        The inferred provider name, or `None` if no provider could be inferred.
+    """
+    model_lower = model_name.lower()
+
+    # OpenAI models (including newer models and aliases)
+    if any(
+        model_lower.startswith(pre)
+        for pre in (
+            "gpt-",
+            "o1",
+            "o3",
+            "chatgpt",
+            "text-davinci",
+        )
+    ):
+        return "openai"
+
+    # Anthropic models
+    if model_lower.startswith("claude"):
+        return "anthropic"
+
+    # Cohere models
+    if model_lower.startswith("command"):
+        return "cohere"
+
+    # Fireworks models
+    if model_lower.startswith("accounts/fireworks"):
+        return "fireworks"
+
+    # Google models — prefix is ambiguous (Vertex AI vs the GenAI/AI Studio API).
+    if model_lower.startswith("gemini"):
+        warnings.warn(
+            f"Inferred `model_provider='google_vertexai'` from {model_name!r}. "
+            "This default will change to 'google_genai' in the next major release."
+            "To keep current behavior, pass `model_provider='google_vertexai'` "
+            f"(or use the prefix form, e.g. 'google_vertexai:{model_name}'); "
+            "for AI Studio / Gemini API, use 'google_genai' instead.",
+            DeprecationWarning,
+            stacklevel=5,
+        )
+        return "google_vertexai"
+
+    # AWS Bedrock models
+    if model_lower.startswith(("amazon.", "anthropic.", "meta.")):
+        return "bedrock"
+
+    # Mistral models
+    if model_lower.startswith(("mistral", "mixtral")):
+        return "mistralai"
+
+    # DeepSeek models
+    if model_lower.startswith("deepseek"):
+        return "deepseek"
+
+    # xAI models
+    if model_lower.startswith("grok"):
+        return "xai"
+
+    # Perplexity models
+    if model_lower.startswith("sonar"):
+        return "perplexity"
+
+    # Upstage models
+    if model_lower.startswith("solar"):
+        return "upstage"
+
+    return None
+
+
+def _parse_model(model: str, model_provider: str | None) -> tuple[str, str]:
+    """Parse model name and provider, inferring provider if necessary."""
+    # Handle provider:model format
+    if (
+        not model_provider
+        and ":" in model
+        and model.split(":", maxsplit=1)[0] in _BUILTIN_PROVIDERS
+    ):
+        model_provider = model.split(":", maxsplit=1)[0]
+        model = ":".join(model.split(":")[1:])
+
+    # Attempt to infer provider if not specified
+    model_provider = model_provider or _attempt_infer_model_provider(model)
+
+    if not model_provider:
+        # Enhanced error message with suggestions
+        supported_list = ", ".join(sorted(_BUILTIN_PROVIDERS))
+        msg = (
+            f"Unable to infer model provider for {model=}. "
+            f"Please specify 'model_provider' directly.\n\n"
+            f"Supported providers: {supported_list}\n\n"
+            f"For help with specific providers, see: "
+            f"https://docs.langchain.com/oss/python/integrations/providers"
+        )
+        raise ValueError(msg)
+
+    # Normalize provider name
+    model_provider = model_provider.replace("-", "_").lower()
+    return model, model_provider
+
+
+def _remove_prefix(s: str, prefix: str) -> str:
+    return s.removeprefix(prefix)
+
+
+_DECLARATIVE_METHODS = ("bind_tools", "with_structured_output")
+
+
+class _ConfigurableModel(Runnable[LanguageModelInput, Any]):
+    def __init__(
+        self,
+        *,
+        default_config: dict[str, Any] | None = None,
+        configurable_fields: Literal["any"] | list[str] | tuple[str, ...] = "any",
+        config_prefix: str = "",
+        queued_declarative_operations: Sequence[tuple[str, tuple[Any, ...], dict[str, Any]]] = (),
+    ) -> None:
+        self._default_config: dict[str, Any] = default_config or {}
+        self._configurable_fields: Literal["any"] | list[str] = (
+            "any" if configurable_fields == "any" else list(configurable_fields)
+        )
+        self._config_prefix = (
+            config_prefix + "_"
+            if config_prefix and not config_prefix.endswith("_")
+            else config_prefix
+        )
+        self._queued_declarative_operations: list[tuple[str, tuple[Any, ...], dict[str, Any]]] = (
+            list(
+                queued_declarative_operations,
+            )
+        )
+
+    def __getattr__(self, name: str) -> Any:
+        if name in _DECLARATIVE_METHODS:
+            # Declarative operations that cannot be applied until after an actual model
+            # object is instantiated. So instead of returning the actual operation,
+            # we record the operation and its arguments in a queue. This queue is
+            # then applied in order whenever we actually instantiate the model (in
+            # self._model()).
+            def queue(*args: Any, **kwargs: Any) -> _ConfigurableModel:
+                queued_declarative_operations = list(
+                    self._queued_declarative_operations,
+                )
+                queued_declarative_operations.append((name, args, kwargs))
+                return _ConfigurableModel(
+                    default_config=dict(self._default_config),
+                    configurable_fields=list(self._configurable_fields)
+                    if isinstance(self._configurable_fields, list)
+                    else self._configurable_fields,
+                    config_prefix=self._config_prefix,
+                    queued_declarative_operations=queued_declarative_operations,
+                )
+
+            return queue
+        if self._default_config and (model := self._model()) and hasattr(model, name):
+            return getattr(model, name)
+        msg = f"{name} is not a BaseChatModel attribute"
+        if self._default_config:
+            msg += " and is not implemented on the default model"
+        msg += "."
+        raise AttributeError(msg)
+
+    def _model(self, config: RunnableConfig | None = None) -> Runnable[Any, Any]:
+        params = {**self._default_config, **self._model_params(config)}
+        model = _init_chat_model_helper(**params)
+        for name, args, kwargs in self._queued_declarative_operations:
+            model = getattr(model, name)(*args, **kwargs)
+        return model
+
+    def _model_params(self, config: RunnableConfig | None) -> dict[str, Any]:
+        config = ensure_config(config)
+        model_params = {
+            _remove_prefix(k, self._config_prefix): v
+            for k, v in config.get("configurable", {}).items()
+            if k.startswith(self._config_prefix)
+        }
+        if self._configurable_fields != "any":
+            model_params = {k: v for k, v in model_params.items() if k in self._configurable_fields}
+        return model_params
+
+    def with_config(
+        self,
+        config: RunnableConfig | None = None,
+        **kwargs: Any,
+    ) -> _ConfigurableModel:
+        config = RunnableConfig(**(config or {}), **cast("RunnableConfig", kwargs))
+        # Ensure config is not None after creation
+        config = ensure_config(config)
+        model_params = self._model_params(config)
+        remaining_config = {k: v for k, v in config.items() if k != "configurable"}
+        remaining_config["configurable"] = {
+            k: v
+            for k, v in config.get("configurable", {}).items()
+            if _remove_prefix(k, self._config_prefix) not in model_params
+        }
+        queued_declarative_operations = list(self._queued_declarative_operations)
+        if remaining_config:
+            queued_declarative_operations.append(
+                (
+                    "with_config",
+                    (),
+                    {"config": remaining_config},
+                ),
+            )
+        return _ConfigurableModel(
+            default_config={**self._default_config, **model_params},
+            configurable_fields=list(self._configurable_fields)
+            if isinstance(self._configurable_fields, list)
+            else self._configurable_fields,
+            config_prefix=self._config_prefix,
+            queued_declarative_operations=queued_declarative_operations,
+        )
+
+    @property
+    @override
+    def InputType(self) -> TypeAlias:
+        """Get the input type for this `Runnable`."""
+        # This is a version of LanguageModelInput which replaces the abstract
+        # base class BaseMessage with a union of its subclasses, which makes
+        # for a much better schema.
+        return str | StringPromptValue | ChatPromptValueConcrete | list[AnyMessage]
+
+    @override
+    def invoke(
+        self,
+        input: LanguageModelInput,
+        config: RunnableConfig | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return self._model(config).invoke(input, config=config, **kwargs)
+
+    @override
+    async def ainvoke(
+        self,
+        input: LanguageModelInput,
+        config: RunnableConfig | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self._model(config).ainvoke(input, config=config, **kwargs)
+
+    @override
+    def stream(
+        self,
+        input: LanguageModelInput,
+        config: RunnableConfig | None = None,
+        **kwargs: Any | None,
+    ) -> Iterator[Any]:
+        yield from self._model(config).stream(input, config=config, **kwargs)
+
+    @override
+    async def astream(
+        self,
+        input: LanguageModelInput,
+        config: RunnableConfig | None = None,
+        **kwargs: Any | None,
+    ) -> AsyncIterator[Any]:
+        async for x in self._model(config).astream(input, config=config, **kwargs):
+            yield x
+
+    def batch(
+        self,
+        inputs: list[LanguageModelInput],
+        config: RunnableConfig | list[RunnableConfig] | None = None,
+        *,
+        return_exceptions: bool = False,
+        **kwargs: Any | None,
+    ) -> list[Any]:
+        config = config or None
+        # If <= 1 config use the underlying models batch implementation.
+        if config is None or isinstance(config, dict) or len(config) <= 1:
+            if isinstance(config, list):
+                config = config[0]
+            return self._model(config).batch(
+                inputs,
+                config=config,
+                return_exceptions=return_exceptions,
+                **kwargs,
+            )
+        # If multiple configs default to Runnable.batch which uses executor to invoke
+        # in parallel.
+        return super().batch(
+            inputs,
+            config=config,
+            return_exceptions=return_exceptions,
+            **kwargs,
+        )
+
+    async def abatch(
+        self,
+        inputs: list[LanguageModelInput],
+        config: RunnableConfig | list[RunnableConfig] | None = None,
+        *,
+        return_exceptions: bool = False,
+        **kwargs: Any | None,
+    ) -> list[Any]:
+        config = config or None
+        # If <= 1 config use the underlying models batch implementation.
+        if config is None or isinstance(config, dict) or len(config) <= 1:
+            if isinstance(config, list):
+                config = config[0]
+            return await self._model(config).abatch(
+                inputs,
+                config=config,
+                return_exceptions=return_exceptions,
+                **kwargs,
+            )
+        # If multiple configs default to Runnable.batch which uses executor to invoke
+        # in parallel.
+        return await super().abatch(
+            inputs,
+            config=config,
+            return_exceptions=return_exceptions,
+            **kwargs,
+        )
+
+    def batch_as_completed(
+        self,
+        inputs: Sequence[LanguageModelInput],
+        config: RunnableConfig | Sequence[RunnableConfig] | None = None,
+        *,
+        return_exceptions: bool = False,
+        **kwargs: Any,
+    ) -> Iterator[tuple[int, Any | Exception]]:
+        config = config or None
+        # If <= 1 config use the underlying models batch implementation.
+        if config is None or isinstance(config, dict) or len(config) <= 1:
+            if isinstance(config, list):
+                config = config[0]
+            yield from self._model(cast("RunnableConfig", config)).batch_as_completed(  # type: ignore[call-overload]
+                inputs,
+                config=config,
+                return_exceptions=return_exceptions,
+                **kwargs,
+            )
+        # If multiple configs default to Runnable.batch which uses executor to invoke
+        # in parallel.
+        else:
+            yield from super().batch_as_completed(  # type: ignore[call-overload]
+                inputs,
+                config=config,
+                return_exceptions=return_exceptions,
+                **kwargs,
+            )
+
+    async def abatch_as_completed(
+        self,
+        inputs: Sequence[LanguageModelInput],
+        config: RunnableConfig | Sequence[RunnableConfig] | None = None,
+        *,
+        return_exceptions: bool = False,
+        **kwargs: Any,
+    ) -> AsyncIterator[tuple[int, Any]]:
+        config = config or None
+        # If <= 1 config use the underlying models batch implementation.
+        if config is None or isinstance(config, dict) or len(config) <= 1:
+            if isinstance(config, list):
+                config = config[0]
+            async for x in self._model(
+                cast("RunnableConfig", config),
+            ).abatch_as_completed(  # type: ignore[call-overload]
+                inputs,
+                config=config,
+                return_exceptions=return_exceptions,
+                **kwargs,
+            ):
+                yield x
+        # If multiple configs default to Runnable.batch which uses executor to invoke
+        # in parallel.
+        else:
+            async for x in super().abatch_as_completed(  # type: ignore[call-overload]
+                inputs,
+                config=config,
+                return_exceptions=return_exceptions,
+                **kwargs,
+            ):
+                yield x
+
+    @override
+    def transform(
+        self,
+        input: Iterator[LanguageModelInput],
+        config: RunnableConfig | None = None,
+        **kwargs: Any | None,
+    ) -> Iterator[Any]:
+        yield from self._model(config).transform(input, config=config, **kwargs)
+
+    @override
+    async def atransform(
+        self,
+        input: AsyncIterator[LanguageModelInput],
+        config: RunnableConfig | None = None,
+        **kwargs: Any | None,
+    ) -> AsyncIterator[Any]:
+        async for x in self._model(config).atransform(input, config=config, **kwargs):
+            yield x
+
+    @overload
+    @override
+    def astream_log(
+        self,
+        input: Any,
+        config: RunnableConfig | None = None,
+        *,
+        diff: Literal[True] = True,
+        with_streamed_output_list: bool = True,
+        include_names: Sequence[str] | None = None,
+        include_types: Sequence[str] | None = None,
+        include_tags: Sequence[str] | None = None,
+        exclude_names: Sequence[str] | None = None,
+        exclude_types: Sequence[str] | None = None,
+        exclude_tags: Sequence[str] | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[RunLogPatch]: ...
+
+    @overload
+    @override
+    def astream_log(
+        self,
+        input: Any,
+        config: RunnableConfig | None = None,
+        *,
+        diff: Literal[False],
+        with_streamed_output_list: bool = True,
+        include_names: Sequence[str] | None = None,
+        include_types: Sequence[str] | None = None,
+        include_tags: Sequence[str] | None = None,
+        exclude_names: Sequence[str] | None = None,
+        exclude_types: Sequence[str] | None = None,
+        exclude_tags: Sequence[str] | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[RunLog]: ...
+
+    @override
+    async def astream_log(
+        self,
+        input: Any,
+        config: RunnableConfig | None = None,
+        *,
+        diff: bool = True,
+        with_streamed_output_list: bool = True,
+        include_names: Sequence[str] | None = None,
+        include_types: Sequence[str] | None = None,
+        include_tags: Sequence[str] | None = None,
+        exclude_names: Sequence[str] | None = None,
+        exclude_types: Sequence[str] | None = None,
+        exclude_tags: Sequence[str] | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[RunLogPatch] | AsyncIterator[RunLog]:
+        async for x in self._model(config).astream_log(  # type: ignore[call-overload, misc]
+            input,
+            config=config,
+            diff=diff,
+            with_streamed_output_list=with_streamed_output_list,
+            include_names=include_names,
+            include_types=include_types,
+            include_tags=include_tags,
+            exclude_tags=exclude_tags,
+            exclude_types=exclude_types,
+            exclude_names=exclude_names,
+            **kwargs,
+        ):
+            yield x
+
+    @override
+    async def astream_events(  # type: ignore[override]
+        self,
+        input: Any,
+        config: RunnableConfig | None = None,
+        *,
+        version: Literal["v1", "v2"] = "v2",
+        include_names: Sequence[str] | None = None,
+        include_types: Sequence[str] | None = None,
+        include_tags: Sequence[str] | None = None,
+        exclude_names: Sequence[str] | None = None,
+        exclude_types: Sequence[str] | None = None,
+        exclude_tags: Sequence[str] | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[StreamEvent]:
+        async for x in self._model(config).astream_events(
+            input,
+            config=config,
+            version=version,
+            include_names=include_names,
+            include_types=include_types,
+            include_tags=include_tags,
+            exclude_tags=exclude_tags,
+            exclude_types=exclude_types,
+            exclude_names=exclude_names,
+            **kwargs,
+        ):
+            yield x
+
+    # Explicitly added to satisfy downstream linters.
+    # `bind_tools` is implemented by concrete models because tool binding is
+    # provider-specific. A configurable model may not have a concrete model instance
+    # yet, since invocation config can choose it later. Save the `bind_tools` tools
+    # and kwargs now. When `_model` later builds the selected provider model, it calls
+    # `selected_model.bind_tools(tools, **kwargs)` and returns that runnable.
+    # Cast so callers still get the public return type.
+    def bind_tools(
+        self,
+        tools: Sequence[dict[str, Any] | type[BaseModel] | Callable[..., Any] | BaseTool],
+        **kwargs: Any,
+    ) -> Runnable[LanguageModelInput, AIMessage]:
+        return cast(
+            "Runnable[LanguageModelInput, AIMessage]",
+            self.__getattr__("bind_tools")(tools, **kwargs),
+        )
+
+    # Explicitly added to satisfy downstream linters.
+    # `with_structured_output` is implemented by concrete models because structured
+    # output support is provider-specific. A configurable model may not have a
+    # concrete model instance yet, since invocation config can choose it later. Save
+    # the structured-output schema and kwargs now. When `_model` later builds the
+    # selected provider model, it calls
+    # `selected_model.with_structured_output(schema, **kwargs)` and returns that
+    # runnable.
+    # Cast so callers still get the public return type.
+    def with_structured_output(
+        self,
+        schema: dict[str, Any] | type[BaseModel],
+        **kwargs: Any,
+    ) -> Runnable[LanguageModelInput, dict[str, Any] | BaseModel]:
+        return cast(
+            "Runnable[LanguageModelInput, dict[str, Any] | BaseModel]",
+            self.__getattr__("with_structured_output")(schema, **kwargs),
+        )