fabricatio 0.2.8.dev3__cp312-cp312-win_amd64.whl → 0.2.9.dev0__cp312-cp312-win_amd64.whl

fabricatio/models/generic.py

@@ -1,18 +1,18 @@
-"""This module defines generic classes for models in the Fabricatio library."""
+"""This module defines generic classes for models in the Fabricatio library, providing a foundation for various model functionalities."""
 
 from abc import ABC, abstractmethod
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Callable, Dict, Iterable, List, Optional, Self, Union, final, overload
+from typing import Any, Callable, Dict, Iterable, List, Optional, Self, Type, Union, final, overload
 
 import orjson
 import rtoml
-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 fabricatio.rust import blake3_hash
+from fabricatio.rust_instances import TEMPLATE_MANAGER
 from fabricatio.utils import ok
 from litellm.utils import token_counter
 from pydantic import (
@@ -30,13 +30,19 @@ from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
 
 
 class Base(BaseModel):
-    """Base class for all models with Pydantic configuration."""
+    """Base class for all models with Pydantic configuration.
+
+    This class sets up the basic Pydantic configuration for all models in the Fabricatio library.
+    """
 
     model_config = ConfigDict(use_attribute_docstrings=True)
 
 
 class Display(Base):
-    """Class that provides a method to display the model in a formatted JSON string."""
+    """Class that provides a method to display the model in a formatted JSON string.
+
+    This class includes methods to display the model in both formatted and compact JSON strings.
+    """
 
     def display(self) -> str:
         """Display the model in a formatted JSON string.
@@ -54,23 +60,48 @@ class Display(Base):
         """
         return self.model_dump_json()
 
+    @staticmethod
+    def seq_display(seq: Iterable["Display"], compact: bool = False) -> str:
+        """Display a sequence of Display objects in a formatted JSON string.
+
+        Args:
+            seq (Iterable[Display]): The sequence of Display objects to display.
+            compact (bool): Whether to display the sequence in a compact format. Defaults to False.
+
+        Returns:
+            str: The formatted JSON string of the sequence.
+        """
+        return "\n".join(d.compact() if compact else d.display() for d in seq)
+
 
 class Named(Base):
-    """Class that includes a name attribute."""
+    """Class that includes a name attribute.
+
+    This class adds a name attribute to models, which is intended to be a unique identifier.
+    """
 
-    name: str = Field(frozen=True)
-    """The name of the object."""
+    name: str
+    """The name of this object,briefly and conclusively."""
 
 
 class Described(Base):
-    """Class that includes a description attribute."""
+    """Class that includes a description attribute.
 
-    description: str = Field(frozen=True)
-    """The description of the object."""
+    This class adds a description attribute to models, providing additional context or information.
+    """
+
+    description: str
+    """A comprehensive description of this object, including its purpose, scope, and context.
+    This should clearly explain what this object is about, why it exists, and in what situations
+    it applies. The description should be detailed enough to provide full understanding of
+    this object's intent and application."""
 
 
 class AsPrompt(Base):
-    """Class that provides a method to generate a prompt from the model."""
+    """Class that provides a method to generate a prompt from the model.
+
+    This class includes a method to generate a prompt based on the model's attributes.
+    """
 
     @final
     def as_prompt(self) -> str:
@@ -85,31 +116,53 @@ class AsPrompt(Base):
         )
 
     @abstractmethod
-    def _as_prompt_inner(self) -> Dict[str, str]: ...
+    def _as_prompt_inner(self) -> Dict[str, str]:
+        """Generate the inner part of the prompt.
+
+        This method should be implemented by subclasses to provide the specific data for the prompt.
+
+        Returns:
+            Dict[str, str]: The data for the prompt.
+        """
 
 
 class WithRef[T](Base):
-    """Class that provides a reference to another object."""
+    """Class that provides a reference to another object.
+
+    This class manages a reference to another object, allowing for easy access and updates.
+    """
 
     _reference: Optional[T] = PrivateAttr(None)
 
     @property
     def referenced(self) -> T:
-        """Get the referenced object."""
+        """Get the referenced object.
+
+        Returns:
+            T: The referenced object.
+
+        Raises:
+            ValueError: If the reference is not set.
+        """
         return ok(
-            self._reference, f"`{self.__class__.__name__}`' s `_reference` field is None. Have you called `update_ref`?"
+            self._reference, f"`{self.__class__.__name__}`'s `_reference` field is None. Have you called `update_ref`?"
         )
 
     @overload
     def update_ref[S: WithRef](self: S, reference: T) -> S: ...
-
     @overload
     def update_ref[S: WithRef](self: S, reference: "WithRef[T]") -> S: ...
-
     @overload
     def update_ref[S: WithRef](self: S, reference: None = None) -> S: ...
     def update_ref[S: WithRef](self: S, reference: Union[T, "WithRef[T]", None] = None) -> S:  # noqa: PYI019
-        """Update the reference of the object."""
+        """Update the reference of the object.
+
+        Args:
+            reference (Union[T, WithRef[T], None]): The new reference to set.
+
+        Returns:
+            S: The current instance with the updated reference.
+        """
         if isinstance(reference, self.__class__):
             self._reference = reference.referenced
         else:
@@ -117,14 +170,24 @@ class WithRef[T](Base):
         return self
 
     def derive[S: WithRef](self: S, reference: Any) -> S:  # noqa: PYI019
-        """Derive a new object from the current object."""
+        """Derive a new object from the current object.
+
+        Args:
+            reference (Any): The reference for the new object.
+
+        Returns:
+            S: A new instance derived from the current object with the provided reference.
+        """
         new = self.model_copy()
         new._reference = reference
         return new
 
 
 class PersistentAble(Base):
-    """Class that provides a method to persist the object."""
+    """Class that provides a method to persist the object.
+
+    This class includes methods to persist the object to a file or directory.
+    """
 
     def persist(self, path: str | Path) -> Self:
         """Persist the object to a file or directory.
@@ -136,7 +199,7 @@ class PersistentAble(Base):
             Self: The current instance of the object.
         """
         p = Path(path)
-        out = rtoml.dumps(self.model_dump())
+        out = self.model_dump_json()
 
         # Generate a timestamp in the format YYYYMMDD_HHMMSS
         timestamp = datetime.now().strftime("%Y%m%d")
