fabricatio 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

fabricatio/__init__.py

@@ -1,18 +1,24 @@
-from fabricatio.core import Env
-from fabricatio.logger import logger
-from fabricatio.models.action import Action, WorkFlow
-from fabricatio.models.events import Event
-from fabricatio.models.role import Role
-from fabricatio.models.tool import ToolBox
-from fabricatio.models.utils import Messages
-
-__all__ = [
-    "Env",
-    "logger",
-    "Action",
-    "Event",
-    "Messages",
-    "Role",
-    "ToolBox",
-    "WorkFlow",
-]
+"""Fabricatio is a Python library for building llm app using event-based agent structure."""
+
+from fabricatio.core import env
+from fabricatio.journal import logger
+from fabricatio.models.action import Action, WorkFlow
+from fabricatio.models.events import Event
+from fabricatio.models.role import Role
+from fabricatio.models.task import Task
+from fabricatio.models.tool import ToolBox
+from fabricatio.models.utils import Messages
+from fabricatio.parser import Capture
+
+__all__ = [
+    "Action",
+    "Capture",
+    "Event",
+    "Messages",
+    "Role",
+    "Task",
+    "ToolBox",
+    "WorkFlow",
+    "env",
+    "logger",
+]

fabricatio/config.py

@@ -1,19 +1,35 @@
 from typing import Literal
 
 from appdirs import user_config_dir
-from pydantic import BaseModel, HttpUrl, SecretStr, PositiveInt, NonNegativeFloat, Field, FilePath
+from pydantic import BaseModel, ConfigDict, Field, FilePath, HttpUrl, NonNegativeFloat, PositiveInt, SecretStr
 from pydantic_settings import (
     BaseSettings,
-    SettingsConfigDict,
+    DotEnvSettingsSource,
+    EnvSettingsSource,
     PydanticBaseSettingsSource,
-    TomlConfigSettingsSource,
     PyprojectTomlConfigSettingsSource,
-    EnvSettingsSource,
-    DotEnvSettingsSource,
+    SettingsConfigDict,
+    TomlConfigSettingsSource,
 )
 
 
 class LLMConfig(BaseModel):
+    """LLM configuration class.
+
+    Attributes:
+        api_endpoint (HttpUrl): OpenAI API Endpoint.
+        api_key (SecretStr): OpenAI API key. Empty by default for security reasons, should be set before use.
+        timeout (PositiveInt): The timeout of the LLM model in seconds. Default is 300 seconds as per request.
+        max_retries (PositiveInt): The maximum number of retries. Default is 3 retries.
+        model (str): The LLM model name. Set to 'gpt-3.5-turbo' as per request.
+        temperature (NonNegativeFloat): The temperature of the LLM model. Controls randomness in generation. Set to 1.0 as per request.
+        stop_sign (str): The stop sign of the LLM model. No default stop sign specified.
+        top_p (NonNegativeFloat): The top p of the LLM model. Controls diversity via nucleus sampling. Set to 0.35 as per request.
+        generation_count (PositiveInt): The number of generations to generate. Default is 1.
+        stream (bool): Whether to stream the LLM model's response. Default is False.
+        max_tokens (PositiveInt): The maximum number of tokens to generate. Set to 8192 as per request.
+    """
+    model_config = ConfigDict(use_attribute_docstrings=True)
     api_endpoint: HttpUrl = Field(default=HttpUrl("https://api.openai.com"))
     """
     OpenAI API Endpoint.
@@ -70,24 +86,65 @@ class LLMConfig(BaseModel):
     """
 
 
+class PymitterConfig(BaseModel):
+    """Pymitter configuration class.
+
+    Attributes:
+        delimiter (str): The delimiter used to separate the event name into segments.
+        new_listener_event (bool): If set, a newListener event is emitted when a new listener is added.
+        max_listeners (int): The maximum number of listeners per event.
+    """
+    model_config = ConfigDict(use_attribute_docstrings=True)
+    delimiter: str = Field(default=".", frozen=True)
+    """
+    The delimiter used to separate the event name into segments.
+    """
+
+    new_listener_event: bool = Field(default=False, frozen=True)
+    """
+    If set, a newListener event is emitted when a new listener is added.
+    """
+
+    max_listeners: int = Field(default=-1, frozen=True)
+    """
+    The maximum number of listeners per event.
+    """
+
+
 class DebugConfig(BaseModel):
+    """Debug configuration class.
+
+    Attributes:
+        log_level (Literal["DEBUG", "INFO", "SUCCESS", "WARNING", "ERROR", "CRITICAL"]): The log level of the application.
+        log_file (FilePath): The log file of the application.
+    """
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
     log_level: Literal["DEBUG", "INFO", "SUCCESS", "WARNING", "ERROR", "CRITICAL"] = Field(default="INFO")
     """
     The log level of the application.
     """
 
-    log_file: FilePath = Field(default=f"{user_config_dir("fabricatio", roaming=True)}.log")
+    log_file: FilePath = Field(default=f"{user_config_dir('fabricatio', roaming=True)}.log")
     """
     The log file of the application.
     """
 
 
 class Settings(BaseSettings):
+    """Application settings class.
+
+    Attributes:
+        llm (LLMConfig): LLM Configuration
+        debug (DebugConfig): Debug Configuration
+        pymitter (PymitterConfig): Pymitter Configuration
+    """
     model_config = SettingsConfigDict(
         env_prefix="FABRIK_",
         env_nested_delimiter="__",
         pyproject_toml_depth=1,
-        toml_file=["fabricatio.toml", f"{user_config_dir("fabricatio", roaming=True)}.toml"],
+        pyproject_toml_table_header=("tool", "fabricatio"),
+        toml_file=["fabricatio.toml", f"{user_config_dir('fabricatio', roaming=True)}.toml"],
         env_file=[".env", ".envrc"],
         use_attribute_docstrings=True,
     )
