fabricatio 0.2.1.dev0__cp313-cp313-win_amd64.whl → 0.3.14.dev4__cp313-cp313-win_amd64.whl

fabricatio/actions/article_rag.py

@@ -0,0 +1,416 @@
+"""A module for writing articles using RAG (Retrieval-Augmented Generation) capabilities."""
+
+from asyncio import gather
+from pathlib import Path
+from typing import ClassVar, List, Optional
+
+from pydantic import Field, PositiveInt
+
+from fabricatio.capabilities.advanced_rag import AdvancedRAG
+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, CitationManager
+from fabricatio.models.extra.article_essence import ArticleEssence
+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.models.kwargs_types import ChooseKwargs, LLMKwargs
+from fabricatio.rust import (
+    BibManager,
+    convert_all_block_tex,
+    convert_all_inline_tex,
+    convert_to_block_formula,
+    convert_to_inline_formula,
+    fix_misplaced_labels,
+)
+from fabricatio.utils import ok
+
+TYPST_CITE_USAGE = (
+    "citation number is REQUIRED to cite any reference!'\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"
+    "You SHALL not cite a single reference more than once!"
+    "It's recommended to cite multiple references that supports your conclusion at a time.\n"
+)
+
+TYPST_MATH_USAGE = (
+    "Wrap inline expression with '\\(' and '\\)',like '\\(>5m\\)' '\\(89%\\)', and wrap block equation with '\\[' and '\\]'.\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 and should never be written within the formula block.\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 two 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"
+    "```\n"
+)
+
+
+class WriteArticleContentRAG(Action, Extract, AdvancedRAG):
+    """Write an article based on the provided outline."""
+
+    ctx_override: ClassVar[bool] = True
+    search_increment_multiplier: float = 1.6
+    """The increment multiplier of the search increment."""
+    ref_limit: int = 35
+    """The limit of references to be retrieved"""
+    threshold: float = 0.62
+    """The threshold of relevance"""
+    extractor_model: LLMKwargs
+    """The model to use for extracting the content from the retrieved references."""
+    query_model: ChooseKwargs
+    """The model to use for querying the database"""
+    supervisor: bool = False
+    """Whether to use supervisor mode"""
+    result_per_query: PositiveInt = 4
+    """The number of results to be returned per query."""
+    cite_req: str = TYPST_CITE_USAGE
+    """The req of the write article content."""
+
+    math_req: str = TYPST_MATH_USAGE
+    """The req of the write article content."""
+    tei_endpoint: Optional[str] = None
+
+    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
+
+        cm = CitationManager()
+        await self.search_database(article, article_outline, chap, sec, subsec, cm)
+
+        raw_paras = await self.write_raw(article, article_outline, chap, sec, subsec, cm)
+        r_print(raw_paras)
+
+        while not await confirm("Accept this version and continue?").ask_async():
+            if inst := await text("Search for more refs for additional spec.").ask_async():
+                await self.search_database(article, article_outline, chap, sec, subsec, cm, extra_instruction=inst)
+
+            if instruction := await text("Enter the instructions to improve").ask_async():
+                raw_paras = await self.write_raw(article, article_outline, chap, sec, subsec, cm, instruction)
+            if edt := await text("Edit", default=raw_paras).ask_async():
+                raw_paras = edt
+
+            raw_paras = fix_misplaced_labels(raw_paras)
+            raw_paras = convert_all_inline_tex(raw_paras)
+            raw_paras = convert_all_block_tex(raw_paras)
+
+            r_print(raw_paras)
+
+        return await self.extract_new_subsec(subsec, raw_paras, cm)
+
+    async def _inner(
+        self,
+        article: Article,
+        article_outline: ArticleOutline,
+        chap: ArticleChapter,
+        sec: ArticleSection,
+        subsec: ArticleSubsection,
+    ) -> ArticleSubsection:
+        cm = CitationManager()
+
+        await self.search_database(article, article_outline, chap, sec, subsec, cm)
+
+        raw_paras = await self.write_raw(article, article_outline, chap, sec, subsec, cm)
+
+        raw_paras = "\n".join(p for p in raw_paras.splitlines() if p and not p.endswith("**") and not p.startswith("#"))
+
+        raw_paras = fix_misplaced_labels(raw_paras)
+        raw_paras = convert_all_inline_tex(raw_paras)
+        raw_paras = convert_all_block_tex(raw_paras)
+
+        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 construct a new `{ArticleSubsection.__class__.__name__}`,"
+                f"Do not attempt to change the original content, your job is ONLY content extraction",
+                **self.extractor_model,
+            ),
+            "Failed to propose new subsection.",
+        )
+
+        for p in new_subsec.paragraphs:
+            p.content = cm.apply(p.content)
+            p.description = cm.apply(p.description)
+        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.cite_req}\n{self.math_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 thesis.\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.\n"
+            f"No extra explanation is allowed."
+        )
+
+    async def search_database(
+        self,
+        article: Article,
+        article_outline: ArticleOutline,
+        chap: ArticleChapter,
+        sec: ArticleSection,
+        subsec: ArticleSubsection,
+        cm: CitationManager,
+        extra_instruction: str = "",
+    ) -> None:
+        """Search database for related references."""
+        search_req = (
+            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}"
+        )
+
+        await self.clued_search(
+            search_req,
+            cm,
+            refinery_kwargs=self.query_model,
+            expand_multiplier=self.search_increment_multiplier,
+            base_accepted=self.ref_limit,
+            result_per_query=self.result_per_query,
+            similarity_threshold=self.threshold,
+            tei_endpoint=self.tei_endpoint,
+        )
+
+
+class ArticleConsultRAG(Action, AdvancedRAG):
+    """Write an article based on the provided outline."""
+
+    ctx_override: ClassVar[bool] = True
+    output_key: str = "consult_count"
+    search_increment_multiplier: float = 1.6
+    """The multiplier to increase the limit of references to retrieve per query."""
+    ref_limit: int = 26
+    """The final limit of references."""
+    ref_per_q: int = 13
+    """The limit of references to retrieve per query."""
+    similarity_threshold: float = 0.62
+    """The similarity threshold of references to retrieve."""
+    ref_q_model: ChooseKwargs = Field(default_factory=ChooseKwargs)
+    """The model to use for refining query."""
+    req: str = TYPST_CITE_USAGE
+    """The request for the rag model."""
+    tei_endpoint: Optional[str] = None
+
+    @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, fix_misplaced_labels
+
+        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()
+
+            req = convert_to_block_formula(req)
+            req = convert_to_inline_formula(req)
+
+            await self.clued_search(
+                req,
+                cm,
+                refinery_kwargs=self.ref_q_model,
+                expand_multiplier=self.search_increment_multiplier,
+                base_accepted=self.ref_limit,
+                result_per_query=self.ref_per_q,
+                similarity_threshold=self.similarity_threshold,
+                tei_endpoint=self.tei_endpoint,
+            )
+
+            ret = await self.aask(f"{cm.as_prompt()}\n{self.req}\n{req}")
+
+            ret = fix_misplaced_labels(ret)
+            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):
+    """Write an article based on the provided outline.
+
+    This class inherits from `Action`, `RAG`, and `Censor` to provide capabilities for writing and refining articles
+    using Retrieval-Augmented Generation (RAG) techniques. It processes an article outline, enhances subsections by
+    searching for related references, and applies censoring rules to ensure compliance with the provided ruleset.
+
+    Attributes:
+        output_key (str): The key used to store the output of the action.
+        ruleset (Optional[RuleSet]): The ruleset to be used for censoring the article.
+    """
+
+    output_key: str = "rag_tweaked_article"
+    """The key used to store the output of the action."""
+
+    ruleset: Optional[RuleSet] = None
+    """The ruleset to be used for censoring the article."""
+
+    ref_limit: int = 30
+    """The limit of references to be retrieved"""
+
+    async def _execute(
+        self,
+        article: Article,
+        collection_name: str = "article_essence",
+        twk_rag_ruleset: Optional[RuleSet] = None,
+        parallel: bool = False,
+        **cxt,
+    ) -> Article:
+        """Write an article based on the provided outline.
+
+        This method processes the article outline, either in parallel or sequentially, by enhancing each subsection
+        with relevant references and applying censoring rules.
+
+        Args:
+            article (Article): The article to be processed.
+            collection_name (str): The name of the collection to view for processing.
+            twk_rag_ruleset (Optional[RuleSet]): The ruleset to apply for censoring. If not provided, the class's ruleset is used.
+            parallel (bool): If True, process subsections in parallel. Otherwise, process them sequentially.
+            **cxt: Additional context parameters.
+
+        Returns:
+            Article: The processed article with enhanced subsections and applied censoring rules.
+        """
+        self.view(collection_name)
+
+        if parallel:
+            await gather(
+                *[
+                    self._inner(article, subsec, ok(twk_rag_ruleset or self.ruleset, "No ruleset provided!"))
+                    for _, __, subsec in article.iter_subsections()
+                ],
+                return_exceptions=True,
+            )
+        else:
+            for _, __, subsec in article.iter_subsections():
+                await self._inner(article, subsec, ok(twk_rag_ruleset or self.ruleset, "No ruleset provided!"))
+        return article
+
+    async def _inner(self, article: Article, subsec: ArticleSubsection, ruleset: RuleSet) -> None:
+        """Enhance a subsection of the article with references and apply censoring rules.
+
+        This method refines the query for the subsection, retrieves related references, and applies censoring rules
+        to the subsection's paragraphs.
+
+        Args:
+            article (Article): The article containing the subsection.
+            subsec (ArticleSubsection): The subsection to be enhanced.
+            ruleset (RuleSet): The ruleset to apply for censoring.
+
+        Returns:
+            None
+        """
+        refind_q = ok(
+            await self.arefined_query(
+                f"{article.referenced.as_prompt()}\n# Subsection requiring reference enhancement\n{subsec.display()}\n"
+            )
+        )
+        await self.censor_obj_inplace(
+            subsec,
+            ruleset=ruleset,
+            reference=f"{'\n\n'.join(d.display() for d in await self.aretrieve(refind_q, document_model=ArticleEssence, max_accepted=self.ref_limit))}\n\n"
+            f"You can use Reference above to rewrite the `{subsec.__class__.__name__}`.\n"
+            f"You should Always use `{subsec.language}` as written language, "
+            f"which is the original language of the `{subsec.title}`. "
+            f"since rewrite a `{subsec.__class__.__name__}` in a different language is usually a bad choice",
+        )
+
+
+class ChunkArticle(Action):
+    """Chunk an article into smaller 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."""
+    max_overlapping_rate: Optional[float] = None
+    """The maximum overlapping rate between chunks."""
+
+    async def _execute(
+        self,
+        article_path: str | Path,
+        bib_manager: BibManager,
+        max_chunk_size: Optional[int] = None,
+        max_overlapping_rate: Optional[float] = None,
+        **_,
+    ) -> List[ArticleChunk]:
+        return ArticleChunk.from_file(
+            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!"
+            ),
+        )

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

