fabricatio 0.2.9.dev1__cp312-cp312-win_amd64.whl → 0.2.9.dev3__cp312-cp312-win_amd64.whl

fabricatio/capabilities/check.py

@@ -1,16 +1,19 @@
 """A class that provides the capability to check strings and objects against rules and guidelines."""
 
-from typing import Optional, Unpack
+from asyncio import gather
+from typing import List, Optional, Unpack
 
 from fabricatio import TEMPLATE_MANAGER
 from fabricatio.capabilities.advanced_judge import AdvancedJudge
 from fabricatio.capabilities.propose import Propose
 from fabricatio.config import configs
+from fabricatio.journal import logger
 from fabricatio.models.extra.patches import RuleSetBriefingPatch
 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
 
 
@@ -50,15 +53,20 @@ class Check(AdvancedJudge, Propose):
         if rule_reqs is None:
             return None
 
-        rules = await self.propose(Rule, [TEMPLATE_MANAGER.render_template(configs.templates.rule_requirement_template, {"rule_requirement": r}) for r in rule_reqs], **kwargs)
+        rules = await self.propose(
+            Rule,
+            [
+                TEMPLATE_MANAGER.render_template(configs.templates.rule_requirement_template, {"rule_requirement": r})
+                for r in rule_reqs
+            ],
+            **kwargs,
+        )
         if any(r for r in rules if r is None):
             return None
 
         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),
         )
 
@@ -94,11 +102,12 @@ class Check(AdvancedJudge, Propose):
             f"# Content to exam\n{input_text}\n\n# Rule Must to follow\n{rule.display()}\nDoes `Content to exam` provided above violate the `Rule Must to follow` provided above?",
             **override_kwargs(kwargs, default=None),
         ):
+            logger.info(f"Rule `{rule.name}` violated: \n{judge.display()}")
             return await self.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,
             )
@@ -142,7 +151,7 @@ class Check(AdvancedJudge, Propose):
         ruleset: RuleSet,
         reference: str = "",
         **kwargs: Unpack[ValidateKwargs[Improvement]],
-    ) -> Optional[Improvement]:
+    ) -> Optional[List[Improvement]]:
         """Validate text against full ruleset.
 
         Args:
@@ -159,12 +168,13 @@ class Check(AdvancedJudge, Propose):
             - Halts validation after first successful improvement proposal
             - Maintains rule execution order from ruleset.rules list
         """
-        imp_seq = [
-            await self.check_string_against_rule(input_text, rule, reference, **kwargs) for rule in ruleset.rules
-        ]
-        if all(isinstance(i, Improvement) for i in imp_seq):
-            return Improvement.gather(*imp_seq)  # pyright: ignore [reportArgumentType]
-        return None
+        imp_seq = await gather(
+            *[self.check_string_against_rule(input_text, rule, reference, **kwargs) for rule in ruleset.rules]
+        )
+        if imp_seq is None:
+            logger.warning(f"Generation failed for string check against `{ruleset.name}`")
+            return None
+        return [imp for imp in imp_seq if imp]
 
     async def check_obj[M: (Display, WithBriefing)](
         self,
@@ -172,7 +182,7 @@ class Check(AdvancedJudge, Propose):
         ruleset: RuleSet,
         reference: str = "",
         **kwargs: Unpack[ValidateKwargs[Improvement]],
-    ) -> Optional[Improvement]:
+    ) -> Optional[List[Improvement]]:
         """Validate object against full ruleset.
 
         Args:
@@ -189,7 +199,9 @@ class Check(AdvancedJudge, Propose):
             - Maintains same early termination behavior as check_string
             - Validates object through text conversion mechanism
         """
-        imp_seq = [await self.check_obj_against_rule(obj, rule, reference, **kwargs) for rule in ruleset.rules]
-        if all(isinstance(i, Improvement) for i in imp_seq):
-            return Improvement.gather(*imp_seq)  # pyright: ignore [reportArgumentType]
-        return None
+        imp_seq = await gather(*[self.check_obj_against_rule(obj, rule, reference, **kwargs) for rule in ruleset.rules])
+
+        if imp_seq is None:
+            logger.warning(f"Generation Failed for `{obj.__class__.__name__}` against Ruleset `{ruleset.name}`")
+            return None
+        return [i for i in imp_seq if i]

fabricatio/capabilities/correct.py

@@ -1,5 +1,6 @@
 """A module containing the Correct capability for reviewing, validating, and improving objects."""
 
+from asyncio import gather
 from typing import Optional, Type, Unpack, cast
 
 from fabricatio.capabilities.propose import Propose
@@ -14,7 +15,7 @@ from fabricatio.models.kwargs_types import (
     ValidateKwargs,
 )
 from fabricatio.rust_instances import TEMPLATE_MANAGER
-from fabricatio.utils import ok, override_kwargs
+from fabricatio.utils import fallback_kwargs, ok, override_kwargs
 
 
 class Correct(Rating, Propose):
