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

fabricatio/__init__.py

@@ -1,36 +1,29 @@
 """Fabricatio is a Python library for building llm app using event-based agent structure."""
 
-from fabricatio import actions, capabilities, toolboxes, workflows
-from fabricatio.core import env
+from fabricatio import actions, capabilities, fs, models, parser, toolboxes, utils, workflows
 from fabricatio.journal import logger
-from fabricatio.models import extra
 from fabricatio.models.action import Action, WorkFlow
-from fabricatio.models.events import Event
 from fabricatio.models.role import Role
 from fabricatio.models.task import Task
 from fabricatio.models.tool import ToolBox
-from fabricatio.parser import Capture, GenericCapture, JsonCapture, PythonCapture
-from fabricatio.rust import BibManager
-from fabricatio.rust_instances import TEMPLATE_MANAGER
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER, Event
 
 __all__ = [
+    "CONFIG",
     "TEMPLATE_MANAGER",
     "Action",
-    "BibManager",
-    "Capture",
     "Event",
-    "GenericCapture",
-    "JsonCapture",
-    "PythonCapture",
     "Role",
     "Task",
     "ToolBox",
     "WorkFlow",
     "actions",
     "capabilities",
-    "env",
-    "extra",
+    "fs",
     "logger",
+    "models",
+    "parser",
     "toolboxes",
+    "utils",
     "workflows",
 ]

fabricatio/actions/article.py

@@ -2,29 +2,27 @@
 
 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
 from rich import print as r_print
 
-from fabricatio import TEMPLATE_MANAGER
 from fabricatio.capabilities.censor import Censor
 from fabricatio.capabilities.extract import Extract
 from fabricatio.capabilities.propose import Propose
-from fabricatio.config import configs
 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 BibManager, detect_language
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER, BibManager, detect_language
 from fabricatio.utils import ok, wrapp_in_block
 
 
@@ -279,43 +277,80 @@ 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
 
-    summary_word_count: int = 200
-
+    summary_word_count: int = 120
+    output_key: str = "summarized_article"
     summary_title: str = "Chapter Summary"
-    write_to: Optional[Path] = None
 
-    async def _execute(self, article: Article, write_to: Optional[Path] = None, **cxt) -> List[str]:
-        logger.info(";".join(a.title for a in article.chapters))
+    skip_chapters: List[str] = Field(default_factory=list)
+
+    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
+
+        # 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:
+            logger.warning(
+                "All chapters considered for summary were skipped as they lack sections. No summaries will be generated for these."
+            )
 
+        # 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(
-                        configs.templates.chap_summary_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:
+                c.sections.pop()
 
-        return ret
+            c.sections[-1].subsections.append(n)
+
+        article.update_article_file(article_path)
+
+        article_string = safe_text_read(article_path)
+        article_string.replace(f"=== {self.summary_title}", f"== {self.summary_title}")
+        dump_text(article_path, article_string)
+        return article

fabricatio/actions/article_rag.py

@@ -6,7 +6,6 @@ from typing import ClassVar, List, Optional
 
 from pydantic import Field, PositiveInt
 
-from fabricatio import BibManager
 from fabricatio.capabilities.advanced_rag import AdvancedRAG
 from fabricatio.capabilities.censor import Censor
 from fabricatio.capabilities.extract import Extract
@@ -21,10 +20,8 @@ from fabricatio.models.extra.article_outline import ArticleOutline
 from fabricatio.models.extra.rule import RuleSet
 from fabricatio.models.kwargs_types import ChooseKwargs, LLMKwargs
 from fabricatio.rust import (
-    convert_all_block_tex,
-    convert_all_inline_tex,
-    convert_to_block_formula,
-    convert_to_inline_formula,
+    BibManager,
+    convert_all_tex_math,
     fix_misplaced_labels,
 )
 from fabricatio.utils import ok
@@ -129,8 +126,7 @@ class WriteArticleContentRAG(Action, Extract, AdvancedRAG):
                 raw_paras = edt
 
             raw_paras = fix_misplaced_labels(raw_paras)
-            raw_paras = convert_all_inline_tex(raw_paras)
-            raw_paras = convert_all_block_tex(raw_paras)
+            raw_paras = convert_all_tex_math(raw_paras)
 
             r_print(raw_paras)
 
@@ -153,8 +149,7 @@ class WriteArticleContentRAG(Action, Extract, AdvancedRAG):
         raw_paras = "\n".join(p for p in raw_paras.splitlines() if p and not p.endswith("**") and not p.startswith("#"))
 
         raw_paras = fix_misplaced_labels(raw_paras)
-        raw_paras = convert_all_inline_tex(raw_paras)
-        raw_paras = convert_all_block_tex(raw_paras)
+        raw_paras = convert_all_tex_math(raw_paras)
 
         return await self.extract_new_subsec(subsec, raw_paras, cm)
 
@@ -261,8 +256,6 @@ class ArticleConsultRAG(Action, AdvancedRAG):
         from questionary import confirm, text
         from rich import print as r_print
 
-        from fabricatio.rust import convert_all_block_tex, convert_all_inline_tex, fix_misplaced_labels
-
         self.target_collection = collection_name or self.safe_target_collection
 
         cm = CitationManager()
@@ -272,8 +265,7 @@ class ArticleConsultRAG(Action, AdvancedRAG):
             if await confirm("Empty the cm?").ask_async():
                 cm.empty()
 
-            req = convert_to_block_formula(req)
-            req = convert_to_inline_formula(req)
+            req = convert_all_tex_math(req)
 
             await self.clued_search(
                 req,
@@ -289,8 +281,7 @@ class ArticleConsultRAG(Action, AdvancedRAG):
             ret = await self.aask(f"{cm.as_prompt()}\n{self.req}\n{req}")
 
             ret = fix_misplaced_labels(ret)
-            ret = convert_all_inline_tex(ret)
-            ret = convert_all_block_tex(ret)
+            ret = convert_all_tex_math(ret)
             ret = cm.apply(ret)
 
             r_print(ret)

fabricatio/actions/output.py

@@ -1,15 +1,16 @@
 """Dump the finalized output to a file."""
 
 from pathlib import Path
-from typing import Any, Iterable, List, Mapping, Optional, Type
+from typing import Any, Iterable, List, Mapping, Optional, Self, Sequence, Type
 
-from fabricatio import TEMPLATE_MANAGER
+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, PersistentAble
+from fabricatio.models.generic import FinalizedDumpAble, FromMapping, FromSequence
 from fabricatio.models.task import Task
 from fabricatio.models.usages import LLMUsage
+from fabricatio.rust import TEMPLATE_MANAGER
 from fabricatio.utils import ok
 
 
@@ -211,3 +212,37 @@ class GatherAsList(Action):
         result = [cxt[k] for k in cxt if k.startswith(self.gather_prefix)]
         logger.debug(f"Gathered {len(result)} items with prefix {self.gather_prefix}")
         return result
+
+
+class Forward(Action, FromMapping, FromSequence):
+    """Forward the object from the context to the output."""
+
+    output_key: str = "forwarded"
+    """Gather the objects from the context as a list."""
+    original: str
+
+    async def _execute(self, *_: Any, **cxt) -> Any:
+        source = cxt.get(self.original)
+        if source is None:
+            logger.warning(f"Original object {self.original} not found in the context")
+        return source
+
+    @classmethod
+    def from_sequence(cls, sequence: Sequence[str], *, original: str, **kwargs: Any) -> List[Self]:
+        """Create a list of `Forward` from the sequence."""
+        return [cls(original=original, output_key=o, **kwargs) for o in sequence]
+
+    @classmethod
+    def from_mapping(cls, mapping: Mapping[str, str | Sequence[str]], **kwargs: Any) -> List[Self]:
+        """Create a list of `Forward` from the mapping."""
+        actions = []
+        for original_key, output_val in mapping.items():
+            if isinstance(output_val, str):
+                actions.append(cls(original=original_key, output_key=output_val, **kwargs))
+            elif isinstance(output_val, Sequence):
+                actions.extend(cls(original=original_key, output_key=output_key, **kwargs) for output_key in output_val)
+            else:
+                logger.warning(
+                    f"Invalid type for output key value in mapping: {type(output_val)} for original key {original_key}. Expected str or Sequence[str]."
+                )
+        return actions

fabricatio/actions/rag.py

@@ -3,11 +3,11 @@
 from typing import List, Optional
 
 from fabricatio.capabilities.rag import RAG
-from fabricatio.config import configs
 from fabricatio.journal import logger
 from fabricatio.models.action import Action
 from fabricatio.models.extra.rag import MilvusClassicModel, MilvusDataBase
 from fabricatio.models.task import Task
+from fabricatio.rust import CONFIG
 from fabricatio.utils import ok
 
 
@@ -19,7 +19,7 @@ class InjectToDB(Action, RAG):
     """The name of the collection to inject data into."""
 
     async def _execute[T: MilvusDataBase](
-            self, to_inject: Optional[T] | List[Optional[T]], override_inject: bool = False, **_
+        self, to_inject: Optional[T] | List[Optional[T]], override_inject: bool = False, **_
     ) -> Optional[str]:
         from pymilvus.milvus_client import IndexParams
 
@@ -39,9 +39,9 @@ class InjectToDB(Action, RAG):
             schema=seq[0].as_milvus_schema(
                 ok(
                     self.milvus_dimensions
-                    or configs.rag.milvus_dimensions
+                    or CONFIG.rag.milvus_dimensions
                     or self.embedding_dimensions
-                    or configs.embedding.dimensions
+                    or CONFIG.embedding.dimensions
                 ),
             ),
             index_params=IndexParams(

fabricatio/capabilities/advanced_judge.py

@@ -1,5 +1,6 @@
 """The Capabilities module for advanced judging."""
 
+from abc import ABC
 from typing import Optional, Unpack
 
 from fabricatio.capabilities.propose import Propose
@@ -7,17 +8,13 @@ from fabricatio.models.extra.advanced_judge import JudgeMent
 from fabricatio.models.kwargs_types import ValidateKwargs
 
 
-class AdvancedJudge(Propose):
+class AdvancedJudge(Propose, ABC):
     """A class that judges the evidence and makes a final decision."""
+
     async def evidently_judge(
         self,
         prompt: str,
         **kwargs: Unpack[ValidateKwargs[JudgeMent]],
     ) -> Optional[JudgeMent]:
         """Judge the evidence and make a final decision."""
-        return await self.propose(
-            JudgeMent,
-            prompt,
-            **kwargs
-        )
-
+        return await self.propose(JudgeMent, prompt, **kwargs)

fabricatio/capabilities/advanced_rag.py

@@ -1,5 +1,6 @@
 """Advanced RAG (Retrieval Augmented Generation) model."""
 
+from abc import ABC
 from typing import Optional, Unpack
 
 from fabricatio.capabilities.rag import RAG
@@ -10,7 +11,7 @@ from fabricatio.models.kwargs_types import ChooseKwargs
 from fabricatio.utils import fallback_kwargs
 
 
-class AdvancedRAG(RAG):
+class AdvancedRAG(RAG, ABC):
     """A class representing the Advanced RAG (Retrieval Augmented Generation) model."""
 
     async def clued_search(

fabricatio/capabilities/censor.py

@@ -4,6 +4,7 @@ This module includes the Censor class which inherits from both Correct and Check
 It provides methods to censor objects and strings by first checking them against a ruleset and then correcting them if necessary.
 """
 
+from abc import ABC
 from typing import Optional, Unpack
 
 from fabricatio.capabilities.check import Check
@@ -16,7 +17,7 @@ from fabricatio.models.kwargs_types import ReferencedKwargs
 from fabricatio.utils import override_kwargs
 
 
-class Censor(Correct, Check):
+class Censor(Correct, Check, ABC):
     """Class to censor objects and strings based on provided rulesets.
 
     Inherits from both Correct and Check classes.
@@ -46,7 +47,7 @@ class Censor(Correct, Check):
         if not imp:
             logger.info(f"No improvement found for `{obj.__class__.__name__}`.")
             return obj
-        logger.info(f'Generated {len(imp)} improvement(s) for `{obj.__class__.__name__}')
+        logger.info(f"Generated {len(imp)} improvement(s) for `{obj.__class__.__name__}")
         return await self.correct_obj(obj, Improvement.gather(*imp), **kwargs)
 
     async def censor_string(
@@ -72,7 +73,7 @@ class Censor(Correct, Check):
         if not imp:
             logger.info("No improvement found for string.")
             return input_text
-        logger.info(f'Generated {len(imp)} improvement(s) for string.')
+        logger.info(f"Generated {len(imp)} improvement(s) for string.")
         return await self.correct_string(input_text, Improvement.gather(*imp), **kwargs)
 
     async def censor_obj_inplace[M: ProposedUpdateAble](
@@ -100,5 +101,5 @@ class Censor(Correct, Check):
         if not imp:
             logger.info(f"No improvement found for `{obj.__class__.__name__}`.")
             return obj
-        logger.info(f'Generated {len(imp)} improvement(s) for `{obj.__class__.__name__}')
+        logger.info(f"Generated {len(imp)} improvement(s) for `{obj.__class__.__name__}")
         return await self.correct_obj_inplace(obj, improvement=Improvement.gather(*imp), **kwargs)

fabricatio/capabilities/check.py

@@ -1,23 +1,22 @@
 """A class that provides the capability to check strings and objects against rules and guidelines."""
 
+from abc import ABC
 from asyncio import gather
 from typing import List, Optional, Unpack
 
-from fabricatio import TEMPLATE_MANAGER
 from fabricatio.capabilities.advanced_judge import AdvancedJudge
 from fabricatio.capabilities.propose import Propose
-from fabricatio.config import configs
 from fabricatio.journal import logger
 from fabricatio.models.extra.patches import RuleSetMetadata
 from fabricatio.models.extra.problem import Improvement
 from fabricatio.models.extra.rule import Rule, RuleSet
 from fabricatio.models.generic import Display, WithBriefing
 from fabricatio.models.kwargs_types import ValidateKwargs
-from fabricatio.rust import detect_language
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER, detect_language
 from fabricatio.utils import override_kwargs
 
 
-class Check(AdvancedJudge, Propose):
+class Check(AdvancedJudge, Propose, ABC):
     """Class for validating strings/objects against predefined rules and guidelines.
 
     This capability combines rule-based judgment and proposal generation to provide
@@ -45,7 +44,7 @@ class Check(AdvancedJudge, Propose):
         rule_reqs = (
             await self.alist_str(
                 TEMPLATE_MANAGER.render_template(
-                    configs.templates.ruleset_requirement_breakdown_template,
+                    CONFIG.templates.ruleset_requirement_breakdown_template,
                     {"ruleset_requirement": ruleset_requirement},
                 ),
                 rule_count,
@@ -61,7 +60,7 @@ class Check(AdvancedJudge, Propose):
         rules = await self.propose(
             Rule,
             [
-                TEMPLATE_MANAGER.render_template(configs.templates.rule_requirement_template, {"rule_requirement": r})
+                TEMPLATE_MANAGER.render_template(CONFIG.templates.rule_requirement_template, {"rule_requirement": r})
                 for r in rule_reqs
             ],
             **kwargs,
@@ -112,7 +111,7 @@ class Check(AdvancedJudge, Propose):
             return await self.propose(
                 Improvement,
                 TEMPLATE_MANAGER.render_template(
-                    configs.templates.check_string_template,
+                    CONFIG.templates.check_string_template,
                     {"to_check": input_text, "rule": rule.display(), "judge": judge.display(), "reference": reference},
                 ),
                 **kwargs,

fabricatio/capabilities/correct.py

@@ -1,11 +1,11 @@
 """A module containing the Correct capability for reviewing, validating, and improving objects."""
 
+from abc import ABC
 from asyncio import gather
 from typing import Optional, Type, Unpack, cast
 
 from fabricatio.capabilities.propose import Propose
 from fabricatio.capabilities.rating import Rating
-from fabricatio.config import configs
 from fabricatio.journal import logger
 from fabricatio.models.adv_kwargs_types import CorrectKwargs
 from fabricatio.models.extra.problem import Improvement, ProblemSolutions
@@ -14,11 +14,11 @@ from fabricatio.models.kwargs_types import (
     BestKwargs,
     ValidateKwargs,
 )
-from fabricatio.rust_instances import TEMPLATE_MANAGER
+from fabricatio.rust import CONFIG, TEMPLATE_MANAGER
 from fabricatio.utils import fallback_kwargs, ok, override_kwargs
 
 
-class Correct(Rating, Propose):
+class Correct(Rating, Propose, ABC):
     """A class that provides the capability to correct objects."""
 
     async def decide_solution(
@@ -92,7 +92,7 @@ class Correct(Rating, Propose):
         return await self.propose(
             cast("Type[M]", obj.__class__),
             TEMPLATE_MANAGER.render_template(
-                configs.templates.fix_troubled_obj_template,
+                CONFIG.templates.fix_troubled_obj_template,
                 {
                     "problem": problem_solutions.problem.display(),
                     "solution": ok(
@@ -125,7 +125,7 @@ class Correct(Rating, Propose):
         """
         return await self.ageneric_string(
             TEMPLATE_MANAGER.render_template(
-                configs.templates.fix_troubled_string_template,
+                CONFIG.templates.fix_troubled_string_template,
                 {
                     "problem": problem_solutions.problem.display(),
                     "solution": ok(

fabricatio/capabilities/extract.py

@@ -1,15 +1,16 @@
 """A module that provide capabilities for extracting information from a given source to a model."""
 
+from abc import ABC
 from typing import List, Optional, Type, Unpack, overload
 
 from fabricatio import TEMPLATE_MANAGER
 from fabricatio.capabilities.propose import Propose
-from fabricatio.config import configs
 from fabricatio.models.generic import ProposedAble
 from fabricatio.models.kwargs_types import ValidateKwargs
+from fabricatio.rust import CONFIG
 
 
-class Extract(Propose):
+class Extract(Propose, ABC):
     """A class that extract information from a given source to a model."""
 
     @overload
@@ -21,6 +22,7 @@ class Extract(Propose):
         align_language: bool = True,
         **kwargs: Unpack[ValidateKwargs[M]],
     ) -> M: ...
+
     @overload
     async def extract[M: ProposedAble](
         self,
@@ -40,6 +42,7 @@ class Extract(Propose):
         align_language: bool = True,
         **kwargs: Unpack[ValidateKwargs[M]],
     ) -> List[M]: ...
+
     @overload
     async def extract[M: ProposedAble](
         self,
@@ -49,6 +52,7 @@ class Extract(Propose):
         align_language: bool = True,
         **kwargs: Unpack[ValidateKwargs[None]],
     ) -> List[Optional[M]]: ...
+
     async def extract[M: ProposedAble](
         self,
         cls: Type[M],
@@ -61,7 +65,7 @@ class Extract(Propose):
         return await self.propose(
             cls,
             prompt=TEMPLATE_MANAGER.render_template(
-                configs.templates.extract_template,
+                CONFIG.templates.extract_template,
                 [{"source": s, "extract_requirement": extract_requirement} for s in source]
                 if isinstance(source, list)
                 else {"source": source, "extract_requirement": extract_requirement, "align_language": align_language},

fabricatio/capabilities/persist.py

@@ -0,0 +1,103 @@
+"""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))