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

fabricatio/models/events.py

@@ -2,67 +2,65 @@ from typing import List, Self
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from fabricatio.config import configs
+
 
 class Event(BaseModel):
+    """A class representing an event."""
+
     model_config = ConfigDict(use_attribute_docstrings=True)
-    delimiter: str = Field(default=".", frozen=True)
-    """ The delimiter used to separate the event name into segments."""
 
     segments: List[str] = Field(default_factory=list, frozen=True)
     """ The segments of the namespaces."""
 
     @classmethod
-    def from_string(cls, event: str, delimiter: str = ".") -> Self:
-        """
-        Create an Event instance from a string.
+    def from_string(cls, event: str) -> Self:
+        """Create an Event instance from a string.
 
         Args:
             event (str): The event string.
-            delimiter (str): The delimiter used to separate the event name into segments.
 
         Returns:
             Event: The Event instance.
         """
-        return cls(delimiter=delimiter, segments=event.split(delimiter))
+        return cls(segments=event.split(configs.pymitter.delimiter))
 
     def collapse(self) -> str:
-        """
-        Collapse the event into a string.
-        """
-        return self.delimiter.join(self.segments)
+        """Collapse the event into a string."""
+        return configs.pymitter.delimiter.join(self.segments)
 
     def clone(self) -> Self:
-        """
-        Clone the event.
-        """
-        return Event(delimiter=self.delimiter, segments=[segment for segment in self.segments])
+        """Clone the event."""
+        return Event(segments=list(self.segments))
 
     def push(self, segment: str) -> Self:
-        """
-        Push a segment to the event.
-        """
+        """Push a segment to the event."""
         assert segment, "The segment must not be empty."
-        assert self.delimiter not in segment, "The segment must not contain the delimiter."
+        assert configs.pymitter.delimiter not in segment, "The segment must not contain the delimiter."
 
         self.segments.append(segment)
         return self
 
     def pop(self) -> str:
-        """
-        Pop a segment from the event.
-        """
+        """Pop a segment from the event."""
         return self.segments.pop()
 
     def clear(self) -> Self:
-        """
-        Clear the event.
-        """
+        """Clear the event."""
         self.segments.clear()
         return self
 
     def concat(self, event: Self) -> Self:
-        """
-        Concatenate another event to this event.
-        """
+        """Concatenate another event to this event."""
         self.segments.extend(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: Self | str) -> bool:
+        """Check if the event is equal to another event or a string."""
+        if isinstance(other, Event):
+            other = other.collapse()
+        return self.collapse() == other

fabricatio/models/generic.py

@@ -1,18 +1,19 @@
 from asyncio import Queue
-from typing import Iterable, Any, Dict, Self, List
+from typing import Callable, Dict, Iterable, List, Optional, Self
 
 import litellm
-from litellm.types.utils import StreamingChoices, ModelResponse, Choices
+import orjson
+from litellm.types.utils import Choices, ModelResponse, StreamingChoices
 from pydantic import (
     BaseModel,
-    Field,
-    PositiveInt,
-    NonNegativeInt,
     ConfigDict,
+    Field,
     HttpUrl,
-    SecretStr,
     NonNegativeFloat,
+    NonNegativeInt,
+    PositiveInt,
     PrivateAttr,
+    SecretStr,
 )
 
 from fabricatio.config import configs
@@ -20,40 +21,44 @@ from fabricatio.models.utils import Messages
 
 
 class Base(BaseModel):
+    """Base class for all models with Pydantic configuration."""
+
     model_config = ConfigDict(use_attribute_docstrings=True)
 
 
 class WithToDo(Base):
+    """Class that manages a todo list using an asynchronous queue."""
+
     _todo: Queue[str] = PrivateAttr(default_factory=Queue)
     """
     The todo list of the current instance.
     """
 
     async def add_todo(self, todo_msg: str) -> Self:
-        """
-        Add a todo item to the todo list.
+        """Add a todo item to the todo list.
+
         Args:
-            todo_msg: The todo item to be added to the todo list.
+            todo_msg (str): The todo item to be added to the todo list.
 
         Returns:
             Self: The current instance object to support method chaining.
         """
-
         await self._todo.put(todo_msg)
         return self
 
     async def get_todo(self) -> str:
-        """
-        Get the last todo item from the todo list.
+        """Get the last todo item from the todo list.
+
         Returns:
             str: The last todo item from the todo list.
-
         """
         # Pop the last todo item from the todo list
         return await self._todo.get()
 
 
 class Named(Base):
+    """Class that includes a name attribute."""
+
     name: str = Field(frozen=True)
     """
     Name of the object.