@@ -0,0 +1,248 @@
+"""Dump the finalized output to a file."""
+
+from pathlib import Path
+from typing import Any, Iterable, List, Mapping, Optional, Self, Sequence, Type
+
+from fabricatio.capabilities.persist import PersistentAble
+from fabricatio.fs import dump_text
+from fabricatio.journal import logger
+from fabricatio.models.action import Action
+from fabricatio.models.generic import FinalizedDumpAble, FromMapping, FromSequence
+from fabricatio.models.task import Task
+from fabricatio.models.usages import LLMUsage
+from fabricatio.rust import TEMPLATE_MANAGER
+from fabricatio.utils import ok
+
+
+class DumpFinalizedOutput(Action, LLMUsage):
+    """Dump the finalized output to a file."""
+
+    output_key: str = "dump_path"
+    dump_path: Optional[str] = None
+
+    async def _execute(
+        self,
+        to_dump: FinalizedDumpAble,
+        task_input: Optional[Task] = None,
+        dump_path: Optional[str | Path] = None,
+        **_,
+    ) -> str:
+        dump_path = Path(
+            dump_path
+            or self.dump_path
+            or ok(
+                await self.awhich_pathstr(
+                    f"{ok(task_input, 'Neither `task_input` and `dump_path` is provided.').briefing}\n\nExtract a single path of the file, to which I will dump the data."
+                ),
+                "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()
+
+
+class RenderedDump(Action, LLMUsage):
+    """Render the data to a file."""
+
+    output_key: str = "dump_path"
+    dump_path: Optional[str] = None
+
+    template_name: str
+    """The template name to render the data."""
+
+    async def _execute(
+        self,
+        to_dump: FinalizedDumpAble,
+        task_input: Optional[Task] = None,
+        dump_path: Optional[str | Path] = None,
+        **_,
+    ) -> str:
+        dump_path = Path(
+            dump_path
+            or self.dump_path
+            or ok(
+                await self.awhich_pathstr(
+                    f"{ok(task_input, 'Neither `task_input` and `dump_path` is provided.').briefing}\n\nExtract a single path of the file, to which I will dump the data."
+                ),
+                "Could not find the path of file to dump the data.",
+            )
+        )
+
+        logger.info(f"Saving output to {dump_path.as_posix()}")
+        dump_text(
+            dump_path,
+            TEMPLATE_MANAGER.render_template(
+                self.template_name, {to_dump.__class__.__name__: to_dump.finalized_dump()}
+            ),
+        )
+
+        return dump_path.as_posix()
+
+
+class PersistentAll(Action, LLMUsage):
+    """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,
+        task_input: Optional[Task] = None,
+        persist_dir: Optional[str | Path] = None,
+        **cxt,
+    ) -> int:
+        persist_dir = Path(
+            persist_dir
+            or self.persist_dir
+            or ok(
+                await self.awhich_pathstr(
+                    f"{ok(task_input, 'Neither `task_input` and `dump_path` is provided.').briefing}\n\nExtract a single path of the file, to which I will persist the data."
+                ),
+                "Can not find the path of file to persist the data.",
+            )
+        )
+
+        count = 0
+        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)
+                    count += 1
+        logger.info(f"Persisted {count} objects to {persist_dir}")
+        return count
+
+
+class RetrieveFromPersistent[T: PersistentAble](Action):
+    """Retrieve the object from the persistent file."""
+
+    output_key: str = "retrieved_obj"
+    """Retrieve the object from the persistent file."""
+    load_path: str
+    """The path of the persistent file or directory contains multiple file."""
+    retrieve_cls: Type[T]
+    """The class of the object to retrieve."""
+
+    async def _execute(self, /, **_) -> Optional[T | List[T]]:
+        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 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]:
+        logger.info(f"Retrieve latest `{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_latest_persistent(self.load_path)
+        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.
+
+    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
+
+
+class Forward(Action, FromMapping, FromSequence):
+    """Forward the object from the context to the output."""
+
+    output_key: str = "forwarded"
+    """Gather the objects from the context as a list."""
+    original: str
+
+    async def _execute(self, *_: Any, **cxt) -> Any:
+        source = cxt.get(self.original)
+        if source is None:
+            logger.warning(f"Original object {self.original} not found in the context")
+        return source
+
+    @classmethod
+    def from_sequence(cls, sequence: Sequence[str], *, original: str, **kwargs: Any) -> List[Self]:
+        """Create a list of `Forward` from the sequence."""
+        return [cls(original=original, output_key=o, **kwargs) for o in sequence]
+
+    @classmethod
+    def from_mapping(cls, mapping: Mapping[str, str | Sequence[str]], **kwargs: Any) -> List[Self]:
+        """Create a list of `Forward` from the mapping."""
+        actions = []
+        for original_key, output_val in mapping.items():
+            if isinstance(output_val, str):
+                actions.append(cls(original=original_key, output_key=output_val, **kwargs))
+            elif isinstance(output_val, Sequence):
+                actions.extend(cls(original=original_key, output_key=output_key, **kwargs) for output_key in output_val)
+            else:
+                logger.warning(
+                    f"Invalid type for output key value in mapping: {type(output_val)} for original key {original_key}. Expected str or Sequence[str]."
+                )
+        return actions