fabricatio 0.2.10.dev1__cp312-cp312-win_amd64.whl → 0.2.11__cp312-cp312-win_amd64.whl

fabricatio/actions/article.py

@@ -4,10 +4,12 @@ from asyncio import gather
 from pathlib import Path
 from typing import Callable, List, Optional
 
-from fabricatio.rust import BibManager, detect_language
 from more_itertools import filter_map
+from pydantic import Field
+from rich import print as r_print
 
 from fabricatio.capabilities.censor import Censor
+from fabricatio.capabilities.extract import Extract
 from fabricatio.capabilities.propose import Propose
 from fabricatio.fs import safe_text_read
 from fabricatio.journal import logger
@@ -17,8 +19,10 @@ from fabricatio.models.extra.article_main import Article
 from fabricatio.models.extra.article_outline import ArticleOutline
 from fabricatio.models.extra.article_proposal import ArticleProposal
 from fabricatio.models.extra.rule import RuleSet
+from fabricatio.models.kwargs_types import ValidateKwargs
 from fabricatio.models.task import Task
-from fabricatio.utils import ok
+from fabricatio.rust import BibManager, detect_language
+from fabricatio.utils import ok, wrapp_in_block
 
 
 class ExtractArticleEssence(Action, Propose):
@@ -130,33 +134,65 @@ class GenerateArticleProposal(Action, Propose):
         ).update_ref(briefing)
 
 
-class GenerateInitialOutline(Action, Propose):
+class GenerateInitialOutline(Action, Extract):
     """Generate the initial article outline based on the article proposal."""
 
     output_key: str = "initial_article_outline"
     """The key of the output data."""
 
+    supervisor: bool = False
+    """Whether to use the supervisor to fix the outline."""
+
+    extract_kwargs: ValidateKwargs[Optional[ArticleOutline]] = Field(default_factory=ValidateKwargs)
+    """The kwargs to extract the outline."""
+
     async def _execute(
         self,
         article_proposal: ArticleProposal,
+        supervisor: Optional[bool] = None,
         **_,
     ) -> Optional[ArticleOutline]:
-        raw_outline = await self.aask(
-            f"{(article_proposal.as_prompt())}\n\nNote that you should use `{article_proposal.language}` to write the `ArticleOutline`\n"
+        req = (
             f"Design each chapter of a proper and academic and ready for release manner.\n"
             f"You Must make sure every chapter have sections, and every section have subsections.\n"
-            f"Make the chapter and sections and subsections bing divided into a specific enough article component.",
+            f"Make the chapter and sections and subsections bing divided into a specific enough article component.\n"
+            f"Every chapter must have sections, every section must have subsections.\n"
+            f"Note that you SHALL use `{article_proposal.language}` as written language",
         )
 
+        raw_outline = await self.aask(f"{(article_proposal.as_prompt())}\n{req}")
+
+        if supervisor or (supervisor is None and self.supervisor):
+            from questionary import confirm, text
+
+            r_print(raw_outline)
+            while not await confirm("Accept this version and continue?", default=True).ask_async():
+                imp = await text("Enter the improvement:").ask_async()
+                raw_outline = await self.aask(
+                    f"{article_proposal.as_prompt()}\n{wrapp_in_block(raw_outline, 'Previous ArticleOutline')}\n{req}\n{wrapp_in_block(imp, title='Improvement')}"
+                )
+                r_print(raw_outline)
+
         return ok(
-            await self.propose(
-                ArticleOutline,
-                f"{raw_outline}\n\n\n\noutline provided above is the outline i need to extract to a JSON,",
-            ),
+            await self.extract(ArticleOutline, raw_outline, **self.extract_kwargs),
             "Could not generate the initial outline.",
         ).update_ref(article_proposal)
 
 
+class ExtractOutlineFromRaw(Action, Extract):
+    """Extract the outline from the raw outline."""
+
+    output_key: str = "article_outline_from_raw"
+
+    async def _execute(self, article_outline_raw_path: str | Path, **cxt) -> ArticleOutline:
+        logger.info(f"Extracting outline from raw: {Path(article_outline_raw_path).as_posix()}")
+
+        return ok(
+            await self.extract(ArticleOutline, safe_text_read(article_outline_raw_path)),
+            "Could not extract the outline from raw.",
+        )
+
+
 class FixIntrospectedErrors(Action, Censor):
     """Fix introspected errors in the article outline."""
 
@@ -226,3 +262,12 @@ class GenerateArticle(Action, Censor):
         )
 
         return article
+
+
+class LoadArticle(Action):
+    """Load the article from the outline and typst code."""
+
+    output_key: str = "loaded_article"
+
+    async def _execute(self, article_outline: ArticleOutline, typst_code: str, **cxt) -> Article:
+        return Article.from_mixed_source(article_outline, typst_code)

fabricatio/actions/article_rag.py

@@ -6,13 +6,271 @@ from typing import List, Optional
 
 from fabricatio import BibManager
 from fabricatio.capabilities.censor import Censor
+from fabricatio.capabilities.extract import Extract
 from fabricatio.capabilities.rag import RAG
+from fabricatio.decorators import precheck_package
+from fabricatio.journal import logger
 from fabricatio.models.action import Action
-from fabricatio.models.extra.aricle_rag import ArticleChunk
+from fabricatio.models.extra.aricle_rag import ArticleChunk, CitationManager
 from fabricatio.models.extra.article_essence import ArticleEssence
-from fabricatio.models.extra.article_main import Article, ArticleSubsection
+from fabricatio.models.extra.article_main import Article, ArticleChapter, ArticleSection, ArticleSubsection
+from fabricatio.models.extra.article_outline import ArticleOutline
 from fabricatio.models.extra.rule import RuleSet
-from fabricatio.utils import ok
+from fabricatio.utils import ask_retain, ok
+
+TYPST_CITE_USAGE = (
+    "citation number is REQUIRED to cite any reference!,for example in Auther Pattern: 'Doe et al.[[1]], Jack et al.[[2]]' or in Sentence Suffix Sattern: 'Global requirement is incresing[[1]].'\n"
+    "Everything is build upon the typst language, which is similar to latex, \n"
+    "Legal citing syntax examples(seperated by |): [[1]]|[[1,2]]|[[1-3]]|[[12,13-15]]|[[1-3,5-7]]\n"
+    "Illegal citing syntax examples(seperated by |): [[1],[2],[3]]|[[1],[1-2]]\n"
+    "Those reference mark shall not be omitted during the extraction\n"
+    "It's recommended to cite multiple references that supports your conclusion at a time.\n"
+    "Wrapp inline expression using $ $,like '$>5m$' '$89%$' , and wrapp block equation using $$ $$. if you are using '$' as the money unit, you should add a '\\' before it to avoid being interpreted as a inline equation. For example 'The pants worths 5\\$.'\n"
+    "In addition to that, you can add a label outside the block equation which can be used as a cross reference identifier, the label is a string wrapped in `<` and `>` like `<energy-release-rate-equation>`.Note that the label string should be a summarizing title for the equation being labeled.\n"
+    "you can refer to that label by using the syntax with prefix of `@eqt:`, which indicate that this notation is citing a label from the equations. For example ' @eqt:energy-release-rate-equation ' DO remember that the notation shall have both suffixed and prefixed space char which enable the compiler to distinguish the notation from the plaintext."
+    "Below is a usage example:\n"
+    "```typst\n"
+    "See @eqt:mass-energy-equation , it's the foundation of physics.\n"
+    "$$\n"
+    "E = m c^2\n"
+    "$$  <mass-energy-equation>\n\n\n"
+    "In @eqt:mass-energy-equation , $m$ stands for mass, $c$ stands for speed of light, and $E$ stands for energy. \n"
+    "```"
+)
+
+
+class WriteArticleContentRAG(Action, RAG, Extract):
+    """Write an article based on the provided outline."""
+
+    ref_limit: int = 35
+    """The limit of references to be retrieved"""
+    threshold: float = 0.62
+    """The threshold of relevance"""
+    extractor_model: str
+    """The model to use for extracting the content from the retrieved references."""
+    query_model: str
+    """The model to use for querying the database"""
+    supervisor: bool = False
+    """Whether to use supervisor mode"""
+    req: str = TYPST_CITE_USAGE
+
+    async def _execute(
+        self,
+        article_outline: ArticleOutline,
+        collection_name: Optional[str] = None,
+        supervisor: Optional[bool] = None,
+        **cxt,
+    ) -> Article:
+        article = Article.from_outline(article_outline).update_ref(article_outline)
+        self.target_collection = collection_name or self.safe_target_collection
+        if supervisor or (supervisor is None and self.supervisor):
+            for chap, sec, subsec in article.iter_subsections():
+                await self._supervisor_inner(article, article_outline, chap, sec, subsec)
+
+        else:
+            await gather(
+                *[
+                    self._inner(article, article_outline, chap, sec, subsec)
+                    for chap, sec, subsec in article.iter_subsections()
+                ]
+            )
+        return article.convert_tex()
+
+    @precheck_package(
+        "questionary", "`questionary` is required for supervisor mode, please install it by `fabricatio[qa]`"
+    )
+    async def _supervisor_inner(
+        self,
+        article: Article,
+        article_outline: ArticleOutline,
+        chap: ArticleChapter,
+        sec: ArticleSection,
+        subsec: ArticleSubsection,
+    ) -> ArticleSubsection:
+        from questionary import confirm, text
+        from rich import print as r_print
+
+        ret = await self.search_database(article, article_outline, chap, sec, subsec)
+
+        cm = CitationManager(article_chunks=await ask_retain([r.chunk for r in ret], ret)).set_cite_number_all()
+
+        raw = await self.write_raw(article, article_outline, chap, sec, subsec, cm)
+        r_print(raw)
+
+        while not await confirm("Accept this version and continue?").ask_async():
+            if inst := await text("Search for more refs for additional spec.").ask_async():
+                new_refs = await self.search_database(
+                    article,
+                    article_outline,
+                    chap,
+                    sec,
+                    subsec,
+                    supervisor=True,
+                    extra_instruction=inst,
+                )
+                cm.add_chunks(await ask_retain([r.chunk for r in new_refs], new_refs))
+
+            if instruction := await text("Enter the instructions to improve").ask_async():
+                raw = await self.write_raw(article, article_outline, chap, sec, subsec, cm, instruction)
+            if edt := await text("Edit", default=raw).ask_async():
+                raw = edt
+
+            r_print(raw)
+
+        return await self.extract_new_subsec(subsec, raw, cm)
+
+    async def _inner(
+        self,
+        article: Article,
+        article_outline: ArticleOutline,
+        chap: ArticleChapter,
+        sec: ArticleSection,
+        subsec: ArticleSubsection,
+    ) -> ArticleSubsection:
+        ret = await self.search_database(article, article_outline, chap, sec, subsec)
+        cm = CitationManager(article_chunks=ret).set_cite_number_all()
+
+        raw_paras = await self.write_raw(article, article_outline, chap, sec, subsec, cm)
+
+        return await self.extract_new_subsec(subsec, raw_paras, cm)
+
+    async def extract_new_subsec(
+        self, subsec: ArticleSubsection, raw_paras: str, cm: CitationManager
+    ) -> ArticleSubsection:
+        """Extract the new subsec."""
+        new_subsec = ok(
+            await self.extract(
+                ArticleSubsection,
+                raw_paras,
+                f"Above is the subsection titled `{subsec.title}`.\n"
+                f"I need you to extract the content to update my subsection obj provided below.\n{self.req}"
+                f"{subsec.display()}\n",
+                model=self.extractor_model,
+            ),
+            "Failed to propose new subsection.",
+        )
+        for p in new_subsec.paragraphs:
+            p.content = cm.apply(p.content).replace("$$", "\n$$\n")
+        subsec.update_from(new_subsec)
+        logger.debug(f"{subsec.title}:rpl\n{subsec.display()}")
+        return subsec
+
+    async def write_raw(
+        self,
+        article: Article,
+        article_outline: ArticleOutline,
+        chap: ArticleChapter,
+        sec: ArticleSection,
+        subsec: ArticleSubsection,
+        cm: CitationManager,
+        extra_instruction: str = "",
+    ) -> str:
+        """Write the raw paragraphs of the subsec."""
+        return (
+            (
+                await self.aask(
+                    f"{cm.as_prompt()}\nAbove is some related reference from other auther retrieved for you."
+                    f"{article_outline.finalized_dump()}\n\nAbove is my article outline, I m writing graduate thesis titled `{article.title}`. "
+                    f"More specifically, i m witting the Chapter `{chap.title}` >> Section `{sec.title}` >> Subsection `{subsec.title}`.\n"
+                    f"Please help me write the paragraphs of the subsec mentioned above, which is `{subsec.title}`.\n"
+                    f"{self.req}\n"
+                    f"You SHALL use `{article.language}` as writing language.\n{extra_instruction}\n"
+                    f"Do not use numbered list to display the outcome, you should regard you are writing the main text of the article\n"
+                    f"You should not copy others' works from the references directly on to my thesis, we can only harness the conclusion they have drawn."
+                )
+            )
+            .replace(r" \( ", "$")
+            .replace(r" \) ", "$")
+            .replace(r"\(", "$")
+            .replace(r"\)", "$")
+            .replace("\\[\n", "$$\n")
+            .replace("\\[ ", "$$\n")
+            .replace("\n\\]", "\n$$")
+            .replace(" \\]", "\n$$")
+        )
+
+    async def search_database(
+        self,
+        article: Article,
+        article_outline: ArticleOutline,
+        chap: ArticleChapter,
+        sec: ArticleSection,
+        subsec: ArticleSubsection,
+        extra_instruction: str = "",
+        supervisor: bool = False,
+    ) -> List[ArticleChunk]:
+        """Search database for related references."""
+        ref_q = ok(
+            await self.arefined_query(
+                f"{article_outline.finalized_dump()}\n\nAbove is my article outline, I m writing graduate thesis titled `{article.title}`. "
+                f"More specifically, i m witting the Chapter `{chap.title}` >> Section `{sec.title}` >> Subsection `{subsec.title}`.\n"
+                f"I need to search related references to build up the content of the subsec mentioned above, which is `{subsec.title}`.\n"
+                f"provide 10~16 queries as possible, to get best result!\n"
+                f"You should provide both English version and chinese version of the refined queries!\n{extra_instruction}\n",
+                model=self.query_model,
+            ),
+            "Failed to refine query.",
+        )
+
+        if supervisor:
+            ref_q = await ask_retain(ref_q)
+
+        return await self.aretrieve(
+            ref_q, ArticleChunk, final_limit=self.ref_limit, result_per_query=3, similarity_threshold=self.threshold
+        )
+
+
+class ArticleConsultRAG(Action, RAG):
+    """Write an article based on the provided outline."""
+
+    output_key:str ="consult_count"
+
+    ref_limit: int = 20
+    """The final limit of references."""
+    ref_per_q: int = 3
+    """The limit of references to retrieve per query."""
+    similarity_threshold: float = 0.62
+    """The similarity threshold of references to retrieve."""
+    ref_q_model: Optional[str] = None
+    """The model to use for refining query."""
+    req: str = TYPST_CITE_USAGE
+    """The request for the rag model."""
+
+    @precheck_package(
+        "questionary", "`questionary` is required for supervisor mode, please install it by `fabricatio[qa]`"
+    )
+    async def _execute(self, collection_name: Optional[str] = None, **cxt) -> int:
+        from questionary import confirm, text
+        from rich import print as r_print
+
+        from fabricatio.rust import convert_all_block_tex, convert_all_inline_tex
+
+        self.target_collection = collection_name or self.safe_target_collection
+
+        cm = CitationManager()
+
+        counter = 0
+        while (req := await text("User: ").ask_async()) is not None:
+            if await confirm("Empty the cm?").ask_async():
+                cm.empty()
+            ref_q = await self.arefined_query(req, model=self.ref_q_model)
+            refs = await self.aretrieve(
+                ok(ref_q, "Failed to refine query."),
+                ArticleChunk,
+                final_limit=self.ref_limit,
+                result_per_query=self.ref_per_q,
+                similarity_threshold=self.similarity_threshold,
+            )
+
+            ret = await self.aask(f"{cm.add_chunks(refs).as_prompt()}\n{self.req}\n{req}")
+            ret = convert_all_inline_tex(ret)
+            ret = convert_all_block_tex(ret)
+            ret = cm.apply(ret)
+
+            r_print(ret)
+            counter += 1
+        logger.info(f"{counter} rounds of conversation.")
+        return counter
 
 
 class TweakArticleRAG(Action, RAG, Censor):
@@ -43,7 +301,7 @@ class TweakArticleRAG(Action, RAG, Censor):
         twk_rag_ruleset: Optional[RuleSet] = None,
         parallel: bool = False,
         **cxt,
-    ) -> Optional[Article]:
+    ) -> Article:
         """Write an article based on the provided outline.
 
         This method processes the article outline, either in parallel or sequentially, by enhancing each subsection
@@ -57,7 +315,7 @@ class TweakArticleRAG(Action, RAG, Censor):
             **cxt: Additional context parameters.
 
         Returns:
-            Optional[Article]: The processed article with enhanced subsections and applied censoring rules.
+            Article: The processed article with enhanced subsections and applied censoring rules.
         """
         self.view(collection_name)
 
@@ -90,12 +348,7 @@ class TweakArticleRAG(Action, RAG, Censor):
         """
         refind_q = ok(
             await self.arefined_query(
-                f"{article.referenced.as_prompt()}\n"
-                f"# Subsection requiring reference enhancement\n"
-                f"{subsec.display()}\n"
-                f"# Requirement\n"
-                f"Search related articles in the base to find reference candidates, "
-                f"provide queries in both `English` and `{subsec.language}` can get more accurate results.",
+                f"{article.referenced.as_prompt()}\n# Subsection requiring reference enhancement\n{subsec.display()}\n"
             )
         )
         await self.censor_obj_inplace(
@@ -112,7 +365,7 @@ class TweakArticleRAG(Action, RAG, Censor):
 class ChunkArticle(Action):
     """Chunk an article into smaller chunks."""
 
-    output_key:str = "article_chunks"
+    output_key: str = "article_chunks"
     """The key used to store the output of the action."""
     max_chunk_size: Optional[int] = None
     """The maximum size of each chunk."""
@@ -131,6 +384,7 @@ class ChunkArticle(Action):
             article_path,
             bib_manager,
             max_chunk_size=ok(max_chunk_size or self.max_chunk_size, "No max_chunk_size provided!"),
-            max_overlapping_rate=ok(max_overlapping_rate or self.max_overlapping_rate, "No max_overlapping_rate provided!"),
+            max_overlapping_rate=ok(
+                max_overlapping_rate or self.max_overlapping_rate, "No max_overlapping_rate provided!"
+            ),
         )
-

fabricatio/actions/fs.py

@@ -0,0 +1,25 @@
+"""A module for file system utilities."""
+
+from pathlib import Path
+from typing import Any, List, Mapping, Self
+
+from fabricatio.fs import safe_text_read
+from fabricatio.journal import logger
+from fabricatio.models.action import Action
+from fabricatio.models.generic import FromMapping
+
+
+class ReadText(Action, FromMapping):
+    """Read text from a file."""
+    output_key: str = "read_text"
+    read_path: str | Path
+    """Path to the file to read."""
+
+    async def _execute(self, *_: Any, **cxt) -> str:
+        logger.info(f"Read text from {Path(self.read_path).as_posix()} to {self.output_key}")
+        return safe_text_read(self.read_path)
+
+    @classmethod
+    def from_mapping(cls, mapping: Mapping[str, str | Path], **kwargs: Any) -> List[Self]:
+        """Create a list of ReadText actions from a mapping of output_key to read_path."""
+        return [cls(read_path=p, output_key=k, **kwargs) for k, p in mapping.items()]

fabricatio/actions/output.py

@@ -1,11 +1,11 @@
 """Dump the finalized output to a file."""
 
 from pathlib import Path
-from typing import Any, Iterable, List, Optional, Type
+from typing import Any, Iterable, List, Mapping, Optional, Type
 
 from fabricatio.journal import logger
 from fabricatio.models.action import Action
-from fabricatio.models.generic import FinalizedDumpAble, PersistentAble
+from fabricatio.models.generic import FinalizedDumpAble, FromMapping, PersistentAble
 from fabricatio.models.task import Task
 from fabricatio.utils import ok
 
@@ -115,7 +115,7 @@ class RetrieveFromPersistent[T: PersistentAble](Action):
         return self.retrieve_cls.from_persistent(self.load_path)
 
 
-class RetrieveFromLatest[T: PersistentAble](RetrieveFromPersistent[T]):
+class RetrieveFromLatest[T: PersistentAble](RetrieveFromPersistent[T], FromMapping):
     """Retrieve the object from the latest persistent file in the dir at `load_path`."""
 
     async def _execute(self, /, **_) -> Optional[T]:
@@ -130,6 +130,20 @@ class RetrieveFromLatest[T: PersistentAble](RetrieveFromPersistent[T]):
         logger.error(f"Path {self.load_path} is not a directory")
         return None
 
+    @classmethod
+    def from_mapping(
+        cls,
+        mapping: Mapping[str, str | Path],
+        *,
+        retrieve_cls: Type[T],
+        **kwargs,
+    ) -> List["RetrieveFromLatest[T]"]:
+        """Create a list of `RetrieveFromLatest` from the mapping."""
+        return [
+            cls(retrieve_cls=retrieve_cls, load_path=Path(p).as_posix(), output_key=o, **kwargs)
+            for o, p in mapping.items()
+        ]
+
 
 class GatherAsList(Action):
     """Gather the objects from the context as a list.

fabricatio/actions/rag.py

@@ -2,8 +2,6 @@
 
 from typing import List, Optional
 
-from questionary import text
-
 from fabricatio.capabilities.rag import RAG
 from fabricatio.config import configs
 from fabricatio.journal import logger
@@ -21,7 +19,7 @@ class InjectToDB(Action, RAG):
     """The name of the collection to inject data into."""
 
     async def _execute[T: MilvusDataBase](
-        self, to_inject: Optional[T] | List[Optional[T]], override_inject: bool = False, **_
+            self, to_inject: Optional[T] | List[Optional[T]], override_inject: bool = False, **_
     ) -> Optional[str]:
         from pymilvus.milvus_client import IndexParams
 
@@ -74,6 +72,8 @@ class RAGTalk(Action, RAG):
     output_key: str = "task_output"
 
     async def _execute(self, task_input: Task[str], **kwargs) -> int:
+        from questionary import text
+
         collection_name = kwargs.get("collection_name", "my_collection")
         counter = 0
 

fabricatio/actions/rules.py

@@ -1,15 +1,16 @@
 """A module containing the DraftRuleSet action."""
 
-from typing import List, Optional
+from typing import Any, List, Mapping, Optional, Self, Tuple
 
 from fabricatio.capabilities.check import Check
 from fabricatio.journal import logger
 from fabricatio.models.action import Action
 from fabricatio.models.extra.rule import RuleSet
