fabricatio 0.3.14.dev8__cp313-cp313-manylinux_2_34_x86_64.whl → 0.3.15.dev5__cp313-cp313-manylinux_2_34_x86_64.whl

fabricatio/actions/article.py

@@ -2,7 +2,7 @@
 
 from asyncio import gather
 from pathlib import Path
-from typing import Callable, List, Optional
+from typing import Callable, ClassVar, List, Optional
 
 from more_itertools import filter_map
 from pydantic import Field
@@ -15,14 +15,14 @@ from fabricatio.fs import dump_text, safe_text_read
 from fabricatio.journal import logger
 from fabricatio.models.action import Action
 from fabricatio.models.extra.article_essence import ArticleEssence
-from fabricatio.models.extra.article_main import Article
+from fabricatio.models.extra.article_main import Article, ArticleChapter, ArticleSubsection
 from fabricatio.models.extra.article_outline import ArticleOutline
 from fabricatio.models.extra.article_proposal import ArticleProposal
 from fabricatio.models.extra.rule import RuleSet
 from fabricatio.models.kwargs_types import ValidateKwargs
 from fabricatio.models.task import Task
 from fabricatio.models.usages import LLMUsage
-from fabricatio.rust import CONFIG, TEMPLATE_MANAGER, BibManager, detect_language
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER, BibManager, detect_language, word_count
 from fabricatio.utils import ok, wrapp_in_block
 
 
@@ -277,43 +277,139 @@ class LoadArticle(Action):
 class WriteChapterSummary(Action, LLMUsage):
     """Write the chapter summary."""
 
-    output_key: str = "chapter_summaries"
+    ctx_override: ClassVar[bool] = True
 
     paragraph_count: int = 1
+    """The number of paragraphs to generate in the chapter summary."""
 
-    summary_word_count: int = 200
-
+    summary_word_count: int = 120
+    """The number of words to use in each chapter summary."""
+    output_key: str = "summarized_article"
+    """The key under which the summarized article will be stored in the output."""
     summary_title: str = "Chapter Summary"
-    write_to: Optional[Path] = None
+    """The title to be used for the generated chapter summary section."""
+
+    skip_chapters: List[str] = Field(default_factory=list)
+    """A list of chapter titles to skip during summary generation."""
+
+    async def _execute(self, article_path: Path, **cxt) -> Article:
+        article = Article.from_article_file(article_path, article_path.stem)
+
+        chaps = [c for c in article.chapters if c.title not in self.skip_chapters]
+
+        retained_chapters = []
+        # Count chapters before filtering based on section presence,
+        # chaps at this point has already been filtered by self.skip_chapters
+        initial_chaps_for_summary_step_count = len(chaps)
+
+        for chapter_candidate in chaps:
+            if chapter_candidate.sections:  # Check if the sections list is non-empty
+                retained_chapters.append(chapter_candidate)
+            else:
+                # Log c warning for each chapter skipped due to lack of sections
+                logger.warning(
+                    f"Chapter '{chapter_candidate.title}' has no sections and will be skipped for summary generation."
+                )
+
+        chaps = retained_chapters  # Update chaps to only include chapters with sections
 
-    async def _execute(self, article: Article, write_to: Optional[Path] = None, **cxt) -> List[str]:
-        logger.info(";".join(a.title for a in article.chapters))
+        # If chaps is now empty, but there were chapters to consider at the start of this step,
+        # log c specific warning.
+        if not chaps and initial_chaps_for_summary_step_count > 0:
+            raise ValueError("No chapters with sections were found. Please check your input data.")
 
+        # This line was part of the original selection.
+        # It will now log the titles of the chapters that are actually being processed (those with sections).
+        # If 'chaps' is empty, this will result in logger.info(""), which is acceptable.
+        logger.info(";".join(a.title for a in chaps))
         ret = [
-            f"== {self.summary_title}\n{raw}"
+            ArticleSubsection.from_typst_code(self.summary_title, raw)
             for raw in (
                 await self.aask(
                     TEMPLATE_MANAGER.render_template(
                         CONFIG.templates.chap_summary_template,
                         [
                             {
-                                "chapter": a.to_typst_code(),
-                                "title": a.title,
-                                "language": a.language,
+                                "chapter": c.to_typst_code(),
+                                "title": c.title,
+                                "language": c.language,
                                 "summary_word_count": self.summary_word_count,
                                 "paragraph_count": self.paragraph_count,
                             }
-                            for a in article.chapters
+                            for c in chaps
                         ],
                     )
                 )
             )
         ]
 
-        if (to := (self.write_to or write_to)) is not None:
-            dump_text(
-                to,
-                "\n\n\n".join(f"//{a.title}\n\n{s}" for a, s in zip(article.chapters, ret, strict=True)),
+        for c, n in zip(chaps, ret, strict=True):
+            c: ArticleChapter
+            n: ArticleSubsection
+            if c.sections[-1].title == self.summary_title:
+                logger.debug(f"Removing old summary `{self.summary_title}` at {c.title}")
+                c.sections.pop()
+
+            c.sections[-1].subsections.append(n)
+
+        article.update_article_file(article_path)
+
+        dump_text(
+            article_path, safe_text_read(article_path).replace(f"=== {self.summary_title}", f"== {self.summary_title}")
+        )
+        return article
+
+
+class WriteResearchContentSummary(Action, LLMUsage):
+    """Write the research content summary."""
+
+    ctx_override: ClassVar[bool] = True
+    summary_word_count: int = 160
+    """The number of words to use in the research content summary."""
+
+    output_key: str = "summarized_article"
+    """The key under which the summarized article will be stored in the output."""
+
+    summary_title: str = "Research Content"
+    """The title to be used for the generated research content summary section."""
+
+    paragraph_count: int = 1
+    """The number of paragraphs to generate in the research content summary."""
+
+    async def _execute(self, article_path: Path, **cxt) -> Article:
+        article = Article.from_article_file(article_path, article_path.stem)
+        if not article.chapters:
+            raise ValueError("No chapters found in the article.")
+        chap_1 = article.chapters[0]
+        if not chap_1.sections:
+            raise ValueError("No sections found in the first chapter of the article.")
+
+        outline = article.extrac_outline()
+        suma: str = await self.aask(
+            TEMPLATE_MANAGER.render_template(
+                CONFIG.templates.research_content_summary_template,
+                {
+                    "title": outline.title,
+                    "outline": outline.to_typst_code(),
+                    "language": detect_language(self.summary_title),
+                    "summary_word_count": self.summary_word_count,
+                    "paragraph_count": self.paragraph_count,
+                },
             )
+        )
+        logger.success(
+            f"{self.summary_title}|Wordcount: {word_count(suma)}|Expected: {self.summary_word_count}\n{suma}"
+        )
+
+        if chap_1.sections[-1].title == self.summary_title:
+            # remove old
+            logger.debug(f"Removing old summary `{self.summary_title}`")
+            chap_1.sections.pop()
 
-        return ret
+        chap_1.sections[-1].subsections.append(ArticleSubsection.from_typst_code(self.summary_title, suma))
+
+        article.update_article_file(article_path)
+        dump_text(
+            article_path, safe_text_read(article_path).replace(f"=== {self.summary_title}", f"== {self.summary_title}")
+        )
+        return article

fabricatio/actions/output.py

@@ -3,11 +3,10 @@
 from pathlib import Path
 from typing import Any, Iterable, List, Mapping, Optional, Self, Sequence, Type
 
-from fabricatio.capabilities.persist import PersistentAble
 from fabricatio.fs import dump_text
 from fabricatio.journal import logger
 from fabricatio.models.action import Action
-from fabricatio.models.generic import FinalizedDumpAble, FromMapping, FromSequence
+from fabricatio.models.generic import FinalizedDumpAble, FromMapping, FromSequence, PersistentAble
 from fabricatio.models.task import Task
 from fabricatio.models.usages import LLMUsage
 from fabricatio.rust import TEMPLATE_MANAGER
@@ -21,11 +20,11 @@ class DumpFinalizedOutput(Action, LLMUsage):
     dump_path: Optional[str] = None
 
     async def _execute(
-        self,
-        to_dump: FinalizedDumpAble,
-        task_input: Optional[Task] = None,
-        dump_path: Optional[str | Path] = None,
-        **_,
+            self,
+            to_dump: FinalizedDumpAble,
+            task_input: Optional[Task] = None,
+            dump_path: Optional[str | Path] = None,
+            **_,
     ) -> str:
         dump_path = Path(
             dump_path
@@ -52,11 +51,11 @@ class RenderedDump(Action, LLMUsage):
     """The template name to render the data."""
 
     async def _execute(
-        self,
-        to_dump: FinalizedDumpAble,
-        task_input: Optional[Task] = None,
-        dump_path: Optional[str | Path] = None,
-        **_,
+            self,
+            to_dump: FinalizedDumpAble,
+            task_input: Optional[Task] = None,
+            dump_path: Optional[str | Path] = None,
+            **_,
     ) -> str:
         dump_path = Path(
             dump_path
@@ -91,10 +90,10 @@ class PersistentAll(Action, LLMUsage):
     """Whether to remove the existing dir before dumping."""
 
     async def _execute(
-        self,
-        task_input: Optional[Task] = None,
-        persist_dir: Optional[str | Path] = None,
-        **cxt,
+            self,
+            task_input: Optional[Task] = None,
+            persist_dir: Optional[str | Path] = None,
+            **cxt,
     ) -> int:
         persist_dir = Path(
             persist_dir
@@ -124,7 +123,7 @@ class PersistentAll(Action, LLMUsage):
                 v.persist(final_dir)
                 count += 1
             if isinstance(v, Iterable) and any(
-                persistent_ables := (pers for pers in v if isinstance(pers, PersistentAble))
+                    persistent_ables := (pers for pers in v if isinstance(pers, PersistentAble))
             ):
                 logger.info(f"Persisting collection {k} to {final_dir}")
                 final_dir.mkdir(parents=True, exist_ok=True)
@@ -174,11 +173,11 @@ class RetrieveFromLatest[T: PersistentAble](RetrieveFromPersistent[T], FromMappi
 
     @classmethod
     def from_mapping(
-        cls,
-        mapping: Mapping[str, str | Path],
-        *,
-        retrieve_cls: Type[T],
-        **kwargs,
+            cls,
+            mapping: Mapping[str, str | Path],
+            *,
+            retrieve_cls: Type[T],
+            **kwargs,
     ) -> List["RetrieveFromLatest[T]"]:
         """Create a list of `RetrieveFromLatest` from the mapping."""
         return [

fabricatio/models/extra/article_base.py

@@ -5,7 +5,6 @@ from enum import StrEnum
 from pathlib import Path
 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
@@ -16,12 +15,21 @@ 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
 
@@ -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,15 +310,34 @@ 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(
@@ -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

@@ -2,7 +2,6 @@
 
 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 (
@@ -17,7 +16,7 @@ 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,
@@ -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."""
@@ -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

@@ -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_workflows(self) -> Self:
+    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 dispatch(self) -> Self:
         """Register each workflow in the registry to its corresponding event in the event bus.
 
         Returns:
@@ -63,8 +76,8 @@ 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
 
@@ -74,26 +87,70 @@ class Role(WithBriefing):
         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
+    ) -> 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).
 
-        config_source_for_actions = self
+        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}`"
             )
-            getattr(workflow, config_method_name)(self)
+            # 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
 
-        for action in (act for act in workflow.iter_actions() if has_capability(act.__class__)):
-            getattr(action, config_method_name)(config_source_for_actions)
+        # 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)
+
+        return self
 
-    def _configure_scoped_config(self, workflow: WorkFlow) -> None:
+    def _configure_scoped_config(self, workflow: WorkFlow) -> Self:
         """Configure scoped configuration for workflow and its actions."""
-        self._propagate_config(workflow, is_scoped_config, "fallback_to", "scoped config")
+        return self._propagate_config(workflow, is_scoped_config, "fallback_to", "scoped config")
 
-    def _configure_toolbox_usage(self, workflow: WorkFlow) -> None:
+    def _configure_toolbox_usage(self, workflow: WorkFlow) -> Self:
         """Configure toolbox usage for workflow and its actions."""
-        self._propagate_config(workflow, is_toolbox_usage, "supply_tools_from", "toolbox usage")
+        return self._propagate_config(workflow, is_toolbox_usage, "supply_tools_from", "toolbox usage")

fabricatio/rust.pyi

@@ -339,6 +339,16 @@ def uncomment(string: str) -> str:
         The string with comments (lines starting with '// ' or '//') removed.
     """
 
+def strip_comment(string: str) -> str:
+    """Remove leading and trailing comment lines from a multi-line string.
+
+    Args:
+        string: Input string that may have comment lines at start and/or end
+
+    Returns:
+        str: A new string with leading and trailing comment lines removed
+    """
+
 def split_out_metadata(string: str) -> Tuple[Optional[JsonValue], str]:
     """Split out metadata from a string.
 
@@ -494,6 +504,9 @@ class TemplateManagerConfig:
 class TemplateConfig:
     """Template configuration structure."""
 
+    research_content_summary_template: str
+    """The name of the research content summary template which will be used to generate a summary of research content."""
+
     create_json_obj_template: str
     """The name of the create json object template which will be used to create a json object."""
 

{fabricatio-0.3.14.dev8.dist-info → fabricatio-0.3.15.dev5.dist-info}/METADATA

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: fabricatio
-Version: 0.3.14.dev8
+Version: 0.3.15.dev5
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Framework :: AsyncIO
 Classifier: Framework :: Pydantic :: 2
@@ -185,4 +186,5 @@ Special thanks to the contributors and maintainers of:
 - [PyO3](https://github.com/PyO3/pyo3)
 - [Maturin](https://github.com/PyO3/maturin)
 - [Handlebars.rs](https://github.com/sunng87/handlebars-rust)
+- [LiteLLM](https://github.com/BerriAI/litellm)
 

{fabricatio-0.3.14.dev8.dist-info → fabricatio-0.3.15.dev5.dist-info}/RECORD

@@ -1,14 +1,14 @@
-fabricatio-0.3.14.dev8.data/scripts/tdown,sha256=op_mffGEO0MwNpPoDJVgVwtrHvVHizmgffZG2vc7aXE,4722624
-fabricatio-0.3.14.dev8.data/scripts/ttm,sha256=497Iiu2C1OODIRb-pqOJ9WZdSL7wlHqfTDoPNkINJX8,3918760
-fabricatio-0.3.14.dev8.dist-info/METADATA,sha256=pPky7D10BatBBFi46gZ4JXl6uVfgtnK_-BS5ydzBMlU,4969
-fabricatio-0.3.14.dev8.dist-info/WHEEL,sha256=OZYXF4emuP5o7uCHyen8StXv3k74AF7eDhQe1rxgOqQ,108
-fabricatio-0.3.14.dev8.dist-info/licenses/LICENSE,sha256=yDZaTLnOi03bi3Dk6f5IjhLUc5old2yOsihHWU0z-i0,1067
+fabricatio-0.3.15.dev5.data/scripts/tdown,sha256=kOUNC-Fj426KqvkK1MaOhkmJLpFzpmUadLJiOxMZz1g,4731456
+fabricatio-0.3.15.dev5.data/scripts/ttm,sha256=1NDJgExOy6aW2zbrXLxqVnEyTOLyduDy8_HD3a7oLro,3937688
+fabricatio-0.3.15.dev5.dist-info/METADATA,sha256=lBlJJr7OtXs-u0rItYYYIoOJ4GsLLHrAbqvrQdhchhc,5068
+fabricatio-0.3.15.dev5.dist-info/WHEEL,sha256=OZYXF4emuP5o7uCHyen8StXv3k74AF7eDhQe1rxgOqQ,108
+fabricatio-0.3.15.dev5.dist-info/licenses/LICENSE,sha256=yDZaTLnOi03bi3Dk6f5IjhLUc5old2yOsihHWU0z-i0,1067
 fabricatio/__init__.py,sha256=pSLe6QL4zQGaZXfhF9KW4fa1D8chqCQm_7yInCP6Kt8,732
 fabricatio/actions/__init__.py,sha256=ZMa1LeM5BNeqp-J-D32W-f5bD53-kdXGyt0zuueJofM,47
-fabricatio/actions/article.py,sha256=8ea9QZk7m21j5fw6_CO_znZtik9_o71JmX77Po5gyS4,12188
+fabricatio/actions/article.py,sha256=DtArcKFQM1jp4f3OKPng9ciqY7TmNIUjrjCaZO3OCg8,16695
 fabricatio/actions/article_rag.py,sha256=2lQogjV_1iZkbYI4C9kGGpQH9TBeIDaQCkyi7ueqFus,17582
 fabricatio/actions/fs.py,sha256=nlTmk-tYDW158nz_fzlsNfuYJwj7j4BHn_MFY5hxdqs,934
-fabricatio/actions/output.py,sha256=3VRwDcvimBPrf4ypxbhJd_ScJ_JYiC0ucr6vGOqs9Fc,9687
+fabricatio/actions/output.py,sha256=cLJqeNOhW2vzZB4Tgzh2t09v0flH_eZhDWTxOXUqI7A,9724
 fabricatio/actions/rag.py,sha256=GuRU6VJzIxo3V8dvGWNQ0uQbu6nF0g_qgVuC8NPRx2Y,3487
 fabricatio/actions/rules.py,sha256=07ILsiwR250AUcKLPHTUPpWD_mPhPCfWKSkEAKcPv3A,3557
 fabricatio/capabilities/__init__.py,sha256=skaJ43CqAQaZMH-mCRzF4Fps3x99P2SwJ8vSM9pInX8,56
@@ -18,7 +18,6 @@ fabricatio/capabilities/censor.py,sha256=m90gGDAkEkkxkUKcZNkyhYsRwAxkcDut_-gZEBK
 fabricatio/capabilities/check.py,sha256=eiZZaiX78k-Zt7-Ik43Pn5visXHeOJLk8yLWgtqln40,8379
 fabricatio/capabilities/correct.py,sha256=z7KiMK1KykGXNdLVA0sB28x63LsQ6Hd4wbtYd0bkEKE,10175
 fabricatio/capabilities/extract.py,sha256=eLQagkRnHVLZ64yPBtLVcPELO7ubJlN3fbwoaNMWT70,2449
-fabricatio/capabilities/persist.py,sha256=GAbj93lYLnGVPu74H_ImrINGWNAglIDH9aGSLJKMLkw,3318
 fabricatio/capabilities/propose.py,sha256=KqeXaUURJ6O-Ve0ijZYg88rgQYCZEFbuWoqIepI-nQ8,1965
 fabricatio/capabilities/rag.py,sha256=VSk4BKN8Clwi28-8bz-roqHRln9vu6mGnozr6snaPeY,10930
 fabricatio/capabilities/rating.py,sha256=FSIh3h0E7G1OkBKAkY83VA4w0G6OZ2bXq27b40WRsL8,17411
@@ -35,25 +34,25 @@ fabricatio/models/adv_kwargs_types.py,sha256=nmj1D0GVosZxKcdiw-B5vJB04Whr5zh30ZB
 fabricatio/models/extra/__init__.py,sha256=0R9eZsCNu6OV-Xtf15H7FrqhfHTFBFf3fBrcd7ChsJ0,53
 fabricatio/models/extra/advanced_judge.py,sha256=CKPP4Lseb_Ey8Y7i2V9HJfB-mZgCknFdqq7Zo41o6s4,1060
 fabricatio/models/extra/aricle_rag.py,sha256=KaryVIaMZRV6vpUYwkHDe09tgOihVWGPb1mGs1GXKSw,11723
-fabricatio/models/extra/article_base.py,sha256=GmtgMa--sHSP_H4rJ-6fUxj6tYYfd-m8fOOBDXVyMZQ,16357
-fabricatio/models/extra/article_essence.py,sha256=lAkfGj4Jqiy3dSmtloVVr2krej76TV1Ky-2Fr6pNE_Q,2692
-fabricatio/models/extra/article_main.py,sha256=Lg0cT4SF-0Y9in5LfYU1l9Rq_OnMYH3cCqqEByEnOhE,10817
-fabricatio/models/extra/article_outline.py,sha256=71mgx66KRiXBtdYId4WNkAYp9tJ7OhUqmQyOEe7IRxI,1627
-fabricatio/models/extra/article_proposal.py,sha256=7OgcsS9ujjSi_06Z1ln4SCDQgrS4xPGrtgc2dv8EzGo,1857
+fabricatio/models/extra/article_base.py,sha256=SD1tQdr20Sah4M8yM9r2KSnTRrx9lkM_3Ya1quiolrc,18394
+fabricatio/models/extra/article_essence.py,sha256=OGci-Z4NRvaJdMuS2YUpY425rSozdush6z2LlBoWOpA,2647
+fabricatio/models/extra/article_main.py,sha256=fxIdHEtlPDHCkaZX5azp18V2shloN_h10Gn54ciRUXk,10978
+fabricatio/models/extra/article_outline.py,sha256=K3Ajb86JQSsjo61briVCkIJkqRwvJ46uNU94NCrW-cY,1584
+fabricatio/models/extra/article_proposal.py,sha256=4G2qLkMxtK54G1ANgPW0G3w4Pahxgk2lhGPU5KMxuzw,1818
 fabricatio/models/extra/patches.py,sha256=_ghmnlvTZQq7UJyaH77mTZE9abjvxRJ2mgWHUbezUls,977
 fabricatio/models/extra/problem.py,sha256=1Sd8hsThQK6pXMXhErRhP1ft58z4PvqeB8AV8VcXiaI,7051
 fabricatio/models/extra/rag.py,sha256=fwyEXOECQNe8LPUKGAxEcp9vp7o5356rna-TzGpkvnE,3869
-fabricatio/models/extra/rule.py,sha256=TYtA_aSgunw8wRS3BfdNqBZbbdeS-VXLbVCJhz85Suk,2617
-fabricatio/models/generic.py,sha256=dGap-ckYy7ZX_lXDNxv4d3yM45vdoLDYW4cl49BbCAY,27061
+fabricatio/models/extra/rule.py,sha256=b756_XmWeDoJ1qOFEGy6ZfP8O7rBjOZs4XvfZvWKXXI,2574
+fabricatio/models/generic.py,sha256=GTJV5uToM0OFe19B-UgCmM6OFQ7lMg93O7WIcdp_3IA,30092
 fabricatio/models/kwargs_types.py,sha256=VrzAJaOSlQ-xN5NIIi3k4KpIY0c9beuxcuUnF-mkEEk,3282
-fabricatio/models/role.py,sha256=KxiP_hsIP85QtJhOQL_UH0lKul87hqRcd49IdWr05qQ,4154
+fabricatio/models/role.py,sha256=n1vOr6HZH-7-rSYarnJdDKsR1OmGSMXkCmXudAHeOqs,7337
 fabricatio/models/task.py,sha256=CdR1Zbf-lZN0jODj9iriTn1X2DxLxjXlvZgy3kEd6lI,10723
 fabricatio/models/tool.py,sha256=jYdN6FWEz6pE-vEh3H78VHDPpSttUQE79nfXOD4FE6U,12091
 fabricatio/models/usages.py,sha256=bpM-a9i-WpSOh-XL3LiYTa3AxQUd_ckn44lh-uuKM6M,32250
 fabricatio/parser.py,sha256=3vT5u5SGpzDH4WLJdMwK5CP8RqO4g1MyQUYpiDKDoEo,4528
 fabricatio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-fabricatio/rust.cpython-313-x86_64-linux-gnu.so,sha256=xzXBPe9ePywwC0nHRFo7mouBTKUerBYu1YotXCT3NJU,7904464
-fabricatio/rust.pyi,sha256=czqdl3jgSjmF05T_mUK6wwzpLaPEXQIFGHckRmuYspA,25026
+fabricatio/rust.cpython-313-x86_64-linux-gnu.so,sha256=liZlbr9MJ00X9xQONvi6yGBz-Sy3ZA7ruUkZ4U5LXe4,7921600
+fabricatio/rust.pyi,sha256=D-YxXyjvX6d1Y5pkjcvv-EjQvxpkeA7qgcTaaHOtJpY,25491
 fabricatio/toolboxes/__init__.py,sha256=dYm_Gd8XolSU_h4wnkA09dlaLDK146eeFz0CUgPZ8_c,380
 fabricatio/toolboxes/arithmetic.py,sha256=sSTPkKI6-mb278DwQKFO9jKyzc9kCx45xNH7V6bGBpE,1307
 fabricatio/toolboxes/fs.py,sha256=OQMdeokYxSNVrCZJAweJ0cYiK4k2QuEiNdIbS5IHIV8,705
@@ -61,4 +60,4 @@ fabricatio/utils.py,sha256=qvl4R8ThuNIIoBJuR1DGEuWYZ7jRFT_8SRx4I_FA8pU,5298
 fabricatio/workflows/__init__.py,sha256=Lq9pFo2cudwFCrQUUNgSTr1CoU0J1Nw-HNEQN7cHLp8,50
 fabricatio/workflows/articles.py,sha256=ZDV5nqUKRo1GOuuKWeSV7ZI32FYZU7WiTrD4YDuCeEo,945
 fabricatio/workflows/rag.py,sha256=uOZXprD479fUhLA6sYvEM8RWcVcUZXXtP0xRbTMPdHE,509
-fabricatio-0.3.14.dev8.dist-info/RECORD,,
+fabricatio-0.3.15.dev5.dist-info/RECORD,,

fabricatio/capabilities/persist.py

@@ -1,103 +0,0 @@
-"""Persistence capabilities for model instances."""
-
-from abc import ABC
-from datetime import datetime
-from pathlib import Path
-from typing import Optional, Self
-
-from loguru import logger
-
-from fabricatio.fs import safe_text_read
-from fabricatio.models.generic import Base
-from fabricatio.rust import blake3_hash
-
-
-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))