coco-framework 0.1.0__py3-none-any.whl

coco_core/output_parsers/__init__.py

@@ -0,0 +1,101 @@
+"""`OutputParser` classes parse the output of an LLM call into structured data.
+
+!!! tip "Structured output"
+
+    Output parsers emerged as an early solution to the challenge of obtaining structured
+    output from LLMs.
+
+    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.
+
+    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
+
+from coco_core._import_utils import import_attr
+
+if TYPE_CHECKING:
+    from coco_core.output_parsers.base import (
+        BaseGenerationOutputParser,
+        BaseLLMOutputParser,
+        BaseOutputParser,
+    )
+    from coco_core.output_parsers.json import (
+        JsonOutputParser,
+        SimpleJsonOutputParser,
+    )
+    from coco_core.output_parsers.list import (
+        CommaSeparatedListOutputParser,
+        ListOutputParser,
+        MarkdownListOutputParser,
+        NumberedListOutputParser,
+    )
+    from coco_core.output_parsers.openai_tools import (
+        JsonOutputKeyToolsParser,
+        JsonOutputToolsParser,
+        PydanticToolsParser,
+    )
+    from coco_core.output_parsers.pydantic import PydanticOutputParser
+    from coco_core.output_parsers.string import StrOutputParser
+    from coco_core.output_parsers.transform import (
+        BaseCumulativeTransformOutputParser,
+        BaseTransformOutputParser,
+    )
+    from coco_core.output_parsers.xml import XMLOutputParser
+
+__all__ = [
+    "BaseCumulativeTransformOutputParser",
+    "BaseGenerationOutputParser",
+    "BaseLLMOutputParser",
+    "BaseOutputParser",
+    "BaseTransformOutputParser",
+    "CommaSeparatedListOutputParser",
+    "JsonOutputKeyToolsParser",
+    "JsonOutputParser",
+    "JsonOutputToolsParser",
+    "ListOutputParser",
+    "MarkdownListOutputParser",
+    "NumberedListOutputParser",
+    "PydanticOutputParser",
+    "PydanticToolsParser",
+    "SimpleJsonOutputParser",
+    "StrOutputParser",
+    "XMLOutputParser",
+]
+
+_dynamic_imports = {
+    "BaseLLMOutputParser": "base",
+    "BaseGenerationOutputParser": "base",
+    "BaseOutputParser": "base",
+    "JsonOutputParser": "json",
+    "SimpleJsonOutputParser": "json",
+    "ListOutputParser": "list",
+    "CommaSeparatedListOutputParser": "list",
+    "MarkdownListOutputParser": "list",
+    "NumberedListOutputParser": "list",
+    "JsonOutputKeyToolsParser": "openai_tools",
+    "JsonOutputToolsParser": "openai_tools",
+    "PydanticToolsParser": "openai_tools",
+    "PydanticOutputParser": "pydantic",
+    "StrOutputParser": "string",
+    "BaseTransformOutputParser": "transform",
+    "BaseCumulativeTransformOutputParser": "transform",
+    "XMLOutputParser": "xml",
+}
+
+
+def __getattr__(attr_name: str) -> object:
+    module_name = _dynamic_imports.get(attr_name)
+    result = import_attr(attr_name, module_name, __spec__.parent)
+    globals()[attr_name] = result
+    return result
+
+
+def __dir__() -> list[str]:
+    return __all__

coco_core/output_parsers/base.py

@@ -0,0 +1,361 @@
+"""Base parser for language model outputs."""
+
+from __future__ import annotations
+
+import builtins
+import contextlib
+from abc import ABC, abstractmethod
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    TypeVar,
+    cast,
+)
+
+from typing_extensions import override
+
+from coco_core._api import deprecated
+from coco_core.language_models import LanguageModelOutput
+from coco_core.messages import AnyMessage, BaseMessage
+from coco_core.outputs import ChatGeneration, Generation
+from coco_core.runnables import Runnable, RunnableConfig, RunnableSerializable
+from coco_core.runnables.config import run_in_executor
+
+if TYPE_CHECKING:
+    import builtins
+
+    from coco_core.prompt_values import PromptValue
+
+T = TypeVar("T")
+OutputParserLike = Runnable[LanguageModelOutput, T]
+
+
+class BaseLLMOutputParser(ABC, Generic[T]):
+    """Abstract base class for parsing the outputs of a model."""
+
+    @abstractmethod
+    def parse_result(self, result: list[Generation], *, partial: bool = False) -> T:
+        """Parse a list of candidate model `Generation` objects into a specific format.
+
+        Args:
+            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.
+
+        Returns:
+            Structured output.
+        """
+
+    async def aparse_result(
+        self, result: list[Generation], *, partial: bool = False
+    ) -> T:
+        """Parse a list of candidate model `Generation` objects into a specific format.
+
+        Args:
+            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.
+
+        Returns:
+            Structured output.
+        """
+        return await run_in_executor(None, self.parse_result, result, partial=partial)
+
+
+class BaseGenerationOutputParser(
+    BaseLLMOutputParser[T], RunnableSerializable[LanguageModelOutput, T]
+):
+    """Base class to parse the output of an LLM call."""
+
+    @property
+    @override
+    def InputType(self) -> Any:
+        """Return the input type for the parser."""
+        return str | AnyMessage
+
+    @property
+    @override
+    def OutputType(self) -> type[T]:
+        """Return the output type for the parser."""
+        # even though mypy complains this isn't valid,
+        # it is good enough for pydantic to build the schema from
+        return cast("type[T]", T)  # type: ignore[misc]
+
+    @override
+    def invoke(
+        self,
+        input: str | BaseMessage,
+        config: RunnableConfig | None = None,
+        **kwargs: Any,
+    ) -> T:
+        if isinstance(input, BaseMessage):
+            return self._call_with_config(
+                lambda inner_input: self.parse_result(
+                    [ChatGeneration(message=inner_input)]
+                ),
+                input,
+                config,
+                run_type="parser",
+            )
+        return self._call_with_config(
+            lambda inner_input: self.parse_result([Generation(text=inner_input)]),
+            input,
+            config,
+            run_type="parser",
+        )
+
+    @override
+    async def ainvoke(
+        self,
+        input: str | BaseMessage,
+        config: RunnableConfig | None = None,
+        **kwargs: Any | None,
+    ) -> T:
+        if isinstance(input, BaseMessage):
+            return await self._acall_with_config(
+                lambda inner_input: self.aparse_result(
+                    [ChatGeneration(message=inner_input)]
+                ),
+                input,
+                config,
+                run_type="parser",
+            )
+        return await self._acall_with_config(
+            lambda inner_input: self.aparse_result([Generation(text=inner_input)]),
+            input,
+            config,
+            run_type="parser",
+        )
+
+
+class BaseOutputParser(
+    BaseLLMOutputParser[T], RunnableSerializable[LanguageModelOutput, T]
+):
+    """Base class to parse the output of an LLM call.
+
+    Output parsers help structure language model responses.
+
+    Example:
+        ```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 str | AnyMessage
+
+    @property
+    @override
+    def OutputType(self) -> type[T]:
+        """Return the output type for the parser.
+
+        This property is inferred from the first type argument of the class.
+
+        Raises:
+            TypeError: If the class doesn't have an inferable `OutputType`.
+        """
+        for base in self.__class__.mro():
+            if hasattr(base, "__pydantic_generic_metadata__"):
+                metadata = base.__pydantic_generic_metadata__
+                if "args" in metadata and len(metadata["args"]) > 0:
+                    return cast("type[T]", metadata["args"][0])
+
+        msg = (
+            f"Runnable {self.__class__.__name__} doesn't have an inferable OutputType. "
+            "Override the OutputType property to specify the output type."
+        )
+        raise TypeError(msg)
+
+    @override
+    def invoke(
+        self,
+        input: str | BaseMessage,
+        config: RunnableConfig | None = None,
+        **kwargs: Any,
+    ) -> T:
+        if isinstance(input, BaseMessage):
+            return self._call_with_config(
+                lambda inner_input: self.parse_result(
+                    [ChatGeneration(message=inner_input)]
+                ),
+                input,
+                config,
+                run_type="parser",
+            )
+        return self._call_with_config(
+            lambda inner_input: self.parse_result([Generation(text=inner_input)]),
+            input,
+            config,
+            run_type="parser",
+        )
+
+    @override
+    async def ainvoke(
+        self,
+        input: str | BaseMessage,
+        config: RunnableConfig | None = None,
+        **kwargs: Any | None,
+    ) -> T:
+        if isinstance(input, BaseMessage):
+            return await self._acall_with_config(
+                lambda inner_input: self.aparse_result(
+                    [ChatGeneration(message=inner_input)]
+                ),
+                input,
+                config,
+                run_type="parser",
+            )
+        return await self._acall_with_config(
+            lambda inner_input: self.aparse_result([Generation(text=inner_input)]),
+            input,
+            config,
+            run_type="parser",
+        )
+
+    @override
+    def parse_result(self, result: list[Generation], *, partial: bool = False) -> T:
+        """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`.
+
+        Args:
+            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.
+
+        Returns:
+            Structured output.
+        """
+        return self.parse(result[0].text)
+
+    @abstractmethod
+    def parse(self, text: str) -> T:
+        """Parse a single string model output into some structure.
+
+        Args:
+            text: String output of a language model.
+
+        Returns:
+            Structured output.
+        """
+
+    async def aparse_result(
+        self, result: list[Generation], *, partial: bool = False
+    ) -> T:
+        """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`.
+
+        Args:
+            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.
+
+        Returns:
+            Structured output.
+        """
+        return await run_in_executor(None, self.parse_result, result, partial=partial)
+
+    async def aparse(self, text: str) -> T:
+        """Async parse a single string model output into some structure.
+
+        Args:
+            text: String output of a language model.
+
+        Returns:
+            Structured output.
+        """
+        return await run_in_executor(None, self.parse, text)
+
+    # TODO: rename 'completion' -> 'text'.
+    def parse_with_prompt(
+        self,
+        completion: str,
+        prompt: PromptValue,  # noqa: ARG002
+    ) -> 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 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`.
+
+        Returns:
+            Structured output.
+        """
+        return self.parse(completion)
+
+    def get_format_instructions(self) -> str:
+        """Instructions on how the LLM output should be formatted."""
+        raise NotImplementedError
+
+    @property
+    def _type(self) -> str:
+        """Return the output parser type for serialization."""
+        msg = (
+            f"_type property is not implemented in class {self.__class__.__name__}."
+            " This is required for serialization."
+        )
+        raise NotImplementedError(msg)
+
+    @deprecated("1.4.2", alternative="asdict", removal="2.0.0")
+    @override
+    def dict(self, **kwargs: Any) -> builtins.dict[str, Any]:
+        """DEPRECATED - use `asdict()` instead.
+
+        Return a dictionary representation of the output parser.
+        """
+        return self.asdict(**kwargs)
+
+    def asdict(self, **kwargs: Any) -> builtins.dict[str, Any]:
+        """Return a dictionary representation of the output parser."""
+        output_parser_dict = super().model_dump(**kwargs)
+        with contextlib.suppress(NotImplementedError):
+            output_parser_dict["_type"] = self._type
+        return output_parser_dict

coco_core/output_parsers/format_instructions.py

@@ -0,0 +1,16 @@
+"""Format instructions."""
+
+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.
+
+The output should be formatted as a JSON instance that conforms to the JSON schema below.
+
+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

coco_core/output_parsers/json.py

@@ -0,0 +1,139 @@
+"""Parser for JSON output."""
+
+from __future__ import annotations
+
+import json
+from json import JSONDecodeError
+from typing import Annotated, Any, TypeVar
+
+import jsonpatch  # type: ignore[import-untyped]
+import pydantic
+from pydantic import SkipValidation
+from pydantic.v1 import BaseModel
+from typing_extensions import override
+
+from coco_core.exceptions import OutputParserException
+from coco_core.output_parsers.format_instructions import JSON_FORMAT_INSTRUCTIONS
+from coco_core.output_parsers.transform import BaseCumulativeTransformOutputParser
+from coco_core.outputs import Generation
+from coco_core.utils.json import (
+    parse_and_check_json_markdown,
+    parse_json_markdown,
+    parse_partial_json,
+)
+
+# Union type needs to be last assignment to PydanticBaseModel to make mypy happy.
+PydanticBaseModel = BaseModel | pydantic.BaseModel
+
+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.
+    """
+
+    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.
+    """
+
+    @override
+    def _diff(self, prev: Any | None, next: Any) -> Any:
+        return jsonpatch.make_patch(prev, next).patch
+
+    @staticmethod
+    def _get_schema(pydantic_object: type[TBaseModel]) -> dict[str, Any]:
+        if issubclass(pydantic_object, pydantic.BaseModel):
+            return pydantic_object.model_json_schema()
+        return pydantic_object.schema()
+
+    @override
+    def parse_result(self, result: list[Generation], *, partial: bool = False) -> Any:
+        """Parse the result of an LLM call to a JSON object.
+
+        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 all the keys that
+                have been returned so far.
+
+                If `False`, the output will be the full JSON object.
+
+        Returns:
+            The parsed JSON object.
+
+        Raises:
+            OutputParserException: If the output is not valid JSON.
+        """
+        text = result[0].text
+        text = text.strip()
+        if partial:
+            try:
+                return parse_json_markdown(text)
+            except JSONDecodeError:
+                return None
+        else:
+            try:
+                return parse_json_markdown(text)
+            except JSONDecodeError as e:
+                msg = f"Invalid json output: {text}"
+                raise OutputParserException(msg, llm_output=text) from e
+
+    def parse(self, text: str) -> Any:
+        """Parse the output of an LLM call to a JSON object.
+
+        Args:
+            text: The output of the LLM call.
+
+        Returns:
+            The parsed JSON object.
+        """
+        return self.parse_result([Generation(text=text)])
+
+    def get_format_instructions(self) -> str:
+        """Return the format instructions for the JSON output.
+
+        Returns:
+            The format instructions for the JSON output.
+        """
+        if self.pydantic_object is None:
+            return "Return a JSON object."
+        # Copy schema to avoid altering original Pydantic schema.
+        schema = dict(self._get_schema(self.pydantic_object).items())
+
+        # Remove extraneous fields.
+        reduced_schema = schema
+        if "title" in reduced_schema:
+            del reduced_schema["title"]
+        if "type" in reduced_schema:
+            del reduced_schema["type"]
+        # Ensure json in context is well-formed with double quotes.
+        schema_str = json.dumps(reduced_schema, ensure_ascii=False)
+        return JSON_FORMAT_INSTRUCTIONS.format(schema=schema_str)
+
+    @property
+    def _type(self) -> str:
+        return "simple_json_output_parser"
+
+
+# For backwards compatibility
+SimpleJsonOutputParser = JsonOutputParser
+
+
+__all__ = [
+    "JsonOutputParser",
+    "SimpleJsonOutputParser",  # For backwards compatibility
+    "parse_and_check_json_markdown",  # For backwards compatibility
+    "parse_partial_json",  # For backwards compatibility
+]