fabricatio 0.2.9.dev3__cp312-cp312-win_amd64.whl → 0.2.10__cp312-cp312-win_amd64.whl

fabricatio/capabilities/correct.py

@@ -57,7 +57,7 @@ class Correct(Rating, Propose):
                     self.decide_solution(
                         ps,
                         **fallback_kwargs(
-                            kwargs, topic=f"which solution is better to deal this problem {ps.problem.compact()}\n\n"
+                            kwargs, topic=f"which solution is better to deal this problem {ps.problem.description}\n\n"
                         ),
                     )
                     for ps in improvement.problem_solutions
@@ -167,13 +167,12 @@ class Correct(Rating, Propose):
             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}")
+        total = len(improvement.problem_solutions)
+        for idx, ps in enumerate(improvement.problem_solutions):
+            logger.info(f"[{idx + 1}/{total}] Fixing {obj.__class__.__name__} for 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.name}",
-                )
+                logger.error(f"[{idx + 1}/{total}] Failed to fix problem `{ps.problem.name}`")
                 return None
             obj = fixed_obj
         return obj

fabricatio/capabilities/rag.py

@@ -3,28 +3,22 @@
 try:
     from pymilvus import MilvusClient
 except ImportError as e:
-    raise RuntimeError("pymilvus is not installed. Have you installed `fabricatio[rag]` instead of `fabricatio`?") from e
+    raise RuntimeError(
+        "pymilvus is not installed. Have you installed `fabricatio[rag]` instead of `fabricatio`?"
+    ) from e
 from functools import lru_cache
 from operator import itemgetter
-from os import PathLike
-from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional, Self, Union, Unpack, cast, overload
+from typing import List, Optional, Self, Type, Unpack
 
 from more_itertools.recipes import flatten, unique
 from pydantic import Field, PrivateAttr
 
 from fabricatio.config import configs
 from fabricatio.journal import logger
-from fabricatio.models.kwargs_types import (
-    ChooseKwargs,
-    CollectionConfigKwargs,
-    EmbeddingKwargs,
-    FetchKwargs,
-    LLMKwargs,
-    RetrievalKwargs,
-)
+from fabricatio.models.adv_kwargs_types import CollectionConfigKwargs, FetchKwargs
+from fabricatio.models.extra.rag import MilvusDataBase
+from fabricatio.models.kwargs_types import ChooseKwargs
 from fabricatio.models.usages import EmbeddingUsage
-from fabricatio.models.utils import MilvusData
 from fabricatio.rust_instances import TEMPLATE_MANAGER
 from fabricatio.utils import ok
 
@@ -78,40 +72,6 @@ class RAG(EmbeddingUsage):
             raise RuntimeError("Client is not initialized. Have you called `self.init_client()`?")
         return self
 
-    @overload
-    async def pack(
-        self, input_text: List[str], subject: Optional[str] = None, **kwargs: Unpack[EmbeddingKwargs]
-    ) -> List[MilvusData]: ...
-    @overload
-    async def pack(
-        self, input_text: str, subject: Optional[str] = None, **kwargs: Unpack[EmbeddingKwargs]
-    ) -> MilvusData: ...
-
-    async def pack(
-        self, input_text: List[str] | str, subject: Optional[str] = None, **kwargs: Unpack[EmbeddingKwargs]
-    ) -> List[MilvusData] | MilvusData:
-        """Asynchronously generates MilvusData objects for the given input text.
-
-        Args:
-            input_text (List[str] | str): A string or list of strings to generate embeddings for.
-            subject (Optional[str]): The subject of the input text. Defaults to None.
-            **kwargs (Unpack[EmbeddingKwargs]): Additional keyword arguments for embedding.
-
-        Returns:
-            List[MilvusData] | MilvusData: The generated MilvusData objects.
-        """
-        if isinstance(input_text, str):
-            return MilvusData(vector=await self.vectorize(input_text, **kwargs), text=input_text, subject=subject)
-        vecs = await self.vectorize(input_text, **kwargs)
-        return [
-            MilvusData(
-                vector=vec,
-                text=text,
-                subject=subject,
-            )
-            for text, vec in zip(input_text, vecs, strict=True)
-        ]
-
     def view(
         self, collection_name: Optional[str], create: bool = False, **kwargs: Unpack[CollectionConfigKwargs]
     ) -> Self:
@@ -152,29 +112,27 @@ class RAG(EmbeddingUsage):
         Returns:
             str: The name of the collection being viewed.
         """
-        if self.target_collection is None:
-            raise RuntimeError("No collection is being viewed. Have you called `self.view()`?")
-        return self.target_collection
+        return ok(self.target_collection, "No collection is being viewed. Have you called `self.view()`?")
 
-    def add_document[D: Union[Dict[str, Any], MilvusData]](
-        self, data: D | List[D], collection_name: Optional[str] = None, flush: bool = False
+    async def add_document[D: MilvusDataBase](
+        self, data: List[D] | D, collection_name: Optional[str] = None, flush: bool = False
     ) -> Self:
         """Adds a document to the specified collection.
 
         Args:
-            data (Union[Dict[str, Any], MilvusData] | List[Union[Dict[str, Any], MilvusData]]): The data to be added to the collection.
+            data (Union[Dict[str, Any], MilvusDataBase] | List[Union[Dict[str, Any], MilvusDataBase]]): The data to be added to the collection.
             collection_name (Optional[str]): The name of the collection. If not provided, the currently viewed collection is used.
             flush (bool): Whether to flush the collection after insertion.
 
         Returns:
             Self: The current instance, allowing for method chaining.
         """
-        if isinstance(data, MilvusData):
-            prepared_data = data.prepare_insertion()
-        elif isinstance(data, list):
-            prepared_data = [d.prepare_insertion() if isinstance(d, MilvusData) else d for d in data]
-        else:
-            raise TypeError(f"Expected MilvusData or list of MilvusData, got {type(data)}")
+        if isinstance(data, MilvusDataBase):
+            data = [data]
+
+        data_vec = await self.vectorize([d.prepare_vectorization() for d in data])
+        prepared_data = [d.prepare_insertion(vec) for d, vec in zip(data, data_vec, strict=True)]
+
         c_name = collection_name or self.safe_target_collection
         self.check_client().client.insert(c_name, prepared_data)
 
@@ -183,84 +141,33 @@ class RAG(EmbeddingUsage):
             self.client.flush(c_name)
         return self
 
-    async def consume_file(
-        self,
-        source: List[PathLike] | PathLike,
-        reader: Callable[[PathLike], str] = lambda path: Path(path).read_text(encoding="utf-8"),
-        collection_name: Optional[str] = None,
-    ) -> Self:
-        """Consume a file and add its content to the collection.
-
-        Args:
-            source (PathLike): The path to the file to be consumed.
-            reader (Callable[[PathLike], MilvusData]): The reader function to read the file.
-            collection_name (Optional[str]): The name of the collection. If not provided, the currently viewed collection is used.
-
-        Returns:
-            Self: The current instance, allowing for method chaining.
-        """
-        if not isinstance(source, list):
-            source = [source]
-        return await self.consume_string([reader(s) for s in source], collection_name)
-
-    async def consume_string(self, text: List[str] | str, collection_name: Optional[str] = None) -> Self:
-        """Consume a string and add it to the collection.
-
-        Args:
-            text (List[str] | str): The text to be added to the collection.
-            collection_name (Optional[str]): The name of the collection. If not provided, the currently viewed collection is used.
-
-        Returns:
-            Self: The current instance, allowing for method chaining.
-        """
-        self.add_document(await self.pack(text), collection_name or self.safe_target_collection, flush=True)
-        return self
-
-    @overload
-    async def afetch_document[V: (int, str, float, bytes)](
+    async def afetch_document[D: MilvusDataBase](
         self,
         vecs: List[List[float]],
-        desired_fields: List[str],
+        document_model: Type[D],
         collection_name: Optional[str] = None,
         similarity_threshold: float = 0.37,
         result_per_query: int = 10,
-    ) -> List[Dict[str, V]]: ...
-
-    @overload
-    async def afetch_document[V: (int, str, float, bytes)](
-        self,
-        vecs: List[List[float]],
-        desired_fields: str,
-        collection_name: Optional[str] = None,
-        similarity_threshold: float = 0.37,
-        result_per_query: int = 10,
-    ) -> List[V]: ...
-    async def afetch_document[V: (int, str, float, bytes)](
-        self,
-        vecs: List[List[float]],
-        desired_fields: List[str] | str,
-        collection_name: Optional[str] = None,
-        similarity_threshold: float = 0.37,
-        result_per_query: int = 10,
-    ) -> List[Dict[str, Any]] | List[V]:
-        """Fetch data from the collection.
+    ) -> List[D]:
+        """Asynchronously fetches documents from a Milvus database based on input vectors.
 
         Args:
-            vecs (List[List[float]]): The vectors to search for.
-            desired_fields (List[str] | str): The fields to retrieve.
-            collection_name (Optional[str]): The name of the collection. If not provided, the currently viewed collection is used.
-            similarity_threshold (float): The threshold for similarity, only results above this threshold will be returned.
-            result_per_query (int): The number of results to return per query.
+           vecs (List[List[float]]): A list of vectors to search for in the database.
+           document_model (Type[D]): The model class used to convert fetched data into document objects.
+           collection_name (Optional[str]): The name of the collection to search within.
+                                             If None, the currently viewed collection is used.
+           similarity_threshold (float): The similarity threshold for vector search. Defaults to 0.37.
+           result_per_query (int): The maximum number of results to return per query. Defaults to 10.
 
         Returns:
-            List[Dict[str, Any]] | List[Any]: The retrieved data.
+           List[D]: A list of document objects created from the fetched data.
         """
         # Step 1: Search for vectors
         search_results = self.check_client().client.search(
             collection_name or self.safe_target_collection,
             vecs,
             search_params={"radius": similarity_threshold},
-            output_fields=desired_fields if isinstance(desired_fields, list) else [desired_fields],
+            output_fields=list(document_model.model_fields),
             limit=result_per_query,
         )
 
