fabricatio 0.2.1.dev0__cp313-cp313-win_amd64.whl → 0.3.14.dev5__cp313-cp313-win_amd64.whl

fabricatio/models/generic.py

@@ -1,42 +1,315 @@
-"""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 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 typing import Any, Callable, Dict, Iterable, List, Mapping, Optional, Self, Sequence, Type, Union, final, overload
+
+import ujson
+from fabricatio.fs import dump_text
+from fabricatio.fs.readers import safe_text_read
+from fabricatio.journal import logger
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER, blake3_hash, detect_language
+from fabricatio.utils import ok
 from pydantic import (
     BaseModel,
     ConfigDict,
     Field,
+    NonNegativeFloat,
+    PositiveFloat,
+    PositiveInt,
+    PrivateAttr,
+    SecretStr,
 )
+from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
+
 
+class Base(BaseModel, ABC):
+    """Base class for all models with Pydantic configuration.
 
-class Base(BaseModel):
-    """Base class for all models with Pydantic configuration."""
+    This class sets up the basic Pydantic configuration for all models in the Fabricatio library.
+    The `model_config` uses `use_attribute_docstrings=True` to ensure field descriptions are
+    pulled from the attribute's docstring instead of the default Pydantic behavior.
+    """
 
     model_config = ConfigDict(use_attribute_docstrings=True)
 
 
-class Named(Base):
-    """Class that includes a name attribute."""
+class Display(Base, ABC):
+    """Class that provides formatted JSON representation utilities.
+
+    Provides methods to generate both pretty-printed and compact JSON representations of the model.
+    Used for debugging and logging purposes.
+    """
+
+    def display(self) -> str:
+        """Generate pretty-printed JSON representation.
+
+        Returns:
+            str: JSON string with 1-level indentation for readability
+        """
+        return self.model_dump_json(indent=1, by_alias=True)
+
+    def compact(self) -> str:
+        """Generate compact JSON representation.
+
+        Returns:
+            str: Minified JSON string without whitespace
+        """
+        return self.model_dump_json(by_alias=True)
+
+    @staticmethod
+    def seq_display(seq: Iterable["Display"], compact: bool = False) -> str:
+        """Generate formatted display for sequence of Display objects.
+
+        Args:
+            seq (Iterable[Display]): Sequence of objects to display
+            compact (bool): Use compact format instead of pretty print
+
+        Returns:
+            str: Combined display output with boundary markers
+        """
+        return (
+            "--- Start of Extra Info Sequence ---"
+            + "\n".join(d.compact() if compact else d.display() for d in seq)
+            + "--- End of Extra Info Sequence ---"
+        )
 
-    name: str = Field(frozen=True)
-    """The name of the object."""
 
+class Named(Base, ABC):
+    """Class that includes a name attribute.
 
-class Described(Base):
-    """Class that includes a description attribute."""
+    This class adds a name attribute to models, which is intended to be a unique identifier.
+    """
 
-    description: str = Field(default="", frozen=True)
-    """The description of the object."""
+    name: str
+    """The name of this object,briefly and conclusively."""
 
 
-class WithBriefing(Named, Described):
-    """Class that provides a briefing based on the name and description."""
+class Described(Base, ABC):
+    """Class that includes a description attribute.
+
+    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 Titled(Base, ABC):
+    """Class that includes a title attribute."""
+
+    title: str
+    """The title of this object, make it professional and concise.No prefixed heading number should be included."""
+
+
+class WordCount(Base, ABC):
+    """Class that includes a word count attribute."""
+
+    expected_word_count: int
+    """Expected word count of this research component."""
+
+    @property
+    def exact_word_count(self) -> int:
+        """Get the exact word count of this research component."""
+        raise NotImplementedError(f"`expected_word_count` is not implemented for {self.__class__.__name__}")
+
+
+class FromMapping:
+    """Class that provides a method to generate a list of objects from a mapping."""
+
+    @classmethod
+    @abstractmethod
+    def from_mapping[S](cls: S, mapping: Mapping[str, Any], **kwargs: Any) -> List[S]:
+        """Generate a list of objects from a mapping."""
+
+
+class FromSequence:
+    """Class that provides a method to generate a list of objects from a sequence."""
+
+    @classmethod
+    @abstractmethod
+    def from_sequence[S](cls: S, sequence: Sequence[Any], **kwargs: Any) -> List[S]:
+        """Generate a list of objects from a sequence."""
+
+
+class AsPrompt:
+    """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:
+        """Generate a prompt from the model.
+
+        Returns:
+            str: The generated prompt.
+        """
+        return TEMPLATE_MANAGER.render_template(
+            CONFIG.templates.as_prompt_template,
+            self._as_prompt_inner(),
+        )
+
+    @abstractmethod
+    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, ABC):
+    """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.
+
+        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`?"
+        )
+
+    @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:
+        """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:
+            self._reference = reference  # pyright: ignore [reportAttributeAccessIssue]
+        return self
+
+
+class Language:
+    """Class that provides a language attribute."""
+
+    @property
+    def language(self) -> str:
+        """Get the language of the object."""
+        if isinstance(self, Described) and self.description:
+            return detect_language(self.description)
+        if isinstance(self, Titled) and self.title:
+            return detect_language(self.title)
+        if isinstance(self, Named) and self.name:
+            return detect_language(self.name)
+        raise RuntimeError(f"Cannot determine language! class that not support language: {self.__class__.__name__}")
+
+
+class ModelHash(Base, ABC):
+    """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 object based on its model_dump_json representation.
+
+        Returns:
+            int: The hash value of the object.
+        """
+        return hash(self.model_dump_json())
+
+
+class UpdateFrom(ABC):
+    """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.
+
+        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.")
+
+        return self
+
+    @abstractmethod
+    def update_from_inner(self, other: Self) -> Self:
+        """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.
+
+        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 Introspect(ABC):
+    """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:
+        """Internal introspection of the object.
+
+        Returns:
+            str: The internal introspection of the object.
+        """
+
+
+class WithBriefing(Named, Described, ABC):
+    """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:
@@ -48,24 +321,157 @@ 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 UnsortGenerate(GenerateJsonSchema):
+    """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.
+
+        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, ABC):
+    """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 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()},
-            option=orjson.OPT_INDENT_2 | orjson.OPT_SORT_KEYS,
-        ).decode()
+        return ujson.dumps(
+            cls.model_json_schema(schema_generator=UnsortGenerate), indent=2, ensure_ascii=False, sort_keys=False
+        )
 
 
-class WithDependency(Base):
-    """Class that manages file dependencies."""
+class CreateJsonObjPrompt(WithFormatedJsonSchema, ABC):
+    """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 | List[str]): The requirement for the JSON object.
+
+        Returns:
+            str | List[str]: The prompt for creating a JSON object with given requirement.
+        """
+        if isinstance(requirement, str):
+            return TEMPLATE_MANAGER.render_template(
+                CONFIG.templates.create_json_obj_template,
+                {"requirement": requirement, "json_schema": cls.formated_json_schema()},
+            )
+        return [
+            TEMPLATE_MANAGER.render_template(
+                CONFIG.templates.create_json_obj_template,
+                {"requirement": r, "json_schema": cls.formated_json_schema()},
+            )
+            for r in requirement
+        ]
+
+
+class InstantiateFromString(Base, ABC):
+    """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:
+        """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.
+        """
+        from fabricatio.parser import JsonCapture
+
+        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, ABC):
+    """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, ABC):
+    """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(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, ABC):
+    """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.
+
+        Returns:
+            str: The finalized dump of the object.
+        """
+        return self.model_dump_json(indent=1, by_alias=True)
+
+    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.
+        """
+        dump_text(path, self.finalized_dump())
+        return self
+
+
+class WithDependency(Base, ABC):
+    """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."""
@@ -108,17 +514,25 @@ class WithDependency(Base):
         self.dependencies.clear()
         return self
 
-    def override_dependencies[P: str | Path](self, dependencies: List[P]) -> Self:
+    def override_dependencies[P: str | Path](self, dependencies: List[P] | P) -> Self:
         """Override the file dependencies of the task.
 
         Args:
-            dependencies (List[str | Path]): The file dependencies to override the task's dependencies.
+            dependencies (List[str | Path] | str | Path): The file dependencies to override the task's dependencies.
 
         Returns:
             Self: The current instance of the task.
         """
         return self.clear_dependencies().add_dependency(dependencies)
 
+    def pop_dependence[T](self, idx: int = -1, reader: Callable[[str], T] = safe_text_read) -> T:
+        """Pop the file dependencies from the task.
+
+        Returns:
+            str: The popped file dependency
+        """
+        return reader(self.dependencies.pop(idx))
+
     @property
     def dependencies_prompt(self) -> str:
         """Generate a prompt for the task based on the file dependencies.
@@ -126,13 +540,15 @@ class WithDependency(Base):
         Returns:
             str: The generated prompt for the task.
         """
-        return template_manager.render_template(
-            configs.templates.dependencies_template,
+        from fabricatio.fs import MAGIKA
+
+        return TEMPLATE_MANAGER.render_template(
+            CONFIG.templates.dependencies_template,
             {
                 (pth := Path(p)).name: {
                     "path": pth.as_posix(),
                     "exists": pth.exists(),
-                    "description": (identity := magika.identify_path(pth)).output.description,
+                    "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()),
@@ -142,3 +558,255 @@ class WithDependency(Base):
                 for p in self.dependencies
             },
         )
+
+
+class Vectorizable(ABC):
+    """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.
+    """
+
+    @abstractmethod
+    def _prepare_vectorization_inner(self) -> str:
+        """Prepare the model for vectorization."""
+
+    @final
+    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.
+        """
+        from litellm.utils import token_counter
+
+        max_length = max_length or CONFIG.embedding.max_sequence_length
+        chunk = self._prepare_vectorization_inner()
+        if max_length and (length := token_counter(text=chunk)) > max_length:
+            raise ValueError(f"Chunk exceeds maximum sequence length {max_length}, got {length}, see \n{chunk}")
+
+        return chunk
+
+
+class ScopedConfig(Base, ABC):
+    """Configuration holder with hierarchical fallback mechanism.
+
+    Manages LLM, embedding, and vector database configurations with fallback logic.
+    Allows configuration values to be overridden in a hierarchical manner.
+    """
+
+    llm_api_endpoint: Optional[str] = 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."""
+
+    llm_tpm: Optional[PositiveInt] = None
+    """The tokens per minute of the LLM model."""
+
+    llm_rpm: Optional[PositiveInt] = None
+    """The requests per minute of the LLM model."""
+
+    llm_presence_penalty: Optional[PositiveFloat] = None
+    """The presence penalty of the LLM model."""
+
+    llm_frequency_penalty: Optional[PositiveFloat] = None
+    """The frequency penalty of the LLM model."""
+
+    embedding_api_endpoint: Optional[str] = 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[str] = 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: Union["ScopedConfig", Any]) -> Self:
+        """Merge configuration values with fallback priority.
+
+        Copies non-null values from 'other' to self where current values are None.
+
+        Args:
+            other (ScopedConfig): Configuration to fallback to
+
+        Returns:
+            Self: Current instance with merged values
+        """
+        if not isinstance(other, ScopedConfig):
+            return self
+
+        # 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[Union["ScopedConfig", Any], Iterable[Union["ScopedConfig", Any]]]) -> Self:
+        """Propagate non-null values to other configurations.
+
+        Copies current non-null values to target configurations where they are None.
+
+        Args:
+            others (ScopedConfig|Iterable): Target configurations to update
+
+        Returns:
+            Self: Current instance unchanged
+        """
+        if not isinstance(others, Iterable):
+            others = [others]
+
+        for other in (o for o in others if isinstance(o, ScopedConfig)):
+            # 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)
+        return self
+
+
+class Patch[T](ProposedAble, ABC):
+    """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)
+
+        ref_cls = cls.ref_cls()
+        if ref_cls is not None:
+            # copy the desc info of each corresponding fields from `ref_cls`
+            for field_name in [f for f in cls.model_fields if f in ref_cls.model_fields]:
+                my_schema["properties"][field_name]["description"] = (
+                    ref_cls.model_fields[field_name].description or my_schema["properties"][field_name]["description"]
+                )
+            my_schema["description"] = ref_cls.__doc__
+
+        return ujson.dumps(my_schema, indent=2, ensure_ascii=False, sort_keys=False)
+
+
+class SequencePatch[T](ProposedUpdateAble, ABC):
+    """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=[])