fabricatio 0.2.6.dev2__cp312-cp312-win_amd64.whl → 0.2.7__cp312-cp312-win_amd64.whl

fabricatio/models/action.py

@@ -1,4 +1,8 @@
-"""Module that contains the classes for actions and workflows."""
+"""Module that contains the classes for actions and workflows.
+
+This module defines the Action and WorkFlow classes, which are used for
+creating and executing sequences of actions in a task-based context.
+"""
 
 import traceback
 from abc import abstractmethod
@@ -15,20 +19,27 @@ from pydantic import Field, PrivateAttr
 
 
 class Action(HandleTask, ProposeTask, Correct):
-    """Class that represents an action to be executed in a workflow."""
+    """Class that represents an action to be executed in a workflow.
+
+    Actions are the atomic units of work in a workflow. Each action performs
+    a specific operation and can modify the shared context data.
+    """
 
     name: str = Field(default="")
     """The name of the action."""
+
     description: str = Field(default="")
     """The description of the action."""
+
     personality: str = Field(default="")
-    """The personality of whom the action belongs to."""
+    """The personality traits or context for the action executor."""
+
     output_key: str = Field(default="")
-    """The key of the output data."""
+    """The key used to store this action's output in the context dictionary."""
 
     @final
     def model_post_init(self, __context: Any) -> None:
-        """Initialize the action by setting the name if not provided.
+        """Initialize the action by setting default name and description if not provided.
 
         Args:
             __context: The context to be used for initialization.
@@ -37,122 +48,185 @@ class Action(HandleTask, ProposeTask, Correct):
         self.description = self.description or self.__class__.__doc__ or ""
 
     @abstractmethod
-    async def _execute(self, **cxt) -> Any:
-        """Execute the action with the provided arguments.
+    async def _execute(self, *_, **cxt) -> Any:  # noqa: ANN002
+        """Execute the action logic with the provided context arguments.
+
+        This method must be implemented by subclasses to define the actual behavior.
 
         Args:
             **cxt: The context dictionary containing input and output data.
 
         Returns:
-            The result of the action execution.
+            Any: The result of the action execution.
         """
         pass
 
     @final
     async def act(self, cxt: Dict[str, Any]) -> Dict[str, Any]:
-        """Perform the action by executing it and setting the output data.
+        """Perform the action and update the context with results.
 
         Args:
             cxt: The context dictionary containing input and output data.
+
+        Returns:
+            Dict[str, Any]: The updated context dictionary.
         """
         ret = await self._execute(**cxt)
+
         if self.output_key:
             logger.debug(f"Setting output: {self.output_key}")
             cxt[self.output_key] = ret
+
         return cxt
 
     @property
     def briefing(self) -> str:
-        """Return a brief description of the action."""
+        """Return a formatted description of the action including personality context if available.
+
+        Returns:
+            str: Formatted briefing text with personality and action description.
+        """
         if self.personality:
             return f"## Your personality: \n{self.personality}\n# The action you are going to perform: \n{super().briefing}"
         return f"# The action you are going to perform: \n{super().briefing}"
 
 
 class WorkFlow(WithBriefing, ToolBoxUsage):
-    """Class that represents a workflow to be executed in a task."""
+    """Class that represents a sequence of actions to be executed for a task.
+
+    A workflow manages the execution of multiple actions in sequence, passing
+    a shared context between them and handling task lifecycle events.
+    """
 
     _context: Queue[Dict[str, Any]] = PrivateAttr(default_factory=lambda: Queue(maxsize=1))
-    """ The context dictionary to be used for workflow execution."""
+    """Queue for storing the workflow execution context."""
 
     _instances: Tuple[Action, ...] = PrivateAttr(default_factory=tuple)
-    """ The instances of the workflow steps."""
+    """Instantiated action objects to be executed in this workflow."""
 
     steps: Tuple[Union[Type[Action], Action], ...] = Field(...)