@@ -270,104 +177,42 @@ class RAG(EmbeddingUsage):
         # Step 3: Sort by distance (descending)
         sorted_results = sorted(unique_results, key=itemgetter("distance"), reverse=True)
 
-        logger.debug(f"Searched similarities: {[t['distance'] for t in sorted_results]}")
+        logger.debug(
+            f"Fetched {len(sorted_results)} document,searched similarities: {[t['distance'] for t in sorted_results]}"
+        )
         # Step 4: Extract the entities
         resp = [result["entity"] for result in sorted_results]
 
-        if isinstance(desired_fields, list):
-            return resp
-        return [r.get(desired_fields) for r in resp]  # extract the single field as list
+        return document_model.from_sequence(resp)
 
-    async def aretrieve(
+    async def aretrieve[D: MilvusDataBase](
         self,
         query: List[str] | str,
+        document_model: Type[D],
         final_limit: int = 20,
         **kwargs: Unpack[FetchKwargs],
-    ) -> List[str]:
+    ) -> List[D]:
         """Retrieve data from the collection.
 
         Args:
             query (List[str] | str): The query to be used for retrieval.
+            document_model (Type[D]): The model class used to convert retrieved data into document objects.
             final_limit (int): The final limit on the number of results to return.
             **kwargs (Unpack[FetchKwargs]): Additional keyword arguments for retrieval.
 
         Returns:
-            List[str]: A list of strings containing the retrieved data.
+            List[D]: A list of document objects created from the retrieved data.
         """
         if isinstance(query, str):
             query = [query]
-        return cast(
-            "List[str]",
+        return (
             await self.afetch_document(
                 vecs=(await self.vectorize(query)),
-                desired_fields="text",
+                document_model=document_model,
                 **kwargs,
-            ),
+            )
         )[:final_limit]
 
