langchain-core 0.3.79__py3-none-any.whl → 1.0.0__py3-none-any.whl

langchain_core/output_parsers/__init__.py

@@ -1,17 +1,4 @@
-"""**OutputParser** classes parse the output of an LLM call.
-
-**Class hierarchy:**
-
-.. code-block::
-
-    BaseLLMOutputParser --> BaseOutputParser --> <name>OutputParser  # ListOutputParser, PydanticOutputParser
-
-**Main helpers:**
-
-.. code-block::
-
-    Serializable, Generation, PromptValue
-"""  # noqa: E501
+"""**OutputParser** classes parse the output of an LLM call."""
 
 from typing import TYPE_CHECKING
 

langchain_core/output_parsers/base.py

@@ -8,9 +8,7 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Generic,
-    Optional,
     TypeVar,
-    Union,
 )
 
 from typing_extensions import override
@@ -33,13 +31,13 @@ class BaseLLMOutputParser(ABC, Generic[T]):
 
     @abstractmethod
     def parse_result(self, result: list[Generation], *, partial: bool = False) -> T:
-        """Parse a list of candidate model Generations into a specific format.
+        """Parse a list of candidate model `Generation` objects into a specific format.
 
         Args:
-            result: A list of Generations to be parsed. The Generations are assumed
-                to be different candidate outputs for a single model input.
+            result: A list of `Generation` to be parsed. The `Generation` objects are
+                assumed to be different candidate outputs for a single model input.
             partial: Whether to parse the output as a partial result. This is useful
-                for parsers that can parse partial results. Default is False.
+                for parsers that can parse partial results.
 
         Returns:
             Structured output.
@@ -48,17 +46,17 @@ class BaseLLMOutputParser(ABC, Generic[T]):
     async def aparse_result(
         self, result: list[Generation], *, partial: bool = False
     ) -> T:
-        """Async parse a list of candidate model Generations into a specific format.
+        """Async parse a list of candidate model `Generation` objects into a specific format.
 
         Args:
-            result: A list of Generations to be parsed. The Generations are assumed
+            result: A list of `Generation` to be parsed. The Generations are assumed
                 to be different candidate outputs for a single model input.
             partial: Whether to parse the output as a partial result. This is useful
-                for parsers that can parse partial results. Default is False.
+                for parsers that can parse partial results.
 
         Returns:
             Structured output.
-        """
+        """  # noqa: E501
         return await run_in_executor(None, self.parse_result, result, partial=partial)
 
 
