langchain-core 1.0.0a6__py3-none-any.whl → 1.0.4__py3-none-any.whl

langchain_core/output_parsers/__init__.py

@@ -1,17 +1,20 @@
-"""**OutputParser** classes parse the output of an LLM call.
+"""`OutputParser` classes parse the output of an LLM call into structured data.
 
-**Class hierarchy:**
+!!! tip "Structured output"
 
-.. code-block::
+    Output parsers emerged as an early solution to the challenge of obtaining structured
+    output from LLMs.
 
-    BaseLLMOutputParser --> BaseOutputParser --> <name>OutputParser  # ListOutputParser, PydanticOutputParser
+    Today, most LLMs support [structured output](https://docs.langchain.com/oss/python/langchain/models#structured-outputs)
+    natively. In such cases, using output parsers may be unnecessary, and you should
+    leverage the model's built-in capabilities for structured output. Refer to the
+    [documentation of your chosen model](https://docs.langchain.com/oss/python/integrations/providers/overview)
+    for guidance on how to achieve structured output directly.
 
-**Main helpers:**
-
-.. code-block::
-
-    Serializable, Generation, PromptValue
-"""  # noqa: E501
+    Output parsers remain valuable when working with models that do not support
+    structured output natively, or when you require additional processing or validation
+    of the model's output beyond its inherent capabilities.
+"""
 
 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,38 @@ 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
+        # Implement a simple boolean output parser
+
+
+        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 +175,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 +192,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 +215,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 +237,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 +267,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 +302,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/format_instructions.py

@@ -1,11 +1,16 @@
 """Format instructions."""
 
-JSON_FORMAT_INSTRUCTIONS = """The output should be formatted as a JSON instance that conforms to the JSON schema below.
+JSON_FORMAT_INSTRUCTIONS = """STRICT OUTPUT FORMAT:
+- Return only the JSON value that conforms to the schema. Do not include any additional text, explanations, headings, or separators.
+- Do not wrap the JSON in Markdown or code fences (no ``` or ```json).
+- Do not prepend or append any text (e.g., do not write "Here is the JSON:").
+- The response must be a single top-level JSON value exactly as required by the schema (object/array/etc.), with no trailing commas or comments.
 
-As an example, for the schema {{"properties": {{"foo": {{"title": "Foo", "description": "a list of strings", "type": "array", "items": {{"type": "string"}}}}}}, "required": ["foo"]}}
-the object {{"foo": ["bar", "baz"]}} is a well-formatted instance of the schema. The object {{"properties": {{"foo": ["bar", "baz"]}}}} is not well-formatted.
+The output should be formatted as a JSON instance that conforms to the JSON schema below.
 
-Here is the output schema:
+As an example, for the schema {{"properties": {{"foo": {{"title": "Foo", "description": "a list of strings", "type": "array", "items": {{"type": "string"}}}}}}, "required": ["foo"]}} the object {{"foo": ["bar", "baz"]}} is a well-formatted instance of the schema. The object {{"properties": {{"foo": ["bar", "baz"]}}}} is not well-formatted.
+
+Here is the output schema (shown in a code block for readability only — do not include any backticks or Markdown in your output):
 ```
 {schema}
 ```"""  # noqa: E501

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)
 
@@ -31,19 +31,22 @@ TBaseModel = TypeVar("TBaseModel", bound=PydanticBaseModel)
 class JsonOutputParser(BaseCumulativeTransformOutputParser[Any]):
     """Parse the output of an LLM call to a JSON object.
 
+    Probably the most reliable output parser for getting structured data that does *not*
+    use function calling.
+
     When used in streaming mode, it will yield partial JSON objects containing
     all the keys that have been returned so far.
 
-    In streaming, if `diff` is set to `True`, yields JSONPatch operations
-    describing the difference between the previous and the current object.
+    In streaming, if `diff` is set to `True`, yields JSONPatch operations 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 +62,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
 
@@ -41,7 +41,7 @@ def droplastn(
 
 
 class ListOutputParser(BaseTransformOutputParser[list[str]]):
-    """Parse the output of an LLM call to a list."""
+    """Parse the output of a model to a list."""
 
     @property
     def _type(self) -> str:
@@ -70,88 +70,86 @@ 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):
-                # extract text
+                # Extract text
                 chunk_content = chunk.content
                 if not isinstance(chunk_content, str):
                     continue
                 buffer += chunk_content
             else:
-                # add current chunk to buffer
+                # Add current chunk to buffer
                 buffer += chunk
-            # parse buffer into a list of parts
+            # Parse buffer into a list of parts
             try:
                 done_idx = 0
-                # yield only complete parts
+                # Yield only complete parts
                 for m in droplastn(self.parse_iter(buffer), 1):
                     done_idx = m.end()
                     yield [m.group(1)]
                 buffer = buffer[done_idx:]
             except NotImplementedError:
                 parts = self.parse(buffer)
-                # yield only complete parts
+                # Yield only complete parts
                 if len(parts) > 1:
                     for part in parts[:-1]:
                         yield [part]
                     buffer = parts[-1]
-        # yield the last part
+        # Yield the last part
         for part in self.parse(buffer):
             yield [part]
 
     @override
     async def _atransform(
-        self, input: AsyncIterator[Union[str, BaseMessage]]
+        self, input: AsyncIterator[str | BaseMessage]
     ) -> AsyncIterator[list[str]]:
         buffer = ""
         async for chunk in input:
             if isinstance(chunk, BaseMessage):
-                # extract text
+                # Extract text
                 chunk_content = chunk.content
                 if not isinstance(chunk_content, str):
                     continue
                 buffer += chunk_content
             else:
-                # add current chunk to buffer
+                # Add current chunk to buffer
                 buffer += chunk
-            # parse buffer into a list of parts
+            # Parse buffer into a list of parts
             try:
                 done_idx = 0
-                # yield only complete parts
+                # Yield only complete parts
                 for m in droplastn(self.parse_iter(buffer), 1):
                     done_idx = m.end()
                     yield [m.group(1)]
                 buffer = buffer[done_idx:]
             except NotImplementedError:
                 parts = self.parse(buffer)
-                # yield only complete parts
+                # Yield only complete parts
                 if len(parts) > 1:
                     for part in parts[:-1]:
                         yield [part]
                     buffer = parts[-1]
-        # yield the last part
+        # Yield the last part
         for part in self.parse(buffer):
             yield [part]
 
 
 class CommaSeparatedListOutputParser(ListOutputParser):
-    """Parse the output of an LLM call to a comma-separated list."""
+    """Parse the output of a model to a comma-separated list."""
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """Return True as 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.
+        """Get the namespace of the LangChain object.
 
         Returns:
-            ``["langchain", "output_parsers", "list"]``
+            `["langchain", "output_parsers", "list"]`
         """
         return ["langchain", "output_parsers", "list"]
 
@@ -179,7 +177,7 @@ class CommaSeparatedListOutputParser(ListOutputParser):
             )
             return [item for sublist in reader for item in sublist]
         except csv.Error:
-            # keep old logic for backup
+            # Keep old logic for backup
             return [part.strip() for part in text.split(",")]
 
     @property