langchain-core 0.4.0.dev0__py3-none-any.whl → 1.0.0a1__py3-none-any.whl

langchain_core/language_models/fake_chat_models.py

@@ -3,8 +3,8 @@
 import asyncio
 import re
 import time
-from collections.abc import AsyncIterator, Iterable, Iterator
-from typing import Any, Optional, Union, cast
+from collections.abc import AsyncIterator, Iterator
+from typing import Any, Literal, Optional, Union, cast
 
 from typing_extensions import override
 
@@ -16,10 +16,6 @@ from langchain_core.language_models.chat_models import BaseChatModel, SimpleChat
 from langchain_core.messages import AIMessage, AIMessageChunk, BaseMessage
 from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult
 from langchain_core.runnables import RunnableConfig
-from langchain_core.v1.chat_models import BaseChatModel as BaseChatModelV1
-from langchain_core.v1.messages import AIMessage as AIMessageV1
-from langchain_core.v1.messages import AIMessageChunk as AIMessageChunkV1
-from langchain_core.v1.messages import MessageV1
 
 
 class FakeMessagesListChatModel(BaseChatModel):
@@ -116,7 +112,12 @@ class FakeListChatModel(SimpleChatModel):
             ):
                 raise FakeListChatModelError
 
-            yield ChatGenerationChunk(message=AIMessageChunk(content=c))
+            chunk_position: Optional[Literal["last"]] = (
+                "last" if i_c == len(response) - 1 else None
+            )
+            yield ChatGenerationChunk(
+                message=AIMessageChunk(content=c, chunk_position=chunk_position)
+            )
 
     @override
     async def _astream(
@@ -139,7 +140,12 @@ class FakeListChatModel(SimpleChatModel):
                 and i_c == self.error_on_chunk_number
             ):
                 raise FakeListChatModelError
-            yield ChatGenerationChunk(message=AIMessageChunk(content=c))
+            chunk_position: Optional[Literal["last"]] = (
+                "last" if i_c == len(response) - 1 else None
+            )
+            yield ChatGenerationChunk(
+                message=AIMessageChunk(content=c, chunk_position=chunk_position)
+            )
 
     @property
     @override
@@ -155,7 +161,7 @@ class FakeListChatModel(SimpleChatModel):
         *,
         return_exceptions: bool = False,
         **kwargs: Any,
-    ) -> list[BaseMessage]:
+    ) -> list[AIMessage]:
         if isinstance(config, list):
             return [self.invoke(m, c, **kwargs) for m, c in zip(inputs, config)]
         return [self.invoke(m, config, **kwargs) for m in inputs]
@@ -168,7 +174,7 @@ class FakeListChatModel(SimpleChatModel):
         *,
         return_exceptions: bool = False,
         **kwargs: Any,
-    ) -> list[BaseMessage]:
+    ) -> list[AIMessage]:
         if isinstance(config, list):
             # do Not use an async iterator here because need explicit ordering
             return [await self.ainvoke(m, c, **kwargs) for m, c in zip(inputs, config)]
@@ -227,11 +233,12 @@ class GenericFakeChatModel(BaseChatModel):
     This can be expanded to accept other types like Callables / dicts / strings
     to make the interface more generic if needed.
 
-    Note: if you want to pass a list, you can use `iter` to convert it to an iterator.
+    .. note::
+        if you want to pass a list, you can use ``iter`` to convert it to an iterator.
 
-    Please note that streaming is not implemented yet. We should try to implement it
-    in the future by delegating to invoke and then breaking the resulting output
-    into message chunks.
+    .. warning::
+        Streaming is not implemented yet. We should try to implement it in the future by
+        delegating to invoke and then breaking the resulting output into message chunks.
     """
 
     @override
@@ -286,10 +293,16 @@ class GenericFakeChatModel(BaseChatModel):
 
             content_chunks = cast("list[str]", re.split(r"(\s)", content))
 
-            for token in content_chunks:
+            for idx, token in enumerate(content_chunks):
                 chunk = ChatGenerationChunk(
                     message=AIMessageChunk(content=token, id=message.id)
                 )
+                if (
+                    idx == len(content_chunks) - 1
+                    and isinstance(chunk.message, AIMessageChunk)
+                    and not message.additional_kwargs
+                ):
+                    chunk.message.chunk_position = "last"
                 if run_manager:
                     run_manager.on_llm_new_token(token, chunk=chunk)
                 yield chunk
@@ -371,69 +384,3 @@ class ParrotFakeChatModel(BaseChatModel):
     @property
     def _llm_type(self) -> str:
         return "parrot-fake-chat-model"
-
-
-class GenericFakeChatModelV1(BaseChatModelV1):
-    """Generic fake chat model that can be used to test the chat model interface."""
-
-    messages: Optional[Iterator[Union[AIMessageV1, str]]] = None
-    message_chunks: Optional[Iterable[Union[AIMessageChunkV1, str]]] = None
-
-    @override
-    def _invoke(
-        self,
-        messages: list[MessageV1],
-        run_manager: Optional[CallbackManagerForLLMRun] = None,
-        **kwargs: Any,
-    ) -> AIMessageV1:
-        """Top Level call."""
-        if self.messages is None:
-            error_msg = "Messages iterator is not set."
-            raise ValueError(error_msg)
-        message = next(self.messages)
-        return AIMessageV1(content=message) if isinstance(message, str) else message
-
-    @override
-    def _stream(
-        self,
-        messages: list[MessageV1],
-        run_manager: Optional[CallbackManagerForLLMRun] = None,
-        **kwargs: Any,
-    ) -> Iterator[AIMessageChunkV1]:
-        """Top Level call."""
-        if self.message_chunks is None:
-            error_msg = "Message chunks iterator is not set."
-            raise ValueError(error_msg)
-        for chunk in self.message_chunks:
-            if isinstance(chunk, str):
-                yield AIMessageChunkV1(chunk)
-            else:
-                yield chunk
-
-    @property
-    def _llm_type(self) -> str:
-        return "generic-fake-chat-model"
-
-
-class ParrotFakeChatModelV1(BaseChatModelV1):
-    """Generic fake chat model that can be used to test the chat model interface.
-
-    * Chat model should be usable in both sync and async tests
-    """
-
-    @override
-    def _invoke(
-        self,
-        messages: list[MessageV1],
-        stop: Optional[list[str]] = None,
-        run_manager: Optional[CallbackManagerForLLMRun] = None,
-        **kwargs: Any,
-    ) -> AIMessageV1:
-        """Top Level call."""
-        if isinstance(messages[-1], AIMessageV1):
-            return messages[-1]
-        return AIMessageV1(content=messages[-1].content)
-
-    @property
-    def _llm_type(self) -> str:
-        return "parrot-fake-chat-model"

langchain_core/load/dump.py

@@ -73,10 +73,9 @@ def dumps(obj: Any, *, pretty: bool = False, **kwargs: Any) -> str:
 def dumpd(obj: Any) -> Any:
     """Return a dict representation of an object.
 
-    Note:
-        Unfortunately this function is not as efficient as it could be
-        because it first dumps the object to a json string and then loads it
-        back into a dictionary.
+    .. note::
+        Unfortunately this function is not as efficient as it could be because it first
+        dumps the object to a json string and then loads it back into a dictionary.
 
     Args:
         obj: The object to dump.

langchain_core/messages/__init__.py

@@ -18,6 +18,7 @@
 from typing import TYPE_CHECKING
 
 from langchain_core._import_utils import import_attr
+from langchain_core.utils.utils import LC_AUTO_PREFIX, LC_ID_PREFIX, ensure_id
 
 if TYPE_CHECKING:
     from langchain_core.messages.ai import (
@@ -32,7 +33,7 @@ if TYPE_CHECKING:
         messages_to_dict,
     )
     from langchain_core.messages.chat import ChatMessage, ChatMessageChunk
-    from langchain_core.messages.content_blocks import (
+    from langchain_core.messages.content import (
         Annotation,
         AudioContentBlock,
         Citation,
@@ -54,6 +55,10 @@ if TYPE_CHECKING:
         convert_to_openai_data_block,
         convert_to_openai_image_block,
         is_data_content_block,
+        is_reasoning_block,
+        is_text_block,
+        is_tool_call_block,
+        is_tool_call_chunk,
     )
     from langchain_core.messages.function import FunctionMessage, FunctionMessageChunk
     from langchain_core.messages.human import HumanMessage, HumanMessageChunk
@@ -81,6 +86,8 @@ if TYPE_CHECKING:
     )
 
 __all__ = (
+    "LC_AUTO_PREFIX",
+    "LC_ID_PREFIX",
     "AIMessage",
     "AIMessageChunk",
     "Annotation",
@@ -124,9 +131,14 @@ __all__ = (
     "convert_to_openai_data_block",
     "convert_to_openai_image_block",
     "convert_to_openai_messages",
+    "ensure_id",
     "filter_messages",
     "get_buffer_string",
     "is_data_content_block",
+    "is_reasoning_block",
+    "is_text_block",
+    "is_tool_call_block",
+    "is_tool_call_chunk",
     "merge_content",
     "merge_message_runs",
     "message_chunk_to_message",
@@ -139,53 +151,57 @@ __all__ = (
 _dynamic_imports = {
     "AIMessage": "ai",
     "AIMessageChunk": "ai",
-    "Annotation": "content_blocks",
-    "AudioContentBlock": "content_blocks",
+    "Annotation": "content",
+    "AudioContentBlock": "content",
     "BaseMessage": "base",
     "BaseMessageChunk": "base",
     "merge_content": "base",
     "message_to_dict": "base",
     "messages_to_dict": "base",
-    "Citation": "content_blocks",
-    "ContentBlock": "content_blocks",
+    "Citation": "content",
+    "ContentBlock": "content",
     "ChatMessage": "chat",
     "ChatMessageChunk": "chat",
-    "CodeInterpreterCall": "content_blocks",
-    "CodeInterpreterOutput": "content_blocks",
-    "CodeInterpreterResult": "content_blocks",
-    "DataContentBlock": "content_blocks",
-    "FileContentBlock": "content_blocks",
+    "CodeInterpreterCall": "content",
+    "CodeInterpreterOutput": "content",
+    "CodeInterpreterResult": "content",
+    "DataContentBlock": "content",
+    "FileContentBlock": "content",
     "FunctionMessage": "function",
     "FunctionMessageChunk": "function",
     "HumanMessage": "human",
     "HumanMessageChunk": "human",
-    "NonStandardAnnotation": "content_blocks",
-    "NonStandardContentBlock": "content_blocks",
-    "PlainTextContentBlock": "content_blocks",
-    "ReasoningContentBlock": "content_blocks",
+    "NonStandardAnnotation": "content",
+    "NonStandardContentBlock": "content",
+    "PlainTextContentBlock": "content",
+    "ReasoningContentBlock": "content",
     "RemoveMessage": "modifier",
     "SystemMessage": "system",
     "SystemMessageChunk": "system",
-    "WebSearchCall": "content_blocks",
-    "WebSearchResult": "content_blocks",
-    "ImageContentBlock": "content_blocks",
+    "WebSearchCall": "content",
+    "WebSearchResult": "content",
+    "ImageContentBlock": "content",
     "InvalidToolCall": "tool",
-    "TextContentBlock": "content_blocks",
+    "TextContentBlock": "content",
     "ToolCall": "tool",
     "ToolCallChunk": "tool",
     "ToolMessage": "tool",
     "ToolMessageChunk": "tool",
-    "VideoContentBlock": "content_blocks",
+    "VideoContentBlock": "content",
     "AnyMessage": "utils",
     "MessageLikeRepresentation": "utils",
     "_message_from_dict": "utils",
     "convert_to_messages": "utils",
-    "convert_to_openai_data_block": "content_blocks",
-    "convert_to_openai_image_block": "content_blocks",
+    "convert_to_openai_data_block": "content",
+    "convert_to_openai_image_block": "content",
     "convert_to_openai_messages": "utils",
     "filter_messages": "utils",
     "get_buffer_string": "utils",
-    "is_data_content_block": "content_blocks",
+    "is_data_content_block": "content",
+    "is_reasoning_block": "content",
+    "is_text_block": "content",
+    "is_tool_call_block": "content",
+    "is_tool_call_chunk": "content",
     "merge_message_runs": "utils",
     "message_chunk_to_message": "utils",
     "messages_from_dict": "utils",

langchain_core/messages/ai.py

@@ -3,12 +3,18 @@
 import json
 import logging
 import operator
+from collections.abc import Sequence
 from typing import Any, Literal, Optional, Union, cast
 
 from pydantic import model_validator
-from typing_extensions import NotRequired, Self, TypedDict, override
+from typing_extensions import NotRequired, Self, TypedDict, overload, override
 
-from langchain_core.messages.base import BaseMessage, BaseMessageChunk, merge_content
+from langchain_core.messages import content as types
+from langchain_core.messages.base import (
+    BaseMessage,
+    BaseMessageChunk,
+    merge_content,
+)
 from langchain_core.messages.tool import (
     InvalidToolCall,
     ToolCall,
@@ -22,23 +28,11 @@ from langchain_core.messages.tool import tool_call_chunk as create_tool_call_chu
 from langchain_core.utils._merge import merge_dicts, merge_lists
 from langchain_core.utils.json import parse_partial_json
 from langchain_core.utils.usage import _dict_int_op
+from langchain_core.utils.utils import LC_AUTO_PREFIX, LC_ID_PREFIX
 
 logger = logging.getLogger(__name__)
 
 
-_LC_ID_PREFIX = "run-"
-"""Internal tracing/callback system identifier.
-
-Used for:
-- Tracing. Every LangChain operation (LLM call, chain execution, tool use, etc.)
-  gets a unique run_id (UUID)
-- Enables tracking parent-child relationships between operations
-"""
-
-_LC_AUTO_PREFIX = "lc_"
-"""LangChain auto-generated ID prefix for messages and content blocks."""
-
-
 class InputTokenDetails(TypedDict, total=False):
     """Breakdown of input token counts.
 
@@ -180,16 +174,42 @@ class AIMessage(BaseMessage):
     type: Literal["ai"] = "ai"
     """The type of the message (used for deserialization). Defaults to "ai"."""
 
+    @overload
+    def __init__(
+        self,
+        content: Union[str, list[Union[str, dict]]],
+        **kwargs: Any,
+    ) -> None: ...
+
+    @overload
     def __init__(
-        self, content: Union[str, list[Union[str, dict]]], **kwargs: Any
+        self,
+        content: Optional[Union[str, list[Union[str, dict]]]] = None,
+        content_blocks: Optional[list[types.ContentBlock]] = None,
+        **kwargs: Any,
+    ) -> None: ...
+
+    def __init__(
+        self,
+        content: Optional[Union[str, list[Union[str, dict]]]] = None,
+        content_blocks: Optional[list[types.ContentBlock]] = None,
+        **kwargs: Any,
     ) -> None:
-        """Pass in content as positional arg.
+        """Specify ``content`` as positional arg or ``content_blocks`` for typing."""
+        if content_blocks is not None:
+            # If there are tool calls in content_blocks, but not in tool_calls, add them
+            content_tool_calls = [
+                block for block in content_blocks if block.get("type") == "tool_call"
+            ]
+            if content_tool_calls and "tool_calls" not in kwargs:
+                kwargs["tool_calls"] = content_tool_calls
 
-        Args:
-            content: The content of the message.
-            kwargs: Additional arguments to pass to the parent class.
-        """
-        super().__init__(content=content, **kwargs)
+            super().__init__(
+                content=cast("Union[str, list[Union[str, dict]]]", content_blocks),
+                **kwargs,
+            )
+        else:
+            super().__init__(content=content, **kwargs)
 
     @property
     def lc_attributes(self) -> dict:
@@ -199,6 +219,49 @@ class AIMessage(BaseMessage):
             "invalid_tool_calls": self.invalid_tool_calls,
         }
 
+    @property
+    def content_blocks(self) -> list[types.ContentBlock]:
+        """Return content blocks of the message."""
+        if self.response_metadata.get("output_version") == "v1":
+            return cast("list[types.ContentBlock]", self.content)
+
+        model_provider = self.response_metadata.get("model_provider")
+        if model_provider:
+            from langchain_core.messages.block_translators import get_translator
+
+            translator = get_translator(model_provider)
+            if translator:
+                try:
+                    return translator["translate_content"](self)
+                except NotImplementedError:
+                    pass
+
+        # Otherwise, use best-effort parsing
+        blocks = super().content_blocks
+
+        if self.tool_calls:
+            # Add from tool_calls if missing from content
+            content_tool_call_ids = {
+                block.get("id")
+                for block in self.content
+                if isinstance(block, dict) and block.get("type") == "tool_call"
+            }
+            for tool_call in self.tool_calls:
+                if (id_ := tool_call.get("id")) and id_ not in content_tool_call_ids:
+                    tool_call_block: types.ToolCall = {
+                        "type": "tool_call",
+                        "id": id_,
+                        "name": tool_call["name"],
+                        "args": tool_call["args"],
+                    }
+                    if "index" in tool_call:
+                        tool_call_block["index"] = tool_call["index"]  # type: ignore[typeddict-item]
+                    if "extras" in tool_call:
+                        tool_call_block["extras"] = tool_call["extras"]  # type: ignore[typeddict-item]
+                    blocks.append(tool_call_block)
+
+        return blocks
+
     # TODO: remove this logic if possible, reducing breaking nature of changes
     @model_validator(mode="before")
     @classmethod
@@ -227,7 +290,9 @@ class AIMessage(BaseMessage):
         # Ensure "type" is properly set on all tool call-like dicts.
         if tool_calls := values.get("tool_calls"):
             values["tool_calls"] = [
-                create_tool_call(**{k: v for k, v in tc.items() if k != "type"})
+                create_tool_call(
+                    **{k: v for k, v in tc.items() if k not in ("type", "extras")}
+                )
                 for tc in tool_calls
             ]
         if invalid_tool_calls := values.get("invalid_tool_calls"):
@@ -298,6 +363,13 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
     tool_call_chunks: list[ToolCallChunk] = []
     """If provided, tool call chunks associated with the message."""
 
+    chunk_position: Optional[Literal["last"]] = None
+    """Optional span represented by an aggregated AIMessageChunk.
+
+    If a chunk with ``chunk_position="last"`` is aggregated into a stream,
+    ``tool_call_chunks`` in message content will be parsed into ``tool_calls``.
+    """
+
     @property
     def lc_attributes(self) -> dict:
         """Attrs to be serialized even if they are derived from other init args."""
@@ -306,6 +378,49 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
             "invalid_tool_calls": self.invalid_tool_calls,
         }
 
+    @property
+    def content_blocks(self) -> list[types.ContentBlock]:
+        """Return content blocks of the message."""
+        if self.response_metadata.get("output_version") == "v1":
+            return cast("list[types.ContentBlock]", self.content)
+
+        model_provider = self.response_metadata.get("model_provider")
+        if model_provider:
+            from langchain_core.messages.block_translators import get_translator
+
+            translator = get_translator(model_provider)
+            if translator:
+                try:
+                    return translator["translate_content_chunk"](self)
+                except NotImplementedError:
+                    pass
+
+        # Otherwise, use best-effort parsing
+        blocks = super().content_blocks
+
+        if (
+            self.tool_call_chunks
+            and not self.content
+            and self.chunk_position != "last"  # keep tool_calls if aggregated
+        ):
+            blocks = [
+                block
+                for block in blocks
+                if block["type"] not in ("tool_call", "invalid_tool_call")
+            ]
+            for tool_call_chunk in self.tool_call_chunks:
+                tc: types.ToolCallChunk = {
+                    "type": "tool_call_chunk",
+                    "id": tool_call_chunk.get("id"),
+                    "name": tool_call_chunk.get("name"),
+                    "args": tool_call_chunk.get("args"),
+                }
+                if (idx := tool_call_chunk.get("index")) is not None:
+                    tc["index"] = idx
+                blocks.append(tc)
+
+        return blocks
+
     @model_validator(mode="after")
     def init_tool_calls(self) -> Self:
         """Initialize tool calls from tool call chunks.
@@ -358,7 +473,10 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
 
         for chunk in self.tool_call_chunks:
             try:
-                args_ = parse_partial_json(chunk["args"]) if chunk["args"] != "" else {}  # type: ignore[arg-type]
+                if chunk["args"] is not None and chunk["args"] != "":
+                    args_ = parse_partial_json(chunk["args"])
+                else:
+                    args_ = {}
                 if isinstance(args_, dict):
                     tool_calls.append(
                         create_tool_call(
@@ -373,10 +491,45 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
                 add_chunk_to_invalid_tool_calls(chunk)
         self.tool_calls = tool_calls
         self.invalid_tool_calls = invalid_tool_calls
+
+        if (
+            self.chunk_position == "last"
+            and self.tool_call_chunks
+            and self.response_metadata.get("output_version") == "v1"
+            and isinstance(self.content, list)
+        ):
+            id_to_tc: dict[str, types.ToolCall] = {
+                cast("str", tc.get("id")): {
+                    "type": "tool_call",
+                    "name": tc["name"],
+                    "args": tc["args"],
+                    "id": tc.get("id"),
+                }
+                for tc in self.tool_calls
+                if "id" in tc
+            }
+            for idx, block in enumerate(self.content):
+                if (
+                    isinstance(block, dict)
+                    and block.get("type") == "tool_call_chunk"
+                    and (call_id := block.get("id"))
+                    and call_id in id_to_tc
+                ):
+                    self.content[idx] = cast("dict[str, Any]", id_to_tc[call_id])
+
         return self
 
+    @overload  # type: ignore[override]  # summing BaseMessages gives ChatPromptTemplate
+    def __add__(self, other: "AIMessageChunk") -> "AIMessageChunk": ...
+
+    @overload
+    def __add__(self, other: Sequence["AIMessageChunk"]) -> "AIMessageChunk": ...
+
+    @overload
+    def __add__(self, other: Any) -> BaseMessageChunk: ...
+
     @override
-    def __add__(self, other: Any) -> BaseMessageChunk:  # type: ignore[override]
+    def __add__(self, other: Any) -> BaseMessageChunk:
         if isinstance(other, AIMessageChunk):
             return add_ai_message_chunks(self, other)
         if isinstance(other, (list, tuple)) and all(
@@ -432,24 +585,28 @@ def add_ai_message_chunks(
     for id_ in candidates:
         if (
             id_
-            and not id_.startswith(_LC_ID_PREFIX)
-            and not id_.startswith(_LC_AUTO_PREFIX)
+            and not id_.startswith(LC_ID_PREFIX)
+            and not id_.startswith(LC_AUTO_PREFIX)
         ):
             chunk_id = id_
             break
     else:
-        # second pass: prefer lc_* ids over run-* ids
+        # second pass: prefer lc_run-* ids over lc_* ids
         for id_ in candidates:
-            if id_ and id_.startswith(_LC_AUTO_PREFIX):
+            if id_ and id_.startswith(LC_ID_PREFIX):
                 chunk_id = id_
                 break
         else:
-            # third pass: take any remaining id (run-* ids)
+            # third pass: take any remaining id (auto-generated lc_* ids)
             for id_ in candidates:
                 if id_:
                     chunk_id = id_
                     break
 
+    chunk_position: Optional[Literal["last"]] = (
+        "last" if any(x.chunk_position == "last" for x in [left, *others]) else None
+    )
+
     return left.__class__(
         example=left.example,
         content=content,
@@ -458,6 +615,7 @@ def add_ai_message_chunks(
         response_metadata=response_metadata,
         usage_metadata=usage_metadata,
         id=chunk_id,
+        chunk_position=chunk_position,
     )