fabricatio 0.2.7.dev5__cp312-cp312-win_amd64.whl → 0.2.8.dev1__cp312-cp312-win_amd64.whl

fabricatio/models/extra/article_base.py

@@ -1,24 +1,23 @@
 """A foundation for hierarchical document components with dependency tracking."""
-from abc import ABC
+
+from abc import ABC, abstractmethod
 from enum import StrEnum
-from typing import TYPE_CHECKING, Generator, List, Optional, Self, Union, overload
+from functools import cache
+from itertools import chain
+from typing import Generator, List, Optional, Self, Tuple
 
 from fabricatio.models.generic import (
-    Base,
+    AsPrompt,
     CensoredAble,
     Display,
+    FinalizedDumpAble,
     Introspect,
     ModelHash,
     PersistentAble,
-    ProposedAble,
+    ProposedUpdateAble,
     ResolveUpdateConflict,
-    UpdateFrom,
 )
 
-if TYPE_CHECKING:
-    from fabricatio.models.extra.article_main import Article
-    from fabricatio.models.extra.article_outline import ArticleOutline
-
 
 class ReferringType(StrEnum):
     """Enumeration of different types of references that can be made in an article."""
@@ -28,7 +27,11 @@ class ReferringType(StrEnum):
     SUBSECTION = "subsection"
 
 
-class ArticleRef(CensoredAble):
+type RefKey = Tuple[str, Optional[str], Optional[str]]
+
+
+@cache
+class ArticleRef(CensoredAble, Display, ProposedUpdateAble):
     """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.
 
     Examples:
@@ -61,30 +64,21 @@ class ArticleRef(CensoredAble):
             ```
     """
 
-    referred_subsection_title: Optional[str] = None
-    """`title` Field of the referenced subsection."""
-
-    referred_section_title: Optional[str] = None
-    """`title` Field of the referenced section."""
-
     referred_chapter_title: str
     """`title` Field of the referenced chapter"""
+    referred_section_title: Optional[str] = None
+    """`title` Field of the referenced section."""
+    referred_subsection_title: Optional[str] = None
+    """`title` Field of the referenced subsection."""
 
-    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["ArticleMainBase"]:
-        """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 update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance."""
+        self.referred_chapter_title = other.referred_chapter_title
+        self.referred_section_title = other.referred_section_title
+        self.referred_subsection_title = other.referred_subsection_title
+        return self
 
-    def deref(
-        self, article: Union["ArticleOutline", "Article"]
-    ) -> Union["ArticleOutlineBase", "ArticleMainBase", None]:
+    def deref(self, article: "ArticleBase") -> Optional["ArticleOutlineBase"]:
         """Dereference the reference to the actual section or subsection within the provided article.
 
         Args:
@@ -111,21 +105,88 @@ class ArticleRef(CensoredAble):
         return ReferringType.CHAPTER
 
 
-class SubSectionBase(
-    UpdateFrom,
+class ArticleMetaData(CensoredAble, Display):
+    """Metadata for an article component."""
+
+    description: str
+    """Description of the research component in academic style."""
+
+    support_to: List[ArticleRef]
+    """List of references to other component of this articles that this component supports."""
+    depend_on: List[ArticleRef]
+    """List of references to other component of this articles that this component depends on."""
+
+    writing_aim: List[str]
+    """List of writing aims of the research component in academic style."""
+    title: str
+    """Do not add any prefix or suffix to the title. should not contain special characters."""
+
+
+class ArticleRefPatch(ProposedUpdateAble, Display):
+    """Patch for article refs."""
+
+    tweaked: List[ArticleRef]
+    """Tweaked refs"""
+
+    def update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance."""
+        self.tweaked.clear()
+        self.tweaked.extend(other.tweaked)
+        return self
+
+    @classmethod
+    def default(cls) -> "ArticleRefPatch":
+        """Defaults to empty list."""
+        return cls(tweaked=[])
+
+
+class ArticleOutlineBase(
+    ArticleMetaData,
+    ResolveUpdateConflict,
+    ProposedUpdateAble,
+    PersistentAble,
+    ModelHash,
     Introspect,
 ):
-    """Base class for article sections and subsections."""
+    """Base class for article outlines."""
 
-    title: str
-    """Title of the subsection, do not add any prefix or suffix to the title. should not contain special characters."""
+    @property
+    def metadata(self) -> ArticleMetaData:
+        """Returns the metadata of the article component."""
+        return ArticleMetaData.model_validate(self, from_attributes=True)
 
+    def update_metadata(self, other: ArticleMetaData) -> Self:
+        """Updates the metadata of the current instance with the attributes of another instance."""
+        self.support_to.clear()
+        self.support_to.extend(other.support_to)
+        self.depend_on.clear()
+        self.depend_on.extend(other.depend_on)
+        self.writing_aim.clear()
+        self.writing_aim.extend(other.writing_aim)
+        self.description = other.description
+        return self
+
+    def display_metadata(self) -> str:
+        """Displays the metadata of the current instance."""
+        return self.model_dump_json(
+            indent=1, include={"title", "writing_aim", "description", "support_to", "depend_on"}
+        )
+
+    def update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance."""
+        return self.update_metadata(other)
+
+    @abstractmethod
     def to_typst_code(self) -> str:
         """Converts the component into a Typst code snippet for rendering."""
-        return f"=== {self.title}\n"
 
-    def update_from_inner(self, other: Self) -> Self:
-        return self
+
+class SubSectionBase(ArticleOutlineBase):
+    """Base class for article sections and subsections."""
+
+    def to_typst_code(self) -> str:
+        """Converts the component into a Typst code snippet for rendering."""
+        return f"=== {self.title}\n"
 
     def introspect(self) -> str:
         """Introspects the article subsection outline."""
@@ -138,16 +199,11 @@ class SubSectionBase(
         return ""
 
 
-class SectionBase[T: SubSectionBase](
-    UpdateFrom,
-    Introspect,
-):
+class SectionBase[T: SubSectionBase](ArticleOutlineBase):
     """Base class for article sections and subsections."""
 
     subsections: List[T]
     """Subsections of the section. Contains at least one subsection. You can also add more as needed."""
-    title: str
-    """Title of the section, do not add any prefix or suffix to the title. should not contain special characters."""
 
     def to_typst_code(self) -> str:
         """Converts the section into a Typst formatted code snippet.
