fabricatio 0.2.4.dev3__cp312-cp312-win_amd64.whl → 0.2.5__cp312-cp312-win_amd64.whl

fabricatio/capabilities/rating.py

@@ -1,15 +1,14 @@
 """A module that provides functionality to rate tasks based on a rating manual and score range."""
 
-from asyncio import gather
 from itertools import permutations
-from typing import Dict, List, Set, Tuple, Union, Unpack, overload
+from random import sample
+from typing import Dict, List, Optional, Set, Tuple, Union, Unpack, overload
 
-import orjson
 from fabricatio._rust_instances import template_manager
 from fabricatio.config import configs
 from fabricatio.journal import logger
 from fabricatio.models.generic import WithBriefing
-from fabricatio.models.kwargs_types import GenerateKwargs, ValidateKwargs
+from fabricatio.models.kwargs_types import ValidateKwargs
 from fabricatio.models.usages import LLMUsage
 from fabricatio.parser import JsonCapture
 from more_itertools import flatten, windowed
@@ -17,15 +16,19 @@ from pydantic import NonNegativeInt, PositiveInt
 
 
 class GiveRating(WithBriefing, LLMUsage):
-    """A class that provides functionality to rate tasks based on a rating manual and score range."""
+    """A class that provides functionality to rate tasks based on a rating manual and score range.
+
+    References:
+        Lu X, Li J, Takeuchi K, et al. AHP-powered LLM reasoning for multi-criteria evaluation of open-ended responses[A/OL]. arXiv, 2024. DOI: 10.48550/arXiv.2410.01246.
+    """
 
     async def rate_fine_grind(
         self,
-        to_rate: str,
+        to_rate: str | List[str],
         rating_manual: Dict[str, str],
         score_range: Tuple[float, float],
-        **kwargs: Unpack[ValidateKwargs],
-    ) -> Dict[str, float]:
+        **kwargs: Unpack[ValidateKwargs[Dict[str, float]]],
+    ) -> Optional[Dict[str, float] | List[Dict[str, float]]]:
         """Rate a given string based on a rating manual and score range.
 
         Args:
@@ -40,10 +43,8 @@ class GiveRating(WithBriefing, LLMUsage):
 
         def _validator(response: str) -> Dict[str, float] | None:
             if (
-                (json_data := JsonCapture.convert_with(response, orjson.loads)) is not None
-                and isinstance(json_data, dict)
+                (json_data := JsonCapture.validate_with(response, dict, str))
                 and json_data.keys() == rating_manual.keys()
-                and all(isinstance(v, float) for v in json_data.values())
                 and all(score_range[0] <= v <= score_range[1] for v in json_data.values())
             ):
                 return json_data
@@ -61,9 +62,21 @@ class GiveRating(WithBriefing, LLMUsage):
                         "rating_manual": rating_manual,
                     },
                 )
-            ),
+            )
+            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,
+                    },
+                )
+                for item in to_rate
+            ],
             validator=_validator,
-            system_message=f"# your personal briefing: \n{self.briefing}",
             **kwargs,
         )
 
@@ -94,7 +107,7 @@ class GiveRating(WithBriefing, LLMUsage):
         criteria: Set[str],
         score_range: Tuple[float, float] = (0.0, 1.0),
         **kwargs: Unpack[ValidateKwargs],
-    ) -> Union[Dict[str, float], List[Dict[str, float]]]:
+    ) -> Optional[Dict[str, float] | List[Dict[str, float]]]:
         """Rate a given string or a sequence of strings based on a topic, criteria, and score range.
 
         Args:
@@ -108,16 +121,13 @@ class GiveRating(WithBriefing, 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)
-        if isinstance(to_rate, str):
-            return await self.rate_fine_grind(to_rate, manual, score_range, **kwargs)
-        if isinstance(to_rate, list):
-            return await gather(*[self.rate_fine_grind(item, manual, score_range, **kwargs) for item in to_rate])
-        raise ValueError("to_rate must be a string or a list of strings")
+        manual = await self.draft_rating_manual(topic, criteria, **kwargs) or dict(zip(criteria, criteria, strict=True))
+
+        return await self.rate_fine_grind(to_rate, manual, score_range, **kwargs)
 
     async def draft_rating_manual(
-        self, topic: str, criteria: Set[str], **kwargs: Unpack[ValidateKwargs]
-    ) -> Dict[str, str]:
+        self, topic: str, criteria: Set[str], **kwargs: Unpack[ValidateKwargs[Dict[str, str]]]
+    ) -> Optional[Dict[str, str]]:
         """Drafts a rating manual based on a topic and dimensions.
 
         Args:
@@ -149,16 +159,15 @@ class GiveRating(WithBriefing, LLMUsage):
                 )
             ),
             validator=_validator,
-            system_message=f"# your personal briefing: \n{self.briefing}",
-            **kwargs,
+            **self.prepend(kwargs),
         )
 
     async def draft_rating_criteria(
         self,
         topic: str,
         criteria_count: NonNegativeInt = 0,
-        **kwargs: Unpack[ValidateKwargs],
-    ) -> Set[str]:
+        **kwargs: Unpack[ValidateKwargs[Set[str]]],
+    ) -> Optional[Set[str]]:
         """Drafts rating dimensions based on a topic.
 
         Args:
@@ -169,16 +178,6 @@ class GiveRating(WithBriefing, LLMUsage):
         Returns:
             Set[str]: A set of rating dimensions.
         """
-
-        def _validator(response: str) -> Set[str] | None:
-            if (
-                json_data := JsonCapture.validate_with(
-                    response, target_type=list, elements_type=str, length=criteria_count
-                )
-            ) is not None:
-                return set(json_data)
-            return None
-
         return await self.aask_validate(
             question=(
                 template_manager.render_template(
@@ -189,19 +188,21 @@ class GiveRating(WithBriefing, LLMUsage):
                     },
                 )
             ),
-            validator=_validator,
-            system_message=f"# your personal briefing: \n{self.briefing}",
-            **kwargs,
+            validator=lambda resp: set(out)
+            if (out := JsonCapture.validate_with(resp, list, str, criteria_count)) is not None
+            else out,
+            **self.prepend(kwargs),
         )
 
     async def draft_rating_criteria_from_examples(
         self,
         topic: str,
         examples: List[str],
+        m: NonNegativeInt = 0,
         reasons_count: PositiveInt = 2,
         criteria_count: PositiveInt = 5,
         **kwargs: Unpack[ValidateKwargs],
-    ) -> Set[str]:
+    ) -> Optional[Set[str]]:
         """Asynchronously drafts a set of rating criteria based on provided examples.
 
         This function generates rating criteria by analyzing examples and extracting reasons for comparison,
@@ -210,18 +211,25 @@ class GiveRating(WithBriefing, LLMUsage):
         Parameters:
             topic (str): The subject topic for the rating criteria.
             examples (List[str]): A list of example texts to analyze.
+            m (NonNegativeInt, optional): The number of examples to sample from the provided list. Defaults to 0 (no sampling).
             reasons_count (PositiveInt, optional): The number of reasons to extract from each pair of examples. Defaults to 2.
             criteria_count (PositiveInt, optional): The final number of rating criteria to draft. Defaults to 5.
             **kwargs (Unpack[ValidateKwargs]): Additional keyword arguments for validation.
 
         Returns:
             Set[str]: A set of drafted rating criteria.
+
+        Warnings:
+            Since this function uses pairwise comparisons, it may not be suitable for large lists of examples.
+            For that reason, consider using a smaller list of examples or setting `m` to a non-zero value smaller than the length of the examples.
         """
-        kwargs = GenerateKwargs(system_message=f"# your personal briefing: \n{self.briefing}", **kwargs)
+        if m:
+            examples = sample(examples, m)
+
         # extract reasons from the comparison of ordered pairs of extracted from examples
         reasons = flatten(
-            await self.aask_validate_batch(
-                questions=[
+            await self.aask_validate(
+                question=[
                     template_manager.render_template(
                         configs.templates.extract_reasons_from_examples_template,
                         {
@@ -236,7 +244,7 @@ class GiveRating(WithBriefing, LLMUsage):
                 validator=lambda resp: JsonCapture.validate_with(
                     resp, target_type=list, elements_type=str, length=reasons_count
                 ),
-                **kwargs,
+                **self.prepend(kwargs),
             )
         )
         # extract certain mount of criteria from reasons according to their importance and frequency
@@ -261,7 +269,7 @@ class GiveRating(WithBriefing, LLMUsage):
         self,
         topic: str,
         criteria: Set[str],
-        **kwargs: Unpack[ValidateKwargs],
+        **kwargs: Unpack[ValidateKwargs[float]],
     ) -> Dict[str, float]:
         """Drafts rating weights for a given topic and criteria using the Klee method.
 
@@ -276,12 +284,12 @@ class GiveRating(WithBriefing, LLMUsage):
         if len(criteria) < 2:  # noqa: PLR2004
             raise ValueError("At least two criteria are required to draft rating weights")
 
-        criteria = list(criteria)  # freeze the order
-        windows = windowed(criteria, 2)
+        criteria_seq = list(criteria)  # freeze the order
+        windows = windowed(criteria_seq, 2)
 
         # get the importance multiplier indicating how important is second criterion compared to the first one
-        relative_weights = await self.aask_validate_batch(
-            questions=[
+        relative_weights = await self.aask_validate(
+            question=[
                 template_manager.render_template(
                     configs.templates.draft_rating_weights_klee_template,
                     {
@@ -293,13 +301,13 @@ class GiveRating(WithBriefing, LLMUsage):
                 for pair in windows
             ],
             validator=lambda resp: JsonCapture.validate_with(resp, target_type=float),
-            **GenerateKwargs(system_message=f"# your personal briefing: \n{self.briefing}", **kwargs),
+            **self.prepend(kwargs),
         )
         weights = [1]
         for rw in relative_weights:
             weights.append(weights[-1] * rw)
         total = sum(weights)
-        return dict(zip(criteria, [w / total for w in weights], strict=True))
+        return dict(zip(criteria_seq, [w / total for w in weights], strict=True))
 
     async def composite_score(
         self,

fabricatio/capabilities/review.py

@@ -0,0 +1,241 @@
+"""A module that provides functionality to rate tasks based on a rating manual and score range."""
+
+from typing import List, Optional, Self, Set, Unpack, cast
+
+from fabricatio import template_manager
+from fabricatio.capabilities.propose import Propose
+from fabricatio.capabilities.rating import GiveRating
+from fabricatio.config import configs
+from fabricatio.models.generic import Base, Display, ProposedAble, WithBriefing
+from fabricatio.models.kwargs_types import ReviewKwargs, ValidateKwargs
+from fabricatio.models.task import Task
+from questionary import Choice, checkbox
+from rich import print
+
+
+class ProblemSolutions(Base):
+    """Represents a problem-solution pair identified during a review process.
+
+    This class encapsulates a single problem with its corresponding potential solutions,
+    providing a structured way to manage review findings.
+
+    Attributes:
+        problem (str): The problem statement identified during review.
+        solutions (List[str]): A collection of potential solutions to address the problem.
+    """
+
+    problem: str
+    """The problem identified in the review."""
+    solutions: List[str]
+    """A collection of potential solutions to address the problem."""
+
+    def update_problem(self, problem: str) -> Self:
+        """Update the problem description.
+
+        Args:
+            problem (str): The new problem description to replace the current one.
+
+        Returns:
+            Self: The current instance with updated problem description.
+        """
+        self.problem = problem
+        return self
+
+    def update_solutions(self, solutions: List[str]) -> Self:
+        """Update the list of potential solutions.
+
+        Args:
+            solutions (List[str]): The new collection of solutions to replace the current ones.
+
+        Returns:
+            Self: The current instance with updated solutions.
+        """
+        self.solutions = solutions
+        return self
+
+
+class ReviewResult[T](ProposedAble, Display):
+    """Represents the outcome of a review process with identified problems and solutions.
+
+    This class maintains a structured collection of problems found during a review,
+    their proposed solutions, and a reference to the original reviewed object.
+
+    Attributes:
+        review_topic (str): The subject or focus area of the review.
+        problem_solutions (List[ProblemSolutions]): Collection of problems identified
+            during review along with their potential solutions.
+
+    Type Parameters:
+        T: The type of the object being reviewed.
+    """
+
+    review_topic: str
+    """The subject or focus area of the review."""
+
+    problem_solutions: List[ProblemSolutions]
+    """Collection of problems identified during review along with their potential solutions."""
+
+    _ref: T
+    """Reference to the original object that was reviewed."""
+
+    def update_topic(self, topic: str) -> Self:
+        """Update the review topic.
+
+        Args:
+            topic (str): The new topic to be associated with this review.
+
+        Returns:
+            Self: The current instance with updated review topic.
+        """
+        self.review_topic = topic
+        return self
+
+    def update_ref[K](self, ref: K) -> "ReviewResult[K]":
+        """Update the reference to the reviewed object.
+
+        Args:
+            ref (K): The new reference object to be associated with this review.
+
+        Returns:
+            ReviewResult[K]: The current instance with updated reference type.
+        """
+        self._ref = ref  # pyright: ignore [reportAttributeAccessIssue]
+        return cast(ReviewResult[K], self)
+
+    def deref(self) -> T:
+        """Retrieve the referenced object that was reviewed.
+
+        Returns:
+            T: The original object that was reviewed.
+        """
+        return self._ref
+
+    async def supervisor_check(self, check_solutions: bool = False) -> Self:
+        """Perform an interactive review session to filter problems and solutions.
+
+        Presents an interactive prompt allowing a supervisor to select which
+        problems (and optionally solutions) should be retained in the final review.
+
+        Args:
+            check_solutions (bool, optional): When True, also prompts for filtering
+                individual solutions for each retained problem. Defaults to False.
+
+        Returns:
+            Self: The current instance with filtered problems and solutions.
+        """
+        if isinstance(self._ref, str):
+            display = self._ref
+        elif isinstance(self._ref, WithBriefing):
+            display = self._ref.briefing
+        elif isinstance(self._ref, Display):
+            display = self._ref.display()
+        else:
+            raise TypeError(f"Unsupported type for review: {type(self._ref)}")
+        # Choose the problems to retain
+        print(display)
+        chosen_ones: List[ProblemSolutions] = await checkbox(
+            f"Please choose the problems you want to retain.(Default: retain all)\n\t`{self.review_topic}`",
+            choices=[Choice(p.problem, p, checked=True) for p in self.problem_solutions],
+        ).ask_async()
+        if not check_solutions:
+            self.problem_solutions = chosen_ones
+            return self
+
+        # Choose the solutions to retain
+        for to_exam in chosen_ones:
+            to_exam.update_solutions(
+                await checkbox(
+                    f"Please choose the solutions you want to retain.(Default: retain all)\n\t`{to_exam.problem}`",
+                    choices=[Choice(s, s, checked=True) for s in to_exam.solutions],
+                ).ask_async()
+            )
+        return self
+
+
+class Review(GiveRating, Propose):
+    """Class that provides functionality to review tasks and strings using a language model.
+
+    This class extends GiveRating and Propose capabilities to analyze content,
+    identify problems, and suggest solutions based on specified criteria.
+
+    The review process can be applied to Task objects or plain strings with
+    appropriate topic and criteria.
+    """
+
+    async def review_task[T](self, task: Task[T], **kwargs: Unpack[ReviewKwargs]) -> ReviewResult[Task[T]]:
+        """Review a task using specified review criteria.
+
+        This method analyzes a task object to identify problems and propose solutions
+        based on the criteria provided in kwargs.
+
+        Args:
+            task (Task[T]): The task object to be reviewed.
+            **kwargs (Unpack[ReviewKwargs]): Additional keyword arguments for the review process,
+                including topic and optional criteria.
+
+        Returns:
+            ReviewResult[Task[T]]: A review result containing identified problems and proposed solutions,
+                with a reference to the original task.
+        """
+        return cast(ReviewResult[Task[T]], await self.review_obj(task, **kwargs))
+
+    async def review_string(
+        self,
+        text: str,
+        topic: str,
+        criteria: Optional[Set[str]] = None,
+        **kwargs: Unpack[ValidateKwargs[ReviewResult[str]]],
+    ) -> ReviewResult[str]:
+        """Review a string based on specified topic and criteria.
+
+        This method analyzes a text string to identify problems and propose solutions
+        based on the given topic and criteria.
+
+        Args:
+            text (str): The text content to be reviewed.
+            topic (str): The subject topic for the review criteria.
+            criteria (Optional[Set[str]], optional): A set of criteria for the review.
+                If not provided, criteria will be drafted automatically. Defaults to None.
+            **kwargs (Unpack[ValidateKwargs]): Additional keyword arguments for the LLM usage.
+
+        Returns:
+            ReviewResult[str]: A review result containing identified problems and proposed solutions,
+                with a reference to the original text.
+        """
+        criteria = criteria or (await self.draft_rating_criteria(topic))
+        manual = await self.draft_rating_manual(topic, criteria)
+        res: ReviewResult[str] = await self.propose(
+            ReviewResult,
+            template_manager.render_template(
+                configs.templates.review_string_template, {"text": text, "topic": topic, "criteria_manual": manual}
+            ),
+            **kwargs,
+        )
+        return res.update_ref(text).update_topic(topic)
+
+    async def review_obj[M: (Display, WithBriefing)](self, obj: M, **kwargs: Unpack[ReviewKwargs]) -> ReviewResult[M]:
+        """Review an object that implements Display or WithBriefing interface.
+
+        This method extracts displayable text from the object and performs a review
+        based on the criteria provided in kwargs.
+
+        Args:
+            obj (M): The object to be reviewed, which must implement either Display or WithBriefing.
+            **kwargs (Unpack[ReviewKwargs]): Additional keyword arguments for the review process,
+                including topic and optional criteria.
+
+        Raises:
+            TypeError: If the object does not implement Display or WithBriefing.
+
+        Returns:
+            ReviewResult[M]: A review result containing identified problems and proposed solutions,
+                with a reference to the original object.
+        """
+        if isinstance(obj, Display):
+            text = obj.display()
+        elif isinstance(obj, WithBriefing):
+            text = obj.briefing
+        else:
+            raise TypeError(f"Unsupported type for review: {type(obj)}")
+
+        return (await self.review_string(text, **kwargs)).update_ref(obj)

fabricatio/capabilities/task.py

@@ -1,7 +1,7 @@
 """A module for the task capabilities of the Fabricatio library."""
 
 from types import CodeType
-from typing import Any, Dict, List, Optional, Tuple, Unpack
+from typing import Any, Dict, List, Optional, Tuple, Unpack, cast
 
 import orjson
 from fabricatio._rust_instances import template_manager
@@ -22,7 +22,7 @@ class ProposeTask(WithBriefing, Propose):
     async def propose_task[T](
         self,
         prompt: str,
-        **kwargs: Unpack[ValidateKwargs],
+        **kwargs: Unpack[ValidateKwargs[Task[T]]],
     ) -> Task[T]:
         """Asynchronously proposes a task based on a given prompt and parameters.
 
@@ -37,7 +37,7 @@ class ProposeTask(WithBriefing, Propose):
             logger.error(err := f"{self.name}: Prompt must be provided.")
             raise ValueError(err)
 
-        return await self.propose(Task, prompt, system_message=f"# your personal briefing: \n{self.briefing}", **kwargs)
+        return await self.propose(Task, prompt, **self.prepend(cast(Dict[str, Any], kwargs)))
 
 
 class HandleTask(WithBriefing, ToolBoxUsage):
@@ -49,7 +49,7 @@ class HandleTask(WithBriefing, ToolBoxUsage):
         tools: List[Tool],
         data: Dict[str, Any],
         **kwargs: Unpack[ValidateKwargs],
-    ) -> Tuple[CodeType, List[str]]:
+    ) -> Optional[Tuple[CodeType, List[str]]]:
         """Asynchronously drafts the tool usage code for a task based on a given task object and tools."""
         logger.info(f"Drafting tool usage code for task: {task.briefing}")
 
@@ -81,8 +81,7 @@ class HandleTask(WithBriefing, ToolBoxUsage):
         return await self.aask_validate(
             question=q,
             validator=_validator,
-            system_message=f"# your personal briefing: \n{self.briefing}",
-            **kwargs,
+            **self.prepend(cast(Dict[str, Any], kwargs)),
         )
 
     async def handle_fin_grind(
@@ -99,10 +98,10 @@ class HandleTask(WithBriefing, ToolBoxUsage):
         tools = await self.gather_tools_fine_grind(task, box_choose_kwargs, tool_choose_kwargs)
         logger.info(f"{self.name} have gathered {[t.name for t in tools]}")
 
-        if tools:
+        if tools and (pack := await self.draft_tool_usage_code(task, tools, data, **kwargs)):
             executor = ToolExecutor(candidates=tools, data=data)
-            code, to_extract = await self.draft_tool_usage_code(task, tools, data, **kwargs)
 
+            code, to_extract = pack
             cxt = executor.execute(code)
             if to_extract:
                 return tuple(cxt.get(k) for k in to_extract)

fabricatio/config.py

@@ -1,8 +1,10 @@
 """Configuration module for the Fabricatio application."""
 
+from pathlib import Path
 from typing import List, Literal, Optional
 
 from appdirs import user_config_dir
+from litellm.types.caching import LiteLLMCacheType
 from pydantic import (
     BaseModel,
     ConfigDict,
@@ -25,6 +27,8 @@ from pydantic_settings import (
     TomlConfigSettingsSource,
 )
 
+from fabricatio.models.kwargs_types import CacheKwargs
+
 ROAMING_DIR = user_config_dir("fabricatio", "", roaming=True)
 
 
@@ -64,7 +68,7 @@ class LLMConfig(BaseModel):
     temperature: NonNegativeFloat = Field(default=1.0)
     """The temperature of the LLM model. Controls randomness in generation. Set to 1.0 as per request."""
 
-    stop_sign: str | List[str] = Field(default=("\n\n\n", "User:"))
+    stop_sign: str | List[str] = Field(default_factory=lambda :["\n\n\n", "User:"])
     """The stop sign of the LLM model. No default stop sign specified."""
 
     top_p: NonNegativeFloat = Field(default=0.35)
@@ -140,7 +144,7 @@ class DebugConfig(BaseModel):
     log_level: Literal["DEBUG", "INFO", "SUCCESS", "WARNING", "ERROR", "CRITICAL"] = Field(default="INFO")
     """The log level of the application."""
 
-    log_file: FilePath = Field(default=rf"{ROAMING_DIR}\fabricatio.log")
+    log_file: FilePath = Field(default=Path(rf"{ROAMING_DIR}\fabricatio.log"))
     """The log file of the application."""
 
     rotation: int = Field(default=1)
@@ -158,7 +162,7 @@ class TemplateConfig(BaseModel):
 
     model_config = ConfigDict(use_attribute_docstrings=True)
     template_dir: List[DirectoryPath] = Field(
-        default_factory=lambda: [DirectoryPath(r".\templates"), DirectoryPath(rf"{ROAMING_DIR}\templates")]
+        default_factory=lambda: [Path(r".\templates"), Path(rf"{ROAMING_DIR}\templates")]
     )
     """The directory containing the templates."""
     active_loading: bool = Field(default=False)
@@ -212,6 +216,12 @@ class TemplateConfig(BaseModel):
     refined_query_template: str = Field(default="refined_query")
     """The name of the refined query template which will be used to refine a query."""
 
+    pathstr_template: str = Field(default="pathstr")
+    """The name of the pathstr template which will be used to acquire a path of strings."""
+
+    review_string_template: str = Field(default="review_string")
+    """The name of the review string template which will be used to review a string."""
+
 
 class MagikaConfig(BaseModel):
     """Magika configuration class."""
@@ -225,12 +235,15 @@ class GeneralConfig(BaseModel):
     """Global configuration class."""
 
     model_config = ConfigDict(use_attribute_docstrings=True)
-    workspace: DirectoryPath = Field(default=DirectoryPath(r"."))
+    workspace: DirectoryPath = Field(default=Path())
     """The workspace directory for the application."""
 
     confirm_on_ops: bool = Field(default=True)
     """Whether to confirm on operations."""
 
+    use_json_repair: bool = Field(default=True)
+    """Whether to use JSON repair."""
+
 
 class ToolBoxConfig(BaseModel):
     """Toolbox configuration class."""
@@ -259,6 +272,19 @@ class RagConfig(BaseModel):
     """The dimensions of the Milvus server."""
 
 
+class CacheConfig(BaseModel):
+    """cache configuration class, uses litellm as cache backend. more info see https://docs.litellm.ai/docs/caching/all_caches."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+    type: Optional[LiteLLMCacheType] = None
+    """The type of cache to use. If None, the default cache type will be used."""
+    params: CacheKwargs = Field(default_factory=CacheKwargs)
+    """The parameters for the cache. If type is None, the default parameters will be used."""
+    enabled: bool = Field(default=False)
+    """Whether to enable cache."""
+
+
 class Settings(BaseSettings):
     """Application settings class.
 
@@ -308,6 +334,9 @@ class Settings(BaseSettings):
     rag: RagConfig = Field(default_factory=RagConfig)
     """RAG Configuration"""
 
+    cache: CacheConfig = Field(default_factory=CacheConfig)
+    """Cache Configuration"""
+
     @classmethod
     def settings_customise_sources(
         cls,

fabricatio/fs/__init__.py

@@ -1,14 +1,26 @@
 """FileSystem manipulation module for Fabricatio."""
 
-from fabricatio.fs.curd import copy_file, create_directory, delete_directory, delete_file, dump_text, move_file, tree
+from fabricatio.fs.curd import (
+    absolute_path,
+    copy_file,
+    create_directory,
+    delete_directory,
+    delete_file,
+    dump_text,
+    gather_files,
+    move_file,
+    tree,
+)
 from fabricatio.fs.readers import magika, safe_json_read, safe_text_read
 
 __all__ = [
+    "absolute_path",
     "copy_file",
     "create_directory",
     "delete_directory",
     "delete_file",
     "dump_text",
+    "gather_files",
     "magika",
     "move_file",
     "safe_json_read",