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

langchain_core/messages/utils.py

@@ -14,16 +14,13 @@ import inspect
 import json
 import logging
 import math
-from collections.abc import Iterable, Sequence
+from collections.abc import Callable, Iterable, Sequence
 from functools import partial
 from typing import (
     TYPE_CHECKING,
     Annotated,
     Any,
-    Callable,
     Literal,
-    Optional,
-    Union,
     cast,
     overload,
 )
@@ -31,29 +28,33 @@ 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.block_translators.openai import (
+    convert_to_openai_data_block,
+)
 from langchain_core.messages.chat import ChatMessage, ChatMessageChunk
+from langchain_core.messages.content import (
+    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
-
     from langchain_core.language_models import BaseLanguageModel
     from langchain_core.prompt_values import PromptValue
     from langchain_core.runnables.base import Runnable
 
+try:
+    from langchain_text_splitters import TextSplitter
+
+    _HAS_LANGCHAIN_TEXT_SPLITTERS = True
+except ImportError:
+    _HAS_LANGCHAIN_TEXT_SPLITTERS = False
+
 logger = logging.getLogger(__name__)
 
 
@@ -71,34 +72,32 @@ def _get_type(v: Any) -> str:
 
 
 AnyMessage = Annotated[
-    Union[
-        Annotated[AIMessage, Tag(tag="ai")],
-        Annotated[HumanMessage, Tag(tag="human")],
-        Annotated[ChatMessage, Tag(tag="chat")],
-        Annotated[SystemMessage, Tag(tag="system")],
-        Annotated[FunctionMessage, Tag(tag="function")],
-        Annotated[ToolMessage, Tag(tag="tool")],
-        Annotated[AIMessageChunk, Tag(tag="AIMessageChunk")],
-        Annotated[HumanMessageChunk, Tag(tag="HumanMessageChunk")],
-        Annotated[ChatMessageChunk, Tag(tag="ChatMessageChunk")],
-        Annotated[SystemMessageChunk, Tag(tag="SystemMessageChunk")],
-        Annotated[FunctionMessageChunk, Tag(tag="FunctionMessageChunk")],
-        Annotated[ToolMessageChunk, Tag(tag="ToolMessageChunk")],
-    ],
+    Annotated[AIMessage, Tag(tag="ai")]
+    | Annotated[HumanMessage, Tag(tag="human")]
+    | Annotated[ChatMessage, Tag(tag="chat")]
+    | Annotated[SystemMessage, Tag(tag="system")]
+    | Annotated[FunctionMessage, Tag(tag="function")]
+    | Annotated[ToolMessage, Tag(tag="tool")]
+    | Annotated[AIMessageChunk, Tag(tag="AIMessageChunk")]
+    | Annotated[HumanMessageChunk, Tag(tag="HumanMessageChunk")]
+    | Annotated[ChatMessageChunk, Tag(tag="ChatMessageChunk")]
+    | Annotated[SystemMessageChunk, Tag(tag="SystemMessageChunk")]
+    | Annotated[FunctionMessageChunk, Tag(tag="FunctionMessageChunk")]
+    | Annotated[ToolMessageChunk, Tag(tag="ToolMessageChunk")],
     Field(discriminator=Discriminator(_get_type)),
 ]
+""""A type representing any defined `Message` or `MessageChunk` type."""
 
 
 def get_buffer_string(
     messages: Sequence[BaseMessage], human_prefix: str = "Human", ai_prefix: str = "AI"
 ) -> str:
-    r"""Convert a sequence of Messages to strings and concatenate them into one string.
+    r"""Convert a sequence of messages to strings and concatenate them into one string.
 
     Args:
         messages: Messages to be converted to strings.
-        human_prefix: The prefix to prepend to contents of HumanMessages.
-            Default is "Human".
-        ai_prefix: THe prefix to prepend to contents of AIMessages. Default is "AI".
+        human_prefix: The prefix to prepend to contents of `HumanMessage`s.
+        ai_prefix: The prefix to prepend to contents of `AIMessage`.
 
     Returns:
         A single string concatenation of all input messages.
@@ -107,17 +106,16 @@ def get_buffer_string(
         ValueError: If an unsupported message type is encountered.
 
     Example:
-        .. code-block:: python
-
-            from langchain_core import AIMessage, HumanMessage
-
-            messages = [
-                HumanMessage(content="Hi, how are you?"),
-                AIMessage(content="Good, how are you?"),
-            ]
-            get_buffer_string(messages)
-            # -> "Human: Hi, how are you?\nAI: Good, how are you?"
-
+        ```python
+        from langchain_core import AIMessage, HumanMessage
+
+        messages = [
+            HumanMessage(content="Hi, how are you?"),
+            AIMessage(content="Good, how are you?"),
+        ]
+        get_buffer_string(messages)
+        # -> "Human: Hi, how are you?\nAI: Good, how are you?"
+        ```
     """
     string_messages = []
     for m in messages:
@@ -136,7 +134,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)
@@ -177,19 +175,20 @@ def _message_from_dict(message: dict) -> BaseMessage:
 
 
 def messages_from_dict(messages: Sequence[dict]) -> list[BaseMessage]:
-    """Convert a sequence of messages from dicts to Message objects.
+    """Convert a sequence of messages from dicts to `Message` objects.
 
     Args:
         messages: Sequence of messages (as dicts) to convert.
 
     Returns:
         list of messages (BaseMessages).
+
     """
     return [_message_from_dict(m) for m in messages]
 
 
-def message_chunk_to_message(chunk: BaseMessageChunk) -> BaseMessage:
-    """Convert a message chunk to a message.
+def message_chunk_to_message(chunk: BaseMessage) -> BaseMessage:
+    """Convert a message chunk to a `Message`.
 
     Args:
         chunk: Message chunk to convert.
@@ -202,43 +201,45 @@ 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
-]
+MessageLikeRepresentation = (
+    BaseMessage | list[str] | tuple[str, str] | str | dict[str, Any]
+)
+"""A type representing the various ways a message can be represented."""
 
 
 def _create_message_from_message_type(
     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,
+    name: str | None = None,
+    tool_call_id: str | None = None,
+    tool_calls: list[dict[str, Any]] | None = None,
+    id: str | None = None,
     **additional_kwargs: Any,
 ) -> BaseMessage:
-    """Create a message from a message type and content string.
+    """Create a message from a `Message` type and content string.
 
     Args:
-        message_type: (str) the type of the message (e.g., "human", "ai", etc.).
+        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.
+        name: (str) the name of the message.
+        tool_call_id: (str) the tool call id.
+        tool_calls: (list[dict[str, Any]]) the tool calls.
+        id: (str) the id of the message.
         additional_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", "function", "tool", "system", or "developer".
+        ValueError: if the message type is not one of `'human'`, `'user'`, `'ai'`,
+            `'assistant'`, `'function'`, `'tool'`, `'system'`, or
+            `'developer'`.
     """
     kwargs: dict[str, Any] = {}
     if name is not None:
@@ -287,6 +288,9 @@ def _create_message_from_message_type(
         message = FunctionMessage(content=content, **kwargs)
     elif message_type == "tool":
         artifact = kwargs.get("additional_kwargs", {}).pop("artifact", None)
+        status = kwargs.get("additional_kwargs", {}).pop("status", None)
+        if status is not None:
+            kwargs["status"] = status
         message = ToolMessage(content=content, artifact=artifact, **kwargs)
     elif message_type == "remove":
         message = RemoveMessage(**kwargs)
@@ -300,150 +304,27 @@ 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.
+    """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}")
+    - `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}"
+    - 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.
+        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, BaseMessage):
         message_ = message
@@ -471,66 +352,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)
@@ -540,7 +361,7 @@ def _convert_to_message_v1(message: MessageLikeRepresentation) -> MessageV1:
 
 
 def convert_to_messages(
-    messages: Union[Iterable[MessageLikeRepresentation], PromptValue],
+    messages: Iterable[MessageLikeRepresentation] | PromptValue,
 ) -> list[BaseMessage]:
     """Convert a sequence of messages to a list of messages.
 
@@ -549,34 +370,16 @@ def convert_to_messages(
 
     Returns:
         list of messages (BaseMessages).
+
     """
     # Import here to avoid circular imports
-    from langchain_core.prompt_values import PromptValue
+    from langchain_core.prompt_values import PromptValue  # noqa: PLC0415
 
     if isinstance(messages, PromptValue):
         return messages.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(
@@ -589,13 +392,14 @@ def _runnable_support(func: Callable) -> Callable:
     ) -> list[BaseMessage]: ...
 
     def wrapped(
-        messages: Union[Sequence[MessageLikeRepresentation], None] = None,
+        messages: Sequence[MessageLikeRepresentation] | None = None,
         **kwargs: Any,
-    ) -> Union[
-        list[BaseMessage],
-        Runnable[Sequence[MessageLikeRepresentation], list[BaseMessage]],
-    ]:
-        from langchain_core.runnables.base import RunnableLambda
+    ) -> (
+        list[BaseMessage]
+        | Runnable[Sequence[MessageLikeRepresentation], list[BaseMessage]]
+    ):
+        # Import locally to prevent circular import.
+        from langchain_core.runnables.base import RunnableLambda  # noqa: PLC0415
 
         if messages is not None:
             return func(messages, **kwargs)
@@ -607,74 +411,89 @@ def _runnable_support(func: Callable) -> Callable:
 
 @_runnable_support
 def filter_messages(
-    messages: Union[Iterable[MessageLikeRepresentation], PromptValue],
+    messages: Iterable[MessageLikeRepresentation] | PromptValue,
     *,
-    include_names: Optional[Sequence[str]] = None,
-    exclude_names: Optional[Sequence[str]] = None,
-    include_types: Optional[Sequence[Union[str, type[BaseMessage]]]] = None,
-    exclude_types: Optional[Sequence[Union[str, type[BaseMessage]]]] = None,
-    include_ids: Optional[Sequence[str]] = None,
-    exclude_ids: Optional[Sequence[str]] = None,
-    exclude_tool_calls: Optional[Sequence[str] | bool] = None,
+    include_names: Sequence[str] | None = None,
+    exclude_names: Sequence[str] | None = None,
+    include_types: Sequence[str | type[BaseMessage]] | None = None,
+    exclude_types: Sequence[str | type[BaseMessage]] | None = None,
+    include_ids: Sequence[str] | None = None,
+    exclude_ids: Sequence[str] | None = None,
+    exclude_tool_calls: Sequence[str] | bool | None = None,
 ) -> list[BaseMessage]:
-    """Filter messages based on name, type or id.
+    """Filter messages based on `name`, `type` or `id`.
 
     Args:
         messages: Sequence Message-like objects to filter.
-        include_names: Message names to include. Default is None.
-        exclude_names: Messages names to exclude. Default is None.
-        include_types: Message types to include. Can be specified as string names (e.g.
-            "system", "human", "ai", ...) or as BaseMessage classes (e.g.
-            SystemMessage, HumanMessage, AIMessage, ...). Default is None.
-        exclude_types: Message types to exclude. Can be specified as string names (e.g.
-            "system", "human", "ai", ...) or as BaseMessage classes (e.g.
-            SystemMessage, HumanMessage, AIMessage, ...). Default is None.
-        include_ids: Message IDs to include. Default is None.
-        exclude_ids: Message IDs to exclude. Default is None.
-        exclude_tool_calls: Tool call IDs to exclude. Default is None.
+        include_names: Message names to include.
+        exclude_names: Messages names to exclude.
+        include_types: Message types to include. Can be specified as string names
+            (e.g. `'system'`, `'human'`, `'ai'`, ...) or as `BaseMessage`
+            classes (e.g. `SystemMessage`, `HumanMessage`, `AIMessage`, ...).
+
+        exclude_types: Message types to exclude. Can be specified as string names
+            (e.g. `'system'`, `'human'`, `'ai'`, ...) or as `BaseMessage`
+            classes (e.g. `SystemMessage`, `HumanMessage`, `AIMessage`, ...).
+
+        include_ids: Message IDs to include.
+        exclude_ids: Message IDs to exclude.
+        exclude_tool_calls: Tool call IDs to exclude.
             Can be one of the following:
-            - `True`: all AIMessages with tool calls and all ToolMessages will be excluded.
+            - `True`: all `AIMessage`s with tool calls and all
+                `ToolMessage` objects will be excluded.
             - a sequence of tool call IDs to exclude:
-              - ToolMessages with the corresponding tool call ID will be excluded.
-              - The `tool_calls` in the AIMessage will be updated to exclude matching tool calls.
-                If all tool_calls are filtered from an AIMessage, the whole message is excluded.
+                - `ToolMessage` objects with the corresponding tool call ID will be
+                    excluded.
+                - The `tool_calls` in the AIMessage will be updated to exclude
+                    matching tool calls. If all `tool_calls` are filtered from an
+                    AIMessage, the whole message is excluded.
 
     Returns:
-        A list of Messages that meets at least one of the incl_* conditions and none
-        of the excl_* conditions. If not incl_* conditions are specified then
+        A list of Messages that meets at least one of the `incl_*` conditions and none
+        of the `excl_*` conditions. If not `incl_*` conditions are specified then
         anything that is not explicitly excluded will be included.
 
     Raises:
-        ValueError if two incompatible arguments are provided.
+        ValueError: If two incompatible arguments are provided.
 
     Example:
-        .. code-block:: python
-
-            from langchain_core.messages import filter_messages, AIMessage, HumanMessage, SystemMessage
-
-            messages = [
-                SystemMessage("you're a good assistant."),
-                HumanMessage("what's your name", id="foo", name="example_user"),
-                AIMessage("steve-o", id="bar", name="example_assistant"),
-                HumanMessage("what's your favorite color", id="baz",),
-                AIMessage("silicon blue", id="blah",),
-            ]
-
-            filter_messages(
-                messages,
-                incl_names=("example_user", "example_assistant"),
-                incl_types=("system",),
-                excl_ids=("bar",),
-            )
-
-        .. code-block:: python
-
-            [
-                SystemMessage("you're a good assistant."),
-                HumanMessage("what's your name", id="foo", name="example_user"),
-            ]
+        ```python
+        from langchain_core.messages import (
+            filter_messages,
+            AIMessage,
+            HumanMessage,
+            SystemMessage,
+        )
 
