fabricatio 0.3.13__cp312-cp312-win_amd64.whl → 0.3.14__cp312-cp312-win_amd64.whl

fabricatio/models/generic.py

@@ -1,18 +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.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 litellm.utils import token_counter
+from fabricatio.utils import ok
 from pydantic import (
     BaseModel,
     ConfigDict,
     Field,
-    HttpUrl,
     NonNegativeFloat,
     PositiveFloat,
     PositiveInt,
@@ -21,14 +22,8 @@ from pydantic import (
 )
 from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
 
-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.utils import ok
 
-
-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.
@@ -74,13 +69,13 @@ class Display(Base):
             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 ---"
+            "--- Start of Extra Info Sequence ---"
+            + "\n".join(d.compact() if compact else d.display() for d in seq)
+            + "--- End of Extra Info Sequence ---"
         )
 
 
-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,19 +98,24 @@ 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:
     """Class that provides a method to generate a list of objects from a mapping."""
@@ -126,6 +126,15 @@ class FromMapping:
         """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.
 
@@ -155,7 +164,7 @@ class AsPrompt:
         """
 
 
-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.
@@ -178,16 +187,13 @@ class WithRef[T](Base):
         )
 
     @overload
-    def update_ref[S: WithRef](self: S, reference: T) -> S:
-        ...
+    def update_ref[S: WithRef](self: S, reference: T) -> S: ...
 
     @overload
-    def update_ref[S: WithRef](self: S, reference: "WithRef[T]") -> S:
-        ...
+    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: None = None) -> S: ...
 
     def update_ref[S: WithRef](self: S, reference: Union[T, "WithRef[T]", None] = None) -> S:
         """Update the reference of the object.
@@ -205,97 +211,6 @@ class WithRef[T](Base):
         return self
 
 
-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:
     """Class that provides a language attribute."""
 
@@ -311,7 +226,7 @@ class Language:
         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.
@@ -326,7 +241,7 @@ class ModelHash(Base):
         return hash(self.model_dump_json())
 
 
-class UpdateFrom:
+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.
@@ -375,7 +290,7 @@ class UpdateFrom:
         return self.update_pre_check(other).update_from_inner(other)
 
 
-class Introspect:
+class Introspect(ABC):
     """Class that provides a method to introspect the object.
 
     This class includes a method to perform internal introspection of the object.
@@ -390,7 +305,7 @@ class Introspect:
         """
 
 
-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.
@@ -425,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.
@@ -443,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.
@@ -481,7 +396,7 @@ class CreateJsonObjPrompt(WithFormatedJsonSchema):
         ]
 
 
-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.
@@ -497,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.
@@ -523,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.
@@ -550,7 +467,7 @@ class FinalizedDumpAble(Base):
         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.
@@ -643,7 +560,7 @@ class WithDependency(Base):
         )
 
 
-class Vectorizable:
+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.
@@ -666,6 +583,8 @@ class Vectorizable:
         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:
@@ -674,14 +593,14 @@ class Vectorizable:
         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
@@ -726,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
@@ -747,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)
@@ -807,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.
@@ -854,15 +773,14 @@ class Patch[T](ProposedAble):
             # 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"]
+                    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):
+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,46 +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.rust import Event
-from pydantic import Field, ConfigDict
-
-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.generic import WithBriefing
-from fabricatio.models.tool import ToolBox
-from fabricatio.models.usages import ToolBoxUsage
+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
     """
-    # fixme: not use arbitrary_types_allowed
+
     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:
@@ -50,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
 
@@ -67,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")

fabricatio/models/task.py

@@ -6,12 +6,11 @@ It includes methods to manage the task's lifecycle, such as starting, finishing,
 from asyncio import Queue
 from typing import Any, Dict, List, Optional, Self, Union
 
-from fabricatio.rust import CONFIG, TEMPLATE_MANAGER, Event, TaskStatus
-from pydantic import Field, PrivateAttr
-
-from fabricatio.core import env
+from fabricatio.emitter import env
 from fabricatio.journal import logger
 from fabricatio.models.generic import ProposedAble, WithBriefing, WithDependency
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER, Event, TaskStatus
+from pydantic import Field, PrivateAttr
 
 type EventLike = Union[str, Event, List[str]]
 

fabricatio/models/tool.py

@@ -10,12 +10,11 @@ from inspect import iscoroutinefunction, signature
 from types import CodeType, ModuleType
 from typing import Any, Callable, Dict, List, Optional, Self, cast, overload
 
-from fabricatio.rust import CONFIG
-from pydantic import BaseModel, ConfigDict, Field
-
 from fabricatio.decorators import logging_execution_info, use_temp_module
 from fabricatio.journal import logger
-from fabricatio.models.generic import WithBriefing
+from fabricatio.models.generic import Base, WithBriefing
+from fabricatio.rust import CONFIG
+from pydantic import Field
 
 
 class Tool[**P, R](WithBriefing):
@@ -182,7 +181,7 @@ class ToolBox(WithBriefing):
         return hash(self.briefing)
 
 
-class ToolExecutor(BaseModel):
+class ToolExecutor(Base):
     """A class representing a tool executor with a sequence of tools to execute.
 
     This class manages a sequence of tools and provides methods to inject tools and data into a module, execute the tools,
@@ -192,7 +191,7 @@ class ToolExecutor(BaseModel):
         candidates (List[Tool]): The sequence of tools to execute.
         data (Dict[str, Any]): The data that could be used when invoking the tools.
     """
-    model_config = ConfigDict(use_attribute_docstrings=True)
+
     candidates: List[Tool] = Field(default_factory=list, frozen=True)
     """The sequence of tools to execute."""
 
@@ -230,7 +229,7 @@ class ToolExecutor(BaseModel):
             M: The module with injected data.
         """
         module = module or cast(
-            'M', module_from_spec(spec=ModuleSpec(name=CONFIG.toolbox.data_module_name, loader=None))
+            "M", module_from_spec(spec=ModuleSpec(name=CONFIG.toolbox.data_module_name, loader=None))
         )
         for key, value in self.data.items():
             logger.debug(f"Injecting data: {key}")