langchain-core 0.3.74__py3-none-any.whl → 0.3.76__py3-none-any.whl

langchain_core/output_parsers/openai_tools.py

@@ -231,6 +231,9 @@ class JsonOutputKeyToolsParser(JsonOutputToolsParser):
                 If False, the output will be the full JSON object.
                 Default is False.
 
+        Raises:
+            OutputParserException: If the generation is not a chat generation.
+
         Returns:
             The parsed tool calls.
         """
@@ -246,6 +249,8 @@ class JsonOutputKeyToolsParser(JsonOutputToolsParser):
                     _ = tool_call.pop("id")
         else:
             try:
+                # This exists purely for backward compatibility / cached messages
+                # All new messages should use `message.tool_calls`
                 raw_tool_calls = copy.deepcopy(message.additional_kwargs["tool_calls"])
             except KeyError:
                 if self.first_tool_only:
@@ -314,7 +319,9 @@ class PydanticToolsParser(JsonOutputToolsParser):
             The parsed Pydantic objects.
 
         Raises:
-            OutputParserException: If the output is not valid JSON.
+            ValueError: If the tool call arguments are not a dict.
+            ValidationError: If the tool call arguments do not conform
+                to the Pydantic model.
         """
         json_results = super().parse_result(result, partial=partial)
         if not json_results:

langchain_core/output_parsers/pydantic.py

@@ -54,6 +54,10 @@ class PydanticOutputParser(JsonOutputParser, Generic[TBaseModel]):
                 all the keys that have been returned so far.
                 Defaults to False.
 
+        Raises:
+            OutputParserException: If the result is not valid JSON
+                or does not conform to the pydantic model.
+
         Returns:
             The parsed pydantic object.
         """

langchain_core/output_parsers/string.py

@@ -1,5 +1,7 @@
 """String output parser."""
 
+from typing_extensions import override
+
 from langchain_core.output_parsers.transform import BaseTransformOutputParser
 
 
@@ -19,7 +21,8 @@ class StrOutputParser(BaseTransformOutputParser[str]):
     def get_lc_namespace(cls) -> list[str]:
         """Get the namespace of the langchain object.
 
-        Default is ["langchain", "schema", "output_parser"].
+        Returns:
+            ``["langchain", "schema", "output_parser"]``
         """
         return ["langchain", "schema", "output_parser"]
 
@@ -28,6 +31,7 @@ class StrOutputParser(BaseTransformOutputParser[str]):
         """Return the output parser type for serialization."""
         return "default"
 
+    @override
     def parse(self, text: str) -> str:
         """Returns the input text with no changes."""
         return text

langchain_core/output_parsers/transform.py

@@ -32,7 +32,7 @@ class BaseTransformOutputParser(BaseOutputParser[T]):
 
     def _transform(
         self,
-        input: Iterator[Union[str, BaseMessage]],  # noqa: A002
+        input: Iterator[Union[str, BaseMessage]],
     ) -> Iterator[T]:
         for chunk in input:
             if isinstance(chunk, BaseMessage):
@@ -42,7 +42,7 @@ class BaseTransformOutputParser(BaseOutputParser[T]):
 
     async def _atransform(
         self,
-        input: AsyncIterator[Union[str, BaseMessage]],  # noqa: A002
+        input: AsyncIterator[Union[str, BaseMessage]],
     ) -> AsyncIterator[T]:
         async for chunk in input:
             if isinstance(chunk, BaseMessage):

langchain_core/output_parsers/xml.py

@@ -15,6 +15,14 @@ from langchain_core.messages import BaseMessage
 from langchain_core.output_parsers.transform import BaseTransformOutputParser
 from langchain_core.runnables.utils import AddableDict
 
+try:
+    from defusedxml import ElementTree  # type: ignore[import-untyped]
+    from defusedxml.ElementTree import XMLParser  # type: ignore[import-untyped]
+
+    _HAS_DEFUSEDXML = True
+except ImportError:
+    _HAS_DEFUSEDXML = False
+
 XML_FORMAT_INSTRUCTIONS = """The output should be formatted as a XML file.
 1. Output should conform to the tags below.
 2. If tags are not given, make them on your own.
@@ -50,17 +58,13 @@ class _StreamingParser:
                 parser is requested.
         """
         if parser == "defusedxml":
-            try:
-                from defusedxml.ElementTree import (  # type: ignore[import-untyped]
-                    XMLParser,
-                )
-            except ImportError as e:
+            if not _HAS_DEFUSEDXML:
                 msg = (
                     "defusedxml is not installed. "
                     "Please install it to use the defusedxml parser."
                     "You can install it with `pip install defusedxml` "
                 )
-                raise ImportError(msg) from e
+                raise ImportError(msg)
             parser_ = XMLParser(target=TreeBuilder())
         else:
             parser_ = None
@@ -105,10 +109,11 @@ class _StreamingParser:
         self.buffer = ""
         # yield all events
         try:
-            for event, elem in self.pull_parser.read_events():
+            events = self.pull_parser.read_events()
+            for event, elem in events:  # type: ignore[misc]
                 if event == "start":
                     # update current path
-                    self.current_path.append(elem.tag)
+                    self.current_path.append(elem.tag)  # type: ignore[union-attr]
                     self.current_path_has_children = False
                 elif event == "end":
                     # remove last element from current path
@@ -116,7 +121,7 @@ class _StreamingParser:
                     self.current_path.pop()
                     # yield element
                     if not self.current_path_has_children:
-                        yield nested_element(self.current_path, elem)
+                        yield nested_element(self.current_path, elem)  # type: ignore[arg-type]
                     # prevent yielding of parent element
                     if self.current_path:
                         self.current_path_has_children = True
@@ -135,9 +140,6 @@ class _StreamingParser:
         """Close the parser.
 
         This should be called after all chunks have been parsed.
