fabricatio 0.3.14.dev7__cp313-cp313-win_amd64.whl → 0.3.15.dev5__cp313-cp313-win_amd64.whl

fabricatio/models/extra/article_base.py

@@ -3,10 +3,8 @@
 from abc import ABC
 from enum import StrEnum
 from pathlib import Path
-from pydantic import Field
 from typing import ClassVar, Generator, List, Optional, Self, Tuple, Type
 
-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
@@ -17,13 +15,23 @@ from fabricatio.models.generic import (
     Introspect,
     Language,
     ModelHash,
+    PersistentAble,
     ProposedUpdateAble,
     SketchedAble,
     Titled,
     WordCount,
 )
-from fabricatio.rust import extract_body, replace_thesis_body, split_out_metadata, to_metadata, word_count
+from fabricatio.rust import (
+    detect_language,
+    extract_body,
+    replace_thesis_body,
+    split_out_metadata,
+    strip_comment,
+    to_metadata,
+    word_count,
+)
 from fabricatio.utils import fallback_kwargs, ok
+from pydantic import Field
 
 ARTICLE_WRAPPER = "// =-=-=-=-=-=-=-=-=-="
 
@@ -52,10 +60,32 @@ class ArticleMetaData(SketchedAble, Described, WordCount, Titled, Language):
     aims: List[str]
     """List of writing aims of the research component in academic style."""
 
+    _unstructured_body: str = ""
+    """Store the source of the unknown information."""
+
     @property
     def typst_metadata_comment(self) -> str:
         """Generates a comment for the metadata of the article component."""
-        return to_metadata(self.model_dump(include={"description", "aims", "expected_word_count"}, by_alias=True))
+        data = self.model_dump(
+            include={"description", "aims", "expected_word_count"},
+            by_alias=True,
+        )
+        return to_metadata({k: v for k, v in data.items() if v})
+
+    @property
+    def unstructured_body(self) -> str:
+        """Returns the unstructured body of the article component."""
+        return self._unstructured_body
+
+    def update_unstructured_body[S: "ArticleMetaData"](self: S, body: str) -> S:
+        """Update the unstructured body of the article component."""
+        self._unstructured_body = body
+        return self
+
+    @property
+    def language(self) -> str:
+        """Get the language of the article component."""
+        return detect_language(self.title)
 
 
 class FromTypstCode(ArticleMetaData):
@@ -67,13 +97,8 @@ class FromTypstCode(ArticleMetaData):
         data, body = split_out_metadata(body)
 
         return cls(
-            heading=title,
-            **fallback_kwargs(
-                data or {},
-                elaboration="",
-                expected_word_count=word_count(body),
-                aims=[],
-            ),
+            heading=title.strip(),
+            **fallback_kwargs(data or {}, elaboration="", expected_word_count=word_count(body), aims=[]),
             **kwargs,
         )
 
@@ -83,7 +108,7 @@ class ToTypstCode(ArticleMetaData):
 
     def to_typst_code(self) -> str:
         """Converts the component into a Typst code snippet for rendering."""