-    """ The steps to be executed in the workflow, actions or action classes."""
+    """The sequence of actions to be executed, can be action classes or instances."""
+
     task_input_key: str = Field(default="task_input")
-    """ The key of the task input data."""
+    """Key used to store the input task in the context dictionary."""
+
     task_output_key: str = Field(default="task_output")
-    """ The key of the task output data."""
+    """Key used to extract the final result from the context dictionary."""
+
     extra_init_context: Dict[str, Any] = Field(default_factory=dict, frozen=True)
-    """ The extra context dictionary to be used for workflow initialization."""
+    """Additional initial context values to be included at workflow start."""
 
     def model_post_init(self, __context: Any) -> None:
-        """Initialize the workflow by setting fallbacks for each step.
+        """Initialize the workflow by instantiating any action classes.
 
         Args:
             __context: The context to be used for initialization.
         """
-        temp = []
-        for step in self.steps:
-            temp.append(step if isinstance(step, Action) else step())
-        self._instances = tuple(temp)
+        # Convert any action classes to instances
+        self._instances = tuple(step if isinstance(step, Action) else step() for step in self.steps)
 
     def inject_personality(self, personality: str) -> Self:
-        """Inject the personality of the workflow.
+        """Set the personality for all actions that don't have one defined.
 
         Args:
-            personality: The personality to be injected.
+            personality: The personality text to inject.
 
         Returns:
-            Self: The instance of the workflow with the injected personality.
+            Self: The workflow instance for method chaining.
         """
-        for a in filter(lambda action: not action.personality, self._instances):
-            a.personality = personality
+        for action in filter(lambda a: not a.personality, self._instances):
+            action.personality = personality
         return self
 
     async def serve(self, task: Task) -> None:
-        """Serve the task by executing the workflow steps.
+        """Execute the workflow to fulfill the given task.
+
+        This method manages the complete lifecycle of processing a task through
+        the workflow's sequence of actions.
 
         Args:
-            task: The task to be served.
+            task: The task to be processed.
         """
+        logger.info(f"Start execute workflow: {self.name}")
+
         await task.start()
         await self._init_context(task)
+
         current_action = None
         try:
+            # Process each action in sequence
             for step in self._instances:
-                logger.debug(f"Executing step: {(current_action := step.name)}")
-                act_task = create_task(step.act(await self._context.get()))
+                current_action = step.name
+                logger.info(f"Executing step: {current_action}")
+
+                # Get current context and execute action
+                context = await self._context.get()
+                act_task = create_task(step.act(context))
+                # Handle task cancellation
                 if task.is_cancelled():
                     act_task.cancel(f"Cancelled by task: {task.name}")
                     break
+
+                # Update context with modified values
                 modified_ctx = await act_task
+                logger.success(f"Step execution finished: {current_action}")
                 await self._context.put(modified_ctx)
-            logger.info(f"Finished executing workflow: {self.name}")
 
-            if self.task_output_key not in (final_ctx := await self._context.get()):
+            logger.success(f"Workflow execution finished: {self.name}")
+
+            # Get final context and extract result
+            final_ctx = await self._context.get()
+            result = final_ctx.get(self.task_output_key)
+
+            if self.task_output_key not in final_ctx:
                 logger.warning(
-                    f"Task output key: {self.task_output_key} not found in the context, None will be returned. You can check if `Action.output_key` is set the same as `WorkFlow.task_output_key`."
+                    f"Task output key: {self.task_output_key} not found in the context, None will be returned. "
+                    f"You can check if `Action.output_key` is set the same as `WorkFlow.task_output_key`."
                 )
 
-            await task.finish(final_ctx.get(self.task_output_key, None))
-        except RuntimeError as e:
-            logger.error(f"Error during task: {current_action} execution: {e}")  # Log the exception
-            logger.error(traceback.format_exc())  # Add this line to log the traceback
-            await task.fail()  # Mark the task as failed
+            await task.finish(result)
+
+        except Exception as e:  # noqa: BLE001
+            logger.critical(f"Error during task: {current_action} execution: {e}")
+            logger.critical(traceback.format_exc())
+            await task.fail()
 
     async def _init_context[T](self, task: Task[T]) -> None:
-        """Initialize the context dictionary for workflow execution."""
+        """Initialize the context dictionary for workflow execution.
+
+        Args:
+            task: The task being served by this workflow.
+        """
         logger.debug(f"Initializing context for workflow: {self.name}")
-        await self._context.put({self.task_input_key: task, **dict(self.extra_init_context)})
+        initial_context = {self.task_input_key: task, **dict(self.extra_init_context)}
+        await self._context.put(initial_context)
 
     def steps_fallback_to_self(self) -> Self:
-        """Set the fallback for each step to the workflow itself."""
+        """Configure all steps to use this workflow's configuration as fallback.
+
+        Returns:
+            Self: The workflow instance for method chaining.
+        """
         self.hold_to(self._instances)
         return self
 
     def steps_supply_tools_from_self(self) -> Self:
-        """Supply the tools from the workflow to each step."""
+        """Provide this workflow's tools to all steps in the workflow.
+
+        Returns:
+            Self: The workflow instance for method chaining.
+        """
         self.provide_tools_to(self._instances)
         return self
+
+    def update_init_context(self, **kwargs) -> Self:
+        """Update the initial context with additional key-value pairs.
+
+        Args:
+            **kwargs: Key-value pairs to add to the initial context.
+
+        Returns:
+            Self: The workflow instance for method chaining.
+        """
+        self.extra_init_context.update(kwargs)
+        return self

fabricatio/models/extra/article_base.py

@@ -0,0 +1,378 @@
+"""A foundation for hierarchical document components with dependency tracking."""
+
+from abc import abstractmethod
+from enum import StrEnum
+from typing import Generator, List, Optional, Self, Tuple
+
+from fabricatio.models.generic import (
+    CensoredAble,
+    Display,
+    FinalizedDumpAble,
+    Introspect,
+    ModelHash,
+    PersistentAble,
+    ProposedAble,
+    ResolveUpdateConflict,
+    UpdateFrom,
+)
+
+
+class ReferringType(StrEnum):
+    """Enumeration of different types of references that can be made in an article."""
+
+    CHAPTER = "chapter"
+    SECTION = "section"
+    SUBSECTION = "subsection"
+
+
+class ArticleRef(CensoredAble, Display):
+    """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_chapter_title: str
+    """`title` Field of the referenced chapter"""
+    referred_section_title: Optional[str] = None
+    """`title` Field of the referenced section."""
+    referred_subsection_title: Optional[str] = None
+    """`title` Field of the referenced subsection."""
+
+    def __hash__(self) -> int:
+        """Overrides the default hash function to ensure consistent hashing across instances."""
+        return hash((self.referred_chapter_title, self.referred_section_title, self.referred_subsection_title))
+
+    def deref(self, article: "ArticleBase") -> Optional["ArticleOutlineBase"]:
+        """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 ArticleMetaData(CensoredAble, Display):
+    """Metadata for an article component."""
+
+    description: str
+    """Description of the research component in academic style."""
+
+    support_to: List[ArticleRef]
+    """List of references to other component of this articles that this component supports."""
+    depend_on: List[ArticleRef]
+    """List of references to other component of this articles that this component depends on."""
+
+    writing_aim: List[str]
+    """List of writing aims of the research component in academic style."""
+    title: str
+    """Do not add any prefix or suffix to the title. should not contain special characters."""
+
+
+class ArticleOutlineBase(
+    ArticleMetaData,
+    UpdateFrom,
+    ResolveUpdateConflict,
+    ProposedAble,
+    PersistentAble,
+    ModelHash,
+    Introspect,
+):
+    """Base class for article outlines."""
+
+    @property
+    def metadata(self) -> ArticleMetaData:
+        """Returns the metadata of the article component."""
+        return ArticleMetaData.model_validate(self, from_attributes=True)
+
+    def update_metadata(self, other: ArticleMetaData) -> Self:
+        """Updates the metadata of the current instance with the attributes of another instance."""
+        self.support_to.clear()
+        self.support_to.extend(other.support_to)
+        self.depend_on.clear()
+        self.depend_on.extend(other.depend_on)
+        self.writing_aim.clear()
+        self.writing_aim.extend(other.writing_aim)
+        self.description = other.description
+        return self
+
+    def display_metadata(self) -> str:
+        """Displays the metadata of the current instance."""
+        return self.model_dump_json(
+            indent=1, include={"title", "writing_aim", "description", "support_to", "depend_on"}
+        )
+
+    def update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance."""
+        return self.update_metadata(other)
+
+    @abstractmethod
+    def to_typst_code(self) -> str:
+        """Converts the component into a Typst code snippet for rendering."""
+
+
+class SubSectionBase(ArticleOutlineBase):
+    """Base class for article sections and subsections."""
+
+    def to_typst_code(self) -> str:
+        """Converts the component into a Typst code snippet for rendering."""
+        return f"=== {self.title}\n"
+
+    def introspect(self) -> str:
+        """Introspects the article subsection outline."""
+        return ""
+
+    def resolve_update_conflict(self, other: Self) -> str:
+        """Resolve update errors in the article outline."""
+        if self.title != other.title:
+            return f"Title mismatched, expected `{self.title}`, got `{other.title}`"
+        return ""
+
+
+class SectionBase[T: SubSectionBase](ArticleOutlineBase):
+    """Base class for article sections and subsections."""
+
+    subsections: List[T]
+    """Subsections of the section. Contains at least one subsection. You can also add more as needed."""
+
+    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)
+
+    def resolve_update_conflict(self, other: Self) -> str:
+        """Resolve update errors in the article outline."""
+        out = ""
+        if self.title != other.title:
+            out += f"Title mismatched, expected `{self.title}`, got `{other.title}`"
+        if len(self.subsections) != len(other.subsections):
+            out += f"Section count mismatched, expected `{len(self.subsections)}`, got `{len(other.subsections)}`"
+        return out or "\n".join(
+            [
+                conf
+                for s, o in zip(self.subsections, other.subsections, strict=True)
+                if (conf := s.resolve_update_conflict(o))
+            ]
+        )
+
+    def update_from_inner(self, other: Self) -> Self:
+        """Updates the current instance with the attributes of another instance."""
+        super().update_from_inner(other)
+        if len(self.subsections) == 0:
+            self.subsections = other.subsections
+            return self
+
+        for self_subsec, other_subsec in zip(self.subsections, other.subsections, strict=True):
+            self_subsec.update_from(other_subsec)
+        return self
+
+    def introspect(self) -> str:
+        """Introspects the article section outline."""
+        if len(self.subsections) == 0:
+            return f"Section `{self.title}` contains no subsections, expected at least one, but got 0, you can add one or more as needed."
+        return ""
+
+
+class ChapterBase[T: SectionBase](ArticleOutlineBase):
+    """Base class for article chapters."""
+
+    sections: List[T]
+    """Sections of the chapter. Contains at least one section. You can also add more as needed."""
+
+    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)
+
+    def resolve_update_conflict(self, other: Self) -> str:
+        """Resolve update errors in the article outline."""
+        out = ""
+
+        if self.title != other.title:
+            out += f"Title mismatched, expected `{self.title}`, got `{other.title}`"
+        if len(self.sections) == len(other.sections):
+            out += f"Chapter count mismatched, expected `{len(self.sections)}`, got `{len(other.sections)}`"
+
+        return out or "\n".join(
+            [conf for s, o in zip(self.sections, other.sections, strict=True) if (conf := s.resolve_update_conflict(o))]
+        )
+
+    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 introspect(self) -> str:
+        """Introspects the article chapter outline."""
+        if len(self.sections) == 0:
+            return f"Chapter `{self.title}` contains no sections, expected at least one, but got 0, you can add one or more as needed."
+        return ""
+
+
+class ArticleBase[T: ChapterBase](FinalizedDumpAble):
+    """Base class for article outlines."""
+
+    language: str
+    """Written language of the article. SHALL be aligned to the language of the article proposal provided."""
+
+    title: str
+    """Title of the academic paper."""
+
+    prospect: str
+    """Consolidated research statement with four pillars:
+    1. Problem Identification: Current limitations
+    2. Methodological Response: Technical approach
+    3. Empirical Validation: Evaluation strategy
+    4. Scholarly Impact: Field contributions
+    """
+
+    abstract: str
+    """The abstract is a concise summary of the academic paper's main findings."""
+    chapters: List[T]
+    """Chapters of the article. Contains at least one chapter. You can also add more as needed."""
+
+    def iter_dfs_rev(
+        self,
+    ) -> Generator[ArticleOutlineBase, None, None]:
+        """Performs a depth-first search (DFS) through the article structure in reverse order.
+
+        Returns:
+            Generator[ArticleMainBase]: Each component in the article structure in reverse order.
+        """
+        for chap in self.chapters:
+            for sec in chap.sections:
+                yield from sec.subsections
+                yield sec
+            yield chap
+
+    def iter_dfs(self) -> Generator[ArticleOutlineBase, 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:
+            yield chap
+            for sec in chap.sections:
+                yield sec
+                yield from sec.subsections
+
+    def iter_sections(self) -> Generator[Tuple[ChapterBase, SectionBase], None, None]:
+        """Iterates through all sections in the article.
+
+        Returns:
+            Generator[ArticleOutlineBase]: Each section in the article.
+        """
+        for chap in self.chapters:
+            for sec in chap.sections:
+                yield chap, sec
+
+    def iter_subsections(self) -> Generator[Tuple[ChapterBase, SectionBase, SubSectionBase], None, None]:
+        """Iterates through all subsections in the article.
+
+        Returns:
+            Generator[ArticleOutlineBase]: Each subsection in the article.
+        """
+        for chap, sec in self.iter_sections():
+            for subsec in sec.subsections:
+                yield chap, sec, subsec
+
+    def find_introspected(self) -> Optional[Tuple[ArticleOutlineBase, str]]:
+        """Finds the first introspected component in the article structure."""
+        summary = ""
+        for component in self.iter_dfs_rev():
+            summary += component.introspect()
+            if summary:
+                return component, summary
+        return None
+
+    def find_illegal_ref(self) -> Optional[Tuple[ArticleOutlineBase, str]]:
+        """Finds the first illegal component in the outline.
+
+        Returns:
+            Tuple[ArticleOutlineBase, str]: A tuple containing the illegal component and an error message.
+        """
+        summary = ""
+        for component in self.iter_dfs_rev():
+            for ref in 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"
+            if summary:
+                return component, summary
+        return None
+
+    def finalized_dump(self) -> str:
+        """Generates standardized hierarchical markup for academic publishing systems.
+
+        Implements ACL 2024 outline conventions with four-level structure:
+        = Chapter Title (Level 1)
+        == Section Title (Level 2)
+        === Subsection Title (Level 3)
+        ==== Subsubsection Title (Level 4)
+
+        Returns:
+            str: Strictly formatted outline with academic sectioning
+
+        Example:
+            = Methodology
+            == Neural Architecture Search Framework
+            === Differentiable Search Space
+            ==== Constrained Optimization Parameters
+            === Implementation Details
+            == Evaluation Protocol
+        """
+        return "\n\n".join(a.to_typst_code() for a in self.chapters)