fabricatio 0.2.1.dev0__cp313-cp313-win_amd64.whl → 0.3.14.dev5__cp313-cp313-win_amd64.whl

fabricatio/capabilities/correct.py

@@ -0,0 +1,228 @@
+"""A module containing the Correct capability for reviewing, validating, and improving objects."""
+
+from abc import ABC
+from asyncio import gather
+from typing import Optional, Type, Unpack, cast
+
+from fabricatio.capabilities.propose import Propose
+from fabricatio.capabilities.rating import Rating
+from fabricatio.journal import logger
+from fabricatio.models.adv_kwargs_types import CorrectKwargs
+from fabricatio.models.extra.problem import Improvement, ProblemSolutions
+from fabricatio.models.generic import ProposedUpdateAble, SketchedAble
+from fabricatio.models.kwargs_types import (
+    BestKwargs,
+    ValidateKwargs,
+)
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER
+from fabricatio.utils import fallback_kwargs, ok, override_kwargs
+
+
+class Correct(Rating, Propose, ABC):
+    """A class that provides the capability to correct objects."""
+
+    async def decide_solution(
+        self, problem_solutions: ProblemSolutions, **kwargs: Unpack[BestKwargs]
+    ) -> ProblemSolutions:
+        """Decide the best solution from a list of problem solutions.
+
+        Args:
+            problem_solutions (ProblemSolutions): The problem solutions to evaluate.
+            **kwargs (Unpack[BestKwargs]): Additional keyword arguments for the decision process.
+
+        Returns:
+            ProblemSolutions: The problem solutions with the best solution selected.
+        """
+        if (leng := len(problem_solutions.solutions)) == 0:
+            logger.error(f"No solutions found in ProblemSolutions, Skip: `{problem_solutions.problem.name}`")
+        if leng > 1:
+            logger.info(f"{leng} solutions found in Problem `{problem_solutions.problem.name}`, select the best.")
+            problem_solutions.solutions = await self.best(problem_solutions.solutions, **kwargs)
+        return problem_solutions
+
+    async def decide_improvement(self, improvement: Improvement, **kwargs: Unpack[BestKwargs]) -> Improvement:
+        """Decide the best solution for each problem solution in an improvement.
+
+        Args:
+            improvement (Improvement): The improvement containing problem solutions to evaluate.
+            **kwargs (Unpack[BestKwargs]): Additional keyword arguments for the decision process.
+
+        Returns:
+            Improvement: The improvement with the best solutions selected for each problem solution.
+        """
+        if leng := len(improvement.problem_solutions):
+            logger.debug(f"{leng} problem_solutions found in Improvement, decide solution for each of them.")
+            await gather(
+                *[
+                    self.decide_solution(
+                        ps,
+                        **fallback_kwargs(
+                            kwargs, topic=f"which solution is better to deal this problem {ps.problem.description}\n\n"
+                        ),
+                    )
+                    for ps in improvement.problem_solutions
+                ],
+            )
+            if any(not (violated := ps).decided() for ps in improvement.problem_solutions):
+                logger.error(f"Some problem_solutions are not decided: {violated}")
+            else:
+                logger.success(f"All problem_solutions are decided '{improvement.focused_on}'")
+        else:
+            logger.error(f"No problem_solutions found in Improvement, Skip: {improvement}")
+        return improvement
+
+    async def fix_troubled_obj[M: SketchedAble](
+        self,
+        obj: M,
+        problem_solutions: ProblemSolutions,
+        reference: str = "",
+        **kwargs: Unpack[ValidateKwargs[M]],
+    ) -> Optional[M]:
+        """Fix a troubled object based on problem solutions.
+
+        Args:
+            obj (M): The object to be fixed.
+            problem_solutions (ProblemSolutions): The problem solutions to apply.
+            reference (str): A reference or contextual information for the object.
+            **kwargs (Unpack[ValidateKwargs[M]]): Additional keyword arguments for the validation process.
+
+        Returns:
+            Optional[M]: The fixed object, or None if fixing fails.
+        """
+        return await self.propose(
+            cast("Type[M]", obj.__class__),
+            TEMPLATE_MANAGER.render_template(
+                CONFIG.templates.fix_troubled_obj_template,
+                {
+                    "problem": problem_solutions.problem.display(),
+                    "solution": ok(
+                        problem_solutions.final_solution(),
+                        f"{len(problem_solutions.solutions)} solution Found for `{problem_solutions.problem.name}`.",
+                    ).display(),
+                    "reference": reference,
+                },
+            ),
+            **kwargs,
+        )
+
+    async def fix_troubled_string(
+        self,
+        input_text: str,
+        problem_solutions: ProblemSolutions,
+        reference: str = "",
+        **kwargs: Unpack[ValidateKwargs[str]],
+    ) -> Optional[str]:
+        """Fix a troubled string based on problem solutions.
+
+        Args:
+            input_text (str): The string to be fixed.
+            problem_solutions (ProblemSolutions): The problem solutions to apply.
+            reference (str): A reference or contextual information for the string.
+            **kwargs (Unpack[ValidateKwargs[str]]): Additional keyword arguments for the validation process.
+
+        Returns:
+            Optional[str]: The fixed string, or None if fixing fails.
+        """
+        return await self.ageneric_string(
+            TEMPLATE_MANAGER.render_template(
+                CONFIG.templates.fix_troubled_string_template,
+                {
+                    "problem": problem_solutions.problem.display(),
+                    "solution": ok(
+                        problem_solutions.final_solution(),
+                        f"No solution found for problem: {problem_solutions.problem}",
+                    ).display(),
+                    "reference": reference,
+                    "string_to_fix": input_text,
+                },
+            ),
+            **kwargs,
+        )
+
+    async def correct_obj[M: SketchedAble](
+        self,
+        obj: M,
+        improvement: Improvement,
+        reference: str = "",
+        **kwargs: Unpack[ValidateKwargs[M]],
+    ) -> Optional[M]:
+        """Review and correct an object based on defined criteria and templates.
+
+        This method first conducts a review of the given object, then uses the review results
+        to generate a corrected version of the object using appropriate templates.
+
+        Args:
+            obj (M): The object to be reviewed and corrected. Must implement ProposedAble.
+            improvement (Improvement): The improvement object containing the review results.
+            reference (str): A reference or contextual information for the object.
+            **kwargs (Unpack[ValidateKwargs[M]]): Review configuration parameters including criteria and review options.
+
+        Returns:
+            Optional[M]: A corrected version of the input object, or None if correction fails.
+
+        Raises:
+            TypeError: If the provided object doesn't implement Display or WithBriefing interfaces.
+        """
+        if not improvement.decided():
+            logger.info(f"Improvement {improvement.focused_on} not decided, start deciding...")
+            improvement = await self.decide_improvement(improvement, **override_kwargs(kwargs, default=None))
+
+        total = len(improvement.problem_solutions)
+        for idx, ps in enumerate(improvement.problem_solutions):
+            logger.info(f"[{idx + 1}/{total}] Fixing {obj.__class__.__name__} for problem `{ps.problem.name}`")
+            fixed_obj = await self.fix_troubled_obj(obj, ps, reference, **kwargs)
+            if fixed_obj is None:
+                logger.error(f"[{idx + 1}/{total}] Failed to fix problem `{ps.problem.name}`")
+                return None
+            obj = fixed_obj
+        return obj
+
+    async def correct_string(
+        self, input_text: str, improvement: Improvement, reference: str = "", **kwargs: Unpack[ValidateKwargs[str]]
+    ) -> Optional[str]:
+        """Review and correct a string based on defined criteria and templates.
+
+        This method first conducts a review of the given string, then uses the review results
+        to generate a corrected version of the string using appropriate templates.
+
+        Args:
+            input_text (str): The string to be reviewed and corrected.
+            improvement (Improvement): The improvement object containing the review results.
+            reference (str): A reference or contextual information for the string.
+            **kwargs (Unpack[ValidateKwargs[str]]): Review configuration parameters including criteria and review options.
+
+        Returns:
+            Optional[str]: A corrected version of the input string, or None if correction fails.
+        """
+        if not improvement.decided():
+            logger.info(f"Improvement {improvement.focused_on} not decided, start deciding...")
+
+            improvement = await self.decide_improvement(improvement, **override_kwargs(kwargs, default=None))
+
+        for ps in improvement.problem_solutions:
+            fixed_string = await self.fix_troubled_string(input_text, ps, reference, **kwargs)
+            if fixed_string is None:
+                logger.error(
+                    f"Failed to fix troubling string when deal with problem: {ps.problem}",
+                )
+                return None
+            input_text = fixed_string
+        return input_text
+
+    async def correct_obj_inplace[M: ProposedUpdateAble](
+        self, obj: M, **kwargs: Unpack[CorrectKwargs[M]]
+    ) -> Optional[M]:
+        """Correct an object in place based on defined criteria and templates.
+
+        Args:
+            obj (M): The object to be corrected.
+            **kwargs (Unpack[CorrectKwargs[M]]): Additional keyword arguments for the correction process.
+
+        Returns:
+            Optional[M]: The corrected object, or None if correction fails.
+        """
+        corrected_obj = await self.correct_obj(obj, **kwargs)
+        if corrected_obj is None:
+            return corrected_obj
+        obj.update_from(corrected_obj)
+        return obj

