fabricatio 0.2.8.dev3__cp312-cp312-win_amd64.whl → 0.2.8.dev4__cp312-cp312-win_amd64.whl

fabricatio/capabilities/rating.py

@@ -7,10 +7,11 @@ from typing import Dict, List, Optional, Set, Tuple, Union, Unpack, overload
 from fabricatio._rust_instances import TEMPLATE_MANAGER
 from fabricatio.config import configs
 from fabricatio.journal import logger
-from fabricatio.models.kwargs_types import ValidateKwargs
+from fabricatio.models.generic import Display
+from fabricatio.models.kwargs_types import CompositeScoreKwargs, ValidateKwargs
 from fabricatio.models.usages import LLMUsage
 from fabricatio.parser import JsonCapture
-from fabricatio.utils import override_kwargs
+from fabricatio.utils import ok, override_kwargs
 from more_itertools import flatten, windowed
 from pydantic import NonNegativeInt, PositiveInt
 
@@ -86,6 +87,7 @@ class Rating(LLMUsage):
         to_rate: str,
         topic: str,
         criteria: Set[str],
+        manual: Optional[Dict[str, str]],
         score_range: Tuple[float, float] = (0.0, 1.0),
         **kwargs: Unpack[ValidateKwargs],
     ) -> Dict[str, float]: ...
@@ -96,6 +98,7 @@ class Rating(LLMUsage):
         to_rate: List[str],
         topic: str,
         criteria: Set[str],
+        manual: Optional[Dict[str, str]],
         score_range: Tuple[float, float] = (0.0, 1.0),
         **kwargs: Unpack[ValidateKwargs],
     ) -> List[Dict[str, float]]: ...
@@ -105,6 +108,7 @@ class Rating(LLMUsage):
         to_rate: Union[str, List[str]],
         topic: str,
         criteria: Set[str],
+        manual: Optional[Dict[str, str]],
         score_range: Tuple[float, float] = (0.0, 1.0),
         **kwargs: Unpack[ValidateKwargs],
     ) -> Optional[Dict[str, float] | List[Dict[str, float]]]:
@@ -114,6 +118,7 @@ class Rating(LLMUsage):
             to_rate (Union[str, List[str]]): The string or sequence of strings to be rated.
             topic (str): The topic related to the task.
             criteria (Set[str]): A set of criteria for rating.
+            manual (Optional[Dict[str, str]]): A dictionary containing the rating criteria. If not provided, then this method will draft the criteria automatically.
             score_range (Tuple[float, float], optional): A tuple representing the valid score range. Defaults to (0.0, 1.0).
             **kwargs (Unpack[ValidateKwargs]): Additional keyword arguments for the LLM usage.
 
@@ -121,7 +126,11 @@ class Rating(LLMUsage):
             Union[Dict[str, float], List[Dict[str, float]]]: A dictionary with the ratings for each criterion if a single string is provided,
             or a list of dictionaries with the ratings for each criterion if a sequence of strings is provided.
         """
-        manual = await self.draft_rating_manual(topic, criteria, **kwargs) or dict(zip(criteria, criteria, strict=True))
+        manual = (
+            manual
+            or await self.draft_rating_manual(topic, criteria, **override_kwargs(kwargs, default=None))
+            or dict(zip(criteria, criteria, strict=True))
+        )
 
         return await self.rate_fine_grind(to_rate, manual, score_range, **kwargs)
 
@@ -309,7 +318,7 @@ class Rating(LLMUsage):
             validator=lambda resp: JsonCapture.validate_with(resp, target_type=float),
             **kwargs,
         )
-        weights = [1]
+        weights = [1.0]
         for rw in relative_weights:
             weights.append(weights[-1] * rw)
         total = sum(weights)
@@ -319,27 +328,66 @@ class Rating(LLMUsage):
         self,
         topic: str,
         to_rate: List[str],
-        reasons_count: PositiveInt = 2,
-        criteria_count: PositiveInt = 5,
-        **kwargs: Unpack[ValidateKwargs],
+        criteria: Optional[Set[str]] = None,
+        weights: Optional[Dict[str, float]] = None,
+        manual: Optional[Dict[str, str]] = None,
+        **kwargs: Unpack[ValidateKwargs[List[Dict[str, float]]]],
     ) -> List[float]:
         """Calculates the composite scores for a list of items based on a given topic and criteria.
 
         Args:
             topic (str): The topic for the rating.
             to_rate (List[str]): A list of strings to be rated.