-    """  # noqa: E501
+        messages = [
+            SystemMessage("you're a good assistant."),
+            HumanMessage("what's your name", id="foo", name="example_user"),
+            AIMessage("steve-o", id="bar", name="example_assistant"),
+            HumanMessage(
+                "what's your favorite color",
+                id="baz",
+            ),
+            AIMessage(
+                "silicon blue",
+                id="blah",
+            ),
+        ]
+
+        filter_messages(
+            messages,
+            incl_names=("example_user", "example_assistant"),
+            incl_types=("system",),
+            excl_ids=("bar",),
+        )
+        ```
+
+        ```python
+        [
+            SystemMessage("you're a good assistant."),
+            HumanMessage("what's your name", id="foo", name="example_user"),
+        ]
+        ```
+    """
     messages = convert_to_messages(messages)
     filtered: list[BaseMessage] = []
     for msg in messages:
@@ -736,76 +555,107 @@ def filter_messages(
 
 @_runnable_support
 def merge_message_runs(
-    messages: Union[Iterable[MessageLikeRepresentation], PromptValue],
+    messages: Iterable[MessageLikeRepresentation] | PromptValue,
     *,
     chunk_separator: str = "\n",
 ) -> list[BaseMessage]:
     r"""Merge consecutive Messages of the same type.
 
-    **NOTE**: ToolMessages are not merged, as each has a distinct tool call id that
-    can't be merged.
+    !!! note
+        `ToolMessage` objects are not merged, as each has a distinct tool call id that
+        can't be merged.
 
     Args:
         messages: Sequence Message-like objects to merge.
         chunk_separator: Specify the string to be inserted between message chunks.
-        Default is "\n".
 
     Returns:
         list of BaseMessages with consecutive runs of message types merged into single
         messages. By default, if two messages being merged both have string contents,
-        the merged content is a concatenation of the two strings with a new-line separator.
+        the merged content is a concatenation of the two strings with a new-line
+        separator.
         The separator inserted between message chunks can be controlled by specifying
-        any string with ``chunk_separator``. If at least one of the messages has a list of
-        content blocks, the merged content is a list of content blocks.
+        any string with `chunk_separator`. If at least one of the messages has a list
+        of content blocks, the merged content is a list of content blocks.
 
     Example:
-        .. code-block:: python
-
-            from langchain_core.messages import (
-                merge_message_runs,
-                AIMessage,
-                HumanMessage,
-                SystemMessage,
-                ToolCall,
-            )
+        ```python
+        from langchain_core.messages import (
+            merge_message_runs,
+            AIMessage,
+            HumanMessage,
+            SystemMessage,
+            ToolCall,
+        )
 
-            messages = [
-                SystemMessage("you're a good assistant."),
-                HumanMessage("what's your favorite color", id="foo",),
-                HumanMessage("wait your favorite food", id="bar",),
-                AIMessage(
+        messages = [
+            SystemMessage("you're a good assistant."),
+            HumanMessage(
+                "what's your favorite color",
+                id="foo",
+            ),
+            HumanMessage(
+                "wait your favorite food",
+                id="bar",
+            ),
+            AIMessage(
+                "my favorite colo",
+                tool_calls=[
+                    ToolCall(
+                        name="blah_tool", args={"x": 2}, id="123", type="tool_call"
+                    )
+                ],
+                id="baz",
+            ),
+            AIMessage(
+                [{"type": "text", "text": "my favorite dish is lasagna"}],
+                tool_calls=[
+                    ToolCall(
+                        name="blah_tool",
+                        args={"x": -10},
+                        id="456",
+                        type="tool_call",
+                    )
+                ],
+                id="blur",
+            ),
+        ]
+
+        merge_message_runs(messages)
+        ```
+
+        ```python
+        [
+            SystemMessage("you're a good assistant."),
+            HumanMessage(
+                "what's your favorite color\\n"
+                "wait your favorite food", id="foo",
+            ),
+            AIMessage(
+                [
                     "my favorite colo",
-                    tool_calls=[ToolCall(name="blah_tool", args={"x": 2}, id="123", type="tool_call")],
-                    id="baz",
-                ),
-                AIMessage(
-                    [{"type": "text", "text": "my favorite dish is lasagna"}],
-                    tool_calls=[ToolCall(name="blah_tool", args={"x": -10}, id="456", type="tool_call")],
-                    id="blur",
-                ),
-            ]
-
-            merge_message_runs(messages)
-
-        .. code-block:: python
-
-            [
-                SystemMessage("you're a good assistant."),
-                HumanMessage("what's your favorite color\\nwait your favorite food", id="foo",),
-                AIMessage(
-                    [
-                        "my favorite colo",
-                        {"type": "text", "text": "my favorite dish is lasagna"}
-                    ],
-                    tool_calls=[
-                        ToolCall({"name": "blah_tool", "args": {"x": 2}, "id": "123", "type": "tool_call"}),
-                        ToolCall({"name": "blah_tool", "args": {"x": -10}, "id": "456", "type": "tool_call"})
-                    ]
-                    id="baz"
-                ),
-            ]
+                    {"type": "text", "text": "my favorite dish is lasagna"}
+                ],
+                tool_calls=[
+                    ToolCall({
+                        "name": "blah_tool",
+                        "args": {"x": 2},
+                        "id": "123",
+                        "type": "tool_call"
+                    }),
+                    ToolCall({
+                        "name": "blah_tool",
+                        "args": {"x": -10},
+                        "id": "456",
+                        "type": "tool_call"
+                    })
+                ]
+                id="baz"
+            ),
+        ]
 
-    """  # noqa: E501
+        ```
+    """
     if not messages:
         return []
     messages = convert_to_messages(messages)
@@ -836,165 +686,161 @@ def merge_message_runs(
 # init not at runtime.
 @_runnable_support
 def trim_messages(
-    messages: Union[Iterable[MessageLikeRepresentation], PromptValue],
+    messages: Iterable[MessageLikeRepresentation] | PromptValue,
     *,
     max_tokens: int,
-    token_counter: Union[
-        Callable[[list[BaseMessage]], int],
-        Callable[[BaseMessage], int],
-        BaseLanguageModel,
-    ],
+    token_counter: Callable[[list[BaseMessage]], int]
+    | Callable[[BaseMessage], int]
+    | BaseLanguageModel,
     strategy: Literal["first", "last"] = "last",
     allow_partial: bool = False,
-    end_on: Optional[
-        Union[str, type[BaseMessage], Sequence[Union[str, type[BaseMessage]]]]
-    ] = None,
-    start_on: Optional[
-        Union[str, type[BaseMessage], Sequence[Union[str, type[BaseMessage]]]]
-    ] = None,
+    end_on: str | type[BaseMessage] | Sequence[str | type[BaseMessage]] | None = None,
+    start_on: str | type[BaseMessage] | Sequence[str | type[BaseMessage]] | None = None,
     include_system: bool = False,
-    text_splitter: Optional[Union[Callable[[str], list[str]], TextSplitter]] = None,
+    text_splitter: Callable[[str], list[str]] | TextSplitter | None = None,
 ) -> list[BaseMessage]:
     r"""Trim messages to be below a token count.
 
-    trim_messages can be used to reduce the size of a chat history to a specified token
-    count or specified message count.
+    `trim_messages` can be used to reduce the size of a chat history to a specified
+    token or message count.
 
     In either case, if passing the trimmed chat history back into a chat model
     directly, the resulting chat history should usually satisfy the following
     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`
-       that involved a tool call.
-       Please see the following link for more information about messages:
-       https://python.langchain.com/docs/concepts/#messages
+        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.
     2. It includes recent messages and drops old messages in the chat history.
-       To achieve this set the `strategy="last"`.
+        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`.
+        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`.
 
-    **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.
         max_tokens: Max token count of trimmed messages.
-        token_counter: Function or llm for counting tokens in a BaseMessage or a list of
-            BaseMessage. If a BaseLanguageModel is passed in then
-            BaseLanguageModel.get_num_tokens_from_messages() will be used.
+        token_counter: Function or llm for counting tokens in a `BaseMessage` or a
+            list of `BaseMessage`. If a `BaseLanguageModel` is passed in then
+            `BaseLanguageModel.get_num_tokens_from_messages()` will be used.
             Set to `len` to count the number of **messages** in the chat history.
 
-            .. note::
-                Use `count_tokens_approximately` to get fast, approximate token counts.
+            !!! note
+                Use `count_tokens_approximately` to get fast, approximate token
+                counts.
                 This is recommended for using `trim_messages` on the hot path, where
                 exact token counting is not necessary.
 
         strategy: Strategy for trimming.
-            - "first": Keep the first <= n_count tokens of the messages.
-            - "last": Keep the last <= n_count tokens of the messages.
-            Default is "last".
+            - `'first'`: Keep the first `<= n_count` tokens of the messages.
+            - `'last'`: Keep the last `<= n_count` tokens of the messages.
         allow_partial: Whether to split a message if only part of the message can be
-            included. If ``strategy="last"`` then the last partial contents of a message
-            are included. If ``strategy="first"`` then the first partial contents of a
+            included. If `strategy='last'` then the last partial contents of a message
+            are included. If `strategy='first'` then the first partial contents of a
             message are included.
-            Default is False.
         end_on: The message type to end on. If specified then every message after the
-            last occurrence of this type is ignored. If ``strategy=="last"`` then this
-            is done before we attempt to get the last ``max_tokens``. If
-            ``strategy=="first"`` then this is done after we get the first
-            ``max_tokens``. Can be specified as string names (e.g. "system", "human",
-            "ai", ...) or as BaseMessage classes (e.g. SystemMessage, HumanMessage,
-            AIMessage, ...). Can be a single type or a list of types.
-            Default is None.
+            last occurrence of this type is ignored. If `strategy='last'` then this
+            is done before we attempt to get the last `max_tokens`. If
+            `strategy='first'` then this is done after we get the first
+            `max_tokens`. Can be specified as string names (e.g. `'system'`,
+            `'human'`, `'ai'`, ...) or as `BaseMessage` classes (e.g.
+            `SystemMessage`, `HumanMessage`, `AIMessage`, ...). Can be a single
+            type or a list of types.
+
         start_on: The message type to start on. Should only be specified if
-            ``strategy="last"``. If specified then every message before
+            `strategy='last'`. If specified then every message before
             the first occurrence of this type is ignored. This is done after we trim
-            the initial messages to the last ``max_tokens``. Does not
-            apply to a SystemMessage at index 0 if ``include_system=True``. Can be
-            specified as string names (e.g. "system", "human", "ai", ...) or as
-            BaseMessage classes (e.g. SystemMessage, HumanMessage, AIMessage, ...). Can
-            be a single type or a list of types.
-            Default is None.
-        include_system: Whether to keep the SystemMessage if there is one at index 0.
-            Should only be specified if ``strategy="last"``.
-            Default is False.
-        text_splitter: Function or ``langchain_text_splitters.TextSplitter`` for
+            the initial messages to the last `max_tokens`. Does not
+            apply to a `SystemMessage` at index 0 if `include_system=True`. Can be
+            specified as string names (e.g. `'system'`, `'human'`, `'ai'`, ...) or
+            as `BaseMessage` classes (e.g. `SystemMessage`, `HumanMessage`,
+            `AIMessage`, ...). Can be a single type or a list of types.
+
+        include_system: Whether to keep the `SystemMessage` if there is one at index
+            `0`. Should only be specified if `strategy="last"`.
+        text_splitter: Function or `langchain_text_splitters.TextSplitter` for
             splitting the string contents of a message. Only used if
-            ``allow_partial=True``. If ``strategy="last"`` then the last split tokens
-            from a partial message will be included. if ``strategy=="first"`` then the
+            `allow_partial=True`. If `strategy='last'` then the last split tokens
+            from a partial message will be included. if `strategy='first'` then the
             first split tokens from a partial message will be included. Token splitter
             assumes that separators are kept, so that split contents can be directly
             concatenated to recreate the original text. Defaults to splitting on
             newlines.
 
     Returns:
-        list of trimmed BaseMessages.
+        List of trimmed `BaseMessage`.
 
     Raises:
         ValueError: if two incompatible arguments are specified or an unrecognized
-            ``strategy`` is specified.
+            `strategy` is specified.
 
     Example:
-        Trim chat history based on token count, keeping the SystemMessage if
-        present, and ensuring that the chat history starts with a HumanMessage (
-        or a SystemMessage followed by a HumanMessage).
-
-        .. code-block:: python
-
-            from langchain_core.messages import (
-                AIMessage,
-                HumanMessage,
-                BaseMessage,
-                SystemMessage,
-                trim_messages,
-            )
-
-            messages = [
-                SystemMessage("you're a good assistant, you always respond with a joke."),
-                HumanMessage("i wonder why it's called langchain"),
-                AIMessage(
-                    'Well, I guess they thought "WordRope" and "SentenceString" just didn\'t have the same ring to it!'
-                ),
-                HumanMessage("and who is harrison chasing anyways"),
-                AIMessage(
-                    "Hmmm let me think.\n\nWhy, he's probably chasing after the last cup of coffee in the office!"
-                ),
-                HumanMessage("what do you call a speechless parrot"),
-            ]
-
-
-            trim_messages(
-                messages,
-                max_tokens=45,
-                strategy="last",
-                token_counter=ChatOpenAI(model="gpt-4o"),
-                # Most chat models expect that chat history starts with either:
-                # (1) a HumanMessage or
-                # (2) a SystemMessage followed by a HumanMessage
-                start_on="human",
-                # Usually, we want to keep the SystemMessage
-                # if it's present in the original history.
-                # The SystemMessage has special instructions for the model.
-                include_system=True,
-                allow_partial=False,
-            )
+        Trim chat history based on token count, keeping the `SystemMessage` if
+        present, and ensuring that the chat history starts with a `HumanMessage` (
+        or a `SystemMessage` followed by a `HumanMessage`).
+
+        ```python
+        from langchain_core.messages import (
+            AIMessage,
+            HumanMessage,
+            BaseMessage,
+            SystemMessage,
+            trim_messages,
+        )
 
-        .. code-block:: python
+        messages = [
+            SystemMessage("you're a good assistant, you always respond with a joke."),
+            HumanMessage("i wonder why it's called langchain"),
+            AIMessage(
+                'Well, I guess they thought "WordRope" and "SentenceString" just '
+                "didn't have the same ring to it!"
+            ),
+            HumanMessage("and who is harrison chasing anyways"),
+            AIMessage(
+                "Hmmm let me think.\n\nWhy, he's probably chasing after the last "
+                "cup of coffee in the office!"
+            ),
+            HumanMessage("what do you call a speechless parrot"),
+        ]
+
+
+        trim_messages(
+            messages,
+            max_tokens=45,
+            strategy="last",
+            token_counter=ChatOpenAI(model="gpt-4o"),
+            # Most chat models expect that chat history starts with either:
+            # (1) a HumanMessage or
+            # (2) a SystemMessage followed by a HumanMessage
+            start_on="human",
+            # Usually, we want to keep the SystemMessage
+            # if it's present in the original history.
+            # The SystemMessage has special instructions for the model.
+            include_system=True,
+            allow_partial=False,
+        )
+        ```
 
-            [
-                SystemMessage(content="you're a good assistant, you always respond with a joke."),
-                HumanMessage(content='what do you call a speechless parrot'),
-            ]
+        ```python
+        [
+            SystemMessage(
+                content="you're a good assistant, you always respond with a joke."
+            ),
+            HumanMessage(content="what do you call a speechless parrot"),
+        ]
+        ```
 
-        Trim chat history based on the message count, keeping the SystemMessage if
-        present, and ensuring that the chat history starts with a HumanMessage (
-        or a SystemMessage followed by a HumanMessage).
+        Trim chat history based on the message count, keeping the `SystemMessage` if
+        present, and ensuring that the chat history starts with a `HumanMessage` (
+        or a `SystemMessage` followed by a `HumanMessage`).
 
             trim_messages(
                 messages,
@@ -1016,72 +862,96 @@ def trim_messages(
                 allow_partial=False,
             )
 
-        .. code-block:: python
-
-            [
-                SystemMessage(content="you're a good assistant, you always respond with a joke."),
-                HumanMessage(content='and who is harrison chasing anyways'),
-                AIMessage(content="Hmmm let me think.\n\nWhy, he's probably chasing after the last cup of coffee in the office!"),
-                HumanMessage(content='what do you call a speechless parrot'),
-            ]
-
-
+        ```python
+        [
+            SystemMessage(
+                content="you're a good assistant, you always respond with a joke."
+            ),
+            HumanMessage(content="and who is harrison chasing anyways"),
+            AIMessage(
+                content="Hmmm let me think.\n\nWhy, he's probably chasing after "
+                "the last cup of coffee in the office!"
+            ),
+            HumanMessage(content="what do you call a speechless parrot"),
+        ]
+        ```
         Trim chat history using a custom token counter function that counts the
         number of tokens in each message.
 
-        .. code-block:: python
-
-            messages = [
-                SystemMessage("This is a 4 token text. The full message is 10 tokens."),
-                HumanMessage("This is a 4 token text. The full message is 10 tokens.", id="first"),
-                AIMessage(
-                    [
-                        {"type": "text", "text": "This is the FIRST 4 token block."},
-                        {"type": "text", "text": "This is the SECOND 4 token block."},
-                    ],
-                    id="second",
-                ),
-                HumanMessage("This is a 4 token text. The full message is 10 tokens.", id="third"),
-                AIMessage("This is a 4 token text. The full message is 10 tokens.", id="fourth"),
-            ]
-
-            def dummy_token_counter(messages: list[BaseMessage]) -> int:
-                # treat each message like it adds 3 default tokens at the beginning
-                # of the message and at the end of the message. 3 + 4 + 3 = 10 tokens
-                # per message.
-
-                default_content_len = 4
-                default_msg_prefix_len = 3
-                default_msg_suffix_len = 3
-
-                count = 0
-                for msg in messages:
-                    if isinstance(msg.content, str):
-                        count += default_msg_prefix_len + default_content_len + default_msg_suffix_len
-                    if isinstance(msg.content, list):
-                        count += default_msg_prefix_len + len(msg.content) *  default_content_len + default_msg_suffix_len
-                return count
-
-        First 30 tokens, allowing partial messages:
-            .. code-block:: python
-
-                trim_messages(
-                    messages,
-                    max_tokens=30,
-                    token_counter=dummy_token_counter,
-                    strategy="first",
-                    allow_partial=True,
-                )
-
-            .. code-block:: python
-
+        ```python
+        messages = [
+            SystemMessage("This is a 4 token text. The full message is 10 tokens."),
+            HumanMessage(
+                "This is a 4 token text. The full message is 10 tokens.", id="first"
+            ),
+            AIMessage(
                 [
-                    SystemMessage("This is a 4 token text. The full message is 10 tokens."),
-                    HumanMessage("This is a 4 token text. The full message is 10 tokens.", id="first"),
-                    AIMessage( [{"type": "text", "text": "This is the FIRST 4 token block."}], id="second"),
-                ]
+                    {"type": "text", "text": "This is the FIRST 4 token block."},
+                    {"type": "text", "text": "This is the SECOND 4 token block."},
+                ],
+                id="second",
+            ),
+            HumanMessage(
+                "This is a 4 token text. The full message is 10 tokens.", id="third"
+            ),
+            AIMessage(
+                "This is a 4 token text. The full message is 10 tokens.",
+                id="fourth",
+            ),
+        ]
+
+
+        def dummy_token_counter(messages: list[BaseMessage]) -> int:
+            # treat each message like it adds 3 default tokens at the beginning
+            # of the message and at the end of the message. 3 + 4 + 3 = 10 tokens
+            # per message.
+
+            default_content_len = 4
+            default_msg_prefix_len = 3
+            default_msg_suffix_len = 3
+
+            count = 0
+            for msg in messages:
+                if isinstance(msg.content, str):
+                    count += (
+                        default_msg_prefix_len
+                        + default_content_len
+                        + default_msg_suffix_len
+                    )
+                if isinstance(msg.content, list):
+                    count += (
+                        default_msg_prefix_len
+                        + len(msg.content) * default_content_len
+                        + default_msg_suffix_len
+                    )
+            return count
+        ```
 
-    """  # noqa: E501
+        First 30 tokens, allowing partial messages:
+        ```python
+        trim_messages(
+            messages,
+            max_tokens=30,
+            token_counter=dummy_token_counter,
+            strategy="first",
+            allow_partial=True,
+        )
+        ```
+
+        ```python
+        [
+            SystemMessage("This is a 4 token text. The full message is 10 tokens."),
+            HumanMessage(
+                "This is a 4 token text. The full message is 10 tokens.",
+                id="first",
+            ),
+            AIMessage(
+                [{"type": "text", "text": "This is the FIRST 4 token block."}],
+                id="second",
+            ),
+        ]
+        ```
+    """
     # Validate arguments
     if start_on and strategy == "first":
         msg = "start_on parameter is only valid with strategy='last'"
@@ -1112,17 +982,12 @@ def trim_messages(
         )
         raise ValueError(msg)
 
-    try:
-        from langchain_text_splitters import TextSplitter
-    except ImportError:
-        text_splitter_fn: Optional[Callable] = cast("Optional[Callable]", text_splitter)
+    if _HAS_LANGCHAIN_TEXT_SPLITTERS and isinstance(text_splitter, TextSplitter):
+        text_splitter_fn = text_splitter.split_text
+    elif text_splitter:
+        text_splitter_fn = cast("Callable", text_splitter)
     else:
-        if isinstance(text_splitter, TextSplitter):
-            text_splitter_fn = text_splitter.split_text
-        else:
-            text_splitter_fn = text_splitter
-
-    text_splitter_fn = text_splitter_fn or _default_text_splitter
+        text_splitter_fn = _default_text_splitter
 
     if strategy == "first":
         return _first_max_tokens(
@@ -1149,65 +1014,90 @@ def trim_messages(
 
 
 def convert_to_openai_messages(
-    messages: Union[MessageLikeRepresentation, Sequence[MessageLikeRepresentation]],
+    messages: MessageLikeRepresentation | Sequence[MessageLikeRepresentation],
     *,
     text_format: Literal["string", "block"] = "string",
-) -> Union[dict, list[dict]]:
+    include_id: bool = False,
+) -> dict | list[dict]:
     """Convert LangChain messages into OpenAI message dicts.
 
     Args:
         messages: Message-like object or iterable of objects whose contents are
             in OpenAI, Anthropic, Bedrock Converse, or VertexAI formats.
         text_format: How to format string or text block contents:
-
-                - "string":
+                - `'string'`:
                     If a message has a string content, this is left as a string. If
-                    a message has content blocks that are all of type 'text', these are
-                    joined with a newline to make a single string. If a message has
-                    content blocks and at least one isn't of type 'text', then
+                    a message has content blocks that are all of type `'text'`, these
+                    are joined with a newline to make a single string. If a message has
+                    content blocks and at least one isn't of type `'text'`, then
                     all blocks are left as dicts.
-                - "block":
+                - `'block'`:
                     If a message has a string content, this is turned into a list
-                    with a single content block of type 'text'. If a message has content
-                    blocks these are left as is.
+                    with a single content block of type `'text'`. If a message has
+                    content blocks these are left as is.
+        include_id: Whether to include message ids in the openai messages, if they
+                    are present in the source messages.
+
+    Raises:
+        ValueError: if an unrecognized `text_format` is specified, or if a message
+            content block is missing expected keys.
 
     Returns:
         The return type depends on the input type:
-            - dict:
-                If a single message-like object is passed in, a single OpenAI message
-                dict is returned.
-            - list[dict]:
-                If a sequence of message-like objects are passed in, a list of OpenAI
-                message dicts is returned.
-
-    Example:
 
-        .. code-block:: python
+        - dict:
+            If a single message-like object is passed in, a single OpenAI message
+            dict is returned.
+        - list[dict]:
+            If a sequence of message-like objects are passed in, a list of OpenAI
+            message dicts is returned.
 
-            from langchain_core.messages import (
-                convert_to_openai_messages,
-                AIMessage,
-                SystemMessage,
-                ToolMessage,
-            )
+    Example:
+        ```python
+        from langchain_core.messages import (
+            convert_to_openai_messages,
+            AIMessage,
+            SystemMessage,
+            ToolMessage,
+        )
 
-            messages = [
-                SystemMessage([{"type": "text", "text": "foo"}]),
-                {"role": "user", "content": [{"type": "text", "text": "whats in this"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,'/9j/4AAQSk'"}}]},
-                AIMessage("", tool_calls=[{"name": "analyze", "args": {"baz": "buz"}, "id": "1", "type": "tool_call"}]),
-                ToolMessage("foobar", tool_call_id="1", name="bar"),
-                {"role": "assistant", "content": "thats nice"},
-            ]
-            oai_messages = convert_to_openai_messages(messages)
-            # -> [
-            #   {'role': 'system', 'content': 'foo'},
-            #   {'role': 'user', 'content': [{'type': 'text', 'text': 'whats in this'}, {'type': 'image_url', 'image_url': {'url': "data:image/png;base64,'/9j/4AAQSk'"}}]},
-            #   {'role': 'assistant', 'tool_calls': [{'type': 'function', 'id': '1','function': {'name': 'analyze', 'arguments': '{"baz": "buz"}'}}], 'content': ''},
-            #   {'role': 'tool', 'name': 'bar', 'content': 'foobar'},
-            #   {'role': 'assistant', 'content': 'thats nice'}
-            # ]
-
-    .. versionadded:: 0.3.11
+        messages = [
+            SystemMessage([{"type": "text", "text": "foo"}]),
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "whats in this"},
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": "data:image/png;base64,'/9j/4AAQSk'"},
+                    },
+                ],
+            },
+            AIMessage(
+                "",
+                tool_calls=[
+                    {
+                        "name": "analyze",
+                        "args": {"baz": "buz"},
+                        "id": "1",
+                        "type": "tool_call",
+                    }
+                ],
+            ),
+            ToolMessage("foobar", tool_call_id="1", name="bar"),
+            {"role": "assistant", "content": "thats nice"},
+        ]
+        oai_messages = convert_to_openai_messages(messages)
+        # -> [
+        #   {'role': 'system', 'content': 'foo'},
+        #   {'role': 'user', 'content': [{'type': 'text', 'text': 'whats in this'}, {'type': 'image_url', 'image_url': {'url': "data:image/png;base64,'/9j/4AAQSk'"}}]},
+        #   {'role': 'assistant', 'tool_calls': [{'type': 'function', 'id': '1','function': {'name': 'analyze', 'arguments': '{"baz": "buz"}'}}], 'content': ''},
+        #   {'role': 'tool', 'name': 'bar', 'content': 'foobar'},
+        #   {'role': 'assistant', 'content': 'thats nice'}
+        # ]
+        ```
+
+    !!! version-added "Added in version 0.3.11"
 
     """  # noqa: E501
     if text_format not in {"string", "block"}:
@@ -1216,16 +1106,15 @@ 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)}
         tool_messages: list = []
-        content: Union[str, list[dict]]
+        content: str | list[dict]
 
         if message.name:
             oai_msg["name"] = message.name
@@ -1235,6 +1124,8 @@ def convert_to_openai_messages(
             oai_msg["refusal"] = message.additional_kwargs["refusal"]
         if isinstance(message, ToolMessage):
             oai_msg["tool_call_id"] = message.tool_call_id
+        if include_id and message.id:
+            oai_msg["id"] = message.id
 
         if not message.content:
             content = "" if text_format == "string" else []
@@ -1475,7 +1366,7 @@ def convert_to_openai_messages(
                             },
                         }
                     )
