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

fabricatio/models/extra/article_outline.py

@@ -0,0 +1,276 @@
+"""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
+
+import regex
+from fabricatio.models.extra.article_proposal import ArticleProposal
+from fabricatio.models.generic import Base, 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):
+    """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 ArticleChapterOutline(ArticleOutlineBase):
+    """Macro-structural unit implementing standard academic paper organization."""
+
+    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 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."""
+
+    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
+
+    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."""
+
+    abstract: str
+    """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.
+
+        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
+        """
+        lines: List[str] = []
+        for i, chapter in enumerate(self.chapters, 1):
+            lines.append(f"= Chapter {i}: {chapter.title}")
+            for j, section in enumerate(chapter.sections, 1):
+                lines.append(f"== {i}.{j} {section.title}")
+                for k, subsection in enumerate(section.subsections, 1):
+                    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.
+
+        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.
+        """
+        summary = ""
+        for component in self.iter_dfs():
+            for ref in component.depend_on:
+                if not ref.deref(self):
+                    summary += f"Invalid internal reference in {component.__class__.__name__} titled `{component.title}` at `depend_on` field, because the referred {ref.referring_type} is not exists within the article, see the original obj dump: {ref.model_dump()}\n"
+            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
+
+    @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)
+        stack = [self]  # 根节点为ArticleOutline实例
+
+        for line in typst_code.splitlines():
+            parsed = cls._parse_line(line)
+            if not parsed:
+                continue
+            level, title = parsed
+            cls._adjust_stack(stack, level)
+            parent = stack[-1]
+            component = cls._create_component(level, title)
+            cls._add_to_parent(parent, component, level)
+            stack.append(component)
+
+        return self
+
+    @classmethod
+    def _parse_line(cls, line: str) -> Optional[Tuple[int, str]]:
+        stripped = line.strip()
+        if not stripped.startswith("="):
+            return None
+        match = regex.match(r"^(\=+)(.*)", stripped)
+        if not match:
+            return None
+        eqs, title_part = match.groups()
+        return len(eqs), title_part.strip()
+
+    @classmethod
+    def _adjust_stack(cls, stack: List[object], target_level: int) -> None:
+        while len(stack) > target_level:
+            stack.pop()
+
+    @classmethod
+    def _create_component(cls, level: int, title: str) -> ArticleOutlineBase:
+        default_kwargs = {
+            "writing_aim": [],
+            "depend_on": [],
+            "support_to": [],
+            "description": [],
+        }
+        component_map = {
+            1: lambda: ArticleChapterOutline(title=title, sections=[], **default_kwargs),
+            2: lambda: ArticleSectionOutline(title=title, subsections=[], **default_kwargs),
+            3: lambda: ArticleSubsectionOutline(title=title, **default_kwargs),
+        }
+        return ok(component_map.get(level, lambda: None)(), "Invalid level")
+
+    @classmethod
+    def _add_to_parent(
+        cls,
+        parent: Union["ArticleOutline", ArticleChapterOutline, ArticleSectionOutline],
+        component: ArticleOutlineBase,
+        level: int,
+    ) -> None:
+        if level == 1 and isinstance(component, ArticleChapterOutline):
+            parent.chapters.append(component)
+        elif level == 2 and isinstance(component, ArticleSectionOutline):  # noqa: PLR2004
+            parent.sections.append(component)
+        elif level == 3 and isinstance(component, ArticleSubsectionOutline):  # noqa: PLR2004
+            parent.subsections.append(component)

fabricatio/models/extra/article_proposal.py

@@ -0,0 +1,37 @@
+"""A structured proposal for academic paper development with core research elements."""
+
+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):
+    """Structured proposal for academic paper development with core research elements.
+
+    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'"""
+
+    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]
+    """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']"""
+
+    technical_approaches: List[str]
+    """Technical approaches"""
+
+    def _as_prompt_inner(self) -> Dict[str, str]:
+        return {"ArticleBriefing": self.referenced, "ArticleProposal": self.display()}

fabricatio/models/generic.py

@@ -103,6 +103,41 @@ class WithRef[T](Base):
         return self
 
 
