fabricatio 0.2.0__cp312-cp312-win_amd64.whl

fabricatio/models/events.py

@@ -0,0 +1,82 @@
+"""The module containing the Event class."""
+
+from typing import List, Self, Union
+
+from fabricatio.config import configs
+from pydantic import BaseModel, ConfigDict, Field
+
+type EventLike = Union[str, List[str], "Event"]
+
+
+class Event(BaseModel):
+    """A class representing an event."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+    segments: List[str] = Field(default_factory=list, frozen=True)
+    """ The segments of the namespaces."""
+
+    @classmethod
+    def instantiate_from(cls, event: EventLike) -> Self:
+        """Create an Event instance from a string or list of strings or an Event instance.
+
+        Args:
+            event (EventLike): The event to instantiate from.
+
+        Returns:
+            Event: The Event instance.
+        """
+        if isinstance(event, Event):
+            return event.clone()
+        if isinstance(event, str):
+            event = event.split(configs.pymitter.delimiter)
+
+        return cls(segments=event)
+
+    def derive(self, event: EventLike) -> Self:
+        """Derive a new event from this event and another event or a string."""
+        return self.clone().concat(event)
+
+    def collapse(self) -> str:
+        """Collapse the event into a string."""
+        return configs.pymitter.delimiter.join(self.segments)
+
+    def clone(self) -> Self:
+        """Clone the event."""
+        return Event(segments=list(self.segments))
+
+    def push(self, segment: str) -> Self:
+        """Push a segment to the event."""
+        if not segment:
+            raise ValueError("The segment must not be empty.")
+        if configs.pymitter.delimiter in segment:
+            raise ValueError("The segment must not contain the delimiter.")
+
+        self.segments.append(segment)
+        return self
+
+    def push_wildcard(self) -> Self:
+        """Push a wildcard segment to the event."""
+        return self.push("*")
+
+    def pop(self) -> str:
+        """Pop a segment from the event."""
+        return self.segments.pop()
+
+    def clear(self) -> Self:
+        """Clear the event."""
+        self.segments.clear()
+        return self
+
+    def concat(self, event: EventLike) -> Self:
+        """Concatenate another event to this event."""
+        self.segments.extend(Event.instantiate_from(event).segments)
+        return self
+
+    def __hash__(self) -> int:
+        """Return the hash of the event, using the collapsed string."""
+        return hash(self.collapse())
+
+    def __eq__(self, other: str | List[str] | Self) -> bool:
+        """Check if the event is equal to another event or a string."""
+        return self.collapse() == Event.instantiate_from(other).collapse()

fabricatio/models/generic.py

@@ -0,0 +1,124 @@
+"""This module defines generic classes for models in the Fabricatio library."""
+
+from pathlib import Path
+from typing import List, Self
+
+import orjson
+from fabricatio._rust import blake3_hash
+from fabricatio._rust_instances import template_manager
+from fabricatio.config import configs
+from fabricatio.fs.readers import magika, safe_text_read
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+)
+
+
+class Base(BaseModel):
+    """Base class for all models with Pydantic configuration."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+
+class Named(Base):
+    """Class that includes a name attribute."""
+
+    name: str = Field(frozen=True)
+    """The name of the object."""
+
+
+class Described(Base):
+    """Class that includes a description attribute."""
+
+    description: str = Field(default="", frozen=True)
+    """The description of the object."""
+
+
+class WithBriefing(Named, Described):
+    """Class that provides a briefing based on the name and description."""
+
+    @property
+    def briefing(self) -> str:
+        """Get the briefing of the object.
+
+        Returns:
+            str: The briefing of the object.
+        """
+        return f"{self.name}: {self.description}" if self.description else self.name
+
+
+class WithJsonExample(Base):
+    """Class that provides a JSON schema for the model."""
+
+    @classmethod
+    def json_example(cls) -> str:
+        """Return a JSON example for the model.
+
+        Returns:
+            str: A JSON example for the model.
+        """
+        return orjson.dumps(
+            {field_name: field_info.description for field_name, field_info in cls.model_fields.items()},
+            option=orjson.OPT_INDENT_2 | orjson.OPT_SORT_KEYS,
+        ).decode()
+
+
+class WithDependency(Base):
+    """Class that manages file dependencies."""
+
+    dependencies: List[str] = Field(default_factory=list)
+    """The file dependencies which is needed to read or write to meet a specific requirement, a list of file paths."""
+
+    def add_dependency[P: str | Path](self, dependency: P | List[P]) -> Self:
+        """Add a file dependency to the task.
+
+        Args:
+            dependency (str | Path | List[str | Path]): The file dependency to add to the task.
+
+        Returns:
+            Self: The current instance of the task.
+        """
+        if not isinstance(dependency, list):
+            dependency = [dependency]
+        self.dependencies.extend(Path(d).as_posix() for d in dependency)
+        return self
+
+    def remove_dependency[P: str | Path](self, dependency: P | List[P]) -> Self:
+        """Remove a file dependency from the task.
+
+        Args:
+            dependency (str | Path | List[str | Path]): The file dependency to remove from the task.
+
+        Returns:
+            Self: The current instance of the task.
+        """
+        if not isinstance(dependency, list):
+            dependency = [dependency]
+        for d in dependency:
+            self.dependencies.remove(Path(d).as_posix())
+        return self
+
+    @property
+    def dependencies_prompt(self) -> str:
+        """Generate a prompt for the task based on the file dependencies.
+
+        Returns:
+            str: The generated prompt for the task.
+        """
+        return template_manager.render_template(
+            configs.templates.dependencies_template,
+            {
+                (pth := Path(p)).name: {
+                    "path": pth.as_posix(),
+                    "exists": pth.exists(),
+                    "description": (identity := magika.identify_path(pth)).output.description,
+                    "size": f"{pth.stat().st_size / (1024 * 1024) if pth.exists() and pth.is_file() else 0:.3f} MB",
+                    "content": (text := safe_text_read(pth)),
+                    "lines": len(text.splitlines()),
+                    "language": identity.output.ct_label,
+                    "checksum": blake3_hash(pth.read_bytes()) if pth.exists() and pth.is_file() else "unknown",
+                }
+                for p in self.dependencies
+            },
+        )

