fabricatio 0.2.6.dev2__cp312-cp312-win_amd64.whl → 0.2.7.dev3__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_essence.py

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