fabricatio 0.2.7.dev0__cp39-cp39-win_amd64.whl → 0.2.7.dev1__cp39-cp39-win_amd64.whl

fabricatio/models/extra.py

@@ -1,11 +1,15 @@
 """Extra models for built-in actions."""
 
-from typing import List, Self
+from abc import abstractmethod
+from itertools import chain
+from typing import Dict, Generator, List, Optional, Self, Tuple, final
 
-from fabricatio.models.generic import Base, Display, FinalizedDumpAble, PrepareVectorization, ProposedAble
+from fabricatio.journal import logger
+from fabricatio.models.generic import AsPrompt, Base, CensoredAble, Display, PrepareVectorization, ProposedAble, WithRef
+from fabricatio.models.utils import ok
+from pydantic import BaseModel, Field
 
 # <editor-fold desc="ArticleEssence">
-from pydantic import BaseModel, Field
 
 
 class Equation(BaseModel):
@@ -231,7 +235,7 @@ class ArticleEssence(ProposedAble, Display, PrepareVectorization):
 # </editor-fold>
 
 
-class ArticleProposal(ProposedAble, Display):
+class ArticleProposal(CensoredAble, Display, WithRef[str], AsPrompt):
     """Structured proposal for academic paper development with core research elements.
 
     Guides LLM in generating comprehensive research proposals with clearly defined components.
@@ -240,63 +244,80 @@ class ArticleProposal(ProposedAble, Display):
     title: str = Field(...)
     """Paper title in academic style (Title Case, 8-15 words). Example: 'Exploring Neural Architecture Search for Low-Resource Machine Translation'"""
 
-    focused_problem: List[str] = Field(default_factory=list)
+    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_aim: List[str] = Field(default_factory=list)
+    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] = Field(default_factory=list)
+    research_methods: List[str]
     """Methodological components (list of techniques/tools).
     Example: ['Differentiable architecture search', 'Transformer-based search space', 'Multi-lingual perplexity evaluation']"""
 
-    technical_approaches: List[str] = Field(default_factory=list)
+    technical_approaches: List[str]
+    """Technical approaches"""
 
+    def _as_prompt_inner(self) -> Dict[str, str]:
+        return {"ArticleBriefing": self.referenced, "ArticleProposal": self.display()}
 
-# <editor-fold desc="ArticleOutline">
-class ArticleSubsectionOutline(Base):
-    """Atomic research component specification for academic paper generation."""
 
-    title: str = Field(...)
-    """Technical focus descriptor following ACL title conventions:
-    - Title Case with 4-8 word limit
-    - Contains method and domain components
-    Example: 'Differentiable Search Space Optimization'"""
+class ArticleRef(CensoredAble):
+    """Reference to a specific section or subsection within an article.
 
-    description: str = Field(...)
-    """Tripartite content specification with strict structure:
-    1. Technical Core: Method/algorithm/formalism (1 sentence)
-    2. Structural Role: Placement rationale in section (1 clause)
-    3. Research Value: Contribution to paper's thesis (1 clause)
+    Always instantiated with a fine-grind reference to a specific subsection if possible.
+    """
 
-    Example: 'Introduces entropy-constrained architecture parameters enabling
-    gradient-based NAS. Serves as foundation for Section 3.2. Critical for
-    maintaining search space diversity while ensuring convergence.'"""
+    referred_chapter_title: str
+    """Full title of the chapter that contains the referenced section."""
 
+    referred_section_title: Optional[str] = None
+    """Full title of the section that contains the referenced subsection. Defaults to None if not applicable, which means the reference is to the entire chapter."""
 
-class ArticleSectionOutline(Base):
-    """Methodological unit organizing related technical components."""
+    referred_subsection_title: Optional[str] = None
+    """Full title of the subsection that contains the referenced paragraph. Defaults to None if not applicable, which means the reference is 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))
 
-    title: str = Field(...)
-    """Process-oriented header with phase identification:
-    - Title Case with 5-10 word limit
-    - Indicates research stage/methodological focus
-    Example: 'Cross-Lingual Evaluation Protocol'"""
+
+# <editor-fold desc="ArticleOutline">
+class ArticleOutlineBase(Base):
+    """Atomic research component specification for academic paper generation."""
+
+    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']"""
+    support_to: List[ArticleRef]
+    """Required: List of 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."""
+
+    depend_on: List[ArticleRef]
+    """Required: List of 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."""
 
     description: str = Field(...)
-    """Functional specification with four required elements:
-    1. Research Stage: Paper progression position
-    2. Technical Innovations: Novel components
-    3. Scholarly Context: Relationship to prior work
-    4. Forward Flow: Connection to subsequent sections
+    """Description of the research component in academic style."""
+    title: str = Field(...)
+    """Title of the research component in academic style."""
+
+
+class ArticleSubsectionOutline(ArticleOutlineBase):
+    """Atomic research component specification for academic paper generation."""
 
-    Example: 'Implements constrained NAS framework building on Section 2's
-    theoretical foundations. Introduces dynamic resource allocation mechanism.
-    Directly supports Results section through ablation study parameters.'"""
 
-    subsections: List[ArticleSubsectionOutline] = Field(..., min_length=3, max_length=5)
+class ArticleSectionOutline(ArticleOutlineBase):
+    """Methodological unit organizing related technical components."""
+
+    subsections: List[ArticleSubsectionOutline] = Field(
+        ...,
+    )
     """IMRaD-compliant substructure with technical progression:
     1. Conceptual Framework
     2. Methodological Details
@@ -314,27 +335,12 @@ class ArticleSectionOutline(Base):
     ]"""
 
 
-class ArticleChapterOutline(Base):
+class ArticleChapterOutline(ArticleOutlineBase):
     """Macro-structural unit implementing standard academic paper organization."""
 
-    title: str = Field(...)
-    """IMRaD-compliant chapter title with domain specification:
-    - Title Case with 2-4 word limit
-    - Matches standard paper sections
-    Example: 'Multilingual Evaluation Results'"""
-
-    description: str = Field(...)
-    """Strategic chapter definition containing:
-    1. Research Phase: Introduction/Methods/Results/etc.
-    2. Chapter Objectives: 3-5 specific goals
-    3. Thesis Alignment: Supported claims/contributions
-    4. Structural Flow: Adjacent chapter relationships
-
-    Example: 'Presents cross-lingual NAS results across 10 language pairs.
-    Validates efficiency claims from Introduction. Provides empirical basis
-    for Discussion chapter. Contrasts with single-language baselines.'"""
-
-    sections: List[ArticleSectionOutline] = Field(..., min_length=3, max_length=5)
+    sections: List[ArticleSectionOutline] = Field(
+        ...,
+    )
     """Standard academic progression implementing chapter goals:
     1. Context Establishment
     2. Technical Presentation
@@ -352,7 +358,7 @@ class ArticleChapterOutline(Base):
     ]"""
 
 
-class ArticleOutline(ProposedAble, Display, FinalizedDumpAble):
+class ArticleOutline(Display, CensoredAble, WithRef[ArticleProposal]):
     """Complete academic paper blueprint with hierarchical validation."""
 
     title: str = Field(...)
@@ -374,7 +380,7 @@ class ArticleOutline(ProposedAble, Display, FinalizedDumpAble):
     across 50+ languages, enabling efficient architecture discovery with
     60% reduced search costs.'"""
 
-    chapters: List[ArticleChapterOutline] = Field(..., min_length=5, max_length=8)
+    chapters: List[ArticleChapterOutline]
     """IMRaD structure with enhanced academic validation:
     1. Introduction: Problem Space & Contributions
     2. Background: Theoretical Foundations
@@ -385,6 +391,9 @@ class ArticleOutline(ProposedAble, Display, FinalizedDumpAble):
     7. Conclusion: Synthesis & Future Work
     8. Appendices: Supplementary Materials"""
 
