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

fabricatio/models/extra/article_main.py

@@ -0,0 +1,293 @@
+"""ArticleBase and ArticleSubsection classes for managing hierarchical document components."""
+
+from itertools import chain
+from typing import Generator, List, Self, Tuple
+
+from fabricatio.journal import logger
+from fabricatio.models.extra.article_base import (
+    ArticleBase,
+    ArticleMainBase,
+    ArticleRef,
+    ChapterBase,
+    SectionBase,
+    SubSectionBase,
+)
+from fabricatio.models.extra.article_outline import (
+    ArticleOutline,
+)
+from fabricatio.models.generic import CensoredAble, Display, PersistentAble, WithRef
+from fabricatio.models.utils import ok
+
+
+class Paragraph(CensoredAble):
+    """Structured academic paragraph blueprint for controlled content generation."""
+
+    description: str
+    """Functional summary of the paragraph's role in document structure."""
+
+    writing_aim: List[str]
+    """Specific communicative objectives for this paragraph's content."""
+
+    sentences: List[str]
+    """List of sentences forming the paragraph's content."""
+
+
+class ArticleSubsection(ArticleMainBase, SubSectionBase):
+    """Atomic argumentative unit with technical specificity."""
+
+    paragraphs: List[Paragraph]
+    """List of Paragraph objects containing the content of the subsection."""
+
+    def resolve_update_error(self, other: Self) -> str:
+        """Resolve update errors in the article outline."""
+        if self.title != other.title:
+            return f"Title `{other.title}` mismatched, expected `{self.title}`. "
+        return ""
+
+    def _update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance."""
+        logger.debug(f"Updating SubSection {self.title}")
+        self.paragraphs = other.paragraphs
+        return self
+
+    def to_typst_code(self) -> str:
+        """Converts the component into a Typst code snippet for rendering.
+
+        Returns:
+            str: Typst code snippet for rendering.
+        """
+        return f"=== {self.title}\n" + "\n\n".join("".join(p.sentences) for p in self.paragraphs)
+
+
+class ArticleSection(ArticleMainBase, SectionBase[ArticleSubsection]):
+    """Atomic argumentative unit with high-level specificity."""
+
+    def resolve_update_error(self, other: Self) -> str:
+        """Resolve update errors in the article outline."""
+        if (s_len := len(self.subsections)) == 0:
+            return ""
+
+        if s_len != len(other.subsections):
+            return f"Subsections length mismatched, expected {len(self.subsections)}, got {len(other.subsections)}"
+
+        sub_sec_err_seq = [
+            out for s, o in zip(self.subsections, other.subsections, strict=True) if (out := s.resolve_update_error(o))
+        ]
+
+        if sub_sec_err_seq:
+            return "\n".join(sub_sec_err_seq)
+        return ""
+
+    def _update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance."""
+        if len(self.subsections) == 0:
+            self.subsections = other.subsections
+            return self
+
+        for self_subsec, other_subsec in zip(self.subsections, other.subsections, strict=True):
+            self_subsec.update_from(other_subsec)
+        return self
+
+    def to_typst_code(self) -> str:
+        """Converts the section into a Typst formatted code snippet.
+
+        Returns:
+            str: The formatted Typst code snippet.
+        """
+        return f"== {self.title}\n" + "\n\n".join(subsec.to_typst_code() for subsec in self.subsections)
+
+
+class ArticleChapter(ArticleMainBase, ChapterBase[ArticleSection]):
+    """Thematic progression implementing research function."""
+
+    def resolve_update_error(self, other: Self) -> str:
+        """Resolve update errors in the article outline."""
+        if (s_len := len(self.sections)) == 0:
+            return ""
+
+        if s_len != len(other.sections):
+            return f"Sections length mismatched, expected {len(self.sections)}, got {len(other.sections)}"
+        sec_err_seq = [
+            out for s, o in zip(self.sections, other.sections, strict=True) if (out := s.resolve_update_error(o))
+        ]
+        if sec_err_seq:
+            return "\n".join(sec_err_seq)
+        return ""
+
+    def _update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance."""
+        if len(self.sections) == 0:
+            self.sections = other.sections
+            return self
+
+        for self_sec, other_sec in zip(self.sections, other.sections, strict=True):
+            self_sec.update_from(other_sec)
+        return self
+
+    def to_typst_code(self) -> str:
+        """Converts the chapter into a Typst formatted code snippet for rendering."""
+        return f"= {self.title}\n" + "\n\n".join(sec.to_typst_code() for sec in self.sections)
+
+
+class Article(Display, CensoredAble, WithRef[ArticleOutline], PersistentAble, ArticleBase[ArticleChapter]):
+    """Represents a complete academic paper specification, incorporating validation constraints.
+
+    This class integrates display, censorship processing, article structure referencing, and persistence capabilities,
+    aiming to provide a comprehensive model for academic papers.
+    """
+
+    abstract: str
+    """Contains a summary of the academic paper."""
+
+    title: str
+    """Represents the title of the academic paper."""
+
+    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)
+
+    @classmethod
+    def from_outline(cls, outline: ArticleOutline) -> "Article":
+        """Generates an article from the given outline.
+
+        Args:
+            outline (ArticleOutline): The outline to generate the article from.
+
+        Returns:
+            Article: The generated article.
+        """
+        # Set the title from the outline
+        article = Article(**outline.model_dump(include={"title", "abstract"}), chapters=[])
+
+        for chapter in outline.chapters:
+            # Create a new chapter
+            article_chapter = ArticleChapter(
+                sections=[],
+                **chapter.model_dump(exclude={"sections"}),
+            )
+            for section in chapter.sections:
+                # Create a new section
+                article_section = ArticleSection(
+                    subsections=[],
+                    **section.model_dump(exclude={"subsections"}),
+                )
+                for subsection in section.subsections:
+                    # Create a new subsection
+                    article_subsection = ArticleSubsection(
+                        paragraphs=[],
+                        **subsection.model_dump(),
+                    )
+                    article_section.subsections.append(article_subsection)
+                article_chapter.sections.append(article_section)
+            article.chapters.append(article_chapter)
+        return article
+
+    def iter_dfs(self) -> Generator[ArticleMainBase, None, None]:
+        """Performs a depth-first search (DFS) through the article structure.
+
+        Returns:
+            Generator[ArticleMainBase]: Each component in the article structure.
+        """
+        for chap in self.chapters:
+            for sec in chap.sections:
+                yield from sec.subsections
+                yield sec
+            yield chap
+
+    def deref(self, ref: ArticleRef) -> ArticleMainBase:
+        """Resolves a reference to the corresponding section or subsection in the article.
+
+        Args:
+            ref (ArticleRef): The reference to resolve.
+
+        Returns:
+            ArticleMainBase: The corresponding section or subsection.
+        """
+        return ok(ref.deref(self), f"{ref} not found in {self.title}")
+
+    def gather_dependencies(self, article: ArticleMainBase) -> List[ArticleMainBase]:
+        """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: ArticleMainBase) -> List[ArticleMainBase]:
+        """Gathers all dependencies recursively for the given article.
+
+        Args:
+            article (ArticleMainBase): 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 q:
+            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 deps:
+            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, chapter: bool = True, section: bool = True, subsection: bool = True
+    ) -> Generator[Tuple[ArticleMainBase, List[ArticleMainBase]], None, None]:
+        """Iterates through the article in a depth-first manner, yielding each component and its dependencies.
+
+        Args:
+            chapter (bool, optional): Whether to include chapter components. Defaults to True.
+            section (bool, optional): Whether to include section components. Defaults to True.
+            subsection (bool, optional): Whether to include subsection components. Defaults to True.
+
+        Yields:
+            Tuple[ArticleBase, List[ArticleBase]]: Each component and its dependencies.
+        """
+        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():
+            if not chapter and isinstance(component, ArticleChapter):
+                continue
+            if not section and isinstance(component, ArticleSection):
+                continue
+            if not subsection and isinstance(component, ArticleSubsection):
+                continue
+            yield component, (self.gather_dependencies_recursive(component))

fabricatio/models/extra/article_outline.py

@@ -0,0 +1,181 @@
+"""A module containing the ArticleOutline class, which represents the outline of an academic paper."""
+
+from typing import Generator, List, Optional, Tuple, Union
+
+import regex
+from fabricatio.models.extra.article_base import (
+    ArticleBase,
+    ArticleOutlineBase,
+    ChapterBase,
+    SectionBase,
+    SubSectionBase,
+)
+from fabricatio.models.extra.article_proposal import ArticleProposal
+from fabricatio.models.generic import CensoredAble, Display, PersistentAble, WithRef
+from fabricatio.models.utils import ok
+
+
+class ArticleSubsectionOutline(ArticleOutlineBase, SubSectionBase):
+    """Atomic research component specification for academic paper generation."""
+
+
+class ArticleSectionOutline(ArticleOutlineBase, SectionBase[ArticleSubsectionOutline]):
+    """A slightly more detailed research component specification for academic paper generation."""
+
+
+class ArticleChapterOutline(ArticleOutlineBase, ChapterBase[ArticleSectionOutline]):
+    """Macro-structural unit implementing standard academic paper organization."""
+
+
+class ArticleOutline(
+    Display,
+    CensoredAble,
+    WithRef[ArticleProposal],
+    PersistentAble,
+    ArticleBase[ArticleChapterOutline],
+):
+    """Complete academic paper blueprint with hierarchical validation."""
+
+    abstract: str
+    """The abstract is a concise summary of the academic paper's main findings."""
+
+    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
+    """
+
+    title: str
+    """Title of the academic paper."""
+
+    language: str
+    """Written language of the article. SHALL be aligned to the language of the article proposal provided."""
+
+    def finalized_dump(self) -> str:
+        """Generates standardized hierarchical markup for academic publishing systems.
+
+        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(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,35 @@
+"""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
+
+
+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.
+    """
+
+    technical_approaches: List[str]
+    """Technical approaches"""
+
+    research_methods: List[str]
+    """Methodological components (list of techniques/tools).
+    Example: ['Differentiable architecture search', 'Transformer-based search space', 'Multi-lingual perplexity evaluation']"""
+
+    research_aim: List[str]
+    """Primary research objectives (list of 2-4 measurable goals).
+    Example: ['Develop parameter-efficient NAS framework', 'Establish cross-lingual architecture transfer metrics']"""
+
+    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']"""
+
+    title: str
+    """Paper title in academic style (Title Case, 8-15 words). Example: 'Exploring Neural Architecture Search for Low-Resource Machine Translation'"""
+    language: str
+    """Written language of the article. SHALL be aligned to the language of the article briefing provided."""
+
+    def _as_prompt_inner(self) -> Dict[str, str]:
+        return {"ArticleBriefing": self.referenced, "ArticleProposal": self.display()}

fabricatio/models/generic.py

@@ -23,6 +23,7 @@ from pydantic import (
     PrivateAttr,
     SecretStr,
 )
+from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
 
 
 class Base(BaseModel):
@@ -103,6 +104,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."""
 
@@ -137,6 +173,23 @@ class WithBriefing(Named, Described):
                 raise TypeError(f"{system_msg_like} is not a dict or str")
 
 
+class ReverseGenerate(GenerateJsonSchema):
+    """Class that provides a reverse JSON schema of the model."""
+
+    def _sort_recursive(self, value: Any, parent_key: str | None = None) -> Any:
+        if isinstance(value, dict):
+            sorted_dict: dict[str, JsonSchemaValue] = {}
+            # Reverse all keys regardless of parent_key
+            keys = reversed(value.keys())
+            for key in keys:
+                sorted_dict[key] = self._sort_recursive(value[key], parent_key=key)
+            return sorted_dict
+        if isinstance(value, list):
+            # Reverse list order and process each item
+            return [self._sort_recursive(item, parent_key) for item in reversed(value)]
+        return value
+
+
 class WithFormatedJsonSchema(Base):
     """Class that provides a formatted JSON schema of the model."""
 
@@ -148,8 +201,8 @@ class WithFormatedJsonSchema(Base):
             str: The JSON schema of the model in a formatted string.
         """
         return orjson.dumps(
-            cls.model_json_schema(),
-            option=orjson.OPT_INDENT_2 | orjson.OPT_SORT_KEYS,
+            cls.model_json_schema(schema_generator=ReverseGenerate),
+            option=orjson.OPT_INDENT_2,
         ).decode()
 
 

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: