fabricatio 0.2.1.dev0__cp313-cp313-win_amd64.whl → 0.3.14.dev5__cp313-cp313-win_amd64.whl

fabricatio/models/kwargs_types.py

@@ -1,26 +1,121 @@
 """This module contains the types for the keyword arguments of the methods in the models module."""
 
-from typing import List, NotRequired, TypedDict
+from typing import Dict, List, NotRequired, Optional, Required, TypedDict
 
-from pydantic import NonNegativeFloat, NonNegativeInt, PositiveInt
 
+class ChunkKwargs(TypedDict):
+    """Configuration parameters for chunking operations."""
 
-class LLMKwargs(TypedDict):
-    """A type representing the keyword arguments for the LLM (Large Language Model) usage."""
+    max_chunk_size: int
+    max_overlapping_rate: NotRequired[float]
 
-    model: NotRequired[str]
-    temperature: NotRequired[NonNegativeFloat]
-    stop: NotRequired[str | List[str]]
-    top_p: NotRequired[NonNegativeFloat]
-    max_tokens: NotRequired[PositiveInt]
-    stream: NotRequired[bool]
-    timeout: NotRequired[PositiveInt]
-    max_retries: NotRequired[PositiveInt]
 
+class EmbeddingKwargs(TypedDict, total=False):
+    """Configuration parameters for text embedding operations.
 
-class ChooseKwargs(LLMKwargs):
-    """A type representing the keyword arguments for the choose method."""
+    These settings control the behavior of embedding models that convert text
+    to vector representations.
+    """
 
-    max_validations: NotRequired[PositiveInt]
-    system_message: NotRequired[str]
-    k: NotRequired[NonNegativeInt]
+    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: Optional[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
+    presence_penalty: float
+    frequency_penalty: float
+
+
+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: Optional[T]
+    max_validations: int
+
+
+class CompositeScoreKwargs(ValidateKwargs[List[Dict[str, float]]], total=False):
+    """Arguments for composite score generation operations.
+
+    Extends GenerateKwargs with parameters for generating composite scores
+    based on specific criteria and weights.
+    """
+
+    topic: str
+    criteria: set[str]
+    weights: Dict[str, float]
+    manual: Dict[str, str]
+
+
+class BestKwargs(CompositeScoreKwargs, total=False):
+    """Arguments for choose top-k operations."""
+
+    k: int
+
+
+class ReviewInnerKwargs[T](ValidateKwargs[T], total=False):
+    """Arguments for content review operations."""
+
+    criteria: set[str]
+
+
+# noinspection PyTypedDict
+class ReviewKwargs[T](ReviewInnerKwargs[T], total=False):
+    """Arguments for content review operations.
+
+    Extends GenerateKwargs with parameters for evaluating content against
+    specific topics and review criteria.
+    """
+
+    rating_manual: Dict[str, str]
+    topic: Required[str]
+
+
+class ReferencedKwargs[T](ValidateKwargs[T], total=False):
+    """Arguments for content review operations."""
+
+    reference: str
+
+
+# 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

fabricatio/models/role.py

@@ -1,48 +1,95 @@
-"""Module that contains the Role class."""
+"""Module that contains the Role class for managing workflows and their event registrations."""
 
-from typing import Any, Self, Set
+from functools import partial
+from typing import Any, Dict, Self
 
-from fabricatio.core import env
+from fabricatio.emitter import env
 from fabricatio.journal import logger
 from fabricatio.models.action import WorkFlow
-from fabricatio.models.advanced import ProposeTask
-from fabricatio.models.events import Event
-from fabricatio.models.tool import ToolBox
-from fabricatio.models.usages import ToolBoxUsage
-from pydantic import Field
+from fabricatio.models.generic import WithBriefing
+from fabricatio.rust import Event
+from fabricatio.utils import is_subclass_of_base
+from pydantic import ConfigDict, Field
 
+is_toolbox_usage = partial(is_subclass_of_base, base_module="fabricatio.models.usages", base_name="ToolBoxUsage")
+is_scoped_config = partial(is_subclass_of_base, base_module="fabricatio.models.generic", base_name="ScopedConfig")
 
-class Role(ProposeTask, ToolBoxUsage):
-    """Class that represents a role with a registry of events and workflows."""
 
-    registry: dict[Event | str, WorkFlow] = Field(...)
-    """ The registry of events and workflows."""
+class Role(WithBriefing):
+    """Class that represents a role with a registry of events and workflows.
 
-    toolboxes: Set[ToolBox] = Field(default_factory=set)
+    A Role serves as a container for workflows, managing their registration to events
+    and providing them with shared configuration like tools and personality.
+    """
+
+    model_config = ConfigDict(use_attribute_docstrings=True, arbitrary_types_allowed=True)
+    name: str = ""
+    """The name of the role."""
+    description: str = ""
+    """A brief description of the role's responsibilities and capabilities."""
+
+    registry: Dict[Event, WorkFlow] = Field(default_factory=dict)
+    """The registry of events and workflows."""
 
     def model_post_init(self, __context: Any) -> None:
-        """Register the workflows in the role to the event bus."""
+        """Initialize the role by resolving configurations and registering workflows.
+
+        Args:
+            __context: The context used for initialization
+        """
+        self.name = self.name or self.__class__.__name__
+
         self.resolve_configuration().register_workflows()
 
     def register_workflows(self) -> Self:
-        """Register the workflows in the role to the event bus."""
+        """Register each workflow in the registry to its corresponding event in the event bus.
+
+        Returns:
+            Self: The role instance for method chaining
+        """
         for event, workflow in self.registry.items():
-            logger.debug(
-                f"Registering workflow: `{workflow.name}` for event: `{Event.instantiate_from(event).collapse()}`"
-            )
+            logger.debug(f"Registering workflow: `{workflow.name}` for event: `{event.collapse()}`")
             env.on(event, workflow.serve)
         return self
 
     def resolve_configuration(self) -> Self:
-        """Resolve the configuration of the role."""
+        """Apply role-level configuration to all workflows in the registry.
+
+        This includes setting up fallback configurations, injecting personality traits,
+        and providing tool access to workflows and their steps.
+
+        Returns:
+            Self: The role instance for method chaining
+        """
         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()
-            )
-
+            self._configure_scoped_config(workflow)
+            self._configure_toolbox_usage(workflow)
+            workflow.inject_personality(self.briefing)
         return self