@@ -33,8 +34,9 @@ class Correct(Rating, Propose):
             ProblemSolutions: The problem solutions with the best solution selected.
         """
         if (leng := len(problem_solutions.solutions)) == 0:
-            logger.error(f"No solutions found in ProblemSolutions, Skip: {problem_solutions.problem}")
+            logger.error(f"No solutions found in ProblemSolutions, Skip: `{problem_solutions.problem.name}`")
         if leng > 1:
+            logger.info(f"{leng} solutions found in Problem `{problem_solutions.problem.name}`, select the best.")
             problem_solutions.solutions = await self.best(problem_solutions.solutions, **kwargs)
         return problem_solutions
 
@@ -48,11 +50,25 @@ class Correct(Rating, Propose):
         Returns:
             Improvement: The improvement with the best solutions selected for each problem solution.
         """
-        if (leng := len(improvement.problem_solutions)) == 0:
+        if leng := len(improvement.problem_solutions):
+            logger.debug(f"{leng} problem_solutions found in Improvement, decide solution for each of them.")
+            await gather(
+                *[
+                    self.decide_solution(
+                        ps,
+                        **fallback_kwargs(
+                            kwargs, topic=f"which solution is better to deal this problem {ps.problem.compact()}\n\n"
+                        ),
+                    )
+                    for ps in improvement.problem_solutions
+                ],
+            )
+            if any(not (violated := ps).decided() for ps in improvement.problem_solutions):
+                logger.error(f"Some problem_solutions are not decided: {violated}")
+            else:
+                logger.success(f"All problem_solutions are decided '{improvement.focused_on}'")
+        else:
             logger.error(f"No problem_solutions found in Improvement, Skip: {improvement}")
-        if leng > 1:
-            for ps in improvement.problem_solutions:
-                ps.solutions = await self.best(ps.solutions, **kwargs)
         return improvement
 
     async def fix_troubled_obj[M: SketchedAble](
@@ -78,11 +94,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}",
-                    ),
+                        f"{len(problem_solutions.solutions)} solution Found for `{problem_solutions.problem.name}`.",
+                    ).display(),
                     "reference": reference,
                 },
             ),
@@ -111,11 +127,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,
                 },
@@ -148,13 +164,15 @@ class Correct(Rating, Propose):
             TypeError: If the provided object doesn't implement Display or WithBriefing interfaces.
         """
         if not improvement.decided():
+            logger.info(f"Improvement {improvement.focused_on} not decided, start deciding...")
             improvement = await self.decide_improvement(improvement, **override_kwargs(kwargs, default=None))
 
         for ps in improvement.problem_solutions:
+            logger.info(f"Fixing troubling obj {obj.__class__.__name__} when deal with problem: {ps.problem.name}")
             fixed_obj = await self.fix_troubled_obj(obj, ps, reference, **kwargs)
             if fixed_obj is None:
                 logger.error(
-                    f"Failed to fix troubling obj {obj.__class__.__name__} when deal with problem: {ps.problem}",
+                    f"Failed to fix troubling obj {obj.__class__.__name__} when deal with problem: {ps.problem.name}",
                 )
                 return None
             obj = fixed_obj
@@ -178,6 +196,8 @@ class Correct(Rating, Propose):
             Optional[str]: A corrected version of the input string, or None if correction fails.
         """
         if not improvement.decided():
+            logger.info(f"Improvement {improvement.focused_on} not decided, start deciding...")
+
             improvement = await self.decide_improvement(improvement, **override_kwargs(kwargs, default=None))
 
         for ps in improvement.problem_solutions:

fabricatio/capabilities/rating.py