-    async def aretrieve_compact(
-        self,
-        query: List[str] | str,
-        **kwargs: Unpack[RetrievalKwargs],
-    ) -> str:
-        """Retrieve data from the collection and format it for display.
-
-        Args:
-            query (List[str] | str): The query to be used for retrieval.
-            **kwargs (Unpack[RetrievalKwargs]): Additional keyword arguments for retrieval.
-
-        Returns:
-            str: A formatted string containing the retrieved data.
-        """
-        return TEMPLATE_MANAGER.render_template(
-            configs.templates.retrieved_display_template, {"docs": (await self.aretrieve(query, **kwargs))}
-        )
-
-    async def aask_retrieved(
-        self,
-        question: str,
-        query: Optional[List[str] | str] = None,
-        collection_name: Optional[str] = None,
-        extra_system_message: str = "",
-        result_per_query: int = 10,
-        final_limit: int = 20,
-        similarity_threshold: float = 0.37,
-        **kwargs: Unpack[LLMKwargs],
-    ) -> str:
-        """Asks a question by retrieving relevant documents based on the provided query.
-
-        This method performs document retrieval using the given query, then asks the
-        specified question using the retrieved documents as context.
-
-        Args:
-            question (str): The question to be asked.
-            query (List[str] | str): The query or list of queries used for document retrieval.
-            collection_name (Optional[str]): The name of the collection to retrieve documents from.
-                                              If not provided, the currently viewed collection is used.
-            extra_system_message (str): An additional system message to be included in the prompt.
-            result_per_query (int): The number of results to return per query. Default is 10.
-            final_limit (int): The maximum number of retrieved documents to consider. Default is 20.
-            similarity_threshold (float): The threshold for similarity, only results above this threshold will be returned.
-            **kwargs (Unpack[LLMKwargs]): Additional keyword arguments passed to the underlying `aask` method.
-
-        Returns:
-            str: A string response generated after asking with the context of retrieved documents.
-        """
-        rendered = await self.aretrieve_compact(
-            query or question,
-            final_limit=final_limit,
-            collection_name=collection_name,
-            result_per_query=result_per_query,
-            similarity_threshold=similarity_threshold,
-        )
-
-        logger.debug(f"Retrieved Documents: \n{rendered}")
-        return await self.aask(
-            question,
-            f"{rendered}\n\n{extra_system_message}",
-            **kwargs,
-        )
-
     async def arefined_query(self, question: List[str] | str, **kwargs: Unpack[ChooseKwargs]) -> Optional[List[str]]:
         """Refines the given question using a template.
 
@@ -385,38 +230,3 @@ class RAG(EmbeddingUsage):
             ),
             **kwargs,
         )
-
-    async def aask_refined(
-        self,
-        question: str,
-        collection_name: Optional[str] = None,
-        extra_system_message: str = "",
-        result_per_query: int = 10,
-        final_limit: int = 20,
-        similarity_threshold: float = 0.37,
-        **kwargs: Unpack[LLMKwargs],
-    ) -> str:
-        """Asks a question using a refined query based on the provided question.
-
-        Args:
-            question (str): The question to be asked.
-            collection_name (Optional[str]): The name of the collection to retrieve documents from.
-            extra_system_message (str): An additional system message to be included in the prompt.
-            result_per_query (int): The number of results to return per query. Default is 10.
-            final_limit (int): The maximum number of retrieved documents to consider. Default is 20.
-            similarity_threshold (float): The threshold for similarity, only results above this threshold will be returned.
-            **kwargs (Unpack[LLMKwargs]): Additional keyword arguments passed to the underlying `aask` method.
-
-        Returns:
-            str: A string response generated after asking with the refined question.
-        """
-        return await self.aask_retrieved(
-            question,
-            await self.arefined_query(question, **kwargs),
-            collection_name=collection_name,
-            extra_system_message=extra_system_message,
-            result_per_query=result_per_query,
-            final_limit=final_limit,
-            similarity_threshold=similarity_threshold,
-            **kwargs,
-        )

fabricatio/capabilities/rating.py

@@ -5,19 +5,19 @@ from random import sample
 from typing import Dict, List, Optional, Set, Tuple, Union, Unpack, overload
 
 from more_itertools import flatten, windowed
-from pydantic import NonNegativeInt, PositiveInt
+from pydantic import Field, NonNegativeInt, PositiveInt, create_model
 
+from fabricatio.capabilities.propose import Propose
 from fabricatio.config import configs
 from fabricatio.journal import logger
-from fabricatio.models.generic import Display
+from fabricatio.models.generic import Display, ProposedAble
 from fabricatio.models.kwargs_types import CompositeScoreKwargs, ValidateKwargs
-from fabricatio.models.usages import LLMUsage
 from fabricatio.parser import JsonCapture
 from fabricatio.rust_instances import TEMPLATE_MANAGER
-from fabricatio.utils import ok, override_kwargs
+from fabricatio.utils import fallback_kwargs, ok, override_kwargs
 
 
-class Rating(LLMUsage):
+class Rating(Propose):
     """A class that provides functionality to rate tasks based on a rating manual and score range.
 
     References:
@@ -30,7 +30,7 @@ class Rating(LLMUsage):
         rating_manual: Dict[str, str],
         score_range: Tuple[float, float],
         **kwargs: Unpack[ValidateKwargs[Dict[str, float]]],
-    ) -> Optional[Dict[str, float] | List[Dict[str, float]]]:
+    ) -> Dict[str, float] | List[Dict[str, float]] | List[Optional[Dict[str, float]]] | None:
         """Rate a given string based on a rating manual and score range.
 
         Args:
@@ -42,45 +42,49 @@ class Rating(LLMUsage):
         Returns:
             Dict[str, float]: A dictionary with the ratings for each dimension.
         """
-
-        def _validator(response: str) -> Optional[Dict[str, float]] :
-            if (
-                (json_data := JsonCapture.validate_with(response, dict, str))
-                and json_data.keys() == rating_manual.keys()
-                and all(score_range[0] <= v <= score_range[1] for v in json_data.values())
-            ):
-                return json_data
-            return None
-
-        logger.info(f"Rating for {to_rate}")
-        return await self.aask_validate(
-            question=(
-                TEMPLATE_MANAGER.render_template(
-                    configs.templates.rate_fine_grind_template,
-                    {
-                        "to_rate": to_rate,
-                        "min_score": score_range[0],
-                        "max_score": score_range[1],
-                        "rating_manual": rating_manual,
-                    },
+        min_score, max_score = score_range
+        tip = (max_score - min_score) / 9
+
+        model = create_model(  # pyright: ignore [reportCallIssue]
+            "RatingResult",
+            __base__=ProposedAble,
+            __doc__=f"The rating result contains the scores against each criterion, with min_score={min_score} and max_score={max_score}.",
+            **{  # pyright: ignore [reportArgumentType]
+                criterion: (
+                    float,
+                    Field(
+                        ge=min_score,
+                        le=max_score,
+                        description=desc,
+                        examples=[round(min_score + tip * i, 2) for i in range(10)],
+                    ),
                 )
+                for criterion, desc in rating_manual.items()
+            },
+        )
+
+        res = await self.propose(
+            model,
+            TEMPLATE_MANAGER.render_template(
+                configs.templates.rate_fine_grind_template,
+                {"to_rate": to_rate, "min_score": min_score, "max_score": max_score},
             )
             if isinstance(to_rate, str)
             else [
                 TEMPLATE_MANAGER.render_template(
                     configs.templates.rate_fine_grind_template,
-                    {
-                        "to_rate": item,
-                        "min_score": score_range[0],
-                        "max_score": score_range[1],
-                        "rating_manual": rating_manual,
-                    },
+                    {"to_rate": t, "min_score": min_score, "max_score": max_score},
                 )
-                for item in to_rate
+                for t in to_rate
             ],
-            validator=_validator,
-            **kwargs,
+            **override_kwargs(kwargs, default=None),
         )
+        default = kwargs.get("default")
+        if isinstance(res, list):
+            return [r.model_dump() if r else default for r in res]
+        if res is None:
+            return default
+        return res.model_dump()
 
     @overload
     async def rate(
@@ -112,7 +116,7 @@ class Rating(LLMUsage):
         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]]]:
+    ) -> Dict[str, float] | List[Dict[str, float]] | List[Optional[Dict[str, float]]] | None:
         """Rate a given string or a sequence of strings based on a topic, criteria, and score range.
 
         Args:
@@ -133,7 +137,7 @@ class Rating(LLMUsage):
             or dict(zip(criteria, criteria, strict=True))
         )
 
-        return await self.rate_fine_grind(to_rate, manual, score_range, **kwargs)
+        return await self.rate_fine_grind(to_rate, manual, score_range, **fallback_kwargs(kwargs, co_extractor={}))
 
     async def draft_rating_manual(
         self, topic: str, criteria: Optional[Set[str]] = None, **kwargs: Unpack[ValidateKwargs[Dict[str, str]]]
@@ -244,7 +248,7 @@ class Rating(LLMUsage):
 
         # extract reasons from the comparison of ordered pairs of extracted from examples
         reasons = flatten(
-            await self.aask_validate(
+            await self.aask_validate(  # pyright: ignore [reportArgumentType]
                 question=[
                     TEMPLATE_MANAGER.render_template(
                         configs.templates.extract_reasons_from_examples_template,
@@ -319,9 +323,11 @@ class Rating(LLMUsage):
             validator=lambda resp: JsonCapture.validate_with(resp, target_type=float),
             **kwargs,
         )
+        if not all(relative_weights):
+            raise ValueError(f"found illegal weight: {relative_weights}")
         weights = [1.0]
         for rw in relative_weights:
-            weights.append(weights[-1] * rw)
+            weights.append(weights[-1] * rw)  # pyright: ignore [reportOperatorIssue]
         total = sum(weights)
         return dict(zip(criteria_seq, [w / total for w in weights], strict=True))
 

fabricatio/config.py

@@ -44,7 +44,7 @@ class LLMConfig(BaseModel):
         top_p (NonNegativeFloat): The top p of the LLM model. Controls diversity via nucleus sampling. Set to 0.35 as per request.
         generation_count (PositiveInt): The number of generations to generate. Default is 1.
         stream (bool): Whether to stream the LLM model's response. Default is False.
-        max_tokens (PositiveInt): The maximum number of tokens to generate. Set to 8192 as per request.
+        max_tokens (PositiveInt): The maximum number of tokens to generate.
     """
 
     model_config = ConfigDict(use_attribute_docstrings=True)
@@ -79,15 +79,17 @@ class LLMConfig(BaseModel):
     """Whether to stream the LLM model's response. Default is False."""
 
     max_tokens: Optional[PositiveInt] = Field(default=None)
-    """The maximum number of tokens to generate. Set to 8192 as per request."""
+    """The maximum number of tokens to generate."""
 
     rpm: Optional[PositiveInt] = Field(default=100)
     """The rate limit of the LLM model in requests per minute. None means not checked."""
 
     tpm: Optional[PositiveInt] = Field(default=1000000)
     """The rate limit of the LLM model in tokens per minute. None means not checked."""
-
-
+    presence_penalty:Optional[PositiveFloat]=None
+    """The presence penalty of the LLM model."""
+    frequency_penalty:Optional[PositiveFloat]=None
+    """The frequency penalty of the LLM model."""
 class EmbeddingConfig(BaseModel):
     """Embedding configuration class."""
 

fabricatio/constants.py

@@ -0,0 +1,20 @@
+"""A module containing constants used throughout the library."""
+from enum import StrEnum
+
+
+class TaskStatus(StrEnum):
+    """An enumeration representing the status of a task.
+
+    Attributes:
+        Pending: The task is pending.
+        Running: The task is currently running.
+        Finished: The task has been successfully completed.
+        Failed: The task has failed.
+        Cancelled: The task has been cancelled.
+    """
+
+    Pending = "pending"
+    Running = "running"
+    Finished = "finished"
+    Failed = "failed"
+    Cancelled = "cancelled"

fabricatio/decorators.py

@@ -2,6 +2,7 @@
 
 from asyncio import iscoroutinefunction
 from functools import wraps
+from importlib.util import find_spec
 from inspect import signature
 from shutil import which
 from types import ModuleType
@@ -209,3 +210,25 @@ def logging_exec_time[**P, R](func: Callable[P, R]) -> Callable[P, R]:
         return result
 
     return _wrapper
+
+
+def precheck_package[**P, R](package_name: str, msg: str) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Check if a package exists in the current environment.
+
+    Args:
+        package_name (str): The name of the package to check.
+        msg (str): The message to display if the package is not found.
+
+    Returns:
+        bool: True if the package exists, False otherwise.
+    """
+
+    def _wrapper(func: Callable[P, R]) -> Callable[P, R]:
+        def _inner(*args: P.args, **kwargs: P.kwargs) -> R:
+            if find_spec(package_name):
+                return func(*args, **kwargs)
+            raise RuntimeError(msg)
+
+        return _inner
+
+    return _wrapper

fabricatio/fs/readers.py

@@ -1,9 +1,10 @@
 """Filesystem readers for Fabricatio."""
 
 from pathlib import Path
-from typing import Dict
+from typing import Dict, List, Tuple
 
 import orjson
+import regex
 from magika import Magika
 
 from fabricatio.config import configs
@@ -44,3 +45,21 @@ def safe_json_read(path: Path | str) -> Dict:
     except (orjson.JSONDecodeError, IsADirectoryError, FileNotFoundError) as e:
         logger.error(f"Failed to read file {path}: {e!s}")
         return {}
+
+
+def extract_sections(string: str, level: int, section_char: str = "#") -> List[Tuple[str, str]]:
+    """Extract sections from markdown-style text by header level.
+
+    Args:
+        string (str): Input text to parse
+        level (int): Header level (e.g., 1 for '#', 2 for '##')
+        section_char (str, optional): The character used for headers (default: '#')
+
+    Returns:
+        List[Tuple[str, str]]: List of (header_text, section_content) tuples
+    """
+    return regex.findall(
+        r"^%s{%d}\s+(.+?)\n((?:(?!^%s{%d}\s).|\n)*)" % (section_char, level, section_char, level),
+        string,
+        regex.MULTILINE,
+    )