+from fabricatio.models.generic import FromMapping
 from fabricatio.utils import ok
 
 
-class DraftRuleSet(Action, Check):
+class DraftRuleSet(Action, Check, FromMapping):
     """Action to draft a ruleset based on a given requirement description."""
 
     output_key: str = "drafted_ruleset"
@@ -45,8 +46,13 @@ class DraftRuleSet(Action, Check):
             logger.warning(f"Drafting Rule Failed for:\n{ruleset_requirement}")
         return ruleset
 
+    @classmethod
+    def from_mapping(cls, mapping: Mapping[str, Tuple[int, str]], **kwargs) -> List[Self]:
+        """Create a list of DraftRuleSet actions from a mapping of output keys to tuples of rule counts and requirements."""
+        return [cls(ruleset_requirement=r, rule_count=c, output_key=k, **kwargs) for k, (c, r) in mapping.items()]
 
-class GatherRuleset(Action):
+
+class GatherRuleset(Action, FromMapping):
     """Action to gather a ruleset from a given requirement description."""
 
     output_key: str = "gathered_ruleset"
@@ -55,6 +61,11 @@ class GatherRuleset(Action):
     to_gather: List[str]
     """the cxt name of RuleSet to gather"""
 
+    @classmethod
+    def from_mapping(cls, mapping: Mapping[str, List[str]], **kwargs: Any) -> List[Self]:
+        """Create a list of GatherRuleset actions from a mapping of output keys to tuples of rule counts and requirements."""
+        return [cls(to_gather=t, output_key=k, **kwargs) for k, t in mapping.items()]
+
     async def _execute(self, **cxt) -> RuleSet:
         logger.info(f"Gathering Ruleset from {self.to_gather}")
         # Fix for not_found

