fabricatio 0.2.3.dev2__cp312-cp312-win_amd64.whl → 0.2.4__cp312-cp312-win_amd64.whl

fabricatio/models/generic.py

@@ -1,17 +1,25 @@
 """This module defines generic classes for models in the Fabricatio library."""
 
+from abc import abstractmethod
 from pathlib import Path
-from typing import Callable, List, Self
+from typing import Callable, Iterable, List, Optional, Self, Union, final
 
 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 fabricatio.journal import logger
+from fabricatio.parser import JsonCapture
 from pydantic import (
     BaseModel,
     ConfigDict,
     Field,
+    HttpUrl,
+    NonNegativeFloat,
+    PositiveFloat,
+    PositiveInt,
+    SecretStr,
 )
 
 
@@ -21,6 +29,18 @@ class Base(BaseModel):
     model_config = ConfigDict(use_attribute_docstrings=True)
 
 
+class Display(Base):
+    """Class that provides a method to display the model in a formatted JSON string."""
+
+    def display(self) -> str:
+        """Display the model in a formatted JSON string.
+
+        Returns:
+            str: The formatted JSON string of the model.
+        """
+        return self.model_dump_json(indent=1)
+
+
 class Named(Base):
     """Class that includes a name attribute."""
 
@@ -48,22 +68,87 @@ class WithBriefing(Named, Described):
         return f"{self.name}: {self.description}" if self.description else self.name
 
 
-class WithJsonExample(Base):
-    """Class that provides a JSON schema for the model."""
+class WithFormatedJsonSchema(Base):
+    """Class that provides a formatted JSON schema of the model."""
 
     @classmethod
-    def json_example(cls) -> str:
-        """Return a JSON example for the model.
+    def formated_json_schema(cls) -> str:
+        """Get the JSON schema of the model in a formatted string.
 
         Returns:
-            str: A JSON example for the model.
+            str: The JSON schema of the model in a formatted string.
         """
         return orjson.dumps(
-            {field_name: field_info.description for field_name, field_info in cls.model_fields.items()},
+            cls.model_json_schema(),
             option=orjson.OPT_INDENT_2 | orjson.OPT_SORT_KEYS,
         ).decode()
 
 
+class CreateJsonObjPrompt(WithFormatedJsonSchema):
+    """Class that provides a prompt for creating a JSON object."""
+
+    @classmethod
+    def create_json_prompt(cls, requirement: str) -> str:
+        """Create the prompt for creating a JSON object with given requirement.
+
+        Args:
+            requirement (str): The requirement for the JSON object.
+
+        Returns:
+            str: The prompt for creating a JSON object with given requirement.
+        """
+        return template_manager.render_template(
+            configs.templates.create_json_obj_template,
+            {"requirement": requirement, "json_schema": cls.formated_json_schema()},
+        )
+
+
+class InstantiateFromString(Base):
+    """Class that provides a method to instantiate the class from a string."""
+
+    @classmethod
+    def instantiate_from_string(cls, string: str) -> Self | None:
+        """Instantiate the class from a string.
+
+        Args:
+            string (str): The string to instantiate the class from.
+
+        Returns:
+            Self | None: The instance of the class or None if the string is not valid.
+        """
+        return JsonCapture.convert_with(string, cls.model_validate_json)
+
+
+class ProposedAble(CreateJsonObjPrompt, InstantiateFromString):
+    """Class that provides methods for proposing a task."""
+
+    pass
+
+
+class FinalizedDumpAble(Base):
+    """Class that provides a method to finalize the dump of the object."""
+
+    @abstractmethod
+    def finalized_dump(self) -> str:
+        """Finalize the dump of the object.
+
+        Returns:
+            str: The finalized dump of the object.
+        """
+
+    def finalized_dump_to(self, path: str | Path) -> Self:
+        """Finalize the dump of the object to a file.
+
+        Args:
+            path (str | Path): The path to save the finalized dump.
+
+        Returns:
+            Self: The current instance of the object.
+        """
+        Path(path).write_text(self.finalized_dump(), encoding="utf-8")
+        return self
+
+
 class WithDependency(Base):
     """Class that manages file dependencies."""
 
@@ -150,3 +235,129 @@ class WithDependency(Base):
                 for p in self.dependencies
             },
         )
+
+
+class PrepareVectorization(Base):
+    """Class that prepares the vectorization of the model."""
+
+    @abstractmethod
+    def _prepare_vectorization_inner(self) -> str:
+        """Prepare the vectorization of the model."""
+
+    def prepare_vectorization(self, max_length: Optional[int] = None) -> str:
+        """Prepare the vectorization of the model.
+
+        Returns:
+            str: The prepared vectorization of the model.
+        """
+        max_length = max_length or configs.embedding.max_sequence_length
+        chunk = self._prepare_vectorization_inner()
+        if len(chunk) > max_length:
+            logger.error(err := f"Chunk exceeds maximum sequence length {max_length}.")
+            raise ValueError(err)
+
+        return chunk
+
+
+class ScopedConfig(Base):
+    """Class that manages a scoped configuration."""
+
+    llm_api_endpoint: Optional[HttpUrl] = None
+    """The OpenAI API endpoint."""
+
+    llm_api_key: Optional[SecretStr] = None
+    """The OpenAI API key."""
+
+    llm_timeout: Optional[PositiveInt] = None
+    """The timeout of the LLM model."""
+
+    llm_max_retries: Optional[PositiveInt] = None
+    """The maximum number of retries."""
+
+    llm_model: Optional[str] = None
+    """The LLM model name."""
+
+    llm_temperature: Optional[NonNegativeFloat] = None
+    """The temperature of the LLM model."""
+
+    llm_stop_sign: Optional[str | List[str]] = None
+    """The stop sign of the LLM model."""
+
+    llm_top_p: Optional[NonNegativeFloat] = None
+    """The top p of the LLM model."""
+
+    llm_generation_count: Optional[PositiveInt] = None
+    """The number of generations to generate."""
+
+    llm_stream: Optional[bool] = None
+    """Whether to stream the LLM model's response."""
+
+    llm_max_tokens: Optional[PositiveInt] = None
+    """The maximum number of tokens to generate."""
+
+    embedding_api_endpoint: Optional[HttpUrl] = None
+    """The OpenAI API endpoint."""
+
+    embedding_api_key: Optional[SecretStr] = None
+    """The OpenAI API key."""
+
+    embedding_timeout: Optional[PositiveInt] = None
+    """The timeout of the LLM model."""
+
+    embedding_model: Optional[str] = None
+    """The LLM model name."""
+
+    embedding_max_sequence_length: Optional[PositiveInt] = None
+    """The maximum sequence length."""
+
+    embedding_dimensions: Optional[PositiveInt] = None
+    """The dimensions of the embedding."""
+    embedding_caching: Optional[bool] = False
+    """Whether to cache the embedding result."""
+
+    milvus_uri: Optional[HttpUrl] = Field(default=None)
+    """The URI of the Milvus server."""
+    milvus_token: Optional[SecretStr] = Field(default=None)
+    """The token for the Milvus server."""
+    milvus_timeout: Optional[PositiveFloat] = Field(default=None)
+    """The timeout for the Milvus server."""
+    milvus_dimensions: Optional[PositiveInt] = Field(default=None)
+    """The dimensions of the Milvus server."""
+
+    @final
+    def fallback_to(self, other: "ScopedConfig") -> 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.
+        """
+        # Iterate over the attribute names and copy values from 'other' to 'self' where applicable
+        # noinspection PydanticTypeChecker,PyTypeChecker
+        for attr_name in ScopedConfig.model_fields:
+            # 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
+
+    @final
+    def hold_to(self, others: Union["ScopedConfig", Iterable["ScopedConfig"]]) -> Self:
+        """Hold to another instance's attribute values if the current instance's attributes are None.
+
+        Args:
+            others (LLMUsage | Iterable[LLMUsage]): Another instance or iterable of instances from which to copy attribute values.
+
+        Returns:
+            Self: The current instance, allowing for method chaining.
+        """
+        if not isinstance(others, Iterable):
+            others = [others]
+        for other in others:
+            # noinspection PyTypeChecker,PydanticTypeChecker
+            for attr_name in ScopedConfig.model_fields:
+                if (attr := getattr(self, attr_name)) is not None and getattr(other, attr_name) is None:
+                    setattr(other, attr_name, attr)

fabricatio/models/kwargs_types.py

@@ -5,6 +5,21 @@ from typing import List, NotRequired, TypedDict
 from pydantic import NonNegativeFloat, NonNegativeInt, PositiveInt
 
 
+class CollectionSimpleConfigKwargs(TypedDict):
+    """A type representing the configuration for a collection."""
+
+    dimension: NotRequired[int]
+    timeout: NotRequired[float]
+
+
+class FetchKwargs(TypedDict):
+    """A type representing the keyword arguments for the fetch method."""
+
+    collection_name: NotRequired[str]
+    similarity_threshold: NotRequired[float]
+    result_per_query: NotRequired[int]
+
+
 class EmbeddingKwargs(TypedDict):
     """A type representing the keyword arguments for the embedding method."""
 

fabricatio/models/task.py

@@ -4,7 +4,6 @@ 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 fabricatio._rust_instances import template_manager
@@ -12,53 +11,36 @@ 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 fabricatio.models.generic import ProposedAble, WithBriefing, WithDependency
+from fabricatio.models.utils import TaskStatus
 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):
+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, which should be a concise and descriptive name."""
+    """The name of the task, which should be concise and descriptive."""
 
     description: str = Field(default="")
-    """The description of the task, which should provide every details and noting about the task if provided, obeying the CEFR level rule and 5W1H rule."""
+    """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. The goal should be a concise and clear statement of what the task is intended to achieve, goal SHALL NOT be too broad or too narrow."""
+    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)
-    """The namespace of the task, a list of namespace segment, as string, if it is not directly given out, it SHALL just be a empty list meaning `NOT ASSIGNED`"""
+    """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, These file are needed to read or write to meet a specific requirement of this task, if it is not directly given out, it SHALL just be a empty list meaning `NOT ASSIGNED`"""
+    """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."""
@@ -101,20 +83,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.
 
@@ -126,7 +94,7 @@ 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

fabricatio/models/tool.py

@@ -7,7 +7,7 @@ from types import CodeType, ModuleType
 from typing import Any, Callable, Dict, List, Optional, Self, overload
 
 from fabricatio.config import configs
-from fabricatio.decorators import use_temp_module
+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
@@ -31,6 +31,7 @@ class Tool[**P, R](WithBriefing):
 
         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()
 
@@ -84,7 +85,7 @@ class ToolBox(WithBriefing):
         Returns:
             Self: The current instance of the toolbox.
         """
-        self.tools.append(Tool(source=func))
+        self.collect_tool(logging_execution_info(func))
         return self
 
     @property