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

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
@@ -136,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):
@@ -154,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
@@ -209,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):
@@ -384,10 +379,10 @@ class BasePromptTemplate(
         directory_path.mkdir(parents=True, exist_ok=True)
 
         if save_path.suffix == ".json":
-            with save_path.open("w") as f:
+            with save_path.open("w", encoding="utf-8") as f:
                 json.dump(prompt_dict, f, indent=4)
         elif save_path.suffix.endswith((".yaml", ".yml")):
-            with save_path.open("w") as f:
+            with save_path.open("w", encoding="utf-8") as f:
                 yaml.dump(prompt_dict, f, default_flow_style=False)
         else:
             msg = f"{save_path} must be json or yaml"

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."),
@@ -543,8 +543,7 @@ class _StringImageMessagePromptTemplate(BaseMessagePromptTemplate):
         Returns:
             A new instance of this class.
         """
-        template = Path(template_file).read_text()
-        # TODO: .read_text(encoding="utf-8") for v0.4
+        template = Path(template_file).read_text(encoding="utf-8")
         return cls.from_template(template, input_variables=input_variables, **kwargs)
 
     def format_messages(self, **kwargs: Any) -> list[BaseMessage]:
@@ -740,10 +739,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(
@@ -795,18 +802,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(
@@ -816,7 +822,7 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
             #        AIMessage(content="I'm doing well, thanks!"),
             #        HumanMessage(content='What is your name?')
             #    ]
-            #)
+            # )
 
     Messages Placeholder:
 
@@ -826,14 +832,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(
                 {
@@ -841,7 +849,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."),
                     ]
                 }
             )
@@ -855,7 +863,7 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
             #        HumanMessage(content='Can you make me an ice cream sundae?'),
             #        AIMessage(content='No.'),
             #    ]
-            #)
+            # )
 
     Single-variable template:
 
@@ -868,10 +876,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
@@ -922,28 +932,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_ = [
@@ -974,7 +985,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:
@@ -1137,20 +1152,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.
@@ -1174,6 +1193,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.
         """
@@ -1284,7 +1306,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]
@@ -1292,7 +1320,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

langchain_core/prompts/dict.py

@@ -31,18 +31,25 @@ class DictPromptTemplate(RunnableSerializable[dict, dict]):
         return _get_input_variables(self.template, self.template_format)
 
     def format(self, **kwargs: Any) -> dict[str, Any]:
-        """Format the prompt with the inputs."""
+        """Format the prompt with the inputs.
+
+        Returns:
+            A formatted dict.
+        """
         return _insert_input_variables(self.template, kwargs, self.template_format)
 
     async def aformat(self, **kwargs: Any) -> dict[str, Any]:
-        """Format the prompt with the inputs."""
+        """Format the prompt with the inputs.
+
+        Returns:
+            A formatted dict.
+        """
         return self.format(**kwargs)
 
     @override
     def invoke(
         self, input: dict, config: Optional[RunnableConfig] = None, **kwargs: Any
     ) -> dict:
-        """Invoke the prompt."""
         return self._call_with_config(
             lambda x: self.format(**x),
             input,
@@ -62,15 +69,16 @@ class DictPromptTemplate(RunnableSerializable[dict, dict]):
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """Return whether or not the class is serializable.
-
-        Returns: True.
-        """
+        """Return True as this class is serializable."""
         return True
 
     @classmethod
     def get_lc_namespace(cls) -> list[str]:
-        """Serialization namespace."""
+        """Get the namespace of the langchain object.
+
+        Returns:
+            ``["langchain_core", "prompts", "dict"]``
+        """
         return ["langchain_core", "prompts", "dict"]
 
     def pretty_repr(self, *, html: bool = False) -> str: