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

langchain_core/messages/{content_blocks.py → content.py}

@@ -4,132 +4,144 @@
     This module is under active development. The API is unstable and subject to
     change in future releases.
 
-This module provides a standardized data structure for representing inputs to and
-outputs from Large Language Models. The core abstraction is the **Content Block**, a
-``TypedDict`` that can represent a piece of text, an image, a tool call, or other
-structured data.
+This module provides standardized data structures for representing inputs to and
+outputs from LLMs. The core abstraction is the **Content Block**, a ``TypedDict``.
+
+**Rationale**
+
+Different LLM providers use distinct and incompatible API schemas. This module
+provides a unified, provider-agnostic format to facilitate these interactions. A
+message to or from a model is simply a list of content blocks, allowing for the natural
+interleaving of text, images, and other content in a single ordered sequence.
+
+An adapter for a specific provider is responsible for translating this standard list of
+blocks into the format required by its API.
+
+**Extensibility**
 
 Data **not yet mapped** to a standard block may be represented using the
 ``NonStandardContentBlock``, which allows for provider-specific data to be included
 without losing the benefits of type checking and validation.
 
 Furthermore, provider-specific fields **within** a standard block are fully supported
-by default. However, since current type checkers do not recognize this, we are temporarily
-applying type ignore comments to suppress warnings. In the future,
-`PEP 728 <https://peps.python.org/pep-0728/>`__ will add an extra param, ``extra_items=Any``.
-When this is supported, we will apply it to block signatures to signify to type checkers
-that additional provider-specific fields are allowed.
-
-**Example with PEP 728 provider-specific fields:**
+by default in the ``extras`` field of each block. This allows for additional metadata
+to be included without breaking the standard structure.
 
-.. code-block:: python
+.. warning::
+    Do not heavily rely on the ``extras`` field for provider-specific data! This field
+    is subject to deprecation in future releases as we move towards PEP 728.
 
-    # Note `extra_items=Any`
-    class TextContentBlock(TypedDict, extra_items=Any):
-        type: Literal["text"]
-        id: NotRequired[str]
-        text: str
-        annotations: NotRequired[list[Annotation]]
-        index: NotRequired[int]
+.. note::
+    Following widespread adoption of `PEP 728 <https://peps.python.org/pep-0728/>`__, we
+    will add ``extra_items=Any`` as a param to Content Blocks. This will signify to type
+    checkers that additional provider-specific fields are allowed outside of the
+    ``extras`` field, and that will become the new standard approach to adding
+    provider-specific metadata.
 
-.. code-block:: python
+    .. dropdown::
 
-    from langchain_core.messages.content_blocks import TextContentBlock
+        **Example with PEP 728 provider-specific fields:**
 
-    my_block: TextContentBlock = {
-        # Add required fields
-        "type": "text",
-        "text": "Hello, world!",
-        # Additional fields not specified in the TypedDict
-        # These are valid with PEP 728 and are typed as Any
-        "openai_metadata": {"model": "gpt-4", "temperature": 0.7},
-        "anthropic_usage": {"input_tokens": 10, "output_tokens": 20},
-        "custom_field": "any value",
-    }
+        .. code-block:: python
 
-    openai_data = my_block["openai_metadata"]  # Type: Any
+            # Content block definition
+            # NOTE: `extra_items=Any`
+            class TextContentBlock(TypedDict, extra_items=Any):
+                type: Literal["text"]
+                id: NotRequired[str]
+                text: str
+                annotations: NotRequired[list[Annotation]]
+                index: NotRequired[int]
 
-.. note::
-    PEP 728 is enabled with ``# type: ignore[call-arg]`` comments to suppress warnings
-    from type checkers that don't yet support it. The functionality works correctly
-    in Python 3.13+ and will be fully supported as the ecosystem catches up.
+        .. code-block:: python
 
-**Rationale**
+            from langchain_core.messages.content import TextContentBlock
+
+            # Create a text content block with provider-specific fields
+            my_block: TextContentBlock = {
+                # Add required fields
+                "type": "text",
+                "text": "Hello, world!",
+                # Additional fields not specified in the TypedDict
+                # These are valid with PEP 728 and are typed as Any
+                "openai_metadata": {"model": "gpt-4", "temperature": 0.7},
+                "anthropic_usage": {"input_tokens": 10, "output_tokens": 20},
+                "custom_field": "any value",
+            }
 
-Different LLM providers use distinct and incompatible API schemas. This module
-introduces a unified, provider-agnostic format to standardize these interactions. A
-message to or from a model is simply a `list` of `ContentBlock` objects, allowing for
-the natural interleaving of text, images, and other content in a single, ordered
-sequence.
+            # Mutating an existing block to add provider-specific fields
+            openai_data = my_block["openai_metadata"]  # Type: Any
 
