fabricatio 0.2.7.dev3__cp312-cp312-win_amd64.whl → 0.2.7.dev5__cp312-cp312-win_amd64.whl

fabricatio/models/extra/article_main.py

@@ -1,13 +1,22 @@
 """ArticleBase and ArticleSubsection classes for managing hierarchical document components."""
 
-from abc import abstractmethod
 from itertools import chain
-from typing import Generator, List, Self, Tuple, final
-
-from fabricatio.models.extra.article_outline import ArticleOutline, ArticleOutlineBase, ArticleRef
+from typing import Generator, List, Self, Tuple, override
+
+from fabricatio.journal import logger
+from fabricatio.models.extra.article_base import (
+    ArticleBase,
+    ArticleOutlineBase,
+    ArticleRef,
+    ChapterBase,
+    SectionBase,
+    SubSectionBase,
+)
+from fabricatio.models.extra.article_outline import (
+    ArticleOutline,
+)
 from fabricatio.models.generic import CensoredAble, Display, PersistentAble, WithRef
 from fabricatio.models.utils import ok
-from loguru import logger
 
 
 class Paragraph(CensoredAble):
@@ -23,62 +32,19 @@ class Paragraph(CensoredAble):
     """List of sentences forming the paragraph's content."""
 
 
-class ArticleBase(CensoredAble, Display, ArticleOutlineBase, PersistentAble):
-    """Foundation for hierarchical document components with dependency tracking."""
-
-    @abstractmethod
-    def to_typst_code(self) -> str:
-        """Converts the component into a Typst code snippet for rendering."""
-
-    def _update_pre_check(self, other: Self) -> Self:
-        if not isinstance(other, self.__class__):
-            raise TypeError(f"Cannot update from a non-{self.__class__} instance.")
-        if self.title != other.title:
-            raise ValueError("Cannot update from a different title.")
-        return self
-
-    @abstractmethod
-    def resolve_update_error(self, other: Self) -> str:
-        """Resolve update errors in the article outline.
-
-        Returns:
-            str: Error message indicating update errors in the article outline.
-        """
-
-    @abstractmethod
-    def _update_from_inner(self, other: Self) -> Self:
-        """Updates the current instance with the attributes of another instance."""
-
-    @final
-    def update_from(self, other: Self) -> Self:
-        """Updates the current instance with the attributes of another instance."""
-        return self._update_pre_check(other)._update_from_inner(other)
-
-    def __eq__(self, other: "ArticleBase") -> bool:
-        """Compares two ArticleBase objects based on their model_dump_json representation."""
-        return self.model_dump_json() == other.model_dump_json()
-
-    def __hash__(self) -> int:
-        """Calculates a hash value for the ArticleBase object based on its model_dump_json representation."""
-        return hash(self.model_dump_json())
-
-
-class ArticleSubsection(ArticleBase):
+class ArticleSubsection(ArticleOutlineBase, SubSectionBase):
     """Atomic argumentative unit with technical specificity."""
 
     paragraphs: List[Paragraph]
     """List of Paragraph objects containing the content of the subsection."""
 
-    def resolve_update_error(self, other: Self) -> str:
-        """Resolve update errors in the article outline."""
-        if self.title != other.title:
-            return f"Title `{other.title}` mismatched, expected `{self.title}`. "
-        return ""
-
-    def _update_from_inner(self, other: Self) -> Self:
+    def update_from_inner(self, other: Self) -> Self:
         """Updates the current instance with the attributes of another instance."""
         logger.debug(f"Updating SubSection {self.title}")
-        self.paragraphs = other.paragraphs
+        SubSectionBase.update_from(self, other)
+        ArticleOutlineBase.update_from(self, other)
+        self.paragraphs.clear()
+        self.paragraphs.extend(other.paragraphs)
         return self
 
     def to_typst_code(self) -> str:
@@ -90,100 +56,37 @@ class ArticleSubsection(ArticleBase):
         return f"=== {self.title}\n" + "\n\n".join("".join(p.sentences) for p in self.paragraphs)
 
 
-class ArticleSection(ArticleBase):
+class ArticleSection(ArticleOutlineBase, SectionBase[ArticleSubsection]):
     """Atomic argumentative unit with high-level specificity."""
 
-    subsections: List[ArticleSubsection]
-    """List of ArticleSubsection objects containing the content of the section."""
-
-    def resolve_update_error(self, other: Self) -> str:
-        """Resolve update errors in the article outline."""
-        if (s_len := len(self.subsections)) == 0:
-            return ""
-
-        if s_len != len(other.subsections):
-            return f"Subsections length mismatched, expected {len(self.subsections)}, got {len(other.subsections)}"
-
-        sub_sec_err_seq = [
-            out for s, o in zip(self.subsections, other.subsections, strict=True) if (out := s.resolve_update_error(o))
-        ]
-
-        if sub_sec_err_seq:
-            return "\n".join(sub_sec_err_seq)
-        return ""
-
-    def _update_from_inner(self, other: Self) -> Self:
-        """Updates the current instance with the attributes of another instance."""
-        if len(self.subsections) == 0:
-            self.subsections = other.subsections
-            return self
-
-        for self_subsec, other_subsec in zip(self.subsections, other.subsections, strict=True):
-            self_subsec.update_from(other_subsec)
-        return self
-
-    def to_typst_code(self) -> str:
-        """Converts the section into a Typst formatted code snippet.
-
-        Returns:
-            str: The formatted Typst code snippet.
-        """
-        return f"== {self.title}\n" + "\n\n".join(subsec.to_typst_code() for subsec in self.subsections)
 
 
-class ArticleChapter(ArticleBase):
+class ArticleChapter(ArticleOutlineBase, ChapterBase[ArticleSection]):
     """Thematic progression implementing research function."""
 
-    sections: List[ArticleSection]
-    """List of ArticleSection objects containing the content of the chapter."""
 
-    def resolve_update_error(self, other: Self) -> str:
-        """Resolve update errors in the article outline."""
-        if (s_len := len(self.sections)) == 0:
-            return ""
 
-        if s_len != len(other.sections):
-            return f"Sections length mismatched, expected {len(self.sections)}, got {len(other.sections)}"
-        sec_err_seq = [
-            out for s, o in zip(self.sections, other.sections, strict=True) if (out := s.resolve_update_error(o))
-        ]
-        if sec_err_seq:
-            return "\n".join(sec_err_seq)
-        return ""
-
-    def _update_from_inner(self, other: Self) -> Self:
-        """Updates the current instance with the attributes of another instance."""
-        if len(self.sections) == 0:
-            self.sections = other.sections
-            return self
-
-        for self_sec, other_sec in zip(self.sections, other.sections, strict=True):
-            self_sec.update_from(other_sec)
-        return self
-
-    def to_typst_code(self) -> str:
-        """Converts the chapter into a Typst formatted code snippet for rendering."""
-        return f"= {self.title}\n" + "\n\n".join(sec.to_typst_code() for sec in self.sections)
-
-
-class Article(Display, CensoredAble, WithRef[ArticleOutline], PersistentAble):
+class Article(
+    Display,
+    CensoredAble,
+    WithRef[ArticleOutline],
+    PersistentAble,
+    ArticleBase[ArticleChapter],
+):
     """Represents a complete academic paper specification, incorporating validation constraints.
 
     This class integrates display, censorship processing, article structure referencing, and persistence capabilities,
     aiming to provide a comprehensive model for academic papers.
     """
 
-    article_language: str
-    """Written language of the article. SHALL be aligned to the language of the article outline provided."""
+    abstract: str
+    """Contains a summary of the academic paper."""
 
     title: str
     """Represents the title of the academic paper."""
 
-    abstract: str
-    """Contains a summary of the academic paper."""
-
-    chapters: List[ArticleChapter]
-    """Contains a list of chapters in the academic paper, each chapter is an ArticleChapter object."""
+    language: str
+    """Written language of the article. SHALL be aligned to the language of the article outline provided."""
 
     def finalized_dump(self) -> str:
         """Exports the article in `typst` format.
@@ -229,56 +132,24 @@ class Article(Display, CensoredAble, WithRef[ArticleOutline], PersistentAble):
             article.chapters.append(article_chapter)
         return article
 
-    def chap_iter(self) -> Generator[ArticleChapter, None, None]:
-        """Iterates over all chapters in the article.
-
-        Yields:
-            ArticleChapter: Each chapter in the article.
-        """
-        yield from self.chapters
-
-    def section_iter(self) -> Generator[ArticleSection, None, None]:
-        """Iterates over all sections in the article.
-
-        Yields:
-            ArticleSection: Each section in the article.
-        """
-        for chap in self.chapters:
-            yield from chap.sections
-
-    def subsection_iter(self) -> Generator[ArticleSubsection, None, None]:
-        """Iterates over all subsections in the article.
-
-        Yields:
-            ArticleSubsection: Each subsection in the article.
-        """
-        for sec in self.section_iter():
-            yield from sec.subsections
-
-    def iter_dfs(self) -> Generator[ArticleBase, None, None]:
-        """Performs a depth-first search (DFS) through the article structure.
-
-        Returns:
-            Generator[ArticleBase]: Each component in the article structure.
-        """
-        for chap in self.chap_iter():
-            for sec in chap.sections:
-                yield from sec.subsections
-                yield sec
-            yield chap
-
-    def deref(self, ref: ArticleRef) -> ArticleBase:
+    @override
+    def iter_dfs(
+        self,
+    ) -> Generator[ArticleChapter | ArticleSection | ArticleSubsection, None, None]:
+        return super().iter_dfs()
+        
+    def deref(self, ref: ArticleRef) -> ArticleOutlineBase:
         """Resolves a reference to the corresponding section or subsection in the article.
 
         Args:
             ref (ArticleRef): The reference to resolve.
 
         Returns:
-            ArticleBase: The corresponding section or subsection.
+            ArticleOutlineBase: The corresponding section or subsection.
         """
         return ok(ref.deref(self), f"{ref} not found in {self.title}")
 
-    def gather_dependencies(self, article: ArticleBase) -> List[ArticleBase]:
+    def gather_dependencies(self, article: ArticleOutlineBase) -> List[ArticleOutlineBase]:
         """Gathers dependencies for all sections and subsections in the article.
 
         This method should be called after the article is fully constructed.
@@ -292,11 +163,11 @@ class Article(Display, CensoredAble, WithRef[ArticleOutline], PersistentAble):
 
         return list(set(depends + supports))
 
-    def gather_dependencies_recursive(self, article: ArticleBase) -> List[ArticleBase]:
+    def gather_dependencies_recursive(self, article: ArticleOutlineBase) -> List[ArticleOutlineBase]:
         """Gathers all dependencies recursively for the given article.
 
         Args:
-            article (ArticleBase): The article to gather dependencies for.
+            article (ArticleOutlineBase): The article to gather dependencies for.
 
         Returns:
             List[ArticleBase]: A list of all dependencies for the given article.
@@ -335,7 +206,7 @@ class Article(Display, CensoredAble, WithRef[ArticleOutline], PersistentAble):
 
     def iter_dfs_with_deps(
         self, chapter: bool = True, section: bool = True, subsection: bool = True
-    ) -> Generator[Tuple[ArticleBase, List[ArticleBase]], None, None]:
+    ) -> Generator[Tuple[ArticleOutlineBase, List[ArticleOutlineBase]], None, None]:
         """Iterates through the article in a depth-first manner, yielding each component and its dependencies.
 
         Args:

fabricatio/models/extra/article_outline.py

@@ -1,134 +1,57 @@
 """A module containing the ArticleOutline class, which represents the outline of an academic paper."""
 
-from enum import Enum
-from typing import TYPE_CHECKING, Generator, List, Optional, Tuple, Union, overload
+from typing import Generator, List, Optional, Self, Tuple, Union, override
 
 import regex
+from fabricatio.models.extra.article_base import (
+    ArticleBase,
+    ArticleOutlineBase,
+    ChapterBase,
+    SectionBase,
+    SubSectionBase,
+)
 from fabricatio.models.extra.article_proposal import ArticleProposal
-from fabricatio.models.generic import Base, CensoredAble, Display, PersistentAble, WithRef
+from fabricatio.models.generic import CensoredAble, Display, PersistentAble, WithRef
 from fabricatio.models.utils import ok
-from pydantic import Field
 
-if TYPE_CHECKING:
-    from fabricatio.models.extra.article_main import Article, ArticleBase
 
-
-class ReferringType(str, Enum):
-    """Enumeration of different types of references that can be made in an article."""
-
-    CHAPTER: str = "chapter"
-    SECTION: str = "section"
-    SUBSECTION: str = "subsection"
-
-
-class ArticleRef(CensoredAble):
-    """Reference to a specific chapter, section or subsection within the article. You SHALL not refer to an article component that is external and not present within our own article."""
-
-    referred_chapter_title: str
-    """`title` Field of the referenced chapter"""
-
-    referred_section_title: Optional[str] = None
-    """`title` Field of the referenced section. Defaults to None if not applicable, which means the reference is pointing to the entire chapter."""
-
-    referred_subsection_title: Optional[str] = None
-    """`title` Field of the referenced subsection. Defaults to None if not applicable, which means the reference is pointing to the entire section."""
-
-    def __hash__(self) -> int:
-        """Overrides the default hash function to ensure consistent hashing across instances."""
-        return hash((self.referred_chapter_title, self.referred_section_title, self.referred_subsection_title))
-
-    @overload
-    def deref(self, article: "Article") -> Optional["ArticleBase"]:
-        """Dereference the reference to the actual section or subsection within the provided article."""
-
-    @overload
-    def deref(self, article: "ArticleOutline") -> Optional["ArticleOutlineBase"]:
-        """Dereference the reference to the actual section or subsection within the provided article."""
-
-    def deref(self, article: Union["ArticleOutline", "Article"]) -> Union["ArticleOutlineBase", "ArticleBase", None]:
-        """Dereference the reference to the actual section or subsection within the provided article.
-
-        Args:
-            article (ArticleOutline | Article): The article to dereference the reference from.
-
-        Returns:
-            ArticleBase | ArticleOutline | None: The dereferenced section or subsection, or None if not found.
-        """
-        chap = next((chap for chap in article.chapters if chap.title == self.referred_chapter_title), None)
-        if self.referred_section_title is None or chap is None:
-            return chap
-        sec = next((sec for sec in chap.sections if sec.title == self.referred_section_title), None)
-        if self.referred_subsection_title is None or sec is None:
-            return sec
-        return next((subsec for subsec in sec.subsections if subsec.title == self.referred_subsection_title), None)
-
-    @property
-    def referring_type(self) -> ReferringType:
-        """Determine the type of reference based on the presence of specific attributes."""
-        if self.referred_subsection_title is not None:
-            return ReferringType.SUBSECTION
-        if self.referred_section_title is not None:
-            return ReferringType.SECTION
-        return ReferringType.CHAPTER
-
-
-class ArticleOutlineBase(Base):
-    """Base class for article outlines."""
-
-    writing_aim: List[str]
-    """Required: List of specific rhetorical objectives (3-5 items).
-    Format: Each item must be an actionable phrase starting with a verb.
-    Example: ['Establish metric validity', 'Compare with baseline approaches',
-             'Justify threshold selection']"""
-    depend_on: List[ArticleRef]
-    """Required: List of all essential ArticleRef objects identifying components this section builds upon.
-    Format: Each reference must point to a previously defined chapter, section, or subsection.
-    Note: Circular dependencies are not permitted."""
-    support_to: List[ArticleRef]
-    """Required: List of all essential ArticleRef objects identifying components this section provides evidence for.
-    Format: Each reference must point to a specific chapter, section, or subsection.
-    Note: References form a directed acyclic graph in the document structure."""
-
-    description: str
-    """Description of the research component in academic style."""
-    title: str
-    """Title of the research component in academic style."""
-
-
-class ArticleSubsectionOutline(ArticleOutlineBase):
+class ArticleSubsectionOutline(ArticleOutlineBase, SubSectionBase):
     """Atomic research component specification for academic paper generation."""
 
 
-class ArticleSectionOutline(ArticleOutlineBase):
-    """A slightly more detailed research component specification for academic paper generation."""
 
-    subsections: List[ArticleSubsectionOutline] = Field(min_length=1)
-    """List of subsections, each containing a specific research component. Must contains at least 1 subsection, But do remember you should always add more subsection as required."""
+class ArticleSectionOutline(ArticleOutlineBase, SectionBase[ArticleSubsectionOutline]):
+    """A slightly more detailed research component specification for academic paper generation, Must contain subsections."""
 
 
-class ArticleChapterOutline(ArticleOutlineBase):
-    """Macro-structural unit implementing standard academic paper organization."""
+    def update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance."""
+        super().update_from_inner(other)
+        super(ArticleOutlineBase, self).update_from_inner(other)
+        return self
 
-    sections: List[ArticleSectionOutline] = Field(min_length=1)
-    """Standard academic progression implementing chapter goals:
-    1. Context Establishment
-    2. Technical Presentation
-    3. Empirical Validation
-    4. Comparative Analysis
-    5. Synthesis
 
-    Must contains at least 1 sections, But do remember you should always add more section as required.
-    """
+class ArticleChapterOutline(ArticleOutlineBase, ChapterBase[ArticleSectionOutline]):
+    """Macro-structural unit implementing standard academic paper organization. Must contain sections."""
 
+    def update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance."""
+        super().update_from_inner(other)
+        super(ArticleOutlineBase, self).update_from_inner(other)
+        return self
 
-class ArticleOutline(Display, CensoredAble, WithRef[ArticleProposal], PersistentAble):
-    """Complete academic paper blueprint with hierarchical validation."""
 
-    article_language: str
-    """Written language of the article. SHALL be aligned to the language of the article proposal provided."""
+class ArticleOutline(
+    Display,
+    CensoredAble,
+    WithRef[ArticleProposal],
+    PersistentAble,
+    ArticleBase[ArticleChapterOutline],
+):
+    """A class representing the outline of an academic paper."""
 
-    title: str
-    """Title of the academic paper."""
+    abstract: str
+    """The abstract is a concise summary of the academic paper's main findings."""
 
     prospect: str
     """Consolidated research statement with four pillars:
@@ -136,17 +59,13 @@ class ArticleOutline(Display, CensoredAble, WithRef[ArticleProposal], Persistent
     2. Methodological Response: Technical approach
     3. Empirical Validation: Evaluation strategy
     4. Scholarly Impact: Field contributions
+    """
 
-    Example: 'Addressing NAS computational barriers through constrained
-    differentiable search spaces, validated via cross-lingual MT experiments
-    across 50+ languages, enabling efficient architecture discovery with
-    60% reduced search costs.'"""
-
-    chapters: List[ArticleChapterOutline]
-    """List of ArticleChapterOutline objects representing the academic paper's structure."""
+    title: str
+    """Title of the academic paper."""
 
-    abstract: str
-    """The abstract is a concise summary of the academic paper's main findings."""
+    language: str
+    """Written language of the article. SHALL be aligned to the language of the article proposal provided."""
 
     def finalized_dump(self) -> str:
         """Generates standardized hierarchical markup for academic publishing systems.
@@ -177,26 +96,16 @@ class ArticleOutline(Display, CensoredAble, WithRef[ArticleProposal], Persistent
                     lines.append(f"=== {i}.{j}.{k} {subsection.title}")
         return "\n".join(lines)
 
-    def iter_dfs(self) -> Generator[ArticleOutlineBase, None, None]:
-        """Iterates through the article outline in a depth-first manner.
+    @override
+    def iter_dfs(
+        self,
+    ) -> Generator[ArticleChapterOutline | ArticleSectionOutline | ArticleSubsectionOutline, None, None]: 
+        return super().iter_dfs()
+    def find_illegal(self) -> Optional[Tuple[ArticleOutlineBase, str]]:
+        """Finds the first illegal component in the outline.
 
         Returns:
-            ArticleOutlineBase: Each component in the article outline.
-        """
-        for chapter in self.chapters:
-            for section in chapter.sections:
-                yield from section.subsections
-                yield section
-            yield chapter
-
-    def resolve_ref_error(self) -> str:
-        """Resolve reference errors in the article outline.
-
-        Returns:
-            str: Error message indicating reference errors in the article outline.
-
-        Notes:
-            This function is designed to find all invalid `ArticleRef` objs in `depend_on` and `support_to` fields, which will be added to the final error summary.
+            Tuple[ArticleOutlineBase, str]: A tuple containing the illegal component and an error message.
         """
         summary = ""
         for component in self.iter_dfs():
