fabricatio 0.3.14.dev1__cp312-cp312-win_amd64.whl → 0.3.14.dev2__cp312-cp312-win_amd64.whl

fabricatio/models/extra/aricle_rag.py

@@ -5,17 +5,16 @@ from itertools import groupby
 from pathlib import Path
 from typing import ClassVar, Dict, List, Optional, Self, Unpack
 
-from fabricatio.rust import BibManager, blake3_hash, split_into_chunks
-from more_itertools.more import first
-from more_itertools.recipes import flatten, unique
-from pydantic import Field
-
 from fabricatio.fs import safe_text_read
 from fabricatio.journal import logger
 from fabricatio.models.extra.rag import MilvusDataBase
 from fabricatio.models.generic import AsPrompt
 from fabricatio.models.kwargs_types import ChunkKwargs
+from fabricatio.rust import BibManager, blake3_hash, split_into_chunks
 from fabricatio.utils import ok, wrapp_in_block
+from more_itertools.more import first
+from more_itertools.recipes import flatten, unique
+from pydantic import Field
 
 
 class ArticleChunk(MilvusDataBase):
@@ -56,6 +55,7 @@ class ArticleChunk(MilvusDataBase):
 
     @property
     def reference_header(self) -> str:
+        """Get the reference header."""
         return f"[[{ok(self._cite_number, 'You need to update cite number first.')}]] reference `{self.article_title}` from {self.as_auther_seq()}"
 
     @property
@@ -68,7 +68,7 @@ class ArticleChunk(MilvusDataBase):
 
     @classmethod
     def from_file[P: str | Path](
-            cls, path: P | List[P], bib_mgr: BibManager, **kwargs: Unpack[ChunkKwargs]
+        cls, path: P | List[P], bib_mgr: BibManager, **kwargs: Unpack[ChunkKwargs]
     ) -> List[Self]:
         """Load the article chunks from the file."""
         if isinstance(path, list):
@@ -85,9 +85,9 @@ class ArticleChunk(MilvusDataBase):
         title_seg = path.stem.split(" - ").pop()
 
         key = (
-                bib_mgr.get_cite_key_by_title(title_seg)
-                or bib_mgr.get_cite_key_by_title_fuzzy(title_seg)
-                or bib_mgr.get_cite_key_fuzzy(path.stem)
+            bib_mgr.get_cite_key_by_title(title_seg)
+            or bib_mgr.get_cite_key_by_title_fuzzy(title_seg)
+            or bib_mgr.get_cite_key_fuzzy(path.stem)
         )
         if key is None:
             logger.warning(f"no cite key found for {path.as_posix()}, skip.")
@@ -179,7 +179,7 @@ class CitationManager(AsPrompt):
     """Separator for abbreviated citation numbers."""
 
     def update_chunks(
-            self, article_chunks: List[ArticleChunk], set_cite_number: bool = True, dedup: bool = True
+        self, article_chunks: List[ArticleChunk], set_cite_number: bool = True, dedup: bool = True
     ) -> Self:
         """Update article chunks."""
         self.article_chunks.clear()
@@ -218,8 +218,9 @@ class CitationManager(AsPrompt):
     def _as_prompt_inner(self) -> Dict[str, str]:
         """Generate prompt inner representation."""
         seg = []
-        for k, g in groupby(self.article_chunks, key=lambda a: a.bibtex_cite_key):
-            g = list(g)
+        for k, g_iter in groupby(self.article_chunks, key=lambda a: a.bibtex_cite_key):
+            g = list(g_iter)
+
             logger.debug(f"Group [{k}]: {len(g)}")
             seg.append(wrapp_in_block("\n\n".join(a.chunk for a in g), first(g).reference_header))
         return {"References": "\n".join(seg)}
@@ -277,5 +278,7 @@ class CitationManager(AsPrompt):
         return "".join(a.as_typst_cite() for a in chunk_seq.values())
 
     def as_milvus_filter_expr(self, blacklist: bool = True) -> str:
+        """Asynchronously fetches documents from a Milvus database based on input vectors."""
         if blacklist:
             return " and ".join(f'bibtex_cite_key != "{a.bibtex_cite_key}"' for a in self.article_chunks)
+        return " or ".join(f'bibtex_cite_key == "{a.bibtex_cite_key}"' for a in self.article_chunks)

fabricatio/models/extra/article_base.py

@@ -5,9 +5,7 @@ from enum import StrEnum
 from pathlib import Path
 from typing import ClassVar, Generator, List, Optional, Self, Tuple, Type
 
-from fabricatio.rust import extract_body, inplace_update, split_out_metadata, to_metadata, word_count
-from pydantic import Field
-
+from fabricatio.capabilities.persist import PersistentAble
 from fabricatio.fs import dump_text, safe_text_read
 from fabricatio.fs.readers import extract_sections
 from fabricatio.journal import logger
@@ -18,13 +16,14 @@ from fabricatio.models.generic import (
     Introspect,
     Language,
     ModelHash,
-    PersistentAble,
     ProposedUpdateAble,
     SketchedAble,
     Titled,
     WordCount,
 )
+from fabricatio.rust import extract_body, inplace_update, split_out_metadata, to_metadata, word_count
 from fabricatio.utils import fallback_kwargs, ok
+from pydantic import Field
 
 ARTICLE_WRAPPER = "// =-=-=-=-=-=-=-=-=-="
 
@@ -276,7 +275,7 @@ class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, FromTypstCode, To
         )
 
     def iter_dfs_rev(
-            self,
+        self,
     ) -> Generator[ArticleOutlineBase, None, None]:
         """Performs a depth-first search (DFS) through the article structure in reverse order.
 

fabricatio/models/extra/article_essence.py

@@ -2,8 +2,9 @@
 
 from typing import List
 
+from fabricatio.capabilities.persist import PersistentAble
 from fabricatio.models.extra.rag import MilvusDataBase
-from fabricatio.models.generic import PersistentAble, SketchedAble
+from fabricatio.models.generic import SketchedAble
 from pydantic import BaseModel
 
 

fabricatio/models/extra/article_main.py

@@ -2,15 +2,7 @@
 
 from typing import ClassVar, Dict, Generator, List, Self, Tuple, Type, override
 
-from fabricatio.rust import (
-    convert_all_block_tex,
-    convert_all_inline_tex,
-    fix_misplaced_labels,
-    split_out_metadata,
-    word_count,
-)
-from pydantic import Field, NonNegativeInt
-
+from fabricatio.capabilities.persist import PersistentAble
 from fabricatio.decorators import precheck_package
 from fabricatio.journal import logger
 from fabricatio.models.extra.article_base import (
@@ -25,7 +17,15 @@ from fabricatio.models.extra.article_outline import (
     ArticleSectionOutline,
     ArticleSubsectionOutline,
 )
-from fabricatio.models.generic import Described, PersistentAble, SequencePatch, SketchedAble, WithRef, WordCount
+from fabricatio.models.generic import Described, SequencePatch, SketchedAble, WithRef, WordCount
+from fabricatio.rust import (
+    convert_all_block_tex,
+    convert_all_inline_tex,
+    fix_misplaced_labels,
+    split_out_metadata,
+    word_count,
+)
+from pydantic import Field, NonNegativeInt
 
 PARAGRAPH_SEP = "\n\n// - - -\n\n"
 
@@ -82,8 +82,8 @@ class ArticleSubsection(SubSectionBase):
         if len(self.paragraphs) == 0:
             summary += f"`{self.__class__.__name__}` titled `{self.title}` have no paragraphs, You should add some!\n"
         if (
-                abs((wc := self.word_count) - self.expected_word_count) / self.expected_word_count
-                > self._max_word_count_deviation
+            abs((wc := self.word_count) - self.expected_word_count) / self.expected_word_count
+            > self._max_word_count_deviation
         ):
             summary += f"`{self.__class__.__name__}` titled `{self.title}` have {wc} words, expected {self.expected_word_count} words!"
 

fabricatio/models/extra/article_outline.py

@@ -2,6 +2,7 @@
 
 from typing import ClassVar, Dict, Type
 
+from fabricatio.capabilities.persist import PersistentAble
 from fabricatio.models.extra.article_base import (
     ArticleBase,
     ChapterBase,
@@ -9,7 +10,7 @@ from fabricatio.models.extra.article_base import (
     SubSectionBase,
 )
 from fabricatio.models.extra.article_proposal import ArticleProposal
-from fabricatio.models.generic import PersistentAble, WithRef
+from fabricatio.models.generic import WithRef
 
 
 class ArticleSubsectionOutline(SubSectionBase):

fabricatio/models/extra/article_proposal.py

@@ -2,11 +2,11 @@
 
 from typing import Dict, List
 
+from fabricatio.capabilities.persist import PersistentAble
 from fabricatio.models.generic import (
     AsPrompt,
     Described,
     Language,
-    PersistentAble,
     SketchedAble,
     Titled,
     WithRef,

fabricatio/models/extra/rag.py

@@ -5,7 +5,7 @@ from functools import partial
 from typing import TYPE_CHECKING, Any, ClassVar, Dict, List, Self, Sequence, Set
 
 from fabricatio.decorators import precheck_package
-from fabricatio.models.generic import Vectorizable
+from fabricatio.models.generic import Base, Vectorizable
 from fabricatio.utils import ok
 from pydantic import JsonValue
 
@@ -18,7 +18,7 @@ if TYPE_CHECKING:
         from pymilvus import CollectionSchema
 
 
-class MilvusDataBase(Vectorizable, ABC):
+class MilvusDataBase(Base, Vectorizable, ABC):
     """A base class for Milvus data."""
 
     primary_field_name: ClassVar[str] = "id"

fabricatio/models/extra/rule.py

@@ -10,7 +10,8 @@ complex rule management systems.
 
 from typing import List, Self, Tuple, Unpack
 
-from fabricatio.models.generic import Language, PersistentAble, SketchedAble, WithBriefing
+from fabricatio.capabilities.persist import PersistentAble
+from fabricatio.models.generic import Language, SketchedAble, WithBriefing
 from more_itertools import flatten
 
 

fabricatio/models/generic.py

@@ -1,12 +1,15 @@
 """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 fabricatio.utils import ok
 from pydantic import (
     BaseModel,
     ConfigDict,
@@ -19,13 +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.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.
@@ -36,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.
@@ -71,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.
@@ -87,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.
@@ -100,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"`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."""
@@ -123,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.
 
@@ -152,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.
@@ -175,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.
@@ -202,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."""
 
@@ -308,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.
@@ -323,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.
@@ -372,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.
@@ -387,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.
@@ -422,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.
@@ -440,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.
@@ -478,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.
@@ -501,14 +419,14 @@ class InstantiateFromString(Base):
         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.
@@ -522,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.
@@ -549,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.
@@ -642,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.
@@ -675,7 +593,7 @@ 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.
@@ -808,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.
@@ -855,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,6 +1,6 @@
 """This module contains the types for the keyword arguments of the methods in the models module."""
 
-from typing import Dict, List, Literal, NotRequired, Optional, Required, TypedDict
+from typing import Dict, List, NotRequired, Optional, Required, TypedDict
 
 
 class ChunkKwargs(TypedDict):
@@ -119,11 +119,3 @@ class ChooseKwargs[T](ValidateKwargs[T], total=False):
     """
 
     k: int
-
-
-class RerankOptions(TypedDict, total=False):
-    """Optional keyword arguments for the rerank method."""
-
-    raw_scores: bool
-    truncate: bool
-    truncation_direction: Literal["Left", "Right"]