-An adapter for a specific provider is responsible for translating this standard list of
-blocks into the format required by its API.
+        PEP 728 is enabled with ``# type: ignore[call-arg]`` comments to suppress
+        warnings from type checkers that don't yet support it. The functionality works
+        correctly in Python 3.13+ and will be fully supported as the ecosystem catches
+        up.
 
 **Key Block Types**
 
 The module defines several types of content blocks, including:
 
-- ``TextContentBlock``: Standard text.
-- ``ImageContentBlock``, ``Audio...``, ``Video...``, ``PlainText...``, ``File...``: For multimodal data.
-- ``ToolCallContentBlock``, ``ToolOutputContentBlock``: For function calling.
+- ``TextContentBlock``: Standard text output.
+- ``Citation``: For annotations that link text output to a source document.
+- ``ToolCallContentBlock``: For function calling.
 - ``ReasoningContentBlock``: To capture a model's thought process.
-- ``Citation``: For annotations that link generated text to a source document.
+- Multimodal data:
+    - ``ImageContentBlock``
+    - ``AudioContentBlock``
+    - ``VideoContentBlock``
+    - ``PlainTextContentBlock`` (e.g. .txt or .md files)
+    - ``FileContentBlock`` (e.g. PDFs, etc.)
 
 **Example Usage**
 
 .. code-block:: python
 
     # Direct construction:
-    from langchain_core.messages.content_blocks import TextContentBlock, ImageContentBlock
-
-    multimodal_message: AIMessage = [
-        TextContentBlock(type="text", text="What is shown in this image?"),
-        ImageContentBlock(
-            type="image",
-            url="https://www.langchain.com/images/brand/langchain_logo_text_w_white.png",
-            mime_type="image/png",
-        ),
-    ]
-
-    from langchain_core.messages.content_blocks import create_text_block, create_image_block
-
-    # Using factory functions:
-    multimodal_message: AIMessage = [
-        create_text_block("What is shown in this image?"),
-        create_image_block(
-            url="https://www.langchain.com/images/brand/langchain_logo_text_w_white.png",
-            mime_type="image/png",
-        ),
-    ]
-"""  # noqa: E501
-
-import warnings
-from typing import Any, Literal, Optional, Union
-from uuid import uuid4
+    from langchain_core.messages.content import TextContentBlock, ImageContentBlock
+
+    multimodal_message: AIMessage(content_blocks=
+        [
+            TextContentBlock(type="text", text="What is shown in this image?"),
+            ImageContentBlock(
+                type="image",
+                url="https://www.langchain.com/images/brand/langchain_logo_text_w_white.png",
+                mime_type="image/png",
+            ),
+        ]
+    )
 
-from typing_extensions import NotRequired, TypedDict, get_args, get_origin
+    # Using factories:
+    from langchain_core.messages.content import create_text_block, create_image_block
+
+    multimodal_message: AIMessage(content=
+        [
+            create_text_block("What is shown in this image?"),
+            create_image_block(
+                url="https://www.langchain.com/images/brand/langchain_logo_text_w_white.png",
+                mime_type="image/png",
+            ),
+        ]
+    )
 
+Factory functions offer benefits such as:
+- Automatic ID generation (when not provided)
+- No need to manually specify the ``type`` field
 
-def _ensure_id(id_val: Optional[str]) -> str:
-    """Ensure the ID is a valid string, generating a new UUID if not provided.
+"""
 
-    Auto-generated UUIDs are prefixed by ``'lc_'`` to indicate they are
-    LangChain-generated IDs.
+import warnings
+from typing import Any, Literal, Optional, Union, get_args, get_type_hints
 
-    Args:
-        id_val: Optional string ID value to validate.
+from typing_extensions import NotRequired, TypedDict, TypeGuard
 
-    Returns:
-        A valid string ID, either the provided value or a new UUID.
-    """
-    return id_val or str(f"lc_{uuid4()}")
+from langchain_core.utils.utils import ensure_id
 
 
 class Citation(TypedDict):
     """Annotation for citing data from a document.
 
     .. note::
-        ``start/end`` indices refer to the **response text**,
+        ``start``/``end`` indices refer to the **response text**,
         not the source text. This means that the indices are relative to the model's
         response, not the original document (as specified in the ``url``).
 
@@ -150,18 +162,12 @@ class Citation(TypedDict):
 
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     url: NotRequired[str]
     """URL of the document source."""
 
-    # For future consideration, if needed:
-    # provenance: NotRequired[str]
-    # """Provenance of the document, e.g., "Wikipedia", "arXiv", etc.
-
-    # Included for future compatibility; not currently implemented.
-    # """
-
     title: NotRequired[str]
     """Source document title.
 
@@ -169,12 +175,10 @@ class Citation(TypedDict):
     """
 
     start_index: NotRequired[int]