@@ -43,7 +43,7 @@ class Rating(LLMUsage):
             Dict[str, float]: A dictionary with the ratings for each dimension.
         """
 
-        def _validator(response: str) -> Dict[str, float] | None:
+        def _validator(response: str) -> Optional[Dict[str, float]] :
             if (
                 (json_data := JsonCapture.validate_with(response, dict, str))
                 and json_data.keys() == rating_manual.keys()
@@ -88,7 +88,7 @@ class Rating(LLMUsage):
         to_rate: str,
         topic: str,
         criteria: Set[str],
-        manual: Optional[Dict[str, str]],
+        manual: Optional[Dict[str, str]] = None,
         score_range: Tuple[float, float] = (0.0, 1.0),
         **kwargs: Unpack[ValidateKwargs],
     ) -> Dict[str, float]: ...
@@ -99,7 +99,7 @@ class Rating(LLMUsage):
         to_rate: List[str],
         topic: str,
         criteria: Set[str],
-        manual: Optional[Dict[str, str]],
+        manual: Optional[Dict[str, str]] = None,
         score_range: Tuple[float, float] = (0.0, 1.0),
         **kwargs: Unpack[ValidateKwargs],
     ) -> List[Dict[str, float]]: ...
@@ -109,7 +109,7 @@ class Rating(LLMUsage):
         to_rate: Union[str, List[str]],
         topic: str,
         criteria: Set[str],
-        manual: Optional[Dict[str, str]],
+        manual: Optional[Dict[str, str]] = None,
         score_range: Tuple[float, float] = (0.0, 1.0),
         **kwargs: Unpack[ValidateKwargs],
     ) -> Optional[Dict[str, float] | List[Dict[str, float]]]:
@@ -170,7 +170,7 @@ class Rating(LLMUsage):
                     configs.templates.draft_rating_manual_template,
                     {
                         "topic": topic,
-                        "criteria": criteria,
+                        "criteria": list(criteria),
                     },
                 )
             ),
@@ -360,14 +360,14 @@ class Rating(LLMUsage):
         return [sum(ratings[c] * weights[c] for c in criteria) for ratings in ratings_seq]
 
     @overload
-    async def best(self, candidates: List[str], k: int=1, **kwargs: Unpack[CompositeScoreKwargs]) -> List[str]: ...
+    async def best(self, candidates: List[str], k: int = 1, **kwargs: Unpack[CompositeScoreKwargs]) -> List[str]: ...
     @overload
     async def best[T: Display](
-        self, candidates: List[T], k: int=1, **kwargs: Unpack[CompositeScoreKwargs]
+        self, candidates: List[T], k: int = 1, **kwargs: Unpack[CompositeScoreKwargs]
     ) -> List[T]: ...
 
     async def best[T: Display](
-        self, candidates: List[str] | List[T], k: int=1, **kwargs: Unpack[CompositeScoreKwargs]
+        self, candidates: List[str] | List[T], k: int = 1, **kwargs: Unpack[CompositeScoreKwargs]
     ) -> Optional[List[str] | List[T]]:
         """Choose the best candidates from the list of candidates based on the composite score.
 

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/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}")
 
@@ -166,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()
@@ -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/models/extra/article_base.py

@@ -7,15 +7,16 @@ 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,
 )
 
 
@@ -30,7 +31,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,12 +105,9 @@ class ArticleRef(CensoredAble, ProposedUpdateAble):
         return ReferringType.CHAPTER
 
 
-class ArticleMetaData(CensoredAble, Display):
+class ArticleMetaData(SketchedAble, Described, Language):
     """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]
@@ -120,6 +118,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."""
@@ -271,12 +272,9 @@ class ChapterBase[T: SectionBase](ArticleOutlineBase):
         return ""
 
 
-class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, ABC):
+class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, 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
     """Title of the academic paper."""
 
@@ -376,12 +374,31 @@ class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, ABC):
                 return component, summary
         return None
 
+    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())])
+
     @overload
     def find_illegal_ref(self, gather_identical: bool) -> Optional[Tuple[ArticleRef | List[ArticleRef], str]]: ...
 
     @overload
     def find_illegal_ref(self) -> Optional[Tuple[ArticleRef, str]]: ...
 
+    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
+
     def find_illegal_ref(self, gather_identical: bool = False) -> Optional[Tuple[ArticleRef | List[ArticleRef], str]]:
         """Finds the first illegal component in the outline.
 
@@ -389,21 +406,68 @@ class ArticleBase[T: ChapterBase](FinalizedDumpAble, AsPrompt, ABC):
             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 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
+
+                    if ref.referred_chapter_title not in (chap_titles_set):
+                        summary += f"Chapter titled `{ref.referred_chapter_title}` is not any of {chap_titles_set}\n"
+                    if ref.referred_section_title and ref.referred_section_title not in (sec_titles_set):
+                        summary += f"Section Titled `{ref.referred_section_title}` is not any of {sec_titles_set}\n"
+                    if ref.referred_subsection_title and ref.referred_subsection_title not in (subsec_titles_set):
+                        summary += (
+                            f"Subsection Titled `{ref.referred_subsection_title}` is not any of {subsec_titles_set}"
+                        )
+
+                if summary:
+                    return (
+                        (
+                            [
+                                identical_ref
+                                for identical_ref in chain(self.iter_depend_on(), self.iter_support_on())
+                                if identical_ref == ref
+                            ],
+                            summary,
+                        )
+                        if gather_identical
+                        else (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.referred_chapter_title not in chap_titles_set:
+                    summary.append(
+                        f"Chapter titled `{ref.referred_chapter_title}` is not exist, since it is not any of {chap_titles_set}."
+                    )
+                if ref.referred_section_title and (ref.referred_section_title not in sec_titles_set):
+                    summary.append(
+                        f"Section Titled `{ref.referred_section_title}` is not exist, since it is not any of {sec_titles_set}"
+                    )
+                if ref.referred_subsection_title and (ref.referred_subsection_title not in subsec_titles_set):
+                    summary.append(
+                        f"Subsection Titled `{ref.referred_subsection_title}` 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.