fabricatio/capabilities/extract.py

@@ -0,0 +1,74 @@
+"""A module that provide capabilities for extracting information from a given source to a model."""
+
+from abc import ABC
+from typing import List, Optional, Type, Unpack, overload
+
+from fabricatio import TEMPLATE_MANAGER
+from fabricatio.capabilities.propose import Propose
+from fabricatio.models.generic import ProposedAble
+from fabricatio.models.kwargs_types import ValidateKwargs
+from fabricatio.rust import CONFIG
+
+
+class Extract(Propose, ABC):
+    """A class that extract information from a given source to a model."""
+
+    @overload
+    async def extract[M: ProposedAble](
+        self,
+        cls: Type[M],
+        source: str,
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[M]],
+    ) -> M: ...
+
+    @overload
+    async def extract[M: ProposedAble](
+        self,
+        cls: Type[M],
+        source: str,
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[None]],
+    ) -> Optional[M]: ...
+
+    @overload
+    async def extract[M: ProposedAble](
+        self,
+        cls: Type[M],
+        source: List[str],
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[M]],
+    ) -> List[M]: ...
+
+    @overload
+    async def extract[M: ProposedAble](
+        self,
+        cls: Type[M],
+        source: List[str],
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[None]],
+    ) -> List[Optional[M]]: ...
+
+    async def extract[M: ProposedAble](
+        self,
+        cls: Type[M],
+        source: List[str] | str,
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[Optional[M]]],
+    ) -> M | List[M] | Optional[M] | List[Optional[M]]:
+        """Extract information from a given source to a model."""
+        return await self.propose(
+            cls,
+            prompt=TEMPLATE_MANAGER.render_template(
+                CONFIG.templates.extract_template,
+                [{"source": s, "extract_requirement": extract_requirement} for s in source]
+                if isinstance(source, list)
+                else {"source": source, "extract_requirement": extract_requirement, "align_language": align_language},
+            ),
+            **kwargs,
+        )

