fabricatio 0.3.14.dev4__cp313-cp313-manylinux_2_34_x86_64.whl

fabricatio/capabilities/review.py

@@ -0,0 +1,114 @@
+"""A module that provides functionality to rate tasks based on a rating manual and score range."""
+
+from abc import ABC
+from typing import Dict, Optional, Set, Unpack
+
+from fabricatio.capabilities.propose import Propose
+from fabricatio.capabilities.rating import Rating
+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 import CONFIG, TEMPLATE_MANAGER
+from fabricatio.utils import ok
+
+
+class Review(Rating, Propose, ABC):
+    """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]) -> Optional[Improvement]:
+        """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:
+            Improvement[Task[T]]: A review result containing identified problems and proposed solutions,
+                with a reference to the original task.
+        """
+        return await self.review_obj(task, **kwargs)
+
+    async def review_string(
+        self,
+        input_text: str,
+        topic: str,
+        criteria: Optional[Set[str]] = None,
+        rating_manual: Optional[Dict[str, str]] = None,
+        **kwargs: Unpack[ValidateKwargs[Improvement]],
+    ) -> Optional[Improvement]:
+        """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:
+            input_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.
+            rating_manual (Optional[Dict[str,str]], optional): A dictionary of rating criteria and their corresponding scores.
+            **kwargs (Unpack[ValidateKwargs]): Additional keyword arguments for the LLM usage.
+
+        Returns:
+            Improvement: A review result containing identified problems and proposed solutions,
+                with a reference to the original text.
+        """
+        default = None
+        if "default" in kwargs:
+            # this `default` is the default for the `propose` method
+            default = kwargs.pop("default")
+
+        criteria = ok(criteria or (await self.draft_rating_criteria(topic, **kwargs)), " No criteria could be use.")
+        manual = rating_manual or await self.draft_rating_manual(topic, criteria, **kwargs)
+
+        if default is not None:
+            kwargs["default"] = default
+        return await self.propose(
+            Improvement,
+            TEMPLATE_MANAGER.render_template(
+                CONFIG.templates.review_string_template,
+                {"text": input_text, "topic": topic, "criteria_manual": manual},
+            ),
+            **kwargs,
+        )
+
+    async def review_obj[M: (Display, WithBriefing)](
+        self, obj: M, **kwargs: Unpack[ReviewKwargs[Improvement]]
+    ) -> Optional[Improvement]:
+        """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:
+            Improvement: A review result containing identified problems and proposed solutions,
+                with a reference to the original object.
+        """
+        if isinstance(obj, Display):
+            text_to_review = obj.display()
+        elif isinstance(obj, WithBriefing):
+            text_to_review = obj.briefing
+        else:
+            raise TypeError(f"Unsupported type for review: {type(obj)}")
+
+        return await self.review_string(text_to_review, **kwargs)

fabricatio/capabilities/task.py

@@ -0,0 +1,113 @@
+"""A module for the task capabilities of the Fabricatio library."""
+
+from abc import ABC
+from types import CodeType
+from typing import Any, Dict, List, Optional, Tuple, Unpack
+
+import ujson
+
+from fabricatio.capabilities.propose import Propose
+from fabricatio.journal import logger
+from fabricatio.models.kwargs_types import ChooseKwargs, ValidateKwargs
+from fabricatio.models.task import Task
+from fabricatio.models.tool import Tool, ToolExecutor
+from fabricatio.models.usages import ToolBoxUsage
+from fabricatio.parser import JsonCapture, PythonCapture
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER
+
+
+class ProposeTask(Propose, ABC):
+    """A class that proposes a task based on a prompt."""
+
+    async def propose_task[T](
+        self,
+        prompt: str,
+        **kwargs: Unpack[ValidateKwargs[Task[T]]],
+    ) -> Optional[Task[T]]:
+        """Asynchronously proposes a task based on a given prompt and parameters.
+
+        Parameters:
+            prompt: The prompt text for proposing a task, which is a string that must be provided.
+            **kwargs: The keyword arguments for the LLM (Large Language Model) usage.
+
+        Returns:
+            A Task object based on the proposal result.
+        """
+        if not prompt:
+            logger.error(err := "Prompt must be provided.")
+            raise ValueError(err)
+
+        return await self.propose(Task, prompt, **kwargs)
+
+
+class HandleTask(ToolBoxUsage,ABC):
+    """A class that handles a task based on a task object."""
+
+    async def draft_tool_usage_code(
+        self,
+        task: Task,
+        tools: List[Tool],
+        data: Dict[str, Any],
+        **kwargs: Unpack[ValidateKwargs],
+    ) -> 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}")
+
+        if not tools:
+            err = "Tools must be provided to draft the tool usage code."
+            logger.error(err)
+            raise ValueError(err)
+
+        def _validator(response: str) -> Tuple[CodeType, List[str]] | None:
+            if (source := PythonCapture.convert_with(response, lambda resp: compile(resp, "<string>", "exec"))) and (
+                to_extract := JsonCapture.convert_with(response, ujson.loads)
+            ):
+                return source, to_extract
+
+            return None
+
+        q = TEMPLATE_MANAGER.render_template(
+            CONFIG.templates.draft_tool_usage_code_template,
+            {
+                "data_module_name": CONFIG.toolbox.data_module_name,
+                "tool_module_name": CONFIG.toolbox.tool_module_name,
+                "task": task.briefing,
+                "deps": task.dependencies_prompt,
+                "tools": [{"name": t.name, "briefing": t.briefing} for t in tools],
+                "data": data,
+            },
+        )
+        logger.debug(f"Code Drafting Question: \n{q}")
+        return await self.aask_validate(
+            question=q,
+            validator=_validator,
+            **kwargs,
+        )
+
+    async def handle_fine_grind(
+        self,
+        task: Task,
+        data: Dict[str, Any],
+        box_choose_kwargs: Optional[ChooseKwargs] = None,
+        tool_choose_kwargs: Optional[ChooseKwargs] = None,
+        **kwargs: Unpack[ValidateKwargs],
+    ) -> Optional[Tuple]:
+        """Asynchronously handles a task based on a given task object and parameters."""
+        logger.info(f"Handling task: \n{task.briefing}")
+
+        tools = await self.gather_tools_fine_grind(task, box_choose_kwargs, tool_choose_kwargs)
+        logger.info(f"Gathered {[t.name for t in tools]}")
+
+        if tools and (pack := await self.draft_tool_usage_code(task, tools, data, **kwargs)):
+            executor = ToolExecutor(candidates=tools, data=data)
+
+            code, to_extract = pack
+            cxt = executor.execute(code)
+            if to_extract:
+                return tuple(cxt.get(k) for k in to_extract)
+
+        return None
+
+    async def handle(self, task: Task, data: Dict[str, Any], **kwargs: Unpack[ValidateKwargs]) -> Optional[Tuple]:
+        """Asynchronously handles a task based on a given task object and parameters."""
+        return await self.handle_fine_grind(task, data, **kwargs)

fabricatio/decorators.py

@@ -0,0 +1,251 @@
+"""Decorators for Fabricatio."""
+
+from asyncio import iscoroutinefunction
+from functools import wraps
+from importlib.util import find_spec
+from inspect import signature
+from shutil import which
+from types import ModuleType
+from typing import Callable, Coroutine, List, Optional
+
+from fabricatio.journal import logger
+from fabricatio.rust import CONFIG
+
+
+def precheck_package[**P, R](package_name: str, msg: str) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Check if a package exists in the current environment.
+
+    Args:
+        package_name (str): The name of the package to check.
+        msg (str): The message to display if the package is not found.
+
+    Returns:
+        bool: True if the package exists, False otherwise.
+    """
+
+    def _wrapper(
+        func: Callable[P, R] | Callable[P, Coroutine[None, None, R]],
+    ) -> Callable[P, R] | Callable[P, Coroutine[None, None, R]]:
+        if iscoroutinefunction(func):
+
+            @wraps(func)
+            async def _async_inner(*args: P.args, **kwargs: P.kwargs) -> R:
+                if find_spec(package_name):
+                    return await func(*args, **kwargs)
+                raise RuntimeError(msg)
+
+            return _async_inner
+
+        @wraps(func)
+        def _inner(*args: P.args, **kwargs: P.kwargs) -> R:
+            if find_spec(package_name):
+                return func(*args, **kwargs)
+            raise RuntimeError(msg)
+
+        return _inner
+
+    return _wrapper
+
+
+def depend_on_external_cmd[**P, R](
+    bin_name: str, install_tip: Optional[str], homepage: Optional[str] = None
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Decorator to check for the presence of an external command.
+
+    Args:
+        bin_name (str): The name of the required binary.
+        install_tip (Optional[str]): Installation instructions for the required binary.
+        homepage (Optional[str]): The homepage of the required binary.
+
+    Returns:
+        Callable[[Callable[P, R]], Callable[P, R]]: A decorator that wraps the function to check for the binary.
+
+    Raises:
+        RuntimeError: If the required binary is not found.
+    """
+
+    def _decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @wraps(func)
+        def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            if which(bin_name) is None:
+                err = f"`{bin_name}` is required to run {func.__name__}{signature(func)}, please install it the to `PATH` first."
+                if install_tip is not None:
+                    err += f"\nInstall tip: {install_tip}"
+                if homepage is not None:
+                    err += f"\nHomepage: {homepage}"
+                logger.error(err)
+                raise RuntimeError(err)
+            return func(*args, **kwargs)
+
+        return _wrapper
+
+    return _decorator
+
+
+def logging_execution_info[**P, R](func: Callable[P, R]) -> Callable[P, R]:
+    """Decorator to log the execution of a function.
+
+    Args:
+        func (Callable): The function to be executed
+
+    Returns:
+        Callable: A decorator that wraps the function to log the execution.
+    """
+
+    @wraps(func)
+    def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        logger.info(f"Executing function: {func.__name__}{signature(func)}")
+        logger.debug(f"{func.__name__}{signature(func)}\nArgs: {args}\nKwargs: {kwargs}")
+        return func(*args, **kwargs)
+
+    return _wrapper
+
+
+@precheck_package(
+    "questionary", "'questionary' is required to run this function. Have you installed `fabricatio[qa]`?."
+)
+def confirm_to_execute[**P, R](func: Callable[P, R]) -> Callable[P, Optional[R]] | Callable[P, R]:
+    """Decorator to confirm before executing a function.
+
+    Args:
+        func (Callable): The function to be executed
+
+    Returns:
+        Callable: A decorator that wraps the function to confirm before execution.
+    """
+    if not CONFIG.general.confirm_on_ops:
+        # Skip confirmation if the configuration is set to False
+        return func
+    from questionary import confirm
+
+    if iscoroutinefunction(func):
+
+        @wraps(func)
+        async def _wrapper(*args: P.args, **kwargs: P.kwargs) -> Optional[R]:
+            if await confirm(
+                f"Are you sure to execute function: {func.__name__}{signature(func)} \n📦 Args:{args}\n🔑 Kwargs:{kwargs}\n",
+                instruction="Please input [Yes/No] to proceed (default: Yes):",
+            ).ask_async():
+                return await func(*args, **kwargs)
+            logger.warning(f"Function: {func.__name__}{signature(func)} canceled by user.")
+            return None
+
+    else:
+
+        @wraps(func)
+        def _wrapper(*args: P.args, **kwargs: P.kwargs) -> Optional[R]:
+            if confirm(
+                f"Are you sure to execute function: {func.__name__}{signature(func)} \n📦 Args:{args}\n��� Kwargs:{kwargs}\n",
+                instruction="Please input [Yes/No] to proceed (default: Yes):",
+            ).ask():
+                return func(*args, **kwargs)
+            logger.warning(f"Function: {func.__name__}{signature(func)} canceled by user.")
+            return None
+
+    return _wrapper
+
+
+def use_temp_module[**P, R](modules: ModuleType | List[ModuleType]) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Temporarily inject modules into sys.modules during function execution.
+
+    This decorator allows you to temporarily inject one or more modules into sys.modules
+    while the decorated function executes. After execution, it restores the original
+    state of sys.modules.
+
+    Args:
+        modules (ModuleType | List[ModuleType]): A single module or list of modules to
+            temporarily inject into sys.modules.
+
+    Returns:
+        Callable[[Callable[P, R]], Callable[P, R]]: A decorator that handles temporary
+            module injection.
+
+    Examples:
+        ```python
+        from types import ModuleSpec, ModuleType, module_from_spec
+
+        # Create a temporary module
+        temp_module = module_from_spec(ModuleSpec("temp_math", None))
+        temp_module.pi = 3.14
+
+        # Use the decorator to temporarily inject the module
+        @use_temp_module(temp_module)
+        def calculate_area(radius: float) -> float:
+            from temp_math import pi
+            return pi * radius ** 2
+
+        # The temp_module is only available inside the function
+        result = calculate_area(5.0)  # Uses temp_module.pi
+        ```
+
+        Multiple modules can also be injected:
+        ```python
+        module1 = module_from_spec(ModuleSpec("mod1", None))
+        module2 = module_from_spec(ModuleSpec("mod2", None))
+
+        @use_temp_module([module1, module2])
+        def process_data():
+            import mod1, mod2
+            # Work with temporary modules
+            ...
+        ```
+    """
+    module_list = [modules] if isinstance(modules, ModuleType) else modules
+
+    def _decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @wraps(func)
+        def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            import sys
+
+            # Store original modules if they exist
+            for module in module_list:
+                if module.__name__ in sys.modules:
+                    raise RuntimeError(
+                        f"Module '{module.__name__}' is already present in sys.modules and cannot be overridden."
+                    )
+                sys.modules[module.__name__] = module
+
+            try:
+                return func(*args, **kwargs)
+            finally:
+                # Restore original state
+                for module in module_list:
+                    del sys.modules[module.__name__]
+
+        return _wrapper
+
+    return _decorator
+
+
+def logging_exec_time[**P, R](
+    func: Callable[P, R] | Callable[P, Coroutine[None, None, R]],
+) -> Callable[P, R] | Callable[P, Coroutine[None, None, R]]:
+    """Decorator to log the execution time of a function.
+
+    Args:
+        func (Callable): The function to be executed
+
+    Returns:
+        Callable: A decorator that wraps the function to log the execution time.
+    """
+    from time import time
+
+    if iscoroutinefunction(func):
+
+        @wraps(func)
+        async def _async_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            start_time = time()
+            result = await func(*args, **kwargs)
+            logger.debug(f"Execution time of `{func.__name__}`: {time() - start_time:.2f} s")
+            return result
+
+        return _async_wrapper
+
+    @wraps(func)
+    def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        start_time = time()
+        result = func(*args, **kwargs)
+        logger.debug(f"Execution time of {func.__name__}: {(time() - start_time) * 1000:.2f} ms")
+        return result
+
+    return _wrapper

fabricatio/emitter.py

@@ -0,0 +1,177 @@
+"""Core module that contains the Env class for managing event handling."""
+from dataclasses import dataclass
+from typing import Callable, ClassVar, Optional, Self, overload
+
+from pymitter import EventEmitter
+
+from fabricatio.rust import CONFIG, Event
+
+
+@dataclass
+class Env:
+    """Environment class that manages event handling using EventEmitter."""
+
+    ee: ClassVar[EventEmitter] = EventEmitter(
+        delimiter=CONFIG.pymitter.delimiter,
+        new_listener=CONFIG.pymitter.new_listener_event,
+        max_listeners=CONFIG.pymitter.max_listeners,
+        wildcard=True,
+    )
+
+    @overload
+    def on(self, event: str | Event, /, ttl: int = -1) -> Self:
+        """
+        Registers an event listener that listens indefinitely or for a specified number of times.
+
+        Args:
+            event (str | Event): The event to listen for.
+            ttl (int): Time-to-live for the listener. If -1, the listener will listen indefinitely.
+
+        Returns:
+            Self: The current instance of Env.
+        """
+        ...
+
+    @overload
+    def on[**P, R](
+            self,
+            event: str | Event,
+            func: Optional[Callable[P, R]] = None,
+            /,
+            ttl: int = -1,
+    ) -> Callable[[Callable[P, R]], Callable[P, R]]:
+        """
+        Registers an event listener with a specific function that listens indefinitely or for a specified number of times.
+
+        Args:
+            event (str | Event): The event to listen for.
+            func (Callable[P, R]): The function to be called when the event is emitted.
+            ttl (int): Time-to-live for the listener. If -1, the listener will listen indefinitely.
+
+        Returns:
+            Callable[[Callable[P, R]], Callable[P, R]]: A decorator that registers the function as an event listener.
+        """
+        ...
+
+    def on[**P, R](
+            self,
+            event: str | Event,
+            func: Optional[Callable[P, R]] = None,
+            /,
+            ttl=-1,
+    ) -> Callable[[Callable[P, R]], Callable[P, R]] | Self:
+        """Registers an event listener with a specific function that listens indefinitely or for a specified number of times.
+
+        Args:
+            event (str | Event): The event to listen for.
+            func (Callable[P, R]): The function to be called when the event is emitted.
+            ttl (int): Time-to-live for the listener. If -1, the listener will listen indefinitely.
+
+        Returns:
+            Callable[[Callable[P, R]], Callable[P, R]] | Self: A decorator that registers the function as an event listener or the current instance of Env.
+        """
+        if isinstance(event, Event):
+            event = event.collapse()
+        if func is None:
+            return self.ee.on(event, ttl=ttl)
+        self.ee.on(event, func, ttl=ttl)
+        return self
+
+    @overload
+    def once[**P, R](
+            self,
+            event: str | Event,
+    ) -> Callable[[Callable[P, R]], Callable[P, R]]:
+        """
+        Registers an event listener that listens only once.
+
+        Args:
+            event (str | Event): The event to listen for.
+
+        Returns:
+            Callable[[Callable[P, R]], Callable[P, R]]: A decorator that registers the function as an event listener.
+        """
+        ...
+
+    @overload
+    def once[**P, R](
+            self,
+            event: str | Event,
+            func: Callable[[Callable[P, R]], Callable[P, R]],
+    ) -> Self:
+        """
+        Registers an event listener with a specific function that listens only once.
+
+        Args:
+            event (str | Event): The event to listen for.
+            func (Callable[P, R]): The function to be called when the event is emitted.
+
+        Returns:
+            Self: The current instance of Env.
+        """
+        ...
+
+    def once[**P, R](
+            self,
+            event: str | Event,
+            func: Optional[Callable[P, R]] = None,
+    ) -> Callable[[Callable[P, R]], Callable[P, R]] | Self:
+        """Registers an event listener with a specific function that listens only once.
+
+        Args:
+            event (str | Event): The event to listen for.
+            func (Callable[P, R]): The function to be called when the event is emitted.
+
+        Returns:
+            Callable[[Callable[P, R]], Callable[P, R]] | Self: A decorator that registers the function as an event listener or the current instance
+        """
+        if isinstance(event, Event):
+            event = event.collapse()
+        if func is None:
+            return self.ee.once(event)
+
+        self.ee.once(event, func)
+        return self
+
+    def emit[**P](self, event: str | Event, *args: P.args, **kwargs: P.kwargs) -> None:
+        """Emits an event to all registered listeners.
+
+        Args:
+            event (str | Event): The event to emit.
+            *args: Positional arguments to pass to the listeners.
+            **kwargs: Keyword arguments to pass to the listeners.
+        """
+        if isinstance(event, Event):
+            event = event.collapse()
+
+        self.ee.emit(event, *args, **kwargs)
+
+    async def emit_async[**P](self, event: str | Event, *args: P.args, **kwargs: P.kwargs) -> None:
+        """Asynchronously emits an event to all registered listeners.
+
+        Args:
+            event (str | Event): The event to emit.
+            *args: Positional arguments to pass to the listeners.
+            **kwargs: Keyword arguments to pass to the listeners.
+        """
+        if isinstance(event, Event):
+            event = event.collapse()
+        return await self.ee.emit_async(event, *args, **kwargs)
+
+    def emit_future[**P](self, event: str | Event, *args: P.args, **kwargs: P.kwargs) -> None:
+        """Emits an event to all registered listeners and returns a future object.
+
+        Args:
+            event (str | Event): The event to emit.
+            *args: Positional arguments to pass to the listeners.
+            **kwargs: Keyword arguments to pass to the listeners.
+
+        Returns:
+            None: The future object.
+        """
+        if isinstance(event, Event):
+            event = event.collapse()
+        return self.ee.emit_future(event, *args, **kwargs)
+
+
+env = Env()

fabricatio/fs/__init__.py

@@ -0,0 +1,35 @@
+"""FileSystem manipulation module for Fabricatio."""
+from importlib.util import find_spec
+
+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 safe_json_read, safe_text_read
+
+__all__ = [
+    "absolute_path",
+    "copy_file",
+    "create_directory",
+    "delete_directory",
+    "delete_file",
+    "dump_text",
+    "gather_files",
+    "move_file",
+    "safe_json_read",
+    "safe_text_read",
+    "tree",
+]
+
+if find_spec("magika"):
+    from magika import Magika
+
+    MAGIKA = Magika()
+    __all__ += ["MAGIKA"]