-    """Start index of the **response text** (``TextContentBlock.text``) for which the
-    annotation applies."""
+    """Start index of the **response text** (``TextContentBlock.text``)."""
 
     end_index: NotRequired[int]
-    """End index of the **response text** (``TextContentBlock.text``) for which the
-    annotation applies."""
+    """End index of the **response text** (``TextContentBlock.text``)"""
 
     cited_text: NotRequired[str]
     """Excerpt of source text being cited."""
@@ -196,10 +200,12 @@ class NonStandardAnnotation(TypedDict):
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     value: dict[str, Any]
@@ -228,19 +234,21 @@ class TextContentBlock(TypedDict):
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     text: str
     """Block text."""
 
     annotations: NotRequired[list[Annotation]]
-    """Citations and other annotations."""
+    """``Citation``s and other annotations."""
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
     extras: NotRequired[dict[str, Any]]
@@ -280,6 +288,7 @@ class ToolCall(TypedDict):
 
     An identifier is needed to associate a tool call request with a tool
     call result in events when multiple concurrent tool calls are made.
+
     """
     # TODO: Consider making this NotRequired[str] in the future.
 
@@ -289,7 +298,7 @@ class ToolCall(TypedDict):
     args: dict[str, Any]
     """The arguments to the tool call."""
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
     extras: NotRequired[dict[str, Any]]
@@ -299,7 +308,7 @@ class ToolCall(TypedDict):
 class ToolCallChunk(TypedDict):
     """A chunk of a tool call (e.g., as part of a stream).
 
-    When merging ToolCallChunks (e.g., via ``AIMessageChunk.__add__``),
+    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``.
 
@@ -314,15 +323,21 @@ class ToolCallChunk(TypedDict):
             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)]
+
     """
 
     # TODO: Consider making fields NotRequired[str] in the future.
 
-    type: NotRequired[Literal["tool_call_chunk"]]
+    type: Literal["tool_call_chunk"]
     """Used for serialization."""
 
     id: Optional[str]
-    """An identifier associated with the tool call."""
+    """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.
+
+    """
 
     name: Optional[str]
     """The name of the tool to be called."""
@@ -330,7 +345,7 @@ class ToolCallChunk(TypedDict):
     args: Optional[str]
     """The arguments to the tool call."""
 
-    index: Optional[int]
+    index: NotRequired[Union[int, str]]
     """The index of the tool call in a sequence."""
 
     extras: NotRequired[dict[str, Any]]
@@ -342,6 +357,7 @@ class InvalidToolCall(TypedDict):
 
     Here we add an ``error`` key to surface errors made during generation
     (e.g., invalid JSON arguments.)
+
     """
 
     # TODO: Consider making fields NotRequired[str] in the future.
@@ -350,7 +366,12 @@ class InvalidToolCall(TypedDict):
     """Used for discrimination."""
 
     id: Optional[str]
-    """An identifier associated with the tool call."""
+    """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.
+
+    """
 
     name: Optional[str]
     """The name of the tool to be called."""
@@ -361,15 +382,13 @@ class InvalidToolCall(TypedDict):
     error: Optional[str]
     """An error message associated with the tool call."""
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
     extras: NotRequired[dict[str, Any]]
     """Provider-specific metadata."""
 
 
-# Note: These are not standard tool calls, but rather provider-specific built-in tools.
-# Web search
 class WebSearchCall(TypedDict):
     """Built-in web search tool call."""
 
@@ -377,16 +396,18 @@ class WebSearchCall(TypedDict):
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     query: NotRequired[str]
     """The search query used in the web search tool call."""
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
     extras: NotRequired[dict[str, Any]]
@@ -400,16 +421,18 @@ class WebSearchResult(TypedDict):
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     urls: NotRequired[list[str]]
     """List of URLs returned by the web search tool call."""
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
     extras: NotRequired[dict[str, Any]]
@@ -423,10 +446,12 @@ class CodeInterpreterCall(TypedDict):
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     language: NotRequired[str]
@@ -435,7 +460,7 @@ class CodeInterpreterCall(TypedDict):
     code: NotRequired[str]
     """The code to be executed by the code interpreter."""
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
     extras: NotRequired[dict[str, Any]]
