langchain-core 1.0.0a5__py3-none-any.whl → 1.0.3__py3-none-any.whl

langchain_core/language_models/_utils.py

@@ -3,10 +3,8 @@ from collections.abc import Sequence
 from typing import (
     TYPE_CHECKING,
     Literal,
-    Optional,
     TypedDict,
     TypeVar,
-    Union,
 )
 
 if TYPE_CHECKING:
@@ -17,11 +15,11 @@ from langchain_core.messages.content import (
 
 
 def is_openai_data_block(
-    block: dict, filter_: Union[Literal["image", "audio", "file"], None] = None
+    block: dict, filter_: Literal["image", "audio", "file"] | None = None
 ) -> bool:
     """Check whether a block contains multimodal data in OpenAI Chat Completions format.
 
-    Supports both data and ID-style blocks (e.g. ``'file_data'`` and ``'file_id'``)
+    Supports both data and ID-style blocks (e.g. `'file_data'` and `'file_id'`)
 
     If additional keys are present, they are ignored / will not affect outcome as long
     as the required keys are present and valid.
@@ -32,12 +30,12 @@ def is_openai_data_block(
             - "image": Only match image_url blocks
             - "audio": Only match input_audio blocks
             - "file": Only match file blocks
-            If None, match any valid OpenAI data block type. Note that this means that
+            If `None`, match any valid OpenAI data block type. Note that this means that
             if the block has a valid OpenAI data type but the filter_ is set to a
             different type, this function will return False.
 
     Returns:
-        True if the block is a valid OpenAI data block and matches the filter_
+        `True` if the block is a valid OpenAI data block and matches the filter_
         (if provided).
 
     """
@@ -88,24 +86,23 @@ class ParsedDataUri(TypedDict):
     mime_type: str
 
 
-def _parse_data_uri(uri: str) -> Optional[ParsedDataUri]:
+def _parse_data_uri(uri: str) -> ParsedDataUri | None:
     """Parse a data URI into its components.
 
-    If parsing fails, return None. If either MIME type or data is missing, return None.
+    If parsing fails, return `None`. If either MIME type or data is missing, return
+    `None`.
 
     Example:
-
-        .. code-block:: python
-
-            data_uri = "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
-            parsed = _parse_data_uri(data_uri)
-
-            assert parsed == {
-                "source_type": "base64",
-                "mime_type": "image/jpeg",
-                "data": "/9j/4AAQSkZJRg...",
-            }
-
+        ```python
+        data_uri = "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
+        parsed = _parse_data_uri(data_uri)
+
+        assert parsed == {
+            "source_type": "base64",
+            "mime_type": "image/jpeg",
+            "data": "/9j/4AAQSkZJRg...",
+        }
+        ```
     """
     regex = r"^data:(?P<mime_type>[^;]+);base64,(?P<data>.+)$"
     match = re.match(regex, uri)
@@ -135,65 +132,65 @@ def _normalize_messages(
     - LangChain v1 standard content blocks
 
     This function extends support to:
-    - `Audio <https://platform.openai.com/docs/api-reference/chat/create>`__ and
-        `file <https://platform.openai.com/docs/api-reference/files>`__ data in OpenAI
+    - `[Audio](https://platform.openai.com/docs/api-reference/chat/create) and
+        `[file](https://platform.openai.com/docs/api-reference/files) data in OpenAI
         Chat Completions format
         - Images are technically supported but we expect chat models to handle them
             directly; this may change in the future
     - LangChain v0 standard content blocks for backward compatibility
 
-    .. versionchanged:: 1.0.0
+    !!! warning "Behavior changed in 1.0.0"
         In previous versions, this function returned messages in LangChain v0 format.
         Now, it returns messages in LangChain v1 format, which upgraded chat models now
         expect to receive when passing back in message history. For backward
         compatibility, this function will convert v0 message content to v1 format.
 
-    .. dropdown:: v0 Content Block Schemas
+    ??? note "v0 Content Block Schemas"
 
-        ``URLContentBlock``:
+        `URLContentBlock`:
 
-        .. codeblock::
-
-            {
-                mime_type: NotRequired[str]
-                type: Literal['image', 'audio', 'file'],
-                source_type: Literal['url'],
-                url: str,
-            }
-
-        ``Base64ContentBlock``:
+        ```python
+        {
+            mime_type: NotRequired[str]
+            type: Literal['image', 'audio', 'file'],
+            source_type: Literal['url'],
+            url: str,
+        }
+        ```
 
-        .. codeblock::
+        `Base64ContentBlock`:
 
-            {
-                mime_type: NotRequired[str]
-                type: Literal['image', 'audio', 'file'],
-                source_type: Literal['base64'],
-                data: str,
-            }
+        ```python
+        {
+            mime_type: NotRequired[str]
+            type: Literal['image', 'audio', 'file'],
+            source_type: Literal['base64'],
+            data: str,
+        }
+        ```
 
-        ``IDContentBlock``:
+        `IDContentBlock`:
 
         (In practice, this was never used)
 
-        .. codeblock::
-
-            {
-                type: Literal['image', 'audio', 'file'],
-                source_type: Literal['id'],
-                id: str,
-            }
-
-        ``PlainTextContentBlock``:
+        ```python
+        {
+            type: Literal["image", "audio", "file"],
+            source_type: Literal["id"],
+            id: str,
+        }
+        ```
 
-        .. codeblock::
+        `PlainTextContentBlock`:
 
-            {
-                mime_type: NotRequired[str]
-                type: Literal['file'],
-                source_type: Literal['text'],
-                url: str,
-            }
+        ```python
+        {
+            mime_type: NotRequired[str]
+            type: Literal['file'],
+            source_type: Literal['text'],
+            url: str,
+        }
+        ```
 
     If a v1 message is passed in, it will be returned as-is, meaning it is safe to
     always pass in v1 messages to this function for assurance.
@@ -224,7 +221,7 @@ def _normalize_messages(
         "type": Literal['file'],
         "file": Union[
             {
-                "filename": Optional[str] = "$FILENAME",
+                "filename": str | None = "$FILENAME",
                 "file_data": str = "$BASE64_ENCODED_FILE",
             },
             {
@@ -304,7 +301,7 @@ def _ensure_message_copy(message: T, formatted_message: T) -> T:
 
 
 def _update_content_block(
-    formatted_message: "BaseMessage", idx: int, new_block: Union[ContentBlock, dict]
+    formatted_message: "BaseMessage", idx: int, new_block: ContentBlock | dict
 ) -> None:
     """Update a content block at the given index, handling type issues."""
     # Type ignore needed because:

langchain_core/language_models/base.py

@@ -4,23 +4,19 @@ from __future__ import annotations
 
 import warnings
 from abc import ABC, abstractmethod
-from collections.abc import Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from functools import cache
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
     Literal,
-    Optional,
     TypeAlias,
     TypeVar,
-    Union,
 )
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 from typing_extensions import TypedDict, override
 
-from langchain_core._api import deprecated
 from langchain_core.caches import BaseCache
 from langchain_core.callbacks import Callbacks
 from langchain_core.globals import get_verbose
@@ -37,7 +33,6 @@ from langchain_core.prompt_values import (
     StringPromptValue,
 )
 from langchain_core.runnables import Runnable, RunnableSerializable
-from langchain_core.utils import get_pydantic_field_names
 
 if TYPE_CHECKING:
     from langchain_core.outputs import LLMResult
@@ -59,11 +54,11 @@ class LangSmithParams(TypedDict, total=False):
     """Name of the model."""
     ls_model_type: Literal["chat", "llm"]
     """Type of the model. Should be 'chat' or 'llm'."""
-    ls_temperature: Optional[float]
+    ls_temperature: float | None
     """Temperature for generation."""
-    ls_max_tokens: Optional[int]
+    ls_max_tokens: int | None
     """Max tokens for generation."""
-    ls_stop: Optional[list[str]]
+    ls_stop: list[str] | None
     """Stop words for generation."""
 
 
@@ -100,10 +95,17 @@ def _get_token_ids_default_method(text: str) -> list[int]:
     return tokenizer.encode(text)
 
 
-LanguageModelInput = Union[PromptValue, str, Sequence[MessageLikeRepresentation]]
-LanguageModelOutput = Union[BaseMessage, str]
+LanguageModelInput = PromptValue | str | Sequence[MessageLikeRepresentation]
+"""Input to a language model."""
+
+LanguageModelOutput = BaseMessage | str
+"""Output from a language model."""
+
 LanguageModelLike = Runnable[LanguageModelInput, LanguageModelOutput]
+"""Input/output interface for a language model."""
+
 LanguageModelOutputVar = TypeVar("LanguageModelOutputVar", AIMessage, str)
+"""Type variable for the output of a language model."""
 
 
 def _get_verbosity() -> bool:
@@ -115,30 +117,29 @@ class BaseLanguageModel(
 ):
     """Abstract base class for interfacing with language models.
 
-    All language model wrappers inherited from ``BaseLanguageModel``.
+    All language model wrappers inherited from `BaseLanguageModel`.
 
     """
 
-    cache: Union[BaseCache, bool, None] = Field(default=None, exclude=True)
+    cache: BaseCache | bool | None = Field(default=None, exclude=True)
     """Whether to cache the response.
 
-    * If true, will use the global cache.
-    * If false, will not use a cache
-    * If None, will use the global cache if it's set, otherwise no cache.
-    * If instance of ``BaseCache``, will use the provided cache.
+    * If `True`, will use the global cache.
+    * If `False`, will not use a cache
+    * If `None`, will use the global cache if it's set, otherwise no cache.
+    * If instance of `BaseCache`, will use the provided cache.
 
     Caching is not currently supported for streaming methods of models.
-
     """
     verbose: bool = Field(default_factory=_get_verbosity, exclude=True, repr=False)
     """Whether to print out response text."""
     callbacks: Callbacks = Field(default=None, exclude=True)
     """Callbacks to add to the run trace."""
-    tags: Optional[list[str]] = Field(default=None, exclude=True)
+    tags: list[str] | None = Field(default=None, exclude=True)
     """Tags to add to the run trace."""
-    metadata: Optional[dict[str, Any]] = Field(default=None, exclude=True)
+    metadata: dict[str, Any] | None = Field(default=None, exclude=True)
     """Metadata to add to the run trace."""
-    custom_get_token_ids: Optional[Callable[[str], list[int]]] = Field(
+    custom_get_token_ids: Callable[[str], list[int]] | None = Field(
         default=None, exclude=True
     )
     """Optional encoder to use for counting tokens."""
@@ -148,10 +149,10 @@ class BaseLanguageModel(
     )
 
     @field_validator("verbose", mode="before")
-    def set_verbose(cls, verbose: Optional[bool]) -> bool:  # noqa: FBT001
-        """If verbose is None, set it.
+    def set_verbose(cls, verbose: bool | None) -> bool:  # noqa: FBT001
+        """If verbose is `None`, set it.
 
-        This allows users to pass in None as verbose to access the global setting.
+        This allows users to pass in `None` as verbose to access the global setting.
 
         Args:
             verbose: The verbosity setting to use.
@@ -167,21 +168,17 @@ class BaseLanguageModel(
     @property
     @override
     def InputType(self) -> TypeAlias:
-        """Get the input type for this runnable."""
+        """Get the input type for this `Runnable`."""
         # This is a version of LanguageModelInput which replaces the abstract
         # base class BaseMessage with a union of its subclasses, which makes
         # for a much better schema.
-        return Union[
-            str,
-            Union[StringPromptValue, ChatPromptValueConcrete],
-            list[AnyMessage],
-        ]
+        return str | StringPromptValue | ChatPromptValueConcrete | list[AnyMessage]
 
     @abstractmethod
     def generate_prompt(
         self,
         prompts: list[PromptValue],
-        stop: Optional[list[str]] = None,
+        stop: list[str] | None = None,
         callbacks: Callbacks = None,
         **kwargs: Any,
     ) -> LLMResult:
@@ -195,22 +192,22 @@ class BaseLanguageModel(
         1. Take advantage of batched calls,
         2. Need more output from the model than just the top generated value,
         3. Are building chains that are agnostic to the underlying language model
-           type (e.g., pure text completion models vs chat models).
+            type (e.g., pure text completion models vs chat models).
 
         Args:
-            prompts: List of PromptValues. A PromptValue is an object that can be
-                converted to match the format of any language model (string for pure
-                text generation models and BaseMessages for chat models).
+            prompts: List of `PromptValue` objects. A `PromptValue` is an object that
+                can be converted to match the format of any language model (string for
+                pure text generation models and `BaseMessage` objects for chat models).
             stop: Stop words to use when generating. Model output is cut off at the
                 first occurrence of any of these substrings.
-            callbacks: Callbacks to pass through. Used for executing additional
+            callbacks: `Callbacks` to pass through. Used for executing additional
                 functionality, such as logging or streaming, throughout generation.
             **kwargs: Arbitrary additional keyword arguments. These are usually passed
                 to the model provider API call.
 
         Returns:
-            An LLMResult, which contains a list of candidate Generations for each input
-            prompt and additional model provider-specific output.
+            An `LLMResult`, which contains a list of candidate `Generation` objects for
+                each input prompt and additional model provider-specific output.
 
         """
 
@@ -218,7 +215,7 @@ class BaseLanguageModel(
     async def agenerate_prompt(
         self,
         prompts: list[PromptValue],
-        stop: Optional[list[str]] = None,
+        stop: list[str] | None = None,
         callbacks: Callbacks = None,
         **kwargs: Any,
     ) -> LLMResult:
@@ -232,144 +229,47 @@ class BaseLanguageModel(
         1. Take advantage of batched calls,
         2. Need more output from the model than just the top generated value,
         3. Are building chains that are agnostic to the underlying language model
-           type (e.g., pure text completion models vs chat models).
+            type (e.g., pure text completion models vs chat models).
 
         Args:
-            prompts: List of PromptValues. A PromptValue is an object that can be
-                converted to match the format of any language model (string for pure
-                text generation models and BaseMessages for chat models).
+            prompts: List of `PromptValue` objects. A `PromptValue` is an object that
+                can be converted to match the format of any language model (string for
+                pure text generation models and `BaseMessage` objects for chat models).
             stop: Stop words to use when generating. Model output is cut off at the
                 first occurrence of any of these substrings.
-            callbacks: Callbacks to pass through. Used for executing additional
+            callbacks: `Callbacks` to pass through. Used for executing additional
                 functionality, such as logging or streaming, throughout generation.
             **kwargs: Arbitrary additional keyword arguments. These are usually passed
                 to the model provider API call.
 
         Returns:
-            An ``LLMResult``, which contains a list of candidate Generations for each
-            input prompt and additional model provider-specific output.
+            An `LLMResult`, which contains a list of candidate `Generation` objects for
+                each input prompt and additional model provider-specific output.
 
         """
 
     def with_structured_output(
-        self, schema: Union[dict, type], **kwargs: Any
-    ) -> Runnable[LanguageModelInput, Union[dict, BaseModel]]:
+        self, schema: dict | type, **kwargs: Any
+    ) -> Runnable[LanguageModelInput, dict | BaseModel]:
         """Not implemented on this class."""
         # Implement this on child class if there is a way of steering the model to
         # generate responses that match a given schema.
         raise NotImplementedError
 
-    @deprecated("0.1.7", alternative="invoke", removal="1.0")
-    @abstractmethod
-    def predict(
-        self, text: str, *, stop: Optional[Sequence[str]] = None, **kwargs: Any
-    ) -> str:
-        """Pass a single string input to the model and return a string.
-
-        Use this method when passing in raw text. If you want to pass in specific types
-        of chat messages, use predict_messages.
-
-        Args:
-            text: String input to pass to the model.
-            stop: Stop words to use when generating. Model output is cut off at the
-                first occurrence of any of these substrings.
-            **kwargs: Arbitrary additional keyword arguments. These are usually passed
-                to the model provider API call.
-
-        Returns:
-            Top model prediction as a string.
-
-        """
-
-    @deprecated("0.1.7", alternative="invoke", removal="1.0")
-    @abstractmethod
-    def predict_messages(
-        self,
-        messages: list[BaseMessage],
-        *,
-        stop: Optional[Sequence[str]] = None,
-        **kwargs: Any,
-    ) -> BaseMessage:
-        """Pass a message sequence to the model and return a message.
-
-        Use this method when passing in chat messages. If you want to pass in raw text,
-        use predict.
-
-        Args:
-            messages: A sequence of chat messages corresponding to a single model input.
-            stop: Stop words to use when generating. Model output is cut off at the
-                first occurrence of any of these substrings.
-            **kwargs: Arbitrary additional keyword arguments. These are usually passed
-                to the model provider API call.
-
-        Returns:
-            Top model prediction as a message.
-
-        """
-
-    @deprecated("0.1.7", alternative="ainvoke", removal="1.0")
-    @abstractmethod
-    async def apredict(
-        self, text: str, *, stop: Optional[Sequence[str]] = None, **kwargs: Any
-    ) -> str:
-        """Asynchronously pass a string to the model and return a string.
-
-        Use this method when calling pure text generation models and only the top
-        candidate generation is needed.
-
-        Args:
-            text: String input to pass to the model.
-            stop: Stop words to use when generating. Model output is cut off at the
-                first occurrence of any of these substrings.
-            **kwargs: Arbitrary additional keyword arguments. These are usually passed
-                to the model provider API call.
-
-        Returns:
-            Top model prediction as a string.
-
-        """
-
-    @deprecated("0.1.7", alternative="ainvoke", removal="1.0")
-    @abstractmethod
-    async def apredict_messages(
-        self,
-        messages: list[BaseMessage],
-        *,
-        stop: Optional[Sequence[str]] = None,
-        **kwargs: Any,
-    ) -> BaseMessage:
-        """Asynchronously pass messages to the model and return a message.
-
-        Use this method when calling chat models and only the top candidate generation
-        is needed.
-
-        Args:
-            messages: A sequence of chat messages corresponding to a single model input.
-            stop: Stop words to use when generating. Model output is cut off at the
-                first occurrence of any of these substrings.
-            **kwargs: Arbitrary additional keyword arguments. These are usually passed
-                to the model provider API call.
-
-        Returns:
-            Top model prediction as a message.
-
-        """
-
     @property
     def _identifying_params(self) -> Mapping[str, Any]:
         """Get the identifying parameters."""
         return self.lc_attributes
 
     def get_token_ids(self, text: str) -> list[int]:
-        """Return the ordered ids of the tokens in a text.
+        """Return the ordered IDs of the tokens in a text.
 
         Args:
             text: The string input to tokenize.
 
         Returns:
-            A list of ids corresponding to the tokens in the text, in order they occur
-            in the text.
-
+            A list of IDs corresponding to the tokens in the text, in order they occur
+                in the text.
         """
         if self.custom_get_token_ids is not None:
             return self.custom_get_token_ids(text)
@@ -392,20 +292,20 @@ class BaseLanguageModel(
     def get_num_tokens_from_messages(
         self,
         messages: list[BaseMessage],
-        tools: Optional[Sequence] = None,
+        tools: Sequence | None = None,
     ) -> int:
         """Get the number of tokens in the messages.
 
         Useful for checking if an input fits in a model's context window.
 
-        .. note::
-            The base implementation of ``get_num_tokens_from_messages`` ignores tool
+        !!! note
+            The base implementation of `get_num_tokens_from_messages` ignores tool
             schemas.
 
         Args:
             messages: The message inputs to tokenize.
-            tools: If provided, sequence of dict, ``BaseModel``, function, or
-                ``BaseTools`` to be converted to tool schemas.
+            tools: If provided, sequence of dict, `BaseModel`, function, or
+                `BaseTool` objects to be converted to tool schemas.
 
         Returns:
             The sum of the number of tokens across the messages.
@@ -417,12 +317,3 @@ class BaseLanguageModel(
                 stacklevel=2,
             )
         return sum(self.get_num_tokens(get_buffer_string([m])) for m in messages)
-
-    @classmethod
-    def _all_required_field_names(cls) -> set:
-        """DEPRECATED: Kept for backwards compatibility.
-
-        Use ``get_pydantic_field_names``.
-
-        """
-        return get_pydantic_field_names(cls)