fabricatio 0.2.8.dev4__cp312-cp312-win_amd64.whl → 0.2.9__cp312-cp312-win_amd64.whl

fabricatio/models/action.py

@@ -1,7 +1,12 @@
-"""Module that contains the classes for actions and workflows.
+"""Module that contains the classes for defining and executing task workflows.
 
-This module defines the Action and WorkFlow classes, which are used for
-creating and executing sequences of actions in a task-based context.
+This module provides the Action and WorkFlow classes for creating structured
+task execution pipelines. Actions represent atomic operations, while WorkFlows
+orchestrate sequences of actions with shared context and error handling.
+
+Classes:
+    Action: Base class for defining executable actions with context management.
+    WorkFlow: Manages action sequences, context propagation, and task lifecycle.
 """
 
 import traceback
@@ -15,6 +20,10 @@ from fabricatio.models.task import Task
 from fabricatio.models.usages import LLMUsage, ToolBoxUsage
 from pydantic import Field, PrivateAttr
 
+OUTPUT_KEY = "task_output"
+
+INPUT_KEY = "task_input"
+
 
 class Action(WithBriefing, LLMUsage):
     """Class that represents an action to be executed in a workflow.
@@ -46,28 +55,26 @@ class Action(WithBriefing, LLMUsage):
         self.description = self.description or self.__class__.__doc__ or ""
 
     @abstractmethod
-    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.
+    async def _execute(self, *_:Any, **cxt) -> Any:
+        """Implement the core logic of the action.
 
         Args:
-            **cxt: The context dictionary containing input and output data.
+            **cxt: Context dictionary containing input/output data.
 
         Returns:
-            Any: The result of the action execution.
+            Result of the action execution to be stored in context.
         """
         pass
 
     @final
     async def act(self, cxt: Dict[str, Any]) -> Dict[str, Any]:
-        """Perform the action and update the context with results.
+        """Execute action and update context.
 
         Args:
-            cxt: The context dictionary containing input and output data.
+            cxt (Dict[str, Any]): Shared context dictionary.
 
         Returns:
-            Dict[str, Any]: The updated context dictionary.
+            Updated context dictionary with new/modified entries.
         """
         ret = await self._execute(**cxt)
 
@@ -79,21 +86,30 @@ class Action(WithBriefing, LLMUsage):
 
     @property
     def briefing(self) -> str:
-        """Return a formatted description of the action including personality context if available.
+        """Generate formatted action description with personality context.
 
         Returns:
-            str: Formatted briefing text with personality and action description.
+            Briefing text combining 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}"
 
+    def to_task_output(self)->Self:
+        """Set the output key to OUTPUT_KEY and return the action instance."""
+        self.output_key=OUTPUT_KEY
+        return self
 
 class WorkFlow(WithBriefing, ToolBoxUsage):
-    """Class that represents a sequence of actions to be executed for a task.
+    """Manages sequences of actions to fulfill tasks.
 
-    A workflow manages the execution of multiple actions in sequence, passing
-    a shared context between them and handling task lifecycle events.
+    Handles context propagation between actions, error handling, and task lifecycle
+    events like cancellation and completion.
+
+    Attributes:
+        steps (Tuple): Sequence of Action instances or classes to execute.
+        task_input_key (str): Key for storing task instance in context.
+        task_output_key (str): Key to retrieve final result from context.
     """
 
     description: str = ""
@@ -110,10 +126,10 @@ class WorkFlow(WithBriefing, ToolBoxUsage):
     )
     """The sequence of actions to be executed, can be action classes or instances."""
 
-    task_input_key: str = Field(default="task_input")
+    task_input_key: str = Field(default=INPUT_KEY)
     """Key used to store the input task in the context dictionary."""
 
-    task_output_key: str = Field(default="task_output")
+    task_output_key: str = Field(default=OUTPUT_KEY)
     """Key used to extract the final result from the context dictionary."""
 
     extra_init_context: Dict[str, Any] = Field(default_factory=dict, frozen=True)
@@ -129,26 +145,29 @@ class WorkFlow(WithBriefing, ToolBoxUsage):
         self._instances = tuple(step if isinstance(step, Action) else step() for step in self.steps)
 
     def inject_personality(self, personality: str) -> Self:
-        """Set the personality for all actions that don't have one defined.
+        """Set personality for actions without existing personality.
 
         Args:
-            personality: The personality text to inject.
+            personality (str): Shared personality context
 
         Returns:
-            Self: The workflow instance for method chaining.
+            Workflow instance with updated actions
         """
         for action in filter(lambda a: not a.personality, self._instances):
             action.personality = personality
         return self
 
     async def serve(self, task: Task) -> None:
-        """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.
+        """Execute workflow to complete given task.
 
         Args:
-            task: The task to be processed.
+            task (Task): Task instance to be processed.
+
+        Steps:
+            1. Initialize context with task instance and extra data
+            2. Execute each action sequentially
+            3. Handle task cancellation and exceptions
+            4. Extract final result from context
         """
         logger.info(f"Start execute workflow: {self.name}")
 
@@ -158,27 +177,27 @@ class WorkFlow(WithBriefing, ToolBoxUsage):
         current_action = None
         try:
             # Process each action in sequence
-            for step in self._instances:
+            for i,step in enumerate(self._instances):
                 current_action = step.name
-                logger.info(f"Executing step >> {current_action}")
+                logger.info(f"Executing step [{i}] >> {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():
-                    logger.warning(f"Task cancelled by task: {task.name}")
+                    logger.warning(f"Workflow cancelled by task: {task.name}")
                     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}")
+                logger.success(f"Step [{i}] `{current_action}` execution finished.")
                 if step.output_key:
-                    logger.success(f"Setting output to `{step.output_key}`")
+                    logger.success(f"Setting action `{current_action}` output to `{step.output_key}`")
                 await self._context.put(modified_ctx)
 
-            logger.success(f"Workflow execution finished: {self.name}")
+            logger.success(f"Workflow `{self.name}` execution finished.")
 
             # Get final context and extract result
             final_ctx = await self._context.get()
@@ -198,10 +217,14 @@ class WorkFlow(WithBriefing, ToolBoxUsage):
             await task.fail()
 
     async def _init_context[T](self, task: Task[T]) -> None:
-        """Initialize the context dictionary for workflow execution.
+        """Initialize workflow execution context.
 
         Args:
-            task: The task being served by this workflow.
+            task (Task[T]): Task being processed
+
+        Context includes:
+            - Task instance stored under task_input_key
+            - Any extra_init_context values
         """
         logger.debug(f"Initializing context for workflow: {self.name}")
         initial_context = {self.task_input_key: task, **dict(self.extra_init_context)}
@@ -222,7 +245,7 @@ class WorkFlow(WithBriefing, ToolBoxUsage):
         Returns:
             Self: The workflow instance for method chaining.
         """
-        self.provide_tools_to(self._instances)
+        self.provide_tools_to(i for i in self._instances if isinstance(i,ToolBoxUsage))
         return self
 
     def update_init_context(self, /, **kwargs) -> Self:

fabricatio/models/extra/__init__.py

@@ -0,0 +1 @@
+"""A module contains extra models for fabricatio."""

fabricatio/models/extra/advanced_judge.py

@@ -2,17 +2,17 @@
 
 from typing import List
 
-from fabricatio.models.generic import Display, ProposedAble
+from fabricatio.models.generic import SketchedAble
 
 
-class JudgeMent(ProposedAble, Display):
+class JudgeMent(SketchedAble):
     """Represents a judgment result containing supporting/denying evidence and final verdict.
 
     The class stores both affirmative and denies evidence, truth and reasons lists along with the final boolean judgment.
     """
 
     issue_to_judge: str
-    """The issue to be judged"""
+    """The issue to be judged, including the original question and context"""
 
     deny_evidence: List[str]
     """List of clues supporting the denial."""
@@ -21,7 +21,7 @@ class JudgeMent(ProposedAble, Display):
     """List of clues supporting the affirmation."""
 
     final_judgement: bool
-    """The final judgment made according to all extracted clues."""
+    """The final judgment made according to all extracted clues. true for the `issue_to_judge` is correct and false for incorrect."""
 
     def __bool__(self) -> bool:
         """Return the final judgment value.

fabricatio/models/extra/article_base.py

@@ -7,16 +7,20 @@ from typing import Generator, List, Optional, Self, Tuple, overload
 
 from fabricatio.models.generic import (
     AsPrompt,
-    CensoredAble,
-    Display,
+    Described,
     FinalizedDumpAble,
     Introspect,
+    Language,
     ModelHash,
     PersistentAble,
     ProposedUpdateAble,
     ResolveUpdateConflict,
     SequencePatch,
+    SketchedAble,
+    Titled,
+    WordCount,
 )
+from pydantic import Field
 
 
 class ReferringType(StrEnum):
@@ -30,51 +34,51 @@ class ReferringType(StrEnum):
 type RefKey = Tuple[str, Optional[str], Optional[str]]
 
 
-class ArticleRef(CensoredAble, ProposedUpdateAble):
+class ArticleRef(ProposedUpdateAble):
     """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")
+            ArticleRef(chap="Introduction")
             ```
             Using JSON
             ```json
-            {referred_chapter_title="Introduction"}
+            {chap="Introduction"}
             ```
         - Referring to a section titled `Background` under the `Introduction` chapter:
             Using Python
             ```python
-            ArticleRef(referred_chapter_title="Introduction", referred_section_title="Background")
+            ArticleRef(chap="Introduction", sec="Background")
             ```
             Using JSON
             ```json
-            {referred_chapter_title="Introduction", referred_section_title="Background"}
+            {chap="Introduction", sec="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")
+            ArticleRef(chap="Introduction", sec="Background", subsec="Related Work")
             ```
             Using JSON
             ```json
-            {referred_chapter_title="Introduction", referred_section_title="Background", referred_subsection_title="Related Work"}
+            {chap="Introduction", sec="Background", subsec="Related Work"}
             ```
     """
 
-    referred_chapter_title: str
+    chap: str
     """`title` Field of the referenced chapter"""
-    referred_section_title: Optional[str] = None
+    sec: Optional[str] = None
     """`title` Field of the referenced section."""
-    referred_subsection_title: Optional[str] = None
+    subsec: Optional[str] = None
     """`title` Field of the referenced subsection."""
 
     def update_from_inner(self, other: Self) -> Self:
         """Updates the current instance with the attributes of another instance."""
-        self.referred_chapter_title = other.referred_chapter_title
-        self.referred_section_title = other.referred_section_title
-        self.referred_subsection_title = other.referred_subsection_title
+        self.chap = other.chap
+        self.sec = other.sec
+        self.subsec = other.subsec
         return self
 
     def deref(self, article: "ArticleBase") -> Optional["ArticleOutlineBase"]:
@@ -86,39 +90,41 @@ class ArticleRef(CensoredAble, ProposedUpdateAble):
         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:
+        chap = next((chap for chap in article.chapters if chap.title == self.chap), None)
+        if self.sec 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:
+        sec = next((sec for sec in chap.sections if sec.title == self.sec), None)
+        if self.subsec is None or sec is None:
             return sec
-        return next((subsec for subsec in sec.subsections if subsec.title == self.referred_subsection_title), None)
+        return next((subsec for subsec in sec.subsections if subsec.title == self.subsec), 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:
+        if self.subsec is not None:
             return ReferringType.SUBSECTION
-        if self.referred_section_title is not None:
+        if self.sec is not None:
             return ReferringType.SECTION
         return ReferringType.CHAPTER
 
 
-class ArticleMetaData(CensoredAble, Display):
+class ArticleMetaData(SketchedAble, Described, WordCount, Titled, Language):
     """Metadata for an article component."""
 
-    description: str
-    """Description of the research component in academic style."""
+    description: str = Field(
+        alias="elaboration",
+        description=Described.model_fields["description"].description,
+    )
 
-    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."""
+    title: str = Field(alias="heading", description=Titled.model_fields["title"].description)
 
-    writing_aim: List[str]
+    aims: 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."""
+
+    support_to: List[ArticleRef]
+    """List of references to other future components in this article that this component supports to."""
+    depend_on: List[ArticleRef]
+    """List of references to other previous components in this article that this component depends on."""
 
 
 class ArticleRefSequencePatch(SequencePatch[ArticleRef]):
@@ -146,8 +152,8 @@ class ArticleOutlineBase(
         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.aims.clear()
+        self.aims.extend(other.aims)
         self.description = other.description
         return self
 
@@ -271,25 +277,19 @@ class ChapterBase[T: SectionBase](ArticleOutlineBase):
         return ""
 
 
-class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, ABC):
+class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, WordCount, Described, Titled, Language, ABC):
     """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 = Field(alias="heading", description=Titled.model_fields["title"].description)
+    description: str = Field(alias="abstract")
+    """The abstract serves as a concise summary of an academic article, encapsulating its core purpose, methodologies, key results,
+    and conclusions while enabling readers to rapidly assess the relevance and significance of the study.
+    Functioning as the article's distilled essence, it succinctly articulates the research problem, objectives,
+    and scope, providing a roadmap for the full text while also facilitating database indexing, literature reviews,
+    and citation tracking through standardized metadata. Additionally, it acts as an accessibility gateway,
+    allowing scholars to gauge the study's contribution to existing knowledge, its methodological rigor,
+    and its broader implications without engaging with the entire manuscript, thereby optimizing scholarly communication efficiency."""
 
-    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."""
 
@@ -376,34 +376,97 @@ class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, ABC):
                 return component, summary
         return None
 
-    @overload
-    def find_illegal_ref(self, gather_identical: bool) -> Optional[Tuple[ArticleRef | List[ArticleRef], str]]: ...
+    def gather_introspected(self) -> Optional[str]:
+        """Gathers all introspected components in the article structure."""
+        return "\n".join([i for component in self.chapters if (i := component.introspect())])
+
+
+    def iter_chap_title(self) -> Generator[str, None, None]:
+        """Iterates through all chapter titles in the article."""
+        for chap in self.chapters:
+            yield chap.title
+
+    def iter_section_title(self) -> Generator[str, None, None]:
+        """Iterates through all section titles in the article."""
+        for _, sec in self.iter_sections():
+            yield sec.title
+
+    def iter_subsection_title(self) -> Generator[str, None, None]:
+        """Iterates through all subsection titles in the article."""
+        for _, _, subsec in self.iter_subsections():
+            yield subsec.title
 
     @overload
-    def find_illegal_ref(self) -> Optional[Tuple[ArticleRef, str]]: ...
+    def find_illegal_ref(self, gather_identical: bool) -> Optional[Tuple[ArticleOutlineBase,ArticleRef | List[ArticleRef], str]]: ...
 
-    def find_illegal_ref(self, gather_identical: bool = False) -> Optional[Tuple[ArticleRef | List[ArticleRef], str]]:
+    @overload
+    def find_illegal_ref(self) -> Optional[Tuple[ArticleOutlineBase,ArticleRef, str]]: ...
+    def find_illegal_ref(
+        self, gather_identical: bool = False
+    ) -> Optional[Tuple[ArticleOutlineBase, ArticleRef | List[ArticleRef], str]]:
         """Finds the first illegal component in the outline.
 
         Returns:
             Tuple[ArticleOutlineBase, str]: A tuple containing the illegal component and an error message.
         """
         summary = ""
+        chap_titles_set = set(self.iter_chap_title())
+        sec_titles_set = set(self.iter_section_title())
+        subsec_titles_set = set(self.iter_subsection_title())
+
         for component in self.iter_dfs_rev():
             for ref in chain(component.depend_on, component.support_to):
                 if not ref.deref(self):
                     summary += f"Invalid internal reference in `{component.__class__.__name__}` titled `{component.title}`, because the referred {ref.referring_type} is not exists within the article, see the original obj dump: {ref.model_dump()}\n"
-                if summary and not gather_identical:
-                    return ref, summary
+
+                    if ref.chap not in (chap_titles_set):
+                        summary += f"Chapter titled `{ref.chap}` is not any of {chap_titles_set}\n"
+                    if ref.sec and ref.sec not in (sec_titles_set):
+                        summary += f"Section Titled `{ref.sec}` is not any of {sec_titles_set}\n"
+                    if ref.subsec and ref.subsec not in (subsec_titles_set):
+                        summary += f"Subsection Titled `{ref.subsec}` is not any of {subsec_titles_set}"
+
                 if summary and gather_identical:
-                    return [
-                        identical_ref
-                        for identical_ref in chain(self.iter_depend_on(), self.iter_support_on())
-                        if identical_ref == ref
-                    ], summary
+                    return (
+                        component,
+                        [
+                            identical_ref
+                            for identical_ref in chain(self.iter_depend_on(), self.iter_support_on())
+                            if identical_ref == ref
+                        ],
+                        summary,
+                    )
+                if summary:
+                    return component, ref, summary
 
         return None
 
+    def gather_illegal_ref(self) -> Tuple[List[ArticleRef], str]:
+        """Gathers all illegal references in the article."""
+        summary = []
+        chap_titles_set = set(self.iter_chap_title())
+        sec_titles_set = set(self.iter_section_title())
+        subsec_titles_set = set(self.iter_subsection_title())
+        res_seq = []
+
+        for component in self.iter_dfs():
+            for ref in (
+                r for r in chain(component.depend_on, component.support_to) if not r.deref(self) and r not in res_seq
+            ):
+                res_seq.append(ref)
+                if ref.chap not in chap_titles_set:
+                    summary.append(
+                        f"Chapter titled `{ref.chap}` is not exist, since it is not any of {chap_titles_set}."
+                    )
+                if ref.sec and (ref.sec not in sec_titles_set):
+                    summary.append(f"Section Titled `{ref.sec}` is not exist, since it is not any of {sec_titles_set}")
+                if ref.subsec and (ref.subsec not in subsec_titles_set):
+                    summary.append(
+                        f"Subsection Titled `{ref.subsec}` is not exist, since it is not any of {subsec_titles_set}"
+                    )
+
+        return res_seq, "\n".join(summary)
+
     def finalized_dump(self) -> str:
         """Generates standardized hierarchical markup for academic publishing systems.