-
-        Raises:
-            xml.etree.ElementTree.ParseError: If the XML is not well-formed.
         """
         # Ignore ParseError. This will ignore any incomplete XML at the end of the input
         with contextlib.suppress(xml.etree.ElementTree.ParseError):
@@ -153,14 +155,15 @@ class XMLOutputParser(BaseTransformOutputParser):
     Note this may not be perfect depending on the LLM implementation.
 
     For example, with tags=["foo", "bar", "baz"]:
-            1. A well-formatted XML instance:
-                "<foo>\n   <bar>\n      <baz></baz>\n   </bar>\n</foo>"
 
-            2. A badly-formatted XML instance (missing closing tag for 'bar'):
-                "<foo>\n   <bar>\n   </foo>"
+    1. A well-formatted XML instance:
+       "<foo>\n   <bar>\n      <baz></baz>\n   </bar>\n</foo>"
+
+    2. A badly-formatted XML instance (missing closing tag for 'bar'):
+       "<foo>\n   <bar>\n   </foo>"
 
-            3. A badly-formatted XML instance (unexpected 'tag' element):
-                "<foo>\n   <tag>\n   </tag>\n</foo>"
+    3. A badly-formatted XML instance (unexpected 'tag' element):
+       "<foo>\n   <tag>\n   </tag>\n</foo>"
     """
     encoding_matcher: re.Pattern = re.compile(
         r"<([^>]*encoding[^>]*)>\n(.*)", re.MULTILINE | re.DOTALL
@@ -208,16 +211,14 @@ class XMLOutputParser(BaseTransformOutputParser):
         # Imports are temporarily placed here to avoid issue with caching on CI
         # likely if you're reading this you can move them to the top of the file
         if self.parser == "defusedxml":
-            try:
-                from defusedxml import ElementTree  # type: ignore[import-untyped]
-            except ImportError as e:
+            if not _HAS_DEFUSEDXML:
                 msg = (
                     "defusedxml is not installed. "
                     "Please install it to use the defusedxml parser."
                     "You can install it with `pip install defusedxml`"
                     "See https://github.com/tiran/defusedxml for more details"
                 )
-                raise ImportError(msg) from e
+                raise ImportError(msg)
             et = ElementTree  # Use the defusedxml parser
         else:
             et = ET  # Use the standard library parser

langchain_core/outputs/chat_generation.py

@@ -47,9 +47,6 @@ class ChatGeneration(Generation):
 
         Returns:
             The values of the object with the text attribute set.
-
-        Raises:
-            ValueError: If the message is not a string or a list.
         """
         text = ""
         if isinstance(self.message.content, str):
@@ -83,11 +80,18 @@ class ChatGenerationChunk(ChatGeneration):
     def __add__(
         self, other: Union[ChatGenerationChunk, list[ChatGenerationChunk]]
     ) -> ChatGenerationChunk:
-        """Concatenate two ChatGenerationChunks.
+        """Concatenate two ``ChatGenerationChunk``s.
 
         Args:
-            other: The other ChatGenerationChunk or list of ChatGenerationChunks to
-                concatenate.
+            other: The other ``ChatGenerationChunk`` or list of ``ChatGenerationChunk``
+                to concatenate.
+
+        Raises:
+            TypeError: If other is not a ``ChatGenerationChunk`` or list of
+                ``ChatGenerationChunk``.
+
+        Returns:
+            A new ``ChatGenerationChunk`` concatenated from self and other.
         """
         if isinstance(other, ChatGenerationChunk):
             generation_info = merge_dicts(
@@ -116,7 +120,14 @@ class ChatGenerationChunk(ChatGeneration):
 def merge_chat_generation_chunks(
     chunks: list[ChatGenerationChunk],
 ) -> Union[ChatGenerationChunk, None]:
-    """Merge a list of ChatGenerationChunks into a single ChatGenerationChunk."""
+    """Merge a list of ``ChatGenerationChunk``s into a single ``ChatGenerationChunk``.
+
+    Args:
+        chunks: A list of ``ChatGenerationChunk`` to merge.
+
+    Returns:
+        A merged ``ChatGenerationChunk``, or None if the input list is empty.
+    """
     if not chunks:
         return None
 

langchain_core/outputs/generation.py

@@ -39,14 +39,15 @@ class Generation(Serializable):
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """Return whether this class is serializable."""
+        """Return True as this class is serializable."""
         return True
 
     @classmethod
     def get_lc_namespace(cls) -> list[str]:
         """Get the namespace of the langchain object.
 
-        Default namespace is ["langchain", "schema", "output"].
+        Returns:
+            ``["langchain", "schema", "output"]``
         """
         return ["langchain", "schema", "output"]
 
@@ -55,7 +56,17 @@ class GenerationChunk(Generation):
     """Generation chunk, which can be concatenated with other Generation chunks."""
 
     def __add__(self, other: GenerationChunk) -> GenerationChunk:
-        """Concatenate two GenerationChunks."""
+        """Concatenate two ``GenerationChunk``s.
+
+        Args:
+            other: Another ``GenerationChunk`` to concatenate with.
+
+        Raises:
+            TypeError: If other is not a ``GenerationChunk``.
+
+        Returns:
+            A new ``GenerationChunk`` concatenated from self and other.
+        """
         if isinstance(other, GenerationChunk):
             generation_info = merge_dicts(
                 self.generation_info or {},

langchain_core/outputs/llm_result.py

@@ -91,7 +91,14 @@ class LLMResult(BaseModel):
         return llm_results
 
     def __eq__(self, other: object) -> bool:
-        """Check for LLMResult equality by ignoring any metadata related to runs."""
+        """Check for ``LLMResult`` equality by ignoring any metadata related to runs.
+
+        Args:
+            other: Another ``LLMResult`` object to compare against.
+
+        Returns:
+            True if the generations and ``llm_output`` are equal, False otherwise.
+        """
         if not isinstance(other, LLMResult):
             return NotImplemented
         return (

langchain_core/prompt_values.py

@@ -30,7 +30,7 @@ class PromptValue(Serializable, ABC):
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """Return whether this class is serializable. Defaults to True."""
+        """Return True as this class is serializable."""
         return True
 
     @classmethod
@@ -38,7 +38,9 @@ class PromptValue(Serializable, ABC):
         """Get the namespace of the langchain object.
 
         This is used to determine the namespace of the object when serializing.
-        Defaults to ["langchain", "schema", "prompt"].
+
+        Returns:
+            ``["langchain", "schema", "prompt"]``
         """
         return ["langchain", "schema", "prompt"]
 
@@ -63,7 +65,9 @@ class StringPromptValue(PromptValue):
         """Get the namespace of the langchain object.
 
         This is used to determine the namespace of the object when serializing.
-        Defaults to ["langchain", "prompts", "base"].
+
+        Returns:
+            ``["langchain", "prompts", "base"]``
         """
         return ["langchain", "prompts", "base"]
 
@@ -98,7 +102,9 @@ class ChatPromptValue(PromptValue):
         """Get the namespace of the langchain object.
 
         This is used to determine the namespace of the object when serializing.
-        Defaults to ["langchain", "prompts", "chat"].
+
+        Returns:
+            ``["langchain", "prompts", "chat"]``
         """
         return ["langchain", "prompts", "chat"]
 

langchain_core/prompts/base.py

@@ -101,16 +101,14 @@ class BasePromptTemplate(
     def get_lc_namespace(cls) -> list[str]:
         """Get the namespace of the langchain object.
 
-        Returns ["langchain", "schema", "prompt_template"].
+        Returns:
+            ``["langchain", "schema", "prompt_template"]``
         """
         return ["langchain", "schema", "prompt_template"]
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """Return whether this class is serializable.
-
-        Returns True.
-        """
+        """Return True as this class is serializable."""
         return True
 
     model_config = ConfigDict(
@@ -212,7 +210,7 @@ class BasePromptTemplate(
         if self.metadata:
             config["metadata"] = {**config["metadata"], **self.metadata}
         if self.tags:
-            config["tags"] = config["tags"] + self.tags
+            config["tags"] += self.tags
         return self._call_with_config(
             self._format_prompt_with_error_handling,
             input,
@@ -341,9 +339,6 @@ class BasePromptTemplate(
 
         Returns:
             Dict: Dictionary representation of the prompt.
-
-        Raises:
-            NotImplementedError: If the prompt type is not implemented.
         """
         prompt_dict = super().model_dump(**kwargs)
         with contextlib.suppress(NotImplementedError):

langchain_core/prompts/chat.py

@@ -67,10 +67,10 @@ class MessagesPlaceholder(BaseMessagePromptTemplate):
             from langchain_core.prompts import MessagesPlaceholder
 
             prompt = MessagesPlaceholder("history")
-            prompt.format_messages() # raises KeyError
+            prompt.format_messages()  # raises KeyError
 
             prompt = MessagesPlaceholder("history", optional=True)
-            prompt.format_messages() # returns empty list []
+            prompt.format_messages()  # returns empty list []
 
             prompt.format_messages(
                 history=[
@@ -93,14 +93,14 @@ class MessagesPlaceholder(BaseMessagePromptTemplate):
                 [
                     ("system", "You are a helpful assistant."),
                     MessagesPlaceholder("history"),
-                    ("human", "{question}")
+                    ("human", "{question}"),
                 ]
             )
             prompt.invoke(
-               {
-                   "history": [("human", "what's 5 + 2"), ("ai", "5 + 2 is 7")],
-                   "question": "now multiply that by 4"
-               }
+                {
+                    "history": [("human", "what's 5 + 2"), ("ai", "5 + 2 is 7")],
+                    "question": "now multiply that by 4",
+                }
             )
             # -> ChatPromptValue(messages=[
             #     SystemMessage(content="You are a helpful assistant."),
@@ -155,9 +155,7 @@ class MessagesPlaceholder(BaseMessagePromptTemplate):
         """
         # mypy can't detect the init which is defined in the parent class
         # b/c these are BaseModel classes.
-        super().__init__(  # type: ignore[call-arg]
-            variable_name=variable_name, optional=optional, **kwargs
-        )
+        super().__init__(variable_name=variable_name, optional=optional, **kwargs)
 
     def format_messages(self, **kwargs: Any) -> list[BaseMessage]:
         """Format messages from kwargs.
@@ -742,10 +740,18 @@ class BaseChatPromptTemplate(BasePromptTemplate, ABC):
 
     @abstractmethod
     def format_messages(self, **kwargs: Any) -> list[BaseMessage]:
-        """Format kwargs into a list of messages."""
+        """Format kwargs into a list of messages.
+
+        Returns:
+            List of messages.
+        """
 
     async def aformat_messages(self, **kwargs: Any) -> list[BaseMessage]:
-        """Async format kwargs into a list of messages."""
+        """Async format kwargs into a list of messages.
+
+        Returns:
+            List of messages.
+        """
         return self.format_messages(**kwargs)
 
     def pretty_repr(
@@ -797,18 +803,17 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
 
             from langchain_core.prompts import ChatPromptTemplate
 
-            template = ChatPromptTemplate([
-                ("system", "You are a helpful AI bot. Your name is {name}."),
-                ("human", "Hello, how are you doing?"),
-                ("ai", "I'm doing well, thanks!"),
-                ("human", "{user_input}"),
-            ])
+            template = ChatPromptTemplate(
+                [
+                    ("system", "You are a helpful AI bot. Your name is {name}."),
+                    ("human", "Hello, how are you doing?"),
+                    ("ai", "I'm doing well, thanks!"),
+                    ("human", "{user_input}"),
+                ]
+            )
 
             prompt_value = template.invoke(
-                {
-                    "name": "Bob",
-                    "user_input": "What is your name?"
-                }
+                {"name": "Bob", "user_input": "What is your name?"}
             )
             # Output:
             # ChatPromptValue(
@@ -818,7 +823,7 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
             #        AIMessage(content="I'm doing well, thanks!"),
             #        HumanMessage(content='What is your name?')
             #    ]
-            #)
+            # )
 
     Messages Placeholder:
 
@@ -828,14 +833,16 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
             # you can initialize the template with a MessagesPlaceholder
             # either using the class directly or with the shorthand tuple syntax:
 
-            template = ChatPromptTemplate([
-                ("system", "You are a helpful AI bot."),
-                # Means the template will receive an optional list of messages under
-                # the "conversation" key
-                ("placeholder", "{conversation}")
-                # Equivalently:
-                # MessagesPlaceholder(variable_name="conversation", optional=True)
-            ])
+            template = ChatPromptTemplate(
+                [
+                    ("system", "You are a helpful AI bot."),
+                    # Means the template will receive an optional list of messages under
+                    # the "conversation" key
+                    ("placeholder", "{conversation}"),
+                    # Equivalently:
+                    # MessagesPlaceholder(variable_name="conversation", optional=True)
+                ]
+            )
 
             prompt_value = template.invoke(
                 {
@@ -843,7 +850,7 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
                         ("human", "Hi!"),
                         ("ai", "How can I assist you today?"),
                         ("human", "Can you make me an ice cream sundae?"),
-                        ("ai", "No.")
+                        ("ai", "No."),
                     ]
                 }
             )
@@ -857,7 +864,7 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
             #        HumanMessage(content='Can you make me an ice cream sundae?'),
             #        AIMessage(content='No.'),
             #    ]
-            #)
+            # )
 
     Single-variable template:
 
@@ -870,10 +877,12 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
 
             from langchain_core.prompts import ChatPromptTemplate
 
-            template = ChatPromptTemplate([
-                ("system", "You are a helpful AI bot. Your name is Carl."),
-                ("human", "{user_input}"),
-            ])
+            template = ChatPromptTemplate(
+                [
+                    ("system", "You are a helpful AI bot. Your name is Carl."),
+                    ("human", "{user_input}"),
+                ]
+            )
 
             prompt_value = template.invoke("Hello, there!")
             # Equivalent to
@@ -924,28 +933,29 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
             input_types: A dictionary of the types of the variables the prompt template
                 expects. If not provided, all variables are assumed to be strings.
 
-        Returns:
-            A chat prompt template.
-
         Examples:
             Instantiation from a list of message templates:
 
             .. code-block:: python
 
-                template = ChatPromptTemplate([
-                    ("human", "Hello, how are you?"),
-                    ("ai", "I'm doing well, thanks!"),
-                    ("human", "That's good to hear."),
-                ])
+                template = ChatPromptTemplate(
+                    [
+                        ("human", "Hello, how are you?"),
+                        ("ai", "I'm doing well, thanks!"),
+                        ("human", "That's good to hear."),
+                    ]
+                )
 
             Instantiation from mixed message formats:
 
             .. code-block:: python
 
-                template = ChatPromptTemplate([
-                    SystemMessage(content="hello"),
-                    ("human", "Hello, how are you?"),
-                ])
+                template = ChatPromptTemplate(
+                    [
+                        SystemMessage(content="hello"),
+                        ("human", "Hello, how are you?"),
+                    ]
+                )
 
         """
         messages_ = [
@@ -976,7 +986,11 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
 
     @classmethod
     def get_lc_namespace(cls) -> list[str]:
-        """Get the namespace of the langchain object."""
+        """Get the namespace of the langchain object.
+
+        Returns:
+            ``["langchain", "prompts", "chat"]``
+        """
         return ["langchain", "prompts", "chat"]
 
     def __add__(self, other: Any) -> ChatPromptTemplate:
@@ -1139,20 +1153,24 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
 
             .. code-block:: python
 
-                template = ChatPromptTemplate.from_messages([
-                    ("human", "Hello, how are you?"),
-                    ("ai", "I'm doing well, thanks!"),
-                    ("human", "That's good to hear."),
-                ])
+                template = ChatPromptTemplate.from_messages(
+                    [
+                        ("human", "Hello, how are you?"),
+                        ("ai", "I'm doing well, thanks!"),
+                        ("human", "That's good to hear."),
+                    ]
+                )
 
             Instantiation from mixed message formats:
 
             .. code-block:: python
 
-                template = ChatPromptTemplate.from_messages([
-                    SystemMessage(content="hello"),
-                    ("human", "Hello, how are you?"),
-                ])
+                template = ChatPromptTemplate.from_messages(
+                    [
+                        SystemMessage(content="hello"),
+                        ("human", "Hello, how are you?"),
+                    ]
+                )
 
         Args:
             messages: sequence of message representations.
@@ -1176,6 +1194,9 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
             **kwargs: keyword arguments to use for filling in template variables
                       in all the template messages in this chat template.
 
+        Raises:
+            ValueError: if messages are of unexpected types.
+
         Returns:
             list of formatted messages.
         """
@@ -1286,7 +1307,13 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
     def __getitem__(
         self, index: Union[int, slice]
     ) -> Union[MessageLike, ChatPromptTemplate]:
-        """Use to index into the chat template."""
+        """Use to index into the chat template.
+
+        Returns:
+            If index is an int, returns the message at that index.
+            If index is a slice, returns a new ``ChatPromptTemplate``
+            containing the messages in that slice.
+        """
         if isinstance(index, slice):
             start, stop, step = index.indices(len(self.messages))
             messages = self.messages[start:stop:step]
@@ -1294,7 +1321,7 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
         return self.messages[index]
 
     def __len__(self) -> int:
-        """Get the length of the chat template."""
+        """Return the length of the chat template."""
         return len(self.messages)
 
     @property