@@ -166,22 +229,50 @@ class PersistentAble(Base):
         Returns:
             Self: The current instance of the object.
         """
-        return cls.model_validate(rtoml.load(path))
+        return cls.model_validate_json(safe_text_read(path))
+
+
+class Language(Base):
+    """Class that provides a language attribute."""
+
+    language: str
+    """The written language of this object, which should be aligned to the original requirement 
+    For example if the requirement is in Chinese, the language should be set to `zh`, if the requirement is in English, the language should be set to `en` and etc."""
 
 
 class ModelHash(Base):
-    """Class that provides a hash value for the object."""
+    """Class that provides a hash value for the object.
+
+    This class includes a method to calculate a hash value for the object based on its JSON representation.
+    """
 
     def __hash__(self) -> int:
-        """Calculates a hash value for the ArticleBase object based on its model_dump_json representation."""
+        """Calculates a hash value for the object based on its model_dump_json representation.
+
+        Returns:
+            int: The hash value of the object.
+        """
         return hash(self.model_dump_json())
 
 
 class UpdateFrom(Base):
-    """Class that provides a method to update the object from another object."""
+    """Class that provides a method to update the object from another object.
+
+    This class includes methods to update the current object with the attributes of another object.
+    """
 
     def update_pre_check(self, other: Self) -> Self:
-        """Pre-check for updating the object from another object."""
+        """Pre-check for updating the object from another object.
+
+        Args:
+            other (Self): The other object to update from.
+
+        Returns:
+            Self: The current instance after pre-check.
+
+        Raises:
+            TypeError: If the other object is not of the same type.
+        """
         if not isinstance(other, self.__class__):
             raise TypeError(f"Cannot update from a non-{self.__class__.__name__} instance.")
 
@@ -189,16 +280,35 @@ class UpdateFrom(Base):
 
     @abstractmethod
     def update_from_inner(self, other: Self) -> Self:
-        """Updates the current instance with the attributes of another instance."""
+        """Updates the current instance with the attributes of another instance.
+
+        This method should be implemented by subclasses to provide the specific update logic.
+
+        Args:
+            other (Self): The other instance to update from.
+
+        Returns:
+            Self: The current instance with updated attributes.
+        """
 
     @final
     def update_from(self, other: Self) -> Self:
-        """Updates the current instance with the attributes of another instance."""
+        """Updates the current instance with the attributes of another instance.
+
+        Args:
+            other (Self): The other instance to update from.
+
+        Returns:
+            Self: The current instance with updated attributes.
+        """
         return self.update_pre_check(other).update_from_inner(other)
 
 
 class ResolveUpdateConflict(Base):
-    """Class that provides a method to update the object from another object."""
+    """Class that provides a method to update the object from another object.
+
+    This class includes a method to resolve conflicts when updating the object from another object.
+    """
 
     @abstractmethod
     def resolve_update_conflict(self, other: Self) -> str:
@@ -213,7 +323,10 @@ class ResolveUpdateConflict(Base):
 
 
 class Introspect(Base):
-    """Class that provides a method to introspect the object."""
+    """Class that provides a method to introspect the object.
+
+    This class includes a method to perform internal introspection of the object.
+    """
 
     @abstractmethod
     def introspect(self) -> str:
@@ -225,7 +338,10 @@ class Introspect(Base):
 
 
 class WithBriefing(Named, Described):
-    """Class that provides a briefing based on the name and description."""
+    """Class that provides a briefing based on the name and description.
+
+    This class combines the name and description attributes to provide a brief summary of the object.
+    """
 
     @property
     def briefing(self) -> str:
@@ -238,15 +354,29 @@ class WithBriefing(Named, Described):
 
 
 class UnsortGenerate(GenerateJsonSchema):
-    """Class that provides a reverse JSON schema of the model."""
+    """Class that provides a reverse JSON schema of the model.
+
+    This class overrides the sorting behavior of the JSON schema generation to maintain the original order.
+    """
 
     def sort(self, value: JsonSchemaValue, parent_key: str | None = None) -> JsonSchemaValue:
-        """Not sort."""
+        """Not sort.
+
+        Args:
+            value (JsonSchemaValue): The JSON schema value to sort.
+            parent_key (str | None): The parent key of the JSON schema value.
+
+        Returns:
+            JsonSchemaValue: The JSON schema value without sorting.
+        """
         return value
 
 
 class WithFormatedJsonSchema(Base):
-    """Class that provides a formatted JSON schema of the model."""
+    """Class that provides a formatted JSON schema of the model.
+
+    This class includes a method to generate a formatted JSON schema of the model.
+    """
 
     @classmethod
     def formated_json_schema(cls) -> str:
@@ -262,25 +392,26 @@ class WithFormatedJsonSchema(Base):
 
 
 class CreateJsonObjPrompt(WithFormatedJsonSchema):
-    """Class that provides a prompt for creating a JSON object."""
+    """Class that provides a prompt for creating a JSON object.
+
+    This class includes a method to create a prompt for creating a JSON object based on the model's schema and a requirement.
+    """
 
     @classmethod
     @overload
     def create_json_prompt(cls, requirement: List[str]) -> List[str]: ...
-
     @classmethod
     @overload
     def create_json_prompt(cls, requirement: str) -> str: ...
-
     @classmethod
     def create_json_prompt(cls, requirement: str | List[str]) -> str | List[str]:
         """Create the prompt for creating a JSON object with given requirement.
 
         Args:
-            requirement (str): The requirement for the JSON object.
+            requirement (str | List[str]): The requirement for the JSON object.
 
         Returns:
-            str: The prompt for creating a JSON object with given requirement.
+            str | List[str]: The prompt for creating a JSON object with given requirement.
         """
         if isinstance(requirement, str):
             return TEMPLATE_MANAGER.render_template(
@@ -297,7 +428,10 @@ class CreateJsonObjPrompt(WithFormatedJsonSchema):
 
 
 class InstantiateFromString(Base):
-    """Class that provides a method to instantiate the class from a string."""
+    """Class that provides a method to instantiate the class from a string.
+
+    This class includes a method to instantiate the class from a JSON string representation.
+    """
 
     @classmethod
     def instantiate_from_string(cls, string: str) -> Self | None:
@@ -309,19 +443,37 @@ class InstantiateFromString(Base):
         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)
+        obj = JsonCapture.convert_with(string, cls.model_validate_json)
+        logger.debug(f"Instantiate `{cls.__name__}` from string, {'Failed' if obj is None else 'Success'}.")
+        return obj
 
 
 class ProposedAble(CreateJsonObjPrompt, InstantiateFromString):
-    """Class that provides a method to propose a JSON object based on the requirement."""
+    """Class that provides a method to propose a JSON object based on the requirement.
+
+    This class combines the functionality to create a prompt for a JSON object and instantiate it from a string.
+    """
+
+
+class SketchedAble(ProposedAble, Display):
+    """Class that provides a method to scratch the object.
 
+    This class combines the functionality to propose a JSON object, instantiate it from a string, and display it.
+    """
 
-class ProposedUpdateAble(ProposedAble, UpdateFrom, ABC):
-    """Make the obj can be updated from the proposed obj in place."""
+
+class ProposedUpdateAble(SketchedAble, UpdateFrom, ABC):
+    """Make the obj can be updated from the proposed obj in place.
+
+    This class provides the ability to update an object in place from a proposed object.
+    """
 
 
 class FinalizedDumpAble(Base):
-    """Class that provides a method to finalize the dump of the object."""
+    """Class that provides a method to finalize the dump of the object.
+
+    This class includes methods to finalize the JSON representation of the object and dump it to a file.
+    """
 
     def finalized_dump(self) -> str:
         """Finalize the dump of the object.
@@ -344,12 +496,11 @@ class FinalizedDumpAble(Base):
         return self
 
 
-class CensoredAble(ProposedAble, FinalizedDumpAble):
-    """Class that provides a method to censor the object."""
-
-
 class WithDependency(Base):
-    """Class that manages file dependencies."""
+    """Class that manages file dependencies.
+
+    This class includes methods to manage file dependencies required for reading or writing.
+    """
 
     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."""
@@ -437,7 +588,10 @@ class WithDependency(Base):
 
 
 class Vectorizable(Base):
-    """Class that prepares the vectorization of the model."""
+    """Class that prepares the vectorization of the model.
+
+    This class includes methods to prepare the model for vectorization, ensuring it fits within a specified token length.
+    """
 
     def _prepare_vectorization_inner(self) -> str:
         return rtoml.dumps(self.model_dump())
@@ -446,20 +600,29 @@ class Vectorizable(Base):
     def prepare_vectorization(self, max_length: Optional[int] = None) -> str:
         """Prepare the vectorization of the model.
 
+        Args:
+            max_length (Optional[int]): The maximum token length for the vectorization. Defaults to the configuration.
+
         Returns:
             str: The prepared vectorization of the model.
+
+        Raises:
+            ValueError: If the chunk exceeds the maximum sequence length.
         """
         max_length = max_length or configs.embedding.max_sequence_length
         chunk = self._prepare_vectorization_inner()
         if max_length and (length := token_counter(text=chunk)) > max_length:
-            logger.error(err := f"Chunk exceeds maximum sequence length {max_length}, got {length},see {chunk}")
+            logger.error(err := f"Chunk exceeds maximum sequence length {max_length}, got {length}, see {chunk}")
             raise ValueError(err)
 
         return chunk
 
 
 class ScopedConfig(Base):
-    """Class that manages a scoped configuration."""
+    """Class that manages a scoped configuration.
+
+    This class includes attributes and methods to manage configuration settings scoped to the instance.
+    """
 
     llm_api_endpoint: Optional[HttpUrl] = None
     """The OpenAI API endpoint."""
@@ -517,15 +680,19 @@ class ScopedConfig(Base):
 
     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."""
 
@@ -567,3 +734,91 @@ class ScopedConfig(Base):
                 if (attr := getattr(self, attr_name)) is not None and getattr(other, attr_name) is None:
                     setattr(other, attr_name, attr)
         return self
