langchain-core 1.0.0a2__py3-none-any.whl → 1.0.0a3__py3-none-any.whl

langchain_core/language_models/__init__.py

@@ -26,7 +26,8 @@ https://python.langchain.com/docs/how_to/custom_chat_model/
 **LLMs**
 
 Language models that takes a string as input and returns a string.
-These are traditionally older models (newer models generally are Chat Models, see below).
+These are traditionally older models (newer models generally are Chat Models,
+see below).
 
 Although the underlying models are string in, string out, the LangChain wrappers
 also allow these models to take messages as input. This gives them the same interface
@@ -39,11 +40,12 @@ Please see the following guide for more information on how to implement a custom
 https://python.langchain.com/docs/how_to/custom_llm/
 
 
-"""  # noqa: E501
+"""
 
 from typing import TYPE_CHECKING
 
 from langchain_core._import_utils import import_attr
+from langchain_core.language_models._utils import is_openai_data_block
 
 if TYPE_CHECKING:
     from langchain_core.language_models.base import (
@@ -84,6 +86,7 @@ __all__ = (
     "ParrotFakeChatModel",
     "SimpleChatModel",
     "get_tokenizer",
+    "is_openai_data_block",
 )
 
 _dynamic_imports = {
@@ -103,6 +106,7 @@ _dynamic_imports = {
     "ParrotFakeChatModel": "fake_chat_models",
     "LLM": "llms",
     "BaseLLM": "llms",
+    "is_openai_data_block": "_utils",
 }
 
 

langchain_core/language_models/_utils.py

@@ -16,16 +16,34 @@ from langchain_core.messages.content import (
 )
 
 
-def _is_openai_data_block(block: dict) -> bool:
-    """Check if the block contains multimodal data in OpenAI Chat Completions format.
+def is_openai_data_block(
+    block: dict, filter_: Union[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'``)
 
     If additional keys are present, they are ignored / will not affect outcome as long
     as the required keys are present and valid.
 
+    Args:
+        block: The content block to check.
+        filter_: If provided, only return True for blocks matching this specific type.
+            - "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 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_
+        (if provided).
+
     """
     if block.get("type") == "image_url":
+        if filter_ is not None and filter_ != "image":
+            return False
         if (
             (set(block.keys()) <= {"type", "image_url", "detail"})
             and (image_url := block.get("image_url"))
@@ -38,6 +56,8 @@ def _is_openai_data_block(block: dict) -> bool:
             # Ignore `'detail'` since it's optional and specific to OpenAI
 
     elif block.get("type") == "input_audio":
+        if filter_ is not None and filter_ != "audio":
+            return False
         if (audio := block.get("input_audio")) and isinstance(audio, dict):
             audio_data = audio.get("data")
             audio_format = audio.get("format")
@@ -46,6 +66,8 @@ def _is_openai_data_block(block: dict) -> bool:
                 return True
 
     elif block.get("type") == "file":
+        if filter_ is not None and filter_ != "file":
+            return False
         if (file := block.get("file")) and isinstance(file, dict):
             file_data = file.get("file_data")
             file_id = file.get("file_id")
@@ -212,10 +234,10 @@ def _normalize_messages(
     }
 
     """
-    from langchain_core.messages.block_translators.langchain_v0 import (
+    from langchain_core.messages.block_translators.langchain_v0 import (  # noqa: PLC0415
         _convert_legacy_v0_content_block_to_v1,
     )
-    from langchain_core.messages.block_translators.openai import (
+    from langchain_core.messages.block_translators.openai import (  # noqa: PLC0415
         _convert_openai_format_to_data_block,
     )
 
@@ -232,7 +254,7 @@ def _normalize_messages(
                     isinstance(block, dict)
                     and block.get("type") in {"input_audio", "file"}
                     # Discriminate between OpenAI/LC format since they share `'type'`
-                    and _is_openai_data_block(block)
+                    and is_openai_data_block(block)
                 ):
                     formatted_message = _ensure_message_copy(message, formatted_message)
 

langchain_core/language_models/base.py

@@ -12,16 +12,18 @@ from typing import (
     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,
@@ -29,13 +31,24 @@ from langchain_core.messages import (
     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
 
 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."""
@@ -60,16 +73,20 @@ def get_tokenizer() -> Any:
 
     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")
 
@@ -90,8 +107,6 @@ LanguageModelOutputVar = TypeVar("LanguageModelOutputVar", AIMessage, str)
 
 
 def _get_verbosity() -> bool:
-    from langchain_core.globals import get_verbose
-
     return get_verbose()
 
 
@@ -153,11 +168,6 @@ class BaseLanguageModel(
     @override
     def InputType(self) -> TypeAlias:
         """Get the input type for this runnable."""
-        from langchain_core.prompt_values import (
-            ChatPromptValueConcrete,
-            StringPromptValue,
-        )
-
         # 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.
@@ -181,10 +191,11 @@ 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
@@ -217,10 +228,11 @@ 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

langchain_core/language_models/chat_models.py

@@ -51,6 +51,10 @@ from langchain_core.messages.block_translators.openai import (
     convert_to_openai_data_block,
     convert_to_openai_image_block,
 )
+from langchain_core.output_parsers.openai_tools import (
+    JsonOutputKeyToolsParser,
+    PydanticToolsParser,
+)
 from langchain_core.outputs import (
     ChatGeneration,
     ChatGenerationChunk,
@@ -143,8 +147,9 @@ def _format_for_tracing(messages: list[BaseMessage]) -> list[BaseMessage]:
                         )
                     elif (
                         block.get("type") == "file"
-                        and is_data_content_block(block)
+                        and is_data_content_block(block)  # v0 (image/audio/file) or v1
                         and "base64" in block
+                        # Narrows to old Base64ContentBlock or new FileContentBlock
                     ):
                         if message_to_trace is message:
                             # Shallow copy
@@ -167,8 +172,6 @@ def _format_for_tracing(messages: list[BaseMessage]) -> list[BaseMessage]:
                             "type": key,
                             key: block[key],
                         }
-                    else:
-                        pass
         messages_to_trace.append(message_to_trace)
 
     return messages_to_trace
@@ -180,6 +183,9 @@ def generate_from_stream(stream: Iterator[ChatGenerationChunk]) -> ChatResult:
     Args:
         stream: Iterator of ``ChatGenerationChunk``.
 
+    Raises:
+        ValueError: If no generations are found in the stream.
+
     Returns:
         ChatResult: Chat result.
 
@@ -369,7 +375,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
     @model_validator(mode="before")
     @classmethod
     def raise_deprecation(cls, values: dict) -> Any:
-        """Raise deprecation warning if ``callback_manager`` is used.
+        """Emit deprecation warning if ``callback_manager`` is used.
 
         Args:
             values (Dict): Values to validate.
@@ -377,9 +383,6 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
         Returns:
             Dict: Validated values.
 
-        Raises:
-            DeprecationWarning: If ``callback_manager`` is used.
-
         """
         if values.get("callback_manager") is not None:
             warnings.warn(
@@ -813,7 +816,9 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
             ls_params["ls_stop"] = stop
 
         # model
-        if hasattr(self, "model") and isinstance(self.model, str):
+        if "model" in kwargs and isinstance(kwargs["model"], str):
+            ls_params["ls_model_name"] = kwargs["model"]
+        elif hasattr(self, "model") and isinstance(self.model, str):
             ls_params["ls_model_name"] = self.model
         elif hasattr(self, "model_name") and isinstance(self.model_name, str):
             ls_params["ls_model_name"] = self.model_name
@@ -864,10 +869,11 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
         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:
             messages: List of list of messages.
@@ -979,10 +985,11 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
         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:
             messages: List of list of messages.
@@ -1350,7 +1357,17 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
         run_manager: Optional[CallbackManagerForLLMRun] = None,
         **kwargs: Any,
     ) -> ChatResult:
-        """Top Level call."""
+        """Generate the result.
+
+        Args:
+            messages: The messages to generate from.
+            stop: Optional list of stop words to use when generating.
+            run_manager: Optional callback manager to use for this call.
+            **kwargs: Additional keyword arguments to pass to the model.
+
+        Returns:
+            The chat result.
+        """
 
     async def _agenerate(
         self,
@@ -1359,7 +1376,17 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
         run_manager: Optional[AsyncCallbackManagerForLLMRun] = None,
         **kwargs: Any,
     ) -> ChatResult:
-        """Top Level call."""
+        """Generate the result.
+
+        Args:
+            messages: The messages to generate from.
+            stop: Optional list of stop words to use when generating.
+            run_manager: Optional callback manager to use for this call.
+            **kwargs: Additional keyword arguments to pass to the model.
+
+        Returns:
+            The chat result.
+        """
         return await run_in_executor(
             None,
             self._generate,
@@ -1376,6 +1403,17 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
         run_manager: Optional[CallbackManagerForLLMRun] = None,
         **kwargs: Any,
     ) -> Iterator[ChatGenerationChunk]:
+        """Stream the output of the model.
+
+        Args:
+            messages: The messages to generate from.
+            stop: Optional list of stop words to use when generating.
+            run_manager: Optional callback manager to use for this call.
+            **kwargs: Additional keyword arguments to pass to the model.
+
+        Yields:
+            The chat generation chunks.
+        """
         raise NotImplementedError
 
     async def _astream(
@@ -1385,6 +1423,17 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
         run_manager: Optional[AsyncCallbackManagerForLLMRun] = None,
         **kwargs: Any,
     ) -> AsyncIterator[ChatGenerationChunk]:
+        """Stream the output of the model.
+
+        Args:
+            messages: The messages to generate from.
+            stop: Optional list of stop words to use when generating.
+            run_manager: Optional callback manager to use for this call.
+            **kwargs: Additional keyword arguments to pass to the model.
+
+        Yields:
+            The chat generation chunks.
+        """
         iterator = await run_in_executor(
             None,
             self._stream,
@@ -1424,6 +1473,9 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
             **kwargs: Arbitrary additional keyword arguments. These are usually passed
                 to the model provider API call.
 
+        Raises:
+            ValueError: If the generation is not a chat generation.
+
         Returns:
             The model output message.
 
@@ -1485,6 +1537,9 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
             **kwargs: Arbitrary additional keyword arguments. These are usually passed
                 to the model provider API call.
 
+        Raises:
+            ValueError: If the output is not a string.
+
         Returns:
             The predicted output string.
 
@@ -1599,6 +1654,11 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
                 will be caught and returned as well. The final output is always a dict
                 with keys ``'raw'``, ``'parsed'``, and ``'parsing_error'``.
 
+        Raises:
+            ValueError: If there are any unsupported ``kwargs``.
+            NotImplementedError: If the model does not implement
+                ``with_structured_output()``.
+
         Returns:
             A Runnable that takes same inputs as a :class:`langchain_core.language_models.chat.BaseChatModel`.
 
@@ -1618,15 +1678,20 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
 
                 from pydantic import BaseModel
 
+
                 class AnswerWithJustification(BaseModel):
                     '''An answer to the user question along with justification for the answer.'''
+
                     answer: str
                     justification: str
 
+
                 llm = ChatModel(model="model-name", temperature=0)
                 structured_llm = llm.with_structured_output(AnswerWithJustification)
 
-                structured_llm.invoke("What weighs more a pound of bricks or a pound of feathers")
+                structured_llm.invoke(
+                    "What weighs more a pound of bricks or a pound of feathers"
+                )
 
                 # -> AnswerWithJustification(
                 #     answer='They weigh the same',
@@ -1638,15 +1703,22 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
 
                 from pydantic import BaseModel
 
+
                 class AnswerWithJustification(BaseModel):
                     '''An answer to the user question along with justification for the answer.'''
+
                     answer: str
                     justification: str
 
+
                 llm = ChatModel(model="model-name", temperature=0)
-                structured_llm = llm.with_structured_output(AnswerWithJustification, include_raw=True)
+                structured_llm = llm.with_structured_output(
+                    AnswerWithJustification, include_raw=True
+                )
 
-                structured_llm.invoke("What weighs more a pound of bricks or a pound of feathers")
+                structured_llm.invoke(
+                    "What weighs more a pound of bricks or a pound of feathers"
+                )
                 # -> {
                 #     'raw': AIMessage(content='', additional_kwargs={'tool_calls': [{'id': 'call_Ao02pnFYXD6GN1yzc0uXPsvF', 'function': {'arguments': '{"answer":"They weigh the same.","justification":"Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ."}', 'name': 'AnswerWithJustification'}, 'type': 'function'}]}),
                 #     'parsed': AnswerWithJustification(answer='They weigh the same.', justification='Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.'),
@@ -1659,16 +1731,21 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
                 from pydantic import BaseModel
                 from langchain_core.utils.function_calling import convert_to_openai_tool
 
+
                 class AnswerWithJustification(BaseModel):
                     '''An answer to the user question along with justification for the answer.'''
+
                     answer: str
                     justification: str
 
+
                 dict_schema = convert_to_openai_tool(AnswerWithJustification)
                 llm = ChatModel(model="model-name", temperature=0)
                 structured_llm = llm.with_structured_output(dict_schema)
 
-                structured_llm.invoke("What weighs more a pound of bricks or a pound of feathers")
+                structured_llm.invoke(
+                    "What weighs more a pound of bricks or a pound of feathers"
+                )
                 # -> {
                 #     'answer': 'They weigh the same',
                 #     'justification': 'Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume and density of the two substances differ.'
@@ -1685,11 +1762,6 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
             msg = f"Received unsupported arguments {kwargs}"
             raise ValueError(msg)
 
-        from langchain_core.output_parsers.openai_tools import (
-            JsonOutputKeyToolsParser,
-            PydanticToolsParser,
-        )
-
         if type(self).bind_tools is BaseChatModel.bind_tools:
             msg = "with_structured_output is not implemented for this model."
             raise NotImplementedError(msg)

langchain_core/language_models/fake_chat_models.py

@@ -75,12 +75,13 @@ class FakeListChatModel(SimpleChatModel):
     @override
     def _call(
         self,
-        messages: list[BaseMessage],
-        stop: Optional[list[str]] = None,
-        run_manager: Optional[CallbackManagerForLLMRun] = None,
+        *args: Any,
         **kwargs: Any,
     ) -> str:
-        """First try to lookup in queries, else return 'foo' or 'bar'."""
+        """Return the next response in the list.
+
+        Cycle back to the start if at the end.
+        """
         if self.sleep is not None:
             time.sleep(self.sleep)
         response = self.responses[self.i]
@@ -249,7 +250,6 @@ class GenericFakeChatModel(BaseChatModel):
         run_manager: Optional[CallbackManagerForLLMRun] = None,
         **kwargs: Any,
     ) -> ChatResult:
-        """Top Level call."""
         message = next(self.messages)
         message_ = AIMessage(content=message) if isinstance(message, str) else message
         generation = ChatGeneration(message=message_)
@@ -262,7 +262,6 @@ class GenericFakeChatModel(BaseChatModel):
         run_manager: Optional[CallbackManagerForLLMRun] = None,
         **kwargs: Any,
     ) -> Iterator[ChatGenerationChunk]:
-        """Stream the output of the model."""
         chat_result = self._generate(
             messages, stop=stop, run_manager=run_manager, **kwargs
         )
@@ -378,7 +377,6 @@ class ParrotFakeChatModel(BaseChatModel):
         run_manager: Optional[CallbackManagerForLLMRun] = None,
         **kwargs: Any,
     ) -> ChatResult:
-        """Top Level call."""
         return ChatResult(generations=[ChatGeneration(message=messages[-1])])
 
     @property