@@ -102,15 +159,32 @@ class Settings(BaseSettings):
     Debug Configuration
     """
 
+    pymitter: PymitterConfig = Field(default_factory=PymitterConfig)
+    """
+    Pymitter Configuration
+    """
+
     @classmethod
     def settings_customise_sources(
-            cls,
-            settings_cls: type[BaseSettings],
-            init_settings: PydanticBaseSettingsSource,
-            env_settings: PydanticBaseSettingsSource,
-            dotenv_settings: PydanticBaseSettingsSource,
-            file_secret_settings: PydanticBaseSettingsSource,
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
     ) -> tuple[PydanticBaseSettingsSource, ...]:
+        """Customize settings sources.
+
+        Args:
+            settings_cls (type[BaseSettings]): The settings class.
+            init_settings (PydanticBaseSettingsSource): Initial settings source.
+            env_settings (PydanticBaseSettingsSource): Environment settings source.
+            dotenv_settings (PydanticBaseSettingsSource): Dotenv settings source.
+            file_secret_settings (PydanticBaseSettingsSource): File secret settings source.
+
+        Returns:
+            tuple[PydanticBaseSettingsSource, ...]: A tuple of settings sources.
+        """
         return (
             DotEnvSettingsSource(settings_cls),
             EnvSettingsSource(settings_cls),

fabricatio/core.py

@@ -1,148 +1,165 @@
-from typing import Callable, Self, overload
-
-from pydantic import BaseModel, ConfigDict, PrivateAttr
-from pymitter import EventEmitter
-
-from fabricatio.models.events import Event
-
-
-class Env(BaseModel):
-    """
-    Environment class that manages event handling using EventEmitter.
-
-    Attributes:
-        _ee (EventEmitter): Private attribute for event handling.
-    """
-
-    model_config = ConfigDict(use_attribute_docstrings=True)
-    _ee: EventEmitter = PrivateAttr(default_factory=EventEmitter)
-
-    @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: 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: 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)
-
-        else:
-            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: Callable[P, R] = None
-    ) -> Callable[[Callable[P, R]], Callable[P, R]] | Self:
-        """
-
-        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)
-
-        else:
-            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.
-        """
-        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.
-        """
-        return await self._ee.emit_async(event, *args, **kwargs)
+from typing import Callable, Optional, Self, overload
+
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+from pymitter import EventEmitter
+
+from fabricatio.config import configs
+from fabricatio.models.events import Event
+
+
+class Env(BaseModel):
+    """Environment class that manages event handling using EventEmitter."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+    _ee: EventEmitter = PrivateAttr(
+        default_factory=lambda: EventEmitter(
+            delimiter=configs.pymitter.delimiter,
+            new_listener=configs.pymitter.new_listener_event,
+            max_listeners=configs.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)
+
+
+env = Env()

fabricatio/{logger.py → journal.py}

@@ -1,11 +1,16 @@
+import sys
+
 from loguru import logger
 from rich import traceback
 
 from fabricatio.config import configs
 
 traceback.install()
-logger.level(configs.debug.log_level)
-logger.add(configs.debug.log_file, rotation="1 weeks", retention="1 month", compression="zip")
+logger.remove()
+logger.add(
+    configs.debug.log_file, level=configs.debug.log_level, rotation="1 weeks", retention="1 month", compression="zip"
+)
+logger.add(sys.stderr, level=configs.debug.log_level)
 
 if __name__ == "__main__":
     logger.debug("This is a trace message.")

fabricatio/models/action.py

@@ -1,22 +1,90 @@
+import traceback
 from abc import abstractmethod
-from typing import Tuple
+from asyncio import Queue
+from typing import Any, Dict, Tuple, Type, Unpack
 
-from pydantic import Field
+from pydantic import Field, PrivateAttr
 
-from fabricatio.models.generic import WithBriefing, LLMUsage
+from fabricatio.journal import logger
+from fabricatio.models.generic import LLMUsage, WithBriefing
+from fabricatio.models.task import Task
 
 
 class Action(WithBriefing, LLMUsage):
+    """Class that represents an action to be executed in a workflow."""
+
+    output_key: str = Field(default="")
+    """ The key of the output data."""
 
     @abstractmethod
-    async def execute(self, *args, **kwargs):
+    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
+
 
 class WorkFlow(WithBriefing, LLMUsage):
-    steps: Tuple[Action, ...] = Field(default=())
+    """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(...)
+
+    steps: Tuple[Type[Action], ...] = Field(...)
+    """ The steps to be executed in the workflow."""
+    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."""
+
+    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.
+        """
+        self._instances = tuple(step() for step in self.steps)
+        for step in self._instances:
+            step.fallback_to(self)
+
+    async def serve(self, task: Task) -> None:
+        """Serve the task by executing the workflow steps.
 
-    async def execute(self, *args, **kwargs):
-        # TODO dispatch params to each step according to the step's signature
-        for step in self.steps:
-            await step.execute(*args, **kwargs)
+        Args:
+            task: The task to be served.
+        """
+        await task.start()
+        await self._context.put({self.task_input_key: task})
+        current_action = None
+        try:
+            for step in self._instances:
+                logger.debug(f"Executing step: {step.name}")
+                ctx = await self._context.get()
+                modified_ctx = await step.act(ctx)
+                await self._context.put(modified_ctx)
+                current_action = step.name
+            logger.info(f"Finished executing workflow: {self.name}")
+            await task.finish((await self._context.get()).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