@@ -206,15 +115,17 @@ class ArticleOutline(Display, CensoredAble, WithRef[ArticleProposal], Persistent
             for ref in component.support_to:
                 if not ref.deref(self):
                     summary += f"Invalid internal reference in {component.__class__.__name__} titled `{component.title}` at `support_to` field, because the referred {ref.referring_type} is not exists within the article, see the original obj dump: {ref.model_dump()}\n"
-
-        return summary
+            summary += component.introspect()
+            if summary:
+                return component, summary
+        return None
 
     @classmethod
     def from_typst_code(
         cls, typst_code: str, title: str = "", article_language: str = "en", prospect: str = "", abstract: str = ""
     ) -> "ArticleOutline":
         """Parses a Typst code string and creates an ArticleOutline instance."""
-        self = cls(article_language=article_language, prospect=prospect, abstract=abstract, chapters=[], title=title)
+        self = cls(language=article_language, prospect=prospect, abstract=abstract, chapters=[], title=title)
         stack = [self]  # 根节点为ArticleOutline实例
 
         for line in typst_code.splitlines():

fabricatio/models/extra/article_proposal.py

@@ -3,7 +3,6 @@
 from typing import Dict, List
 
 from fabricatio.models.generic import AsPrompt, CensoredAble, Display, PersistentAble, WithRef
-from pydantic import Field
 
 
 class ArticleProposal(CensoredAble, Display, WithRef[str], AsPrompt, PersistentAble):
@@ -12,26 +11,25 @@ class ArticleProposal(CensoredAble, Display, WithRef[str], AsPrompt, PersistentA
     Guides LLM in generating comprehensive research proposals with clearly defined components.
     """
 
-    article_language: str
-    """Written language of the article. SHALL be aligned to the language of the article briefing provided."""
-
-    title: str = Field(...)
-    """Paper title in academic style (Title Case, 8-15 words). Example: 'Exploring Neural Architecture Search for Low-Resource Machine Translation'"""
+    technical_approaches: List[str]
+    """Technical approaches"""
 
-    focused_problem: List[str]
-    """Specific research problem(s) or question(s) addressed (list of 1-3 concise statements).
-    Example: ['NAS computational overhead in low-resource settings', 'Architecture transferability across language pairs']"""
+    research_methods: List[str]
+    """Methodological components (list of techniques/tools).
+    Example: ['Differentiable architecture search', 'Transformer-based search space', 'Multi-lingual perplexity evaluation']"""
 
     research_aim: List[str]
     """Primary research objectives (list of 2-4 measurable goals).
     Example: ['Develop parameter-efficient NAS framework', 'Establish cross-lingual architecture transfer metrics']"""
 
-    research_methods: List[str]
-    """Methodological components (list of techniques/tools).
-    Example: ['Differentiable architecture search', 'Transformer-based search space', 'Multi-lingual perplexity evaluation']"""
+    focused_problem: List[str]
+    """Specific research problem(s) or question(s) addressed (list of 1-3 concise statements).
+    Example: ['NAS computational overhead in low-resource settings', 'Architecture transferability across language pairs']"""
 
-    technical_approaches: List[str]
-    """Technical approaches"""
+    title: str
+    """Paper title in academic style (Title Case, 8-15 words). Example: 'Exploring Neural Architecture Search for Low-Resource Machine Translation'"""
+    language: str
+    """Written language of the article. SHALL be aligned to the language of the article briefing provided."""
 
     def _as_prompt_inner(self) -> Dict[str, str]:
         return {"ArticleBriefing": self.referenced, "ArticleProposal": self.display()}