fabricatio 0.2.0__cp312-cp312-win_amd64.whl

fabricatio/decorators.py

@@ -0,0 +1,178 @@
+"""Decorators for Fabricatio."""
+
+from asyncio import iscoroutinefunction
+from functools import wraps
+from inspect import signature
+from shutil import which
+from types import ModuleType
+from typing import Callable, List, Optional
+
+from questionary import confirm
+
+from fabricatio.config import configs
+from fabricatio.journal import logger
+
+
+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)}\nArgs: {args}\nKwargs: {kwargs}")
+        return func(*args, **kwargs)
+
+    return _wrapper
+
+
+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 configs.general.confirm_on_ops:
+        # Skip confirmation if the configuration is set to False
+        return func
+
+    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

fabricatio/fs/__init__.py

@@ -0,0 +1,5 @@
+"""FileSystem manipulation module for Fabricatio."""
+
+from fabricatio.fs.readers import magika
+
+__all__ = ["magika"]

fabricatio/fs/curd.py

@@ -0,0 +1,130 @@
+"""File system create, update, read, delete operations."""
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Union
+
+from fabricatio.decorators import depend_on_external_cmd, logging_execution_info
+from fabricatio.journal import logger
+
+
+@logging_execution_info
+def dump_text(path: Union[str, Path], text: str) -> None:
+    """Dump text to a file. you need to make sure the file's parent directory exists.
+
+    Args:
+        path(str, Path): Path to the file
+        text(str): Text to write to the file
+
+    Returns:
+        None
+    """
+    Path(path).write_text(text, encoding="utf-8", errors="ignore")
+
+
+@logging_execution_info
+def copy_file(src: Union[str, Path], dst: Union[str, Path]) -> None:
+    """Copy a file from source to destination.
+
+    Args:
+        src: Source file path
+        dst: Destination file path
+
+    Raises:
+        FileNotFoundError: If source file doesn't exist
+        shutil.SameFileError: If source and destination are the same
+    """
+    try:
+        shutil.copy(src, dst)
+        logger.info(f"Copied file from {src} to {dst}")
+    except OSError as e:
+        logger.error(f"Failed to copy file from {src} to {dst}: {e!s}")
+        raise
+
+
+@logging_execution_info
+def move_file(src: Union[str, Path], dst: Union[str, Path]) -> None:
+    """Move a file from source to destination.
+
+    Args:
+        src: Source file path
+        dst: Destination file path
+
+    Raises:
+        FileNotFoundError: If source file doesn't exist
+        shutil.SameFileError: If source and destination are the same
+    """
+    try:
+        shutil.move(src, dst)
+        logger.info(f"Moved file from {src} to {dst}")
+    except OSError as e:
+        logger.error(f"Failed to move file from {src} to {dst}: {e!s}")
+        raise
+
+
+@logging_execution_info
+def delete_file(file_path: Union[str, Path]) -> None:
+    """Delete a file.
+
+    Args:
+        file_path: Path to the file to be deleted
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        PermissionError: If no permission to delete the file
+    """
+    try:
+        Path(file_path).unlink()
+        logger.info(f"Deleted file: {file_path}")
+    except OSError as e:
+        logger.error(f"Failed to delete file {file_path}: {e!s}")
+        raise
+
+
+@logging_execution_info
+def create_directory(dir_path: Union[str, Path], parents: bool = True, exist_ok: bool = True) -> None:
+    """Create a directory.
+
+    Args:
+        dir_path: Path to the directory to create
+        parents: Create parent directories if they don't exist
+        exist_ok: Don't raise error if directory already exists
+    """
+    try:
+        Path(dir_path).mkdir(parents=parents, exist_ok=exist_ok)
+        logger.info(f"Created directory: {dir_path}")
+    except OSError as e:
+        logger.error(f"Failed to create directory {dir_path}: {e!s}")
+        raise
+
+
+@logging_execution_info
+@depend_on_external_cmd(
+    "erd",
+    "Please install `erd` using `cargo install erdtree` or `scoop install erdtree`.",
+    "https://github.com/solidiquis/erdtree",
+)
+def tree(dir_path: Union[str, Path]) -> str:
+    """Generate a tree representation of the directory structure. Requires `erd` to be installed."""
+    dir_path = Path(dir_path)
+    return subprocess.check_output(("erd", dir_path.as_posix()), encoding="utf-8")  # noqa: S603
+
+
+@logging_execution_info
+def delete_directory(dir_path: Union[str, Path]) -> None:
+    """Delete a directory and its contents.
+
+    Args:
+        dir_path: Path to the directory to delete
+
+    Raises:
+        FileNotFoundError: If directory doesn't exist
+        OSError: If directory is not empty and can't be removed
+    """
+    try:
+        shutil.rmtree(dir_path)
+        logger.info(f"Deleted directory: {dir_path}")
+    except OSError as e:
+        logger.error(f"Failed to delete directory {dir_path}: {e!s}")
+        raise

fabricatio/fs/readers.py

@@ -0,0 +1,24 @@
+"""Filesystem readers for Fabricatio."""
+
+from pathlib import Path
+
+from magika import Magika
+
+from fabricatio.config import configs
+
+magika = Magika(model_dir=configs.magika.model_dir)
+
+
+def safe_text_read(path: Path) -> str:
+    """Safely read the text from a file.
+
+    Args:
+        path (Path): The path to the file.
+
+    Returns:
+        str: The text from the file.
+    """
+    try:
+        return path.read_text(encoding="utf-8")
+    except (UnicodeDecodeError, IsADirectoryError, FileNotFoundError):
+        return ""

fabricatio/journal.py

@@ -0,0 +1,28 @@
+"""Logging setup for the project."""
+
+import sys
+
+from loguru import logger
+from rich import pretty, traceback
+
+from fabricatio.config import configs
+
+pretty.install()
+traceback.install()
+logger.remove()
+logger.add(
+    configs.debug.log_file,
+    level=configs.debug.log_level,
+    rotation=f"{configs.debug.rotation} weeks",
+    retention=f"{configs.debug.retention} weeks",
+)
+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.")
+    logger.success("This is a success message.")
+    logger.warning("This is a warning message.")
+    logger.error("This is an error message.")
+    logger.critical("This is a critical message.")

fabricatio/models/action.py