+
+
+class Patch[T](ProposedAble):
+    """Base class for patches.
+
+    This class provides a base implementation for patches that can be applied to other objects.
+    """
+
+    def apply(self, other: T) -> T:
+        """Apply the patch to another instance.
+
+        Args:
+            other (T): The instance to apply the patch to.
+
+        Returns:
+            T: The instance with the patch applied.
+
+        Raises:
+            ValueError: If a field in the patch is not found in the target instance.
+        """
+        for field in self.__class__.model_fields:
+            if not hasattr(other, field):
+                raise ValueError(f"{field} not found in {other}, are you applying to the wrong type?")
+            setattr(other, field, getattr(self, field))
+        return other
+
+    def as_kwargs(self) -> Dict[str, Any]:
+        """Get the kwargs of the patch."""
+        return self.model_dump()
+
+    @staticmethod
+    def ref_cls() -> Optional[Type[BaseModel]]:
+        """Get the reference class of the model."""
+        return None
+
+    @classmethod
+    def formated_json_schema(cls) -> str:
+        """Get the JSON schema of the model in a formatted string.
+
+        Returns:
+            str: The JSON schema of the model in a formatted string.
+        """
+        my_schema = cls.model_json_schema(schema_generator=UnsortGenerate)
+        if (ref_cls := cls.ref_cls()) is not None:
+            # copy the desc info of each corresponding fields from `ref_cls`
+            for field_name, field_info in cls.model_fields.items():
+                if (ref_field := getattr(ref_cls, field_name, None)) is not None:
+                    if (desc := ref_field.field_info.description) is not None:
+                        my_schema["properties"][field_name]["description"] = desc
+                    if (example := ref_field.field_info.examples) is not None:
+                        my_schema["properties"][field_name]["examples"] = example
+
+        return orjson.dumps(
+            my_schema,
+            option=orjson.OPT_INDENT_2,
+        ).decode()
+
+
+class SequencePatch[T](ProposedUpdateAble):
+    """Base class for patches.
+
+    This class provides a base implementation for patches that can be applied to sequences of objects.
+    """
+
+    tweaked: List[T]
+    """Tweaked content list"""
+
+    def update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance.
+
+        Args:
+            other (Self): The other instance to update from.
+
+        Returns:
+            Self: The current instance with updated attributes.
+        """
+        self.tweaked.clear()
+        self.tweaked.extend(other.tweaked)
+        return self
+
+    @classmethod
+    def default(cls) -> Self:
+        """Defaults to empty list.
+
+        Returns:
+            Self: A new instance with an empty list of tweaks.
+        """
+        return cls(tweaked=[])

fabricatio/models/kwargs_types.py

@@ -1,7 +1,7 @@
 """This module contains the types for the keyword arguments of the methods in the models module."""
 
 from importlib.util import find_spec
-from typing import Any, Dict, Required, TypedDict
+from typing import Any, Dict, List, Optional, Required, TypedDict
 
 from litellm.caching.caching import CacheMode
 from litellm.types.caching import CachingSupportedCallTypes
@@ -95,11 +95,30 @@ class ValidateKwargs[T](GenerateKwargs, total=False):
     such as limiting the number of validation attempts.
     """
 
-    default: T
+    default: Optional[T]
     max_validations: int
     co_extractor: GenerateKwargs
 
 
+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."""
 
@@ -118,22 +137,9 @@ class ReviewKwargs[T](ReviewInnerKwargs[T], total=False):
     topic: Required[str]
 
 
-class CorrectKwargs[T](ReviewKwargs[T], total=False):
-    """Arguments for content correction operations.
-
-    Extends GenerateKwargs with parameters for correcting content based on
-    specific criteria and templates.
-    """
-
-    reference: str
-    supervisor_check: bool
-
-
-class CensoredCorrectKwargs[T](ReviewInnerKwargs[T], total=False):
-    """Arguments for content censorship operations."""
-
+class ReferencedKwargs[T](ValidateKwargs[T], total=False):
+    """Arguments for content review operations."""
     reference: str
-    supervisor_check: bool
 
 
 # noinspection PyTypedDict

fabricatio/models/task.py

@@ -6,13 +6,13 @@ It includes methods to manage the task's lifecycle, such as starting, finishing,
 from asyncio import Queue
 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 ProposedAble, WithBriefing, WithDependency
 from fabricatio.models.utils import TaskStatus
+from fabricatio.rust_instances import TEMPLATE_MANAGER
 from pydantic import Field, PrivateAttr