+
+    def _configure_scoped_config(self, workflow: WorkFlow) -> None:
+        """Configure scoped configuration for workflow and its actions."""
+        if not is_scoped_config(self.__class__):
+            return
+
+        fallback_target = self
+        if is_scoped_config(workflow):
+            workflow.fallback_to(self)
+            fallback_target = workflow
+
+        for action in (a for a in workflow.iter_actions() if is_scoped_config(a)):
+            action.fallback_to(fallback_target)
+
+    def _configure_toolbox_usage(self, workflow: WorkFlow) -> None:
+        """Configure toolbox usage for workflow and its actions."""
+        if not is_toolbox_usage(self.__class__):
+            return
+
+        supply_target = self
+        if is_toolbox_usage(workflow):
+            workflow.supply_tools_from(self)
+            supply_target = workflow
+
+        for action in (a for a in workflow.iter_actions() if is_toolbox_usage(a)):
+            action.supply_tools_from(supply_target)

fabricatio/models/task.py

@@ -4,60 +4,44 @@ It includes methods to manage the task's lifecycle, such as starting, finishing,
 """
 
 from asyncio import Queue
-from enum import Enum
-from typing import Any, List, Optional, Self
+from typing import Any, Dict, List, Optional, Self, Union
 
-from fabricatio._rust_instances import template_manager
-from fabricatio.config import configs
-from fabricatio.core import env
+from fabricatio.emitter import env
 from fabricatio.journal import logger
-from fabricatio.models.events import Event, EventLike
-from fabricatio.models.generic import WithBriefing, WithDependency, WithJsonExample
+from fabricatio.models.generic import ProposedAble, WithBriefing, WithDependency
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER, Event, TaskStatus
 from pydantic import Field, PrivateAttr
 
+type EventLike = Union[str, Event, List[str]]
 
-class TaskStatus(Enum):
-    """An enumeration representing the status of a task.
 
-    Attributes:
-        Pending: The task is pending.
-        Running: The task is currently running.
-        Finished: The task has been successfully completed.
-        Failed: The task has failed.
-        Cancelled: The task has been cancelled.
-    """
-
-    Pending = "pending"
-    Running = "running"
-    Finished = "finished"
-    Failed = "failed"
-    Cancelled = "cancelled"
-
-
-class Task[T](WithBriefing, WithJsonExample, WithDependency):
+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.
-        goal (str): The goal 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."""
+    """The name of the task, which should be concise and descriptive."""
 
     description: str = Field(default="")