+class PersistentAble(Base):
+    """Class that provides a method to persist the object."""
+
+    def persist(self, path: str | Path) -> Self:
+        """Persist the object to a file.
+
+        Args:
+            path (str | Path): The path to save the object.
+
+        Returns:
+            Self: The current instance of the object.
+        """
+        p = Path(path)
+        out = self.model_dump_json()
+        if p.is_dir():
+            p.joinpath(f"{self.__class__.__name__}_{blake3_hash(out.encode())[:6]}.json").write_text(
+                out, encoding="utf-8"
+            )
+            return self
+        p.mkdir(exist_ok=True, parents=True)
+        p.write_text(out, encoding="utf-8")
+        return self
+
+    def from_persistent(self, path: str | Path) -> Self:
+        """Load the object from a file.
+
+        Args:
+            path (str | Path): The path to load the object from.
+
+        Returns:
+            Self: The current instance of the object.
+        """
+        return self.model_validate_json(Path(path).read_text(encoding="utf-8"))
+
+
 class WithBriefing(Named, Described):
     """Class that provides a briefing based on the name and description."""
 

fabricatio/models/utils.py

@@ -11,11 +11,11 @@ class Message(BaseModel):
     """A class representing a message."""
 
     model_config = ConfigDict(use_attribute_docstrings=True)
-    role: Literal["user", "system", "assistant"] = Field(default="user")
+    role: Literal["user", "system", "assistant"]
     """
     Who is sending the message.
     """
-    content: str = Field(default="")
+    content: str
     """
     The content of the message.
     """
@@ -172,12 +172,14 @@ def override_kwargs[T](kwargs: Dict[str, T], **overrides) -> Dict[str, T]:
     kwargs.update({k: v for k, v in overrides.items() if v is not None})
     return kwargs
 
+
 def fallback_kwargs[T](kwargs: Dict[str, T], **overrides) -> Dict[str, T]:
     """Fallback the values in kwargs with the provided overrides."""
-    kwargs.update({k: v for k, v in overrides.items() if  k not in kwargs})
+    kwargs.update({k: v for k, v in overrides.items() if k not in kwargs})
     return kwargs
 