-                elif block.get("type") == "thinking":
+                elif block.get("type") in ["thinking", "reasoning"]:
                     content.append(block)
                 else:
                     err = (
@@ -1506,10 +1397,8 @@ def _first_max_tokens(
     max_tokens: int,
     token_counter: Callable[[list[BaseMessage]], int],
     text_splitter: Callable[[str], list[str]],
-    partial_strategy: Optional[Literal["first", "last"]] = None,
-    end_on: Optional[
-        Union[str, type[BaseMessage], Sequence[Union[str, type[BaseMessage]]]]
-    ] = None,
+    partial_strategy: Literal["first", "last"] | None = None,
+    end_on: str | type[BaseMessage] | Sequence[str | type[BaseMessage]] | None = None,
 ) -> list[BaseMessage]:
     messages = list(messages)
     if not messages:
@@ -1626,12 +1515,8 @@ def _last_max_tokens(
     text_splitter: Callable[[str], list[str]],
     allow_partial: bool = False,
     include_system: bool = False,
-    start_on: Optional[
-        Union[str, type[BaseMessage], Sequence[Union[str, type[BaseMessage]]]]
-    ] = None,
-    end_on: Optional[
-        Union[str, type[BaseMessage], Sequence[Union[str, type[BaseMessage]]]]
-    ] = None,
+    start_on: str | type[BaseMessage] | Sequence[str | type[BaseMessage]] | None = None,
+    end_on: str | type[BaseMessage] | Sequence[str | type[BaseMessage]] | None = None,
 ) -> list[BaseMessage]:
     messages = list(messages)
     if len(messages) == 0:
@@ -1707,11 +1592,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 "
@@ -1728,7 +1617,7 @@ def _default_text_splitter(text: str) -> list[str]:
 
 def _is_message_type(
     message: BaseMessage,
-    type_: Union[str, type[BaseMessage], Sequence[Union[str, type[BaseMessage]]]],
+    type_: str | type[BaseMessage] | Sequence[str | type[BaseMessage]],
 ) -> bool:
     types = [type_] if isinstance(type_, (str, type)) else type_
     types_str = [t for t in types if isinstance(t, str)]
@@ -1788,28 +1677,28 @@ def count_tokens_approximately(
     Args:
         messages: List of messages to count tokens for.
         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
-        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
+            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).
+        extra_tokens_per_message: Number of extra tokens to add per message, e.g.
+            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).
         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
+    !!! version-added "Added in version 0.3.46"
+
     """
     token_count = 0.0
     for message in convert_to_messages(messages):