fabricatio 0.2.13.dev3__cp312-cp312-win_amd64.whl → 0.3.14__cp312-cp312-win_amd64.whl

fabricatio/models/generic.py

@@ -1,24 +1,19 @@
 """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, Mapping, Optional, Self, Type, Union, final, overload
+from typing import Any, Callable, Dict, Iterable, List, Mapping, Optional, Self, Sequence, Type, Union, final, overload
 
 import ujson
-from fabricatio.config import configs
+from fabricatio.fs import dump_text
 from fabricatio.fs.readers import safe_text_read
 from fabricatio.journal import logger
-from fabricatio.parser import JsonCapture
-from fabricatio.rust import blake3_hash, detect_language
-from fabricatio.rust_instances import TEMPLATE_MANAGER
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER, blake3_hash, detect_language
 from fabricatio.utils import ok
-from litellm.utils import token_counter
 from pydantic import (
     BaseModel,
     ConfigDict,
     Field,
-    HttpUrl,
     NonNegativeFloat,
     PositiveFloat,
     PositiveInt,
@@ -28,7 +23,7 @@ from pydantic import (
 from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
 
 
-class Base(BaseModel):
+class Base(BaseModel, ABC):
     """Base class for all models with Pydantic configuration.
 
     This class sets up the basic Pydantic configuration for all models in the Fabricatio library.
@@ -39,7 +34,7 @@ class Base(BaseModel):
     model_config = ConfigDict(use_attribute_docstrings=True)
 
 
-class Display(Base):
+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.
@@ -80,7 +75,7 @@ class Display(Base):
         )
 
 
-class Named(Base):
+class Named(Base, ABC):
     """Class that includes a name attribute.
 
     This class adds a name attribute to models, which is intended to be a unique identifier.
@@ -90,7 +85,7 @@ class Named(Base):
     """The name of this object,briefly and conclusively."""
 
 
-class Described(Base):
+class Described(Base, ABC):
     """Class that includes a description attribute.
 
     This class adds a description attribute to models, providing additional context or information.
@@ -103,21 +98,26 @@ class Described(Base):
     this object's intent and application."""
 
 
-class Titled(Base):
+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):
+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"`exact_word_count` is not implemented for {self.__class__.__name__}")
+
 
-class FromMapping(Base):
+class FromMapping:
     """Class that provides a method to generate a list of objects from a mapping."""
 
     @classmethod
@@ -126,7 +126,16 @@ class FromMapping(Base):
         """Generate a list of objects from a mapping."""
 
 
-class AsPrompt(Base):
+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.
@@ -140,7 +149,7 @@ class AsPrompt(Base):
             str: The generated prompt.
         """
         return TEMPLATE_MANAGER.render_template(
-            configs.templates.as_prompt_template,
+            CONFIG.templates.as_prompt_template,
             self._as_prompt_inner(),
         )
 
@@ -155,7 +164,7 @@ class AsPrompt(Base):
         """
 
 
-class WithRef[T](Base):
+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.
@@ -201,112 +210,8 @@ class WithRef[T](Base):
             self._reference = reference  # pyright: ignore [reportAttributeAccessIssue]
         return self
 
-    def derive[S: WithRef](self: S, reference: Any) -> S:
-        """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 providing file persistence capabilities.
 
-    Enables saving model instances to disk with timestamped filenames and loading from persisted files.
-    Implements basic versioning through filename hashing and timestamping.
-    """
-
-    def persist(self, path: str | Path) -> Self:
-        """Save model instance to disk with versioned filename.
-
-        Args:
-            path (str | Path): Target directory or file path. If directory, filename is auto-generated.
-
-        Returns:
-            Self: Current instance for method chaining
-
-        Notes:
-            - Filename format: <ClassName>_<YYYYMMDD_HHMMSS>_<6-char_hash>.json
-            - Hash generated from JSON content ensures uniqueness
-        """
-        p = Path(path)
-        out = self.model_dump_json(indent=1, by_alias=True)
-
-        # Generate a timestamp in the format YYYYMMDD_HHMMSS
-        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-
-        # Generate the hash
-        file_hash = blake3_hash(out.encode())[:6]
-
-        # Construct the file name with timestamp and hash
-        file_name = f"{self.__class__.__name__}_{timestamp}_{file_hash}.json"
-
-        if p.is_dir():
-            p.joinpath(file_name).write_text(out, encoding="utf-8")
-        else:
-            p.mkdir(exist_ok=True, parents=True)
-            p.write_text(out, encoding="utf-8")
-
-        logger.info(f"Persisted `{self.__class__.__name__}` to {p.as_posix()}")
-        return self
-
-    @classmethod
-    def from_latest_persistent(cls, dir_path: str | Path) -> Optional[Self]:
-        """Load most recent persisted instance from directory.
-
-        Args:
-            dir_path (str | Path): Directory containing persisted files
-
-        Returns:
-            Self: Most recently modified instance
-
-        Raises:
-            NotADirectoryError: If path is not a valid directory
-            FileNotFoundError: If no matching files found
-        """
-        dir_path = Path(dir_path)
-        if not dir_path.is_dir():
-            return None
-
-        pattern = f"{cls.__name__}_*.json"
-        files = list(dir_path.glob(pattern))
-
-        if not files:
-            return None
-
-        def _get_timestamp(file_path: Path) -> datetime:
-            stem = file_path.stem
-            parts = stem.split("_")
-            return datetime.strptime(f"{parts[1]}_{parts[2]}", "%Y%m%d_%H%M%S")
-
-        files.sort(key=lambda f: _get_timestamp(f), reverse=True)
-
-        return cls.from_persistent(files.pop(0))
-
-    @classmethod
-    def from_persistent(cls, path: str | Path) -> Self:
-        """Load an instance from a specific persisted file.
-
-        Args:
-            path (str | Path): Path to the JSON file.
-
-        Returns:
-            Self: The loaded instance from the file.
-
-        Raises:
-            FileNotFoundError: If the specified file does not exist.
-            ValueError: If the file content is invalid for the model.
-        """
-        return cls.model_validate_json(safe_text_read(path))
-
-
-class Language(Base):
+class Language:
     """Class that provides a language attribute."""
 
     @property