-        return f"{self.title}\n{self.typst_metadata_comment}\n"
+        return f"{self.title}\n{self.typst_metadata_comment}\n\n{self._unstructured_body}"
 
 
 class ArticleOutlineBase(
@@ -151,12 +176,16 @@ class SectionBase[T: SubSectionBase](ArticleOutlineBase):
     @classmethod
     def from_typst_code(cls, title: str, body: str, **kwargs) -> Self:
         """Creates an Article object from the given Typst code."""
-        return super().from_typst_code(
-            title,
-            body,
-            subsections=[
-                cls.child_type.from_typst_code(*pack) for pack in extract_sections(body, level=3, section_char="=")
-            ],
+        raw = extract_sections(body, level=3, section_char="=")
+
+        return (
+            super()
+            .from_typst_code(
+                title,
+                body,
+                subsections=[cls.child_type.from_typst_code(*pack) for pack in raw],
+            )
+            .update_unstructured_body("" if raw else strip_comment(body))
         )
 
     def resolve_update_conflict(self, other: Self) -> str:
@@ -191,6 +220,11 @@ class SectionBase[T: SubSectionBase](ArticleOutlineBase):
             return f"Section `{self.title}` contains no subsections, expected at least one, but got 0, you can add one or more as needed."
         return ""
 
+    @property
+    def exact_word_count(self) -> int:
+        """Returns the exact word count of the article section outline."""
+        return sum(a.exact_word_count for a in self.subsections)
+
 
 class ChapterBase[T: SectionBase](ArticleOutlineBase):
     """Base class for article chapters."""
@@ -206,12 +240,16 @@ class ChapterBase[T: SectionBase](ArticleOutlineBase):
     @classmethod
     def from_typst_code(cls, title: str, body: str, **kwargs) -> Self:
         """Creates an Article object from the given Typst code."""
-        return super().from_typst_code(
-            title,
-            body,
-            sections=[
-                cls.child_type.from_typst_code(*pack) for pack in extract_sections(body, level=2, section_char="=")
-            ],
+        raw_sec = extract_sections(body, level=2, section_char="=")
+
+        return (
+            super()
+            .from_typst_code(
+                title,
+                body,
+                sections=[cls.child_type.from_typst_code(*pack) for pack in raw_sec],
+            )
+            .update_unstructured_body("" if raw_sec else strip_comment(body))
         )
 
     def resolve_update_conflict(self, other: Self) -> str:
@@ -243,6 +281,15 @@ class ChapterBase[T: SectionBase](ArticleOutlineBase):
             return f"Chapter `{self.title}` contains no sections, expected at least one, but got 0, you can add one or more as needed."
         return ""
 
+    @property
+    def exact_word_count(self) -> int:
+        """Calculates the total word count across all sections in the chapter.
+
+        Returns:
+            int: The cumulative word count of all sections.
+        """
+        return sum(a.exact_word_count for a in self.sections)
+
 
 class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, FromTypstCode, ToTypstCode, ABC):
     """Base class for article outlines."""
@@ -263,19 +310,38 @@ class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, FromTypstCode, To
 
     child_type: ClassVar[Type[ChapterBase]]
 
+    @property
+    def language(self) -> str:
+        """Get the language of the article."""
+        if self.title:
+            return super().language
+        return self.chapters[0].language
+
+    @property
+    def exact_word_count(self) -> int:
+        """Calculates the total word count across all chapters in the article.
+
+        Returns:
+            int: The cumulative word count of all chapters.
+        """
+        return sum(ch.exact_word_count for ch in self.chapters)
+
     @classmethod
     def from_typst_code(cls, title: str, body: str, **kwargs) -> Self:
         """Generates an article from the given Typst code."""
-        return super().from_typst_code(
-            title,
-            body,
-            chapters=[
-                cls.child_type.from_typst_code(*pack) for pack in extract_sections(body, level=1, section_char="=")
-            ],
+        raw = extract_sections(body, level=1, section_char="=")
+        return (
+            super()
+            .from_typst_code(
+                title,
+                body,
+                chapters=[cls.child_type.from_typst_code(*pack) for pack in raw],
+            )
+            .update_unstructured_body("" if raw else strip_comment(body))
         )
 
     def iter_dfs_rev(
-            self,
+        self,
     ) -> Generator[ArticleOutlineBase, None, None]:
         """Performs a depth-first search (DFS) through the article structure in reverse order.
 
@@ -350,7 +416,7 @@ class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, FromTypstCode, To
 
     def to_typst_code(self) -> str:
         """Generates the Typst code representation of the article."""
-        return f"// #{super().to_typst_code()}\n\n" + "\n\n".join(a.to_typst_code() for a in self.chapters)
+        return f"// #Title: {super().to_typst_code()}\n" + "\n\n".join(a.to_typst_code() for a in self.chapters)
 
     def finalized_dump(self) -> str:
         """Generates standardized hierarchical markup for academic publishing systems.
@@ -401,11 +467,11 @@ class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, FromTypstCode, To
         """Set all chap, sec, subsec have same word count sum up to be `self.expected_word_count`."""
         return self.avg_chap_wordcount().avg_sec_wordcount().avg_subsec_wordcount()
 
-    def update_article_file(self, file: str | Path) -> Self:
+    def update_article_file[S: "ArticleBase"](self: S, file: str | Path) -> S:
         """Update the article file."""
         file = Path(file)
         string = safe_text_read(file)
-        if updated := replace_thesis_body(string, ARTICLE_WRAPPER, self.to_typst_code()):
+        if updated := replace_thesis_body(string, ARTICLE_WRAPPER, f"\n\n{self.to_typst_code()}\n\n"):
             dump_text(file, updated)
             logger.success(f"Successfully updated {file.as_posix()}.")
         else:
@@ -413,7 +479,7 @@ class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, FromTypstCode, To
         return self
 
     @classmethod
-    def from_article_file[S: "ArticleBase"](cls: Type[S], file: str | Path, title: str) -> S:
+    def from_article_file[S: "ArticleBase"](cls: Type[S], file: str | Path, title: str = "") -> S:
         """Load article from file."""
         file = Path(file)
         string = safe_text_read(file)

fabricatio/models/extra/article_essence.py

@@ -2,9 +2,8 @@
 
 from typing import List
 
-from fabricatio.capabilities.persist import PersistentAble
 from fabricatio.models.extra.rag import MilvusDataBase
-from fabricatio.models.generic import SketchedAble
+from fabricatio.models.generic import PersistentAble, SketchedAble
 from pydantic import BaseModel
 
 
@@ -97,5 +96,3 @@ class ArticleEssence(SketchedAble, PersistentAble, MilvusDataBase):
 
     def _prepare_vectorization_inner(self) -> str:
         return self.compact()
-
-

fabricatio/models/extra/article_main.py

@@ -1,9 +1,7 @@
 """ArticleBase and ArticleSubsection classes for managing hierarchical document components."""
 
-from pydantic import Field, NonNegativeInt
 from typing import ClassVar, Dict, Generator, List, Self, Tuple, Type, override
 
-from fabricatio.capabilities.persist import PersistentAble
 from fabricatio.decorators import precheck_package
 from fabricatio.journal import logger
 from fabricatio.models.extra.article_base import (
@@ -18,13 +16,14 @@ from fabricatio.models.extra.article_outline import (
     ArticleSectionOutline,
     ArticleSubsectionOutline,
 )
-from fabricatio.models.generic import Described, SequencePatch, SketchedAble, WithRef, WordCount
+from fabricatio.models.generic import Described, PersistentAble, SequencePatch, SketchedAble, WithRef, WordCount
 from fabricatio.rust import (
     convert_all_tex_math,
     fix_misplaced_labels,
     split_out_metadata,
     word_count,
 )
+from pydantic import Field, NonNegativeInt
 
 PARAGRAPH_SEP = "// - - -"
 
@@ -52,7 +51,7 @@ class Paragraph(SketchedAble, WordCount, Described):
         return cls(elaboration="", aims=[], expected_word_count=word_count(content), content=content.strip())
 
     @property
-    def exact_wordcount(self) -> int:
+    def exact_word_count(self) -> int:
         """Calculates the exact word count of the content."""
         return word_count(self.content)
 
@@ -70,6 +69,11 @@ class ArticleSubsection(SubSectionBase):
     _max_word_count_deviation: float = 0.3
     """Maximum allowed deviation from the expected word count, as a percentage."""
 
+    @property
+    def exact_word_count(self) -> int:
+        """Calculates the exact word count of all paragraphs in the subsection."""
+        return sum(a.exact_word_count for a in self.paragraphs)
+
     @property
     def word_count(self) -> int:
         """Calculates the total word count of all paragraphs in the subsection."""
@@ -81,8 +85,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!"
 
@@ -273,9 +277,9 @@ class Article(
         err = []
         for chap, sec, subsec in self.iter_subsections():
             for i, p in enumerate(subsec.paragraphs):
-                if p.exact_wordcount <= threshold:
+                if p.exact_word_count <= threshold:
                     err.append(
-                        f"{chap.title}->{sec.title}->{subsec.title}-> Paragraph [{i}] is too short, {p.exact_wordcount} words."
+                        f"{chap.title}->{sec.title}->{subsec.title}-> Paragraph [{i}] is too short, {p.exact_word_count} words."
                     )
 
         return "\n".join(err)

fabricatio/models/extra/article_outline.py

@@ -2,7 +2,6 @@
 
 from typing import ClassVar, Dict, Type
 
-from fabricatio.capabilities.persist import PersistentAble
 from fabricatio.models.extra.article_base import (
     ArticleBase,
     ChapterBase,
@@ -10,7 +9,7 @@ from fabricatio.models.extra.article_base import (
     SubSectionBase,
 )
 from fabricatio.models.extra.article_proposal import ArticleProposal
-from fabricatio.models.generic import WithRef
+from fabricatio.models.generic import PersistentAble, 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/rule.py

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

fabricatio/models/generic.py

@@ -1,6 +1,7 @@
 """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, Sequence, Type, Union, final, overload
 
@@ -114,7 +115,7 @@ class WordCount(Base, ABC):
     @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__}")
+        raise NotImplementedError(f"`exact_word_count` is not implemented for {self.__class__.__name__}")
 
 
 class FromMapping:
@@ -810,3 +811,94 @@ class SequencePatch[T](ProposedUpdateAble, ABC):
             Self: A new instance with an empty list of tweaks.
         """
         return cls(tweaked=[])
+
+
+class PersistentAble(Base, ABC):
+    """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))

fabricatio/models/role.py

@@ -1,7 +1,7 @@
 """Module that contains the Role class for managing workflows and their event registrations."""
 
 from functools import partial
-from typing import Any, Dict, Self
+from typing import Any, Callable, Dict, Self, Type
 
 from fabricatio.emitter import env
 from fabricatio.journal import logger
@@ -30,6 +30,8 @@ class Role(WithBriefing):
 
     registry: Dict[Event, WorkFlow] = Field(default_factory=dict)
     """The registry of events and workflows."""
+    dispatch_on_init: bool = True
+    """Whether to dispatch registered workflows on initialization."""
 
     def model_post_init(self, __context: Any) -> None:
         """Initialize the role by resolving configurations and registering workflows.
@@ -39,9 +41,20 @@ class Role(WithBriefing):
         """
         self.name = self.name or self.__class__.__name__
 
-        self.resolve_configuration().register_workflows()
+        if self.dispatch_on_init:
+            self.resolve_configuration().dispatch()
+
+    def register_workflow(self, event: Event, workflow: WorkFlow) -> Self:
+        """Register a workflow to the role's registry."""
+        if event in self.registry:
+            logger.warning(
+                f"Event `{event.collapse()}` is already registered with workflow "
+                f"`{self.registry[event].name}`. It will be overwritten by `{workflow.name}`."
+            )
+        self.registry[event] = workflow
+        return self
 
-    def register_workflows(self) -> Self:
+    def dispatch(self) -> Self:
         """Register each workflow in the registry to its corresponding event in the event bus.
 
         Returns:
@@ -63,33 +76,81 @@ class Role(WithBriefing):
         """
         for workflow in self.registry.values():
             logger.debug(f"Resolving config for workflow: `{workflow.name}`")
-            self._configure_scoped_config(workflow)
-            self._configure_toolbox_usage(workflow)
+            self._configure_scoped_config(workflow)._configure_toolbox_usage(workflow)
+
             workflow.inject_personality(self.briefing)
         return self
 
-    def _configure_scoped_config(self, workflow: WorkFlow) -> None:
-        """Configure scoped configuration for workflow and its actions."""
-        if not is_scoped_config(self.__class__):
-            return
+    def _propagate_config(
+        self,
+        workflow: WorkFlow,
+        has_capability: Callable[[Type], bool],
+        config_method_name: str,
+        capability_description: str,
+    ) -> Self:
+        """Propagates configuration from the Role to a Workflow and its Actions.
+
+        This method checks if the Role, Workflow, or its Actions possess a specific
+        capability (e.g., being a ScopedConfig or ToolBoxUsage). If they do,
+        a specified configuration method is called on them to apply or inherit
+        settings.
+
+        The configuration flows hierarchically:
+        1. If the Role has the capability, it's the initial source.
+        2. If the Workflow also has the capability, it can inherit from the Role
+           and then becomes the source for its Actions.
+        3. Actions with the capability inherit from the determined source (either
+           Workflow or Role).
 
-        fallback_target = self
-        if is_scoped_config(workflow):
-            workflow.fallback_to(self)
-            fallback_target = workflow
-
-        for action in (a for a in workflow.iter_actions() if is_scoped_config(a)):
-            action.fallback_to(fallback_target)
+        Args:
+            workflow: The WorkFlow instance to configure.
+            has_capability: A callable that takes a Type and returns True if
+                            the type possesses the specific capability, False otherwise.
+            config_method_name: The name of the method to call on an object
+                                (Role, Workflow, Action) to apply the configuration.
+                                For example, "fallback_to" or "supply_tools_from".
+            capability_description: A string describing the capability, used for
+                                    logging purposes (e.g., "scoped config", "toolbox usage").
+        """
+        # This variable will hold the object from which Actions should inherit their configuration.
+        # It could be the Role itself or the Workflow, depending on their capabilities.
+        config_source_for_actions = None
+
+        # Check if the Role itself has the capability.
+        if has_capability(self.__class__):
+            # If the Role has the capability, it becomes the initial source for configuration.
+            config_source_for_actions = self
+
+        # Check if the Workflow has the capability.
+        if has_capability(workflow.__class__):
+            logger.debug(
+                f"Configuring {capability_description} inherited from `{self.name}` for workflow: `{workflow.name}`"
+            )
+            # If the Role was already identified as a config source,
+            # the Workflow an inherit its configuration directly from the Role.
+            if config_source_for_actions is not None:
+                # Call the specified configuration method on the workflow, passing the Role (self) as the source.
+                getattr(workflow, config_method_name)(config_source_for_actions)
+
+            # After potentially inheriting from the Role, the Workflow itself becomes
+            # the source of configuration for its Actions.
+            config_source_for_actions = workflow
+
+        # If a configuration source (either Role or Workflow) has been established:
+        if config_source_for_actions is not None:
+            # Iterate over all actions within the workflow.
+            # Filter for actions that possess the specified capability.
+            for action in (act for act in workflow.iter_actions() if has_capability(act.__class__)):
+                # Call the specified configuration method on the action,
+                # passing the determined config_source_for_actions.
+                getattr(action, config_method_name)(config_source_for_actions)
 
-    def _configure_toolbox_usage(self, workflow: WorkFlow) -> None:
-        """Configure toolbox usage for workflow and its actions."""
-        if not is_toolbox_usage(self.__class__):
-            return
+        return self
 
-        supply_target = self
-        if is_toolbox_usage(workflow):
-            workflow.supply_tools_from(self)
-            supply_target = workflow
+    def _configure_scoped_config(self, workflow: WorkFlow) -> Self:
+        """Configure scoped configuration for workflow and its actions."""
+        return self._propagate_config(workflow, is_scoped_config, "fallback_to", "scoped config")
 
-        for action in (a for a in workflow.iter_actions() if is_toolbox_usage(a)):
-            action.supply_tools_from(supply_target)
+    def _configure_toolbox_usage(self, workflow: WorkFlow) -> Self:
+        """Configure toolbox usage for workflow and its actions."""
+        return self._propagate_config(workflow, is_toolbox_usage, "supply_tools_from", "toolbox usage")