-            reasons_count (PositiveInt, optional): The number of reasons to extract from each pair of examples. Defaults to 2.
-            criteria_count (PositiveInt, optional): The number of criteria to draft. Defaults to 5.
+            criteria (Optional[Set[str]]): A set of criteria for the rating. Defaults to None.
+            weights (Optional[Dict[str, float]]): A dictionary of rating weights for each criterion. Defaults to None.
+            manual (Optional[Dict[str, str]]): A dictionary of manual ratings for each item. Defaults to None.
             **kwargs (Unpack[ValidateKwargs]): Additional keyword arguments for the LLM usage.
 
         Returns:
             List[float]: A list of composite scores for the items.
         """
-        criteria = await self.draft_rating_criteria_from_examples(
-            topic, to_rate, reasons_count, criteria_count, **kwargs
+        criteria = ok(
+            criteria
+            or await self.draft_rating_criteria_from_examples(topic, to_rate, **override_kwargs(kwargs, default=None))
+        )
+        weights = ok(
+            weights or await self.drafting_rating_weights_klee(topic, criteria, **override_kwargs(kwargs, default=None))
         )
-        weights = await self.drafting_rating_weights_klee(topic, criteria, **kwargs)
         logger.info(f"Criteria: {criteria}\nWeights: {weights}")
-        ratings_seq = await self.rate(to_rate, topic, criteria, **kwargs)
+        ratings_seq = await self.rate(to_rate, topic, criteria, manual, **kwargs)
 
         return [sum(ratings[c] * weights[c] for c in criteria) for ratings in ratings_seq]
+
+    @overload
+    async def best(self, candidates: List[str], k: int=1, **kwargs: Unpack[CompositeScoreKwargs]) -> List[str]: ...
+    @overload
+    async def best[T: Display](
+        self, candidates: List[T], k: int=1, **kwargs: Unpack[CompositeScoreKwargs]
+    ) -> List[T]: ...
+
+    async def best[T: Display](
+        self, candidates: List[str] | List[T], k: int=1, **kwargs: Unpack[CompositeScoreKwargs]
+    ) -> Optional[List[str] | List[T]]:
+        """Choose the best candidates from the list of candidates based on the composite score.
+
+        Args:
+            k (int): The number of best candidates to choose.
+            candidates (List[str]): A list of candidates to choose from.
+            **kwargs (CompositeScoreKwargs): Additional keyword arguments for the composite score calculation.
+
+        Returns:
+            List[str]: The best candidates.
+        """
+        if (leng := len(candidates)) == 0:
+            logger.warning(f"No candidates, got {leng}, return None.")
+            return None
+
+        if leng == 1:
+            logger.warning(f"Only one candidate, got {leng}, return it.")
+            return candidates
+        logger.info(f"Choose best {k} from {leng} candidates.")
+
+        rating_seq = await self.composite_score(
+            to_rate=[c.display() if isinstance(c, Display) else c for c in candidates], **kwargs
+        )
+        return [a[0] for a in sorted(zip(candidates, rating_seq, strict=True), key=lambda x: x[1], reverse=True)[:k]]  # pyright: ignore [reportReturnType]

fabricatio/config.py

@@ -229,9 +229,6 @@ class TemplateConfig(BaseModel):
     generic_string_template: str = Field(default="generic_string")
     """The name of the generic string template which will be used to review a string."""
 
-    correct_template: str = Field(default="correct")
-    """The name of the correct template which will be used to correct a string."""
-
     co_validation_template: str = Field(default="co_validation")
     """The name of the co-validation template which will be used to co-validate a string."""
 
@@ -241,6 +238,15 @@ class TemplateConfig(BaseModel):
     check_string_template: str = Field(default="check_string")
     """The name of the check string template which will be used to check a string."""
 
+    ruleset_requirement_breakdown_template: str = Field(default="ruleset_requirement_breakdown")
+    """The name of the ruleset requirement breakdown template which will be used to breakdown a ruleset requirement."""
+
+    fix_troubled_obj_template: str = Field(default="fix_troubled_obj")
+    """The name of the fix troubled object template which will be used to fix a troubled object."""
+
+    fix_troubled_string_template: str = Field(default="fix_troubled_string")
+    """The name of the fix troubled string template which will be used to fix a troubled string."""
+
 class MagikaConfig(BaseModel):
     """Magika configuration class."""
 

fabricatio/models/action.py

@@ -9,16 +9,14 @@ from abc import abstractmethod
 from asyncio import Queue, create_task
 from typing import Any, Dict, Self, Tuple, Type, Union, final
 
-from fabricatio.capabilities.correct import Correct
-from fabricatio.capabilities.task import HandleTask, ProposeTask
 from fabricatio.journal import logger
 from fabricatio.models.generic import WithBriefing
 from fabricatio.models.task import Task
-from fabricatio.models.usages import ToolBoxUsage
+from fabricatio.models.usages import LLMUsage, ToolBoxUsage
 from pydantic import Field, PrivateAttr
 
 
-class Action(WithBriefing, HandleTask, ProposeTask, Correct):
+class Action(WithBriefing, LLMUsage):
     """Class that represents an action to be executed in a workflow.
 
     Actions are the atomic units of work in a workflow. Each action performs
@@ -97,7 +95,8 @@ class WorkFlow(WithBriefing, ToolBoxUsage):
     A workflow manages the execution of multiple actions in sequence, passing
     a shared context between them and handling task lifecycle events.
     """
-    description:str =""
+
+    description: str = ""
     """The description of the workflow, which describes the workflow's purpose and requirements."""
 
     _context: Queue[Dict[str, Any]] = PrivateAttr(default_factory=lambda: Queue(maxsize=1))

fabricatio/models/adv_kwargs_types.py

@@ -0,0 +1,25 @@
+"""A module containing kwargs types for content correction and checking operations."""
+from fabricatio.models.extra.problem import Improvement
+from fabricatio.models.extra.rule import RuleSet
+from fabricatio.models.generic import SketchedAble
+from fabricatio.models.kwargs_types import ReferencedKwargs
+
+
+class CorrectKwargs[T: SketchedAble](ReferencedKwargs[T], total=False):
+    """Arguments for content correction operations.
+
+    Extends GenerateKwargs with parameters for correcting content based on
+    specific criteria and templates.
+    """
+
+    improvement: Improvement
+
+
+class CheckKwargs(ReferencedKwargs[Improvement], total=False):
+    """Arguments for content checking operations.
+
+    Extends GenerateKwargs with parameters for checking content against
+    specific criteria and templates.
+    """
+
+    ruleset: RuleSet

fabricatio/models/extra/advanced_judge.py

@@ -5,18 +5,21 @@ from typing import List
 from fabricatio.models.generic import Display, ProposedAble
 
 
-class JudgeMent(ProposedAble,Display):
+class JudgeMent(ProposedAble, Display):
     """Represents a judgment result containing supporting/denying evidence and final verdict.
 
     The class stores both affirmative and denies evidence, truth and reasons lists along with the final boolean judgment.
     """
+
+    issue_to_judge: str
+    """The issue to be judged"""
+
     deny_evidence: List[str]
     """List of clues supporting the denial."""
 
     affirm_evidence: List[str]
     """List of clues supporting the affirmation."""
 
-
     final_judgement: bool
     """The final judgment made according to all extracted clues."""
 

fabricatio/models/extra/article_base.py

@@ -15,6 +15,7 @@ from fabricatio.models.generic import (
     PersistentAble,
     ProposedUpdateAble,
     ResolveUpdateConflict,
+    SequencePatch,
 )
 
 
@@ -29,7 +30,7 @@ class ReferringType(StrEnum):
 type RefKey = Tuple[str, Optional[str], Optional[str]]
 
 
-class ArticleRef(CensoredAble, Display, ProposedUpdateAble):
+class ArticleRef(CensoredAble, ProposedUpdateAble):
     """Reference to a specific chapter, section or subsection within the article. You SHALL not refer to an article component that is external and not present within our own article.
 
     Examples:
@@ -120,25 +121,7 @@ class ArticleMetaData(CensoredAble, Display):
     """Do not add any prefix or suffix to the title. should not contain special characters."""
 
 
-class Patch[T](ProposedUpdateAble, Display):
-    """Base class for patches."""
-
-    tweaked: List[T]
-    """Tweaked content list"""
-
-    def update_from_inner(self, other: Self) -> Self:
-        """Updates the current instance with the attributes of another instance."""
-        self.tweaked.clear()
-        self.tweaked.extend(other.tweaked)
-        return self
-
-    @classmethod
-    def default(cls) -> Self:
-        """Defaults to empty list."""
-        return cls(tweaked=[])
-
-
-class ArticleRefPatch(Patch[ArticleRef]):
+class ArticleRefSequencePatch(SequencePatch[ArticleRef]):
     """Patch for article refs."""
 
 

fabricatio/models/extra/article_main.py

@@ -8,14 +8,13 @@ from fabricatio.models.extra.article_base import (
     ArticleBase,
     ArticleOutlineBase,
     ChapterBase,
-    Patch,
     SectionBase,
     SubSectionBase,
 )
 from fabricatio.models.extra.article_outline import (
     ArticleOutline,
 )
-from fabricatio.models.generic import CensoredAble, Display, PersistentAble, WithRef
+from fabricatio.models.generic import CensoredAble, Display, PersistentAble, SequencePatch, WithRef
 from fabricatio.utils import ok
 
 
@@ -32,7 +31,7 @@ class Paragraph(CensoredAble):
     """The actual content of the paragraph, represented as a string."""
 
 
-class ArticleParagraphPatch(Patch[Paragraph]):
+class ArticleParagraphSequencePatch(SequencePatch[Paragraph]):
     """Patch for `Paragraph` list of `ArticleSubsection`."""
 
 

fabricatio/models/extra/patches.py

@@ -0,0 +1,7 @@
+"""A patch class for updating the description and name of a `WithBriefing` object."""
+
+from fabricatio.models.generic import Patch, WithBriefing
+
+
+class BriefingPatch[T:WithBriefing](Patch[T], WithBriefing):
+    """Patch class for updating the description and name of a `WithBriefing` object."""

fabricatio/models/extra/problem.py

@@ -1,14 +1,16 @@
 """A class representing a problem-solution pair identified during a review process."""
 
-from typing import List, Literal, Self
+from itertools import chain
+from typing import List, Literal, Optional, Self
 
-from fabricatio.models.generic import Display, ProposedAble, ProposedUpdateAble, WithBriefing
+from fabricatio.journal import logger
+from fabricatio.models.generic import SketchedAble, WithBriefing
 from fabricatio.utils import ask_edit
 from questionary import Choice, checkbox, text
 from rich import print as r_print
 
 
-class Problem(ProposedAble, WithBriefing, Display):
+class Problem(SketchedAble, WithBriefing):
     """Represents a problem identified during review."""
 
     description: str
@@ -27,11 +29,14 @@ class Problem(ProposedAble, WithBriefing, Display):
     """Recommended solution or action."""
 
 
-class Solution(ProposedAble, WithBriefing, Display):
+class Solution(SketchedAble, WithBriefing):
     """Represents a proposed solution to a problem."""
 
-    operation: str
-    """Description or identifier of the operation."""
+    description: str
+    """Description of the solution, including a detailed description of the execution steps, and the mechanics, principle or fact."""
+
+    execute_steps: List[str]
+    """A list of steps to execute to implement the solution, which is expected to be able to finally solve the corresponding problem."""
 
     feasibility: Literal["low", "medium", "high"]
     """Feasibility level of the solution."""
@@ -40,7 +45,7 @@ class Solution(ProposedAble, WithBriefing, Display):
     """Impact level of the solution."""
 
 
-class ProblemSolutions(ProposedUpdateAble):
+class ProblemSolutions(SketchedAble):
     """Represents a problem-solution pair identified during a review process."""
 
     problem: Problem
@@ -78,10 +83,26 @@ class ProblemSolutions(ProposedUpdateAble):
         self.solutions = [Solution.model_validate_strings(s) for s in string_seq]
         return self
 
+    def decided(self) -> bool:
+        """Check if the improvement is decided."""
+        return len(self.solutions) == 1
+
+    def final_solution(self) -> Optional[Solution]:
+        """Get the final solution."""
+        if not self.decided():
+            logger.error(
+                f"There is more than one solution for problem {self.problem.name}, please decide which solution is eventually adopted."
+            )
+            return None
+        return self.solutions[0]
+
 
-class Improvement(ProposedAble, Display):
+class Improvement(SketchedAble):
     """A class representing an improvement suggestion."""
 
+    focused_on: str
+    """The focused on topic of the improvement"""
+
     problem_solutions: List[ProblemSolutions]
     """Collection of problems identified during review along with their potential solutions."""
 
@@ -118,3 +139,15 @@ class Improvement(ProposedAble, Display):
             await to_exam.edit_solutions()
 
         return self
+
+    def decided(self) -> bool:
+        """Check if the improvement is decided."""
+        return all(ps.decided() for ps in self.problem_solutions)
+
+    @classmethod
+    def gather(cls, *improvements: Self) -> Self:
+        """Gather multiple improvements into a single instance."""
+        return cls(
+            focused_on="\n".join(imp.focused_on for imp in improvements),
+            problem_solutions=list(chain(*(imp.problem_solutions for imp in improvements))),
+        )

fabricatio/models/extra/rule.py

@@ -2,7 +2,7 @@
 
 from typing import List
 
-from fabricatio.models.generic import Described, Display, PersistentAble, ProposedAble, WithBriefing
+from fabricatio.models.generic import Display, PersistentAble, ProposedAble, WithBriefing
 
 
 class Rule(WithBriefing,ProposedAble,Display):
@@ -14,10 +14,8 @@ class Rule(WithBriefing,ProposedAble,Display):
     """Examples of how to comply with the rule."""
 
 
-class RuleSet(ProposedAble, Display, PersistentAble, Described):
+class RuleSet(ProposedAble, Display, PersistentAble, WithBriefing):
     """Represents a collection of rules and guidelines for a particular topic."""
 
-    title: str
-    """The title of the rule set."""
     rules: List[Rule]
     """The rules and guidelines contained in the rule set."""

fabricatio/models/generic.py

@@ -54,6 +54,11 @@ class Display(Base):
         """
         return self.model_dump_json()
 
+    @staticmethod
+    def seq_display(seq: Iterable["Display"], compact: bool = False) -> str:
+        """Display a sequence of Display objects in a formatted JSON string."""
+        return "\n".join(d.compact() if compact else d.display() for d in seq)
+
 
 class Named(Base):
     """Class that includes a name attribute."""
@@ -136,7 +141,7 @@ class PersistentAble(Base):
             Self: The current instance of the object.
         """
         p = Path(path)
-        out = rtoml.dumps(self.model_dump())
+        out = self.model_dump_json()
 
         # Generate a timestamp in the format YYYYMMDD_HHMMSS
         timestamp = datetime.now().strftime("%Y%m%d")
@@ -166,7 +171,7 @@ class PersistentAble(Base):
         Returns:
             Self: The current instance of the object.
         """
-        return cls.model_validate(rtoml.load(path))
+        return cls.model_validate_json(safe_text_read(path))
 
 
 class ModelHash(Base):
@@ -309,14 +314,20 @@ class InstantiateFromString(Base):
         Returns:
             Self | None: The instance of the class or None if the string is not valid.
         """
-        return JsonCapture.convert_with(string, cls.model_validate_json)
+        obj = JsonCapture.convert_with(string, cls.model_validate_json)
+        logger.debug(f"Instantiate `{cls.__name__}` from string, {'Failed' if obj is None else 'Success'}.")
+        return obj
 
 
 class ProposedAble(CreateJsonObjPrompt, InstantiateFromString):
     """Class that provides a method to propose a JSON object based on the requirement."""
 
 
-class ProposedUpdateAble(ProposedAble, UpdateFrom, ABC):
+class SketchedAble(ProposedAble, Display):
+    """Class that provides a method to scratch the object."""
+
+
+class ProposedUpdateAble(SketchedAble, UpdateFrom, ABC):
     """Make the obj can be updated from the proposed obj in place."""
 
 
@@ -344,8 +355,6 @@ class FinalizedDumpAble(Base):
         return self
 
 
-class CensoredAble(ProposedAble, FinalizedDumpAble):
-    """Class that provides a method to censor the object."""
 
 
 class WithDependency(Base):
@@ -567,3 +576,33 @@ class ScopedConfig(Base):
                 if (attr := getattr(self, attr_name)) is not None and getattr(other, attr_name) is None:
                     setattr(other, attr_name, attr)
         return self
+
+
+class Patch[T](ProposedAble):
+    """Base class for patches."""
+
+    def apply(self, other: T) -> T:
+        """Apply the patch to another instance."""
+        for field in self.__class__.model_fields:
+            if not hasattr(other, field):
+                raise ValueError(f"{field} not found in {other}, are you applying to the wrong type?")
+            setattr(other, field, getattr(self, field))
+        return other
+
+
+class SequencePatch[T](ProposedUpdateAble):
+    """Base class for patches."""
+
+    tweaked: List[T]
+    """Tweaked content list"""
+
+    def update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance."""
+        self.tweaked.clear()
+        self.tweaked.extend(other.tweaked)
+        return self
+
+    @classmethod
+    def default(cls) -> Self:
+        """Defaults to empty list."""
+        return cls(tweaked=[])