+    abstract: str = Field(...)
+    """The abstract is a concise summary of the academic paper's main findings."""
+
     def finalized_dump(self) -> str:
         """Generates standardized hierarchical markup for academic publishing systems.
 
@@ -419,7 +428,7 @@ class ArticleOutline(ProposedAble, Display, FinalizedDumpAble):
 
 
 # <editor-fold desc="Article">
-class Paragraph(ProposedAble):
+class Paragraph(CensoredAble):
     """Structured academic paragraph blueprint for controlled content generation."""
 
     description: str
@@ -431,255 +440,273 @@ class Paragraph(ProposedAble):
     Example: ['Introduce gradient-based NAS', 'Compare computational costs',
              'Link efficiency to practical applications']"""
 
-    lines: List[str]
-    """Hierarchically structured content with enforced rhetorical elements:
-    1. Topic Sentence: Principal claim/position (1 sentence)
-    2. Development: Evidence chain with citations (2-4 sentences)
-    3. Synthesis: Interpretation & significance (1 sentence)
-    4. Transition: Logical bridge to next paragraph (optional)
-
-    Example: [
-        'Differentiable NAS revolutionized architecture search efficiency.',
-        'DARTS reduced search costs from 2000+ to 4 GPU days (Liu et al., 2019) while maintaining competitive ImageNet accuracy.',
-        'This order-of-magnitude improvement enables NAS deployment in resource-constrained research contexts.',
-        'These efficiency gains directly impact our framework's design choices as detailed in Section 3.'
-    ]"""
-
-
-class SectionRef(ProposedAble):
-    """Cross-component reference system for maintaining document consistency."""
-
-    ref_chapter_title: str
-    """Title of referenced chapter (e.g., 'Methodology')"""
-
-    ref_section_title: str
-    """Exact section header text (e.g., '3.2 Gradient Optimization')"""
+    sentences: List[str]
+    """List of sentences forming the paragraph's content."""
 
-    ref_subsection_title: str
-    """Specific subsection identifier (e.g., '3.2.1 Learning Rate Scheduling')"""
 
-
-class ArticleBase(ProposedAble, Display):
+class ArticleBase(CensoredAble, Display, ArticleOutlineBase):
     """Foundation for hierarchical document components with dependency tracking."""
 
-    description: str
-    """Functional purpose statement for this component's role in the paper.
-    Example: 'Defines evaluation metrics for cross-lingual transfer experiments'"""
+    @abstractmethod
+    def to_typst_code(self) -> str:
+        """Converts the component into a Typst code snippet for rendering."""
 
-    writing_aim: List[str]
-    """Author intentions mapped to rhetorical moves:
-    Example: ['Establish metric validity', 'Compare with baseline approaches',
-             'Justify threshold selection']"""
+    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.")
 
-    title: str = Field(...)
-    """Standardized academic header following ACL style guidelines:
-    - Title Case with maximal 12-word length
-    - No abbreviations without prior definition
-    Example: 'Multilingual Benchmark Construction'"""
+    @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)
 
-    support_to: List[SectionRef]
-    """Upstream dependencies requiring this component's validation.
-    Format: List of hierarchical references to supported claims/sections
-    Example: [SectionRef(chapter='Results', section='4.1', subsection='4.1.2')]"""
+    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()
 
-    depend_on: List[SectionRef]
-    """Downstream prerequisites for content validity.
-    Format: List of references to foundational components
-    Example: [SectionRef(chapter='Methods', section='2.3', subsection='2.3.4')]"""
+    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):
     """Atomic argumentative unit with technical specificity."""
 
-    title: str = Field(...)
-    """Technical descriptor with maximal information density:
-    Format: [Method]-[Domain]-[Innovation]
-    Example: 'Transformer-Based Architecture Search Space'"""
-
-    support_to: List[SectionRef]
-    """Immediate parent components and supported hypotheses.
-    Example: [SectionRef(chapter='Methods', section='3', subsection='3.1')]"""
-
-    depend_on: List[SectionRef]
-    """Technical dependencies including equations, algorithms, and datasets.
-    Example: [SectionRef(chapter='Background', section='2.2', subsection='2.2.3')]"""
-
-    paragraphs: List[Paragraph] = Field(..., min_length=3, max_length=5)
-    """Technical exposition following ACM writing guidelines:
-    1. Contextualization: Position in research design
-    2. Technical Detail: Equations/algorithms/code
-    3. Validation: Citations/experimental confirmation
-    4. Interpretation: Scholarly significance
-    5. Transition: Logical connection to subsequent content
-
-    Example Paragraph Chain:
-    [
-        'Our search space builds on standard CNN architectures...',
-        'Formally, we define architecture parameters $\\alpha \\in R^d$ where...',
-        'This parameterization reduces search complexity by 42% compared to...',
-        'The efficiency gains validate our approach to...'
-    ]"""
+    paragraphs: List[Paragraph]
+    """List of Paragraph objects containing the content of the subsection."""
 
+    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
+        return self
 
-class ArticleSection(ArticleBase):
-    """Methodological complete unit presenting cohesive research phase."""
+    def to_typst_code(self) -> str:
+        """Converts the component into a Typst code snippet for rendering.
 
-    title: str = Field(...)
-    """Process-oriented header indicating methodological scope.
-    Example: 'Cross-Lingual Transfer Evaluation Protocol'"""
+        Returns:
+            str: Typst code snippet for rendering.
+        """
+        return f"=== {self.title}\n" + "\n\n".join("".join(p.sentences) for p in self.paragraphs)
 
-    support_to: List[SectionRef]
-    """Supported research questions and paper-level claims.
-    Example: [SectionRef(chapter='Introduction', section='1', subsection='1.2')]"""
 
-    depend_on: List[SectionRef]
-    """Required methodological components and theoretical frameworks.
-    Example: [SectionRef(chapter='Background', section='2', subsection='2.4')]"""
+class ArticleSection(ArticleBase):
+    """Atomic argumentative unit with high-level specificity."""
 
-    subsections: List[ArticleSubsection] = Field(..., min_length=3, max_length=5)
-    """Thematic progression implementing section's research function:
-    1. Conceptual Framework
-    2. Technical Implementation
-    3. Experimental Validation
-    4. Comparative Analysis
-    5. Synthesis
+    subsections: List[ArticleSubsection]
 
-    Example Subsection Flow:
-    [
-        'Evaluation Metrics',
-        'Dataset Preparation',
-        'Baseline Comparisons',
-        'Ablation Studies',
-        'Interpretation Framework'
-    ]"""
+    def _update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance."""
+        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.
 
-class ArticleChapter(ArticleBase):
-    """Macro-structural unit implementing IMRaD document architecture."""
+        Returns:
+            str: The formatted Typst code snippet.
+        """
+        return f"== {self.title}\n" + "\n\n".join(subsec.to_typst_code() for subsec in self.subsections)
 
-    title: str = Field(...)
-    """Standard IMRaD chapter title with domain specification.
-    Example: 'Neural Architecture Search for Low-Resource Languages'"""
 
-    support_to: List[SectionRef]
-    """Supported thesis statements and paper-level contributions.
-    Example: [SectionRef(chapter='Abstract', section='', subsection='')]"""
+class ArticleChapter(ArticleBase):
+    """Thematic progression implementing research function."""
 
-    depend_on: List[SectionRef]
-    """Foundational chapters and external knowledge prerequisites.
-    Example: [SectionRef(chapter='Related Work', section='2', subsection='2.3')]"""
+    sections: List[ArticleSection]
+    """Thematic progression implementing chapter's research function."""
 