@@ -318,11 +223,10 @@ class Language(Base):
             return detect_language(self.title)
         if isinstance(self, Named) and self.name:
             return detect_language(self.name)
-
-        return detect_language(self.model_dump_json(by_alias=True))
+        raise RuntimeError(f"Cannot determine language! class that not support language: {self.__class__.__name__}")
 
 
-class ModelHash(Base):
+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.
@@ -337,7 +241,7 @@ class ModelHash(Base):
         return hash(self.model_dump_json())
 
 
-class UpdateFrom(Base):
+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.
@@ -386,25 +290,7 @@ class UpdateFrom(Base):
         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.
-
-    This class includes a method to resolve conflicts when updating the object from another object.
-    """
-
-    @abstractmethod
-    def resolve_update_conflict(self, other: Self) -> str:
-        """Resolve the update conflict between two objects.
-
-        Args:
-            other (Self): The other object to resolve the update conflict with.
-
-        Returns:
-            str: The resolved update conflict.
-        """
-
-
-class Introspect(Base):
+class Introspect(ABC):
     """Class that provides a method to introspect the object.
 
     This class includes a method to perform internal introspection of the object.
@@ -419,7 +305,7 @@ class Introspect(Base):
         """
 
 
-class WithBriefing(Named, Described):
+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.
@@ -454,7 +340,7 @@ class UnsortGenerate(GenerateJsonSchema):
         return value
 
 
-class WithFormatedJsonSchema(Base):
+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.
@@ -472,7 +358,7 @@ class WithFormatedJsonSchema(Base):
         )
 
 
-class CreateJsonObjPrompt(WithFormatedJsonSchema):
+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.
@@ -498,19 +384,19 @@ class CreateJsonObjPrompt(WithFormatedJsonSchema):
         """
         if isinstance(requirement, str):
             return TEMPLATE_MANAGER.render_template(
-                configs.templates.create_json_obj_template,
+                CONFIG.templates.create_json_obj_template,
                 {"requirement": requirement, "json_schema": cls.formated_json_schema()},
             )
         return [
             TEMPLATE_MANAGER.render_template(
-                configs.templates.create_json_obj_template,
+                CONFIG.templates.create_json_obj_template,
                 {"requirement": r, "json_schema": cls.formated_json_schema()},
             )
             for r in requirement
         ]
 
 
-class InstantiateFromString(Base):
+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.
@@ -526,19 +412,21 @@ class InstantiateFromString(Base):
         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):
+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):
+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.
@@ -552,7 +440,7 @@ class ProposedUpdateAble(SketchedAble, UpdateFrom, ABC):
     """
 
 
-class FinalizedDumpAble(Base):
+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.
@@ -575,11 +463,11 @@ class FinalizedDumpAble(Base):
         Returns:
             Self: The current instance of the object.
         """
-        Path(path).write_text(self.finalized_dump(), encoding="utf-8")
+        dump_text(path, self.finalized_dump())
         return self
 
 