fabricatio/models/kwargs_types.py

@@ -1,7 +1,7 @@
 """This module contains the types for the keyword arguments of the methods in the models module."""
 
 from importlib.util import find_spec
-from typing import Any, Dict, Required, TypedDict
+from typing import Any, Dict, List, Optional, Required, TypedDict
 
 from litellm.caching.caching import CacheMode
 from litellm.types.caching import CachingSupportedCallTypes
@@ -95,11 +95,30 @@ class ValidateKwargs[T](GenerateKwargs, total=False):
     such as limiting the number of validation attempts.
     """
 
-    default: T
+    default: Optional[T]
     max_validations: int
     co_extractor: GenerateKwargs
 
 
+class CompositeScoreKwargs(ValidateKwargs[List[Dict[str, float]]], total=False):
+    """Arguments for composite score generation operations.
+
+    Extends GenerateKwargs with parameters for generating composite scores
+    based on specific criteria and weights.
+    """
+
+    topic: str
+    criteria: set[str]
+    weights: Dict[str, float]
+    manual: Dict[str, str]
+
+
+class BestKwargs(CompositeScoreKwargs, total=False):
+    """Arguments for choose top-k operations."""
+
+    k: int
+
+
 class ReviewInnerKwargs[T](ValidateKwargs[T], total=False):
     """Arguments for content review operations."""
 
@@ -118,22 +137,9 @@ class ReviewKwargs[T](ReviewInnerKwargs[T], total=False):
     topic: Required[str]
 
 
-class CorrectKwargs[T](ReviewKwargs[T], total=False):
-    """Arguments for content correction operations.
-
-    Extends GenerateKwargs with parameters for correcting content based on
-    specific criteria and templates.
-    """
-
-    reference: str
-    supervisor_check: bool
-
-
-class CensoredCorrectKwargs[T](ReviewInnerKwargs[T], total=False):
-    """Arguments for content censorship operations."""
-
+class ReferencedKwargs[T](ValidateKwargs[T], total=False):
+    """Arguments for content review operations."""
     reference: str
-    supervisor_check: bool
 
 
 # noinspection PyTypedDict