-    sections: List[ArticleSection] = Field(..., min_length=3, max_length=5)
-    """Complete research narrative implementing chapter objectives:
-    1. Context Establishment
-    2. Methodology Exposition
-    3. Results Presentation
-    4. Critical Analysis
-    5. Synthesis
+    def _update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance."""
+        for self_sec, other_sec in zip(self.sections, other.sections, strict=True):
+            self_sec.update_from(other_sec)
+        return self
 
-    Example Section Hierarchy:
-    [
-        'Theoretical Framework',
-        'Experimental Design',
-        'Results Analysis',
-        'Threats to Validity',
-        'Comparative Discussion'
-    ]"""
+    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(ProposedAble, Display):
+class Article(Display, CensoredAble, WithRef[ArticleOutline]):
     """Complete academic paper specification with validation constraints."""
 
     title: str = Field(...)
-    """Full technical descriptor following ACL 2024 guidelines:
-    Structure: [Method] for [Task] in [Domain]: [Subtitle with Technical Focus]
-    Example: 'Efficient Differentiable NAS for Low-Resource MT:
-             A Parameter-Sharing Approach to Cross-Lingual Transfer'"""
+    """The academic title"""
 
     abstract: str = Field(...)
-    """Structured summary with controlled natural language:
-    1. Context: 2 clauses (problem + gap)
-    2. Methods: 3 clauses (approach + innovation + implementation)
-    3. Results: 3 clauses (metrics + comparisons + significance)
-    4. Impact: 2 clauses (theoretical + practical)
-
-    Example: 'Neural architecture search (NAS) faces prohibitive... [150 words]'"""
-
-    chapters: List[ArticleChapter] = Field(..., min_length=5, max_length=8)
-    """IMRaD-compliant document structure with enhanced validation:
-    1. Introduction: Motivation & Contributions
-    2. Background: Literature & Theory
-    3. Methods: Technical Implementation
-    4. Experiments: Protocols & Setup
-    5. Results: Empirical Findings
-    6. Discussion: Interpretation & Limitations
-    7. Conclusion: Summary & Future Work
+    """Abstract of the academic paper."""
+
+    chapters: List[ArticleChapter]
+    """List of ArticleChapter objects representing the academic paper's structure."""
 
-    Additional: Appendices, Ethics Review, Reproducibility Statements"""
+    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)
 
-    def init_from_outline(self, outline: ArticleOutline) -> Self:
-        """Initialize the article from a given outline.
+    @classmethod
+    def from_outline(cls, outline: ArticleOutline) -> "Article":
+        """Generates an article from the given outline.
 
         Args:
-            outline (ArticleOutline): The outline to initialize from.
+            outline (ArticleOutline): The outline to generate the article from.
 
         Returns:
-            Self: The current instance of the article.
+            Article: The generated article.
         """
         # Set the title from the outline
-        self.title = outline.title
+        article = Article(**outline.model_dump(include={"title", "abstract"}), chapters=[])
 
-        # Initialize chapters based on outline's chapters
-        self.chapters = []
-
-        for chapter_outline in outline.chapters:
+        for chapter in outline.chapters:
             # Create a new chapter