fabricatio/models/kwargs_types.py

@@ -0,0 +1,26 @@
+"""This module contains the types for the keyword arguments of the methods in the models module."""
+
+from typing import List, NotRequired, TypedDict
+
+from pydantic import NonNegativeFloat, NonNegativeInt, PositiveInt
+
+
+class LLMKwargs(TypedDict):
+    """A type representing the keyword arguments for the LLM (Large Language Model) usage."""
+
+    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 ChooseKwargs(LLMKwargs):
+    """A type representing the keyword arguments for the choose method."""
+
+    max_validations: NotRequired[PositiveInt]
+    system_message: NotRequired[str]
+    k: NotRequired[NonNegativeInt]

fabricatio/models/role.py

@@ -0,0 +1,48 @@
+"""Module that contains the Role class."""
+
+from typing import Any, Self, Set
+
+from fabricatio.core 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
+
+
+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."""
+
+    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,276 @@
+"""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 enum import Enum
+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 WithBriefing, WithDependency, WithJsonExample
+from pydantic import Field, PrivateAttr
+
+
+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):
+    """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.
+        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."""
+
+    description: str = Field(default="")
+    """The description of the task."""
+
+    goal: List[str] = Field(default=[])
+    """The goal of the task, a list of strings."""
+
+    namespace: List[str] = Field(default_factory=list)
+    """The namespace of the task, a list of namespace segment, as string."""
+
+    _output: Queue = PrivateAttr(default_factory=lambda: Queue(maxsize=1))
+    """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
+
+    @classmethod
+    def simple_task(cls, name: str, goal: str, description: str) -> Self:
+        """Create a simple task with a name, goal, and description.
+
+        Args:
+            name (str): The name of the task.
+            goal (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[str] = None, description: Optional[str] = None) -> Self:
+        """Update the goal and description of the task.
+
+        Args:
+            goal (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.goal = goal
+        if description:
+            self.description = description
+        return self
+
+    async def get_output(self) -> T:
+        """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 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 env.emit_async(self.failed_label, self)
+        return self
+
+    async def publish(self) -> Self:
+        """Publish the task to the event bus.
+
+        Returns:
+            Task: The published instance of the `Task` class
+        """
+        logger.info(f"Publishing task `{(label := self.pending_label)}`")
+        await env.emit_async(label, self)
+        return self
+
+    async def delegate(self) -> T:
+        """Delegate the task to the event bus and wait for the output.
+
+        Returns:
+            T: The output of the task
+        """
+        logger.info(f"Delegating task `{(label := self.pending_label)}`")
+        await env.emit_async(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(),
+        )