@@ -447,22 +472,26 @@ class CodeInterpreterOutput(TypedDict):
 
     Full output of a code interpreter tool call is represented by
     ``CodeInterpreterResult`` which is a list of these blocks.
+
     """
 
     type: Literal["code_interpreter_output"]
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     return_code: NotRequired[int]
     """Return code of the executed code.
 
     Example: ``0`` for success, non-zero for failure.
+
     """
 
     stderr: NotRequired[str]
@@ -474,12 +503,6 @@ class CodeInterpreterOutput(TypedDict):
     file_ids: NotRequired[list[str]]
     """List of file IDs generated by the code interpreter."""
 
-    index: NotRequired[int]
-    """Index of block in aggregate response. Used during streaming."""
-
-    extras: NotRequired[dict[str, Any]]
-    """Provider-specific metadata."""
-
 
 class CodeInterpreterResult(TypedDict):
     """Result of a code interpreter tool call."""
@@ -488,16 +511,18 @@ class CodeInterpreterResult(TypedDict):
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     output: list[CodeInterpreterOutput]
     """List of outputs from the code interpreter tool call."""
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
     extras: NotRequired[dict[str, Any]]
@@ -520,10 +545,12 @@ class ReasoningContentBlock(TypedDict):
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     reasoning: NotRequired[str]
@@ -531,9 +558,10 @@ class ReasoningContentBlock(TypedDict):
 
     Either the thought summary or the raw reasoning text itself. This is often parsed
     from ``<think>`` tags in the model's response.
+
     """
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
     extras: NotRequired[dict[str, Any]]
@@ -559,10 +587,12 @@ class ImageContentBlock(TypedDict):
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     file_id: NotRequired[str]
@@ -572,9 +602,10 @@ class ImageContentBlock(TypedDict):
     """MIME type of the image. Required for base64.
 
     `Examples from IANA <https://www.iana.org/assignments/media-types/media-types.xhtml#image>`__
+
     """
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
     url: NotRequired[str]
@@ -584,7 +615,7 @@ class ImageContentBlock(TypedDict):
     """Data as a base64 string."""
 
     extras: NotRequired[dict[str, Any]]
-    """Provider-specific metadata."""
+    """Provider-specific metadata. This shouldn't be used for the image data itself."""
 
 
 class VideoContentBlock(TypedDict):
@@ -603,10 +634,12 @@ class VideoContentBlock(TypedDict):
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     file_id: NotRequired[str]
@@ -616,9 +649,10 @@ class VideoContentBlock(TypedDict):
     """MIME type of the video. Required for base64.
 
     `Examples from IANA <https://www.iana.org/assignments/media-types/media-types.xhtml#video>`__
+
     """
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
     url: NotRequired[str]
@@ -628,7 +662,7 @@ class VideoContentBlock(TypedDict):
     """Data as a base64 string."""
 
     extras: NotRequired[dict[str, Any]]
-    """Provider-specific metadata."""
+    """Provider-specific metadata. This shouldn't be used for the video data itself."""
 
 
 class AudioContentBlock(TypedDict):
@@ -637,7 +671,6 @@ class AudioContentBlock(TypedDict):
     .. note::
         ``create_audio_block`` may also be used as a factory to create an
         ``AudioContentBlock``. Benefits include:
-
         * Automatic ID generation (when not provided)
         * Required arguments strictly validated at creation time
 
@@ -647,10 +680,12 @@ class AudioContentBlock(TypedDict):
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     file_id: NotRequired[str]
@@ -660,9 +695,10 @@ class AudioContentBlock(TypedDict):
     """MIME type of the audio. Required for base64.
 
     `Examples from IANA <https://www.iana.org/assignments/media-types/media-types.xhtml#audio>`__
+
     """
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
     url: NotRequired[str]
@@ -672,7 +708,7 @@ class AudioContentBlock(TypedDict):
     """Data as a base64 string."""
 
     extras: NotRequired[dict[str, Any]]
-    """Provider-specific metadata."""
+    """Provider-specific metadata. This shouldn't be used for the audio data itself."""
 
 
 class PlainTextContentBlock(TypedDict):
@@ -695,10 +731,12 @@ class PlainTextContentBlock(TypedDict):
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     file_id: NotRequired[str]
@@ -707,7 +745,7 @@ class PlainTextContentBlock(TypedDict):
     mime_type: Literal["text/plain"]
     """MIME type of the file. Required for base64."""
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
     url: NotRequired[str]