-    """The description of the task."""
+    """A detailed explanation of the task that includes all necessary information. Should be clear and answer what, why, when, where, who, and how questions."""
 
-    goal: List[str] = Field(default=[])
-    """The goal of the task, a list of strings."""
+    goals: List[str] = Field(default_factory=list)
+    """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)
-    """The namespace of the task, a list of namespace segment, as string."""
+    """A list of string segments that identify the task's location in the system. If not specified, defaults to an empty list."""
 
-    _output: Queue = PrivateAttr(default_factory=lambda: Queue(maxsize=1))
+    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)
@@ -65,10 +49,22 @@ class Task[T](WithBriefing, WithJsonExample, WithDependency):
 
     _namespace: Event = PrivateAttr(default_factory=Event)
     """The namespace of the task as an event, which is generated from the namespace list."""
+    _extra_init_context: Dict = PrivateAttr(default_factory=dict)
+    """Extra initialization context for the task, which is designed to override the one of the Workflow."""
+
+    @property
+    def extra_init_context(self) -> Dict:
+        """Extra initialization context for the task, which is designed to override the one of the Workflow."""
+        return self._extra_init_context
+
+    def update_init_context(self, /, **kwargs) -> Self:
+        """Update the extra initialization context for the task."""
+        self.extra_init_context.update(kwargs)
+        return self
 
     def model_post_init(self, __context: Any) -> None:
         """Initialize the task with a namespace event."""
-        self._namespace.segments.extend(self.namespace)
+        self._namespace.concat(self.namespace)
 
     def move_to(self, new_namespace: EventLike) -> Self:
         """Move the task to a new namespace.
@@ -98,20 +94,6 @@ class Task[T](WithBriefing, WithJsonExample, WithDependency):
         self.namespace = self._namespace.segments
         return self
 
-    @classmethod
-    def simple_task(cls, name: str, goal: List[str], description: str) -> Self:
-        """Create a simple task with a name, goal, and description.
-
-        Args:
-            name (str): The name of the task.
-            goal (List[str]): The goal of the task.
-            description (str): The description of the task.
-
-        Returns:
-            Task: A new instance of the `Task` class.
-        """
-        return cls(name=name, goal=goal, description=description)
-
     def update_task(self, goal: Optional[List[str] | str] = None, description: Optional[str] = None) -> Self:
         """Update the goal and description of the task.
 
@@ -123,12 +105,12 @@ class Task[T](WithBriefing, WithJsonExample, WithDependency):
             Task: The updated instance of the `Task` class.
         """
         if goal:
-            self.goal = goal if isinstance(goal, list) else [goal]
+            self.goals = goal if isinstance(goal, list) else [goal]
         if description:
             self.description = description
         return self
 
-    async def get_output(self) -> T:
+    async def get_output(self) -> T | None:
         """Get the output of the task.
 
         Returns:
@@ -141,12 +123,12 @@ class Task[T](WithBriefing, WithJsonExample, WithDependency):
         """Return a formatted status label for the task.
 
         Args:
-            status (TaskStatus): The status of the task.
+            status (fabricatio.constants.TaskStatus): The status of the task.
 
         Returns:
             str: The formatted status label.
         """
-        return self._namespace.derive(self.name).push(status.value).collapse()
+        return self._namespace.derive(self.name).push(status).collapse()
 
     @property
     def pending_label(self) -> str:
@@ -229,6 +211,7 @@ class Task[T](WithBriefing, WithJsonExample, WithDependency):
         """
         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
 
@@ -240,27 +223,38 @@ class Task[T](WithBriefing, WithJsonExample, WithDependency):
         """
         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
 
-    async def publish(self) -> 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
+            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)}`")
-        await env.emit_async(label, self)
+        env.emit_future(label, self)
         return self
 
-    async def delegate(self) -> T:
-        """Delegate the task to the event bus and wait for the output.
+    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: The output of the task
+            T|None: The output of the task.
         """
+        if new_namespace:
+            self.move_to(new_namespace)
         logger.info(f"Delegating task `{(label := self.pending_label)}`")
-        await env.emit_async(label, self)
+        env.emit_future(label, self)
         return await self.get_output()
 
     @property
@@ -270,7 +264,47 @@ class Task[T](WithBriefing, WithJsonExample, WithDependency):
         Returns:
             str: The briefing of the task.
         """
-        return template_manager.render_template(
-            configs.templates.task_briefing_template,
+        return TEMPLATE_MANAGER.render_template(
+            CONFIG.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