fabricatio 0.2.5.dev1__cp312-cp312-manylinux_2_34_x86_64.whl → 0.2.5.dev3__cp312-cp312-manylinux_2_34_x86_64.whl

fabricatio/_rust.pyi

@@ -2,60 +2,101 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 class TemplateManager:
-    """TemplateManager class for managing handlebars templates."""
+    """Template rendering engine using Handlebars templates.
+
+    This manager handles template discovery, loading, and rendering
+    through a wrapper around the handlebars-rust engine.
+
+    See: https://crates.io/crates/handlebars
+    """
     def __init__(
         self, template_dirs: List[Path], suffix: Optional[str] = None, active_loading: Optional[bool] = None
     ) -> None:
         """Initialize the template manager.
 
         Args:
-            template_dirs (List[Path]): A list of paths to directories containing templates.
-            suffix (str, optional): The suffix of template files. None means 'hbs' suffix.
-            active_loading (bool, optional): Whether to enable active loading of templates.
+            template_dirs: List of directories containing template files
+            suffix: File extension for templates (defaults to 'hbs')
+            active_loading: Whether to enable dev mode for reloading templates on change
         """
 
     @property
     def template_count(self) -> int:
-        """Get the number of templates discovered."""
+        """Returns the number of currently loaded templates."""
 
     def get_template_source(self, name: str) -> Optional[str]:
-        """Get the source path of a template by name.
+        """Get the filesystem path for a template.
 
         Args:
-            name (str): The name of the template to retrieve.
+            name: Template name (without extension)
 
         Returns:
-            Optional[str]: The source path of the template.
+            Path to the template file if found, None otherwise
         """
 
     def discover_templates(self) -> None:
-        """Discover templates in the specified directories."""
+        """Scan template directories and load available templates.
+
+        This refreshes the template cache, finding any new or modified templates.
+        """
 
     def render_template(self, name: str, data: Dict[str, Any]) -> str:
-        """Render a template with the given name and data.
+        """Render a template with context data.
 
         Args:
-            name (str): The name of the template to render.
-            data (Dict[str, Any]): The data to pass to the template.
+            name: Template name (without extension)
+            data: Context dictionary to provide variables to the template
 
         Returns:
-            str: The rendered template.
+            Rendered template content as string
+
+        Raises:
+            RuntimeError: If template rendering fails
         """
 
 def blake3_hash(content: bytes) -> str:
-    """Calculate the BLAKE3 hash of the given data.
+    """Calculate the BLAKE3 cryptographic hash of data.
 
     Args:
-        content (bytes): The data to hash.
+        content: Bytes to be hashed
 
     Returns:
-        str: The BLAKE3 hash of the data.
+        Hex-encoded BLAKE3 hash string
     """
 
 class BibManager:
-    """BibManager class for managing BibTeX files."""
+    """BibTeX bibliography manager for parsing and querying citation data."""
+
     def __init__(self, path: str) -> None:
-        """Initialize the BibManager with the given path."""
+        """Initialize the bibliography manager.
+
+        Args:
+            path: Path to BibTeX (.bib) file to load
+
+        Raises:
+            RuntimeError: If file cannot be read or parsed
+        """
+
+    def get_cite_key(self, title: str) -> Optional[str]:
+        """Find citation key by exact title match.
 
-    def get_cite_key(self, title: str) -> str:
-        """Get the cite key for the given title."""
+        Args:
+            title: Full title to search for (case-insensitive)
+
+        Returns:
+            Citation key if exact match found, None otherwise
+        """
+
+    def get_cite_key_fuzzy(self, query: str) -> Optional[str]:
+        """Find best matching citation using fuzzy text search.
+
+        Args:
+            query: Search term to find in bibliography entries
+
+        Returns:
+            Citation key of best matching entry, or None if no good match
+
+        Notes:
+            Uses nucleo_matcher for high-quality fuzzy text searching
+            See: https://crates.io/crates/nucleo-matcher
+        """

fabricatio/_rust_instances.py

@@ -1,3 +1,5 @@
+"""Some necessary instances."""
+
 from fabricatio._rust import TemplateManager
 from fabricatio.config import configs
 

fabricatio/capabilities/propose.py

@@ -15,7 +15,7 @@ class Propose[M: ProposedAble](LLMUsage):
         self,
         cls: Type[M],
         prompt: List[str],
-        **kwargs: Unpack[GenerateKwargs],
+        **kwargs: Unpack[GenerateKwargs[M]],
     ) -> List[M]: ...
 
     @overload
@@ -23,14 +23,14 @@ class Propose[M: ProposedAble](LLMUsage):
         self,
         cls: Type[M],
         prompt: str,
-        **kwargs: Unpack[GenerateKwargs],
+        **kwargs: Unpack[GenerateKwargs[M]],
     ) -> M: ...
 
     async def propose(
         self,
         cls: Type[M],
         prompt: List[str] | str,
-        **kwargs: Unpack[GenerateKwargs],
+        **kwargs: Unpack[GenerateKwargs[M]],
     ) -> List[M] | M:
         """Asynchronously proposes a task based on a given prompt and parameters.
 

fabricatio/capabilities/rating.py

@@ -2,9 +2,9 @@
 
 from asyncio import gather
 from itertools import permutations
+from random import sample
 from typing import Dict, List, Set, Tuple, Union, Unpack, overload
 
-from cache import AsyncLRU
 from fabricatio._rust_instances import template_manager
 from fabricatio.config import configs
 from fabricatio.journal import logger
@@ -17,7 +17,11 @@ 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,
@@ -113,7 +117,6 @@ class GiveRating(WithBriefing, LLMUsage):
             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")
 
-    @AsyncLRU(maxsize=32)
     async def draft_rating_manual(
         self, topic: str, criteria: Set[str], **kwargs: Unpack[ValidateKwargs]
     ) -> Dict[str, str]:
@@ -189,6 +192,7 @@ class GiveRating(WithBriefing, LLMUsage):
         self,
         topic: str,
         examples: List[str],
+        m: NonNegativeInt = 0,
         reasons_count: PositiveInt = 2,
         criteria_count: PositiveInt = 5,
         **kwargs: Unpack[ValidateKwargs],
@@ -201,13 +205,21 @@ 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.
         """
+        if m:
+            examples = sample(examples, m)
+
         kwargs = GenerateKwargs(system_message=f"# your personal briefing: \n{self.briefing}", **kwargs)
         # extract reasons from the comparison of ordered pairs of extracted from examples
         reasons = flatten(

fabricatio/capabilities/review.py

@@ -1,60 +1,157 @@
 """A module that provides functionality to rate tasks based on a rating manual and score range."""
 
-from typing import List, Optional, Set, Unpack
+from typing import List, Optional, Self, Set, Unpack
 
 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 Display, ProposedAble, WithBriefing
+from fabricatio.models.generic import Base, Display, ProposedAble, WithBriefing
 from fabricatio.models.kwargs_types import GenerateKwargs, ReviewKwargs
 from fabricatio.models.task import Task
 from pydantic import PrivateAttr
+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):
-    """Class that represents the result of a review.
+    """Represents the outcome of a review process with identified problems and solutions.
 
-    This class holds the problems identified in a review and their proposed solutions,
-    along with a reference to the reviewed object.
+    This class maintains a structured collection of problems found during a review,
+    their proposed solutions, and a reference to the original reviewed object.
 
     Attributes:
-        existing_problems (List[str]): List of problems identified in the review.
-        proposed_solutions (List[str]): List of proposed solutions to the problems identified in the review.
+        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.
     """
 
-    existing_problems: List[str]
-    """List of problems identified in the review."""
+    review_topic: str
+    """The subject or focus area of the review."""
 
-    proposed_solutions: List[str]
-    """List of proposed solutions to the problems identified in the review."""
+    problem_solutions: List[ProblemSolutions]
+    """Collection of problems identified during review along with their potential solutions."""
 
     _ref: T = PrivateAttr(None)
-    """Reference to the object being reviewed."""
+    """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 object being reviewed.
+        """Update the reference to the reviewed object.
 
         Args:
-            ref (K): The new reference to the object being reviewed.
+            ref (K): The new reference object to be associated with this review.
 
         Returns:
-            ReviewResult[K]: The updated instance of the ReviewResult class with the new reference type.
+            ReviewResult[K]: The current instance with updated reference type.
         """
         self._ref = ref
         return self
 
     def deref(self) -> T:
-        """Dereference the object being reviewed.
+        """Retrieve the referenced object that was reviewed.
 
         Returns:
-            T: The object being reviewed.
+            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.
@@ -84,7 +181,11 @@ class Review(GiveRating, Propose):
         return await self.review_obj(task, **kwargs)
 
     async def review_string(
-        self, text: str, topic: str, criteria: Optional[Set[str]] = None, **kwargs: Unpack[GenerateKwargs]
+        self,
+        text: str,
+        topic: str,
+        criteria: Optional[Set[str]] = None,
+        **kwargs: Unpack[GenerateKwargs[ReviewResult[str]]],
     ) -> ReviewResult[str]:
         """Review a string based on specified topic and criteria.
 
@@ -111,7 +212,7 @@ class Review(GiveRating, Propose):
             ),
             **kwargs,
         )
-        return res.update_ref(text)
+        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.

fabricatio/config.py

@@ -3,6 +3,7 @@
 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 +26,8 @@ from pydantic_settings import (
     TomlConfigSettingsSource,
 )
 
+from fabricatio.models.kwargs_types import CacheKwargs
+
 ROAMING_DIR = user_config_dir("fabricatio", "", roaming=True)
 
 
@@ -265,6 +268,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.
 
@@ -314,6 +330,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

@@ -7,6 +7,7 @@ from fabricatio.fs.curd import (
     delete_directory,
     delete_file,
     dump_text,
+    gather_files,
     move_file,
     tree,
 )
@@ -19,6 +20,7 @@ __all__ = [
     "delete_directory",
     "delete_file",
     "dump_text",
+    "gather_files",
     "magika",
     "move_file",
     "safe_json_read",

fabricatio/fs/curd.py

@@ -134,3 +134,16 @@ def absolute_path(path: str | Path | PathLike) -> str:
         str: The absolute path of the file or directory.
     """
     return Path(path).expanduser().resolve().as_posix()
+
+
+def gather_files(directory: str | Path | PathLike, extension: str) -> list[str]:
+    """Gather all files with a specific extension in a directory.
+
+    Args:
+        directory (str, Path, PathLike): The directory to search in.
+        extension (str): The file extension to look for.
+
+    Returns:
+        list[str]: A list of file paths with the specified extension.
+    """
+    return [file.as_posix() for file in Path(directory).rglob(f"*.{extension}")]

fabricatio/journal.py

@@ -18,7 +18,6 @@ logger.add(
 )
 logger.add(sys.stderr, level=configs.debug.log_level)
 
-
 if __name__ == "__main__":
     logger.debug("This is a trace message.")
     logger.info("This is an information message.")

fabricatio/models/action.py

@@ -122,17 +122,16 @@ class WorkFlow(WithBriefing, ToolBoxUsage):
         current_action = None
         try:
             for step in self._instances:
-                logger.debug(f"Executing step: {step.name}")
+                logger.debug(f"Executing step: {(current_action := step.name)}")
                 act_task = create_task(step.act(await self._context.get()))
                 if task.is_cancelled():
                     act_task.cancel(f"Cancelled by task: {task.name}")
                     break
                 modified_ctx = await act_task
                 await self._context.put(modified_ctx)
-                current_action = step.name
             logger.info(f"Finished executing workflow: {self.name}")
-            final_ctx = await self._context.get()
-            if self.task_output_key not in final_ctx:
+
+            if self.task_output_key not in (final_ctx := await self._context.get()):
                 logger.warning(
                     f"Task output key: {self.task_output_key} not found in the context, None will be returned. You can check if `Action.output_key` is set the same as `WorkFlow.task_output_key`."
                 )

fabricatio/models/kwargs_types.py

@@ -1,19 +1,28 @@
 """This module contains the types for the keyword arguments of the methods in the models module."""
 
-from typing import List, NotRequired, Set, TypedDict
+from typing import Any, List, NotRequired, Set, TypedDict
 
+from litellm.caching.caching import CacheMode
+from litellm.types.caching import CachingSupportedCallTypes
 from pydantic import NonNegativeFloat, NonNegativeInt, PositiveInt
 
 
 class CollectionSimpleConfigKwargs(TypedDict):
-    """A type representing the configuration for a collection."""
+    """Configuration parameters for a vector collection.
+
+    These arguments are typically used when configuring connections to vector databases.
+    """
 
     dimension: NotRequired[int]
     timeout: NotRequired[float]
 
 
 class FetchKwargs(TypedDict):
-    """A type representing the keyword arguments for the fetch method."""
+    """Arguments for fetching data from vector collections.
+
+    Controls how data is retrieved from vector databases, including filtering
+    and result limiting parameters.
+    """
 
     collection_name: NotRequired[str]
     similarity_threshold: NotRequired[float]
@@ -21,7 +30,11 @@ class FetchKwargs(TypedDict):
 
 
 class EmbeddingKwargs(TypedDict):
-    """A type representing the keyword arguments for the embedding method."""
+    """Configuration parameters for text embedding operations.
+
+    These settings control the behavior of embedding models that convert text
+    to vector representations.
+    """
 
     model: NotRequired[str]
     dimensions: NotRequired[int]
@@ -30,7 +43,11 @@ class EmbeddingKwargs(TypedDict):
 
 
 class LLMKwargs(TypedDict):
-    """A type representing the keyword arguments for the LLM (Large Language Model) usage."""
+    """Configuration parameters for language model inference.
+
+    These arguments control the behavior of large language model calls,
+    including generation parameters and caching options.
+    """
 
     model: NotRequired[str]
     temperature: NotRequired[NonNegativeFloat]
@@ -40,28 +57,90 @@ class LLMKwargs(TypedDict):
     stream: NotRequired[bool]
     timeout: NotRequired[PositiveInt]
     max_retries: NotRequired[PositiveInt]
+    no_cache: NotRequired[bool]  # If use cache in this call
+    no_store: NotRequired[bool]  # If store the response of this call to cache
+    cache_ttl: NotRequired[int]  # how long the stored cache is alive, in seconds
+    s_maxage: NotRequired[int]  # max accepted age of cached response, in seconds
 
 
-class ValidateKwargs(LLMKwargs):
-    """A type representing the keyword arguments for the validate method."""
+class ValidateKwargs[T](LLMKwargs):
+    """Arguments for content validation operations.
 
+    Extends LLMKwargs with additional parameters specific to validation tasks,
+    such as limiting the number of validation attempts.
+    """
+
+    default: NotRequired[T]
     max_validations: NotRequired[PositiveInt]
 
 
 class GenerateKwargs(ValidateKwargs):
-    """A type representing the keyword arguments for the generate method."""
+    """Arguments for content generation operations.
+
+    Extends ValidateKwargs with parameters specific to text generation,
+    including system prompt configuration.
+    """
 
     system_message: NotRequired[str]
 
 
 class ReviewKwargs(GenerateKwargs):
-    """A type representing the keyword arguments for the review method."""
+    """Arguments for content review operations.
+
+    Extends GenerateKwargs with parameters for evaluating content against
+    specific topics and review criteria.
+    """
 
     topic: str
     criteria: NotRequired[Set[str]]
 
 
 class ChooseKwargs(GenerateKwargs):
-    """A type representing the keyword arguments for the choose method."""
+    """Arguments for selection operations.
+
+    Extends GenerateKwargs with parameters for selecting among options,
+    such as the number of items to choose.
+    """
 
     k: NotRequired[NonNegativeInt]
+
+
+class CacheKwargs(TypedDict, total=False):
+    """Configuration parameters for the caching system.
+
+    These arguments control the behavior of various caching backends,
+    including in-memory, Redis, S3, and vector database caching options.
+    """
+
+    mode: NotRequired[CacheMode]  # when default_on cache is always on, when default_off cache is opt in
+    host: NotRequired[str]
+    port: NotRequired[str]
+    password: NotRequired[str]
+    namespace: NotRequired[str]
+    ttl: NotRequired[float]
+    default_in_memory_ttl: NotRequired[float]
+    default_in_redis_ttl: NotRequired[float]
+    similarity_threshold: NotRequired[float]
+    supported_call_types: NotRequired[List[CachingSupportedCallTypes]]
+    # s3 Bucket, boto3 configuration
+    s3_bucket_name: NotRequired[str]
+    s3_region_name: NotRequired[str]
+    s3_api_version: NotRequired[str]
+    s3_use_ssl: NotRequired[bool]
+    s3_verify: NotRequired[bool | str]
+    s3_endpoint_url: NotRequired[str]
+    s3_aws_access_key_id: NotRequired[str]
+    s3_aws_secret_access_key: NotRequired[str]
+    s3_aws_session_token: NotRequired[str]
+    s3_config: NotRequired[Any]
+    s3_path: NotRequired[str]
+    redis_semantic_cache_use_async: bool
+    redis_semantic_cache_embedding_model: str
+    redis_flush_size: NotRequired[int]
+    redis_startup_nodes: NotRequired[List]
+    disk_cache_dir: Any
+    qdrant_api_base: NotRequired[str]
+    qdrant_api_key: NotRequired[str]
+    qdrant_collection_name: NotRequired[str]
+    qdrant_quantization_config: NotRequired[str]
+    qdrant_semantic_cache_embedding_model: str

fabricatio/models/role.py

@@ -15,7 +15,7 @@ from pydantic import Field
 class Role(ProposeTask, HandleTask, Review):
     """Class that represents a role with a registry of events and workflows."""
 
-    registry: dict[Event | str, WorkFlow] = Field(...)
+    registry: dict[Event | str, WorkFlow] = Field(default_factory=dict)
     """ The registry of events and workflows."""
 
     toolboxes: Set[ToolBox] = Field(default_factory=set)

fabricatio/models/usages.py

@@ -25,6 +25,10 @@ from litellm.utils import CustomStreamWrapper
 from more_itertools import duplicates_everseen
 from pydantic import Field, NonNegativeInt, PositiveInt
 
+if configs.cache.enabled:
+    litellm.enable_cache(type=configs.cache.type, **configs.cache.params)
+    logger.success(f"{configs.cache.type.name} Cache enabled")
+
 
 class LLMUsage(ScopedConfig):
     """Class that manages LLM (Large Language Model) usage parameters and methods."""
@@ -63,6 +67,12 @@ class LLMUsage(ScopedConfig):
             max_retries=kwargs.get("max_retries") or self.llm_max_retries or configs.llm.max_retries,
             api_key=(self.llm_api_key or configs.llm.api_key).get_secret_value(),
             base_url=(self.llm_api_endpoint or configs.llm.api_endpoint).unicode_string(),
+            cache={
+                "no-cache": kwargs.get("no_cache"),
+                "no-store": kwargs.get("no_store"),
+                "cache-ttl": kwargs.get("cache_ttl"),
+                "s-maxage": kwargs.get("s_maxage"),
+            },
         )
 
     async def ainvoke(
@@ -105,14 +115,14 @@ class LLMUsage(ScopedConfig):
     async def aask(
         self,
         question: List[str],
-        system_message: Optional[List[str]] = None,
+        system_message: List[str],
         **kwargs: Unpack[LLMKwargs],
     ) -> List[str]: ...
     @overload
     async def aask(
         self,
         question: str,
-        system_message: Optional[List[str]] = None,
+        system_message: List[str],
         **kwargs: Unpack[LLMKwargs],
     ) -> List[str]: ...
     @overload
@@ -148,52 +158,52 @@ class LLMUsage(ScopedConfig):
             str | List[str]: The content of the model's response message.
         """
         system_message = system_message or ""
-        match (isinstance(question, list), isinstance(system_message, list)):
-            case (True, True):
+        match (question, system_message):
+            case (list(q_seq), list(sm_seq)):
                 res = await gather(
                     *[
                         self.ainvoke(n=1, question=q, system_message=sm, **kwargs)
-                        for q, sm in zip(question, system_message, strict=True)
+                        for q, sm in zip(q_seq, sm_seq, strict=True)
                     ]
                 )
                 return [r.pop().message.content for r in res]
-            case (True, False):
-                res = await gather(
-                    *[self.ainvoke(n=1, question=q, system_message=system_message, **kwargs) for q in question]
-                )
+            case (list(q_seq), str(sm)):
+                res = await gather(*[self.ainvoke(n=1, question=q, system_message=sm, **kwargs) for q in q_seq])
                 return [r.pop().message.content for r in res]
-            case (False, True):
-                res = await gather(
-                    *[self.ainvoke(n=1, question=question, system_message=sm, **kwargs) for sm in system_message]
-                )
+            case (str(q), list(sm_seq)):
+                res = await gather(*[self.ainvoke(n=1, question=q, system_message=sm, **kwargs) for sm in sm_seq])
                 return [r.pop().message.content for r in res]
-            case (False, False):
-                return (
-                    (
-                        await self.ainvoke(
-                            n=1,
-                            question=question,
-                            system_message=system_message,
-                            **kwargs,
-                        )
-                    ).pop()
-                ).message.content
+            case (str(q), str(sm)):
+                return ((await self.ainvoke(n=1, question=q, system_message=sm, **kwargs)).pop()).message.content
             case _:
                 raise RuntimeError("Should not reach here.")
 
+    @overload
     async def aask_validate[T](
         self,
         question: str,
         validator: Callable[[str], T | None],
+        default: T,
         max_validations: PositiveInt = 2,
         system_message: str = "",
         **kwargs: Unpack[LLMKwargs],
-    ) -> T:
+    ) -> T: ...
+
+    async def aask_validate[T](
+        self,
+        question: str,
+        validator: Callable[[str], T | None],
+        default: Optional[T] = None,
+        max_validations: PositiveInt = 2,
+        system_message: str = "",
+        **kwargs: Unpack[LLMKwargs],
+    ) -> Optional[T]:
         """Asynchronously asks a question and validates the response using a given validator.
 
         Args:
             question (str): The question to ask.
             validator (Callable[[str], T | None]): A function to validate the response.
+            default (T | None): Default value to return if validation fails. Defaults to None.
             max_validations (PositiveInt): Maximum number of validation attempts. Defaults to 2.
             system_message (str): System message to include in the request. Defaults to an empty string.
             **kwargs (Unpack[LLMKwargs]): Additional keyword arguments for the LLM usage.
@@ -201,8 +211,6 @@ class LLMUsage(ScopedConfig):
         Returns:
             T: The validated response.
 
-        Raises:
-            ValueError: If the response fails to validate after the maximum number of attempts.
         """
         for i in range(max_validations):
             if (
@@ -214,14 +222,17 @@ class LLMUsage(ScopedConfig):
             ) and (validated := validator(response)):
                 logger.debug(f"Successfully validated the response at {i}th attempt.")
                 return validated
-        logger.error(err := f"Failed to validate the response after {max_validations} attempts.")
-        raise ValueError(err)
+            kwargs["no_cache"] = True
+            logger.debug("Closed the cache for the next attempt")
+        if default is None:
+            logger.error(f"Failed to validate the response after {max_validations} attempts.")
+        return default
 
     async def aask_validate_batch[T](
         self,
         questions: List[str],
         validator: Callable[[str], T | None],
-        **kwargs: Unpack[GenerateKwargs],
+        **kwargs: Unpack[GenerateKwargs[T]],
     ) -> List[T]:
         """Asynchronously asks a batch of questions and validates the responses using a given validator.
 
@@ -238,7 +249,9 @@ class LLMUsage(ScopedConfig):
         """
         return await gather(*[self.aask_validate(question, validator, **kwargs) for question in questions])
 
-    async def aliststr(self, requirement: str, k: NonNegativeInt = 0, **kwargs: Unpack[GenerateKwargs]) -> List[str]:
+    async def aliststr(
+        self, requirement: str, k: NonNegativeInt = 0, **kwargs: Unpack[GenerateKwargs[List[str]]]
+    ) -> List[str]:
         """Asynchronously generates a list of strings based on a given requirement.
 
         Args:
@@ -258,7 +271,7 @@ class LLMUsage(ScopedConfig):
             **kwargs,
         )
 
-    async def apathstr(self, requirement: str, **kwargs: Unpack[ChooseKwargs]) -> List[str]:
+    async def apathstr(self, requirement: str, **kwargs: Unpack[ChooseKwargs[List[str]]]) -> List[str]:
         """Asynchronously generates a list of strings based on a given requirement.
 
         Args:
@@ -276,7 +289,7 @@ class LLMUsage(ScopedConfig):
             **kwargs,
         )
 
-    async def awhich_pathstr(self, requirement: str, **kwargs: Unpack[GenerateKwargs]) -> str:
+    async def awhich_pathstr(self, requirement: str, **kwargs: Unpack[GenerateKwargs[List[str]]]) -> str:
         """Asynchronously generates a single path string based on a given requirement.
 
         Args:
@@ -299,7 +312,7 @@ class LLMUsage(ScopedConfig):
         instruction: str,
         choices: List[T],
         k: NonNegativeInt = 0,
-        **kwargs: Unpack[GenerateKwargs],
+        **kwargs: Unpack[GenerateKwargs[List[T]]],
     ) -> List[T]:
         """Asynchronously executes a multi-choice decision-making process, generating a prompt based on the instruction and options, and validates the returned selection results.
 
@@ -350,7 +363,7 @@ class LLMUsage(ScopedConfig):
         self,
         instruction: str,
         choices: List[T],
-        **kwargs: Unpack[GenerateKwargs],
+        **kwargs: Unpack[GenerateKwargs[List[T]]],
     ) -> T:
         """Asynchronously picks a single choice from a list of options using AI validation.
 
@@ -379,7 +392,7 @@ class LLMUsage(ScopedConfig):
         prompt: str,
         affirm_case: str = "",
         deny_case: str = "",
-        **kwargs: Unpack[GenerateKwargs],
+        **kwargs: Unpack[GenerateKwargs[bool]],
     ) -> bool:
         """Asynchronously judges a prompt using AI validation.
 
@@ -494,17 +507,13 @@ class ToolBoxUsage(LLMUsage):
         self,
         task: Task,
         system_message: str = "",
-        k: NonNegativeInt = 0,
-        max_validations: PositiveInt = 2,
-        **kwargs: Unpack[LLMKwargs],
+        **kwargs: Unpack[ChooseKwargs[List[ToolBox]]],
     ) -> List[ToolBox]:
         """Asynchronously executes a multi-choice decision-making process to choose toolboxes.
 
         Args:
             task (Task): The task for which to choose toolboxes.
             system_message (str): Custom system-level prompt, defaults to an empty string.
-            k (NonNegativeInt): The number of toolboxes to select, 0 means infinite. Defaults to 0.
-            max_validations (PositiveInt): Maximum number of validation failures, default is 2.
             **kwargs (Unpack[LLMKwargs]): Additional keyword arguments for the LLM usage.
 
         Returns:
@@ -514,10 +523,8 @@ class ToolBoxUsage(LLMUsage):
             logger.warning("No toolboxes available.")
             return []
         return await self.achoose(
-            instruction=task.briefing,  # TODO write a template to build a more robust instruction
+            instruction=task.briefing,
             choices=list(self.toolboxes),
-            k=k,
-            max_validations=max_validations,
             system_message=system_message,
             **kwargs,
         )
@@ -526,19 +533,13 @@ class ToolBoxUsage(LLMUsage):
         self,
         task: Task,
         toolbox: ToolBox,
-        system_message: str = "",
-        k: NonNegativeInt = 0,
-        max_validations: PositiveInt = 2,
-        **kwargs: Unpack[LLMKwargs],
+        **kwargs: Unpack[ChooseKwargs[List[Tool]]],
     ) -> List[Tool]:
         """Asynchronously executes a multi-choice decision-making process to choose tools.
 
         Args:
             task (Task): The task for which to choose tools.
             toolbox (ToolBox): The toolbox from which to choose tools.
-            system_message (str): Custom system-level prompt, defaults to an empty string.
-            k (NonNegativeInt): The number of tools to select, 0 means infinite. Defaults to 0.
-            max_validations (PositiveInt): Maximum number of validation failures, default is 2.
             **kwargs (Unpack[LLMKwargs]): Additional keyword arguments for the LLM usage.
 
         Returns:
@@ -548,11 +549,8 @@ class ToolBoxUsage(LLMUsage):
             logger.warning(f"No tools available in toolbox {toolbox.name}.")
             return []
         return await self.achoose(
-            instruction=task.briefing,  # TODO write a template to build a more robust instruction
+            instruction=task.briefing,
             choices=toolbox.tools,
-            k=k,
-            max_validations=max_validations,
-            system_message=system_message,
             **kwargs,
         )
 

fabricatio/toolboxes/fs.py

@@ -7,6 +7,7 @@ from fabricatio.fs import (
     delete_directory,
     delete_file,
     dump_text,
+    gather_files,
     move_file,
     safe_json_read,
     safe_text_read,
@@ -26,4 +27,5 @@ fs_toolbox = (
     .add_tool(absolute_path)
     .add_tool(safe_text_read)
     .add_tool(safe_json_read)
+    .add_tool(gather_files)
 )

{fabricatio-0.2.5.dev1.dist-info → fabricatio-0.2.5.dev3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fabricatio
-Version: 0.2.5.dev1
+Version: 0.2.5.dev3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3.12
@@ -9,7 +9,6 @@ Classifier: Framework :: AsyncIO
 Classifier: Framework :: Pydantic :: 2
 Classifier: Typing :: Typed
 Requires-Dist: appdirs>=1.4.4
-Requires-Dist: async-cache>=1.1.1
 Requires-Dist: asyncio>=3.4.3
 Requires-Dist: asyncstdlib>=3.13.0
 Requires-Dist: litellm>=1.60.0

{fabricatio-0.2.5.dev1.dist-info → fabricatio-0.2.5.dev3.dist-info}/RECORD

@@ -1,41 +1,41 @@
-fabricatio-0.2.5.dev1.dist-info/METADATA,sha256=PsgnEb4yQ2DY_hhyF2y3h0smp-IZwa49GxJb0Mftekc,8623
-fabricatio-0.2.5.dev1.dist-info/WHEEL,sha256=RIvmwLDYujv60MYBx2jxyP4vdn1DD7X0kBgz1TQvZuc,108
-fabricatio-0.2.5.dev1.dist-info/licenses/LICENSE,sha256=yDZaTLnOi03bi3Dk6f5IjhLUc5old2yOsihHWU0z-i0,1067
+fabricatio-0.2.5.dev3.dist-info/METADATA,sha256=MKx81GhYa4Kl5fyAn1CtYrdf_nWPZt-sq86I_iteWXE,8589
+fabricatio-0.2.5.dev3.dist-info/WHEEL,sha256=RIvmwLDYujv60MYBx2jxyP4vdn1DD7X0kBgz1TQvZuc,108
+fabricatio-0.2.5.dev3.dist-info/licenses/LICENSE,sha256=yDZaTLnOi03bi3Dk6f5IjhLUc5old2yOsihHWU0z-i0,1067
 fabricatio/decorators.py,sha256=cJHsxxbnMhc4SzPl4454CPLuDP3H0qbTrzV_U2rLPrs,6372
 fabricatio/core.py,sha256=MaEKZ6DDmbdScAY-7F1gwGA6fr7ADX6Mz5rNVi2msFA,6277
 fabricatio/models/generic.py,sha256=dP5rNf13Yo-Zy0WpmunsDYOxNbJF3RpFcVBTrYaHnvc,12197
 fabricatio/models/tool.py,sha256=m7gFo8nXywGj7J3zOfPC_wPUgcTY-76ZwAmHlQLWkb8,6836
-fabricatio/models/role.py,sha256=cmKhS_IVjvwkjusestEci_0F0hK0eCa_1Hl4U9vqhiY,1774
+fabricatio/models/role.py,sha256=Xd-TYNefcY9FGeINAI8Q5sCu2pgBXl0l9XKxN0r4rZ0,1791
 fabricatio/models/extra.py,sha256=svUxjM9iPtXCpNJwxYdkvRtvORsze8Fcz4Oql-46huQ,7295
-fabricatio/models/kwargs_types.py,sha256=_nycS6qG1geLmVR5Rh29w7bsANbYyPoI5n77AYO4nMQ,1935
+fabricatio/models/kwargs_types.py,sha256=3K7c72NYnqQ7aEs6tTninVb2670bNqiKdfUT7uzLjas,4769
 fabricatio/models/utils.py,sha256=vahILaesw50ofFft-wZ9kZ_Qogqi6vIOISWczvwVXxk,4311
-fabricatio/models/usages.py,sha256=bhRaAlqLSt7p3Khgot4uElo8C-hzVbwst3boeIIMpXo,26237
+fabricatio/models/usages.py,sha256=TBADSlnY70ewfXri3FbIPaD_jzgZz4dwMNEMJtWirxw,25845
 fabricatio/models/events.py,sha256=sBCKeNoYc4TFDoke-jhFEyA11RcdGu-wdF5ynAuVOMM,3983
 fabricatio/models/task.py,sha256=BdBfCtxzgDzqHE0eP65liUGRmddAtKhim6optodzEcQ,10193
-fabricatio/models/action.py,sha256=JgCjyddvY-YYnfQPdBwe7i-r4CJNTkGSMnuUW8666HQ,6326
-fabricatio/toolboxes/fs.py,sha256=0Uxbxj0kPYQ7srtP5eL_O-e83DBpNwEiaNLDu8ZsOug,659
+fabricatio/models/action.py,sha256=xAzNbkRMh8-6V-P9VwOgbc_hoFLcsXe7w0vcdSxmqhU,6285
+fabricatio/toolboxes/fs.py,sha256=OQMdeokYxSNVrCZJAweJ0cYiK4k2QuEiNdIbS5IHIV8,705
 fabricatio/toolboxes/__init__.py,sha256=dYm_Gd8XolSU_h4wnkA09dlaLDK146eeFz0CUgPZ8_c,380
 fabricatio/toolboxes/arithmetic.py,sha256=sSTPkKI6-mb278DwQKFO9jKyzc9kCx45xNH7V6bGBpE,1307
 fabricatio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 fabricatio/fs/readers.py,sha256=JNjTaHpH0ljXxJ7SREJYL5gU8bbCe3lDEaVCmna1rww,1168
-fabricatio/fs/curd.py,sha256=DjaL8_lROZVcPghC0U1u7mklLWFxbO9Vz1LWqp6aLl0,4010
-fabricatio/fs/__init__.py,sha256=kfE2e_ijOQtDND_GUBGWDEwtgcP5pYAymCgT0H3qh6M,521
-fabricatio/config.py,sha256=niQ2_IfIQXc6JV4Ff7Z3uGn2SdCEmdGne1lozKikp00,13641
-fabricatio/journal.py,sha256=bzxZay48ZWI0VIkkDXm4Wc_Cc9lBQYa2VGx3Hxy_PtA,753
+fabricatio/fs/curd.py,sha256=FuG75qco4dX8vhIK27gKz9rKUXbWHOFg5yK3nGLB25s,4469
+fabricatio/fs/__init__.py,sha256=iNYphupcebrXEKLG2MgLliEUlh_G6xmupqfVrUwGT9E,559
+fabricatio/config.py,sha256=tByDnt0HOthTOdEYK4KJwUqT74gJSVjUUxNOtc9Sa58,14422
+fabricatio/journal.py,sha256=HbqgbSMckpr8vNxNAR1k4EbRtpzVZDnWzvu9at0hhrc,752
 fabricatio/__init__.py,sha256=kr86hyEDgUbxl1KmWTJqmW1R-aeC8Hd4KFp-2HFr0LM,1870
 fabricatio/actions/output.py,sha256=0sKfU8C9y326IcgZMLeEoZZH3iMpgFGOLGoi9wYZz1U,663
 fabricatio/actions/rag.py,sha256=tP1uKLq7mo19YhsJzFbGYryrcMx6xcvBc3n_Wzh0hjg,796
 fabricatio/actions/article.py,sha256=-WKVYu1HrQOL5nyBraCvRG2bfbkTa_ylH_PyFSI6iLs,2704
-fabricatio/_rust_instances.py,sha256=JAtO-vL8ihvduf1SHLNf0w7ZSVGCJeIv6zZ9Ekyy1hY,271
+fabricatio/_rust_instances.py,sha256=CdvEQquLgXJ4slqYlqAYyBIzo3hiAmx1M98PIP2ajww,304
 fabricatio/workflows/articles.py,sha256=utvKDBFEJbcM76729-H2AvgMCNcsX1NquqMpHqGZq8E,565
 fabricatio/workflows/rag.py,sha256=uOZXprD479fUhLA6sYvEM8RWcVcUZXXtP0xRbTMPdHE,509
 fabricatio/parser.py,sha256=S-4p1mjvJZEgnQW6WKdkmE68MzqqWXGSiLbADdhE-W4,4791
 fabricatio/capabilities/rag.py,sha256=mGUWaVsLbA1vNe0LRdAOeUlR4WMc6mwuOQ0vhPG8m74,15181
-fabricatio/capabilities/rating.py,sha256=ZBlWbecHTAtRhO1beO4fWX3IfwjeyAYSvpXGIRhoGss,13384
-fabricatio/capabilities/review.py,sha256=rsUlKZzURibM33UxuqjgPgxlHcA1vEGvCb-sIeZO9Do,5725
-fabricatio/capabilities/propose.py,sha256=oW9QKpY2mDkVPEvgsgqxXxDR2ylVqN5TEL8E0Wh_vJI,1714
+fabricatio/capabilities/rating.py,sha256=_F8-t60W4EFHW62gPOFgys4oqAoXAVk442oz91P0z0c,14044
+fabricatio/capabilities/review.py,sha256=PoJZrPGq8FvqLjQELuWv1CCMcJMusuv6KZTl7Wv6_zE,9463
+fabricatio/capabilities/propose.py,sha256=fuQzwx6OBymEbHbHDDPoT4sqFRso8u6Kk7NXKS5DFVc,1723
 fabricatio/capabilities/task.py,sha256=BISAFbMgBI4udW0otE3-iyq0RXc05YN_30N0yI5qLxQ,4504
-fabricatio/_rust.pyi,sha256=tKI4o5ZsxcW4k-O5etU5s60TzjRgJArYxR2YUk7sqkE,1980
-fabricatio/_rust.cpython-312-x86_64-linux-gnu.so,sha256=1ySWosE-ZFyYk7EHHNApJ54x4Q5QgUY4aRrb92LgyLQ,1684256
-fabricatio-0.2.5.dev1.data/scripts/tdown,sha256=EP2gMfsbKrPyWPCx4itYrQqbhVaVpbCxoufK3IbXrTs,4568208
-fabricatio-0.2.5.dev1.dist-info/RECORD,,
+fabricatio/_rust.pyi,sha256=xXSaL7llihyFIyr9_k6e5RRJVNYk2jM-jrrheNvvaIA,3067
+fabricatio/_rust.cpython-312-x86_64-linux-gnu.so,sha256=X-d8ziGuBqQEtJXheq6NTFAsxotGLiy2it6rteu9Cic,1898944
+fabricatio-0.2.5.dev3.data/scripts/tdown,sha256=MsmVZJr1r5g1VXyayAS7DEtHgLj0O8a2YbGNf1u6SDw,4571832
+fabricatio-0.2.5.dev3.dist-info/RECORD,,