@@ -0,0 +1,139 @@
+"""Module that contains the classes for actions and workflows."""
+
+import traceback
+from abc import abstractmethod
+from asyncio import Queue
+from typing import Any, Dict, Self, Tuple, Type, Union, Unpack
+
+from fabricatio.journal import logger
+from fabricatio.models.advanced import HandleTask, ProposeTask
+from fabricatio.models.generic import WithBriefing
+from fabricatio.models.task import Task
+from fabricatio.models.usages import ToolBoxUsage
+from pydantic import Field, PrivateAttr
+
+
+class Action(HandleTask, ProposeTask):
+    """Class that represents an action to be executed in a workflow."""
+
+    personality: str = Field(default="")
+    """The personality of whom the action belongs to."""
+    output_key: str = Field(default="")
+    """The key of the output data."""
+
+    @abstractmethod
+    async def _execute(self, **cxt: Unpack) -> Any:
+        """Execute the action with the provided arguments.
+
+        Args:
+            **cxt: The context dictionary containing input and output data.
+
+        Returns:
+            The result of the action execution.
+        """
+        pass
+
+    async def act(self, cxt: Dict[str, Any]) -> Dict[str, Any]:
+        """Perform the action by executing it and setting the output data.
+
+        Args:
+            cxt: The context dictionary containing input and output data.
+        """
+        ret = await self._execute(**cxt)
+        if self.output_key:
+            logger.debug(f"Setting output: {self.output_key}")
+            cxt[self.output_key] = ret
+        return cxt
+
+    def briefing(self) -> str:
+        """Return a brief description of the action."""
+        if self.personality:
+            return f"## Your personality: \n{self.personality}\n# The action you are going to perform: \n{super().briefing}"
+        return f"# The action you are going to perform: \n{super().briefing}"
+
+
+class WorkFlow(WithBriefing, ToolBoxUsage):
+    """Class that represents a workflow to be executed in a task."""
+
+    _context: Queue[Dict[str, Any]] = PrivateAttr(default_factory=lambda: Queue(maxsize=1))
+    """ The context dictionary to be used for workflow execution."""
+
+    _instances: Tuple[Action, ...] = PrivateAttr(...)
+    """ The instances of the workflow steps."""
+
+    steps: Tuple[Union[Type[Action], Action], ...] = Field(...)
+    """ The steps to be executed in the workflow, actions or action classes."""
+    task_input_key: str = Field(default="task_input")
+    """ The key of the task input data."""
+    task_output_key: str = Field(default="task_output")
+    """ The key of the task output data."""
+    extra_init_context: Dict[str, Any] = Field(default_factory=dict, frozen=True)
+    """ The extra context dictionary to be used for workflow initialization."""
+
+    def model_post_init(self, __context: Any) -> None:
+        """Initialize the workflow by setting fallbacks for each step.
+
+        Args:
+            __context: The context to be used for initialization.
+        """
+        temp = []
+        for step in self.steps:
+            temp.append(step if isinstance(step, Action) else step())
+        self._instances = tuple(temp)
+
+    def inject_personality(self, personality: str) -> Self:
+        """Inject the personality of the workflow.
+
+        Args:
+            personality: The personality to be injected.
+
+        Returns:
+            Self: The instance of the workflow with the injected personality.
+        """
+        for a in self._instances:
+            if not a.personality:
+                a.personality = personality
+        return self
+
+    async def serve(self, task: Task) -> None:
+        """Serve the task by executing the workflow steps.
+
+        Args:
+            task: The task to be served.
+        """
+        await task.start()
+        await self._init_context(task)
+        current_action = None
+        try:
+            for step in self._instances:
+                logger.debug(f"Executing step: {step.name}")
+                modified_ctx = await step.act(await self._context.get())
+                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:
+                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`."
+                )
+
+            await task.finish(final_ctx.get(self.task_output_key, None))
+        except RuntimeError as e:
+            logger.error(f"Error during task: {current_action} execution: {e}")  # Log the exception
+            logger.error(traceback.format_exc())  # Add this line to log the traceback
+            await task.fail()  # Mark the task as failed
+
+    async def _init_context[T](self, task: Task[T]) -> None:
+        """Initialize the context dictionary for workflow execution."""
+        logger.debug(f"Initializing context for workflow: {self.name}")
+        await self._context.put({self.task_input_key: task, **dict(self.extra_init_context)})
+
+    def steps_fallback_to_self(self) -> Self:
+        """Set the fallback for each step to the workflow itself."""
+        self.hold_to(self._instances)
+        return self
+
+    def steps_supply_tools_from_self(self) -> Self:
+        """Supply the tools from the workflow to each step."""
+        self.provide_tools_to(self._instances)
+        return self

fabricatio/models/advanced.py

@@ -0,0 +1,128 @@
+"""A module for advanced models and functionalities."""
+
+from types import CodeType
+from typing import Any, Dict, List, Optional, Tuple, Unpack
+
+import orjson
+from fabricatio._rust_instances import template_manager
+from fabricatio.config import configs
+from fabricatio.models.generic import WithBriefing
+from fabricatio.models.kwargs_types import LLMKwargs
+from fabricatio.models.task import Task
+from fabricatio.models.tool import Tool, ToolExecutor
+from fabricatio.models.usages import LLMUsage, ToolBoxUsage
+from fabricatio.parser import JsonCapture, PythonCapture
+from loguru import logger
+from pydantic import PositiveInt, ValidationError
+
+
+class ProposeTask(WithBriefing, LLMUsage):
+    """A class that proposes a task based on a prompt."""
+
+    async def propose[T](
+        self,
+        prompt: str,
+        max_validations: PositiveInt = 2,
+        **kwargs: Unpack[LLMKwargs],
+    ) -> 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.
+            max_validations: The maximum number of validations allowed, default is 2.
+            **kwargs: The keyword arguments for the LLM (Large Language Model) usage.
+
+        Returns:
+            A Task object based on the proposal result.
+        """
+        if not prompt:
+            err = f"{self.name}: Prompt must be provided."
+            logger.error(err)
+            raise ValueError(err)
+
+        def _validate_json(response: str) -> None | Task:
+            try:
+                cap = JsonCapture.capture(response)
+                logger.debug(f"Response: \n{response}")
+                logger.info(f"Captured JSON: \n{cap}")
+                return Task.model_validate_json(cap)
+            except ValidationError as e:
+                logger.error(f"Failed to parse task from JSON: {e}")
+                return None
+
+        template_data = {"prompt": prompt, "json_example": Task.json_example()}
+        return await self.aask_validate(
+            question=template_manager.render_template(configs.templates.propose_task_template, template_data),
+            validator=_validate_json,
+            system_message=f"# your personal briefing: \n{self.briefing}",
+            max_validations=max_validations,
+            **kwargs,
+        )
+
+
+class HandleTask(WithBriefing, ToolBoxUsage):
+    """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[LLMKwargs],
+    ) -> 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 = f"{self.name}: 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, orjson.loads)
+            ):
+                return source, to_extract
+
+            return None
+
+        q = template_manager.render_template(
+            configs.templates.draft_tool_usage_code_template,
+            {
+                "data_module_name": configs.toolbox.data_module_name,
+                "tool_module_name": configs.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,
+            system_message=f"# your personal briefing: \n{self.briefing}",
+            **kwargs,
+        )
+
+    async def handle_fin_grind(
+        self,
+        task: Task,
+        data: Dict[str, Any],
+        **kwargs: Unpack[LLMKwargs],
+    ) -> 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(task)
+        logger.info(f"{self.name} have gathered {[t.name for t in tools]}")
+
+        if tools:
+            executor = ToolExecutor(candidates=tools, data=data)
+            code, to_extract = await self.draft_tool_usage_code(task, tools, data, **kwargs)
+
+            cxt = executor.execute(code)
+            if to_extract:
+                return tuple(cxt.get(k) for k in to_extract)
+
+        return None