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

langchain_core/language_models/base.py

@@ -4,38 +4,46 @@ 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 TypeAlias, TypedDict, override
+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
 from langchain_core.messages import (
+    AIMessage,
     AnyMessage,
     BaseMessage,
     MessageLikeRepresentation,
     get_buffer_string,
 )
-from langchain_core.prompt_values import PromptValue
+from langchain_core.prompt_values import (
+    ChatPromptValueConcrete,
+    PromptValue,
+    StringPromptValue,
+)
 from langchain_core.runnables import Runnable, RunnableSerializable
-from langchain_core.utils import get_pydantic_field_names
-from langchain_core.v1.messages import AIMessage as AIMessageV1
 
 if TYPE_CHECKING:
     from langchain_core.outputs import LLMResult
 
+try:
+    from transformers import GPT2TokenizerFast  # type: ignore[import-not-found]
+
+    _HAS_TRANSFORMERS = True
+except ImportError:
+    _HAS_TRANSFORMERS = False
+
 
 class LangSmithParams(TypedDict, total=False):
     """LangSmith parameters for tracing."""
@@ -46,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."""
 
 
@@ -58,18 +66,22 @@ class LangSmithParams(TypedDict, total=False):
 def get_tokenizer() -> Any:
     """Get a GPT-2 tokenizer instance.
 
-    This function is cached to avoid re-loading the tokenizer
-    every time it is called.
+    This function is cached to avoid re-loading the tokenizer every time it is called.
+
+    Raises:
+        ImportError: If the transformers package is not installed.
+
+    Returns:
+        The GPT-2 tokenizer instance.
+
     """
-    try:
-        from transformers import GPT2TokenizerFast  # type: ignore[import-not-found]
-    except ImportError as e:
+    if not _HAS_TRANSFORMERS:
         msg = (
             "Could not import transformers python package. "
             "This is needed in order to calculate get_token_ids. "
             "Please install it with `pip install transformers`."
         )
-        raise ImportError(msg) from e
+        raise ImportError(msg)
     # create a GPT-2 tokenizer instance
     return GPT2TokenizerFast.from_pretrained("gpt2")
 
@@ -83,17 +95,20 @@ 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]
-LanguageModelOutputVar = TypeVar(
-    "LanguageModelOutputVar", BaseMessage, str, AIMessageV1
-)
+"""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:
-    from langchain_core.globals import get_verbose
 
+def _get_verbosity() -> bool:
     return get_verbose()
 
 
@@ -102,16 +117,17 @@ 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.
     """
@@ -119,11 +135,11 @@ class BaseLanguageModel(
     """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."""
@@ -133,16 +149,17 @@ 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.
 
         Returns:
             The verbosity setting to use.
+
         """
         if verbose is None:
             return _get_verbosity()
@@ -151,26 +168,17 @@ class BaseLanguageModel(
     @property
     @override
     def InputType(self) -> TypeAlias:
-        """Get the input type for this runnable."""
-        from langchain_core.prompt_values import (
-            ChatPromptValueConcrete,
-            StringPromptValue,
-        )
-
+        """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:
@@ -180,32 +188,34 @@ class BaseLanguageModel(
         API.
 
         Use this method when you want to:
-            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).
+
+        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).
 
         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.
+
         """
 
     @abstractmethod
     async def agenerate_prompt(
         self,
         prompts: list[PromptValue],
-        stop: Optional[list[str]] = None,
+        stop: list[str] | None = None,
         callbacks: Callbacks = None,
         **kwargs: Any,
     ) -> LLMResult:
@@ -215,127 +225,37 @@ class BaseLanguageModel(
         API.
 
         Use this method when you want to:
-            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).
+
+        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).
 
         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."""
@@ -365,28 +285,31 @@ class BaseLanguageModel(
 
         Returns:
             The integer number of tokens in the text.
+
         """
         return len(self.get_token_ids(text))
 
     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 schemas.
+        !!! 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.
+
         """
         if tools is not None:
             warnings.warn(
@@ -394,11 +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)