fabricatio 0.2.7.dev2__cp312-cp312-win_amd64.whl → 0.2.7.dev4__cp312-cp312-win_amd64.whl

fabricatio/actions/article.py

@@ -6,7 +6,10 @@ from typing import Any, Callable, List, Optional
 from fabricatio.fs import safe_text_read
 from fabricatio.journal import logger
 from fabricatio.models.action import Action
-from fabricatio.models.extra import Article, ArticleEssence, ArticleOutline, ArticleProposal
+from fabricatio.models.extra.article_essence import ArticleEssence
+from fabricatio.models.extra.article_main import Article
+from fabricatio.models.extra.article_outline import ArticleOutline
+from fabricatio.models.extra.article_proposal import ArticleProposal
 from fabricatio.models.task import Task
 from fabricatio.models.utils import ok
 

fabricatio/actions/article_rag.py

@@ -0,0 +1,35 @@
+"""A module for writing articles using RAG (Retrieval-Augmented Generation) capabilities."""
+
+from typing import Optional
+
+from fabricatio.capabilities.rag import RAG
+from fabricatio.journal import logger
+from fabricatio.models.action import Action
+from fabricatio.models.extra.article_main import Article
+from fabricatio.models.extra.article_outline import ArticleOutline
+
+
+class GenerateArticleRAG(Action, RAG):
+    """Write an article based on the provided outline."""
+
+    output_key: str = "article"
+
+    async def _execute(self, article_outline: ArticleOutline, **cxt) -> Optional[Article]:
+        """Write an article based on the provided outline."""
+        logger.info(f"Writing an article based on the outline:\n{article_outline.title}")
+        refined_q = await self.arefined_query(article_outline.display())
+        return await self.propose(
+            Article,
+            article_outline.display(),
+            **self.prepend_sys_msg(f"{await self.aretrieve_compact(refined_q)}\n{self.briefing}"),
+        )
+
+
+class WriteArticleFineGrind(Action, RAG):
+    """Fine-grind an article based on the provided outline."""
+
+    output_key: str = "article"
+
+    async def _execute(self, article_outline: ArticleOutline, **cxt) -> Optional[Article]:
+        """Fine-grind an article based on the provided outline."""
+        logger.info(f"Fine-grinding an article based on the outline:\n{article_outline.title}")

fabricatio/models/extra/article_base.py

@@ -0,0 +1,192 @@
+"""A foundation for hierarchical document components with dependency tracking."""
+
+from abc import abstractmethod
+from enum import StrEnum
+from typing import TYPE_CHECKING, List, Optional, Self, Union, final, overload
+
+from fabricatio.models.generic import Base, CensoredAble, Display, PersistentAble
+from pydantic import Field
+
+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."""
+
+    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.
+
+    Examples:
+        - Referring to a chapter titled `Introduction`:
+            Using Python
+            ```python
+            ArticleRef(referred_chapter_title="Introduction")
+            ```
+            Using JSON
+            ```json
+            {referred_chapter_title="Introduction"}
+            ```
+        - Referring to a section titled `Background` under the `Introduction` chapter:
+            Using Python
+            ```python
+            ArticleRef(referred_chapter_title="Introduction", referred_section_title="Background")
+            ```
+            Using JSON
+            ```json
+            {referred_chapter_title="Introduction", referred_section_title="Background"}
+            ```
+        - Referring to a subsection titled `Related Work` under the `Background` section of the `Introduction` chapter:
+            Using Python
+            ```python
+            ArticleRef(referred_chapter_title="Introduction", referred_section_title="Background", referred_subsection_title="Related Work")
+            ```
+            Using JSON
+            ```json
+            {referred_chapter_title="Introduction", referred_section_title="Background", referred_subsection_title="Related Work"}
+            ```
+    """
+
+    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"""
+
+    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 deref(
+        self, article: Union["ArticleOutline", "Article"]
+    ) -> Union["ArticleOutlineBase", "ArticleMainBase", 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:
+            ArticleMainBase | 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 SubSectionBase(Base):
+    """Base class for article sections and subsections."""
+
+
+class SectionBase[T: SubSectionBase](Base):
+    """Base class for article sections and subsections."""
+
+    subsections: List[T] = 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 ChapterBase[T: SectionBase](Base):
+    """Base class for article chapters."""
+
+    sections: List[T] = Field(min_length=1)
+    """List of sections, each containing a specific research component. Must contains at least 1 section, But do remember you should always add more section as required."""
+
+
+class ArticleBase[T: ChapterBase](Base):
+    """Base class for article outlines."""
+
+    chapters: List[T] = Field(min_length=5)
+    """List of chapters, each containing a specific research component. Must contains at least 5 chapters, But do remember you should always add more chapter as required."""
+
+
+class ArticleOutlineBase(Base):
+    """Base class for article outlines."""
+
+    title: str
+    """Title of the research component in academic style."""
+    description: str
+    """Description of the research component in academic style."""
+
+    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."""
+    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."""
+
+    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']"""
+
+
+class ArticleMainBase(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: "ArticleMainBase") -> 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())

fabricatio/models/extra/article_essence.py

@@ -0,0 +1,226 @@
+"""ArticleEssence: Semantic fingerprint of academic paper for structured analysis."""
+
+from typing import List
+
+from fabricatio.models.generic import Display, PrepareVectorization, ProposedAble
+from pydantic import BaseModel, Field
+
+
+class Equation(BaseModel):
+    """Mathematical formalism specification for research contributions.
+
+    Encodes equations with dual representation: semantic meaning and typeset-ready notation.
+    """
+
+    description: str
+    """Equation significance structured in three elements:
+    1. Physical/conceptual meaning of the equation.
+    2. Role in technical workflow (e.g., derivation, optimization, or analysis).
+    3. Relationship to the paper's core contribution (e.g., theoretical foundation, empirical validation).
+    Example: "Defines constrained search space dimensionality reduction. Used in architecture optimization phase (Section 3.2). Enables 40% parameter reduction."
+    """
+
+    latex_code: str
+    """LaTeX representation following academic typesetting standards:
+    - Must use equation environment (e.g., `equation`, `align`).
+    - Multiline equations must align at '=' using `&`.
+    - Include unit annotations where applicable.
+    Example: "\\begin{equation} \\mathcal{L}_{NAS} = \\alpha \\|\\theta\\|_2 + \\beta H(p) \\end{equation}"
+    """
+
+
+class Figure(BaseModel):
+    """Visual component specification for technical communication.
+
+    Combines graphical assets with structured academic captioning.Extracted from the article provided
+    """
+
+    description: str
+    """Figure interpretation guide containing:
+    1. Key visual elements mapping (e.g., axes, legends, annotations).
+    2. Data representation methodology (e.g., visualization type, statistical measures).
+    3. Connection to research findings (e.g., supports hypothesis, demonstrates performance).
+    Example: "Architecture search space topology (left) vs. convergence curves (right). Demonstrates NAS efficiency gains through constrained search."
+    """
+
+    figure_caption: str
+    """Complete caption following Nature-style guidelines:
+    1. Brief overview statement (首句总结).
+    2. Technical detail layer (e.g., data sources, experimental conditions).
+    3. Result implication (e.g., key insights, implications for future work).
+    Example: "Figure 3: Differentiable NAS framework. (a) Search space topology with constrained dimensions. (b) Training convergence across language pairs. Dashed lines indicate baseline methods."
+    """
+
+    figure_serial_number: int
+    """The Image serial number extracted from the Markdown article provided, the path usually in the form of `![](images/1.jpg)`, in this case the serial number is `1`"""
+
+
+class Algorithm(BaseModel):
+    """Algorithm specification for research contributions."""
+
+    title: str
+    """Algorithm title with technical focus descriptor (e.g., 'Gradient Descent Optimization').
+
+    Tip: Do not attempt to translate the original element titles when generating JSON.
+    """
+
+    description: str
+    """Algorithm description with technical focus descriptor:
+    - Includes input/output specifications.
+    - Describes key steps and their purpose.
+    - Explains its role in the research workflow.
+    Example: "Proposed algorithm for neural architecture search. Inputs include search space constraints and training data. Outputs optimized architecture."
+    """
+
+
+class Table(BaseModel):
+    """Table specification for research contributions."""
+
+    title: str
+    """Table title with technical focus descriptor (e.g., 'Comparison of Model Performance Metrics').
+
+    Tip: Do not attempt to translate the original element titles when generating JSON.
+    """
+
+    description: str
+    """Table description with technical focus descriptor:
+    - Includes data source and structure.
+    - Explains key columns/rows and their significance.
+    - Connects to research findings or hypotheses.
+    Example: "Performance metrics for different architectures. Columns represent accuracy, F1-score, and inference time. Highlights efficiency gains of proposed method."
+    """
+
+
+class Highlightings(BaseModel):
+    """Technical showcase aggregator for research artifacts.
+
+    Curates core scientific components with machine-parseable annotations.
+    """
+
+    highlighted_equations: List[Equation]
+    """3-5 pivotal equations representing theoretical contributions:
+    - Each equation must be wrapped in $$ for display math.
+    - Contain at least one novel operator/symbol.
+    - Be referenced in Methods/Results sections.
+    Example: Equation describing proposed loss function.
+    """
+
+    highlighted_algorithms: List[Algorithm]
+    """1-2 key algorithms demonstrating methodological contributions:
+    - Include pseudocode or step-by-step descriptions.
+    - Highlight innovation in computational approach.
+    Example: Algorithm for constrained search space exploration.
+
+    Tip: Do not attempt to translate the original element titles when generating JSON.
+    """
+
+    highlighted_figures: List[Figure]
+    """4-6 key figures demonstrating:
+    1. Framework overview (1 required).
+    2. Quantitative results (2-3 required).
+    3. Ablation studies (1 optional).
+    Each must appear in Results/Discussion chapters.
+    Example: Figure showing architecture topology and convergence curves.
+    """
+
+    highlighted_tables: List[Table]
+    """2-3 key tables summarizing:
+    - Comparative analysis of methods.
+    - Empirical results supporting claims.
+    Example: Table comparing model performance across datasets.
+
+    Tip: Do not attempt to translate the original element titles when generating JSON.
+    """
+
+
+class ArticleEssence(ProposedAble, Display, PrepareVectorization):
+    """Semantic fingerprint of academic paper for structured analysis.
+
+    Encodes research artifacts with dual human-machine interpretability.
+    """
+
+    title: str = Field(...)
+    """Exact title of the original article without any modification.
+    Must be preserved precisely from the source material without:
+    - Translation
+    - Paraphrasing
+    - Adding/removing words
+    - Altering style or formatting
+    """
+
+    authors: List[str]
+    """Original author 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]
+    """Original keywords exactly as they appear in the source document. No translation or paraphrasing.
+    Extract the complete set without modifying format or terminology."""
+
+    publication_year: int
+    """Publication timestamp in ISO 8601 (YYYY format)."""
+
+    highlightings: Highlightings
+    """Technical highlight reel containing:
+    - Core equations (Theory)
+    - Key algorithms (Implementation)
+    - Critical figures (Results)
+    - Benchmark tables (Evaluation)"""
+
+    domain: List[str]
+    """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"""
+
+    core_contributions: List[str]
+    """3-5 technical contributions using CRediT taxonomy verbs.
+    Each item starts with action verb.
+    Example:
+    - 'Developed constrained NAS framework'
+    - 'Established cross-lingual transfer metrics'"""
+
+    technical_novelty: List[str]
+    """Patent-style claims with technical specificity.
+    Format: 'A [system/method] comprising [novel components]...'
+    Example:
+    'A neural architecture search system comprising:
+     a differentiable constrained search space;
+     multi-lingual transferability predictors...'"""
+
+    research_problems: List[str]
+    """Problem statements as how/why questions.
+    Example:
+    - 'How to reduce NAS computational overhead while maintaining search diversity?'
+    - 'Why do existing architectures fail in low-resource cross-lingual transfer?'"""
+
+    limitations: List[str]
+    """Technical limitations analysis containing:
+    1. Constraint source (data/method/theory)
+    2. Impact quantification
+    3. Mitigation pathway
+    Example:
+    'Methodology constraint: Single-objective optimization (affects 5% edge cases),
+    mitigated through future multi-task extension'"""
+
+    future_work: List[str]
+    """Research roadmap items with 3 horizons:
+    1. Immediate extensions (1 year)
+    2. Mid-term directions (2-3 years)
+    3. Long-term vision (5+ years)
+    Example:
+    'Short-term: Adapt framework for vision transformers (ongoing with CVPR submission)'"""
+
+    impact_analysis: List[str]
+    """Bibliometric impact projections:
+    - Expected citation counts (next 3 years)
+    - Target application domains
+    - Standard adoption potential
+    Example:
+    'Predicted 150+ citations via integration into MMEngine (Alibaba OpenMMLab)'"""
+
+    def _prepare_vectorization_inner(self) -> str:
+        return self.model_dump_json()