fabricatio 0.2.9.dev1__tar.gz → 0.2.9.dev2__tar.gz

{fabricatio-0.2.9.dev1 → fabricatio-0.2.9.dev2}/PKG-INFO

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

{fabricatio-0.2.9.dev1 → fabricatio-0.2.9.dev2}/examples/rules/draft_ruleset.py

@@ -24,10 +24,10 @@ async def main() -> None:
         registry={
             Event.quick_instantiate(ns := "article"): WorkFlow(
                 name="write ruleset",
-                description="Generate an outline for an article. dump the outline to the given path. in typst format.",
+                description="Generate a draft ruleset for article.",
                 steps=(
                     DraftRuleSet(
-                        ruleset_requirement="1.when try to use an article as reference cited in our article, you should obey the format like (author1, author2 et al., YYYY)\n"
+                        ruleset_requirement="1.when try to use an article as reference cited in our article, you should obey the format like `(author1, author2 et al., YYYY)#cite(<bibtex_cite_key>)`\n"
                         "2.we use typst to generate numeric citation. For example, for an article whose `bibtex_key` is `YanWindEnergy2018`, you can create a numeric citation by typing `#cite(<YanWindEnergy2018>)`(note that `bibtex_key` with `<` and `>` wrapped is needed), those notations could automatically be processed and output by compiler as a numeric citation like `[1]` in the upper right corner of text.\n"
                         "3.in addition, since `#cite()` can ONLY cite ONE article at once, we need use multiple `#cite()` notations to cite multiple articles, for example, there are three articles whose `bibtex_key` are `YanWindEnergy2018`, `YanWindEnergy2019`, `YanWindEnergy2020, you can cite them three as numeric citation by typing `#cite(<YanWindEnergy2018>)#cite(<YanWindEnergy2019>)#cite(<YanWindEnergy2020>)` those notations could automatically be processed and output by compiler as a numeric citation like `[1,2,3]` in the upper right corner of text.\n"
                         "4.to cover more references, we usually cite more than one articles that have similar opinions in a single sentence if possible.\n"
@@ -36,11 +36,11 @@ async def main() -> None:
                         output_key="en_ruleset"
                     ),
                     DraftRuleSet(
-                        ruleset_requirement="1. 当在文章中引用其他文章作为参考文献时，应遵循（作者1，作者2等，年份）的格式进行标注。\n"
-                        "2. 我们使用Typst生成数字引用格式。例如，对于BibTeX键为`YanWindEnergy2018`的文献，可通过输入`#cite(<YanWindEnergy2018>)`创建数字引用（注意：BibTeX键必须用尖括号`<`和`>`包裹）。这些标记会被编译器自动处理并输出为右上角的数字引用格式，例如文本旁的[1]。\n"
-                        "3. 此外，由于`#cite()`每次只能引用单一文献，需通过叠加多个`#cite()`标记实现多文献引用。例如，若需引用三个BibTeX键分别为`YanWindEnergy2018`、`YanWindEnergy2019`和`YanWindEnergy2020`的文献，应输入`#cite(<YanWindEnergy2018>)#cite(<YanWindEnergy2019>)#cite(<YanWindEnergy2020>)`，编译后将呈现为[1,2,3]的右上角数字引用格式。\n"
-                        "4. 为增加参考文献的覆盖率，我们通常建议在可能的情况下，将多个观点相似的文献合并引用于同一句子中。"
-                        "5. 使用`#cite()`时需注意：BibTeX键必须用尖括号`<`和`>`包裹，否则编译器将拒绝通过编译。",
+                        ruleset_requirement="1. 当在文章中引用其他文章作为参考文献时, 应遵循`(作者1, 作者2等, 年份)#cite(<bibtex_cite_key>)`的格式进行标注。\n"
+                        "2. 我们使用Typst生成数字引用格式。例如, 对于BibTeX键为`YanWindEnergy2018`的文献, 可通过输入`#cite(<YanWindEnergy2018>)`创建数字引用(注意:BibTeX键必须用尖括号`<`和`>`包裹)。这些标记会被编译器自动处理并输出为右上角的数字引用格式, 例如文本旁的[1]。\n"
+                        "3. 此外, 由于`#cite()`每次只能引用单一文献, 需通过叠加多个`#cite()`标记实现多文献引用。例如, 若需引用三个BibTeX键分别为`YanWindEnergy2018`、`YanWindEnergy2019`和`YanWindEnergy2020`的文献, 应输入`#cite(<YanWindEnergy2018>)#cite(<YanWindEnergy2019>)#cite(<YanWindEnergy2020>)`, 编译后将呈现为[1,2,3]的右上角数字引用格式。\n"
+                        "4. 为增加参考文献的覆盖率, 我们通常建议在可能的情况下, 将多个观点相似的文献合并引用于同一句子中。"
+                        "5. 使用`#cite()`时需注意:BibTeX键必须用尖括号`<`和`>`包裹, 否则编译器将拒绝通过编译。",
                         rule_count=5,
                         output_key="zh_ruleset"
                     ),

{fabricatio-0.2.9.dev1 → fabricatio-0.2.9.dev2}/examples/write_article/.gitignore

@@ -1,3 +1,3 @@
 article_briefing.txt
 out.typ
-persistent
+persistent*

{fabricatio-0.2.9.dev1 → fabricatio-0.2.9.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fabricatio"
-version = "0.2.9-dev1"
+version = "0.2.9-dev2"
 description = "A LLM multi-agent framework."
 readme = "README.md"
 license = { file = "LICENSE" }

{fabricatio-0.2.9.dev1 → fabricatio-0.2.9.dev2}/python/fabricatio/actions/output.py

@@ -1,7 +1,7 @@
 """Dump the finalized output to a file."""
 
 from pathlib import Path
-from typing import Iterable, List, Optional, Type
+from typing import Any, Iterable, List, Optional, Type
 
 from fabricatio.journal import logger
 from fabricatio.models.action import Action
@@ -33,6 +33,7 @@ class DumpFinalizedOutput(Action):
                 "Could not find the path of file to dump the data.",
             )
         )
+        logger.info(f"Saving output to {dump_path.as_posix()}")
         ok(to_dump, "Could not dump the data since the path is not specified.").finalized_dump_to(dump_path)
         return dump_path.as_posix()
 
@@ -41,7 +42,11 @@ class PersistentAll(Action):
     """Persist all the data to a file."""
 
     output_key: str = "persistent_count"
+    """The number of objects persisted."""
     persist_dir: Optional[str] = None
+    """The directory to persist the data."""
+    override: bool = False
+    """Whether to remove the existing dir before dumping."""
 
     async def _execute(
         self,
@@ -64,16 +69,22 @@ class PersistentAll(Action):
         if persist_dir.is_file():
             logger.warning("Dump should be a directory, but it is a file. Skip dumping.")
             return count
-
+        if self.override and persist_dir.is_dir():
+            logger.info(f"Override the existing directory {persist_dir.as_posix()}.")
+            persist_dir.rmdir()
+        logger.info(f"Starting persistence in directory {persist_dir}")
         for k, v in cxt.items():
             final_dir = persist_dir.joinpath(k)
+            logger.debug(f"Checking key {k} for persistence")
             if isinstance(v, PersistentAble):
+                logger.info(f"Persisting object {k} to {final_dir}")
                 final_dir.mkdir(parents=True, exist_ok=True)
                 v.persist(final_dir)
                 count += 1
             if isinstance(v, Iterable) and any(
                 persistent_ables := (pers for pers in v if isinstance(pers, PersistentAble))
             ):
+                logger.info(f"Persisting collection {k} to {final_dir}")
                 final_dir.mkdir(parents=True, exist_ok=True)
                 for per in persistent_ables:
                     per.persist(final_dir)
@@ -93,10 +104,39 @@ class RetrieveFromPersistent[T: PersistentAble](Action):
     """The class of the object to retrieve."""
 
     async def _execute(self, /, **__) -> Optional[T | List[T]]:
-        logger.info(f"Retrieve `{self.retrieve_cls.__name__}` from persistent file: {self.load_path}")
+        logger.info(f"Retrieve `{self.retrieve_cls.__name__}` from {self.load_path}")
         if not (p := Path(self.load_path)).exists():
+            logger.warning(f"Path {self.load_path} does not exist")
             return None
 
         if p.is_dir():
+            logger.info(f"Found directory with {len(list(p.glob('*')))} items")
             return [self.retrieve_cls.from_persistent(per) for per in p.glob("*")]
         return self.retrieve_cls.from_persistent(self.load_path)
+
+
+class GatherAsList(Action):
+    """Gather the objects from the context as a list.
+
+    Notes:
+        If both `gather_suffix` and `gather_prefix` are specified, only the objects with the suffix will be gathered.
+    """
+    output_key: str = "gathered"
+    """Gather the objects from the context as a list."""
+    gather_suffix: Optional[str] = None
+    """Gather the objects from the context as a list."""
+    gather_prefix: Optional[str] = None
+    """Gather the objects from the context as a list."""
+
+    async def _execute(self, **cxt) -> List[Any]:
+
+        if self.gather_suffix is not None:
+            result = [cxt[k] for k in cxt if k.endswith(self.gather_suffix)]
+            logger.debug(f"Gathered {len(result)} items with suffix {self.gather_suffix}")
+            return result
+        if  self.gather_prefix is None:
+            logger.error(err:="Either `gather_suffix` or `gather_prefix` must be specified.")
+            raise ValueError(err)
+        result = [cxt[k] for k in cxt if k.startswith(self.gather_prefix)]
+        logger.debug(f"Gathered {len(result)} items with prefix {self.gather_prefix}")
+        return result

{fabricatio-0.2.9.dev1 → fabricatio-0.2.9.dev2}/python/fabricatio/capabilities/censor.py

@@ -20,8 +20,6 @@ class Censor(Correct, Check):
     Inherits from both Correct and Check classes.
     Provides methods to censor objects and strings by first checking them against a ruleset and then correcting them if necessary.
 
-    Attributes:
-        ruleset (RuleSet): The ruleset to be used for censoring.
     """
 
     async def censor_obj[M: SketchedAble](
@@ -42,7 +40,7 @@ class Censor(Correct, Check):
         """
         imp = await self.check_obj(obj, ruleset, **override_kwargs(kwargs, default=None))
         if imp is None:
-            return imp
+            return None
         return await self.correct_obj(obj, imp, **kwargs)
 
     async def censor_string(

{fabricatio-0.2.9.dev1 → fabricatio-0.2.9.dev2}/python/fabricatio/capabilities/check.py

@@ -11,6 +11,7 @@ from fabricatio.models.extra.problem import Improvement
 from fabricatio.models.extra.rule import Rule, RuleSet
 from fabricatio.models.generic import Display, WithBriefing
 from fabricatio.models.kwargs_types import ValidateKwargs
+from fabricatio.rust import detect_language
 from fabricatio.utils import override_kwargs
 
 
@@ -56,9 +57,7 @@ class Check(AdvancedJudge, Propose):
 
         ruleset_patch = await self.propose(
             RuleSetBriefingPatch,
-            f"# Rules Requirements\n{rule_reqs}\n# Generated Rules\n{Display.seq_display(rules)}\n\n"
-            f"You need to write a concise and detailed patch for this ruleset that can be applied to the ruleset nicely.\n"
-            f"Note that all fields in this patch will be directly copied to the ruleset obj, including `name` and `description`, so write when knowing the subject.\n",
+            f"{ruleset_requirement}\n\nYou should use `{detect_language(ruleset_requirement)}`!",
             **override_kwargs(kwargs, default=None),
         )
 
@@ -98,7 +97,7 @@ class Check(AdvancedJudge, Propose):
                 Improvement,
                 TEMPLATE_MANAGER.render_template(
                     configs.templates.check_string_template,
-                    {"to_check": input_text, "rule": rule, "judge": judge.display(), "reference": reference},
+                    {"to_check": input_text, "rule": rule.display(), "judge": judge.display(), "reference": reference},
                 ),
                 **kwargs,
             )

{fabricatio-0.2.9.dev1 → fabricatio-0.2.9.dev2}/python/fabricatio/capabilities/correct.py

@@ -78,11 +78,11 @@ class Correct(Rating, Propose):
             TEMPLATE_MANAGER.render_template(
                 configs.templates.fix_troubled_obj_template,
                 {
-                    "problem": problem_solutions.problem,
+                    "problem": problem_solutions.problem.display(),
                     "solution": ok(
                         problem_solutions.final_solution(),
                         f"No solution found for problem: {problem_solutions.problem}",
-                    ),
+                    ).display(),
                     "reference": reference,
                 },
             ),
@@ -111,11 +111,11 @@ class Correct(Rating, Propose):
             TEMPLATE_MANAGER.render_template(
                 configs.templates.fix_troubled_string_template,
                 {
-                    "problem": problem_solutions.problem,
+                    "problem": problem_solutions.problem.display(),
                     "solution": ok(
                         problem_solutions.final_solution(),
                         f"No solution found for problem: {problem_solutions.problem}",
-                    ),
+                    ).display(),
                     "reference": reference,
                     "string_to_fix": input_text,
                 },

{fabricatio-0.2.9.dev1 → fabricatio-0.2.9.dev2}/python/fabricatio/config.py

@@ -303,7 +303,7 @@ class CacheConfig(BaseModel):
 
     model_config = ConfigDict(use_attribute_docstrings=True)
 
-    type: Optional[LiteLLMCacheType] = None
+    type: LiteLLMCacheType = LiteLLMCacheType.LOCAL
     """The type of cache to use. If None, the default cache type will be used."""
     params: CacheKwargs = Field(default_factory=CacheKwargs)
     """The parameters for the cache. If type is None, the default parameters will be used."""

{fabricatio-0.2.9.dev1 → fabricatio-0.2.9.dev2}/python/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
@@ -50,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)
 
@@ -83,10 +86,10 @@ 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}"
@@ -98,10 +101,15 @@ class Action(WithBriefing, LLMUsage):
         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 = ""
@@ -137,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}")
 
@@ -206,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)}
@@ -230,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-0.2.9.dev1 → fabricatio-0.2.9.dev2}/python/fabricatio/models/extra/article_base.py

@@ -7,8 +7,6 @@ from typing import Generator, List, Optional, Self, Tuple, overload
 
 from fabricatio.models.generic import (
     AsPrompt,
-    CensoredAble,
-    Display,
     FinalizedDumpAble,
     Introspect,
     ModelHash,
@@ -16,6 +14,7 @@ from fabricatio.models.generic import (
     ProposedUpdateAble,
     ResolveUpdateConflict,
     SequencePatch,
+    SketchedAble,
 )
 
 
@@ -30,7 +29,7 @@ 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:
@@ -104,7 +103,7 @@ class ArticleRef(CensoredAble, ProposedUpdateAble):
         return ReferringType.CHAPTER
 
 
-class ArticleMetaData(CensoredAble, Display):
+class ArticleMetaData(SketchedAble):
     """Metadata for an article component."""
 
     description: str
@@ -120,6 +119,9 @@ class ArticleMetaData(CensoredAble, Display):
     title: str
     """Do not add any prefix or suffix to the title. should not contain special characters."""
 
+    expected_word_count: int
+    """Expected word count of this research component."""
+
 
 class ArticleRefSequencePatch(SequencePatch[ArticleRef]):
     """Patch for article refs."""

{fabricatio-0.2.9.dev1 → fabricatio-0.2.9.dev2}/python/fabricatio/models/extra/article_main.py

@@ -14,11 +14,11 @@ from fabricatio.models.extra.article_base import (
 from fabricatio.models.extra.article_outline import (
     ArticleOutline,
 )
-from fabricatio.models.generic import CensoredAble, Display, PersistentAble, SequencePatch, WithRef
+from fabricatio.models.generic import PersistentAble, SequencePatch, SketchedAble, WithRef
 from fabricatio.utils import ok
 
 
-class Paragraph(CensoredAble):
+class Paragraph(SketchedAble):
     """Structured academic paragraph blueprint for controlled content generation."""
 
     description: str
@@ -73,8 +73,7 @@ class ArticleChapter(ChapterBase[ArticleSection]):
 
 
 class Article(
-    Display,
-    CensoredAble,
+    SketchedAble,
     WithRef[ArticleOutline],
     PersistentAble,
     ArticleBase[ArticleChapter],

{fabricatio-0.2.9.dev1 → fabricatio-0.2.9.dev2}/python/fabricatio/models/extra/article_outline.py

@@ -9,7 +9,7 @@ from fabricatio.models.extra.article_base import (
     SubSectionBase,
 )
 from fabricatio.models.extra.article_proposal import ArticleProposal
-from fabricatio.models.generic import CensoredAble, Display, PersistentAble, WithRef
+from fabricatio.models.generic import PersistentAble, SketchedAble, WithRef
 
 
 class ArticleSubsectionOutline(SubSectionBase):
@@ -25,8 +25,7 @@ class ArticleChapterOutline(ChapterBase[ArticleSectionOutline]):
 
 
 class ArticleOutline(
-    Display,
-    CensoredAble,
+    SketchedAble,
     WithRef[ArticleProposal],
     PersistentAble,
     ArticleBase[ArticleChapterOutline],

{fabricatio-0.2.9.dev1 → fabricatio-0.2.9.dev2}/python/fabricatio/models/extra/article_proposal.py

@@ -2,10 +2,10 @@
 
 from typing import Dict, List
 
-from fabricatio.models.generic import AsPrompt, CensoredAble, Display, PersistentAble, WithRef
+from fabricatio.models.generic import AsPrompt, SketchedAble, PersistentAble, WithRef
 
 
-class ArticleProposal(CensoredAble, Display, WithRef[str], AsPrompt, PersistentAble):
+class ArticleProposal(SketchedAble, 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.
@@ -41,8 +41,8 @@ class ArticleProposal(CensoredAble, Display, WithRef[str], AsPrompt, PersistentA
     abstract: str
     """A concise summary of the research proposal, outlining the main points and objectives."""
 
-    min_word_count: int
-    """The minimum number of words required for the research proposal."""
+    expected_word_count: int
+    """The estimated word count of the final academic paper."""
 
     def _as_prompt_inner(self) -> Dict[str, str]:
         return {