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

langchain_core/messages/content_blocks.py

@@ -1,110 +1,935 @@
-"""Types for content blocks."""
+"""Standard, multimodal content blocks for Large Language Model I/O.
+
+.. warning::
+    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.
+
+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:**
+
+.. code-block:: python
+
+    # 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]
+
+.. code-block:: python
+
+    from langchain_core.messages.content_blocks import TextContentBlock
+
+    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",
+    }
+
+    openai_data = my_block["openai_metadata"]  # Type: Any
+
+.. 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.
+
+**Rationale**
+
+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.
+
+An adapter for a specific provider is responsible for translating this standard list of
+blocks into the format required by its API.
+
+**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.
+- ``ReasoningContentBlock``: To capture a model's thought process.
+- ``Citation``: For annotations that link generated text to a source document.
+
+**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, Union
+from typing import Any, Literal, Optional, Union
+from uuid import uuid4
+
+from typing_extensions import NotRequired, TypedDict, get_args, get_origin
+
+
+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.
+
+    Args:
+        id_val: Optional string ID value to validate.
+
+    Returns:
+        A valid string ID, either the provided value or a new UUID.
+    """
+    return id_val or str(f"lc_{uuid4()}")
+
+
+class Citation(TypedDict):
+    """Annotation for citing data from a document.
+
+    .. note::
+        ``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``).
+
+    .. note::
+        ``create_citation`` may also be used as a factory to create a ``Citation``.
+        Benefits include:
+
+        * Automatic ID generation (when not provided)
+        * Required arguments strictly validated at creation time
+
+    """
+
+    type: Literal["citation"]
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """Content block identifier. Either:
+
+    - 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.
+
+    For example, the page title for a web page or the title of a paper.
+    """
+
+    start_index: NotRequired[int]
+    """Start index of the **response text** (``TextContentBlock.text``) for which the
+    annotation applies."""
+
+    end_index: NotRequired[int]
+    """End index of the **response text** (``TextContentBlock.text``) for which the
+    annotation applies."""
+
+    cited_text: NotRequired[str]
+    """Excerpt of source text being cited."""
+
+    # NOTE: not including spans for the raw document text (such as `text_start_index`
+    # and `text_end_index`) as this is not currently supported by any provider. The
+    # thinking is that the `cited_text` should be sufficient for most use cases, and it
+    # is difficult to reliably extract spans from the raw document text across file
+    # formats or encoding schemes.
+
+    extras: NotRequired[dict[str, Any]]
+    """Provider-specific metadata."""
+
+
+class NonStandardAnnotation(TypedDict):
+    """Provider-specific annotation format."""
+
+    type: Literal["non_standard_annotation"]
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """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 annotation data."""
+
+
+Annotation = Union[Citation, NonStandardAnnotation]
+
+
+class TextContentBlock(TypedDict):
+    """Text output from a LLM.
+
+    This typically represents the main text content of a message, such as the response
+    from a language model or the text of a user message.
+
+    .. note::
+        ``create_text_block`` may also be used as a factory to create a
+        ``TextContentBlock``. Benefits include:
+
+        * Automatic ID generation (when not provided)
+        * Required arguments strictly validated at creation time
+
+    """
+
+    type: Literal["text"]
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """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."""
+
+    index: NotRequired[int]
+    """Index of block in aggregate response. Used during streaming."""
+
+    extras: NotRequired[dict[str, Any]]
+    """Provider-specific metadata."""
+
+
+class ToolCall(TypedDict):
+    """Represents a request to call a tool.
+
+    Example:
+
+        .. code-block:: python
+
+            {
+                "name": "foo",
+                "args": {"a": 1},
+                "id": "123"
+            }
+
+        This represents a request to call the tool named "foo" with arguments {"a": 1}
+        and an identifier of "123".
+
+    .. note::
+        ``create_tool_call`` may also be used as a factory to create a
+        ``ToolCall``. Benefits include:
+
+        * Automatic ID generation (when not provided)
+        * Required arguments strictly validated at creation time
+
+    """
+
+    type: Literal["tool_call"]
+    """Used for discrimination."""
+
+    id: Optional[str]
+    """An identifier associated with the tool call.
+
+    An identifier is needed to associate a tool call request with a tool
+    call result in events when multiple concurrent tool calls are made.
+    """
+    # TODO: Consider making this NotRequired[str] in the future.
+
+    name: str
+    """The name of the tool to be called."""
+
+    args: dict[str, Any]
+    """The arguments to the tool call."""
+
+    index: NotRequired[int]
+    """Index of block in aggregate response. Used during streaming."""
+
+    extras: NotRequired[dict[str, Any]]
+    """Provider-specific metadata."""
+
+
+class ToolCallChunk(TypedDict):
+    """A chunk of a tool call (e.g., as part of a stream).
+
+    When merging ToolCallChunks (e.g., via ``AIMessageChunk.__add__``),
+    all string attributes are concatenated. Chunks are only merged if their
+    values of ``index`` are equal and not ``None``.
+
+    Example:
+
+    .. code-block:: python
+
+        left_chunks = [ToolCallChunk(name="foo", args='{"a":', index=0)]
+        right_chunks = [ToolCallChunk(name=None, args='1}', index=0)]
+
+        (
+            AIMessageChunk(content="", tool_call_chunks=left_chunks)
+            + AIMessageChunk(content="", tool_call_chunks=right_chunks)
+        ).tool_call_chunks == [ToolCallChunk(name='foo', args='{"a":1}', index=0)]
+    """
 
-from pydantic import TypeAdapter, ValidationError
-from typing_extensions import NotRequired, TypedDict
+    # TODO: Consider making fields NotRequired[str] in the future.
 
+    type: NotRequired[Literal["tool_call_chunk"]]
+    """Used for serialization."""
 
-class BaseDataContentBlock(TypedDict, total=False):
-    """Base class for data content blocks."""
+    id: Optional[str]
+    """An identifier associated with the tool call."""
+
+    name: Optional[str]
+    """The name of the tool to be called."""
+
+    args: Optional[str]
+    """The arguments to the tool call."""
+
+    index: Optional[int]
+    """The index of the tool call in a sequence."""
+
+    extras: NotRequired[dict[str, Any]]
+    """Provider-specific metadata."""
+
+
+class InvalidToolCall(TypedDict):
+    """Allowance for errors made by LLM.
+
+    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.
+
+    type: Literal["invalid_tool_call"]
+    """Used for discrimination."""
+
+    id: Optional[str]
+    """An identifier associated with the tool call."""
+
+    name: Optional[str]
+    """The name of the tool to be called."""
+
+    args: Optional[str]
+    """The arguments to the tool call."""
+
+    error: Optional[str]
+    """An error message associated with the tool call."""
+
+    index: NotRequired[int]
+    """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."""
+
+    type: Literal["web_search_call"]
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """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 of block in aggregate response. Used during streaming."""
+
+    extras: NotRequired[dict[str, Any]]
+    """Provider-specific metadata."""
+
+
+class WebSearchResult(TypedDict):
+    """Result of a built-in web search tool call."""
+
+    type: Literal["web_search_result"]
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """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 of block in aggregate response. Used during streaming."""
+
+    extras: NotRequired[dict[str, Any]]
+    """Provider-specific metadata."""
+
+
+class CodeInterpreterCall(TypedDict):
+    """Built-in code interpreter tool call."""
+
+    type: Literal["code_interpreter_call"]
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """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]
+    """The name of the programming language used in the code interpreter tool call."""
+
+    code: NotRequired[str]
+    """The code to be executed 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 CodeInterpreterOutput(TypedDict):
+    """Output of a singular code interpreter tool call.
+
+    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:
+
+    - 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]
+    """Standard error output of the executed code."""
+
+    stdout: NotRequired[str]
+    """Standard output of the executed code."""
+
+    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."""
+
+    type: Literal["code_interpreter_result"]
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """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 of block in aggregate response. Used during streaming."""
+
+    extras: NotRequired[dict[str, Any]]
+    """Provider-specific metadata."""
+
+
+class ReasoningContentBlock(TypedDict):
+    """Reasoning output from a LLM.
+
+    .. note::
+        ``create_reasoning_block`` may also be used as a factory to create a
+        ``ReasoningContentBlock``. Benefits include:
+
+        * Automatic ID generation (when not provided)
+        * Required arguments strictly validated at creation time
+
+    """
+
+    type: Literal["reasoning"]
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """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]
+    """Reasoning text.
+
+    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 of block in aggregate response. Used during streaming."""
+
+    extras: NotRequired[dict[str, Any]]
+    """Provider-specific metadata."""
+
+
+# Note: `title` and `context` are fields that could be used to provide additional
+# information about the file, such as a description or summary of its content.
+# E.g. with Claude, you can provide a context for a file which is passed to the model.
+class ImageContentBlock(TypedDict):
+    """Image data.
+
+    .. note::
+        ``create_image_block`` may also be used as a factory to create a
+        ``ImageContentBlock``. Benefits include:
+
+        * Automatic ID generation (when not provided)
+        * Required arguments strictly validated at creation time
+
+    """
+
+    type: Literal["image"]
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """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]
+    """ID of the image file, e.g., from a file storage system."""
 
     mime_type: NotRequired[str]
-    """MIME type of the content block (if needed)."""
+    """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 of block in aggregate response. Used during streaming."""
+
+    url: NotRequired[str]
+    """URL of the image."""
+
+    base64: NotRequired[str]
+    """Data as a base64 string."""
 
-class URLContentBlock(BaseDataContentBlock):
-    """Content block for data from a URL."""
+    extras: NotRequired[dict[str, Any]]
+    """Provider-specific metadata."""
 
-    type: Literal["image", "audio", "file"]
-    """Type of the content block."""
-    source_type: Literal["url"]
-    """Source type (url)."""
-    url: str
-    """URL for data."""
 
+class VideoContentBlock(TypedDict):
+    """Video data.
 
-class Base64ContentBlock(BaseDataContentBlock):
-    """Content block for inline data from a base64 string."""
+    .. note::
+        ``create_video_block`` may also be used as a factory to create a
+        ``VideoContentBlock``. Benefits include:
 
-    type: Literal["image", "audio", "file"]
-    """Type of the content block."""
-    source_type: Literal["base64"]
-    """Source type (base64)."""
-    data: str
+        * Automatic ID generation (when not provided)
+        * Required arguments strictly validated at creation time
+
+    """
+
+    type: Literal["video"]
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """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]
+    """ID of the video file, e.g., from a file storage system."""
+
+    mime_type: NotRequired[str]
+    """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 of block in aggregate response. Used during streaming."""
+
+    url: NotRequired[str]
+    """URL of the video."""
+
+    base64: NotRequired[str]
     """Data as a base64 string."""
 
+    extras: NotRequired[dict[str, Any]]
+    """Provider-specific metadata."""
+
+
+class AudioContentBlock(TypedDict):
+    """Audio data.
+
+    .. 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
+
+    """
+
+    type: Literal["audio"]
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """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]
+    """ID of the audio file, e.g., from a file storage system."""
+
+    mime_type: NotRequired[str]
+    """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 of block in aggregate response. Used during streaming."""
+
+    url: NotRequired[str]
+    """URL of the audio."""
+
+    base64: NotRequired[str]
+    """Data as a base64 string."""
+
+    extras: NotRequired[dict[str, Any]]
+    """Provider-specific metadata."""
+
+
+class PlainTextContentBlock(TypedDict):
+    """Plaintext data (e.g., from a document).
+
+    .. note::
+        Title and context are optional fields that may be passed to the model. See
+        Anthropic `example <https://docs.anthropic.com/en/docs/build-with-claude/citations#citable-vs-non-citable-content>`__.
+
+    .. note::
+        ``create_plaintext_block`` may also be used as a factory to create a
+        ``PlainTextContentBlock``. Benefits include:
+
+        * Automatic ID generation (when not provided)
+        * Required arguments strictly validated at creation time
+
+    """
+
+    type: Literal["text-plain"]
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """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]
+    """ID of the plaintext file, e.g., from a file storage system."""
+
+    mime_type: Literal["text/plain"]
+    """MIME type of the file. Required for base64."""
+
+    index: NotRequired[int]
+    """Index of block in aggregate response. Used during streaming."""
+
+    url: NotRequired[str]
+    """URL of the plaintext."""
+
+    base64: NotRequired[str]
+    """Data as a base64 string."""
+
+    text: NotRequired[str]
+    """Plaintext content. This is optional if the data is provided as base64."""
+
+    title: NotRequired[str]
+    """Title of the text data, e.g., the title of a document."""
+
+    context: NotRequired[str]
+    """Context for the text, e.g., a description or summary of the text's content."""
+
+    extras: NotRequired[dict[str, Any]]
+    """Provider-specific metadata."""
+
+
+class FileContentBlock(TypedDict):
+    """File data that doesn't fit into other multimodal blocks.
+
+    This block is intended for files that are not images, audio, or plaintext. For
+    example, it can be used for PDFs, Word documents, etc.
+
+    If the file is an image, audio, or plaintext, you should use the corresponding
+    content block type (e.g., ``ImageContentBlock``, ``AudioContentBlock``,
+    ``PlainTextContentBlock``).
 
-class PlainTextContentBlock(BaseDataContentBlock):
-    """Content block for plain text data (e.g., from a document)."""
+    .. note::
+        ``create_file_block`` may also be used as a factory to create a
+        ``FileContentBlock``. Benefits include:
+
+        * Automatic ID generation (when not provided)
+        * Required arguments strictly validated at creation time
+
+    """
 
     type: Literal["file"]
-    """Type of the content block."""
-    source_type: Literal["text"]
-    """Source type (text)."""
-    text: str
-    """Text data."""
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """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]
+    """ID of the file, e.g., from a file storage system."""
 
-class IDContentBlock(TypedDict):
-    """Content block for data specified by an identifier."""
+    mime_type: NotRequired[str]
+    """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 of block in aggregate response. Used during streaming."""
+
+    url: NotRequired[str]
+    """URL of the file."""
+
+    base64: NotRequired[str]
+    """Data as a base64 string."""
 
-    type: Literal["image", "audio", "file"]
-    """Type of the content block."""
-    source_type: Literal["id"]
-    """Source type (id)."""
-    id: str
-    """Identifier for data source."""
+    extras: NotRequired[dict[str, Any]]
+    """Provider-specific metadata."""
 
 
+# Future modalities to consider:
+# - 3D models
+# - Tabular data
+
+
+class NonStandardContentBlock(TypedDict):
+    """Provider-specific data.
+
+    This block contains data for which there is not yet a standard type.
+
+    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.
+
+    .. note::
+        ``create_non_standard_block`` may also be used as a factory to create a
+        ``NonStandardContentBlock``. Benefits include:
+
+        * Automatic ID generation (when not provided)
+        * Required arguments strictly validated at creation time
+
+    """
+
+    type: Literal["non_standard"]
+    """Type of the content block. Used for discrimination."""
+
+    id: NotRequired[str]
+    """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 of block in aggregate response. Used during streaming."""
+
+
+# --- Aliases ---
 DataContentBlock = Union[
-    URLContentBlock,
-    Base64ContentBlock,
+    ImageContentBlock,
+    VideoContentBlock,
+    AudioContentBlock,
     PlainTextContentBlock,
-    IDContentBlock,
+    FileContentBlock,
 ]
 
-_DataContentBlockAdapter: TypeAdapter[DataContentBlock] = TypeAdapter(DataContentBlock)
+ToolContentBlock = Union[
+    ToolCall,
+    CodeInterpreterCall,
+    CodeInterpreterOutput,
+    CodeInterpreterResult,
+    WebSearchCall,
+    WebSearchResult,
+]
+
+ContentBlock = Union[
+    TextContentBlock,
+    ToolCall,
+    InvalidToolCall,
+    ToolCallChunk,
+    ReasoningContentBlock,
+    NonStandardContentBlock,
+    DataContentBlock,
+    ToolContentBlock,
+]
 
 
-def is_data_content_block(
-    content_block: dict,
-) -> bool:
+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",
+    "text-plain",
+    "tool_call",
+    "invalid_tool_call",
+    "tool_call_chunk",
+    "reasoning",
+    "non_standard",
+    "image",
+    "audio",
+    "file",
+    "video",
+    "code_interpreter_call",
+    "code_interpreter_output",
+    "code_interpreter_result",
+    "web_search_call",
+    "web_search_result",
+}
+
+
+def is_data_content_block(block: dict) -> bool:
     """Check if the content block is a standard data content block.
 
     Args:
-        content_block: The content block to check.
+        block: The content block to check.
 
     Returns:
         True if the content block is a data content block, False otherwise.
     """
-    try:
-        _ = _DataContentBlockAdapter.validate_python(content_block)
-    except ValidationError:
-        return False
-    else:
-        return True
+    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
+        )
+    )
 
 
-def convert_to_openai_image_block(content_block: dict[str, Any]) -> dict:
+def convert_to_openai_image_block(block: dict[str, Any]) -> dict:
     """Convert image content block to format expected by OpenAI Chat Completions API."""
-    if content_block["source_type"] == "url":
+    if "url" in block:
         return {
             "type": "image_url",
             "image_url": {
-                "url": content_block["url"],
+                "url": block["url"],
             },
         }
-    if content_block["source_type"] == "base64":
-        if "mime_type" not in content_block:
+    if "base64" in block or block.get("source_type") == "base64":
+        if "mime_type" not in block:
             error_message = "mime_type key is required for base64 data."
             raise ValueError(error_message)
-        mime_type = content_block["mime_type"]
+        mime_type = block["mime_type"]
+        base64_data = block["data"] if "data" in block else block["base64"]
         return {
             "type": "image_url",
             "image_url": {
-                "url": f"data:{mime_type};base64,{content_block['data']}",
+                "url": f"data:{mime_type};base64,{base64_data}",
             },
         }
     error_message = "Unsupported source type. Only 'url' and 'base64' are supported."
@@ -117,8 +942,9 @@ def convert_to_openai_data_block(block: dict) -> dict:
         formatted_block = convert_to_openai_image_block(block)
 
     elif block["type"] == "file":
-        if block["source_type"] == "base64":
-            file = {"file_data": f"data:{block['mime_type']};base64,{block['data']}"}
+        if "base64" in block or block.get("source_type") == "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):
@@ -126,30 +952,484 @@ def convert_to_openai_data_block(block: dict) -> dict:
             else:
                 warnings.warn(
                     "OpenAI may require a filename for file inputs. Specify a filename "
-                    "in the content block: {'type': 'file', 'source_type': 'base64', "
-                    "'mime_type': 'application/pdf', 'data': '...', "
-                    "'filename': 'my-pdf'}",
+                    "in the content block: {'type': 'file', 'mime_type': "
+                    "'application/pdf', 'base64': '...', 'filename': 'my-pdf'}",
                     stacklevel=1,
                 )
             formatted_block = {"type": "file", "file": file}
-        elif block["source_type"] == "id":
-            formatted_block = {"type": "file", "file": {"file_id": block["id"]}}
+        elif "file_id" in block or block.get("source_type") == "id":
+            file_id = block["id"] if "source_type" in block else block["file_id"]
+            formatted_block = {"type": "file", "file": {"file_id": file_id}}
         else:
-            error_msg = "source_type base64 or id is required for file blocks."
+            error_msg = "Keys base64 or file_id required for file blocks."
             raise ValueError(error_msg)
 
     elif block["type"] == "audio":
-        if block["source_type"] == "base64":
+        if "base64" in block or block.get("source_type") == "base64":
+            base64_data = block["data"] if "source_type" in block else block["base64"]
             audio_format = block["mime_type"].split("/")[-1]
             formatted_block = {
                 "type": "input_audio",
-                "input_audio": {"data": block["data"], "format": audio_format},
+                "input_audio": {"data": base64_data, "format": audio_format},
             }
         else:
-            error_msg = "source_type base64 is required for audio blocks."
+            error_msg = "Key base64 is required for audio blocks."
             raise ValueError(error_msg)
     else:
         error_msg = f"Block of type {block['type']} is not supported."
         raise ValueError(error_msg)
 
     return formatted_block
+
+
+def create_text_block(
+    text: str,
+    *,
+    id: Optional[str] = None,
+    annotations: Optional[list[Annotation]] = None,
+    index: Optional[int] = None,
+) -> 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.
+        index: Index of block in aggregate response. Used during streaming.
+
+    Returns:
+        A properly formatted ``TextContentBlock``.
+
+    .. note::
+        The ``id`` is generated automatically if not provided, using a UUID4 format
+        prefixed with ``'lc_'`` to indicate it is a LangChain-generated ID.
+
+    """
+    block = TextContentBlock(
+        type="text",
+        text=text,
+        id=_ensure_id(id),
+    )
+    if annotations is not None:
+        block["annotations"] = annotations
+    if index is not None:
+        block["index"] = index
+    return block
+
+
+def create_image_block(
+    *,
+    url: Optional[str] = None,
+    base64: Optional[str] = None,
+    file_id: Optional[str] = None,
+    mime_type: Optional[str] = None,
+    id: Optional[str] = None,
+    index: Optional[int] = None,
+) -> ImageContentBlock:
+    """Create an ``ImageContentBlock``.
+
+    Args:
+        url: URL of the image.
+        base64: Base64-encoded image data.
+        file_id: ID of the image file from a file storage system.
+        mime_type: MIME type of the image. Required for base64 data.
+        id: Content block identifier. Generated automatically if not provided.
+        index: Index of block in aggregate response. Used during streaming.
+
+    Returns:
+        A properly formatted ``ImageContentBlock``.
+
+    Raises:
+        ValueError: If no image source is provided or if ``base64`` is used without
+            ``mime_type``.
+
+    .. note::
+        The ``id`` is generated automatically if not provided, using a UUID4 format
+        prefixed with ``'lc_'`` to indicate it is a LangChain-generated ID.
+
+    """
+    if not any([url, base64, file_id]):
+        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))
+
+    if url is not None:
+        block["url"] = url
+    if base64 is not None:
+        block["base64"] = base64
+    if file_id is not None:
+        block["file_id"] = file_id
+    if mime_type is not None:
+        block["mime_type"] = mime_type
+    if index is not None:
+        block["index"] = index
+
+    return block
+
+
+def create_video_block(
+    *,
+    url: Optional[str] = None,
+    base64: Optional[str] = None,
+    file_id: Optional[str] = None,
+    mime_type: Optional[str] = None,
+    id: Optional[str] = None,
+    index: Optional[int] = None,
+) -> VideoContentBlock:
+    """Create a ``VideoContentBlock``.
+
+    Args:
+        url: URL of the video.
+        base64: Base64-encoded video data.
+        file_id: ID of the video file from a file storage system.
+        mime_type: MIME type of the video. Required for base64 data.
+        id: Content block identifier. Generated automatically if not provided.
+        index: Index of block in aggregate response. Used during streaming.
+
+    Returns:
+        A properly formatted ``VideoContentBlock``.
+
+    Raises:
+        ValueError: If no video source is provided or if ``base64`` is used without
+            ``mime_type``.
+
+    .. note::
+        The ``id`` is generated automatically if not provided, using a UUID4 format
+        prefixed with ``'lc_'`` to indicate it is a LangChain-generated ID.
+
+    """
+    if not any([url, base64, file_id]):
+        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 = VideoContentBlock(type="video", id=_ensure_id(id))
+
+    if url is not None:
+        block["url"] = url
+    if base64 is not None:
+        block["base64"] = base64
+    if file_id is not None:
+        block["file_id"] = file_id
+    if mime_type is not None:
+        block["mime_type"] = mime_type
+    if index is not None:
+        block["index"] = index
+
+    return block
+
+
+def create_audio_block(
+    *,
+    url: Optional[str] = None,
+    base64: Optional[str] = None,
+    file_id: Optional[str] = None,
+    mime_type: Optional[str] = None,
+    id: Optional[str] = None,
+    index: Optional[int] = None,
+) -> AudioContentBlock:
+    """Create an ``AudioContentBlock``.
+
+    Args:
+        url: URL of the audio.
+        base64: Base64-encoded audio data.
+        file_id: ID of the audio file from a file storage system.
+        mime_type: MIME type of the audio. Required for base64 data.
+        id: Content block identifier. Generated automatically if not provided.
+        index: Index of block in aggregate response. Used during streaming.
+
+    Returns:
+        A properly formatted ``AudioContentBlock``.
+
+    Raises:
+        ValueError: If no audio source is provided or if ``base64`` is used without
+            ``mime_type``.
+
+    .. note::
+        The ``id`` is generated automatically if not provided, using a UUID4 format
+        prefixed with ``'lc_'`` to indicate it is a LangChain-generated ID.
+
+    """
+    if not any([url, base64, file_id]):
+        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 = AudioContentBlock(type="audio", id=_ensure_id(id))
+
+    if url is not None:
+        block["url"] = url
+    if base64 is not None:
+        block["base64"] = base64
+    if file_id is not None:
+        block["file_id"] = file_id
+    if mime_type is not None:
+        block["mime_type"] = mime_type
+    if index is not None:
+        block["index"] = index
+
+    return block
+
+
+def create_file_block(
+    *,
+    url: Optional[str] = None,
+    base64: Optional[str] = None,
+    file_id: Optional[str] = None,
+    mime_type: Optional[str] = None,
+    id: Optional[str] = None,
+    index: Optional[int] = None,
+) -> FileContentBlock:
+    """Create a ``FileContentBlock``.
+
+    Args:
+        url: URL of the file.
+        base64: Base64-encoded file data.
+        file_id: ID of the file from a file storage system.
+        mime_type: MIME type of the file. Required for base64 data.
+        id: Content block identifier. Generated automatically if not provided.
+        index: Index of block in aggregate response. Used during streaming.
+
+    Returns:
+        A properly formatted ``FileContentBlock``.
+
+    Raises:
+        ValueError: If no file source is provided or if ``base64`` is used without
+            ``mime_type``.
+
+    .. note::
+        The ``id`` is generated automatically if not provided, using a UUID4 format
+        prefixed with ``'lc_'`` to indicate it is a LangChain-generated ID.
+
+    """
+    if not any([url, base64, file_id]):
+        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 = FileContentBlock(type="file", id=_ensure_id(id))
+
+    if url is not None:
+        block["url"] = url
+    if base64 is not None:
+        block["base64"] = base64
+    if file_id is not None:
+        block["file_id"] = file_id
+    if mime_type is not None:
+        block["mime_type"] = mime_type
+    if index is not None:
+        block["index"] = index
+
+    return block
+
+
+def create_plaintext_block(
+    text: str,
+    *,
+    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,
+) -> PlainTextContentBlock:
+    """Create a ``PlainTextContentBlock``.
+
+    Args:
+        text: The plaintext content.
+        url: URL of the plaintext file.
+        base64: Base64-encoded plaintext data.
+        file_id: ID of the plaintext file from a file storage system.
+        title: Title of the text data.
+        context: Context or description of the text content.
+        id: Content block identifier. Generated automatically if not provided.
+        index: Index of block in aggregate response. Used during streaming.
+
+    Returns:
+        A properly formatted ``PlainTextContentBlock``.
+
+    .. note::
+        The ``id`` is generated automatically if not provided, using a UUID4 format
+        prefixed with ``'lc_'`` to indicate it is a LangChain-generated ID.
+
+    """
+    block = PlainTextContentBlock(
+        type="text-plain",
+        mime_type="text/plain",
+        text=text,
+        id=_ensure_id(id),
+    )
+
+    if url is not None:
+        block["url"] = url
+    if base64 is not None:
+        block["base64"] = base64
+    if file_id is not None:
+        block["file_id"] = file_id
+    if title is not None:
+        block["title"] = title
+    if context is not None:
+        block["context"] = context
+    if index is not None:
+        block["index"] = index
+
+    return block
+
+
+def create_tool_call(
+    name: str,
+    args: dict[str, Any],
+    *,
+    id: Optional[str] = None,
+    index: Optional[int] = None,
+) -> ToolCall:
+    """Create a ``ToolCall``.
+
+    Args:
+        name: The name of the tool to be called.
+        args: The arguments to the tool call.
+        id: An identifier for the tool call. Generated automatically if not provided.
+        index: Index of block in aggregate response. Used during streaming.
+
+    Returns:
+        A properly formatted ``ToolCall``.
+
+    .. note::
+        The ``id`` is generated automatically if not provided, using a UUID4 format
+        prefixed with ``'lc_'`` to indicate it is a LangChain-generated ID.
+
+    """
+    block = ToolCall(
+        type="tool_call",
+        name=name,
+        args=args,
+        id=_ensure_id(id),
+    )
+
+    if index is not None:
+        block["index"] = index
+
+    return block
+
+
+def create_reasoning_block(
+    reasoning: Optional[str] = None,
+    id: Optional[str] = None,
+    index: Optional[int] = None,
+) -> ReasoningContentBlock:
+    """Create a ``ReasoningContentBlock``.
+
+    Args:
+        reasoning: The reasoning text or thought summary.
+        id: Content block identifier. Generated automatically if not provided.
+        index: Index of block in aggregate response. Used during streaming.
+
+    Returns:
+        A properly formatted ``ReasoningContentBlock``.
+
+    .. note::
+        The ``id`` is generated automatically if not provided, using a UUID4 format
+        prefixed with ``'lc_'`` to indicate it is a LangChain-generated ID.
+
+    """
+    block = ReasoningContentBlock(
+        type="reasoning",
+        reasoning=reasoning or "",
+        id=_ensure_id(id),
+    )
+
+    if index is not None:
+        block["index"] = index
+
+    return block
+
+
+def create_citation(
+    *,
+    url: Optional[str] = None,
+    title: Optional[str] = None,
+    start_index: Optional[int] = None,
+    end_index: Optional[int] = None,
+    cited_text: Optional[str] = None,
+    id: Optional[str] = None,
+) -> Citation:
+    """Create a ``Citation``.
+
+    Args:
+        url: URL of the document source.
+        title: Source document title.
+        start_index: Start index in the response text where citation applies.
+        end_index: End index in the response text where citation applies.
+        cited_text: Excerpt of source text being cited.
+        id: Content block identifier. Generated automatically if not provided.
+
+    Returns:
+        A properly formatted ``Citation``.
+
+    .. note::
+        The ``id`` is generated automatically if not provided, using a UUID4 format
+        prefixed with ``'lc_'`` to indicate it is a LangChain-generated ID.
+
+    """
+    block = Citation(type="citation", id=_ensure_id(id))
+
+    if url is not None:
+        block["url"] = url
+    if title is not None:
+        block["title"] = title
+    if start_index is not None:
+        block["start_index"] = start_index
+    if end_index is not None:
+        block["end_index"] = end_index
+    if cited_text is not None:
+        block["cited_text"] = cited_text
+
+    return block
+
+
+def create_non_standard_block(
+    value: dict[str, Any],
+    *,
+    id: Optional[str] = None,
+    index: Optional[int] = None,
+) -> NonStandardContentBlock:
+    """Create a ``NonStandardContentBlock``.
+
+    Args:
+        value: Provider-specific data.
+        id: Content block identifier. Generated automatically if not provided.
+        index: Index of block in aggregate response. Used during streaming.
+
+    Returns:
+        A properly formatted ``NonStandardContentBlock``.
+
+    .. note::
+        The ``id`` is generated automatically if not provided, using a UUID4 format
+        prefixed with ``'lc_'`` to indicate it is a LangChain-generated ID.
+
+    """
+    block = NonStandardContentBlock(
+        type="non_standard",
+        value=value,
+        id=_ensure_id(id),
+    )
+
+    if index is not None:
+        block["index"] = index
+
+    return block