@@ -61,6 +66,8 @@ class Named(Base):
 
 
 class Described(Base):
+    """Class that includes a description attribute."""
+
     description: str = Field(default="", frozen=True)
     """
     Description of the object.
@@ -68,11 +75,12 @@ class Described(Base):
 
 
 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.
+        """Get the briefing of the object.
+
         Returns:
             str: The briefing of the object.
         """
@@ -80,6 +88,8 @@ class WithBriefing(Named, Described):
 
 
 class Memorable(Base):
+    """Class that manages a memory list with a maximum size."""
+
     memory: List[str] = Field(default_factory=list)
     """
     Memory list.
@@ -90,19 +100,13 @@ class Memorable(Base):
     """
 
     def add_memory(self, memories: str | Iterable[str]) -> Self:
-        """
-        Add memory items to the memory list.
-
-        This method appends memory items to the memory list of the current instance.
+        """Add memory items to the memory list.
 
-        Parameters:
-        - memories: str | Iterable[str] - A single memory item as a string or multiple memory items as an iterable.
+        Args:
+            memories (str | Iterable[str]): A single memory item as a string or multiple memory items as an iterable.
 
         Returns:
-        - Returns the current instance object to support method chaining.
-
-        This method design allows users to add memory items to the memory list
-        through a unified interface, enhancing code usability and extensibility.
+            Self: The current instance object to support method chaining.
         """
         # Convert a single memory item to a list
         if isinstance(memories, str):
@@ -111,43 +115,31 @@ class Memorable(Base):
         self.memory.extend(memories)
         # Limit the memory list size if the maximum size is set
         if self.memory_max_size > 0:
-            self.memory = self.memory[-self.memory_max_size:]
+            self.memory = self.memory[-self.memory_max_size :]
         # Return the current instance object to support method chaining
         return self
 
     def top_memories(self, n: PositiveInt = 1) -> List[str]:
-        """
-        Get the top memory items from the memory list.
-
-        This method returns the top memory items from the memory list of the current instance.
+        """Get the top memory items from the memory list.
 
-        Parameters:
-        - n: PositiveInt - The number of top memory items to return.
+        Args:
+            n (PositiveInt): The number of top memory items to return.
 
         Returns:
-        - List[str] - The top memory items from the memory list.
-
-        This method design allows users to get the top memory items from the memory list
-        through a unified interface, enhancing code usability and extensibility.
+            List[str]: The top memory items from the memory list.
         """
         # Get the top memory items from the memory list
         return self.memory[-n:]
 
     def top_memories_as_string(self, n: PositiveInt = 1, separator: str = "\n\n") -> str:
-        """
-        Get the memory items as a string.
-
-        This method returns the memory items as a string from the memory list of the current instance.
+        """Get the memory items as a string.
 
-        Parameters:
-        - n: PositiveInt - The number of memory items to return.
-        - separator: str - The separator to join memory items.
+        Args:
+            n (PositiveInt): The number of memory items to return.
+            separator (str): The separator to join memory items.
 
         Returns:
-        - str - The memory items as a string.
-
-        This method design allows users to get the memory items as a string from the memory list
-        through a unified interface, enhancing code usability and extensibility.
+            str: The memory items as a string.
         """
         # Get the top memory items from the memory list
         memories = self.top_memories(n)
@@ -155,19 +147,10 @@ class Memorable(Base):
         return separator.join(memories)
 
     def clear_memories(self) -> Self:
-        """
-        Clear all memory items.
-
-        This method clears all memory items from the memory list of the current instance.
-
-        Parameters:
-        - self: The current instance object.
+        """Clear all memory items.
 
         Returns:
-        - Returns the current instance object to support method chaining.
-
-        This method design allows users to clear all memory items from the memory list
-        through a unified interface, enhancing code usability and extensibility.
+            Self: The current instance object to support method chaining.
         """
         # Clear all memory items from the memory list
         self.memory.clear()
@@ -176,124 +159,143 @@ class Memorable(Base):
 
 
 class LLMUsage(Base):
-    llm_api_endpoint: HttpUrl = Field(default=configs.llm.api_endpoint)
+    """Class that manages LLM (Large Language Model) usage parameters and methods."""
+
+    llm_api_endpoint: Optional[HttpUrl] = None
     """
     The OpenAI API endpoint.
     """
 
-    llm_api_key: SecretStr = Field(default=configs.llm.api_key)
+    llm_api_key: Optional[SecretStr] = None
     """
     The OpenAI API key.
     """
 
-    llm_timeout: PositiveInt = Field(default=configs.llm.timeout)
+    llm_timeout: Optional[PositiveInt] = None
     """
     The timeout of the LLM model.
     """
 
-    llm_max_retries: PositiveInt = Field(default=configs.llm.max_retries)
+    llm_max_retries: Optional[PositiveInt] = None
     """
     The maximum number of retries.
     """
 
-    llm_model: str = Field(default=configs.llm.model)
+    llm_model: Optional[str] = None
     """
     The LLM model name.
     """
 
-    llm_temperature: NonNegativeFloat = Field(default=configs.llm.temperature)
+    llm_temperature: Optional[NonNegativeFloat] = None
     """
     The temperature of the LLM model.
     """
 
-    llm_stop_sign: str = Field(default=configs.llm.stop_sign)
+    llm_stop_sign: Optional[str | List[str]] = None
     """
     The stop sign of the LLM model.
     """
 
-    llm_top_p: NonNegativeFloat = Field(default=configs.llm.top_p)
+    llm_top_p: Optional[NonNegativeFloat] = None
     """
     The top p of the LLM model.
     """
 
-    llm_generation_count: PositiveInt = Field(default=configs.llm.generation_count)
+    llm_generation_count: Optional[PositiveInt] = None
     """
     The number of generations to generate.
     """
 
-    llm_stream: bool = Field(default=configs.llm.stream)
+    llm_stream: Optional[bool] = None
     """
     Whether to stream the LLM model's response.
     """
 
-    llm_max_tokens: PositiveInt = Field(default=configs.llm.max_tokens)
+    llm_max_tokens: Optional[PositiveInt] = None
     """
     The maximum number of tokens to generate.
     """
 
-    def model_post_init(self, __context: Any) -> None:
-        litellm.api_key = self.llm_api_key.get_secret_value()
-        litellm.api_base = self.llm_api_endpoint.unicode_string()
-
     async def aquery(
-            self,
-            messages: List[Dict[str, str]],
-            model: str | None = None,
-            temperature: NonNegativeFloat | None = None,
-            stop: str | None = None,
-            top_p: NonNegativeFloat | None = None,
-            max_tokens: PositiveInt | None = None,
-            n: PositiveInt | None = None,
-            stream: bool | None = None,
-            timeout: PositiveInt | None = None,
-            max_retries: PositiveInt | None = None,
+        self,
+        messages: List[Dict[str, str]],
+        model: str | None = None,
+        temperature: NonNegativeFloat | None = None,
+        stop: str | List[str] | None = None,
+        top_p: NonNegativeFloat | None = None,
+        max_tokens: PositiveInt | None = None,
+        n: PositiveInt | None = None,
+        stream: bool | None = None,
+        timeout: PositiveInt | None = None,
+        max_retries: PositiveInt | None = None,
     ) -> ModelResponse:
-        """
-        Asynchronously queries the language model to generate a response based on the provided messages and parameters.
-
-        Parameters:
-        - messages (List[Dict[str, str]]): A list of messages, where each message is a dictionary containing the role and content of the message.
-        - model (str | None): The name of the model to use. If not provided, the default model will be used.
-        - temperature (NonNegativeFloat | None): Controls the randomness of the output. Lower values make the output more deterministic.
-        - stop (str | None): A sequence at which to stop the generation of the response.
-        - top_p (NonNegativeFloat | None): Controls the diversity of the output through nucleus sampling.
-        - max_tokens (PositiveInt | None): The maximum number of tokens to generate in the response.
-        - n (PositiveInt | None): The number of responses to generate.
-        - stream (bool | None): Whether to receive the response in a streaming fashion.
-        - timeout (PositiveInt | None): The timeout duration for the request.
-        - max_retries (PositiveInt | None): The maximum number of retries in case of failure.
+        """Asynchronously queries the language model to generate a response based on the provided messages and parameters.
+
+        Args:
+            messages (List[Dict[str, str]]): A list of messages, where each message is a dictionary containing the role and content of the message.
+            model (str | None): The name of the model to use. If not provided, the default model will be used.
+            temperature (NonNegativeFloat | None): Controls the randomness of the output. Lower values make the output more deterministic.
+            stop (str | None): A sequence at which to stop the generation of the response.
+            top_p (NonNegativeFloat | None): Controls the diversity of the output through nucleus sampling.
+            max_tokens (PositiveInt | None): The maximum number of tokens to generate in the response.
+            n (PositiveInt | None): The number of responses to generate.
+            stream (bool | None): Whether to receive the response in a streaming fashion.
+            timeout (PositiveInt | None): The timeout duration for the request.
+            max_retries (PositiveInt | None): The maximum number of retries in case of failure.
 
         Returns:
-        - ModelResponse: An object containing the generated response and other metadata from the model.
+            ModelResponse: An object containing the generated response and other metadata from the model.
         """
         # Call the underlying asynchronous completion function with the provided and default parameters
         return await litellm.acompletion(
             messages=messages,
-            model=model or self.llm_model,
-            temperature=temperature or self.llm_temperature,
-            stop=stop or self.llm_stop_sign,
-            top_p=top_p or self.llm_top_p,
-            max_tokens=max_tokens or self.llm_max_tokens,
-            n=n or self.llm_generation_count,
-            stream=stream or self.llm_stream,
-            timeout=timeout or self.llm_timeout,
-            max_retries=max_retries or self.llm_max_retries,
+            model=model or self.llm_model or configs.llm.model,
+            temperature=temperature or self.llm_temperature or configs.llm.temperature,
+            stop=stop or self.llm_stop_sign or configs.llm.stop_sign,
+            top_p=top_p or self.llm_top_p or configs.llm.top_p,
+            max_tokens=max_tokens or self.llm_max_tokens or configs.llm.max_tokens,
+            n=n or self.llm_generation_count or configs.llm.generation_count,
+            stream=stream or self.llm_stream or configs.llm.stream,
+            timeout=timeout or self.llm_timeout or configs.llm.timeout,
+            max_retries=max_retries or self.llm_max_retries or configs.llm.max_retries,
+            api_key=self.llm_api_key.get_secret_value() if self.llm_api_key else configs.llm.api_key.get_secret_value(),
+            base_url=self.llm_api_endpoint.unicode_string()
+            if self.llm_api_endpoint
+            else configs.llm.api_endpoint.unicode_string(),
         )
 
-    async def aask(
-            self,
-            question: str,
-            system_message: str = "",
-            model: str | None = None,
-            temperature: NonNegativeFloat | None = None,
-            stop: str | None = None,
-            top_p: NonNegativeFloat | None = None,
-            max_tokens: PositiveInt | None = None,
-            n: PositiveInt | None = None,
-            stream: bool | None = None,
-            timeout: PositiveInt | None = None,
-            max_retries: PositiveInt | None = None,
+    async def ainvoke(
+        self,
+        question: str,
+        system_message: str = "",
+        model: str | None = None,
+        temperature: NonNegativeFloat | None = None,
+        stop: str | List[str] | None = None,
+        top_p: NonNegativeFloat | None = None,
+        max_tokens: PositiveInt | None = None,
+        n: PositiveInt | None = None,
+        stream: bool | None = None,
+        timeout: PositiveInt | None = None,
+        max_retries: PositiveInt | None = None,
     ) -> List[Choices | StreamingChoices]:
+        """Asynchronously invokes the language model with a question and optional system message.
+
+        Args:
+            question (str): The question to ask the model.
+            system_message (str): The system message to provide context to the model.
+            model (str | None): The name of the model to use. If not provided, the default model will be used.
+            temperature (NonNegativeFloat | None): Controls the randomness of the output. Lower values make the output more deterministic.
+            stop (str | None): A sequence at which to stop the generation of the response.
+            top_p (NonNegativeFloat | None): Controls the diversity of the output through nucleus sampling.
+            max_tokens (PositiveInt | None): The maximum number of tokens to generate in the response.
+            n (PositiveInt | None): The number of responses to generate.
+            stream (bool | None): Whether to receive the response in a streaming fashion.
+            timeout (PositiveInt | None): The timeout duration for the request.
+            max_retries (PositiveInt | None): The maximum number of retries in case of failure.
+
+        Returns:
+            List[Choices | StreamingChoices]: A list of choices or streaming choices from the model response.
+        """
         return (
             await self.aquery(
                 messages=Messages().add_system_message(system_message).add_user_message(question),
@@ -308,3 +310,157 @@ class LLMUsage(Base):
                 max_retries=max_retries,
             )
         ).choices
+
+    async def aask(
+        self,
+        question: str,
+        system_message: str = "",
+        model: str | None = None,
+        temperature: NonNegativeFloat | None = None,
+        stop: str | List[str] | None = None,
+        top_p: NonNegativeFloat | None = None,
+        max_tokens: PositiveInt | None = None,
+        stream: bool | None = None,
+        timeout: PositiveInt | None = None,
+        max_retries: PositiveInt | None = None,
+    ) -> str:
+        """Asynchronously asks the language model a question and returns the response content.
+
+        Args:
+            question (str): The question to ask the model.
+            system_message (str): The system message to provide context to the model.
+            model (str | None): The name of the model to use. If not provided, the default model will be used.
+            temperature (NonNegativeFloat | None): Controls the randomness of the output. Lower values make the output more deterministic.
+            stop (str | None): A sequence at which to stop the generation of the response.
+            top_p (NonNegativeFloat | None): Controls the diversity of the output through nucleus sampling.
+            max_tokens (PositiveInt | None): The maximum number of tokens to generate in the response.
+            stream (bool | None): Whether to receive the response in a streaming fashion.
+            timeout (PositiveInt | None): The timeout duration for the request.
+            max_retries (PositiveInt | None): The maximum number of retries in case of failure.
+
+        Returns:
+            str: The content of the model's response message.
+        """
+        return (
+            (
+                await self.ainvoke(
+                    n=1,
+                    question=question,
+                    system_message=system_message,
+                    model=model,
+                    temperature=temperature,
+                    stop=stop,
+                    top_p=top_p,
+                    max_tokens=max_tokens,
+                    stream=stream,
+                    timeout=timeout,
+                    max_retries=max_retries,
+                )
+            )
+            .pop()
+            .message.content
+        )
+
+    async def aask_validate[T](
+        self,
+        question: str,
+        validator: Callable[[str], T | None],
+        max_validations: PositiveInt = 2,
+        system_message: str = "",
+        model: str | None = None,
+        temperature: NonNegativeFloat | None = None,
+        stop: str | List[str] | None = None,
+        top_p: NonNegativeFloat | None = None,
+        max_tokens: PositiveInt | None = None,
+        stream: bool | None = None,
+        timeout: PositiveInt | None = None,
+        max_retries: PositiveInt | None = None,
+    ) -> T:
+        """Asynchronously ask a question and validate the response using a given validator.
+
+        Args:
+            question (str): The question to ask.
+            validator (Callable[[str], T | None]): A function to validate the response.
+            max_validations (PositiveInt): Maximum number of validation attempts.
+            system_message (str): System message to include in the request.
+            model (str | None): The model to use for the request.
+            temperature (NonNegativeFloat | None): Temperature setting for the request.
+            stop (str | None): Stop sequence for the request.
+            top_p (NonNegativeFloat | None): Top-p sampling parameter.
+            max_tokens (PositiveInt | None): Maximum number of tokens in the response.
+            stream (bool | None): Whether to stream the response.
+            timeout (PositiveInt | None): Timeout for the request.
+            max_retries (PositiveInt | None): Maximum number of retries for the request.
+
+        Returns:
+            T: The validated response.
+
+        Raises:
+            ValueError: If the response fails to validate after the maximum number of attempts.
+        """
+        for _ in range(max_validations):
+            if (
+                response := await self.aask(
+                    question,
+                    system_message,
+                    model,
+                    temperature,
+                    stop,
+                    top_p,
+                    max_tokens,
+                    stream,
+                    timeout,
+                    max_retries,
+                )
+            ) and (validated := validator(response)):
+                return validated
+        raise ValueError("Failed to validate the response.")
+
+    def fallback_to(self, other: "LLMUsage") -> Self:
+        """Fallback to another instance's attribute values if the current instance's attributes are None.
+
+        Args:
+            other (LLMUsage): Another instance from which to copy attribute values.
+
+        Returns:
+            Self: The current instance, allowing for method chaining.
+        """
+        # Define the list of attribute names to check and potentially copy
+        attr_names = [
+            "llm_api_endpoint",
+            "llm_api_key",
+            "llm_model",
+            "llm_stop_sign",
+            "llm_temperature",
+            "llm_top_p",
+            "llm_generation_count",
+            "llm_stream",
+            "llm_max_tokens",
+            "llm_timeout",
+            "llm_max_retries",
+        ]
+
+        # Iterate over the attribute names and copy values from 'other' to 'self' where applicable
+        for attr_name in attr_names:
+            # Copy the attribute value from 'other' to 'self' only if 'self' has None and 'other' has a non-None value
+            if getattr(self, attr_name) is None and (attr := getattr(other, attr_name)) is not None:
+                setattr(self, attr_name, attr)
+
+        # Return the current instance to allow for method chaining
+        return self
+
+
+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()