@@ -726,7 +764,7 @@ class PlainTextContentBlock(TypedDict):
     """Context for the text, e.g., a description or summary of the text's content."""
 
     extras: NotRequired[dict[str, Any]]
-    """Provider-specific metadata."""
+    """Provider-specific metadata. This shouldn't be used for the data itself."""
 
 
 class FileContentBlock(TypedDict):
@@ -752,10 +790,12 @@ class FileContentBlock(TypedDict):
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     file_id: NotRequired[str]
@@ -765,9 +805,10 @@ class FileContentBlock(TypedDict):
     """MIME type of the file. Required for base64.
 
     `Examples from IANA <https://www.iana.org/assignments/media-types/media-types.xhtml>`__
+
     """
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
     url: NotRequired[str]
@@ -777,7 +818,7 @@ class FileContentBlock(TypedDict):
     """Data as a base64 string."""
 
     extras: NotRequired[dict[str, Any]]
-    """Provider-specific metadata."""
+    """Provider-specific metadata. This shouldn't be used for the file data itself."""
 
 
 # Future modalities to consider:
@@ -793,7 +834,10 @@ class NonStandardContentBlock(TypedDict):
     The purpose of this block should be to simply hold a provider-specific payload.
     If a provider's non-standard output includes reasoning and tool calls, it should be
     the adapter's job to parse that payload and emit the corresponding standard
-    ReasoningContentBlock and ToolCallContentBlocks.
+    ``ReasoningContentBlock`` and ``ToolCallContentBlocks``.
+
+    Has no ``extras`` field, as provider-specific data should be included in the
+    ``value`` field.
 
     .. note::
         ``create_non_standard_block`` may also be used as a factory to create a
@@ -808,16 +852,18 @@ class NonStandardContentBlock(TypedDict):
     """Type of the content block. Used for discrimination."""
 
     id: NotRequired[str]
-    """Content block identifier. Either:
+    """Content block identifier.
 
+    Either:
     - Generated by the provider (e.g., OpenAI's file ID)
     - Generated by LangChain upon creation (``UUID4`` prefixed with ``'lc_'``))
+
     """
 
     value: dict[str, Any]
     """Provider-specific data."""
 
-    index: NotRequired[int]
+    index: NotRequired[Union[int, str]]
     """Index of block in aggregate response. Used during streaming."""
 
 
@@ -832,8 +878,8 @@ DataContentBlock = Union[
 
 ToolContentBlock = Union[
     ToolCall,
+    ToolCallChunk,
     CodeInterpreterCall,
-    CodeInterpreterOutput,
     CodeInterpreterResult,
     WebSearchCall,
     WebSearchResult,
@@ -841,9 +887,7 @@ ToolContentBlock = Union[
 
 ContentBlock = Union[
     TextContentBlock,
-    ToolCall,
     InvalidToolCall,
-    ToolCallChunk,
     ReasoningContentBlock,
     NonStandardContentBlock,
     DataContentBlock,
@@ -851,68 +895,106 @@ ContentBlock = Union[
 ]
 
 
-def _extract_typedict_type_values(union_type: Any) -> set[str]:
-    """Extract the values of the 'type' field from a TypedDict union type."""
-    result: set[str] = set()
-    for value in get_args(union_type):
-        annotation = value.__annotations__["type"]
-        if get_origin(annotation) is Literal:
-            result.update(get_args(annotation))
-        else:
-            msg = f"{value} 'type' is not a Literal"
-            raise ValueError(msg)
-    return result
-
-
 KNOWN_BLOCK_TYPES = {
+    # Text output
     "text",
-    "text-plain",
+    "reasoning",
+    # Tools
     "tool_call",
     "invalid_tool_call",
     "tool_call_chunk",
-    "reasoning",
-    "non_standard",
+    # Multimodal data
     "image",
     "audio",
     "file",
+    "text-plain",
     "video",
+    # Server-side tool calls
     "code_interpreter_call",
-    "code_interpreter_output",
     "code_interpreter_result",
     "web_search_call",
     "web_search_result",
+    # Catch-all
+    "non_standard",
 }
 
 
+def _get_data_content_block_types() -> tuple[str, ...]:
+    """Get type literals from DataContentBlock union members dynamically."""
+    data_block_types = []
+
+    for block_type in get_args(DataContentBlock):
+        hints = get_type_hints(block_type)
+        if "type" in hints:
+            type_annotation = hints["type"]
+            if hasattr(type_annotation, "__args__"):
+                # This is a Literal type, get the literal value
+                literal_value = type_annotation.__args__[0]
+                data_block_types.append(literal_value)
+
+    return tuple(data_block_types)
+
+
 def is_data_content_block(block: dict) -> bool:
-    """Check if the content block is a standard data content block.
+    """Check if the provided content block is a standard v1 data content block.
 
     Args:
         block: The content block to check.
 
     Returns:
         True if the content block is a data content block, False otherwise.
+
     """
