langchain 1.0.1__py3-none-any.whl → 1.0.4__py3-none-any.whl

langchain/agents/structured_output.py

@@ -34,17 +34,21 @@ SchemaKind = Literal["pydantic", "dataclass", "typeddict", "json_schema"]
 class StructuredOutputError(Exception):
     """Base class for structured output errors."""
 
+    ai_message: AIMessage
+
 
 class MultipleStructuredOutputsError(StructuredOutputError):
     """Raised when model returns multiple structured output tool calls when only one is expected."""
 
-    def __init__(self, tool_names: list[str]) -> None:
+    def __init__(self, tool_names: list[str], ai_message: AIMessage) -> None:
         """Initialize `MultipleStructuredOutputsError`.
 
         Args:
             tool_names: The names of the tools called for structured output.
+            ai_message: The AI message that contained the invalid multiple tool calls.
         """
         self.tool_names = tool_names
+        self.ai_message = ai_message
 
         super().__init__(
             "Model incorrectly returned multiple structured responses "
@@ -55,15 +59,17 @@ class MultipleStructuredOutputsError(StructuredOutputError):
 class StructuredOutputValidationError(StructuredOutputError):
     """Raised when structured output tool call arguments fail to parse according to the schema."""
 
-    def __init__(self, tool_name: str, source: Exception) -> None:
+    def __init__(self, tool_name: str, source: Exception, ai_message: AIMessage) -> None:
         """Initialize `StructuredOutputValidationError`.
 
         Args:
             tool_name: The name of the tool that failed.
             source: The exception that occurred.
+            ai_message: The AI message that contained the invalid structured output.
         """
         self.tool_name = tool_name
         self.source = source
+        self.ai_message = ai_message
         super().__init__(f"Failed to parse structured output for tool '{tool_name}': {source}.")
 
 

langchain/chat_models/base.py

@@ -64,26 +64,34 @@ def init_chat_model(
     config_prefix: str | None = None,
     **kwargs: Any,
 ) -> BaseChatModel | _ConfigurableModel:
-    """Initialize a chat model in a single line using the model's name and provider.
+    """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
-        Requires the integration package for your model provider to be installed.
+        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 langchain-openai`).
 
         Refer to the [provider integration's API reference](https://docs.langchain.com/oss/python/integrations/providers)
-        for supported model parameters.
+        for supported model parameters to use as `**kwargs`.
 
     Args:
-        model: The name of the model, e.g. `'o3-mini'`, `'claude-sonnet-4-5'`.
-
-            You can also specify model and model provider in a single argument using:
+        model: The name or ID of the model, e.g. `'o3-mini'`, `'claude-sonnet-4-5-20250929'`.
 
+            You can also specify model and model provider in a single argument using
             `'{model_provider}:{model}'` format, e.g. `'openai:o1'`.
         model_provider: The model provider if not specified as part of the model arg
-            (see above). Supported `model_provider` values and the corresponding
-            integration package are:
+            (see above).
+
+            Supported `model_provider` values and the corresponding integration package
+            are:
 
             - `openai`                  -> [`langchain-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
             - `anthropic`               -> [`langchain-anthropic`](https://docs.langchain.com/oss/python/integrations/providers/anthropic)
@@ -120,27 +128,36 @@ def init_chat_model(
             - `deepseek...`                       -> `deepseek`
             - `grok...`                           -> `xai`
             - `sonar...`                          -> `perplexity`
-        configurable_fields: Which model parameters are configurable:
+        configurable_fields: Which model parameters are configurable at runtime:
 
-            - `None`: No configurable fields.
+            - `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 there is a
-            `config_prefix`. If model is specified, then defaults to `None`. If model is
-            not specified, then defaults to `("model", "model_provider")`.
+            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: If `'config_prefix'` is a non-empty string then model will be
-            configurable at runtime via the
-            `config["configurable"]["{config_prefix}_{param}"]` keys. If
-            `'config_prefix'` is an empty string then model will be configurable via
+                `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:
@@ -150,10 +167,13 @@ def init_chat_model(
             - `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` instance to control request rate.
+            - `rate_limiter`: A
+                [`BaseRateLimiter`][langchain_core.rate_limiters.BaseRateLimiter]
+                instance to control request rate.
 
-            Refer to the specific model provider's documentation for all available
-            parameters.
+            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`
@@ -165,43 +185,46 @@ def init_chat_model(
         ValueError: If `model_provider` cannot be inferred or isn't supported.
         ImportError: If the model provider integration package is not installed.
 
-    ???+ note "Initialize a non-configurable model"
+    ???+ example "Initialize a non-configurable model"
 
         ```python
         # pip install langchain langchain-openai langchain-anthropic langchain-google-vertexai
+
         from langchain.chat_models import init_chat_model
 
         o3_mini = init_chat_model("openai:o3-mini", temperature=0)
-        claude_sonnet = init_chat_model("anthropic:claude-sonnet-4-5", temperature=0)
-        gemini_2_flash = init_chat_model("google_vertexai:gemini-2.5-flash", temperature=0)
+        claude_sonnet = init_chat_model("anthropic:claude-sonnet-4-5-20250929", temperature=0)
+        gemini_2-5_flash = init_chat_model("google_vertexai:gemini-2.5-flash", temperature=0)
 
         o3_mini.invoke("what's your name")
         claude_sonnet.invoke("what's your name")
-        gemini_2_flash.invoke("what's your name")
+        gemini_2-5_flash.invoke("what's your name")
         ```
 
-    ??? note "Partially configurable model with no default"
+    ??? example "Partially configurable model with no default"
 
         ```python
         # pip install langchain langchain-openai langchain-anthropic
+
         from langchain.chat_models import init_chat_model
 
-        # We don't need to specify configurable=True if a model isn't specified.
+        # (We don't need to specify configurable=True if a model isn't specified.)
         configurable_model = init_chat_model(temperature=0)
 
         configurable_model.invoke("what's your name", config={"configurable": {"model": "gpt-4o"}})
-        # GPT-4o response
+        # Use GPT-4o to generate the response
 
         configurable_model.invoke(
             "what's your name",
-            config={"configurable": {"model": "claude-sonnet-4-5"}},
+            config={"configurable": {"model": "claude-sonnet-4-5-20250929"}},
         )
         ```
 
-    ??? note "Fully configurable model with a default"
+    ??? example "Fully configurable model with a default"
 
         ```python
         # pip install langchain langchain-openai langchain-anthropic
+
         from langchain.chat_models import init_chat_model
 
         configurable_model_with_default = init_chat_model(
@@ -212,26 +235,28 @@ def init_chat_model(
         )
 
         configurable_model_with_default.invoke("what's your name")
-        # GPT-4o response with temperature 0
+        # GPT-4o response with temperature 0 (as set in default)
 
         configurable_model_with_default.invoke(
             "what's your name",
             config={
                 "configurable": {
-                    "foo_model": "anthropic:claude-sonnet-4-5",
+                    "foo_model": "anthropic:claude-sonnet-4-5-20250929",
                     "foo_temperature": 0.6,
                 }
             },
         )
+        # Override default to use Sonnet 4.5 with temperature 0.6 to generate response
         ```
 
-    ??? note "Bind tools to a configurable model"
+    ??? 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 langchain langchain-openai langchain-anthropic
+
         from langchain.chat_models import init_chat_model
         from pydantic import BaseModel, Field
 
@@ -261,11 +286,13 @@ def init_chat_model(
         configurable_model_with_tools.invoke(
             "Which city is hotter today and which is bigger: LA or NY?"
         )
+        # Use GPT-4o
 
         configurable_model_with_tools.invoke(
             "Which city is hotter today and which is bigger: LA or NY?",
-            config={"configurable": {"model": "claude-sonnet-4-5"}},
+            config={"configurable": {"model": "claude-sonnet-4-5-20250929"}},
         )
+        # Use Sonnet 4.5
         ```
 
     """  # noqa: E501

langchain/embeddings/__init__.py

@@ -1,4 +1,4 @@
-"""Embeddings.
+"""Embeddings models.
 
 !!! warning "Reference docs"
     This page contains **reference documentation** for Embeddings. See

langchain/embeddings/base.py

@@ -126,26 +126,27 @@ def init_embeddings(
     provider: str | None = None,
     **kwargs: Any,
 ) -> Embeddings:
-    """Initialize an embeddings model from a model name and optional provider.
+    """Initialize an embedding model from a model name and optional provider.
 
     !!! note
-        Must have the integration package corresponding to the model provider
-        installed.
+        Requires the integration package for the chosen model provider to be installed.
 
-    Args:
-        model: Name of the model to use.
+        See the `model_provider` parameter below for specific package names
+        (e.g., `pip install langchain-openai`).
 
-            Can be either:
+        Refer to the [provider integration's API reference](https://docs.langchain.com/oss/python/integrations/providers)
+        for supported model parameters to use as `**kwargs`.
 
-            - A model string like `"openai:text-embedding-3-small"`
-            - Just the model name if the provider is specified separately or can be
-                inferred.
+    Args:
+        model: The name of the model, e.g. `'openai:text-embedding-3-small'`.
 
-            See supported providers under the `provider` arg description.
-        provider: Optional explicit provider name. If not specified, will attempt to
-            parse from the model string in the `model` arg.
+            You can also specify model and model provider in a single argument using
+            `'{model_provider}:{model}'` format, e.g. `'openai:text-embedding-3-small'`.
+        provider: The model provider if not specified as part of the model arg
+            (see above).
 
-            Supported providers:
+            Supported `provider` values and the corresponding integration package
+            are:
 
             - `openai`                  -> [`langchain-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
             - `azure_openai`            -> [`langchain-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
@@ -157,7 +158,10 @@ def init_embeddings(
             - `ollama`                  -> [`langchain-ollama`](https://docs.langchain.com/oss/python/integrations/providers/ollama)
 
         **kwargs: Additional model-specific parameters passed to the embedding model.
-            These vary by provider, see the provider-specific documentation for details.
+
+            These vary by provider. Refer to the specific model provider's
+            [integration reference](https://reference.langchain.com/python/integrations/)
+            for all available parameters.
 
     Returns:
         An `Embeddings` instance that can generate embeddings for text.
@@ -166,9 +170,11 @@ def init_embeddings(
         ValueError: If the model provider is not supported or cannot be determined
         ImportError: If the required provider package is not installed
 
-    ???+ note "Example Usage"
+    ???+ example
 
         ```python
+        # pip install langchain langchain-openai
+
         # Using a model string
         model = init_embeddings("openai:text-embedding-3-small")
         model.embed_query("Hello, world!")

langchain/messages/__init__.py

@@ -1,4 +1,4 @@
-"""Message types.
+"""Message and message content types.
 
 Includes message types for different roles (e.g., human, AI, system), as well as types
 for message content blocks (e.g., text, image, audio) and tool calls.
@@ -21,10 +21,12 @@ from langchain_core.messages import (
     FileContentBlock,
     HumanMessage,
     ImageContentBlock,
+    InputTokenDetails,
     InvalidToolCall,
     MessageLikeRepresentation,
     NonStandardAnnotation,
     NonStandardContentBlock,
+    OutputTokenDetails,
     PlainTextContentBlock,
     ReasoningContentBlock,
     RemoveMessage,
@@ -36,6 +38,7 @@ from langchain_core.messages import (
     ToolCall,
     ToolCallChunk,
     ToolMessage,
+    UsageMetadata,
     VideoContentBlock,
     trim_messages,
 )
@@ -52,10 +55,12 @@ __all__ = [
     "FileContentBlock",
     "HumanMessage",
     "ImageContentBlock",
+    "InputTokenDetails",
     "InvalidToolCall",
     "MessageLikeRepresentation",
     "NonStandardAnnotation",
     "NonStandardContentBlock",
+    "OutputTokenDetails",
     "PlainTextContentBlock",
     "ReasoningContentBlock",
     "RemoveMessage",
@@ -67,6 +72,7 @@ __all__ = [
     "ToolCall",
     "ToolCallChunk",
     "ToolMessage",
+    "UsageMetadata",
     "VideoContentBlock",
     "trim_messages",
 ]