-class WithDependency(Base):
+class WithDependency(Base, ABC):
     """Class that manages file dependencies.
 
     This class includes methods to manage file dependencies required for reading or writing.
@@ -655,7 +543,7 @@ class WithDependency(Base):
         from fabricatio.fs import MAGIKA
 
         return TEMPLATE_MANAGER.render_template(
-            configs.templates.dependencies_template,
+            CONFIG.templates.dependencies_template,
             {
                 (pth := Path(p)).name: {
                     "path": pth.as_posix(),
@@ -672,7 +560,7 @@ class WithDependency(Base):
         )
 
 
-class Vectorizable(Base):
+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.
@@ -695,7 +583,9 @@ class Vectorizable(Base):
         Raises:
             ValueError: If the chunk exceeds the maximum sequence length.
         """
-        max_length = max_length or configs.embedding.max_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}")
@@ -703,14 +593,14 @@ class Vectorizable(Base):
         return chunk
 
 
-class ScopedConfig(Base):
+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[HttpUrl] = None
+    llm_api_endpoint: Optional[str] = None
     """The OpenAI API endpoint."""
 
     llm_api_key: Optional[SecretStr] = None
@@ -755,7 +645,7 @@ class ScopedConfig(Base):
     llm_frequency_penalty: Optional[PositiveFloat] = None
     """The frequency penalty of the LLM model."""
 
-    embedding_api_endpoint: Optional[HttpUrl] = None
+    embedding_api_endpoint: Optional[str] = None
     """The OpenAI API endpoint."""
 
     embedding_api_key: Optional[SecretStr] = None
@@ -776,7 +666,7 @@ class ScopedConfig(Base):
     embedding_caching: Optional[bool] = False
     """Whether to cache the embedding result."""
 
-    milvus_uri: Optional[HttpUrl] = Field(default=None)
+    milvus_uri: Optional[str] = Field(default=None)
     """The URI of the Milvus server."""
 
     milvus_token: Optional[SecretStr] = Field(default=None)
@@ -836,7 +726,7 @@ class ScopedConfig(Base):
         return self
 
 
-class Patch[T](ProposedAble):
+class Patch[T](ProposedAble, ABC):
     """Base class for patches.
 
     This class provides a base implementation for patches that can be applied to other objects.
@@ -890,7 +780,7 @@ class Patch[T](ProposedAble):
         return ujson.dumps(my_schema, indent=2, ensure_ascii=False, sort_keys=False)
 
 
-class SequencePatch[T](ProposedUpdateAble):
+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.

fabricatio/models/kwargs_types.py

@@ -1,9 +1,6 @@
 """This module contains the types for the keyword arguments of the methods in the models module."""
 
-from typing import Any, Dict, List, Literal, NotRequired, Optional, Required, TypedDict
-
-from litellm.caching.caching import CacheMode
-from litellm.types.caching import CachingSupportedCallTypes
+from typing import Dict, List, NotRequired, Optional, Required, TypedDict
 
 
 class ChunkKwargs(TypedDict):
@@ -70,7 +67,6 @@ class ValidateKwargs[T](GenerateKwargs, total=False):
     max_validations: int
 
 
-
 class CompositeScoreKwargs(ValidateKwargs[List[Dict[str, float]]], total=False):
     """Arguments for composite score generation operations.
 
@@ -123,52 +119,3 @@ class ChooseKwargs[T](ValidateKwargs[T], total=False):
     """
 
     k: int
-
-
-class CacheKwargs(TypedDict, total=False):
-    """Configuration parameters for the caching system.
-
-    These arguments control the behavior of various caching backends,
-    including in-memory, Redis, S3, and vector database caching options.
-    """
-
-    mode: CacheMode  # when default_on cache is always on, when default_off cache is opt in
-    host: str
-    port: str
-    password: str
-    namespace: str
-    ttl: float
-    default_in_memory_ttl: float
-    default_in_redis_ttl: float
-    similarity_threshold: float
-    supported_call_types: list[CachingSupportedCallTypes]
-    # s3 Bucket, boto3 configuration
-    s3_bucket_name: str
-    s3_region_name: str
-    s3_api_version: str
-    s3_use_ssl: bool
-    s3_verify: bool | str
-    s3_endpoint_url: str
-    s3_aws_access_key_id: str
-    s3_aws_secret_access_key: str
-    s3_aws_session_token: str
-    s3_config: Any
-    s3_path: str
-    redis_semantic_cache_use_async: bool
-    redis_semantic_cache_embedding_model: str
-    redis_flush_size: int
-    redis_startup_nodes: list
-    disk_cache_dir: Any
-    qdrant_api_base: str
-    qdrant_api_key: str
-    qdrant_collection_name: str
-    qdrant_quantization_config: str
-    qdrant_semantic_cache_embedding_model: str
-
-
-class RerankOptions(TypedDict, total=False):
-    """Optional keyword arguments for the rerank method."""
-
-    raw_scores: bool
-    truncate: bool
-    truncation_direction: Literal["Left", "Right"]

fabricatio/models/role.py

@@ -1,44 +1,44 @@
 """Module that contains the Role class for managing workflows and their event registrations."""
 
-from typing import Any, Self, Set
+from functools import partial
+from typing import Any, Callable, Dict, Self, Type
 
-from fabricatio.capabilities.propose import Propose
-from fabricatio.core import env
+from fabricatio.emitter import env
 from fabricatio.journal import logger
 from fabricatio.models.action import WorkFlow
-from fabricatio.models.events import Event
 from fabricatio.models.generic import WithBriefing
-from fabricatio.models.tool import ToolBox
-from fabricatio.models.usages import ToolBoxUsage
-from pydantic import Field
+from fabricatio.rust import Event
+from fabricatio.utils import is_subclass_of_base
+from pydantic import ConfigDict, Field
 
+is_toolbox_usage = partial(is_subclass_of_base, base_module="fabricatio.models.usages", base_name="ToolBoxUsage")
+is_scoped_config = partial(is_subclass_of_base, base_module="fabricatio.models.generic", base_name="ScopedConfig")
 
-class Role(WithBriefing, Propose, ToolBoxUsage):
+
+class Role(WithBriefing):
     """Class that represents a role with a registry of events and workflows.
 
     A Role serves as a container for workflows, managing their registration to events
     and providing them with shared configuration like tools and personality.