-    return block.get("type") in (
-        "audio",
-        "image",
-        "video",
-        "file",
-        "text-plain",
-    ) and any(
-        key in block
-        for key in (
-            "url",
-            "base64",
-            "file_id",
-            "text",
-            "source_type",  # backwards compatibility
-        )
-    )
+    if block.get("type") not in _get_data_content_block_types():
+        return False
+
+    if any(key in block for key in ("url", "base64", "file_id", "text")):
+        return True
+
+    # Verify data presence based on source type
+    if "source_type" in block:
+        source_type = block["source_type"]
+        if (source_type == "url" and "url" in block) or (
+            source_type == "base64" and "data" in block
+        ):
+            return True
+        if (source_type == "id" and "id" in block) or (
+            source_type == "text" and "url" in block
+        ):
+            return True
+
+    return False
+
+
+def is_tool_call_block(block: ContentBlock) -> TypeGuard[ToolCall]:
+    """Type guard to check if a content block is a ``ToolCall``."""
+    return block.get("type") == "tool_call"
+
+
+def is_tool_call_chunk(block: ContentBlock) -> TypeGuard[ToolCallChunk]:
+    """Type guard to check if a content block is a ``ToolCallChunk``."""
+    return block.get("type") == "tool_call_chunk"
+
+
+def is_text_block(block: ContentBlock) -> TypeGuard[TextContentBlock]:
+    """Type guard to check if a content block is a ``TextContentBlock``."""
+    return block.get("type") == "text"
+
+
+def is_reasoning_block(block: ContentBlock) -> TypeGuard[ReasoningContentBlock]:
+    """Type guard to check if a content block is a ``ReasoningContentBlock``."""
+    return block.get("type") == "reasoning"
+
+
+def is_invalid_tool_call_block(
+    block: ContentBlock,
+) -> TypeGuard[InvalidToolCall]:
+    """Type guard to check if a content block is an ``InvalidToolCall``."""
+    return block.get("type") == "invalid_tool_call"
 
 
 def convert_to_openai_image_block(block: dict[str, Any]) -> dict:
-    """Convert image content block to format expected by OpenAI Chat Completions API."""
+    """Convert ``ImageContentBlock`` to format expected by OpenAI Chat Completions."""
     if "url" in block:
         return {
             "type": "image_url",
@@ -943,12 +1025,17 @@ def convert_to_openai_data_block(block: dict) -> dict:
 
     elif block["type"] == "file":
         if "base64" in block or block.get("source_type") == "base64":
+            # Handle v0 format: {"source_type": "base64", "data": "...", ...}
+            # Handle v1 format: {"base64": "...", ...}
             base64_data = block["data"] if "source_type" in block else block["base64"]
             file = {"file_data": f"data:{block['mime_type']};base64,{base64_data}"}
             if filename := block.get("filename"):
                 file["filename"] = filename
-            elif (metadata := block.get("metadata")) and ("filename" in metadata):
-                file["filename"] = metadata["filename"]
+            elif (extras := block.get("extras")) and ("filename" in extras):
+                file["filename"] = extras["filename"]
+            elif (extras := block.get("metadata")) and ("filename" in extras):
+                # Backward compat
+                file["filename"] = extras["filename"]
             else:
                 warnings.warn(
                     "OpenAI may require a filename for file inputs. Specify a filename "
@@ -958,6 +1045,8 @@ def convert_to_openai_data_block(block: dict) -> dict:
                 )
             formatted_block = {"type": "file", "file": file}
         elif "file_id" in block or block.get("source_type") == "id":
+            # Handle v0 format: {"source_type": "id", "id": "...", ...}
+            # Handle v1 format: {"file_id": "...", ...}
             file_id = block["id"] if "source_type" in block else block["file_id"]
             formatted_block = {"type": "file", "file": {"file_id": file_id}}
         else:
@@ -966,6 +1055,8 @@ def convert_to_openai_data_block(block: dict) -> dict:
 
     elif block["type"] == "audio":
         if "base64" in block or block.get("source_type") == "base64":
+            # Handle v0 format: {"source_type": "base64", "data": "...", ...}
+            # Handle v1 format: {"base64": "...", ...}
             base64_data = block["data"] if "source_type" in block else block["base64"]
             audio_format = block["mime_type"].split("/")[-1]
             formatted_block = {
@@ -987,14 +1078,15 @@ def create_text_block(
     *,
     id: Optional[str] = None,
     annotations: Optional[list[Annotation]] = None,
-    index: Optional[int] = None,
+    index: Optional[Union[int, str]] = None,
+    **kwargs: Any,
 ) -> TextContentBlock:
     """Create a ``TextContentBlock``.
 
     Args:
         text: The text content of the block.
         id: Content block identifier. Generated automatically if not provided.
-        annotations: Citations and other annotations for the text.
+        annotations: ``Citation``s and other annotations for the text.
         index: Index of block in aggregate response. Used during streaming.
 
     Returns:
@@ -1008,12 +1100,17 @@ def create_text_block(
     block = TextContentBlock(
         type="text",
         text=text,
-        id=_ensure_id(id),
+        id=ensure_id(id),
     )
     if annotations is not None:
         block["annotations"] = annotations
     if index is not None:
         block["index"] = index
+
+    extras = {k: v for k, v in kwargs.items() if v is not None}
+    if extras:
+        block["extras"] = extras
+
     return block
 
 
@@ -1024,7 +1121,8 @@ def create_image_block(
     file_id: Optional[str] = None,
     mime_type: Optional[str] = None,
     id: Optional[str] = None,
-    index: Optional[int] = None,
+    index: Optional[Union[int, str]] = None,
+    **kwargs: Any,
 ) -> ImageContentBlock:
     """Create an ``ImageContentBlock``.
 
@@ -1052,11 +1150,7 @@ def create_image_block(
         msg = "Must provide one of: url, base64, or file_id"
         raise ValueError(msg)
 
-    if base64 and not mime_type:
-        msg = "mime_type is required when using base64 data"
-        raise ValueError(msg)
-
-    block = ImageContentBlock(type="image", id=_ensure_id(id))
+    block = ImageContentBlock(type="image", id=ensure_id(id))
 
     if url is not None:
         block["url"] = url
@@ -1069,6 +1163,10 @@ def create_image_block(
     if index is not None:
         block["index"] = index
 
+    extras = {k: v for k, v in kwargs.items() if v is not None}
+    if extras:
+        block["extras"] = extras
+
     return block
 
 
@@ -1079,7 +1177,8 @@ def create_video_block(
     file_id: Optional[str] = None,
     mime_type: Optional[str] = None,
     id: Optional[str] = None,
-    index: Optional[int] = None,
+    index: Optional[Union[int, str]] = None,
+    **kwargs: Any,
 ) -> VideoContentBlock:
     """Create a ``VideoContentBlock``.
 
@@ -1111,7 +1210,7 @@ def create_video_block(
         msg = "mime_type is required when using base64 data"
         raise ValueError(msg)
 
-    block = VideoContentBlock(type="video", id=_ensure_id(id))
+    block = VideoContentBlock(type="video", id=ensure_id(id))
 
     if url is not None:
         block["url"] = url
@@ -1124,6 +1223,10 @@ def create_video_block(
     if index is not None:
         block["index"] = index
 
+    extras = {k: v for k, v in kwargs.items() if v is not None}
+    if extras:
+        block["extras"] = extras
+
     return block
 
 
@@ -1134,7 +1237,8 @@ def create_audio_block(
     file_id: Optional[str] = None,
     mime_type: Optional[str] = None,
     id: Optional[str] = None,
-    index: Optional[int] = None,
+    index: Optional[Union[int, str]] = None,
+    **kwargs: Any,
 ) -> AudioContentBlock:
     """Create an ``AudioContentBlock``.
 
@@ -1166,7 +1270,7 @@ def create_audio_block(
         msg = "mime_type is required when using base64 data"
         raise ValueError(msg)
 
-    block = AudioContentBlock(type="audio", id=_ensure_id(id))
+    block = AudioContentBlock(type="audio", id=ensure_id(id))
 
     if url is not None:
         block["url"] = url
@@ -1179,6 +1283,10 @@ def create_audio_block(
     if index is not None:
         block["index"] = index
 
+    extras = {k: v for k, v in kwargs.items() if v is not None}
+    if extras:
+        block["extras"] = extras
+
     return block
 
 
@@ -1189,7 +1297,8 @@ def create_file_block(
     file_id: Optional[str] = None,
     mime_type: Optional[str] = None,
     id: Optional[str] = None,
-    index: Optional[int] = None,
+    index: Optional[Union[int, str]] = None,
+    **kwargs: Any,
 ) -> FileContentBlock:
     """Create a ``FileContentBlock``.
 
@@ -1221,7 +1330,7 @@ def create_file_block(
         msg = "mime_type is required when using base64 data"
         raise ValueError(msg)
 
-    block = FileContentBlock(type="file", id=_ensure_id(id))
+    block = FileContentBlock(type="file", id=ensure_id(id))
 
     if url is not None:
         block["url"] = url
@@ -1234,19 +1343,23 @@ def create_file_block(
     if index is not None:
         block["index"] = index
 
+    extras = {k: v for k, v in kwargs.items() if v is not None}
+    if extras:
+        block["extras"] = extras
+
     return block
 
 
 def create_plaintext_block(
-    text: str,
-    *,
+    text: Optional[str] = None,
     url: Optional[str] = None,
     base64: Optional[str] = None,
     file_id: Optional[str] = None,
     title: Optional[str] = None,
     context: Optional[str] = None,
     id: Optional[str] = None,
-    index: Optional[int] = None,
+    index: Optional[Union[int, str]] = None,
+    **kwargs: Any,
 ) -> PlainTextContentBlock:
     """Create a ``PlainTextContentBlock``.
 
@@ -1271,10 +1384,11 @@ def create_plaintext_block(
     block = PlainTextContentBlock(
         type="text-plain",
         mime_type="text/plain",
-        text=text,
-        id=_ensure_id(id),
+        id=ensure_id(id),
     )
 
+    if text is not None:
+        block["text"] = text
     if url is not None:
         block["url"] = url
     if base64 is not None:
@@ -1288,6 +1402,10 @@ def create_plaintext_block(
     if index is not None:
         block["index"] = index
 
+    extras = {k: v for k, v in kwargs.items() if v is not None}
+    if extras:
+        block["extras"] = extras
+
     return block
 
 
@@ -1296,7 +1414,8 @@ def create_tool_call(
     args: dict[str, Any],
     *,
     id: Optional[str] = None,
-    index: Optional[int] = None,
+    index: Optional[Union[int, str]] = None,
+    **kwargs: Any,
 ) -> ToolCall:
     """Create a ``ToolCall``.
 
@@ -1318,19 +1437,24 @@ def create_tool_call(
         type="tool_call",
         name=name,
         args=args,
-        id=_ensure_id(id),
+        id=ensure_id(id),
     )
 
     if index is not None:
         block["index"] = index
 
+    extras = {k: v for k, v in kwargs.items() if v is not None}
+    if extras:
+        block["extras"] = extras
+
     return block
 
 
 def create_reasoning_block(
     reasoning: Optional[str] = None,
     id: Optional[str] = None,
-    index: Optional[int] = None,
+    index: Optional[Union[int, str]] = None,
+    **kwargs: Any,
 ) -> ReasoningContentBlock:
     """Create a ``ReasoningContentBlock``.
 
@@ -1350,12 +1474,16 @@ def create_reasoning_block(
     block = ReasoningContentBlock(
         type="reasoning",
         reasoning=reasoning or "",
-        id=_ensure_id(id),
+        id=ensure_id(id),
     )
 
     if index is not None:
         block["index"] = index
 
+    extras = {k: v for k, v in kwargs.items() if v is not None}
+    if extras:
+        block["extras"] = extras
+
     return block
 
 
@@ -1367,6 +1495,7 @@ def create_citation(
     end_index: Optional[int] = None,
     cited_text: Optional[str] = None,
     id: Optional[str] = None,
+    **kwargs: Any,
 ) -> Citation:
     """Create a ``Citation``.
 
@@ -1386,7 +1515,7 @@ def create_citation(
         prefixed with ``'lc_'`` to indicate it is a LangChain-generated ID.
 
     """
-    block = Citation(type="citation", id=_ensure_id(id))
+    block = Citation(type="citation", id=ensure_id(id))
 
     if url is not None:
         block["url"] = url
@@ -1399,6 +1528,10 @@ def create_citation(
     if cited_text is not None:
         block["cited_text"] = cited_text
 
+    extras = {k: v for k, v in kwargs.items() if v is not None}
+    if extras:
+        block["extras"] = extras
+
     return block
 
 
@@ -1406,7 +1539,7 @@ def create_non_standard_block(
     value: dict[str, Any],
     *,
     id: Optional[str] = None,
-    index: Optional[int] = None,
+    index: Optional[Union[int, str]] = None,
 ) -> NonStandardContentBlock:
     """Create a ``NonStandardContentBlock``.
 
@@ -1426,7 +1559,7 @@ def create_non_standard_block(
     block = NonStandardContentBlock(
         type="non_standard",
         value=value,
-        id=_ensure_id(id),
+        id=ensure_id(id),
     )
 
     if index is not None: