fabricatio 0.2.6.dev3__cp39-cp39-win_amd64.whl

fabricatio/models/kwargs_types.py

@@ -0,0 +1,158 @@
+"""This module contains the types for the keyword arguments of the methods in the models module."""
+
+from typing import Any, TypedDict
+
+from litellm.caching.caching import CacheMode
+from litellm.types.caching import CachingSupportedCallTypes
+
+
+class CollectionSimpleConfigKwargs(TypedDict, total=False):
+    """Configuration parameters for a vector collection.
+
+    These arguments are typically used when configuring connections to vector databases.
+    """
+
+    dimension: int | None
+    timeout: float
+
+
+class FetchKwargs(TypedDict, total=False):
+    """Arguments for fetching data from vector collections.
+
+    Controls how data is retrieved from vector databases, including filtering
+    and result limiting parameters.
+    """
+
+    collection_name: str | None
+    similarity_threshold: float
+    result_per_query: int
+
+
+class EmbeddingKwargs(TypedDict, total=False):
+    """Configuration parameters for text embedding operations.
+
+    These settings control the behavior of embedding models that convert text
+    to vector representations.
+    """
+
+    model: str
+    dimensions: int
+    timeout: int
+    caching: bool
+
+
+class LLMKwargs(TypedDict, total=False):
+    """Configuration parameters for language model inference.
+
+    These arguments control the behavior of large language model calls,
+    including generation parameters and caching options.
+    """
+
+    model: str
+    temperature: float
+    stop: str | list[str]
+    top_p: float
+    max_tokens: int
+    stream: bool
+    timeout: int
+    max_retries: int
+    no_cache: bool  # if the req uses cache in this call
+    no_store: bool  # If store the response of this call to cache
+    cache_ttl: int  # how long the stored cache is alive, in seconds
+    s_maxage: int  # max accepted age of cached response, in seconds
+
+
+class GenerateKwargs(LLMKwargs, total=False):
+    """Arguments for content generation operations.
+
+    Extends LLMKwargs with additional parameters specific to generation tasks,
+    such as the number of generated items and the system message.
+    """
+
+    system_message: str
+
+
+class ValidateKwargs[T](GenerateKwargs, total=False):
+    """Arguments for content validation operations.
+
+    Extends LLMKwargs with additional parameters specific to validation tasks,
+    such as limiting the number of validation attempts.
+    """
+
+    default: T
+    max_validations: int
+
+
+# noinspection PyTypedDict
+class ReviewKwargs[T](ValidateKwargs[T], total=False):
+    """Arguments for content review operations.
+
+    Extends GenerateKwargs with parameters for evaluating content against
+    specific topics and review criteria.
+    """
+
+    topic: str
+    criteria: set[str]
+
+
+class CorrectKwargs[T](ReviewKwargs[T], total=False):
+    """Arguments for content correction operations.
+
+    Extends GenerateKwargs with parameters for correcting content based on
+    specific criteria and templates.
+    """
+
+    reference: str
+    supervisor_check: bool
+
+
+# noinspection PyTypedDict
+class ChooseKwargs[T](ValidateKwargs[T], total=False):
+    """Arguments for selection operations.
+
+    Extends GenerateKwargs with parameters for selecting among options,
+    such as the number of items to choose.
+    """
+
+    k: int
+
+
+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: CacheMode  # when default_on cache is always on, when default_off cache is opt in
+    host: str
+    port: str
+    password: str
+    namespace: str
+    ttl: float
+    default_in_memory_ttl: float
+    default_in_redis_ttl: float
+    similarity_threshold: float
+    supported_call_types: list[CachingSupportedCallTypes]
+    # s3 Bucket, boto3 configuration
+    s3_bucket_name: str
+    s3_region_name: str
+    s3_api_version: str
+    s3_use_ssl: bool
+    s3_verify: bool | str
+    s3_endpoint_url: str
+    s3_aws_access_key_id: str
+    s3_aws_secret_access_key: str
+    s3_aws_session_token: str
+    s3_config: Any
+    s3_path: str
+    redis_semantic_cache_use_async: bool
+    redis_semantic_cache_embedding_model: str
+    redis_flush_size: int
+    redis_startup_nodes: list
+    disk_cache_dir: Any
+    qdrant_api_base: str
+    qdrant_api_key: str
+    qdrant_collection_name: str
+    qdrant_quantization_config: str
+    qdrant_semantic_cache_embedding_model: str

fabricatio/models/role.py

@@ -0,0 +1,48 @@
+"""Module that contains the Role class."""
+
+from typing import Any, Self, Set
+
+from fabricatio.capabilities.correct import Correct
+from fabricatio.capabilities.task import HandleTask, ProposeTask
+from fabricatio.core import env
+from fabricatio.journal import logger
+from fabricatio.models.action import WorkFlow
+from fabricatio.models.events import Event
+from fabricatio.models.tool import ToolBox
+from pydantic import Field
+
+
+class Role(ProposeTask, HandleTask, Correct):
+    """Class that represents a role with a registry of events and workflows."""
+
+    registry: dict[Event | str, WorkFlow] = Field(default_factory=dict)
+    """ The registry of events and workflows."""
+
+    toolboxes: Set[ToolBox] = Field(default_factory=set)
+
+    def model_post_init(self, __context: Any) -> None:
+        """Register the workflows in the role to the event bus."""
+        self.resolve_configuration().register_workflows()
+
+    def register_workflows(self) -> Self:
+        """Register the workflows in the role to the event bus."""
+        for event, workflow in self.registry.items():
+            logger.debug(
+                f"Registering workflow: `{workflow.name}` for event: `{Event.instantiate_from(event).collapse()}`"
+            )
+            env.on(event, workflow.serve)
+        return self
+
+    def resolve_configuration(self) -> Self:
+        """Resolve the configuration of the role."""
+        for workflow in self.registry.values():
+            logger.debug(f"Resolving config for workflow: `{workflow.name}`")
+            (
+                workflow.fallback_to(self)
+                .steps_fallback_to_self()
+                .inject_personality(self.briefing)
+                .supply_tools_from(self)
+                .steps_supply_tools_from_self()
+            )
+
+        return self

fabricatio/models/task.py

@@ -0,0 +1,299 @@
+"""This module defines the `Task` class, which represents a task with a status and output.
+
+It includes methods to manage the task's lifecycle, such as starting, finishing, cancelling, and failing the task.
+"""
+
+from asyncio import Queue
+from typing import Any, List, Optional, Self
+
+from fabricatio._rust_instances import TEMPLATE_MANAGER
+from fabricatio.config import configs
+from fabricatio.core import env
+from fabricatio.journal import logger
+from fabricatio.models.events import Event, EventLike
+from fabricatio.models.generic import ProposedAble, WithBriefing, WithDependency
+from fabricatio.models.utils import TaskStatus
+from pydantic import Field, PrivateAttr
+
+
+class Task[T](WithBriefing, ProposedAble, WithDependency):
+    """A class representing a task with a status and output.
+
+    Attributes:
+        name (str): The name of the task.
+        description (str): The description of the task.
+        goals (str): The goal of the task.
+        dependencies (List[str]): The file dependencies of the task, a list of file paths.
+        namespace (List[str]): The namespace of the task, a list of namespace segment, as string.
+    """
+
+    name: str = Field(...)
+    """The name of the task, which should be concise and descriptive."""
+
+    description: str = Field(default="")
+    """A detailed explanation of the task that includes all necessary information. Should be clear and answer what, why, when, where, who, and how questions."""
+
+    goals: List[str] = Field(default=[])
+    """A list of objectives that the task aims to accomplish. Each goal should be clear and specific. Complex tasks should be broken into multiple smaller goals."""
+
+    namespace: List[str] = Field(default_factory=list)
+    """A list of string segments that identify the task's location in the system. If not specified, defaults to an empty list."""
+
+    dependencies: List[str] = Field(default_factory=list)
+    """A list of file paths that are needed or mentioned in the task's description (either reading or writing) to complete this task. If not specified, defaults to an empty list."""
+
+    _output: Queue[T | None] = PrivateAttr(default_factory=Queue)
+    """The output queue of the task."""
+
+    _status: TaskStatus = PrivateAttr(default=TaskStatus.Pending)
+    """The status of the task."""
+
+    _namespace: Event = PrivateAttr(default_factory=Event)
+    """The namespace of the task as an event, which is generated from the namespace list."""
+
+    def model_post_init(self, __context: Any) -> None:
+        """Initialize the task with a namespace event."""
+        self._namespace.segments.extend(self.namespace)
+
+    def move_to(self, new_namespace: EventLike) -> Self:
+        """Move the task to a new namespace.
+
+        Args:
+            new_namespace (EventLike): The new namespace to move the task to.
+
+        Returns:
+            Task: The moved instance of the `Task` class.
+        """
+        logger.debug(f"Moving task `{self.name}` to `{new_namespace}`")
+        self._namespace.clear().concat(new_namespace)
+        self.namespace = self._namespace.segments
+        return self
+
+    def nested_move_to(self, new_parent_namespace: EventLike) -> Self:
+        """Move the task to a new namespace by nesting it under the new parent namespace.
+
+        Args:
+            new_parent_namespace (EventLike): The new parent namespace to move the task to.
+
+        Returns:
+            Task: The nested moved instance of the `Task` class.
+        """
+        logger.debug(f"Nested moving task `{self.name}` to `{new_parent_namespace}`")
+        self._namespace.clear().concat(new_parent_namespace).concat(self.namespace)
+        self.namespace = self._namespace.segments
+        return self
+
+    def update_task(self, goal: Optional[List[str] | str] = None, description: Optional[str] = None) -> Self:
+        """Update the goal and description of the task.
+
+        Args:
+            goal (str|List[str], optional): The new goal of the task.
+            description (str, optional): The new description of the task.
+
+        Returns:
+            Task: The updated instance of the `Task` class.
+        """
+        if goal:
+            self.goals = goal if isinstance(goal, list) else [goal]
+        if description:
+            self.description = description
+        return self
+
+    async def get_output(self) -> T | None:
+        """Get the output of the task.
+
+        Returns:
+            T: The output of the task.
+        """
+        logger.debug(f"Getting output for task {self.name}")
+        return await self._output.get()
+
+    def status_label(self, status: TaskStatus) -> str:
+        """Return a formatted status label for the task.
+
+        Args:
+            status (TaskStatus): The status of the task.
+
+        Returns:
+            str: The formatted status label.
+        """
+        return self._namespace.derive(self.name).push(status.value).collapse()
+
+    @property
+    def pending_label(self) -> str:
+        """Return the pending status label for the task.
+
+        Returns:
+            str: The pending status label.
+        """
+        return self.status_label(TaskStatus.Pending)
+
+    @property
+    def running_label(self) -> str:
+        """Return the running status label for the task.
+
+        Returns:
+            str: The running status label.
+        """
+        return self.status_label(TaskStatus.Running)
+
+    @property
+    def finished_label(self) -> str:
+        """Return the finished status label for the task.
+
+        Returns:
+            str: The finished status label.
+        """
+        return self.status_label(TaskStatus.Finished)
+
+    @property
+    def failed_label(self) -> str:
+        """Return the failed status label for the task.
+
+        Returns:
+            str: The failed status label.
+        """
+        return self.status_label(TaskStatus.Failed)
+
+    @property
+    def cancelled_label(self) -> str:
+        """Return the cancelled status label for the task.
+
+        Returns:
+            str: The cancelled status label.
+        """
+        return self.status_label(TaskStatus.Cancelled)
+
+    async def finish(self, output: T) -> Self:
+        """Mark the task as finished and set the output.
+
+        Args:
+            output (T): The output of the task.
+
+        Returns:
+            Task: The finished instance of the `Task` class.
+        """
+        logger.info(f"Finishing task {self.name}")
+        self._status = TaskStatus.Finished
+        await self._output.put(output)
+        logger.debug(f"Output set for task {self.name}")
+        await env.emit_async(self.finished_label, self)
+        logger.debug(f"Emitted finished event for task {self.name}")
+        return self
+
+    async def start(self) -> Self:
+        """Mark the task as running.
+
+        Returns:
+            Task: The running instance of the `Task` class.
+        """
+        logger.info(f"Starting task `{self.name}`")
+        self._status = TaskStatus.Running
+        await env.emit_async(self.running_label, self)
+        return self
+
+    async def cancel(self) -> Self:
+        """Mark the task as cancelled.
+
+        Returns:
+            Task: The cancelled instance of the `Task` class.
+        """
+        logger.info(f"Cancelling task `{self.name}`")
+        self._status = TaskStatus.Cancelled
+        await self._output.put(None)
+        await env.emit_async(self.cancelled_label, self)
+        return self
+
+    async def fail(self) -> Self:
+        """Mark the task as failed.
+
+        Returns:
+            Task: The failed instance of the `Task` class.
+        """
+        logger.info(f"Failing task `{self.name}`")
+        self._status = TaskStatus.Failed
+        await self._output.put(None)
+        await env.emit_async(self.failed_label, self)
+        return self
+
+    def publish(self, new_namespace: Optional[EventLike] = None) -> Self:
+        """Publish the task to the event bus.
+
+        Args:
+            new_namespace(EventLike, optional): The new namespace to move the task to.
+
+        Returns:
+            Task: The published instance of the `Task` class.
+        """
+        if new_namespace:
+            self.move_to(new_namespace)
+        logger.info(f"Publishing task `{(label := self.pending_label)}`")
+        env.emit_future(label, self)
+        return self
+
+    async def delegate(self, new_namespace: Optional[EventLike] = None) -> T | None:
+        """Delegate the task to the event.
+
+        Args:
+            new_namespace(EventLike, optional): The new namespace to move the task to.
+
+        Returns:
+            T|None: The output of the task.
+        """
+        if new_namespace:
+            self.move_to(new_namespace)
+        logger.info(f"Delegating task `{(label := self.pending_label)}`")
+        env.emit_future(label, self)
+        return await self.get_output()
+
+    @property
+    def briefing(self) -> str:
+        """Return a briefing of the task including its goal.
+
+        Returns:
+            str: The briefing of the task.
+        """
+        return TEMPLATE_MANAGER.render_template(
+            configs.templates.task_briefing_template,
+            self.model_dump(),
+        )
+
+    def is_running(self) -> bool:
+        """Check if the task is running.
+
+        Returns:
+            bool: True if the task is running, False otherwise.
+        """
+        return self._status == TaskStatus.Running
+
+    def is_finished(self) -> bool:
+        """Check if the task is finished.
+
+        Returns:
+            bool: True if the task is finished, False otherwise.
+        """
+        return self._status == TaskStatus.Finished
+
+    def is_failed(self) -> bool:
+        """Check if the task is failed.
+
+        Returns:
+            bool: True if the task is failed, False otherwise.
+        """
+        return self._status == TaskStatus.Failed
+
+    def is_cancelled(self) -> bool:
+        """Check if the task is cancelled.
+
+        Returns:
+            bool: True if the task is cancelled, False otherwise.
+        """
+        return self._status == TaskStatus.Cancelled
+
+    def is_pending(self) -> bool:
+        """Check if the task is pending.
+
+        Returns:
+            bool: True if the task is pending, False otherwise.
+        """
+        return self._status == TaskStatus.Pending

fabricatio/models/tool.py

@@ -0,0 +1,189 @@
+"""A module for defining tools and toolboxes."""
+
+from importlib.machinery import ModuleSpec
+from importlib.util import module_from_spec
+from inspect import iscoroutinefunction, signature
+from types import CodeType, ModuleType
+from typing import Any, Callable, Dict, List, Optional, Self, cast, overload
+
+from fabricatio.config import configs
+from fabricatio.decorators import logging_execution_info, use_temp_module
+from fabricatio.journal import logger
+from fabricatio.models.generic import WithBriefing
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Tool[**P, R](WithBriefing):
+    """A class representing a tool with a callable source function."""
+
+    name: str = Field(default="")
+    """The name of the tool."""
+
+    description: str = Field(default="")
+    """The description of the tool."""
+
+    source: Callable[P, R]
+    """The source function of the tool."""
+
+    def model_post_init(self, __context: Any) -> None:
+        """Initialize the tool with a name and a source function."""
+        self.name = self.name or self.source.__name__
+
+        if not self.name:
+            raise RuntimeError("The tool must have a source function.")
+
+        self.description = self.description or self.source.__doc__ or ""
+        self.description = self.description.strip()
+
+    def invoke(self, *args: P.args, **kwargs: P.kwargs) -> R:
+        """Invoke the tool's source function with the provided arguments."""
+        logger.info(f"Invoking tool: {self.name}")
+        return self.source(*args, **kwargs)
+
+    @property
+    def briefing(self) -> str:
+        """Return a brief description of the tool.
+
+        Returns:
+            str: A brief description of the tool.
+        """
+        # 获取源函数的返回类型
+
+        return f"{'async ' if iscoroutinefunction(self.source) else ''}def {self.name}{signature(self.source)}\n{_desc_wrapper(self.description)}"
+
+
+def _desc_wrapper(desc: str) -> str:
+    lines = desc.split("\n")
+    lines_indent = [f"    {line}" for line in ['"""', *lines, '"""']]
+    return "\n".join(lines_indent)
+
+
+class ToolBox(WithBriefing):
+    """A class representing a collection of tools."""
+
+    tools: List[Tool] = Field(default_factory=list, frozen=True)
+    """A list of tools in the toolbox."""
+
+    def collect_tool[**P, R](self, func: Callable[P, R]) -> Callable[P, R]:
+        """Add a callable function to the toolbox as a tool.
+
+        Args:
+            func (Callable[P, R]): The function to be added as a tool.
+
+        Returns:
+            Callable[P, R]: The added function.
+        """
+        self.tools.append(Tool(source=func))
+        return func
+
+    def add_tool[**P, R](self, func: Callable[P, R]) -> Self:
+        """Add a callable function to the toolbox as a tool.
+
+        Args:
+            func (Callable): The function to be added as a tool.
+
+        Returns:
+            Self: The current instance of the toolbox.
+        """
+        self.collect_tool(logging_execution_info(func))
+        return self
+
+    @property
+    def briefing(self) -> str:
+        """Return a brief description of the toolbox.
+
+        Returns:
+            str: A brief description of the toolbox.
+        """
+        list_out = "\n\n".join([f"{tool.briefing}" for tool in self.tools])
+        toc = f"## {self.name}: {self.description}\n## {len(self.tools)} tools available:"
+        return f"{toc}\n\n{list_out}"
+
+    def get[**P, R](self, name: str) -> Tool[P, R]:
+        """Invoke a tool by name with the provided arguments.
+
+        Args:
+            name (str): The name of the tool to invoke.
+
+        Returns:
+            Tool: The tool instance with the specified name.
+
+        Raises:
+            ValueError: If no tool with the specified name is found.
+        """
+        tool = next((tool for tool in self.tools if tool.name == name), None)
+        if tool is None:
+            err = f"No tool with the name {name} found in the toolbox."
+            logger.error(err)
+            raise ValueError(err)
+
+        return tool
+
+    def __hash__(self) -> int:
+        """Return a hash of the toolbox based on its briefing."""
+        return hash(self.briefing)
+
+
+class ToolExecutor(BaseModel):
+    """A class representing a tool executor with a sequence of tools to execute."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+    candidates: List[Tool] = Field(default_factory=list, frozen=True)
+    """The sequence of tools to execute."""
+
+    data: Dict[str, Any] = Field(default_factory=dict)
+    """The data that could be used when invoking the tools."""
+
+    def inject_tools[M: ModuleType](self, module: Optional[M] = None) -> M:
+        """Inject the tools into the provided module or default."""
+        module = module or cast(M, module_from_spec(spec=ModuleSpec(name=configs.toolbox.tool_module_name, loader=None)))
+        for tool in self.candidates:
+            logger.debug(f"Injecting tool: {tool.name}")
+            setattr(module, tool.name, tool.invoke)
+        return module
+
+    def inject_data[M: ModuleType](self, module: Optional[M] = None) -> M:
+        """Inject the data into the provided module or default."""
+        module = module or cast(M,module_from_spec(spec=ModuleSpec(name=configs.toolbox.data_module_name, loader=None)))
+        for key, value in self.data.items():
+            logger.debug(f"Injecting data: {key}")
+            setattr(module, key, value)
+        return module
+
+    def execute[C: Dict[str, Any]](self, source: CodeType, cxt: Optional[C] = None) -> C:
+        """Execute the sequence of tools with the provided context."""
+        cxt = cxt or {}
+
+        @use_temp_module([self.inject_data(), self.inject_tools()])
+        def _exec() -> None:
+            exec(source, cxt)  # noqa: S102
+
+        _exec()
+        return cxt
+
+    @overload
+    def take[C: Dict[str, Any]](self, keys: List[str], source: CodeType, cxt: Optional[C] = None) -> C:
+        """Check the output of the tools with the provided context."""
+        ...
+
+    @overload
+    def take[C: Dict[str, Any]](self, keys: str, source: CodeType, cxt: Optional[C] = None) -> Any:
+        """Check the output of the tools with the provided context."""
+        ...
+
+    def take[C: Dict[str, Any]](self, keys: List[str] | str, source: CodeType, cxt: Optional[C] = None) -> C | Any:
+        """Check the output of the tools with the provided context."""
+        cxt = self.execute(source, cxt)
+        if isinstance(keys, str):
+            return cxt[keys]
+        return {key: cxt[key] for key in keys}
+
+    @classmethod
+    def from_recipe(cls, recipe: List[str], toolboxes: List[ToolBox]) -> Self:
+        """Create a tool executor from a recipe and a list of toolboxes."""
+        tools = []
+        while tool_name := recipe.pop(0):
+            for toolbox in toolboxes:
+                tools.append(toolbox.get(tool_name))
+
+        return cls(candidates=tools)