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

langchain_core/messages/human.py

@@ -1,7 +1,8 @@
 """Human message."""
 
-from typing import Any, Literal, Union
+from typing import Any, Literal, Optional, Union, cast, overload
 
+from langchain_core.messages import content as types
 from langchain_core.messages.base import BaseMessage, BaseMessageChunk
 
 
@@ -41,16 +42,35 @@ class HumanMessage(BaseMessage):
     type: Literal["human"] = "human"
     """The type of the message (used for serialization). Defaults to "human"."""
 
+    @overload
     def __init__(
-        self, content: Union[str, list[Union[str, dict]]], **kwargs: Any
-    ) -> None:
-        """Pass in content as positional arg.
+        self,
+        content: Union[str, list[Union[str, dict]]],
+        **kwargs: Any,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        content: Optional[Union[str, list[Union[str, dict]]]] = None,
+        content_blocks: Optional[list[types.ContentBlock]] = None,
+        **kwargs: Any,
+    ) -> None: ...
 
-        Args:
-            content: The string contents of the message.
-            kwargs: Additional fields to pass to the message.
-        """
-        super().__init__(content=content, **kwargs)
+    def __init__(
+        self,
+        content: Optional[Union[str, list[Union[str, dict]]]] = None,
+        content_blocks: Optional[list[types.ContentBlock]] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Specify ``content`` as positional arg or ``content_blocks`` for typing."""
+        if content_blocks is not None:
+            super().__init__(
+                content=cast("Union[str, list[Union[str, dict]]]", content_blocks),
+                **kwargs,
+            )
+        else:
+            super().__init__(content=content, **kwargs)
 
 
 class HumanMessageChunk(HumanMessage, BaseMessageChunk):

langchain_core/messages/system.py

@@ -1,7 +1,8 @@
 """System message."""
 
-from typing import Any, Literal, Union
+from typing import Any, Literal, Optional, Union, cast, overload
 
+from langchain_core.messages import content as types
 from langchain_core.messages.base import BaseMessage, BaseMessageChunk
 
 
@@ -34,16 +35,35 @@ class SystemMessage(BaseMessage):
     type: Literal["system"] = "system"
     """The type of the message (used for serialization). Defaults to "system"."""
 
+    @overload
     def __init__(
-        self, content: Union[str, list[Union[str, dict]]], **kwargs: Any
-    ) -> None:
-        """Pass in content as positional arg.
+        self,
+        content: Union[str, list[Union[str, dict]]],
+        **kwargs: Any,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        content: Optional[Union[str, list[Union[str, dict]]]] = None,
+        content_blocks: Optional[list[types.ContentBlock]] = None,
+        **kwargs: Any,
+    ) -> None: ...
 
-        Args:
-               content: The string contents of the message.
-               kwargs: Additional fields to pass to the message.
-        """
-        super().__init__(content=content, **kwargs)
+    def __init__(
+        self,
+        content: Optional[Union[str, list[Union[str, dict]]]] = None,
+        content_blocks: Optional[list[types.ContentBlock]] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Specify ``content`` as positional arg or ``content_blocks`` for typing."""
+        if content_blocks is not None:
+            super().__init__(
+                content=cast("Union[str, list[Union[str, dict]]]", content_blocks),
+                **kwargs,
+            )
+        else:
+            super().__init__(content=content, **kwargs)
 
 
 class SystemMessageChunk(SystemMessage, BaseMessageChunk):

langchain_core/messages/tool.py

@@ -1,16 +1,15 @@
 """Messages for tools."""
 
 import json
-from typing import Any, Literal, Optional, Union
+from typing import Any, Literal, Optional, Union, cast, overload
 from uuid import UUID
 
 from pydantic import Field, model_validator
-from typing_extensions import override
+from typing_extensions import NotRequired, TypedDict, override
 
+from langchain_core.messages import content as types
 from langchain_core.messages.base import BaseMessage, BaseMessageChunk, merge_content