@@ -71,7 +69,7 @@ class BaseGenerationOutputParser(
     @override
     def InputType(self) -> Any:
         """Return the input type for the parser."""
-        return Union[str, AnyMessage]
+        return str | AnyMessage
 
     @property
     @override
@@ -84,8 +82,8 @@ class BaseGenerationOutputParser(
     @override
     def invoke(
         self,
-        input: Union[str, BaseMessage],
-        config: Optional[RunnableConfig] = None,
+        input: str | BaseMessage,
+        config: RunnableConfig | None = None,
         **kwargs: Any,
     ) -> T:
         if isinstance(input, BaseMessage):
@@ -107,9 +105,9 @@ class BaseGenerationOutputParser(
     @override
     async def ainvoke(
         self,
-        input: Union[str, BaseMessage],
-        config: Optional[RunnableConfig] = None,
-        **kwargs: Optional[Any],
+        input: str | BaseMessage,
+        config: RunnableConfig | None = None,
+        **kwargs: Any | None,
     ) -> T:
         if isinstance(input, BaseMessage):
             return await self._acall_with_config(
@@ -136,36 +134,35 @@ class BaseOutputParser(
     Output parsers help structure language model responses.
 
     Example:
-        .. code-block:: python
-
-            class BooleanOutputParser(BaseOutputParser[bool]):
-                true_val: str = "YES"
-                false_val: str = "NO"
-
-                def parse(self, text: str) -> bool:
-                    cleaned_text = text.strip().upper()
-                    if cleaned_text not in (
-                        self.true_val.upper(),
-                        self.false_val.upper(),
-                    ):
-                        raise OutputParserException(
-                            f"BooleanOutputParser expected output value to either be "
-                            f"{self.true_val} or {self.false_val} (case-insensitive). "
-                            f"Received {cleaned_text}."
-                        )
-                    return cleaned_text == self.true_val.upper()
-
-                @property
-                def _type(self) -> str:
-                    return "boolean_output_parser"
-
+        ```python
+        class BooleanOutputParser(BaseOutputParser[bool]):
+            true_val: str = "YES"
+            false_val: str = "NO"
+
+            def parse(self, text: str) -> bool:
+                cleaned_text = text.strip().upper()
+                if cleaned_text not in (
+                    self.true_val.upper(),
+                    self.false_val.upper(),
+                ):
+                    raise OutputParserException(
+                        f"BooleanOutputParser expected output value to either be "
+                        f"{self.true_val} or {self.false_val} (case-insensitive). "
+                        f"Received {cleaned_text}."
+                    )
+                return cleaned_text == self.true_val.upper()
+
+            @property
+            def _type(self) -> str:
+                return "boolean_output_parser"
+        ```
     """
 
     @property
     @override
     def InputType(self) -> Any:
         """Return the input type for the parser."""
-        return Union[str, AnyMessage]
+        return str | AnyMessage
 
     @property
     @override
@@ -175,7 +172,7 @@ class BaseOutputParser(
         This property is inferred from the first type argument of the class.
 
         Raises:
-            TypeError: If the class doesn't have an inferable OutputType.
+            TypeError: If the class doesn't have an inferable `OutputType`.
         """
         for base in self.__class__.mro():
             if hasattr(base, "__pydantic_generic_metadata__"):
@@ -192,8 +189,8 @@ class BaseOutputParser(
     @override
     def invoke(
         self,
-        input: Union[str, BaseMessage],
-        config: Optional[RunnableConfig] = None,
+        input: str | BaseMessage,
+        config: RunnableConfig | None = None,
         **kwargs: Any,
     ) -> T:
         if isinstance(input, BaseMessage):
@@ -215,9 +212,9 @@ class BaseOutputParser(
     @override
     async def ainvoke(
         self,
-        input: Union[str, BaseMessage],
-        config: Optional[RunnableConfig] = None,
-        **kwargs: Optional[Any],
+        input: str | BaseMessage,
+        config: RunnableConfig | None = None,
+        **kwargs: Any | None,
     ) -> T:
         if isinstance(input, BaseMessage):
             return await self._acall_with_config(
@@ -237,16 +234,16 @@ class BaseOutputParser(
 
     @override
     def parse_result(self, result: list[Generation], *, partial: bool = False) -> T:
-        """Parse a list of candidate model Generations into a specific format.
+        """Parse a list of candidate model `Generation` objects into a specific format.
 
-        The return value is parsed from only the first Generation in the result, which
-            is assumed to be the highest-likelihood Generation.
+        The return value is parsed from only the first `Generation` in the result, which
+            is assumed to be the highest-likelihood `Generation`.
 
         Args:
-            result: A list of Generations to be parsed. The Generations are assumed
-                to be different candidate outputs for a single model input.
+            result: A list of `Generation` to be parsed. The `Generation` objects are
+                assumed to be different candidate outputs for a single model input.
             partial: Whether to parse the output as a partial result. This is useful
-                for parsers that can parse partial results. Default is False.
+                for parsers that can parse partial results.
 
         Returns:
             Structured output.
@@ -267,20 +264,20 @@ class BaseOutputParser(
     async def aparse_result(
         self, result: list[Generation], *, partial: bool = False
     ) -> T:
-        """Async parse a list of candidate model Generations into a specific format.
+        """Async parse a list of candidate model `Generation` objects into a specific format.
 
-        The return value is parsed from only the first Generation in the result, which
-            is assumed to be the highest-likelihood Generation.
+        The return value is parsed from only the first `Generation` in the result, which
+            is assumed to be the highest-likelihood `Generation`.
 
         Args:
-            result: A list of Generations to be parsed. The Generations are assumed
-                to be different candidate outputs for a single model input.
+            result: A list of `Generation` to be parsed. The `Generation` objects are
+                assumed to be different candidate outputs for a single model input.
             partial: Whether to parse the output as a partial result. This is useful
-                for parsers that can parse partial results. Default is False.
+                for parsers that can parse partial results.
 
         Returns:
             Structured output.
-        """
+        """  # noqa: E501
         return await run_in_executor(None, self.parse_result, result, partial=partial)
 
     async def aparse(self, text: str) -> T:
@@ -302,13 +299,13 @@ class BaseOutputParser(
     ) -> Any:
         """Parse the output of an LLM call with the input prompt for context.
 
-        The prompt is largely provided in the event the OutputParser wants
+        The prompt is largely provided in the event the `OutputParser` wants
         to retry or fix the output in some way, and needs information from
         the prompt to do so.
 
         Args:
             completion: String output of a language model.
-            prompt: Input PromptValue.
+            prompt: Input `PromptValue`.
 
         Returns:
             Structured output.

langchain_core/output_parsers/json.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import json
 from json import JSONDecodeError
-from typing import Annotated, Any, Optional, TypeVar, Union
+from typing import Annotated, Any, TypeVar
 
 import jsonpatch  # type: ignore[import-untyped]
 import pydantic
@@ -23,7 +23,7 @@ from langchain_core.utils.json import (
 )
 
 # Union type needs to be last assignment to PydanticBaseModel to make mypy happy.
-PydanticBaseModel = Union[BaseModel, pydantic.BaseModel]
+PydanticBaseModel = BaseModel | pydantic.BaseModel
 
 TBaseModel = TypeVar("TBaseModel", bound=PydanticBaseModel)
 
@@ -38,12 +38,12 @@ class JsonOutputParser(BaseCumulativeTransformOutputParser[Any]):
     describing the difference between the previous and the current object.
     """
 
-    pydantic_object: Annotated[Optional[type[TBaseModel]], SkipValidation()] = None  # type: ignore[valid-type]
+    pydantic_object: Annotated[type[TBaseModel] | None, SkipValidation()] = None  # type: ignore[valid-type]
     """The Pydantic object to use for validation.
-    If None, no validation is performed."""
+    If `None`, no validation is performed."""
 
     @override
-    def _diff(self, prev: Optional[Any], next: Any) -> Any:
+    def _diff(self, prev: Any | None, next: Any) -> Any:
         return jsonpatch.make_patch(prev, next).patch
 
     @staticmethod
@@ -59,10 +59,9 @@ class JsonOutputParser(BaseCumulativeTransformOutputParser[Any]):
         Args:
             result: The result of the LLM call.
             partial: Whether to parse partial JSON objects.
-                If True, the output will be a JSON object containing
+                If `True`, the output will be a JSON object containing
                 all the keys that have been returned so far.
-                If False, the output will be the full JSON object.
-                Default is False.
+                If `False`, the output will be the full JSON object.
 
         Returns:
             The parsed JSON object.

langchain_core/output_parsers/list.py

@@ -7,7 +7,7 @@ import re
 from abc import abstractmethod
 from collections import deque
 from io import StringIO
-from typing import TYPE_CHECKING, TypeVar, Union
+from typing import TYPE_CHECKING, TypeVar
 
 from typing_extensions import override
 
@@ -70,9 +70,7 @@ class ListOutputParser(BaseTransformOutputParser[list[str]]):
         raise NotImplementedError
 
     @override
-    def _transform(
-        self, input: Iterator[Union[str, BaseMessage]]
-    ) -> Iterator[list[str]]:
+    def _transform(self, input: Iterator[str | BaseMessage]) -> Iterator[list[str]]:
         buffer = ""
         for chunk in input:
             if isinstance(chunk, BaseMessage):
@@ -105,7 +103,7 @@ class ListOutputParser(BaseTransformOutputParser[list[str]]):
 
     @override
     async def _atransform(
-        self, input: AsyncIterator[Union[str, BaseMessage]]
+        self, input: AsyncIterator[str | BaseMessage]
     ) -> AsyncIterator[list[str]]:
         buffer = ""
         async for chunk in input:
@@ -148,10 +146,10 @@ class CommaSeparatedListOutputParser(ListOutputParser):
 
     @classmethod
     def get_lc_namespace(cls) -> list[str]:
-        """Get the namespace of the langchain object.
+        """Get the namespace of the LangChain object.
 
         Returns:
-            ``["langchain", "output_parsers", "list"]``
+            `["langchain", "output_parsers", "list"]`
         """
         return ["langchain", "output_parsers", "list"]
 

langchain_core/output_parsers/openai_functions.py

@@ -3,7 +3,7 @@
 import copy
 import json
 from types import GenericAlias
-from typing import Any, Optional, Union
+from typing import Any
 
 import jsonpatch  # type: ignore[import-untyped]
 from pydantic import BaseModel, model_validator
@@ -31,13 +31,13 @@ class OutputFunctionsParser(BaseGenerationOutputParser[Any]):
 
         Args:
             result: The result of the LLM call.
-            partial: Whether to parse partial JSON objects. Default is False.
+            partial: Whether to parse partial JSON objects.
 
         Returns:
             The parsed JSON object.
 
         Raises:
-            OutputParserException: If the output is not valid JSON.
+            `OutputParserException`: If the output is not valid JSON.
         """
         generation = result[0]
         if not isinstance(generation, ChatGeneration):
@@ -56,7 +56,7 @@ class OutputFunctionsParser(BaseGenerationOutputParser[Any]):
 
 
 class JsonOutputFunctionsParser(BaseCumulativeTransformOutputParser[Any]):
-    """Parse an output as the Json object."""
+    """Parse an output as the JSON object."""
 
     strict: bool = False
     """Whether to allow non-JSON-compliant strings.
@@ -74,7 +74,7 @@ class JsonOutputFunctionsParser(BaseCumulativeTransformOutputParser[Any]):
         return "json_functions"
 
     @override
-    def _diff(self, prev: Optional[Any], next: Any) -> Any:
+    def _diff(self, prev: Any | None, next: Any) -> Any:
         return jsonpatch.make_patch(prev, next).patch
 
     def parse_result(self, result: list[Generation], *, partial: bool = False) -> Any:
@@ -82,13 +82,13 @@ class JsonOutputFunctionsParser(BaseCumulativeTransformOutputParser[Any]):
 
         Args:
             result: The result of the LLM call.
-            partial: Whether to parse partial JSON objects. Default is False.
+            partial: Whether to parse partial JSON objects.
 
         Returns:
             The parsed JSON object.
 
         Raises:
-            OutputParserException: If the output is not valid JSON.
+            OutputParserExcept`ion: If the output is not valid JSON.
         """
         if len(result) != 1:
             msg = f"Expected exactly one result, but got {len(result)}"
@@ -155,7 +155,7 @@ class JsonOutputFunctionsParser(BaseCumulativeTransformOutputParser[Any]):
 
 
 class JsonKeyOutputFunctionsParser(JsonOutputFunctionsParser):
-    """Parse an output as the element of the Json object."""
+    """Parse an output as the element of the JSON object."""
 
     key_name: str
     """The name of the key to return."""
@@ -165,7 +165,7 @@ class JsonKeyOutputFunctionsParser(JsonOutputFunctionsParser):
 
         Args:
             result: The result of the LLM call.
-            partial: Whether to parse partial JSON objects. Default is False.
+            partial: Whether to parse partial JSON objects.
 
         Returns:
             The parsed JSON object.
@@ -177,48 +177,50 @@ class JsonKeyOutputFunctionsParser(JsonOutputFunctionsParser):
 
 
 class PydanticOutputFunctionsParser(OutputFunctionsParser):
-    """Parse an output as a pydantic object.
+    """Parse an output as a Pydantic object.
 
-    This parser is used to parse the output of a ChatModel that uses
-    OpenAI function format to invoke functions.
+    This parser is used to parse the output of a chat model that uses OpenAI function
+    format to invoke functions.
 
-    The parser extracts the function call invocation and matches
-    them to the pydantic schema provided.
+    The parser extracts the function call invocation and matches them to the Pydantic
+    schema provided.
 
-    An exception will be raised if the function call does not match
-    the provided schema.
+    An exception will be raised if the function call does not match the provided schema.
 
     Example:
-        ... code-block:: python
-
-            message = AIMessage(
-                content="This is a test message",
-                additional_kwargs={
-                    "function_call": {
-                        "name": "cookie",
-                        "arguments": json.dumps({"name": "value", "age": 10}),
-                    }
-                },
-            )
-            chat_generation = ChatGeneration(message=message)
+        ```python
+        message = AIMessage(
+            content="This is a test message",
+            additional_kwargs={
+                "function_call": {
+                    "name": "cookie",
+                    "arguments": json.dumps({"name": "value", "age": 10}),
+                }
+            },
+        )
+        chat_generation = ChatGeneration(message=message)
 
-            class Cookie(BaseModel):
-                name: str
-                age: int
 
-            class Dog(BaseModel):
-                species: str
+        class Cookie(BaseModel):
+            name: str
+            age: int
 
-            # Full output
-            parser = PydanticOutputFunctionsParser(
-                pydantic_schema={"cookie": Cookie, "dog": Dog}
-            )
-            result = parser.parse_result([chat_generation])
+
+        class Dog(BaseModel):
+            species: str
+
+
+        # Full output
+        parser = PydanticOutputFunctionsParser(
+            pydantic_schema={"cookie": Cookie, "dog": Dog}
+        )
+        result = parser.parse_result([chat_generation])
+        ```
 
     """
 
-    pydantic_schema: Union[type[BaseModel], dict[str, type[BaseModel]]]
-    """The pydantic schema to parse the output with.
+    pydantic_schema: type[BaseModel] | dict[str, type[BaseModel]]
+    """The Pydantic schema to parse the output with.
 
     If multiple schemas are provided, then the function name will be used to
     determine which schema to use.
@@ -227,7 +229,7 @@ class PydanticOutputFunctionsParser(OutputFunctionsParser):
     @model_validator(mode="before")
     @classmethod
     def validate_schema(cls, values: dict) -> Any:
-        """Validate the pydantic schema.
+        """Validate the Pydantic schema.
 
         Args:
             values: The values to validate.
@@ -236,7 +238,7 @@ class PydanticOutputFunctionsParser(OutputFunctionsParser):
             The validated values.
 
         Raises:
-            ValueError: If the schema is not a pydantic schema.
+            ValueError: If the schema is not a Pydantic schema.
         """
         schema = values["pydantic_schema"]
         if "args_only" not in values:
@@ -259,10 +261,10 @@ class PydanticOutputFunctionsParser(OutputFunctionsParser):
 
         Args:
             result: The result of the LLM call.
-            partial: Whether to parse partial JSON objects. Default is False.
+            partial: Whether to parse partial JSON objects.
 
         Raises:
-            ValueError: If the pydantic schema is not valid.
+            ValueError: If the Pydantic schema is not valid.
 
         Returns:
             The parsed JSON object.
@@ -285,13 +287,13 @@ class PydanticOutputFunctionsParser(OutputFunctionsParser):
             elif issubclass(pydantic_schema, BaseModelV1):
                 pydantic_args = pydantic_schema.parse_raw(args)
             else:
-                msg = f"Unsupported pydantic schema: {pydantic_schema}"
+                msg = f"Unsupported Pydantic schema: {pydantic_schema}"
                 raise ValueError(msg)
         return pydantic_args
 
 
 class PydanticAttrOutputFunctionsParser(PydanticOutputFunctionsParser):
-    """Parse an output as an attribute of a pydantic object."""
+    """Parse an output as an attribute of a Pydantic object."""
 
     attr_name: str
     """The name of the attribute to return."""
@@ -302,7 +304,7 @@ class PydanticAttrOutputFunctionsParser(PydanticOutputFunctionsParser):
 
         Args:
             result: The result of the LLM call.
-            partial: Whether to parse partial JSON objects. Default is False.
+            partial: Whether to parse partial JSON objects.
 
         Returns:
             The parsed JSON object.

langchain_core/output_parsers/openai_tools.py

@@ -4,7 +4,7 @@ import copy
 import json
 import logging
 from json import JSONDecodeError
-from typing import Annotated, Any, Optional
+from typing import Annotated, Any
 
 from pydantic import SkipValidation, ValidationError
 
@@ -26,15 +26,14 @@ def parse_tool_call(
     partial: bool = False,
     strict: bool = False,
     return_id: bool = True,
-) -> Optional[dict[str, Any]]:
+) -> dict[str, Any] | None:
     """Parse a single tool call.
 
     Args:
         raw_tool_call: The raw tool call to parse.
-        partial: Whether to parse partial JSON. Default is False.
+        partial: Whether to parse partial JSON.
         strict: Whether to allow non-JSON-compliant strings.
-            Default is False.
-        return_id: Whether to return the tool call id. Default is True.
+        return_id: Whether to return the tool call id.
 
     Returns:
         The parsed tool call.
@@ -75,7 +74,7 @@ def parse_tool_call(
 
 def make_invalid_tool_call(
     raw_tool_call: dict[str, Any],
-    error_msg: Optional[str],
+    error_msg: str | None,
 ) -> InvalidToolCall:
     """Create an InvalidToolCall from a raw tool call.
 
@@ -105,10 +104,9 @@ def parse_tool_calls(
 
     Args:
         raw_tool_calls: The raw tool calls to parse.
-        partial: Whether to parse partial JSON. Default is False.
+        partial: Whether to parse partial JSON.
         strict: Whether to allow non-JSON-compliant strings.
-            Default is False.
-        return_id: Whether to return the tool call id. Default is True.
+        return_id: Whether to return the tool call id.
 
     Returns:
         The parsed tool calls.
@@ -148,7 +146,7 @@ class JsonOutputToolsParser(BaseCumulativeTransformOutputParser[Any]):
     first_tool_only: bool = False
     """Whether to return only the first tool call.
 
-    If False, the result will be a list of tool calls, or an empty list
+    If `False`, the result will be a list of tool calls, or an empty list
     if no tool calls are found.
 
     If true, and multiple tool calls are found, only the first one will be returned,
@@ -162,10 +160,9 @@ class JsonOutputToolsParser(BaseCumulativeTransformOutputParser[Any]):
         Args:
             result: The result of the LLM call.
             partial: Whether to parse partial JSON.
-                If True, the output will be a JSON object containing
+                If `True`, the output will be a JSON object containing
                 all the keys that have been returned so far.
-                If False, the output will be the full JSON object.
-                Default is False.
+                If `False`, the output will be the full JSON object.
 
         Returns:
             The parsed tool calls.
@@ -226,10 +223,9 @@ class JsonOutputKeyToolsParser(JsonOutputToolsParser):
         Args:
             result: The result of the LLM call.
             partial: Whether to parse partial JSON.
-                If True, the output will be a JSON object containing
+                If `True`, the output will be a JSON object containing
                 all the keys that have been returned so far.
-                If False, the output will be the full JSON object.
-                Default is False.
+                If `False`, the output will be the full JSON object.
 
         Raises:
             OutputParserException: If the generation is not a chat generation.
@@ -310,10 +306,9 @@ class PydanticToolsParser(JsonOutputToolsParser):
         Args:
             result: The result of the LLM call.
             partial: Whether to parse partial JSON.
-                If True, the output will be a JSON object containing
+                If `True`, the output will be a JSON object containing
                 all the keys that have been returned so far.
-                If False, the output will be the full JSON object.
-                Default is False.
+                If `False`, the output will be the full JSON object.
 
         Returns:
             The parsed Pydantic objects.