-            chapter = ArticleChapter(
-                title=chapter_outline.title,
-                description=chapter_outline.description,
-                writing_aim=["Implement " + chapter_outline.description],
-                support_to=[],
-                depend_on=[],
+            article_chapter = ArticleChapter(
                 sections=[],
+                **chapter.model_dump(exclude={"sections"}),
             )
-
-            # Create sections for each chapter
-            for section_outline in chapter_outline.sections:
-                section = ArticleSection(
-                    title=section_outline.title,
-                    description=section_outline.description,
-                    writing_aim=["Address " + section_outline.description],
-                    support_to=[],
-                    depend_on=[],
+            for section in chapter.sections:
+                # Create a new section
+                article_section = ArticleSection(
                     subsections=[],
+                    **section.model_dump(exclude={"subsections"}),
                 )
-
-                # Create subsections for each section
-                for subsection_outline in section_outline.subsections:
-                    subsection = ArticleSubsection(
-                        title=subsection_outline.title,
-                        description=subsection_outline.description,
-                        writing_aim=["Explain " + subsection_outline.description],
-                        support_to=[],
-                        depend_on=[],
-                        paragraphs=[
-                            Paragraph(
-                                description=f"Implementation of {subsection_outline.title}",
-                                writing_aim=["Present key concepts", "Support main arguments"],
-                                lines=[],
-                            )
-                        ],
+                for subsection in section.subsections:
+                    # Create a new subsection
+                    article_subsection = ArticleSubsection(
+                        paragraphs=[],
+                        **subsection.model_dump(),
                     )
-                    section.subsections.append(subsection)
+                    article_section.subsections.append(article_subsection)
+                article_chapter.sections.append(article_section)
+            article.chapters.append(article_chapter)
+        return article
 
-                chapter.sections.append(section)
+    def chap_iter(self) -> Generator[ArticleChapter, None, None]:
+        """Iterates over all chapters in the article.
 
-            self.chapters.append(chapter)
+        Yields:
+            ArticleChapter: Each chapter in the article.
+        """
+        yield from self.chapters
 
-        # Generate a placeholder abstract from the outline's prospect
-        self.abstract = f"Abstract: {outline.prospect}"
+    def section_iter(self) -> Generator[ArticleSection, None, None]:
+        """Iterates over all sections in the article.
 
-        return self
+        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:
+        """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.
+        """
+        chap = ok(
+            next(chap for chap in self.chap_iter() if chap.title == ref.referred_chapter_title), "Chapter not found"
+        )
+        if ref.referred_section_title is None:
+            return chap
+        sec = ok(next(sec for sec in chap.sections if sec.title == ref.referred_section_title))
+        if ref.referred_subsection_title is None:
+            return sec
+        return ok(next(subsec for subsec in sec.subsections if subsec.title == ref.referred_subsection_title))
+
+    def gather_dependencies(self, article: ArticleBase) -> List[ArticleBase]:
+        """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]
+
+        supports = []
+        for a in self.iter_dfs():
+            if article in {self.deref(b) for b in a.support_to}:
+                supports.append(a)
+
+        return list(set(depends + supports))
+
+    def gather_dependencies_recursive(self, article: ArticleBase) -> List[ArticleBase]:
+        """Gathers all dependencies recursively for the given article.
+
+        Args:
+            article (ArticleBase): The article to gather dependencies for.
+
+        Returns:
+            List[ArticleBase]: A list of all dependencies for the given article.
+        """
+        q = self.gather_dependencies(article)
+
+        deps = []
+        while a := q.pop():
+            deps.extend(self.gather_dependencies(a))
+
+        deps = list(
+            chain(
+                filter(lambda x: isinstance(x, ArticleChapter), deps),
+                filter(lambda x: isinstance(x, ArticleSection), deps),
+                filter(lambda x: isinstance(x, ArticleSubsection), deps),
+            )
+        )
+
+        # Initialize result containers
+        formatted_code = ""
+        processed_components = []
+
+        # Process all dependencies
+        while component := deps.pop():
+            # Skip duplicates
+            if (component_code := component.to_typst_code()) in formatted_code:
+                continue
+
+            # Add this component
+            formatted_code += component_code
+            processed_components.append(component)
+
+        return processed_components
+
+    def iter_dfs_with_deps(self) -> Generator[Tuple[ArticleBase, List[ArticleBase]], None, None]:
+        """Iterates through the article in a depth-first manner, yielding each component and its dependencies.
+
+        Yields:
+            Tuple[ArticleBase, List[ArticleBase]]: Each component and its dependencies.
+        """
+        for component in self.iter_dfs():
+            yield component, (self.gather_dependencies_recursive(component))
 
 
 # </editor-fold>