-def ok[T](val: Optional[T], msg:str="Value is None") -> T:
+
+def ok[T](val: Optional[T], msg: str = "Value is None") -> T:
     """Check if a value is None and raise a ValueError with the provided message if it is.
 
     Args:

{fabricatio-0.2.7.dev2.dist-info → fabricatio-0.2.7.dev3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fabricatio
-Version: 0.2.7.dev2
+Version: 0.2.7.dev3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3.12

{fabricatio-0.2.7.dev2.dist-info → fabricatio-0.2.7.dev3.dist-info}/RECORD

@@ -1,7 +1,8 @@
-fabricatio-0.2.7.dev2.dist-info/METADATA,sha256=FuFYXWRaOSL3hauoIRP1WP_dJtA9qQ90MVE9H_HFrAk,14236
-fabricatio-0.2.7.dev2.dist-info/WHEEL,sha256=jABKVkLC9kJr8mi_er5jOqpiQUjARSLXDUIIxDqsS50,96
-fabricatio-0.2.7.dev2.dist-info/licenses/LICENSE,sha256=do7J7EiCGbq0QPbMAL_FqLYufXpHnCnXBOuqVPwSV8Y,1088
-fabricatio/actions/article.py,sha256=u1rS2AAUts2mnPqRePQFWhZBvUlNwQO4mKUmfR4qaJA,7514
+fabricatio-0.2.7.dev3.dist-info/METADATA,sha256=6O8sm_fbzBC9kYdt9UKzf8ZoXEfFcLGWKHOgJMvC52Q,14236
+fabricatio-0.2.7.dev3.dist-info/WHEEL,sha256=jABKVkLC9kJr8mi_er5jOqpiQUjARSLXDUIIxDqsS50,96
+fabricatio-0.2.7.dev3.dist-info/licenses/LICENSE,sha256=do7J7EiCGbq0QPbMAL_FqLYufXpHnCnXBOuqVPwSV8Y,1088
+fabricatio/actions/article.py,sha256=AgxNKIRLXF9T-TdrhLPE8NWmT8QZXz1QvFnouvuoRBc,7684
+fabricatio/actions/article_rag.py,sha256=PiOFxI6VTmLXm3BK-01g_KH1mTE9uOtnA-CwUjt16AU,1456
 fabricatio/actions/output.py,sha256=K7xsBH8MjXRH6JOy3ZO94KCQzX2jNrwPPK_rRXVkS0E,1161
 fabricatio/actions/rag.py,sha256=QBdzEM8MloM_ahx5pTBZAETm9_631lTe_0ih_he_Iuo,2759
 fabricatio/capabilities/correct.py,sha256=8GOU2VBPUakjG-r59SqsCgCD0QHX-l__IynCLO-ib8Q,6482
@@ -19,14 +20,17 @@ fabricatio/fs/__init__.py,sha256=PCf0s_9KDjVfNw7AfPoJzGt3jMq4gJOfbcT4pb0D0ZY,588
 fabricatio/journal.py,sha256=stnEP88aUBA_GmU9gfTF2EZI8FS2OyMLGaMSTgK4QgA,476
 fabricatio/models/action.py,sha256=UlflniS__MMrUXglu_U3PDFAtKEjVsKEix17AT9oP3M,8769
 fabricatio/models/events.py,sha256=QvlnS8FEELg6KNabcJMeh2GV_y0ZBzKOPphcteKYWYU,4183
-fabricatio/models/extra.py,sha256=g1w4fPPN-znbDFLQYxTzT-ngvi_mwiA3BXBK3U4XfgU,33415
-fabricatio/models/generic.py,sha256=k4nGSnCKmCqcRs852jhphILZXwRRuNAhx1rf4ZBCPF0,15731
+fabricatio/models/extra/article_essence.py,sha256=DUESuK4CGgkRvIMoJCv4l8MNp5MawRYoNOtLCrFRPXY,9229
+fabricatio/models/extra/article_main.py,sha256=F6rhHMICErzvtRIEWdxS5AoY9thLhUUeDofoJbNF9ZI,13984
+fabricatio/models/extra/article_outline.py,sha256=0t-aI3OtY1O1_dhwDDm1y4kUdqoh4bmQ8voNe6MDU4w,12452
+fabricatio/models/extra/article_proposal.py,sha256=eXtomW88urP9M4aKbVNN9dct0GH-fBwYOM_Rcq3d7j4,1771
+fabricatio/models/generic.py,sha256=TXNPGeVOWJnCKJ6KZU8T-SWQ913woX4Xt1BLJ0x4V9M,16820
 fabricatio/models/kwargs_types.py,sha256=chJ-rHaeBVRUPuORHuGR3DdNxxTUrotz0eflPEh4l4w,5474
 fabricatio/models/role.py,sha256=mmQbJ6GKr2Gx3wtjEz8d-vYoXs09ffcEkT_eCXaDd3E,2782
 fabricatio/models/task.py,sha256=8NaR7ojQWyM740EDTqt9stwHKdrD6axCRpLKo0QzS-I,10492
 fabricatio/models/tool.py,sha256=kD0eB7OxO9geZOxO6JIKvCBeG-KOpRAkfRZqK_WGfW4,7105
 fabricatio/models/usages.py,sha256=BSqTENSva8Flga3bPBfwuc1nHo5Z_29oYzar99NbjLM,31566
-fabricatio/models/utils.py,sha256=NyIS82Gex4Q9qs6pzys5HplQ6JJXOLJBj4OkMPZYioc,5910
+fabricatio/models/utils.py,sha256=yjxPZ6N7QGpGwkI_Vb28Ud3EhkdlB-tyfGRHAZMcGxs,5872
 fabricatio/parser.py,sha256=9Jzw-yV6uKbFvf6sPna-XHdziVGVBZWvPctgX_6ODL8,6251
 fabricatio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 fabricatio/toolboxes/arithmetic.py,sha256=WLqhY-Pikv11Y_0SGajwZx3WhsLNpHKf9drzAqOf_nY,1369
@@ -37,6 +41,6 @@ fabricatio/workflows/rag.py,sha256=-YYp2tlE9Vtfgpg6ROpu6QVO8j8yVSPa6yDzlN3qVxs,5
 fabricatio/_rust.pyi,sha256=dGTGV7viu3YAGl1cRKIWrdHPc1hlwk3_hbaDaswxdVo,3831
 fabricatio/_rust_instances.py,sha256=2GwF8aVfYNemRI2feBzH1CZfBGno-XJJE5imJokGEYw,314
 fabricatio/__init__.py,sha256=SzBYsRhZeL77jLtfJEjmoHOSwHwUGyvMATX6xfndLDM,1135
-fabricatio/_rust.cp312-win_amd64.pyd,sha256=lOWesZXJMOLJI1YaeUJ7POMGcUkj18dalXlv-eNHKQ0,1840128
-fabricatio-0.2.7.dev2.data/scripts/tdown.exe,sha256=3Hnf6QrzesUMqUflXmsbyS8IJgPJ45sTupsZlaWk9yM,3402752
-fabricatio-0.2.7.dev2.dist-info/RECORD,,
+fabricatio/_rust.cp312-win_amd64.pyd,sha256=JqLbZHAa0qBcJyWzAWC4Px5MTCxV9VN_BMsfm4saGus,1840128
+fabricatio-0.2.7.dev3.data/scripts/tdown.exe,sha256=2sqdWL-XEloL8IsQRQ9wZ_4O0aaLO02jgeb8KWCLgdM,3402752
+fabricatio-0.2.7.dev3.dist-info/RECORD,,