fabricatio/capabilities/extract.py

@@ -0,0 +1,70 @@
+"""A module that provide capabilities for extracting information from a given source to a model."""
+
+from typing import List, Optional, Type, Unpack, overload
+
+from fabricatio import TEMPLATE_MANAGER
+from fabricatio.capabilities.propose import Propose
+from fabricatio.config import configs
+from fabricatio.models.generic import ProposedAble
+from fabricatio.models.kwargs_types import ValidateKwargs
+
+
+class Extract(Propose):
+    """A class that extract information from a given source to a model."""
+
+    @overload
+    async def extract[M: ProposedAble](
+        self,
+        cls: Type[M],
+        source: str,
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[M]],
+    ) -> M: ...
+    @overload
+    async def extract[M: ProposedAble](
+        self,
+        cls: Type[M],
+        source: str,
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[None]],
+    ) -> Optional[M]: ...
+
+    @overload
+    async def extract[M: ProposedAble](
+        self,
+        cls: Type[M],
+        source: List[str],
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[M]],
+    ) -> List[M]: ...
+    @overload
+    async def extract[M: ProposedAble](
+        self,
+        cls: Type[M],
+        source: List[str],
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[None]],
+    ) -> List[Optional[M]]: ...
+    async def extract[M: ProposedAble](
+        self,
+        cls: Type[M],
+        source: List[str] | str,
+        extract_requirement: Optional[str] = None,
+        align_language: bool = True,
+        **kwargs: Unpack[ValidateKwargs[Optional[M]]],
+    ) -> M | List[M] | Optional[M] | List[Optional[M]]:
+        """Extract information from a given source to a model."""
+        return await self.propose(
+            cls,
+            prompt=TEMPLATE_MANAGER.render_template(
+                configs.templates.extract_template,
+                [{"source": s, "extract_requirement": extract_requirement} for s in source]
+                if isinstance(source, list)
+                else {"source": source, "extract_requirement": extract_requirement, "align_language": align_language},
+            ),
+            **kwargs,
+        )