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

fabricatio/capabilities/correct.py

@@ -1,160 +1,222 @@
-"""Correct capability module providing advanced review and validation functionality.
+"""A module containing the Correct capability for reviewing, validating, and improving objects."""
 
-This module implements the Correct capability, which extends the Review functionality
-to provide mechanisms for reviewing, validating, and correcting various objects and tasks
-based on predefined criteria and templates.
-"""
+from asyncio import gather
+from typing import Optional, Type, Unpack, cast
 
-from typing import Optional, Unpack, cast
-
-from fabricatio._rust_instances import TEMPLATE_MANAGER
-from fabricatio.capabilities.review import Review
+from fabricatio.capabilities.propose import Propose
+from fabricatio.capabilities.rating import Rating
 from fabricatio.config import configs
-from fabricatio.models.extra.problem import Improvement
-from fabricatio.models.generic import CensoredAble, Display, ProposedAble, ProposedUpdateAble, WithBriefing
-from fabricatio.models.kwargs_types import CensoredCorrectKwargs, CorrectKwargs, ReviewKwargs
-from fabricatio.models.task import Task
-from questionary import confirm, text
-from rich import print as rprint
+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_instances import TEMPLATE_MANAGER
+from fabricatio.utils import fallback_kwargs, ok, override_kwargs
+
+
+class Correct(Rating, Propose):
+    """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
 
-class Correct(Review):
-    """Correct capability for reviewing, validating, and improving objects.
+    async def decide_improvement(self, improvement: Improvement, **kwargs: Unpack[BestKwargs]) -> Improvement:
+        """Decide the best solution for each problem solution in an improvement.
 
-    This class enhances the Review capability with specialized functionality for
-    correcting and improving objects based on review feedback. It can process
-    various inputs including tasks, strings, and generic objects that implement
-    the required interfaces, applying corrections based on templated review processes.
-    """
+        Args:
+            improvement (Improvement): The improvement containing problem solutions to evaluate.
+            **kwargs (Unpack[BestKwargs]): Additional keyword arguments for the decision process.
 
-    async def correct_obj[M: ProposedAble](
+        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 = "",
-        supervisor_check: bool = True,
-        **kwargs: Unpack[ReviewKwargs[Improvement]],
+        **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.
+        """Fix a troubled object based on problem solutions.
 
         Args:
-            obj (M): The object to be reviewed and corrected. Must implement ProposedAble.
+            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.
-            supervisor_check (bool, optional): Whether to perform a supervisor check on the review results. Defaults to True.
-            **kwargs: Review configuration parameters including criteria and review options.
+            **kwargs (Unpack[ValidateKwargs[M]]): Additional keyword arguments for the validation process.
 
         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.
+            Optional[M]: The fixed object, or None if fixing fails.
         """
-        if not isinstance(obj, (Display, WithBriefing)):
-            raise TypeError(f"Expected Display or WithBriefing, got {type(obj)}")
-
-        review_res = await self.review_obj(obj, **kwargs)
-        if supervisor_check:
-            await review_res.supervisor_check()
-        if "default" in kwargs:
-            cast("ReviewKwargs[None]", kwargs)["default"] = None
         return await self.propose(
-            obj.__class__,
+            cast("Type[M]", obj.__class__),
             TEMPLATE_MANAGER.render_template(
-                configs.templates.correct_template,
+                configs.templates.fix_troubled_obj_template,
                 {
-                    "content": f"{(reference + '\n\nAbove is referencing material') if reference else ''}{obj.display() if isinstance(obj, Display) else obj.briefing}",
-                    "review": review_res.display(),
+                    "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 correct_string(
-        self, input_text: str, supervisor_check: bool = True, **kwargs: Unpack[ReviewKwargs[Improvement]]
+    async def fix_troubled_string(
+        self,
+        input_text: str,
+        problem_solutions: ProblemSolutions,
+        reference: str = "",
+        **kwargs: Unpack[ValidateKwargs[str]],
     ) -> Optional[str]:
-        """Review and correct a string based on defined criteria and templates.
-
-        This method applies the review process to the input text and generates
-        a corrected version based on the review results.
+        """Fix a troubled string based on problem solutions.
 
         Args:
-            input_text (str): The text content to be reviewed and corrected.
-            supervisor_check (bool, optional): Whether to perform a supervisor check on the review results. Defaults to True.
-            **kwargs: Review configuration parameters including criteria and review options.
+            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 corrected text content, or None if correction fails.
+            Optional[str]: The fixed string, or None if fixing fails.
         """
-        review_res = await self.review_string(input_text, **kwargs)
-        if supervisor_check:
-            await review_res.supervisor_check()
-
-        if "default" in kwargs:
-            cast("ReviewKwargs[None]", kwargs)["default"] = None
         return await self.ageneric_string(
             TEMPLATE_MANAGER.render_template(
-                configs.templates.correct_template, {"content": input_text, "review": review_res.display()}
+                configs.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_task[T](
-        self, task: Task[T], **kwargs: Unpack[CorrectKwargs[Improvement]]
-    ) -> Optional[Task[T]]:
-        """Review and correct a task object based on defined criteria.
+    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 is a specialized version of correct_obj specifically for Task objects,
-        applying the same review and correction process to task definitions.
+        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:
-            task (Task[T]): The task to be reviewed and corrected.
-            **kwargs: Review configuration parameters including criteria and review options.
+            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[Task[T]]: The corrected task, or None if correction fails.
+            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.
         """
-        return await self.correct_obj(task, **kwargs)
+        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 censor_obj[M: CensoredAble](
-        self, obj: M, **kwargs: Unpack[CensoredCorrectKwargs[Improvement]]
-    ) -> M:
-        """Censor and correct an object based on defined criteria and templates.
+    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:
-            obj (M): The object to be reviewed and corrected.
-            **kwargs (Unpack[CensoredCorrectKwargs]): Additional keyword
+            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:
-            M: The censored and corrected object.
+            Optional[str]: A corrected version of the input string, or None if correction fails.
         """
-        last_modified_obj = obj
-        modified_obj = None
-        rprint(obj.finalized_dump())
-        while await confirm("Begin to correct obj above with human censorship?").ask_async():
-            while (topic := await text("What is the topic of the obj reviewing?").ask_async()) is not None and topic:
-                ...
-            if (
-                modified_obj := await self.correct_obj(
-                    last_modified_obj,
-                    topic=topic,
-                    **kwargs,
+        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}",
                 )
-            ) is None:
-                break
-            last_modified_obj = modified_obj
-            rprint(last_modified_obj.finalized_dump())
-        return modified_obj or last_modified_obj
+                return None
+            input_text = fixed_string
+        return input_text
 
     async def correct_obj_inplace[M: ProposedUpdateAble](
-        self, obj: M, **kwargs: Unpack[CorrectKwargs[Improvement]]
+        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[CensoredCorrectKwargs]): Additional keyword arguments for the correction process.
+            **kwargs (Unpack[CorrectKwargs[M]]): Additional keyword arguments for the correction process.
 
         Returns:
             Optional[M]: The corrected object, or None if correction fails.

fabricatio/capabilities/rag.py

@@ -3,14 +3,16 @@
 try:
     from pymilvus import MilvusClient
 except ImportError as e:
-    raise RuntimeError("pymilvus is not installed. Have you installed `fabricatio[rag]` instead of `fabricatio`") from e
+    raise RuntimeError("pymilvus is not installed. Have you installed `fabricatio[rag]` instead of `fabricatio`?") from e
 from functools import lru_cache
 from operator import itemgetter
 from os import PathLike
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Self, Union, Unpack, cast, overload
 
-from fabricatio._rust_instances import TEMPLATE_MANAGER
+from more_itertools.recipes import flatten, unique
+from pydantic import Field, PrivateAttr
+
 from fabricatio.config import configs
 from fabricatio.journal import logger
 from fabricatio.models.kwargs_types import (
@@ -23,9 +25,8 @@ from fabricatio.models.kwargs_types import (
 )
 from fabricatio.models.usages import EmbeddingUsage
 from fabricatio.models.utils import MilvusData
+from fabricatio.rust_instances import TEMPLATE_MANAGER
 from fabricatio.utils import ok
-from more_itertools.recipes import flatten, unique
-from pydantic import Field, PrivateAttr
 
 
 @lru_cache(maxsize=None)

fabricatio/capabilities/rating.py

@@ -4,18 +4,20 @@ from itertools import permutations
 from random import sample
 from typing import Dict, List, Optional, Set, Tuple, Union, Unpack, overload
 
-from fabricatio._rust_instances import TEMPLATE_MANAGER
+from more_itertools import flatten, windowed
+from pydantic import Field, NonNegativeInt, PositiveInt, create_model
+
+from fabricatio.capabilities.propose import Propose
 from fabricatio.config import configs
 from fabricatio.journal import logger
-from fabricatio.models.kwargs_types import ValidateKwargs
-from fabricatio.models.usages import LLMUsage
+from fabricatio.models.generic import Display, ProposedAble
+from fabricatio.models.kwargs_types import CompositeScoreKwargs, ValidateKwargs
 from fabricatio.parser import JsonCapture
-from fabricatio.utils import override_kwargs
-from more_itertools import flatten, windowed
-from pydantic import NonNegativeInt, PositiveInt
+from fabricatio.rust_instances import TEMPLATE_MANAGER
+from fabricatio.utils import fallback_kwargs, ok, override_kwargs
 
 
-class Rating(LLMUsage):
+class Rating(Propose):
     """A class that provides functionality to rate tasks based on a rating manual and score range.
 
     References:
@@ -28,7 +30,7 @@ class Rating(LLMUsage):
         rating_manual: Dict[str, str],
         score_range: Tuple[float, float],
         **kwargs: Unpack[ValidateKwargs[Dict[str, float]]],
-    ) -> Optional[Dict[str, float] | List[Dict[str, float]]]:
+    ) -> Dict[str, float] | List[Dict[str, float]] | List[Optional[Dict[str, float]]] | None:
         """Rate a given string based on a rating manual and score range.
 
         Args:
@@ -40,45 +42,49 @@ class Rating(LLMUsage):
         Returns:
             Dict[str, float]: A dictionary with the ratings for each dimension.
         """
-
-        def _validator(response: str) -> Dict[str, float] | None:
-            if (
-                (json_data := JsonCapture.validate_with(response, dict, str))
-                and json_data.keys() == rating_manual.keys()
-                and all(score_range[0] <= v <= score_range[1] for v in json_data.values())
-            ):
-                return json_data
-            return None
-
-        logger.info(f"Rating for {to_rate}")
-        return await self.aask_validate(
-            question=(
-                TEMPLATE_MANAGER.render_template(
-                    configs.templates.rate_fine_grind_template,
-                    {
-                        "to_rate": to_rate,
-                        "min_score": score_range[0],
-                        "max_score": score_range[1],
-                        "rating_manual": rating_manual,
-                    },
+        min_score, max_score = score_range
+        tip = (max_score - min_score) / 9
+
+        model = create_model(  # pyright: ignore [reportCallIssue]
+            "RatingResult",
+            __base__=ProposedAble,
+            __doc__=f"The rating result contains the scores against each criterion, with min_score={min_score} and max_score={max_score}.",
+            **{  # pyright: ignore [reportArgumentType]
+                criterion: (
+                    float,
+                    Field(
+                        ge=min_score,
+                        le=max_score,
+                        description=desc,
+                        examples=[round(min_score + tip * i, 2) for i in range(10)],
+                    ),
                 )
+                for criterion, desc in rating_manual.items()
+            },
+        )
+
+        res = await self.propose(
+            model,
+            TEMPLATE_MANAGER.render_template(
+                configs.templates.rate_fine_grind_template,
+                {"to_rate": to_rate, "min_score": min_score, "max_score": max_score},
             )
             if isinstance(to_rate, str)
             else [
                 TEMPLATE_MANAGER.render_template(
                     configs.templates.rate_fine_grind_template,
-                    {
-                        "to_rate": item,
-                        "min_score": score_range[0],
-                        "max_score": score_range[1],
-                        "rating_manual": rating_manual,
-                    },
+                    {"to_rate": t, "min_score": min_score, "max_score": max_score},
                 )
-                for item in to_rate
+                for t in to_rate
             ],
-            validator=_validator,
-            **kwargs,
+            **override_kwargs(kwargs, default=None),
         )
+        default = kwargs.get("default")
+        if isinstance(res, list):
+            return [r.model_dump() if r else default for r in res]
+        if res is None:
+            return default
+        return res.model_dump()
 
     @overload
     async def rate(
@@ -86,6 +92,7 @@ class Rating(LLMUsage):
         to_rate: str,
         topic: str,
         criteria: Set[str],
+        manual: Optional[Dict[str, str]] = None,
         score_range: Tuple[float, float] = (0.0, 1.0),
         **kwargs: Unpack[ValidateKwargs],
     ) -> Dict[str, float]: ...
@@ -96,6 +103,7 @@ class Rating(LLMUsage):
         to_rate: List[str],
         topic: str,
         criteria: Set[str],
+        manual: Optional[Dict[str, str]] = None,
         score_range: Tuple[float, float] = (0.0, 1.0),
         **kwargs: Unpack[ValidateKwargs],
     ) -> List[Dict[str, float]]: ...
@@ -105,15 +113,17 @@ class Rating(LLMUsage):
         to_rate: Union[str, List[str]],
         topic: str,
         criteria: Set[str],
+        manual: Optional[Dict[str, str]] = None,
         score_range: Tuple[float, float] = (0.0, 1.0),
         **kwargs: Unpack[ValidateKwargs],
-    ) -> Optional[Dict[str, float] | List[Dict[str, float]]]:
+    ) -> Dict[str, float] | List[Dict[str, float]] | List[Optional[Dict[str, float]]] | None:
         """Rate a given string or a sequence of strings based on a topic, criteria, and score range.
 
         Args:
             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,9 +131,13 @@ 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)
+        return await self.rate_fine_grind(to_rate, manual, score_range, **fallback_kwargs(kwargs, co_extractor={}))
 
     async def draft_rating_manual(
         self, topic: str, criteria: Optional[Set[str]] = None, **kwargs: Unpack[ValidateKwargs[Dict[str, str]]]
@@ -160,7 +174,7 @@ class Rating(LLMUsage):
                     configs.templates.draft_rating_manual_template,
                     {
                         "topic": topic,
-                        "criteria": criteria,
+                        "criteria": list(criteria),
                     },
                 )
             ),
@@ -234,7 +248,7 @@ class Rating(LLMUsage):
 
         # extract reasons from the comparison of ordered pairs of extracted from examples
         reasons = flatten(
-            await self.aask_validate(
+            await self.aask_validate(  # pyright: ignore [reportArgumentType]
                 question=[
                     TEMPLATE_MANAGER.render_template(
                         configs.templates.extract_reasons_from_examples_template,
@@ -309,9 +323,11 @@ class Rating(LLMUsage):
             validator=lambda resp: JsonCapture.validate_with(resp, target_type=float),
             **kwargs,
         )
-        weights = [1]
+        if not all(relative_weights):
+            raise ValueError(f"found illegal weight: {relative_weights}")
+        weights = [1.0]
         for rw in relative_weights:
-            weights.append(weights[-1] * rw)
+            weights.append(weights[-1] * rw)  # pyright: ignore [reportOperatorIssue]
         total = sum(weights)
         return dict(zip(criteria_seq, [w / total for w in weights], strict=True))
 
@@ -319,27 +335,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/capabilities/review.py

@@ -2,7 +2,6 @@
 
 from typing import Dict, Optional, Set, Unpack
 
-from fabricatio._rust_instances import TEMPLATE_MANAGER
 from fabricatio.capabilities.propose import Propose
 from fabricatio.capabilities.rating import Rating
 from fabricatio.config import configs
@@ -10,6 +9,7 @@ from fabricatio.models.extra.problem import Improvement
 from fabricatio.models.generic import Display, WithBriefing
 from fabricatio.models.kwargs_types import ReviewKwargs, ValidateKwargs
 from fabricatio.models.task import Task
+from fabricatio.rust_instances import TEMPLATE_MANAGER
 from fabricatio.utils import ok