-from langchain_core.messages.content_blocks import InvalidToolCall as InvalidToolCall
-from langchain_core.messages.content_blocks import ToolCall as ToolCall
-from langchain_core.messages.content_blocks import ToolCallChunk as ToolCallChunk
+from langchain_core.messages.content import InvalidToolCall as InvalidToolCall
 from langchain_core.utils._merge import merge_dicts, merge_obj
 
 
@@ -136,16 +135,35 @@ class ToolMessage(BaseMessage, ToolOutputMixin):
             values["tool_call_id"] = str(tool_call_id)
         return values
 
+    @overload
     def __init__(
-        self, content: Union[str, list[Union[str, dict]]], **kwargs: Any
-    ) -> None:
-        """Create a ToolMessage.
+        self,
+        content: Union[str, list[Union[str, dict]]],
+        **kwargs: Any,
+    ) -> None: ...
 
-        Args:
-            content: The string contents of the message.
-            **kwargs: Additional fields.
-        """
-        super().__init__(content=content, **kwargs)
+    @overload
+    def __init__(
+        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:
+        """Specify ``content`` as positional arg or ``content_blocks`` for typing."""
+        if content_blocks is not None:
+            super().__init__(
+                content=cast("Union[str, list[Union[str, dict]]]", content_blocks),
+                **kwargs,
+            )
+        else:
+            super().__init__(content=content, **kwargs)
 
 
 class ToolMessageChunk(ToolMessage, BaseMessageChunk):
@@ -180,6 +198,37 @@ class ToolMessageChunk(ToolMessage, BaseMessageChunk):
         return super().__add__(other)
 
 
+class ToolCall(TypedDict):
+    """Represents a request to call a tool.
+
+    Example:
+
+        .. code-block:: python
+
+            {
+                "name": "foo",
+                "args": {"a": 1},
+                "id": "123"
+            }
+
+        This represents a request to call the tool named "foo" with arguments {"a": 1}
+        and an identifier of "123".
+
+    """
+
+    name: str
+    """The name of the tool to be called."""
+    args: dict[str, Any]
+    """The arguments to the tool call."""
+    id: Optional[str]
+    """An identifier associated with the tool call.
+
+    An identifier is needed to associate a tool call request with a tool
+    call result in events when multiple concurrent tool calls are made.
+    """
+    type: NotRequired[Literal["tool_call"]]
+
+
 def tool_call(
     *,
     name: str,
@@ -196,6 +245,38 @@ def tool_call(
     return ToolCall(name=name, args=args, id=id, type="tool_call")
 
 
+class ToolCallChunk(TypedDict):
+    """A chunk of a tool call (e.g., as part of a stream).
+
+    When merging ToolCallChunks (e.g., via AIMessageChunk.__add__),
+    all string attributes are concatenated. Chunks are only merged if their
+    values of `index` are equal and not None.
+
+    Example:
+
+    .. code-block:: python
+
+        left_chunks = [ToolCallChunk(name="foo", args='{"a":', index=0)]
+        right_chunks = [ToolCallChunk(name=None, args='1}', index=0)]
+
+        (
+            AIMessageChunk(content="", tool_call_chunks=left_chunks)
+            + AIMessageChunk(content="", tool_call_chunks=right_chunks)
+        ).tool_call_chunks == [ToolCallChunk(name='foo', args='{"a":1}', index=0)]
+
+    """
+
+    name: Optional[str]
+    """The name of the tool to be called."""
+    args: Optional[str]
+    """The arguments to the tool call."""
+    id: Optional[str]
+    """An identifier associated with the tool call."""
+    index: Optional[int]
+    """The index of the tool call in a sequence."""
+    type: NotRequired[Literal["tool_call_chunk"]]
+
+
 def tool_call_chunk(
     *,
     name: Optional[str] = None,

langchain_core/messages/utils.py

@@ -31,21 +31,18 @@ from typing import (
 from pydantic import Discriminator, Field, Tag
 
 from langchain_core.exceptions import ErrorCode, create_message
-from langchain_core.messages import convert_to_openai_data_block, is_data_content_block
 from langchain_core.messages.ai import AIMessage, AIMessageChunk
 from langchain_core.messages.base import BaseMessage, BaseMessageChunk
 from langchain_core.messages.chat import ChatMessage, ChatMessageChunk
+from langchain_core.messages.content import (
+    convert_to_openai_data_block,
+    is_data_content_block,
+)
 from langchain_core.messages.function import FunctionMessage, FunctionMessageChunk
 from langchain_core.messages.human import HumanMessage, HumanMessageChunk
 from langchain_core.messages.modifier import RemoveMessage
 from langchain_core.messages.system import SystemMessage, SystemMessageChunk
 from langchain_core.messages.tool import ToolCall, ToolMessage, ToolMessageChunk
-from langchain_core.v1.messages import AIMessage as AIMessageV1
-from langchain_core.v1.messages import AIMessageChunk as AIMessageChunkV1
-from langchain_core.v1.messages import HumanMessage as HumanMessageV1
-from langchain_core.v1.messages import MessageV1, MessageV1Types
-from langchain_core.v1.messages import SystemMessage as SystemMessageV1
-from langchain_core.v1.messages import ToolMessage as ToolMessageV1
 
 if TYPE_CHECKING:
     from langchain_text_splitters import TextSplitter
@@ -136,7 +133,7 @@ def get_buffer_string(
         else:
             msg = f"Got unsupported message type: {m}"
             raise ValueError(msg)  # noqa: TRY004
-        message = f"{role}: {m.text()}"
+        message = f"{role}: {m.text}"
         if isinstance(m, AIMessage) and "function_call" in m.additional_kwargs:
             message += f"{m.additional_kwargs['function_call']}"
         string_messages.append(message)
@@ -202,14 +199,14 @@ def message_chunk_to_message(chunk: BaseMessageChunk) -> BaseMessage:
     # chunk classes always have the equivalent non-chunk class as their first parent
     ignore_keys = ["type"]
     if isinstance(chunk, AIMessageChunk):
-        ignore_keys.append("tool_call_chunks")
+        ignore_keys.extend(["tool_call_chunks", "chunk_position"])
     return chunk.__class__.__mro__[1](
         **{k: v for k, v in chunk.__dict__.items() if k not in ignore_keys}
     )
 
 
 MessageLikeRepresentation = Union[
-    BaseMessage, list[str], tuple[str, str], str, dict[str, Any], MessageV1
+    BaseMessage, list[str], tuple[str, str], str, dict[str, Any]
 ]
 
 
@@ -300,130 +297,6 @@ def _create_message_from_message_type(
     return message
 
 
-def _create_message_from_message_type_v1(
-    message_type: str,
-    content: str,
-    name: Optional[str] = None,
-    tool_call_id: Optional[str] = None,
-    tool_calls: Optional[list[dict[str, Any]]] = None,
-    id: Optional[str] = None,
-    **kwargs: Any,
-) -> MessageV1:
-    """Create a message from a message type and content string.
-
-    Args:
-        message_type: (str) the type of the message (e.g., "human", "ai", etc.).
-        content: (str) the content string.
-        name: (str) the name of the message. Default is None.
-        tool_call_id: (str) the tool call id. Default is None.
-        tool_calls: (list[dict[str, Any]]) the tool calls. Default is None.
-        id: (str) the id of the message. Default is None.
-        kwargs: (dict[str, Any]) additional keyword arguments.
-
-    Returns:
-        a message of the appropriate type.
-
-    Raises:
-        ValueError: if the message type is not one of "human", "user", "ai",
-            "assistant", "tool", "system", or "developer".
-    """
-    if name is not None:
-        kwargs["name"] = name
-    if tool_call_id is not None:
-        kwargs["tool_call_id"] = tool_call_id
-    if kwargs and (response_metadata := kwargs.pop("response_metadata", None)):
-        kwargs["response_metadata"] = response_metadata
-    if id is not None:
-        kwargs["id"] = id
-    if tool_calls is not None:
-        kwargs["tool_calls"] = []
-        for tool_call in tool_calls:
-            # Convert OpenAI-format tool call to LangChain format.
-            if "function" in tool_call:
-                args = tool_call["function"]["arguments"]
-                if isinstance(args, str):
-                    args = json.loads(args, strict=False)
-                kwargs["tool_calls"].append(
-                    {
-                        "name": tool_call["function"]["name"],
-                        "args": args,
-                        "id": tool_call["id"],
-                        "type": "tool_call",
-                    }
-                )
-            else:
-                kwargs["tool_calls"].append(tool_call)
-    if message_type in {"human", "user"}:
-        message: MessageV1 = HumanMessageV1(content=content, **kwargs)
-    elif message_type in {"ai", "assistant"}:
-        message = AIMessageV1(content=content, **kwargs)
-    elif message_type in {"system", "developer"}:
-        if message_type == "developer":
-            kwargs["custom_role"] = "developer"
-        message = SystemMessageV1(content=content, **kwargs)
-    elif message_type == "tool":
-        artifact = kwargs.pop("artifact", None)
-        message = ToolMessageV1(content=content, artifact=artifact, **kwargs)
-    else:
-        msg = (
-            f"Unexpected message type: '{message_type}'. Use one of 'human',"
-            f" 'user', 'ai', 'assistant', 'function', 'tool', 'system', or 'developer'."
-        )
-        msg = create_message(message=msg, error_code=ErrorCode.MESSAGE_COERCION_FAILURE)
-        raise ValueError(msg)
-    return message
-
-
-def convert_from_v1_message(message: MessageV1) -> BaseMessage:
-    """Compatibility layer to convert v1 messages to current messages.
-
-    Args:
-        message: MessageV1 instance to convert.
-
-    Returns:
-        BaseMessage: Converted message instance.
-    """
-    content = cast("Union[str, list[str | dict]]", message.content)
-    if isinstance(message, AIMessageV1):
-        return AIMessage(
-            content=content,
-            id=message.id,
-            name=message.name,
-            tool_calls=message.tool_calls,
-            response_metadata=cast("dict", message.response_metadata),
-        )
-    if isinstance(message, AIMessageChunkV1):
-        return AIMessageChunk(
-            content=content,
-            id=message.id,
-            name=message.name,
-            tool_call_chunks=message.tool_call_chunks,
-            response_metadata=cast("dict", message.response_metadata),
-        )
-    if isinstance(message, HumanMessageV1):
-        return HumanMessage(
-            content=content,
-            id=message.id,
-            name=message.name,
-        )
-    if isinstance(message, SystemMessageV1):
-        return SystemMessage(
-            content=content,
-            id=message.id,
-        )
-    if isinstance(message, ToolMessageV1):
-        return ToolMessage(
-            content=content,
-            id=message.id,
-            tool_call_id=message.tool_call_id,
-            artifact=message.artifact,
-            name=message.name,
-            status=message.status,
-        )
-    message = f"Unsupported message type: {type(message)}"
-    raise NotImplementedError(message)
-
-
 def _convert_to_message(message: MessageLikeRepresentation) -> BaseMessage:
     """Instantiate a message from a variety of message formats.
 
@@ -471,66 +344,6 @@ def _convert_to_message(message: MessageLikeRepresentation) -> BaseMessage:
         message_ = _create_message_from_message_type(
             msg_type, msg_content, **msg_kwargs
         )
-    elif isinstance(message, MessageV1Types):
-        message_ = convert_from_v1_message(message)
-    else:
-        msg = f"Unsupported message type: {type(message)}"
-        msg = create_message(message=msg, error_code=ErrorCode.MESSAGE_COERCION_FAILURE)
-        raise NotImplementedError(msg)
-
-    return message_
-
-
-def _convert_to_message_v1(message: MessageLikeRepresentation) -> MessageV1:
-    """Instantiate a message from a variety of message formats.
-
-    The message format can be one of the following:
-
-    - BaseMessagePromptTemplate
-    - BaseMessage
-    - 2-tuple of (role string, template); e.g., ("human", "{user_input}")
-    - dict: a message dict with role and content keys
-    - string: shorthand for ("human", template); e.g., "{user_input}"
-
-    Args:
-        message: a representation of a message in one of the supported formats.
-
-    Returns:
-        an instance of a message or a message template.
-
-    Raises:
-        NotImplementedError: if the message type is not supported.
-        ValueError: if the message dict does not contain the required keys.
-    """
-    if isinstance(message, MessageV1Types):
-        if isinstance(message, AIMessageChunkV1):
-            message_: MessageV1 = message.to_message()
-        else:
-            message_ = message
-    elif isinstance(message, str):
-        message_ = _create_message_from_message_type_v1("human", message)
-    elif isinstance(message, Sequence) and len(message) == 2:
-        # mypy doesn't realise this can't be a string given the previous branch
-        message_type_str, template = message  # type: ignore[misc]
-        message_ = _create_message_from_message_type_v1(message_type_str, template)
-    elif isinstance(message, dict):
-        msg_kwargs = message.copy()
-        try:
-            try:
-                msg_type = msg_kwargs.pop("role")
-            except KeyError:
-                msg_type = msg_kwargs.pop("type")
-            # None msg content is not allowed
-            msg_content = msg_kwargs.pop("content") or ""
-        except KeyError as e:
-            msg = f"Message dict must contain 'role' and 'content' keys, got {message}"
-            msg = create_message(
-                message=msg, error_code=ErrorCode.MESSAGE_COERCION_FAILURE
-            )
-            raise ValueError(msg) from e
-        message_ = _create_message_from_message_type_v1(
-            msg_type, msg_content, **msg_kwargs
-        )
     else:
         msg = f"Unsupported message type: {type(message)}"
         msg = create_message(message=msg, error_code=ErrorCode.MESSAGE_COERCION_FAILURE)
@@ -558,25 +371,6 @@ def convert_to_messages(
     return [_convert_to_message(m) for m in messages]
 
 
-def convert_to_messages_v1(
-    messages: Union[Iterable[MessageLikeRepresentation], PromptValue],
-) -> list[MessageV1]:
-    """Convert a sequence of messages to a list of messages.
-
-    Args:
-        messages: Sequence of messages to convert.
-
-    Returns:
-        list of messages (BaseMessages).
-    """
-    # Import here to avoid circular imports
-    from langchain_core.prompt_values import PromptValue
-
-    if isinstance(messages, PromptValue):
-        return messages.to_messages(message_version="v1")
-    return [_convert_to_message_v1(m) for m in messages]
-
-
 def _runnable_support(func: Callable) -> Callable:
     @overload
     def wrapped(
@@ -865,22 +659,23 @@ def trim_messages(
     properties:
 
     1. The resulting chat history should be valid. Most chat models expect that chat
-       history starts with either (1) a `HumanMessage` or (2) a `SystemMessage` followed
-       by a `HumanMessage`. To achieve this, set `start_on="human"`.
-       In addition, generally a `ToolMessage` can only appear after an `AIMessage`
+       history starts with either (1) a ``HumanMessage`` or (2) a ``SystemMessage`` followed
+       by a ``HumanMessage``. To achieve this, set ``start_on="human"``.
+       In addition, generally a ``ToolMessage`` can only appear after an ``AIMessage``
        that involved a tool call.
        Please see the following link for more information about messages:
        https://python.langchain.com/docs/concepts/#messages
     2. It includes recent messages and drops old messages in the chat history.
-       To achieve this set the `strategy="last"`.
-    3. Usually, the new chat history should include the `SystemMessage` if it
-       was present in the original chat history since the `SystemMessage` includes
-       special instructions to the chat model. The `SystemMessage` is almost always
+       To achieve this set the ``strategy="last"``.
+    3. Usually, the new chat history should include the ``SystemMessage`` if it
+       was present in the original chat history since the ``SystemMessage`` includes
+       special instructions to the chat model. The ``SystemMessage`` is almost always
        the first message in the history if present. To achieve this set the
-       `include_system=True`.
+       ``include_system=True``.
 
-    **Note** The examples below show how to configure `trim_messages` to achieve
-        a behavior consistent with the above properties.
+    .. note::
+        The examples below show how to configure ``trim_messages`` to achieve a behavior
+        consistent with the above properties.
 
     Args:
         messages: Sequence of Message-like objects to trim.
@@ -1216,11 +1011,10 @@ def convert_to_openai_messages(
 
     oai_messages: list = []
 
-    if is_single := isinstance(messages, (BaseMessage, dict, str, MessageV1Types)):
+    if is_single := isinstance(messages, (BaseMessage, dict, str)):
         messages = [messages]
 
-    # TODO: resolve type ignore here
-    messages = convert_to_messages(messages)  # type: ignore[arg-type]
+    messages = convert_to_messages(messages)
 
     for i, message in enumerate(messages):
         oai_msg: dict = {"role": _get_message_openai_role(message)}
@@ -1707,11 +1501,15 @@ def _msg_to_chunk(message: BaseMessage) -> BaseMessageChunk:
 def _chunk_to_msg(chunk: BaseMessageChunk) -> BaseMessage:
     if chunk.__class__ in _CHUNK_MSG_MAP:
         return _CHUNK_MSG_MAP[chunk.__class__](
-            **chunk.model_dump(exclude={"type", "tool_call_chunks"})
+            **chunk.model_dump(exclude={"type", "tool_call_chunks", "chunk_position"})
         )
     for chunk_cls, msg_cls in _CHUNK_MSG_MAP.items():
         if isinstance(chunk, chunk_cls):
-            return msg_cls(**chunk.model_dump(exclude={"type", "tool_call_chunks"}))
+            return msg_cls(
+                **chunk.model_dump(
+                    exclude={"type", "tool_call_chunks", "chunk_position"}
+                )
+            )
 
     msg = (
         f"Unrecognized message chunk class {chunk.__class__}. Supported classes are "
@@ -1790,26 +1588,26 @@ def count_tokens_approximately(
         chars_per_token: Number of characters per token to use for the approximation.
             Default is 4 (one token corresponds to ~4 chars for common English text).
             You can also specify float values for more fine-grained control.
-            See more here: https://platform.openai.com/tokenizer
+            `See more here. <https://platform.openai.com/tokenizer>`__
         extra_tokens_per_message: Number of extra tokens to add per message.
             Default is 3 (special tokens, including beginning/end of message).
             You can also specify float values for more fine-grained control.
-            See more here:
-            https://github.com/openai/openai-cookbook/blob/main/examples/How_to_count_tokens_with_tiktoken.ipynb
+            `See more here. <https://github.com/openai/openai-cookbook/blob/main/examples/How_to_count_tokens_with_tiktoken.ipynb>`__
         count_name: Whether to include message names in the count.
             Enabled by default.
 
     Returns:
         Approximate number of tokens in the messages.
 
-    Note:
-        This is a simple approximation that may not match the exact token count
-        used by specific models. For accurate counts, use model-specific tokenizers.
+    .. note::
+        This is a simple approximation that may not match the exact token count used by
+        specific models. For accurate counts, use model-specific tokenizers.
 
     Warning:
         This function does not currently support counting image tokens.
 
     .. versionadded:: 0.3.46
+
     """
     token_count = 0.0
     for message in convert_to_messages(messages):