fabricatio/capabilities/persist.py

@@ -0,0 +1,103 @@
+"""Persistence capabilities for model instances."""
+
+from abc import ABC
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Self
+
+from loguru import logger
+
+from fabricatio.fs import safe_text_read
+from fabricatio.models.generic import Base
+from fabricatio.rust import blake3_hash
+
+
+class PersistentAble(Base, ABC):
+    """Class providing file persistence capabilities.
+
+    Enables saving model instances to disk with timestamped filenames and loading from persisted files.
+    Implements basic versioning through filename hashing and timestamping.
+    """
+
+    def persist(self, path: str | Path) -> Self:
+        """Save model instance to disk with versioned filename.
+
+        Args:
+            path (str | Path): Target directory or file path. If directory, filename is auto-generated.
+
+        Returns:
+            Self: Current instance for method chaining
+
+        Notes:
+            - Filename format: <ClassName>_<YYYYMMDD_HHMMSS>_<6-char_hash>.json
+            - Hash generated from JSON content ensures uniqueness
+        """
+        p = Path(path)
+        out = self.model_dump_json(indent=1, by_alias=True)
+
+        # Generate a timestamp in the format YYYYMMDD_HHMMSS
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+        # Generate the hash
+        file_hash = blake3_hash(out.encode())[:6]
+
+        # Construct the file name with timestamp and hash
+        file_name = f"{self.__class__.__name__}_{timestamp}_{file_hash}.json"
+
+        if p.is_dir():
+            p.joinpath(file_name).write_text(out, encoding="utf-8")
+        else:
+            p.mkdir(exist_ok=True, parents=True)
+            p.write_text(out, encoding="utf-8")
+
+        logger.info(f"Persisted `{self.__class__.__name__}` to {p.as_posix()}")
+        return self
+
+    @classmethod
+    def from_latest_persistent(cls, dir_path: str | Path) -> Optional[Self]:
+        """Load most recent persisted instance from directory.
+
+        Args:
+            dir_path (str | Path): Directory containing persisted files
+
+        Returns:
+            Self: Most recently modified instance
+
+        Raises:
+            NotADirectoryError: If path is not a valid directory
+            FileNotFoundError: If no matching files found
+        """
+        dir_path = Path(dir_path)
+        if not dir_path.is_dir():
+            return None
+
+        pattern = f"{cls.__name__}_*.json"
+        files = list(dir_path.glob(pattern))
+
+        if not files:
+            return None
+
+        def _get_timestamp(file_path: Path) -> datetime:
+            stem = file_path.stem
+            parts = stem.split("_")
+            return datetime.strptime(f"{parts[1]}_{parts[2]}", "%Y%m%d_%H%M%S")
+
+        files.sort(key=lambda f: _get_timestamp(f), reverse=True)
+
+        return cls.from_persistent(files.pop(0))
+
+    @classmethod
+    def from_persistent(cls, path: str | Path) -> Self:
+        """Load an instance from a specific persisted file.
+
+        Args:
+            path (str | Path): Path to the JSON file.
+
+        Returns:
+            Self: The loaded instance from the file.
+
+        Raises:
+            FileNotFoundError: If the specified file does not exist.
+            ValueError: If the file content is invalid for the model.
+        """
+        return cls.model_validate_json(safe_text_read(path))

