langchain-core 1.1.1__tar.gz → 1.2.0__tar.gz

{langchain_core-1.1.1 → langchain_core-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-core
-Version: 1.1.1
+Version: 1.2.0
 Summary: Building applications with LLMs through composability
 Project-URL: Homepage, https://docs.langchain.com/
 Project-URL: Documentation, https://reference.langchain.com/python/langchain_core/

{langchain_core-1.1.1 → langchain_core-1.2.0}/langchain_core/callbacks/usage.py

@@ -95,7 +95,7 @@ def get_usage_metadata_callback(
     """Get usage metadata callback.
 
     Get context manager for tracking usage metadata across chat model calls using
-    `AIMessage.usage_metadata`.
+    [`AIMessage.usage_metadata`][langchain.messages.AIMessage.usage_metadata].
 
     Args:
         name: The name of the context variable.

{langchain_core-1.1.1 → langchain_core-1.2.0}/langchain_core/language_models/__init__.py

@@ -1,7 +1,7 @@
-"""Language models.
+"""Core language model abstractions.
 
 LangChain has two main classes to work with language models: chat models and
-"old-fashioned" LLMs.
+"old-fashioned" LLMs (string-in, string-out).
 
 **Chat models**
 
@@ -11,14 +11,16 @@ as outputs (as opposed to using plain text).
 Chat models support the assignment of distinct roles to conversation messages, helping
 to distinguish messages from the AI, users, and instructions such as system messages.
 
-The key abstraction for chat models is `BaseChatModel`. Implementations should inherit
-from this class.
+The key abstraction for chat models is
+[`BaseChatModel`][langchain_core.language_models.BaseChatModel]. Implementations should
+inherit from this class.
 
 See existing [chat model integrations](https://docs.langchain.com/oss/python/integrations/chat).
 
-**LLMs**
+**LLMs (legacy)**
 
 Language models that takes a string as input and returns a string.
+
 These are traditionally older models (newer models generally are chat models).
 
 Although the underlying models are string in, string out, the LangChain wrappers also

{langchain_core-1.1.1 → langchain_core-1.2.0}/langchain_core/language_models/chat_models.py

@@ -1578,86 +1578,86 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
                     depends on the `schema` as described above.
                 - `'parsing_error'`: `BaseException | None`
 
-        Example: Pydantic schema (`include_raw=False`):
+        ???+ example "Pydantic schema (`include_raw=False`)"
 
-        ```python
-        from pydantic import BaseModel
+            ```python
+            from pydantic import BaseModel
 
 
-        class AnswerWithJustification(BaseModel):
-            '''An answer to the user question along with justification for the answer.'''
+            class AnswerWithJustification(BaseModel):
+                '''An answer to the user question along with justification for the answer.'''
 
-            answer: str
-            justification: str
+                answer: str
+                justification: str
 
 
-        model = ChatModel(model="model-name", temperature=0)
-        structured_model = model.with_structured_output(AnswerWithJustification)
+            model = ChatModel(model="model-name", temperature=0)
+            structured_model = model.with_structured_output(AnswerWithJustification)
 
-        structured_model.invoke(
-            "What weighs more a pound of bricks or a pound of feathers"
-        )
+            structured_model.invoke(
+                "What weighs more a pound of bricks or a pound of feathers"
+            )
 
-        # -> AnswerWithJustification(
-        #     answer='They weigh the same',
-        #     justification='Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.'
-        # )
-        ```
+            # -> AnswerWithJustification(
+            #     answer='They weigh the same',
+            #     justification='Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.'
+            # )
+            ```
 
-        Example: Pydantic schema (`include_raw=True`):
+        ??? example "Pydantic schema (`include_raw=True`)"
 
-        ```python
-        from pydantic import BaseModel
+            ```python
+            from pydantic import BaseModel
 
 
-        class AnswerWithJustification(BaseModel):
-            '''An answer to the user question along with justification for the answer.'''
+            class AnswerWithJustification(BaseModel):
+                '''An answer to the user question along with justification for the answer.'''
 
-            answer: str
-            justification: str
+                answer: str
+                justification: str
 
 
-        model = ChatModel(model="model-name", temperature=0)
-        structured_model = model.with_structured_output(
-            AnswerWithJustification, include_raw=True
-        )
+            model = ChatModel(model="model-name", temperature=0)
+            structured_model = model.with_structured_output(
+                AnswerWithJustification, include_raw=True
+            )
 
-        structured_model.invoke(
-            "What weighs more a pound of bricks or a pound of feathers"
-        )
-        # -> {
-        #     'raw': AIMessage(content='', additional_kwargs={'tool_calls': [{'id': 'call_Ao02pnFYXD6GN1yzc0uXPsvF', 'function': {'arguments': '{"answer":"They weigh the same.","justification":"Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ."}', 'name': 'AnswerWithJustification'}, 'type': 'function'}]}),
-        #     'parsed': AnswerWithJustification(answer='They weigh the same.', justification='Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.'),
-        #     'parsing_error': None
-        # }
-        ```
+            structured_model.invoke(
+                "What weighs more a pound of bricks or a pound of feathers"
+            )
+            # -> {
+            #     'raw': AIMessage(content='', additional_kwargs={'tool_calls': [{'id': 'call_Ao02pnFYXD6GN1yzc0uXPsvF', 'function': {'arguments': '{"answer":"They weigh the same.","justification":"Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ."}', 'name': 'AnswerWithJustification'}, 'type': 'function'}]}),
+            #     'parsed': AnswerWithJustification(answer='They weigh the same.', justification='Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.'),
+            #     'parsing_error': None
+            # }
+            ```
 
-        Example: Dictionary schema (`include_raw=False`):
+        ??? example "Dictionary schema (`include_raw=False`)"
 
-        ```python
-        from pydantic import BaseModel
-        from langchain_core.utils.function_calling import convert_to_openai_tool
+            ```python
+            from pydantic import BaseModel
+            from langchain_core.utils.function_calling import convert_to_openai_tool
 
 
-        class AnswerWithJustification(BaseModel):
-            '''An answer to the user question along with justification for the answer.'''
+            class AnswerWithJustification(BaseModel):
+                '''An answer to the user question along with justification for the answer.'''
 
-            answer: str
-            justification: str
+                answer: str
+                justification: str
 
 
-        dict_schema = convert_to_openai_tool(AnswerWithJustification)
-        model = ChatModel(model="model-name", temperature=0)
-        structured_model = model.with_structured_output(dict_schema)
+            dict_schema = convert_to_openai_tool(AnswerWithJustification)
+            model = ChatModel(model="model-name", temperature=0)
+            structured_model = model.with_structured_output(dict_schema)
 
-        structured_model.invoke(
-            "What weighs more a pound of bricks or a pound of feathers"
-        )
-        # -> {
-        #     'answer': 'They weigh the same',
-        #     'justification': 'Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume and density of the two substances differ.'
-        # }
-        ```
+            structured_model.invoke(
+                "What weighs more a pound of bricks or a pound of feathers"
+            )
+            # -> {
+            #     'answer': 'They weigh the same',
+            #     'justification': 'Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume and density of the two substances differ.'
+            # }
+            ```
 
         !!! warning "Behavior changed in `langchain-core` 0.2.26"
 

{langchain_core-1.1.1 → langchain_core-1.2.0}/langchain_core/language_models/llms.py

@@ -61,6 +61,8 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+_background_tasks: set[asyncio.Task] = set()
+
 
 @functools.lru_cache
 def _log_error_once(msg: str) -> None:
@@ -100,9 +102,9 @@ def create_base_retry_decorator(
                         asyncio.run(coro)
                     else:
                         if loop.is_running():
-                            # TODO: Fix RUF006 - this task should have a reference
-                            #  and be awaited somewhere
-                            loop.create_task(coro)  # noqa: RUF006
+                            task = loop.create_task(coro)
+                            _background_tasks.add(task)
+                            task.add_done_callback(_background_tasks.discard)
                         else:
                             asyncio.run(coro)
                 except Exception as e:

{langchain_core-1.1.1 → langchain_core-1.2.0}/langchain_core/load/load.py

@@ -1,4 +1,9 @@
-"""Load LangChain objects from JSON strings or objects."""
+"""Load LangChain objects from JSON strings or objects.
+
+!!! warning
+    `load` and `loads` are vulnerable to remote code execution. Never use with untrusted
+    input.
+"""
 
 import importlib
 import json
@@ -193,6 +198,10 @@ def loads(
 ) -> Any:
     """Revive a LangChain class from a JSON string.
 
+    !!! warning
+        This function is vulnerable to remote code execution. Never use with untrusted
+        input.
+
     Equivalent to `load(json.loads(text))`.
 
     Args:
@@ -236,6 +245,10 @@ def load(
 ) -> Any:
     """Revive a LangChain class from a JSON object.
 
+    !!! warning
+        This function is vulnerable to remote code execution. Never use with untrusted
+        input.
+
     Use this if you already have a parsed JSON object,
     eg. from `json.load` or `orjson.loads`.
 

{langchain_core-1.1.1 → langchain_core-1.2.0}/langchain_core/messages/ai.py

@@ -51,22 +51,22 @@ class InputTokenDetails(TypedDict, total=False):
     May also hold extra provider-specific keys.
 
     !!! version-added "Added in `langchain-core` 0.3.9"
-
     """
 
     audio: int
     """Audio input tokens."""
+
     cache_creation: int
     """Input tokens that were cached and there was a cache miss.
 
     Since there was a cache miss, the cache was created from these tokens.
     """
+
     cache_read: int
     """Input tokens that were cached and there was a cache hit.
 
     Since there was a cache hit, the tokens were read from the cache. More precisely,
     the model state given these tokens was read from the cache.
-
     """
 
 
@@ -91,12 +91,12 @@ class OutputTokenDetails(TypedDict, total=False):
 
     audio: int
     """Audio output tokens."""
+
     reasoning: int
     """Reasoning output tokens.
 
     Tokens generated by the model in a chain of thought process (i.e. by OpenAI's o1
     models) that are not returned as part of model output.
-
     """
 
 
@@ -136,15 +136,19 @@ class UsageMetadata(TypedDict):
 
     input_tokens: int
     """Count of input (or prompt) tokens. Sum of all input token types."""
+
     output_tokens: int
     """Count of output (or completion) tokens. Sum of all output token types."""
+
     total_tokens: int
     """Total token count. Sum of `input_tokens` + `output_tokens`."""
+
     input_token_details: NotRequired[InputTokenDetails]
     """Breakdown of input token counts.
 
     Does *not* need to sum to full input token count. Does *not* need to have all keys.
     """
+
     output_token_details: NotRequired[OutputTokenDetails]
     """Breakdown of output token counts.
 
@@ -164,8 +168,10 @@ class AIMessage(BaseMessage):
 
     tool_calls: list[ToolCall] = []
     """If present, tool calls associated with the message."""
+
     invalid_tool_calls: list[InvalidToolCall] = []
     """If present, tool calls with parsing errors associated with the message."""
+
     usage_metadata: UsageMetadata | None = None
     """If present, usage metadata for a message, such as token counts.
 
@@ -557,7 +563,7 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
 
     @model_validator(mode="after")
     def init_server_tool_calls(self) -> Self:
-        """Parse `server_tool_call_chunks`."""
+        """Parse `server_tool_call_chunks` from [`ServerToolCallChunk`][langchain.messages.ServerToolCallChunk] objects."""  # noqa: E501
         if (
             self.chunk_position == "last"
             and self.response_metadata.get("output_version") == "v1"

{langchain_core-1.1.1 → langchain_core-1.2.0}/langchain_core/messages/base.py

@@ -391,12 +391,12 @@ class BaseMessageChunk(BaseMessage):
         Raises:
             TypeError: If the other object is not a message chunk.
 
-        For example,
-
-        `AIMessageChunk(content="Hello") + AIMessageChunk(content=" World")`
-
-        will give `AIMessageChunk(content="Hello World")`
-
+        Example:
+            ```txt
+              AIMessageChunk(content="Hello", ...)
+            + AIMessageChunk(content=" World", ...)
+            = AIMessageChunk(content="Hello World", ...)
+            ```
         """
         if isinstance(other, BaseMessageChunk):
             # If both are (subclasses of) BaseMessageChunk,

{langchain_core-1.1.1 → langchain_core-1.2.0}/langchain_core/messages/block_translators/anthropic.py

@@ -248,8 +248,14 @@ def _convert_to_v1_from_anthropic(message: AIMessage) -> list[types.ContentBlock
                     tool_call_chunk: types.ToolCallChunk = (
                         message.tool_call_chunks[0].copy()  # type: ignore[assignment]
                     )
+                    if "caller" in block:
+                        if "extras" not in tool_call_chunk:
+                            tool_call_chunk["extras"] = {}
+                        tool_call_chunk["extras"]["caller"] = block["caller"]
+
                     if "type" not in tool_call_chunk:
                         tool_call_chunk["type"] = "tool_call_chunk"
+
                     yield tool_call_chunk
                 else:
                     tool_call_block: types.ToolCall | None = None
@@ -282,6 +288,11 @@ def _convert_to_v1_from_anthropic(message: AIMessage) -> list[types.ContentBlock
                         }
                     if "index" in block:
                         tool_call_block["index"] = block["index"]
+                    if "caller" in block:
+                        if "extras" not in tool_call_block:
+                            tool_call_block["extras"] = {}
+                        tool_call_block["extras"]["caller"] = block["caller"]
+
                     yield tool_call_block
 
             elif block_type == "input_json_delta" and isinstance(

{langchain_core-1.1.1 → langchain_core-1.2.0}/langchain_core/messages/block_translators/google_genai.py

@@ -76,21 +76,36 @@ def translate_grounding_metadata_to_citations(
         for chunk_index in chunk_indices:
             if chunk_index < len(grounding_chunks):
                 chunk = grounding_chunks[chunk_index]
-                web_info = chunk.get("web", {})
+
+                # Handle web and maps grounding
+                web_info = chunk.get("web") or {}
+                maps_info = chunk.get("maps") or {}
+
+                # Extract citation info depending on source
+                url = maps_info.get("uri") or web_info.get("uri")
+                title = maps_info.get("title") or web_info.get("title")
+
+                # Note: confidence_scores is a legacy field from Gemini 2.0 and earlier
+                # that indicated confidence (0.0-1.0) for each grounding chunk.
+                #
+                # In Gemini 2.5+, this field is always None/empty and should be ignored.
+                extras_metadata = {
+                    "web_search_queries": web_search_queries,
+                    "grounding_chunk_index": chunk_index,
+                    "confidence_scores": support.get("confidence_scores") or [],
+                }
+
+                # Add maps-specific metadata if present
+                if maps_info.get("placeId"):
+                    extras_metadata["place_id"] = maps_info["placeId"]
 
                 citation = create_citation(
-                    url=web_info.get("uri"),
-                    title=web_info.get("title"),
+                    url=url,
+                    title=title,
                     start_index=start_index,
                     end_index=end_index,
                     cited_text=cited_text,
-                    extras={
-                        "google_ai_metadata": {
-                            "web_search_queries": web_search_queries,
-                            "grounding_chunk_index": chunk_index,
-                            "confidence_scores": support.get("confidence_scores", []),
-                        }
-                    },
+                    google_ai_metadata=extras_metadata,
                 )
                 citations.append(citation)
 

{langchain_core-1.1.1 → langchain_core-1.2.0}/langchain_core/messages/tool.py

@@ -29,38 +29,39 @@ class ToolMessage(BaseMessage, ToolOutputMixin):
     `ToolMessage` objects contain the result of a tool invocation. Typically, the result
     is encoded inside the `content` field.
 
-    Example: A `ToolMessage` representing a result of `42` from a tool call with id
+    `tool_call_id` is used to associate the tool call request with the tool call
+    response. Useful in situations where a chat model is able to request multiple tool
+    calls in parallel.
 
-    ```python
-    from langchain_core.messages import ToolMessage
-
-    ToolMessage(content="42", tool_call_id="call_Jja7J89XsjrOLA5r!MEOW!SL")
-    ```
+    Example:
+        A `ToolMessage` representing a result of `42` from a tool call with id
 
-    Example: A `ToolMessage` where only part of the tool output is sent to the model
-    and the full output is passed in to artifact.
+        ```python
+        from langchain_core.messages import ToolMessage
 
-    ```python
-    from langchain_core.messages import ToolMessage
-
-    tool_output = {
-        "stdout": "From the graph we can see that the correlation between "
-        "x and y is ...",
-        "stderr": None,
-        "artifacts": {"type": "image", "base64_data": "/9j/4gIcSU..."},
-    }
-
-    ToolMessage(
-        content=tool_output["stdout"],
-        artifact=tool_output,
-        tool_call_id="call_Jja7J89XsjrOLA5r!MEOW!SL",
-    )
-    ```
+        ToolMessage(content="42", tool_call_id="call_Jja7J89XsjrOLA5r!MEOW!SL")
+        ```
 
-    The `tool_call_id` field is used to associate the tool call request with the
-    tool call response. Useful in situations where a chat model is able
-    to request multiple tool calls in parallel.
+    Example:
+        A `ToolMessage` where only part of the tool output is sent to the model
+        and the full output is passed in to artifact.
 
+        ```python
+        from langchain_core.messages import ToolMessage
+
+        tool_output = {
+            "stdout": "From the graph we can see that the correlation between "
+            "x and y is ...",
+            "stderr": None,
+            "artifacts": {"type": "image", "base64_data": "/9j/4gIcSU..."},
+        }
+
+        ToolMessage(
+            content=tool_output["stdout"],
+            artifact=tool_output,
+            tool_call_id="call_Jja7J89XsjrOLA5r!MEOW!SL",
+        )
+        ```
     """
 
     tool_call_id: str

{langchain_core-1.1.1 → langchain_core-1.2.0}/langchain_core/messages/utils.py

@@ -15,12 +15,16 @@ import json
 import logging
 import math
 from collections.abc import Callable, Iterable, Sequence
-from functools import partial
+from functools import partial, wraps
 from typing import (
     TYPE_CHECKING,
     Annotated,
     Any,
+    Concatenate,
     Literal,
+    ParamSpec,
+    Protocol,
+    TypeVar,
     cast,
     overload,
 )
@@ -384,33 +388,54 @@ def convert_to_messages(
     return [_convert_to_message(m) for m in messages]
 
 
-def _runnable_support(func: Callable) -> Callable:
-    @overload
-    def wrapped(
-        messages: None = None, **kwargs: Any
-    ) -> Runnable[Sequence[MessageLikeRepresentation], list[BaseMessage]]: ...
+_P = ParamSpec("_P")
+_R_co = TypeVar("_R_co", covariant=True)
+
 
+class _RunnableSupportCallable(Protocol[_P, _R_co]):
     @overload
-    def wrapped(
-        messages: Sequence[MessageLikeRepresentation], **kwargs: Any
-    ) -> list[BaseMessage]: ...
+    def __call__(
+        self,
+        messages: None = None,
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> Runnable[Sequence[MessageLikeRepresentation], _R_co]: ...
 
+    @overload
+    def __call__(
+        self,
+        messages: Sequence[MessageLikeRepresentation] | PromptValue,
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> _R_co: ...
+
+    def __call__(
+        self,
+        messages: Sequence[MessageLikeRepresentation] | PromptValue | None = None,
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> _R_co | Runnable[Sequence[MessageLikeRepresentation], _R_co]: ...
+
+
+def _runnable_support(
+    func: Callable[
+        Concatenate[Sequence[MessageLikeRepresentation] | PromptValue, _P], _R_co
+    ],
+) -> _RunnableSupportCallable[_P, _R_co]:
+    @wraps(func)
     def wrapped(
-        messages: Sequence[MessageLikeRepresentation] | None = None,
-        **kwargs: Any,
-    ) -> (
-        list[BaseMessage]
-        | Runnable[Sequence[MessageLikeRepresentation], list[BaseMessage]]
-    ):
+        messages: Sequence[MessageLikeRepresentation] | PromptValue | None = None,
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> _R_co | Runnable[Sequence[MessageLikeRepresentation], _R_co]:
         # Import locally to prevent circular import.
         from langchain_core.runnables.base import RunnableLambda  # noqa: PLC0415
 
         if messages is not None:
-            return func(messages, **kwargs)
+            return func(messages, *args, **kwargs)
         return RunnableLambda(partial(func, **kwargs), name=func.__name__)
 
-    wrapped.__doc__ = func.__doc__
-    return wrapped
+    return cast("_RunnableSupportCallable[_P, _R_co]", wrapped)
 
 
 @_runnable_support

langchain_core-1.2.0/langchain_core/output_parsers/string.py

@@ -0,0 +1,63 @@
+"""String output parser."""
+
+from typing_extensions import override
+
+from langchain_core.output_parsers.transform import BaseTransformOutputParser
+
+
+class StrOutputParser(BaseTransformOutputParser[str]):
+    """Extract text content from model outputs as a string.
+
+    Converts model outputs (such as `AIMessage` or `AIMessageChunk` objects) into plain
+    text strings. It's the simplest output parser and is useful when you need string
+    responses for downstream processing, display, or storage.
+
+    Supports streaming, yielding text chunks as they're generated by the model.
+
+    Example:
+        ```python
+        from langchain_core.output_parsers import StrOutputParser
+        from langchain_openai import ChatOpenAI
+
+        model = ChatOpenAI(model="gpt-4o")
+        parser = StrOutputParser()
+
+        # Get string output from a model
+        message = model.invoke("Tell me a joke")
+        result = parser.invoke(message)
+        print(result)  # plain string
+
+        # With streaming - use transform() to process a stream
+        stream = model.stream("Tell me a story")
+        for chunk in parser.transform(stream):
+            print(chunk, end="", flush=True)
+        ```
+    """
+
+    @classmethod
+    def is_lc_serializable(cls) -> bool:
+        """`StrOutputParser` is serializable.
+
+        Returns:
+            `True`
+        """
+        return True
+
+    @classmethod
+    def get_lc_namespace(cls) -> list[str]:
+        """Get the namespace of the LangChain object.
+
+        Returns:
+            `["langchain", "schema", "output_parser"]`
+        """
+        return ["langchain", "schema", "output_parser"]
+
+    @property
+    def _type(self) -> str:
+        """Return the output parser type for serialization."""
+        return "default"
+
+    @override
+    def parse(self, text: str) -> str:
+        """Returns the input text with no changes."""
+        return text