waldiez 0.4.7__py3-none-any.whl → 0.4.9__py3-none-any.whl

waldiez/exporting/flow/execution_generator.py

@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Generates the main() and call_main() functions."""
+
+# pylint: disable=no-self-use,unused-argument
+
+from ..core import get_comment
+from .utils.common import RETURN_TYPE_HINT, main_doc_string
+
+
+class ExecutionGenerator:
+    """Generate the main function and its calling block for flow exporter."""
+
+    @staticmethod
+    def generate(
+        content: str,
+        is_async: bool,
+        for_notebook: bool,
+        cache_seed: int | None,
+        after_run: str,
+    ) -> str:
+        """Generate the complete flow script content.
+
+        Parameters
+        ----------
+        content : str
+            The content of the chats to be included in the main function.
+        is_async : bool
+            Whether to generate async content.
+        for_notebook : bool
+            Whether the export is intended for a notebook environment.
+        cache_seed : str | int | None
+            The cache seed to use for flow chat if any.
+        after_run : str, optional
+            Additional content to add after the main chat execution,
+            by default ""
+
+        Returns
+        -------
+        str
+            The complete flow script content.
+        """
+        main_function = ExecutionGenerator.generate_main_function(
+            content=content,
+            is_async=is_async,
+            cache_seed=cache_seed,
+            after_run=after_run,
+            for_notebook=for_notebook,
+        )
+        call_main_function = ExecutionGenerator.generate_call_main_function(
+            is_async=is_async,
+            for_notebook=for_notebook,
+        )
+        if not for_notebook:
+            execution_block = ExecutionGenerator.generate_execution_block(
+                is_async=is_async,
+            )
+        else:
+            execution_block = ""
+        return (
+            "\n".join([main_function, call_main_function, execution_block])
+            + "\n"
+        )
+
+    @staticmethod
+    def generate_main_function(
+        content: str,
+        is_async: bool,
+        cache_seed: int | None,
+        after_run: str,
+        for_notebook: bool,
+    ) -> str:
+        """Generate the main function for the flow script.
+
+        Parameters
+        ----------
+        content : str
+            The content of the chats to be included in the main function.
+        is_async : bool
+            Whether to generate async content
+        cache_seed : str | int | None
+            The cache seed to use for flow chat if any
+        after_run : str
+            Additional content to add after the main chat execution.
+        for_notebook : bool
+            Whether the export is intended for a notebook environment.
+
+        Returns
+        -------
+        str
+            The complete main function content.
+        """
+        if content.startswith("\n"):
+            content = content[1:]
+        flow_content = "\n\n"
+        comment = get_comment(
+            "Start chatting",
+            for_notebook=for_notebook,
+        )
+        flow_content += f"{comment}\n"
+        if is_async:
+            flow_content += "async "
+
+        flow_content += f"def main() -> {RETURN_TYPE_HINT}:\n"
+        flow_content += f"    {main_doc_string()}\n"
+        space = "    "
+        if cache_seed is not None:
+            flow_content += (
+                f"    with Cache.disk(cache_seed={cache_seed}"
+                ") as cache:  # pyright: ignore\n"
+            )
+            space = f"{space}    "
+        flow_content += f"{content}" + "\n"
+        if is_async:
+            flow_content += f"{space}await stop_logging()"
+        else:
+            flow_content += f"{space}stop_logging()"
+        flow_content += "\n"
+        if after_run:
+            flow_content += after_run + "\n"
+        if cache_seed is not None:
+            space = space[4:]
+        flow_content += f"{space}return results\n"
+        return flow_content
+
+    @staticmethod
+    def generate_call_main_function(is_async: bool, for_notebook: bool) -> str:
+        """Generate the call_main function for the flow script.
+
+        Parameters
+        ----------
+        is_async : bool
+            Whether to generate async content
+        for_notebook : bool
+            Whether the export is intended for a notebook environment.
+
+        Returns
+        -------
+        str
+            The complete call_main function content.
+        """
+        content = "\n"
+        if for_notebook:
+            if is_async:
+                return "# %%\nawait main()\n"
+            return "# %%\nmain()\n"
+        if is_async:
+            content += "async def call_main() -> None:\n"
+        else:
+            content += "def call_main() -> None:\n"
+        content += '    """Run the main function and print the results."""\n'
+        content += f"    results: {RETURN_TYPE_HINT} = "
+        if is_async:
+            content += "await "
+        content += "main()\n"
+        content += "    if isinstance(results, dict):\n"
+        content += "        # order by key\n"
+        content += "        ordered_results = dict(sorted(results.items()))\n"
+        content += "        for _, result in ordered_results.items():\n"
+        content += "            pprint(asdict(result))\n"
+        content += "    else:\n"
+        content += "        if not isinstance(results, list):\n"
+        content += "            results = [results]\n"
+        content += "        for result in results:\n"
+        content += "            pprint(asdict(result))\n"
+        content += "\n"
+        return content
+
+    @staticmethod
+    def generate_execution_block(is_async: bool) -> str:
+        """Generate the execution block for the main function.
+
+        Parameters
+        ----------
+        is_async : bool
+            Whether to generate async content
+
+        Returns
+        -------
+        str
+            The complete if __name__ == "__main__": block content
+        """
+        comment = get_comment(
+            "Let's go!",
+            for_notebook=False,
+        )
+        content = 'if __name__ == "__main__":\n'
+        content += f"    {comment}"
+        if is_async:
+            content += "    anyio.run(call_main)\n"
+        else:
+            content += "    call_main()\n"
+        return content

waldiez/exporting/flow/exporter.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Flow exporter."""
+
+from pathlib import Path
+from typing import Any, Optional
+
+from waldiez.models import Waldiez
+
+from ..core import Exporter, ExporterContext
+from ..core.extras import FlowExtras
+from .file_generator import FileGenerator
+from .orchestrator import ExportOrchestrator
+
+
+class FlowExporter(Exporter[FlowExtras]):
+    """Flow exporter."""
+
+    def __init__(
+        self,
+        waldiez: Waldiez,
+        output_dir: Path | None,
+        for_notebook: bool,
+        context: Optional[ExporterContext] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the chats exporter.
+
+        Parameters
+        ----------
+        waldiez : Waldiez
+            The Waldiez instance containing the flow data.
+        output_dir : Path
+            The directory where the exported flow will be saved.
+        for_notebook : bool
+            Whether the export is intended for a notebook environment.
+        context : Optional[ExporterContext], optional
+            Exporter context with dependencies, by default None
+        **kwargs : Any
+            Additional keyword arguments for the exporter.
+        """
+        super().__init__(context, **kwargs)
+
+        self.waldiez = waldiez
+        self.output_dir = Path(output_dir) if output_dir is not None else None
+        self.flow_config = self.context.get_config(
+            name=waldiez.name,
+            description=waldiez.description,
+            requirements=waldiez.requirements or [],
+            tags=waldiez.tags or [],
+            output_extension="ipynb" if for_notebook else "py",
+            is_async=waldiez.is_async,
+            output_directory=str(self.output_dir) if self.output_dir else None,
+            cache_seed=waldiez.cache_seed,
+        )
+        self._extras = self._generate_extras()
+
+    @property
+    def extras(self) -> FlowExtras:
+        """Get the flow exporter extras.
+
+        Returns
+        -------
+        dict[str, Any]
+            The extras dictionary containing additional
+            information for the flow exporter.
+        """
+        return self._extras
+
+    def _generate_extras(self) -> FlowExtras:
+        """Generate the extras for the flow exporter.
+
+        Returns
+        -------
+        BaseExtras
+            An instance of BaseExtras containing the generated content.
+        """
+        extras = FlowExtras(
+            instance_id=self.waldiez.id,
+            flow_name=self.waldiez.name,
+            description=self.waldiez.description or "",
+            config=self.flow_config,
+        )
+        return extras
+
+    def generate_main_content(self) -> str:
+        """Generate the main content of the export.
+
+        Returns
+        -------
+        str
+            The final executable script or notebook content.
+        """
+        orchestrator = ExportOrchestrator(
+            waldiez=self.waldiez,
+            context=self.context,
+        )
+        merged_result = orchestrator.orchestrate()
+        after_run = orchestrator.get_after_run_content()
+        generator = FileGenerator(
+            context=self.context,
+        )
+        return generator.generate(
+            merged_result=merged_result,
+            is_async=self.waldiez.is_async,
+            after_run=after_run,
+        )

waldiez/exporting/flow/factory.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Factory function for creating a FlowExporter instance."""
+
+from pathlib import Path
+from typing import Any, Optional
+
+from waldiez.logger import WaldiezLogger
+from waldiez.models import Waldiez
+
+from ..core import (
+    DefaultPathResolver,
+    DefaultSerializer,
+    ExportConfig,
+    ExporterContext,
+)
+from .exporter import FlowExporter
+
+
+def create_flow_exporter(
+    waldiez: Waldiez,
+    output_dir: Path | None,
+    for_notebook: bool,
+    context: Optional[ExporterContext] = None,
+    **kwargs: Any,
+) -> FlowExporter:
+    """Create a flow exporter.
+
+    Parameters
+    ----------
+    waldiez : Waldiez
+        The Waldiez instance containing the flow data.
+    output_dir : Path
+        The directory where the exported flow will be saved.
+    for_notebook : bool
+        Whether the export is intended for a notebook environment.
+    context : Optional[ExporterContext], optional
+        Exporter context with dependencies, by default None
+    **kwargs : Any
+        Additional keyword arguments for the exporter.
+
+    Returns
+    -------
+    ChatsExporter
+        The created chats exporter.
+    """
+    if context is None:
+        config = ExportConfig(
+            name=waldiez.name,
+            description=waldiez.description or "",
+            tags=waldiez.tags or [],
+            requirements=waldiez.requirements or [],
+            output_extension="ipynb" if for_notebook else "py",
+            is_async=waldiez.is_async,
+            output_directory=output_dir,
+            cache_seed=waldiez.cache_seed,
+        )
+        context = ExporterContext(
+            config=config,
+            serializer=DefaultSerializer(),
+            path_resolver=DefaultPathResolver(),
+            logger=WaldiezLogger(),
+        )
+    else:
+        if not context.config:  # pragma: no cover
+            context.config = ExportConfig(
+                name=waldiez.name,
+                description=waldiez.description or "",
+                tags=waldiez.tags or [],
+                requirements=waldiez.requirements or [],
+                output_extension="ipynb" if for_notebook else "py",
+                is_async=waldiez.is_async,
+                output_directory=output_dir,
+                cache_seed=waldiez.cache_seed,
+            )
+        else:
+            context.config.update(
+                name=waldiez.name,
+                description=waldiez.description or "",
+                tags=waldiez.tags or [],
+                requirements=waldiez.requirements or [],
+                output_extension="ipynb" if for_notebook else "py",
+                is_async=waldiez.is_async,
+                output_directory=output_dir,
+                cache_seed=waldiez.cache_seed,
+            )
+
+    return FlowExporter(
+        waldiez=waldiez,
+        output_dir=output_dir,
+        for_notebook=for_notebook,
+        context=context,
+        **kwargs,
+    )

waldiez/exporting/flow/file_generator.py

@@ -0,0 +1,214 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Generate the whole folw content."""
+
+from typing import Any
+
+from ..core import (
+    ContentGenerator,
+    ExporterContentError,
+    ExporterContext,
+    ExportPosition,
+    ExportResult,
+    PositionedContent,
+    get_comment,
+)
+from .execution_generator import ExecutionGenerator
+from .utils.common import generate_header
+
+
+class FileGenerator(ContentGenerator):
+    """Generate the complete flow notebook content."""
+
+    def __init__(
+        self,
+        context: ExporterContext,
+    ) -> None:
+        """Initialize the notebook generator.
+
+        Parameters
+        ----------
+        context : ExporterContext
+            The exporter context containing dependencies.
+        """
+        self.context = context
+        self.config = context.get_config()
+
+    # pylint: disable=too-many-locals
+    def generate(
+        self,
+        merged_result: ExportResult,
+        is_async: bool,
+        after_run: str,
+        **kwargs: Any,
+    ) -> str:
+        """Generate the complete flow notebook content.
+
+        Parameters
+        ----------
+        merged_result : ExportResult
+            The merged export result containing all content.
+        is_async : bool
+            Whether to generate async conten
+        after_run : str
+            Additional content to add after the main flow execution.
+        **kwargs : Any
+            Additional keyword arguments for the generator.
+
+        Returns
+        -------
+        str
+            The complete flow notebook content.
+
+        Raises
+        ------
+        ExporterContentError
+            If there is no content to export.
+        """
+        # 1. Generate header
+        header = self.get_header(merged_result)
+
+        # 2. Generate imports
+        imports_section = merged_result.get_content_by_position(
+            ExportPosition.IMPORTS
+        )
+
+        # 3. Generate content sections
+        tools_section = merged_result.get_content_by_position(
+            ExportPosition.TOOLS
+        )
+        models_section = merged_result.get_content_by_position(
+            ExportPosition.MODELS
+        )
+        agents_section = merged_result.get_content_by_position(
+            ExportPosition.AGENTS,
+            # Skip agent arguments (should already be there)
+            skip_agent_arguments=True,
+        )
+        chats_content = merged_result.get_content_by_position(
+            ExportPosition.CHATS
+        )
+        if not chats_content:
+            raise ExporterContentError(
+                "No content to export. Please ensure that the flow has chats."
+            )
+        after_chats = merged_result.get_content_by_position(
+            ExportPosition.BOTTOM
+        )
+
+        main, call_main, execution_block = self._get_execution_content(
+            chats_content=chats_content,
+            is_async=is_async,
+            after_run=after_run,
+            for_notebook=self.config.for_notebook,
+        )
+
+        # 5. Combine everything
+        everything: list[str] = [header]
+        if imports_section:
+            comment = get_comment(
+                "Imports",
+                for_notebook=self.config.for_notebook,
+            )
+            everything.append(comment)
+            everything.append(
+                "\n".join([entry.content for entry in imports_section])
+            )
+        if tools_section:
+            comment = get_comment(
+                "Tools",
+                for_notebook=self.config.for_notebook,
+            )
+            everything.append(comment)
+            everything.append(
+                "\n".join([entry.content for entry in tools_section]) + "\n"
+            )
+        if models_section:
+            comment = get_comment(
+                "Models",
+                for_notebook=self.config.for_notebook,
+            )
+            everything.append(comment)
+            everything.append(
+                "\n\n".join([entry.content for entry in models_section]) + "\n"
+            )
+        if agents_section:
+            comment = get_comment(
+                "Agents",
+                for_notebook=self.config.for_notebook,
+            )
+            if self.config.for_notebook:
+                comment += "# pyright: reportUnnecessaryIsInstance=false\n"
+            everything.append(comment)
+            everything.append(
+                "\n\n".join([entry.content for entry in agents_section]) + "\n"
+            )
+        everything.append(main)
+        if after_chats:
+            everything.append(
+                "\n".join([entry.content for entry in after_chats])
+            )
+        everything.append(call_main)
+        if execution_block:
+            everything.append(execution_block)
+
+        return "\n".join(everything)
+
+    def _get_execution_content(
+        self,
+        chats_content: list[PositionedContent],
+        is_async: bool,
+        for_notebook: bool,
+        after_run: str,
+    ) -> tuple[str, str, str]:
+        cache_seed = (
+            self.context.config.cache_seed if self.context.config else None
+        )
+        execution_gen = ExecutionGenerator()
+        chat_contents = "\n".join(chat.content for chat in chats_content)
+        main = execution_gen.generate_main_function(
+            content=chat_contents,
+            is_async=is_async,
+            for_notebook=for_notebook,
+            cache_seed=cache_seed,
+            after_run=after_run,
+        )
+        call_main = execution_gen.generate_call_main_function(
+            is_async=is_async,
+            for_notebook=for_notebook,
+        )
+        execution_block = (
+            execution_gen.generate_execution_block(
+                is_async=is_async,
+            )
+            if not for_notebook
+            else ""
+        )
+        return main, call_main, execution_block
+
+    def get_header(self, merged_result: ExportResult) -> str:
+        """Get or generate the header for the script.
+
+        Parameters
+        ----------
+        merged_result : ExportResult
+            The merged export result containing all content.
+
+        Returns
+        -------
+        str
+            The header content.
+        """
+        from_result = merged_result.get_content_by_position(ExportPosition.TOP)
+        if not from_result:
+            return generate_header(
+                name=self.config.name,
+                description=self.config.description,
+                requirements=self.config.requirements,
+                tags=self.config.tags,
+                for_notebook=self.config.for_notebook,
+            )
+        header_string = "\n".join(content.content for content in from_result)
+        while not header_string.endswith("\n\n"):
+            header_string += "\n"
+        return header_string