fabricatio/capabilities/propose.py

@@ -0,0 +1,65 @@
+"""A module for the task capabilities of the Fabricatio library."""
+from abc import ABC
+from typing import List, Optional, Type, Unpack, overload
+
+from fabricatio.models.generic import ProposedAble
+from fabricatio.models.kwargs_types import ValidateKwargs
+from fabricatio.models.usages import LLMUsage
+
+
+class Propose(LLMUsage,ABC):
+    """A class that proposes an Obj based on a prompt."""
+
+    @overload
+    async def propose[M: ProposedAble](
+        self,
+        cls: Type[M],
+        prompt: List[str],
+        **kwargs: Unpack[ValidateKwargs[None]],
+    ) -> List[Optional[M]]: ...
+
+    @overload
+    async def propose[M: ProposedAble](
+        self,
+        cls: Type[M],
+        prompt: List[str],
+        **kwargs: Unpack[ValidateKwargs[M]],
+    ) -> List[M]: ...
+
+    @overload
+    async def propose[M: ProposedAble](
+        self,
+        cls: Type[M],
+        prompt: str,
+        **kwargs: Unpack[ValidateKwargs[None]],
+    ) -> Optional[M]: ...
+    @overload
+    async def propose[M: ProposedAble](
+        self,
+        cls: Type[M],
+        prompt: str,
+        **kwargs: Unpack[ValidateKwargs[M]],
+    ) -> M: ...
+
+    async def propose[M: ProposedAble](
+        self,
+        cls: Type[M],
+        prompt: List[str] | str,
+        **kwargs: Unpack[ValidateKwargs[Optional[M]]],
+    ) -> Optional[M] | List[Optional[M]] | M | List[M]:
+        """Asynchronously proposes a task based on a given prompt and parameters.
+
+        Parameters:
+            cls: The class type of the task to be proposed.
+            prompt: The prompt text for proposing a task, which is a string that must be provided.
+            **kwargs: The keyword arguments for the LLM (Large Language Model) usage.
+
+        Returns:
+            A Task object based on the proposal result.
+        """
+        return await self.aask_validate(
+            question=cls.create_json_prompt(prompt),
+            validator=cls.instantiate_from_string,
+            **kwargs,
+        )
+