@@ -174,6 +230,7 @@ class SectionBase[T: SubSectionBase](
 
     def update_from_inner(self, other: Self) -> Self:
         """Updates the current instance with the attributes of another instance."""
+        super().update_from_inner(other)
         if len(self.subsections) == 0:
             self.subsections = other.subsections
             return self
@@ -189,16 +246,12 @@ class SectionBase[T: SubSectionBase](
         return ""
 
 
-class ChapterBase[T: SectionBase](
-    UpdateFrom,
-    Introspect,
-):
+class ChapterBase[T: SectionBase](ArticleOutlineBase):
     """Base class for article chapters."""
 
     sections: List[T]
     """Sections of the chapter. Contains at least one section. You can also add more as needed."""
-    title: str
-    """Title of the chapter, do not add any prefix or suffix to the title. should not contain special characters."""
+
     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)
@@ -233,21 +286,35 @@ class ChapterBase[T: SectionBase](
         return ""
 
 
-class ArticleBase[T: ChapterBase](Base):
+class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, ABC):
     """Base class for article outlines."""
 
+    language: str
+    """Written language of the article. SHALL be aligned to the language of the article proposal provided."""
+
+    title: str
+    """Title of the academic paper."""
+
+    prospect: str
+    """Consolidated research statement with four pillars:
+    1. Problem Identification: Current limitations
+    2. Methodological Response: Technical approach
+    3. Empirical Validation: Evaluation strategy
+    4. Scholarly Impact: Field contributions
+    """
+
+    abstract: str
+    """The abstract is a concise summary of the academic paper's main findings."""
     chapters: List[T]
     """Chapters of the article. Contains at least one chapter. You can also add more as needed."""
-    title: str
-    """Title of the article outline, do not add any prefix or suffix to the title. should not contain special characters."""
 
-    def iter_dfs(
+    def iter_dfs_rev(
         self,
-    ) -> Generator[ChapterBase | SectionBase | SubSectionBase, None, None]:
-        """Performs a depth-first search (DFS) through the article structure.
+    ) -> Generator[ArticleOutlineBase, None, None]:
+        """Performs a depth-first search (DFS) through the article structure in reverse order.
 
         Returns:
-            Generator[ArticleMainBase]: Each component in the article structure.
+            Generator[ArticleMainBase]: Each component in the article structure in reverse order.
         """
         for chap in self.chapters:
             for sec in chap.sections:
@@ -255,37 +322,80 @@ class ArticleBase[T: ChapterBase](Base):
                 yield sec
             yield chap
 
+    def iter_dfs(self) -> Generator[ArticleOutlineBase, None, None]:
+        """Performs a depth-first search (DFS) through the article structure.
 
-class ArticleOutlineBase(
-    CensoredAble,
-    UpdateFrom,
-    ResolveUpdateConflict,
-    ProposedAble,
-    PersistentAble,
-    Display,
-    ModelHash,
-    ABC,
-):
-    """Base class for article outlines."""
+        Returns:
+            Generator[ArticleMainBase]: Each component in the article structure.
+        """
+        for chap in self.chapters:
+            yield chap
+            for sec in chap.sections:
+                yield sec
+                yield from sec.subsections
 
-    description: str
-    """Description of the research component in academic style."""
+    def iter_sections(self) -> Generator[Tuple[ChapterBase, SectionBase], None, None]:
+        """Iterates through all sections in the article.
 
-    support_to: List[ArticleRef]
-    """List of references to other component of this articles that this component supports."""
-    depend_on: List[ArticleRef]
-    """List of references to other component of this articles that this component depends on."""
+        Returns:
+            Generator[ArticleOutlineBase]: Each section in the article.
+        """
+        for chap in self.chapters:
+            for sec in chap.sections:
+                yield chap, sec
 
-    writing_aim: List[str]
-    """List of writing aims of the research component in academic style."""
+    def iter_subsections(self) -> Generator[Tuple[ChapterBase, SectionBase, SubSectionBase], None, None]:
+        """Iterates through all subsections in the article.
 
-    def update_from_inner(self, other: Self) -> Self:
-        """Updates the current instance with the attributes of another instance."""
-        self.support_to.clear()
-        self.support_to.extend(other.support_to)
-        self.depend_on.clear()
-        self.depend_on.extend(other.depend_on)
-        self.writing_aim.clear()
-        self.writing_aim.extend(other.writing_aim)
-        self.description = other.description
-        return self
+        Returns:
+            Generator[ArticleOutlineBase]: Each subsection in the article.
+        """
+        for chap, sec in self.iter_sections():
+            for subsec in sec.subsections:
+                yield chap, sec, subsec
+
+    def find_introspected(self) -> Optional[Tuple[ArticleOutlineBase, str]]:
+        """Finds the first introspected component in the article structure."""
+        summary = ""
+        for component in self.iter_dfs_rev():
+            summary += component.introspect()
+            if summary:
+                return component, summary
+        return None
+
+    def find_illegal_ref(self) -> Optional[Tuple[ArticleRef, str]]:
+        """Finds the first illegal component in the outline.
+
+        Returns:
+            Tuple[ArticleOutlineBase, str]: A tuple containing the illegal component and an error message.
+        """
+        summary = ""
+        for component in self.iter_dfs_rev():
+            for ref in chain(component.depend_on, component.support_to):
+                if not ref.deref(self):
+                    summary += f"Invalid internal reference in `{component.__class__.__name__}` titled `{component.title}`, because the referred {ref.referring_type} is not exists within the article, see the original obj dump: {ref.model_dump()}\n"
+                if summary:
+                    return ref, summary
+        return None
+
+    def finalized_dump(self) -> str:
+        """Generates standardized hierarchical markup for academic publishing systems.
+
+        Implements ACL 2024 outline conventions with four-level structure:
+        = Chapter Title (Level 1)
+        == Section Title (Level 2)
+        === Subsection Title (Level 3)
+        ==== Subsubsection Title (Level 4)
+
+        Returns:
+            str: Strictly formatted outline with academic sectioning
+
+        Example:
+            = Methodology
+            == Neural Architecture Search Framework
+            === Differentiable Search Space
+            ==== Constrained Optimization Parameters
+            === Implementation Details
+            == Evaluation Protocol
+        """
+        return "\n\n".join(a.to_typst_code() for a in self.chapters)

fabricatio/models/extra/article_essence.py

@@ -134,10 +134,10 @@ class Highlightings(BaseModel):
 
 
 class ArticleEssence(ProposedAble, Display, PrepareVectorization):
-    """Semantic fingerprint of academic paper for structured analysis.
+    """ArticleEssence is a structured representation of the core elements of a scientific article."""
 
-    Encodes research artifacts with dual human-machine interpretability.
-    """
+    language: str = Field(...)
+    """Language of the original article."""
 
     title: str = Field(...)
     """Exact title of the original article without any modification.
@@ -149,7 +149,7 @@ class ArticleEssence(ProposedAble, Display, PrepareVectorization):
     """
 
     authors: List[str]
-    """Original author names exactly as they appear in the source document. No translation or paraphrasing.
+    """Original author full names exactly as they appear in the source document. No translation or paraphrasing.
     Extract complete list without any modifications or formatting changes."""
 
     keywords: List[str]
@@ -170,11 +170,7 @@ class ArticleEssence(ProposedAble, Display, PrepareVectorization):
     """Domain tags for research focus."""
 
     abstract: str = Field(...)
-    """Three-paragraph structured abstract:
-    Paragraph 1: Problem & Motivation (2-3 sentences)
-    Paragraph 2: Methodology & Innovations (3-4 sentences)
-    Paragraph 3: Results & Impact (2-3 sentences)
-    Total length: 150-250 words"""
+    """Abstract text with original language."""
 
     core_contributions: List[str]
     """3-5 technical contributions using CRediT taxonomy verbs.
@@ -184,6 +180,7 @@ class ArticleEssence(ProposedAble, Display, PrepareVectorization):
     - 'Established cross-lingual transfer metrics'"""
 
     technical_novelty: List[str]
+
     """Patent-style claims with technical specificity.
     Format: 'A [system/method] comprising [novel components]...'
     Example:

fabricatio/models/extra/article_main.py

@@ -1,13 +1,12 @@
 """ArticleBase and ArticleSubsection classes for managing hierarchical document components."""
 
 from itertools import chain
-from typing import Generator, List, Self, Tuple, override
+from typing import Dict, Generator, List, Self, Tuple, override
 
 from fabricatio.journal import logger
 from fabricatio.models.extra.article_base import (
     ArticleBase,
     ArticleOutlineBase,
-    ArticleRef,
     ChapterBase,
     SectionBase,
     SubSectionBase,
@@ -28,21 +27,26 @@ class Paragraph(CensoredAble):
     writing_aim: List[str]
     """Specific communicative objectives for this paragraph's content."""
 
-    sentences: List[str]
-    """List of sentences forming the paragraph's content."""
+    content: str
+    """The actual content of the paragraph, represented as a string."""
 
 
-class ArticleSubsection(ArticleOutlineBase, SubSectionBase):
+class ArticleSubsection(SubSectionBase):
     """Atomic argumentative unit with technical specificity."""
 
     paragraphs: List[Paragraph]
     """List of Paragraph objects containing the content of the subsection."""
 
+    def introspect(self) -> str:
+        """Introspects the subsection and returns a message if it has no paragraphs."""
+        if len(self.paragraphs) == 0:
+            return f"`{self.__class__.__name__}` titled `{self.title}` have no paragraphs, to achieve the goal of `{self.writing_aim}`."
+        return ""
+
     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}")
-        SubSectionBase.update_from(self, other)
-        ArticleOutlineBase.update_from(self, other)
+        super().update_from_inner(other)
         self.paragraphs.clear()
         self.paragraphs.extend(other.paragraphs)
         return self
@@ -53,19 +57,17 @@ class ArticleSubsection(ArticleOutlineBase, SubSectionBase):
         Returns:
             str: Typst code snippet for rendering.
         """
-        return f"=== {self.title}\n" + "\n\n".join("".join(p.sentences) for p in self.paragraphs)
+        return f"=== {self.title}\n" + "\n\n".join(p.content for p in self.paragraphs)
 
 
-class ArticleSection(ArticleOutlineBase, SectionBase[ArticleSubsection]):
+class ArticleSection(SectionBase[ArticleSubsection]):
     """Atomic argumentative unit with high-level specificity."""
 
 
-
-class ArticleChapter(ArticleOutlineBase, ChapterBase[ArticleSection]):
+class ArticleChapter(ChapterBase[ArticleSection]):
     """Thematic progression implementing research function."""
 
 
-
 class Article(
     Display,
     CensoredAble,
@@ -79,22 +81,17 @@ class Article(
     aiming to provide a comprehensive model for academic papers.
     """
 
-    abstract: str
-    """Contains a summary of the academic paper."""
-
-    title: str
-    """Represents the title of the academic paper."""
+    def _as_prompt_inner(self) -> Dict[str, str]:
+        return {
+            "Original Article Briefing": self.referenced.referenced.referenced,
+            "Original Article Proposal": self.referenced.referenced.display(),
+            "Original Article Outline": self.referenced.display(),
+            "Original Article": self.display(),
+        }
 
-    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.
-
-        Returns:
-                str: Strictly formatted outline with typst formatting.
-        """
-        return "\n\n".join(c.to_typst_code() for c in self.chapters)
+    @override
+    def iter_subsections(self) -> Generator[Tuple[ArticleChapter, ArticleSection, ArticleSubsection], None, None]:
+        return super().iter_subsections()
 
     @classmethod
     def from_outline(cls, outline: ArticleOutline) -> "Article":
@@ -107,7 +104,7 @@ class Article(
             Article: The generated article.
         """
         # Set the title from the outline
-        article = Article(**outline.model_dump(include={"title", "abstract"}), chapters=[])
+        article = Article(**outline.model_dump(exclude={"chapters"}), chapters=[])
 
         for chapter in outline.chapters:
             # Create a new chapter
@@ -132,33 +129,16 @@ class Article(
             article.chapters.append(article_chapter)
         return article
 
-    @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:
-            ArticleOutlineBase: The corresponding section or subsection.
-        """
-        return ok(ref.deref(self), f"{ref} not found in {self.title}")
-
     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.
         """
-        depends = [self.deref(a) for a in article.depend_on]
+        depends = [ok(a.deref(self)) for a in article.depend_on]
 
         supports = []
-        for a in self.iter_dfs():
-            if article in {self.deref(b) for b in a.support_to}:
+        for a in self.iter_dfs_rev():
+            if article in {ok(b.deref(self)) for b in a.support_to}:
                 supports.append(a)
 
         return list(set(depends + supports))
@@ -220,7 +200,7 @@ class Article(
         if all((not chapter, not section, not subsection)):
             raise ValueError("At least one of chapter, section, or subsection must be True.")
 
-        for component in self.iter_dfs():
+        for component in self.iter_dfs_rev():
             if not chapter and isinstance(component, ArticleChapter):
                 continue
             if not section and isinstance(component, ArticleSection):