fabricatio 0.2.8.dev3__cp312-cp312-win_amd64.whl → 0.2.9__cp312-cp312-win_amd64.whl

fabricatio/actions/output.py

@@ -1,7 +1,7 @@
 """Dump the finalized output to a file."""
 
 from pathlib import Path
-from typing import Iterable, List, Optional, Type
+from typing import Any, Iterable, List, Optional, Type
 
 from fabricatio.journal import logger
 from fabricatio.models.action import Action
@@ -33,6 +33,7 @@ class DumpFinalizedOutput(Action):
                 "Could not find the path of file to dump the data.",
             )
         )
+        logger.info(f"Saving output to {dump_path.as_posix()}")
         ok(to_dump, "Could not dump the data since the path is not specified.").finalized_dump_to(dump_path)
         return dump_path.as_posix()
 
@@ -41,7 +42,11 @@ class PersistentAll(Action):
     """Persist all the data to a file."""
 
     output_key: str = "persistent_count"
+    """The number of objects persisted."""
     persist_dir: Optional[str] = None
+    """The directory to persist the data."""
+    override: bool = False
+    """Whether to remove the existing dir before dumping."""
 
     async def _execute(
         self,
@@ -64,16 +69,22 @@ class PersistentAll(Action):
         if persist_dir.is_file():
             logger.warning("Dump should be a directory, but it is a file. Skip dumping.")
             return count
-
+        if self.override and persist_dir.is_dir():
+            logger.info(f"Override the existing directory {persist_dir.as_posix()}.")
+            persist_dir.rmdir()
+        logger.info(f"Starting persistence in directory {persist_dir}")
         for k, v in cxt.items():
             final_dir = persist_dir.joinpath(k)
+            logger.debug(f"Checking key {k} for persistence")
             if isinstance(v, PersistentAble):
+                logger.info(f"Persisting object {k} to {final_dir}")
                 final_dir.mkdir(parents=True, exist_ok=True)
                 v.persist(final_dir)
                 count += 1
             if isinstance(v, Iterable) and any(
                 persistent_ables := (pers for pers in v if isinstance(pers, PersistentAble))
             ):
+                logger.info(f"Persisting collection {k} to {final_dir}")
                 final_dir.mkdir(parents=True, exist_ok=True)
                 for per in persistent_ables:
                     per.persist(final_dir)
@@ -92,11 +103,56 @@ class RetrieveFromPersistent[T: PersistentAble](Action):
     retrieve_cls: Type[T]
     """The class of the object to retrieve."""
 
-    async def _execute(self, /, **__) -> Optional[T | List[T]]:
-        logger.info(f"Retrieve `{self.retrieve_cls.__name__}` from persistent file: {self.load_path}")
+    async def _execute(self, /, **_) -> Optional[T | List[T]]:
+        logger.info(f"Retrieve `{self.retrieve_cls.__name__}` from {self.load_path}")
         if not (p := Path(self.load_path)).exists():
+            logger.warning(f"Path {self.load_path} does not exist")
             return None
 
         if p.is_dir():
+            logger.info(f"Found directory with {len(list(p.glob('*')))} items")
             return [self.retrieve_cls.from_persistent(per) for per in p.glob("*")]
         return self.retrieve_cls.from_persistent(self.load_path)
+
+
+class RetrieveFromLatest[T: PersistentAble](RetrieveFromPersistent[T]):
+    """Retrieve the object from the latest persistent file in the dir at `load_path`."""
+
+    async def _execute(self, /, **_) -> Optional[T]:
+        logger.info(f"Retrieve latest `{self.retrieve_cls.__name__}` from {self.load_path}")
+        if not (p := Path(self.load_path)).exists():
+            logger.warning(f"Path {self.load_path} does not exist")
+            return None
+
+        if p.is_dir():
+            logger.info(f"Found directory with {len(list(p.glob('*')))} items")
+            return self.retrieve_cls.from_latest_persistent(self.load_path)
+        logger.error(f"Path {self.load_path} is not a directory")
+        return None
+
+
+class GatherAsList(Action):
+    """Gather the objects from the context as a list.
+
+    Notes:
+        If both `gather_suffix` and `gather_prefix` are specified, only the objects with the suffix will be gathered.
+    """
+
+    output_key: str = "gathered"
+    """Gather the objects from the context as a list."""
+    gather_suffix: Optional[str] = None
+    """Gather the objects from the context as a list."""
+    gather_prefix: Optional[str] = None
+    """Gather the objects from the context as a list."""
+
+    async def _execute(self, **cxt) -> List[Any]:
+        if self.gather_suffix is not None:
+            result = [cxt[k] for k in cxt if k.endswith(self.gather_suffix)]
+            logger.debug(f"Gathered {len(result)} items with suffix {self.gather_suffix}")
+            return result
+        if self.gather_prefix is None:
+            logger.error(err := "Either `gather_suffix` or `gather_prefix` must be specified.")
+            raise ValueError(err)
+        result = [cxt[k] for k in cxt if k.startswith(self.gather_prefix)]
+        logger.debug(f"Gathered {len(result)} items with prefix {self.gather_prefix}")
+        return result

fabricatio/actions/rag.py

@@ -2,12 +2,13 @@
 
 from typing import List, Optional
 
+from questionary import text
+
 from fabricatio.capabilities.rag import RAG
 from fabricatio.journal import logger
 from fabricatio.models.action import Action
 from fabricatio.models.generic import Vectorizable
 from fabricatio.models.task import Task
-from questionary import text
 
 
 class InjectToDB(Action, RAG):

fabricatio/actions/rules.py

@@ -0,0 +1,72 @@
+"""A module containing the DraftRuleSet action."""
+
+from typing import List, Optional
+
+from fabricatio.capabilities.check import Check
+from fabricatio.journal import logger
+from fabricatio.models.action import Action
+from fabricatio.models.extra.rule import RuleSet
+from fabricatio.utils import ok
+
+
+class DraftRuleSet(Action, Check):
+    """Action to draft a ruleset based on a given requirement description."""
+
+    output_key: str = "drafted_ruleset"
+    """The key used to store the drafted ruleset in the context dictionary."""
+
+    ruleset_requirement: Optional[str] = None
+    """The natural language description of the desired ruleset characteristics."""
+    rule_count: int = 0
+    """The number of rules to generate in the ruleset (0 for no restriction)."""
+
+    async def _execute(
+        self,
+        ruleset_requirement: Optional[str] = None,
+        **_,
+    ) -> Optional[RuleSet]:
+        """Draft a ruleset based on the requirement description.
+
+        Args:
+            ruleset_requirement (str): Natural language description of desired ruleset characteristics
+            rule_count (int): Number of rules to generate (0 for no restriction)
+            **kwargs: Validation parameters for rule generation
+
+        Returns:
+            Optional[RuleSet]: Drafted ruleset object or None if generation fails
+        """
+        ruleset = await self.draft_ruleset(
+            ruleset_requirement=ok(ruleset_requirement or self.ruleset_requirement, "No ruleset requirement provided"),
+            rule_count=self.rule_count,
+        )
+        if ruleset:
+            logger.info(f"Drafted Ruleset length: {len(ruleset.rules)}\n{ruleset.display()}")
+        else:
+            logger.warning(f"Drafting Rule Failed for:\n{ruleset_requirement}")
+        return ruleset
+
+
+class GatherRuleset(Action):
+    """Action to gather a ruleset from a given requirement description."""
+
+    output_key: str = "gathered_ruleset"
+    """The key used to store the drafted ruleset in the context dictionary."""
+
+    to_gather: List[str]
+    """the cxt name of RuleSet to gather"""
+
+    async def _execute(self, **cxt) -> RuleSet:
+        logger.info(f"Gathering Ruleset from {self.to_gather}")
+        # Fix for not_found
+        not_found = next((t for t in self.to_gather if t not in cxt), None)
+        if not_found:
+            raise ValueError(
+                f"Not all required keys found in context: {self.to_gather}|`{not_found}` not found in context."
+            )
+
+        # Fix for invalid RuleSet check
+        invalid = next((t for t in self.to_gather if not isinstance(cxt[t], RuleSet)), None)
+        if invalid is not None:
+            raise TypeError(f"Invalid RuleSet instance for key `{invalid}`")
+
+        return RuleSet.gather(*[cxt[t] for t in self.to_gather])

fabricatio/capabilities/__init__.py

@@ -0,0 +1 @@
+"""A module containing some high level capabilities."""

fabricatio/capabilities/censor.py

@@ -0,0 +1,104 @@
+"""Module for censoring objects and strings based on provided rulesets.
+
+This module includes the Censor class which inherits from both Correct and Check classes.
+It provides methods to censor objects and strings by first checking them against a ruleset and then correcting them if necessary.
+"""
+
+from typing import Optional, Unpack
+
+from fabricatio.capabilities.check import Check
+from fabricatio.capabilities.correct import Correct
+from fabricatio.journal import logger
+from fabricatio.models.extra.problem import Improvement
+from fabricatio.models.extra.rule import RuleSet
+from fabricatio.models.generic import ProposedUpdateAble, SketchedAble
+from fabricatio.models.kwargs_types import ReferencedKwargs
+from fabricatio.utils import override_kwargs
+
+
+class Censor(Correct, Check):
+    """Class to censor objects and strings based on provided rulesets.
+
+    Inherits from both Correct and Check classes.
+    Provides methods to censor objects and strings by first checking them against a ruleset and then correcting them if necessary.
+
+    """
+
+    async def censor_obj[M: SketchedAble](
+        self, obj: M, ruleset: RuleSet, **kwargs: Unpack[ReferencedKwargs[M]]
+    ) -> Optional[M]:
+        """Censors an object based on the provided ruleset.
+
+        Args:
+            obj (M): The object to be censored.
+            ruleset (RuleSet): The ruleset to apply for censoring.
+            **kwargs: Additional keyword arguments to be passed to the check and correct methods.
+
+        Returns:
+            Optional[M]: The censored object if corrections were made, otherwise None.
+
+        Note:
+            This method first checks the object against the ruleset and then corrects it if necessary.
+        """
+        imp = await self.check_obj(obj, ruleset, **override_kwargs(kwargs, default=None))
+        if imp is None:
+            return None
+        if not imp:
+            logger.info(f"No improvement found for `{obj.__class__.__name__}`.")
+            return obj
+        logger.info(f'Generated {len(imp)} improvement(s) for `{obj.__class__.__name__}')
+        return await self.correct_obj(obj, Improvement.gather(*imp), **kwargs)
+
+    async def censor_string(
+        self, input_text: str, ruleset: RuleSet, **kwargs: Unpack[ReferencedKwargs[str]]
+    ) -> Optional[str]:
+        """Censors a string based on the provided ruleset.
+
+        Args:
+            input_text (str): The string to be censored.
+            ruleset (RuleSet): The ruleset to apply for censoring.
+            **kwargs: Additional keyword arguments to be passed to the check and correct methods.
+
+        Returns:
+            Optional[str]: The censored string if corrections were made, otherwise None.
+
+        Note:
+            This method first checks the string against the ruleset and then corrects it if necessary.
+        """
+        imp = await self.check_string(input_text, ruleset, **override_kwargs(kwargs, default=None))
+        if imp is None:
+            logger.warning(f"Censor failed for string:\n{input_text}")
+            return None
+        if not imp:
+            logger.info("No improvement found for string.")
+            return input_text
+        logger.info(f'Generated {len(imp)} improvement(s) for string.')
+        return await self.correct_string(input_text, Improvement.gather(*imp), **kwargs)
+
+    async def censor_obj_inplace[M: ProposedUpdateAble](
+        self, obj: M, ruleset: RuleSet, **kwargs: Unpack[ReferencedKwargs[M]]
+    ) -> Optional[M]:
+        """Censors an object in-place based on the provided ruleset.
+
+        This method modifies the object directly if corrections are needed.
+
+        Args:
+            obj (M): The object to be censored.
+            ruleset (RuleSet): The ruleset to apply for censoring.
+            **kwargs: Additional keyword arguments to be passed to the check and correct methods.
+
+        Returns:
+            Optional[M]: The censored object if corrections were made, otherwise None.
+
+        Note:
+            This method first checks the object against the ruleset and then corrects it in-place if necessary.
+        """
+        imp = await self.check_obj(obj, ruleset, **override_kwargs(kwargs, default=None))
+        if imp is None:
+            logger.warning(f"Censor failed for `{obj.__class__.__name__}`")
+            return None
+        if not imp:
+            logger.info(f"No improvement found for `{obj.__class__.__name__}`.")
+            return obj
+        logger.info(f'Generated {len(imp)} improvement(s) for `{obj.__class__.__name__}')
+        return await self.correct_obj_inplace(obj, improvement=Improvement.gather(*imp), **kwargs)

fabricatio/capabilities/check.py

@@ -1,91 +1,146 @@
 """A class that provides the capability to check strings and objects against rules and guidelines."""
-from typing import Optional, Unpack
+
+from asyncio import gather
+from typing import List, Optional, Unpack
 
 from fabricatio import TEMPLATE_MANAGER
 from fabricatio.capabilities.advanced_judge import AdvancedJudge
 from fabricatio.capabilities.propose import Propose
 from fabricatio.config import configs
+from fabricatio.journal import logger
+from fabricatio.models.extra.patches import RuleSetMetadata
 from fabricatio.models.extra.problem import Improvement
 from fabricatio.models.extra.rule import Rule, RuleSet
 from fabricatio.models.generic import Display, WithBriefing
 from fabricatio.models.kwargs_types import ValidateKwargs
+from fabricatio.rust import detect_language
 from fabricatio.utils import override_kwargs
 
 
 class Check(AdvancedJudge, Propose):
-    """Class that provides the capability to validate strings/objects against predefined rules and guidelines."""
+    """Class for validating strings/objects against predefined rules and guidelines.
+
+    This capability combines rule-based judgment and proposal generation to provide
+    structured validation results with actionable improvement suggestions.
+    """
 
     async def draft_ruleset(
-        self, ruleset_requirement: str, **kwargs: Unpack[ValidateKwargs[RuleSet]]
+        self, ruleset_requirement: str, rule_count: int = 0, **kwargs: Unpack[ValidateKwargs[Rule]]
     ) -> Optional[RuleSet]:
-        """Generate a rule set based on specified requirements.
+        """Generate rule set based on requirement description.
 
         Args:
-            ruleset_requirement (str): Description of desired rule set characteristics
-            **kwargs: Validation configuration parameters
+            ruleset_requirement (str): Natural language description of desired ruleset characteristics
+            rule_count (int): Number of rules to generate (0 for default count)
+            **kwargs: Validation parameters for rule generation
 
         Returns:
-            Optional[RuleSet]: Generated rule set if successful
-        """
-        return await self.propose(RuleSet, ruleset_requirement, **kwargs)
+            Optional[RuleSet]: Validated ruleset object or None if generation fails
 
-    async def draft_rule(self, rule_requirement: str, **kwargs: Unpack[ValidateKwargs[Rule]]) -> Optional[Rule]:
-        """Create a specific rule based on given specifications.
+        Notes:
+            - Requires valid template configuration in configs.templates
+            - Returns None if any step in rule generation fails
+            - Uses `alist_str` for requirement breakdown and iterative rule proposal
+        """
+        rule_reqs = (
+            await self.alist_str(
+                TEMPLATE_MANAGER.render_template(
+                    configs.templates.ruleset_requirement_breakdown_template,
+                    {"ruleset_requirement": ruleset_requirement},
+                ),
+                rule_count,
+                **override_kwargs(kwargs, default=None),
+            )
+            if rule_count > 1
+            else [ruleset_requirement]
+        )
+
+        if rule_reqs is None:
+            return None
+
+        rules = await self.propose(
+            Rule,
+            [
+                TEMPLATE_MANAGER.render_template(configs.templates.rule_requirement_template, {"rule_requirement": r})
+                for r in rule_reqs
+            ],
+            **kwargs,
+        )
+        if any(r for r in rules if r is None):
+            return None
+
+        ruleset_patch = await self.propose(
+            RuleSetMetadata,
+            f"{ruleset_requirement}\n\nYou should use `{detect_language(ruleset_requirement)}`!",
+            **override_kwargs(kwargs, default=None),
+        )
 
-        Args:
-            rule_requirement (str): Detailed rule description requirements
-            **kwargs: Validation configuration parameters
+        if ruleset_patch is None:
+            return None
 
-        Returns:
-            Optional[Rule]: Generated rule instance if successful
-        """
-        return await self.propose(Rule, rule_requirement, **kwargs)
+        return RuleSet(rules=rules, **ruleset_patch.as_kwargs())
 
-    async def check_string(
+    async def check_string_against_rule(
         self,
         input_text: str,
         rule: Rule,
+        reference: str = "",
         **kwargs: Unpack[ValidateKwargs[Improvement]],
     ) -> Optional[Improvement]:
-        """Evaluate text against a specific rule.
+        """Validate text against specific rule.
 
         Args:
-            input_text (str): Text content to be evaluated
-            rule (Rule): Rule instance used for validation
-            **kwargs: Validation configuration parameters
+            input_text (str): Text content to validate
+            rule (Rule): Rule instance for validation
+            reference (str): Reference text for comparison (default: "")
+            **kwargs: Configuration for validation process
 
         Returns:
-            Optional[Improvement]: Suggested improvement if violations found, else None
+            Optional[Improvement]: Suggested improvement if violation detected
+
+        Notes:
+            - Uses `evidently_judge` to determine violation presence
+            - Renders template using `check_string_template` for proposal
+            - Proposes Improvement only when violation is confirmed
         """
         if judge := await self.evidently_judge(
-            f"# Content to exam\n{input_text}\n\n# Rule Must to follow\n{rule.display()}\nDoes `Content to exam` provided above violate the `Rule Must to follow` provided above?",
+            f"# Content to exam\n{input_text}\n\n# Rule Must to follow\n{rule.display()}\nDoes `Content to exam` provided above violate the `{rule.name}` provided above?"
+            f"should I take some measure to fix that violation? true for I do need, false for I don't need.",
             **override_kwargs(kwargs, default=None),
         ):
+            logger.info(f"Rule `{rule.name}` violated: \n{judge.display()}")
             return await self.propose(
                 Improvement,
                 TEMPLATE_MANAGER.render_template(
                     configs.templates.check_string_template,
-                    {"to_check": input_text, "rule": rule, "judge": judge.display()},
+                    {"to_check": input_text, "rule": rule.display(), "judge": judge.display(), "reference": reference},
                 ),
                 **kwargs,
             )
         return None
 
-    async def check_obj[M: (Display, WithBriefing)](
+    async def check_obj_against_rule[M: (Display, WithBriefing)](
         self,
         obj: M,
         rule: Rule,
+        reference: str = "",
         **kwargs: Unpack[ValidateKwargs[Improvement]],
     ) -> Optional[Improvement]:
-        """Validate an object against specified rule.
+        """Validate object against rule using text representation.
 
         Args:
-            obj (M): Object implementing Display or WithBriefing interface
-            rule (Rule): Validation rule to apply
+            obj (M): Object implementing Display/WithBriefing interface
+            rule (Rule): Validation rule
+            reference (str): Reference text for comparison (default: "")
             **kwargs: Validation configuration parameters
 
         Returns:
-            Optional[Improvement]: Improvement suggestion if issues detected
+            Optional[Improvement]: Improvement suggestion if issues found
+
+        Notes:
+            - Requires obj to implement display() or briefing property
+            - Raises TypeError for incompatible object types
+            - Converts object to text before string validation
         """
         if isinstance(obj, Display):
             input_text = obj.display()
@@ -94,4 +149,65 @@ class Check(AdvancedJudge, Propose):
         else:
             raise TypeError("obj must be either Display or WithBriefing")
 
-        return await self.check_string(input_text, rule, **kwargs)
+        return await self.check_string_against_rule(input_text, rule, reference, **kwargs)
+
+    async def check_string(
+        self,
+        input_text: str,
+        ruleset: RuleSet,
+        reference: str = "",
+        **kwargs: Unpack[ValidateKwargs[Improvement]],
+    ) -> Optional[List[Improvement]]:
+        """Validate text against full ruleset.
+
+        Args:
+            input_text (str): Text content to validate
+            ruleset (RuleSet): Collection of validation rules
+            reference (str): Reference text for comparison
+            **kwargs: Validation configuration parameters
+
+        Returns:
+            Optional[Improvement]: First detected improvement
+
+        Notes:
+            - Checks rules sequentially and returns first violation
+            - Halts validation after first successful improvement proposal
+            - Maintains rule execution order from ruleset.rules list
+        """
+        imp_seq = await gather(
+            *[self.check_string_against_rule(input_text, rule, reference, **kwargs) for rule in ruleset.rules]
+        )
+        if imp_seq is None:
+            logger.warning(f"Generation failed for string check against `{ruleset.name}`")
+            return None
+        return [imp for imp in imp_seq if imp]
+
+    async def check_obj[M: (Display, WithBriefing)](
+        self,
+        obj: M,
+        ruleset: RuleSet,
+        reference: str = "",
+        **kwargs: Unpack[ValidateKwargs[Improvement]],
+    ) -> Optional[List[Improvement]]:
+        """Validate object against full ruleset.
+
+        Args:
+            obj (M): Object implementing Display/WithBriefing interface
+            ruleset (RuleSet): Collection of validation rules
+            reference (str): Reference text for comparison (default: "")
+            **kwargs: Validation configuration parameters
+
+        Returns:
+            Optional[Improvement]: First detected improvement
+
+        Notes:
+            - Uses check_obj_against_rule for individual rule checks
+            - Maintains same early termination behavior as check_string
+            - Validates object through text conversion mechanism
+        """
+        imp_seq = await gather(*[self.check_obj_against_rule(obj, rule, reference, **kwargs) for rule in ruleset.rules])
+
+        if imp_seq is None:
+            logger.warning(f"Generation Failed for `{obj.__class__.__name__}` against Ruleset `{ruleset.name}`")
+            return None
+        return [i for i in imp_seq if i]