langchain-core 0.3.75__py3-none-any.whl → 0.3.77__py3-none-any.whl

langchain_core/indexing/base.py

@@ -7,6 +7,8 @@ import time
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, Optional, TypedDict
 
+from typing_extensions import override
+
 from langchain_core._api import beta
 from langchain_core.retrievers import BaseRetriever
 from langchain_core.runnables import run_in_executor
@@ -254,14 +256,14 @@ class InMemoryRecordManager(RecordManager):
         """In-memory schema creation is simply ensuring the structure is initialized."""
 
     async def acreate_schema(self) -> None:
-        """Async in-memory schema creation is simply ensuring the structure is initialized."""  # noqa: E501
+        """In-memory schema creation is simply ensuring the structure is initialized."""
 
+    @override
     def get_time(self) -> float:
-        """Get the current server time as a high resolution timestamp!"""
         return time.time()
 
+    @override
     async def aget_time(self) -> float:
-        """Async get the current server time as a high resolution timestamp!"""
         return self.get_time()
 
     def update(
@@ -322,11 +324,6 @@ class InMemoryRecordManager(RecordManager):
                 raise an error.
                 This is meant to help prevent time-drift issues since
                 time may not be monotonically increasing!
-
-        Raises:
-            ValueError: If the length of keys doesn't match the length of group
-                ids.
-            ValueError: If time_at_least is in the future.
         """
         self.update(keys, group_ids=group_ids, time_at_least=time_at_least)
 

langchain_core/indexing/in_memory.py

@@ -32,7 +32,17 @@ class InMemoryDocumentIndex(DocumentIndex):
 
     @override
     def upsert(self, items: Sequence[Document], /, **kwargs: Any) -> UpsertResponse:
-        """Upsert items into the index."""
+        """Upsert documents into the index.
+
+        Args:
+            items: Sequence of documents to add to the index.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            A response object that contains the list of IDs that were
+            successfully added or updated in the index and the list of IDs that
+            failed to be added or updated.
+        """
         ok_ids = []
 
         for item in items:
@@ -51,7 +61,18 @@ class InMemoryDocumentIndex(DocumentIndex):
 
     @override
     def delete(self, ids: Optional[list[str]] = None, **kwargs: Any) -> DeleteResponse:
-        """Delete by ID."""
+        """Delete by IDs.
+
+        Args:
+            ids: List of ids to delete.
+
+        Raises:
+            ValueError: If ids is None.
+
+        Returns:
+            A response object that contains the list of IDs that were successfully
+            deleted and the list of IDs that failed to be deleted.
+        """
         if ids is None:
             msg = "IDs must be provided for deletion"
             raise ValueError(msg)
@@ -69,7 +90,6 @@ class InMemoryDocumentIndex(DocumentIndex):
 
     @override
     def get(self, ids: Sequence[str], /, **kwargs: Any) -> list[Document]:
-        """Get by ids."""
         return [self.store[id_] for id_ in ids if id_ in self.store]
 
     @override

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,7 +40,7 @@ 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
 

langchain_core/language_models/base.py

@@ -22,19 +22,31 @@ from typing_extensions import TypeAlias, 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 (
     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
 
 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."""
@@ -59,16 +71,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")
 
@@ -89,8 +105,6 @@ LanguageModelOutputVar = TypeVar("LanguageModelOutputVar", BaseMessage, str)
 
 
 def _get_verbosity() -> bool:
-    from langchain_core.globals import get_verbose
-
     return get_verbose()
 
 
@@ -152,11 +166,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.
@@ -180,10 +189,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
@@ -216,10 +226,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

@@ -46,6 +46,10 @@ from langchain_core.messages import (
     message_chunk_to_message,
 )
 from langchain_core.messages.ai import _LC_ID_PREFIX
+from langchain_core.output_parsers.openai_tools import (
+    JsonOutputKeyToolsParser,
+    PydanticToolsParser,
+)
 from langchain_core.outputs import (
     ChatGeneration,
     ChatGenerationChunk,
@@ -148,8 +152,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
@@ -161,6 +163,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.
 
@@ -328,7 +333,7 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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.
@@ -336,9 +341,6 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], ABC):
         Returns:
             Dict: Validated values.
 
-        Raises:
-            DeprecationWarning: If ``callback_manager`` is used.
-
         """
         if values.get("callback_manager") is not None:
             warnings.warn(
@@ -469,7 +471,7 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], ABC):
         **kwargs: Any,
     ) -> Iterator[BaseMessageChunk]:
         if not self._should_stream(async_api=False, **{**kwargs, "stream": True}):
-            # model doesn't implement streaming, so use default implementation
+            # Model doesn't implement streaming, so use default implementation
             yield cast(
                 "BaseMessageChunk",
                 self.invoke(input, config=config, stop=stop, **kwargs),
@@ -718,7 +720,9 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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
@@ -769,10 +773,11 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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.
@@ -884,10 +889,11 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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.
@@ -1185,7 +1191,17 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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,
@@ -1194,7 +1210,17 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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,
@@ -1211,6 +1237,17 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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(
@@ -1220,6 +1257,17 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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,
@@ -1259,6 +1307,9 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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.
 
@@ -1320,6 +1371,9 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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.
 
@@ -1434,6 +1488,11 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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`.
 
@@ -1453,15 +1512,20 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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',
@@ -1473,15 +1537,22 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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.'),
@@ -1494,16 +1565,21 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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.'
@@ -1520,11 +1596,6 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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

@@ -19,7 +19,7 @@ from langchain_core.runnables import RunnableConfig
 
 
 class FakeMessagesListChatModel(BaseChatModel):
-    """Fake ChatModel for testing purposes."""
+    """Fake ``ChatModel`` for testing purposes."""
 
     responses: list[BaseMessage]
     """List of responses to **cycle** through in order."""
@@ -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]
@@ -211,10 +212,11 @@ class GenericFakeChatModel(BaseChatModel):
     """Generic fake chat model that can be used to test the chat model interface.
 
     * Chat model should be usable in both sync and async tests
-    * Invokes on_llm_new_token to allow for testing of callback related code for new
+    * Invokes ``on_llm_new_token`` to allow for testing of callback related code for new
       tokens.
     * Includes logic to break messages into message chunk to facilitate testing of
       streaming.
+
     """
 
     messages: Iterator[Union[AIMessage, str]]
@@ -229,6 +231,7 @@ class GenericFakeChatModel(BaseChatModel):
     .. warning::
         Streaming is not implemented yet. We should try to implement it in the future by
         delegating to invoke and then breaking the resulting output into message chunks.
+
     """
 
     @override
@@ -239,7 +242,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_)
@@ -252,7 +254,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
         )
@@ -352,6 +353,7 @@ class ParrotFakeChatModel(BaseChatModel):
     """Generic fake chat model that can be used to test the chat model interface.
 
     * Chat model should be usable in both sync and async tests
+
     """
 
     @override
@@ -362,7 +364,6 @@ class ParrotFakeChatModel(BaseChatModel):
         run_manager: Optional[CallbackManagerForLLMRun] = None,
         **kwargs: Any,
     ) -> ChatResult:
-        """Top Level call."""
         return ChatResult(generations=[ChatGeneration(message=messages[-1])])
 
     @property