-
-    Attributes:
-        registry: Mapping of events to workflows that handle them
-        toolboxes: Set of toolboxes available to this role and its workflows
     """
 
+    model_config = ConfigDict(use_attribute_docstrings=True, arbitrary_types_allowed=True)
+    name: str = ""
+    """The name of the role."""
     description: str = ""
     """A brief description of the role's responsibilities and capabilities."""
 
-    registry: dict[Event | str, WorkFlow] = Field(default_factory=dict)
+    registry: Dict[Event, WorkFlow] = Field(default_factory=dict)
     """The registry of events and workflows."""
 
-    toolboxes: Set[ToolBox] = Field(default_factory=set)
-    """Collection of tools available to this role."""
-
     def model_post_init(self, __context: Any) -> None:
         """Initialize the role by resolving configurations and registering workflows.
 
         Args:
             __context: The context used for initialization
         """
+        self.name = self.name or self.__class__.__name__
+
         self.resolve_configuration().register_workflows()
 
     def register_workflows(self) -> Self:
@@ -48,9 +48,7 @@ class Role(WithBriefing, Propose, ToolBoxUsage):
             Self: The role instance for method chaining
         """
         for event, workflow in self.registry.items():
-            logger.debug(
-                f"Registering workflow: `{workflow.name}` for event: `{Event.instantiate_from(event).collapse()}`"
-            )
+            logger.debug(f"Registering workflow: `{workflow.name}` for event: `{event.collapse()}`")
             env.on(event, workflow.serve)
         return self
 
@@ -65,12 +63,37 @@ class Role(WithBriefing, Propose, ToolBoxUsage):
         """
         for workflow in self.registry.values():
             logger.debug(f"Resolving config for workflow: `{workflow.name}`")
-            (
-                workflow.fallback_to(self)
-                .steps_fallback_to_self()
-                .inject_personality(self.briefing)
-                .supply_tools_from(self)
-                .steps_supply_tools_from_self()
+            self._configure_scoped_config(workflow)
+            self._configure_toolbox_usage(workflow)
+            workflow.inject_personality(self.briefing)
+        return self
+
+    def _propagate_config(
+        self,
+        workflow: WorkFlow,
+        has_capability: Callable[[Type], bool],
+        config_method_name: str,
+        capability_description: str,
+    ) -> None:
+        """Propagates configuration to workflow and its actions if they have a given capability."""
+        if not has_capability(self.__class__):
+            return
+
+        config_source_for_actions = self
+        if has_capability(workflow.__class__):
+            logger.debug(
+                f"Configuring {capability_description} inherited from `{self.name}` for workflow: `{workflow.name}`"
             )
+            getattr(workflow, config_method_name)(self)
+            config_source_for_actions = workflow
 
-        return self
+        for action in (act for act in workflow.iter_actions() if has_capability(act.__class__)):
+            getattr(action, config_method_name)(config_source_for_actions)
+
+    def _configure_scoped_config(self, workflow: WorkFlow) -> None:
+        """Configure scoped configuration for workflow and its actions."""
+        self._propagate_config(workflow, is_scoped_config, "fallback_to", "scoped config")
+
+    def _configure_toolbox_usage(self, workflow: WorkFlow) -> None:
+        """Configure toolbox usage for workflow and its actions."""
+        self._propagate_config(workflow, is_toolbox_usage, "supply_tools_from", "toolbox usage")