waldiez 0.5.6__py3-none-any.whl → 0.5.8__py3-none-any.whl

waldiez/exporting/chats/utils/single.py

@@ -4,7 +4,7 @@
 # pylint: disable=line-too-long
 """Utilities for exporting a single chat in a flow."""
 
-from typing import Any, Callable, Optional
+from typing import Any, Callable
 
 from waldiez.models import (
     WaldiezAgent,
@@ -57,42 +57,6 @@ def export_single_chat(
     -------
     tuple[str, str]
         The chat string and additional methods string if any
-
-    Example
-    -------
-    ```python
-    >>> from waldiez.models import WaldiezAgent, WaldiezChat, WaldiezChatData, WaldiezChatMessage
-    >>> chat = WaldiezChat(
-    ...     id="wc-1",
-    ...     name="chat1",
-    ...     description="A chat between two agents.",
-    ...     tags=["chat", "chat1"],
-    ...     requirements=[],
-    ...     data=WaldiezChatData(
-    ...         sender="wa-1",
-    ...         recipient="wa-2",
-    ...         message=WaldiezChatMessage(
-    ...             type="string",
-    ...             content="Hello, how are you?",
-    ...         ),
-    ...     ),
-    ... )
-    >>> agent_names = {"wa-1": "agent1", "wa-2": "agent2"}
-    >>> chat_names = {"wc-1": "chat1"}
-    >>> export_single_chat_string(
-    ...     sender=agent1,
-    ...     recipient=agent2,
-    ...     chat=chat,
-    ...     agent_names=agent_names,
-    ...     chat_names=chat_names,
-    ...     tabs=0,
-    ... )
-    agent1.initiate_chat(
-        agent2,
-        message="Hello, how are you?",
-        cache=cache,
-    )
-    ```
     """
     tab = " " * tab_length * tabs if tabs > 0 else ""
     chat_args = chat.get_chat_args(for_queue=False, sender=sender)
@@ -280,7 +244,6 @@ def get_chat_message(
         The message argument and additional methods string if any.
     """
     additional_methods_string = ""
-    method_content: Optional[str] = None
     if (
         sender.is_rag_user
         and isinstance(sender, WaldiezRagUserProxy)

waldiez/exporting/core/context.py

@@ -18,11 +18,11 @@ from .types import ExportConfig
 class ExporterContext:
     """Context object containing common exporter dependencies."""
 
-    serializer: Optional[Serializer] = None
-    path_resolver: Optional[PathResolver] = None
-    validator: Optional[Validator] = None
-    config: Optional[ExportConfig] = None
-    logger: Optional[ExportingLogger] = None
+    serializer: Serializer | None = None
+    path_resolver: PathResolver | None = None
+    validator: Validator | None = None
+    config: ExportConfig | None = None
+    logger: ExportingLogger | None = None
 
     def get_serializer(self) -> Serializer:
         """Get serializer or raise if not set.
@@ -46,34 +46,34 @@ class ExporterContext:
 
     def get_config(
         self,
-        name: Optional[str] = None,
-        description: Optional[str] = None,
-        requirements: Optional[list[str]] = None,
-        tags: Optional[list[str]] = None,
-        output_extension: Optional[str] = None,
+        name: str | None = None,
+        description: str | None = None,
+        requirements: list[str] | None = None,
+        tags: list[str] | None = None,
+        output_extension: str | None = None,
         is_async: bool = False,
-        output_directory: Optional[str] = None,
-        cache_seed: Optional[int] = None,
+        output_directory: str | None = None,
+        cache_seed: int | None = None,
     ) -> ExportConfig:
         """Get export config or return default.
 
         Parameters
         ----------
-        name : Optional[str], optional
+        name : str], optional
             The name of the export, by default None
-        description : Optional[str], optional
+        description : str], optional
             A brief description of the export, by default None
-        requirements : Optional[list[str]], optional
+        requirements : list[str]], optional
             A list of requirements for the export, by default None
-        tags : Optional[list[str]], optional
+        tags : list[str]], optional
             A list of tags associated with the export, by default None
-        output_extension : Optional[str], optional
+        output_extension : str], optional
             The file extension for the output, by default None
         is_async : bool, optional
             Whether the export is asynchronous, by default False
-        output_directory : Optional[str], optional
+        output_directory : str], optional
             The directory where the output will be saved, by default None
-        cache_seed : Optional[int], optional
+        cache_seed : int], optional
             The seed for caching, by default None
 
         Returns
@@ -124,6 +124,7 @@ class ExporterContext:
 
 
 # pylint: disable=too-few-public-methods
+# noinspection PyUnresolvedReferences,PyTypeChecker
 class DefaultExporterContext(ExporterContext):
     """Singleton context for exporters.
 
@@ -164,11 +165,11 @@ class DefaultExporterContext(ExporterContext):
 
     def __init__(
         self,
-        serializer: Optional[Serializer] = None,
-        validator: Optional[Validator] = None,
-        path_resolver: Optional[PathResolver] = None,
-        logger: Optional[ExportingLogger] = None,
-        config: Optional[ExportConfig] = None,
+        serializer: Serializer | None = None,
+        validator: Validator | None = None,
+        path_resolver: PathResolver | None = None,
+        logger: ExportingLogger | None = None,
+        config: ExportConfig | None = None,
     ) -> None:
         if hasattr(self, "_initialized"):
             return
@@ -183,16 +184,16 @@ class DefaultExporterContext(ExporterContext):
 
 
 def get_default_exporter_context(
-    config: Optional[ExportConfig] = None,
-    logger: Optional[ExportingLogger] = None,
+    config: ExportConfig | None = None,
+    logger: ExportingLogger | None = None,
 ) -> ExporterContext:
     """Get the default exporter context.
 
     Parameters
     ----------
-    config : Optional[ExportConfig], optional
+    config : ExportConfig | None, optional
         The export configuration, by default None
-    logger : Optional[ExportingLogger], optional
+    logger : ExportingLogger | None, optional
         The logger instance, by default None
 
     Returns
@@ -209,25 +210,25 @@ def get_default_exporter_context(
 
 
 def create_exporter_context(
-    serializer: Optional[Serializer] = None,
-    validator: Optional[Validator] = None,
-    path_resolver: Optional[PathResolver] = None,
-    config: Optional[ExportConfig] = None,
-    logger: Optional[ExportingLogger] = None,
+    serializer: Serializer | None = None,
+    validator: Validator | None = None,
+    path_resolver: PathResolver | None = None,
+    config: ExportConfig | None = None,
+    logger: ExportingLogger | None = None,
 ) -> ExporterContext:
     """Create an exporter context with the given components.
 
     Parameters
     ----------
-    serializer : Optional[Serializer], optional
+    serializer : Serializer | None, optional
         The serializer component, by default None
-    path_resolver : Optional[PathResolver], optional
+    path_resolver : PathResolver | None, optional
         The path resolver component, by default None
-    validator : Optional[Validator], optional
+    validator : Validator | None, optional
         The validator component, by default None
-    config : Optional[ExportConfig], optional
+    config : ExportConfig | None, optional
         The export configuration, by default None
-    logger : Optional[ExportingLogger], optional
+    logger : ExportingLogger | None, optional
         The logger instance, by default None
 
     Returns

waldiez/exporting/core/exporter.py

@@ -90,12 +90,12 @@ class Exporter(abc.ABC, Generic[Extras]):
         """
 
     @abc.abstractmethod
-    def generate_main_content(self) -> Optional[str]:
+    def generate_main_content(self) -> str | None:
         """Generate the main export content.
 
         Returns
         -------
-        Optional[str]
+        str | None
             The main content, or None if no content should be generated.
         """
 
@@ -182,8 +182,8 @@ class Exporter(abc.ABC, Generic[Extras]):
         content: str,
         position: ExportPosition,
         order: ContentOrder = ContentOrder.MAIN_CONTENT,
-        agent_id: Optional[str] = None,
-        agent_position: Optional[AgentPosition] = None,
+        agent_id: str | None = None,
+        agent_position: AgentPosition | None = None,
         skip_strip: bool | None = None,
         **metadata: Any,
     ) -> None:
@@ -195,11 +195,11 @@ class Exporter(abc.ABC, Generic[Extras]):
             The content to add.
         position : ExportPosition
             The position of the content.
-        order : int, optional
-            The order within the position, by default 0
-        agent_id : Optional[str], optional
+        order : ContentOrder, optional
+            The order within the position, by default ContentOrder.MAIN_CONTENT
+        agent_id : str | None, optional
             Agent ID for agent-relative positioning, by default None
-        agent_position : Optional[AgentPosition], optional
+        agent_position : AgentPosition | None, optional
             Position relative to agent, by default None
         skip_strip : bool | None, optional
             Whether to skip stripping whitespace, by default None
@@ -223,7 +223,7 @@ class Exporter(abc.ABC, Generic[Extras]):
         self,
         name: str,
         value: str,
-        description: Optional[str] = None,
+        description: str | None = None,
         required: bool = True,
     ) -> None:
         """Add environment variable.
@@ -234,7 +234,7 @@ class Exporter(abc.ABC, Generic[Extras]):
             The name of the environment variable.
         value : str
             The value of the environment variable.
-        description : Optional[str], optional
+        description : str | None, optional
             Description of the variable, by default None
         required : bool, optional
             Whether the variable is required, by default True

waldiez/exporting/core/exporters.py

@@ -12,6 +12,16 @@ from .types import Extras
 class SimpleExporter(Exporter[None]):
     """Simple exporter that doesn't use extras system."""
 
+    def generate_main_content(self) -> str | None:
+        """Generate main content for the exporter.
+
+        Returns
+        -------
+        str | None
+            The main content as a string or None if not applicable.
+        """
+        raise NotImplementedError("Subclasses must implement this method.")
+
     @property
     def extras(self) -> None:
         """Simple exporters don't have extras."""
@@ -24,6 +34,22 @@ class SimpleExporter(Exporter[None]):
 class ConfigurableExporter(Exporter[Extras]):
     """Exporter with configuration support."""
 
+    @property
+    def extras(self) -> Extras:
+        """Get the extras for this exporter.
+
+        Returns
+        -------
+        Extras
+            The extras associated with this exporter.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented in a subclass.
+        """
+        raise NotImplementedError("Subclasses must implement this method.")
+
     def __init__(self, config: Optional[dict[str, Any]] = None, **kwargs: Any):
         """Initialize with configuration.
 
@@ -37,6 +63,16 @@ class ConfigurableExporter(Exporter[Extras]):
         super().__init__(**kwargs)
         self._config = config or {}
 
+    def generate_main_content(self) -> str | None:
+        """Generate main content for the exporter.
+
+        Returns
+        -------
+        str | None
+            The main content as a string or None if not applicable.
+        """
+        raise NotImplementedError("Subclasses must implement this method.")
+
     def get_config_value(self, key: str, default: Any = None) -> Any:
         """Get a configuration value.
 

waldiez/exporting/core/extras/base.py

@@ -43,7 +43,7 @@ class BaseExtras(ExportContributor):
 
         Parameters
         ----------
-        arg : InstanceArgument
+        arg : InstanceArgument | str
             The argument to add.
         tabs : int, optional
             The number of tabs to indent the argument, by default 0.
@@ -76,7 +76,7 @@ class BaseExtras(ExportContributor):
 
         Parameters
         ----------
-        import_statement : str
+        import_statement : ImportStatement
             The import statement to add.
         """
         if import_statement and import_statement.statement.strip():

waldiez/exporting/core/extras/chat_extras.py

@@ -16,10 +16,12 @@ class ChatExtras(BaseExtras):
 
     Attributes
     ----------
-    chat_definition : str
-        The chat definition content.
+    chat_prerequisites : str
+        The chat prerequisites content.
     chat_initiation : str
         The chat initiation content.
+    chat_registration : str
+        The chat registration content.
     """
 
     chat_prerequisites: str = ""

waldiez/exporting/core/extras/path_resolver.py

@@ -3,7 +3,7 @@
 """Default path resolver for Waldiez items."""
 
 from pathlib import Path
-from typing import Optional, Union
+from typing import Union
 
 from ..protocols import PathResolver
 
@@ -45,7 +45,7 @@ class DefaultPathResolver(PathResolver):
         return DefaultPathResolver._check_local_path(path) is not None
 
     @staticmethod
-    def _check_local_path(string: str) -> Optional[Path]:
+    def _check_local_path(string: str) -> Path | None:
         """Check if a string is a local path.
 
         Parameters
@@ -55,10 +55,12 @@ class DefaultPathResolver(PathResolver):
 
         Returns
         -------
-        bool
-            True if the path is a local path.
+        Path | None
+            The resolved local path string (raw path format) or
+            None if it does not exist.
         """
         # pylint: disable=broad-exception-caught
+        # noinspection PyBroadException
         try:
             path = Path(string).resolve()
         except BaseException:  # pragma: no cover

waldiez/exporting/core/extras/serializer.py

@@ -14,6 +14,7 @@ from ..protocols import Serializer
 class DefaultSerializer(Serializer):
     """Default serializer for Waldiez items."""
 
+    # noinspection PyProtocol
     def serialize(self, obj: Any, **kwargs: Any) -> str:
         """Serialize an item to a formatted string.
 

waldiez/exporting/core/protocols.py

@@ -132,6 +132,12 @@ class ContentGenerator(Protocol):
         -------
         str
             The generated content.
+
+
+        Raises
+        ------
+        ExporterContentError
+            If exporting fails.
         """
 
 

waldiez/exporting/core/result.py

@@ -215,7 +215,7 @@ class ExportResult:
         self,
         content: str,
         position: ExportPosition = DEFAULT_EXPORT_POSITION,
-        order: Union[ContentOrder, int] = ContentOrder.MAIN_CONTENT,
+        order: ContentOrder | int = ContentOrder.MAIN_CONTENT,
         skip_strip: bool = False,
         agent_id: Optional[str] = None,
         agent_position: Optional[AgentPosition] = None,
@@ -229,15 +229,15 @@ class ExportResult:
             The content to add.
         position : ExportPosition, optional
             The position of the content, by default AGENTS
-        order : int, optional
+        order : ContentOrder | int, optional
             The order within the position, by default 0
         skip_strip : bool, optional
             Whether to skip stripping whitespace from content, by default False
-        agent_id : Optional[str], optional
+        agent_id : str | None, optional
             The agent ID if positioned relative to an agent, by default None
-        agent_position : Optional[AgentPosition], optional
+        agent_position : AgentPosition | None, optional
             The position relative to the agent, by default None
-        metadata : Optional[dict[str, Any]], optional
+        metadata : dict[str, Any] | None, optional
             Additional metadata for the content, by default None
         """
         order_value = order.value if isinstance(order, ContentOrder) else order
@@ -662,6 +662,7 @@ def merge_export_results(*results: ExportResult) -> ExportResult:
         return ExportResult()
 
     merged = ExportResult()
+    # noinspection PyTypeChecker
     for result in results:
         merged.merge_with(result)
 
@@ -681,7 +682,7 @@ def create_empty_result() -> ExportResult:
 
 def create_result_with_content(
     main_content: str,
-    imports: Optional[list[str]] = None,
+    imports: list[str] | None = None,
 ) -> ExportResult:
     """Create an ExportResult with basic content.
 
@@ -689,7 +690,7 @@ def create_result_with_content(
     ----------
     main_content : str
         The main content.
-    imports : Optional[list[str]], optional
+    imports : list[str], optional
         list of import statements, by default None
 
     Returns

waldiez/exporting/core/types.py

@@ -133,7 +133,7 @@ class EnvironmentVariable:
         tuple[str, str]
             The environment variable as a tuple.
         """
-        return (self.name, self.value)
+        return self.name, self.value
 
 
 # Instance Argument
@@ -311,7 +311,7 @@ class ExportConfig:
         valid_fields = {f.name for f in fields(cls)}
         output_extension = kwargs.pop("output_extension", "py")
         for_notebook = kwargs.pop("for_notebook", output_extension == "ipynb")
-        if for_notebook is True:
+        if for_notebook:
             output_extension = "ipynb"
         cache_seed = kwargs.pop("cache_seed", None)
         if cache_seed is not None and not isinstance(cache_seed, int):

waldiez/exporting/core/utils/llm_config.py

@@ -52,6 +52,7 @@ def get_agent_llm_config_arg(
     )
 
 
+# noinspection DuplicatedCode
 def _get_agent_llm_config_arg_as_arg(
     agent: WaldiezAgent,
     all_models: list[WaldiezModel],
@@ -85,6 +86,7 @@ def _get_agent_llm_config_arg_as_arg(
     return content
 
 
+# noinspection DuplicatedCode
 def _get_agent_llm_config_arg_as_dict(
     agent: WaldiezAgent,
     all_models: list[WaldiezModel],

waldiez/exporting/flow/execution_generator.py

@@ -115,11 +115,14 @@ class ExecutionGenerator:
                 "Callable[[BaseEvent], Coroutine[None, None, bool]]"
                 "] = None"
             )
-        return_type_hint = (
-            "AsyncRunResponseProtocol" if is_async else "RunResponseProtocol"
-        )
+        return_type_hint = "list[dict[str, Any]]"
         flow_content += f"def main({on_event_arg}) -> {return_type_hint}:\n"
-        flow_content += f"    {main_doc_string(is_async=is_async)}\n"
+        flow_content += f"    {main_doc_string()}\n"
+        if not is_async:
+            flow_content += "    results: list[RunResponseProtocol] | RunResponseProtocol = []\n"
+        else:
+            flow_content += "    results: list[AsyncRunResponseProtocol] | AsyncRunResponseProtocol = []\n"
+        flow_content += "    result_dicts: list[dict[str, Any]] = []\n"
         space = "    "
         if cache_seed is not None:
             flow_content += (
@@ -138,7 +141,7 @@ class ExecutionGenerator:
             flow_content += after_run + "\n"
         if cache_seed is not None:
             space = space[4:]
-        flow_content += f"{space}return results\n"
+        flow_content += f"{space}return result_dicts\n"
         return flow_content
 
     @staticmethod
@@ -163,42 +166,19 @@ class ExecutionGenerator:
             if is_async:
                 return "# %%\nawait main()\n"
             return "# %%\nmain()\n"
+        return_type_hint = "list[dict[str, Any]]"
         if is_async:
             content += "async def call_main() -> None:\n"
-            return_type_hint = "list[AsyncRunResponseProtocol]"
         else:
             content += "def call_main() -> None:\n"
-            return_type_hint = "list[RunResponseProtocol]"
         content += f'{tab}"""Run the main function and print the results."""\n'
         content += f"{tab}results: {return_type_hint} = "
         if is_async:
             content += "await "
         content += "main()\n"
-        content += f"{tab}results_dicts: list[dict[str, Any]] = []\n"
-        content += f"{tab}for result in results:\n"
-        if is_async:
-            content += f"{tab}{tab}result_summary = await result.summary\n"
-            content += f"{tab}{tab}result_messages = await result.messages\n"
-            content += f"{tab}{tab}result_cost = await result.cost\n"
-        else:
-            content += f"{tab}{tab}result_summary = result.summary\n"
-            content += f"{tab}{tab}result_messages = result.messages\n"
-            content += f"{tab}{tab}result_cost = result.cost\n"
-        content += f"{tab}{tab}cost: dict[str, Any] | None = None\n"
-        content += f"{tab}{tab}if result_cost:\n"
-        content += f'{tab}{tab}{tab}cost = result_cost.model_dump(mode="json", fallback=str)\n'
-        content += f"{tab}{tab}results_dicts.append(\n"
-        content += f"{tab}{tab}{tab}{{\n"
-        content += f"{tab}{tab}{tab}{tab}'summary': result_summary,\n"
-        content += f"{tab}{tab}{tab}{tab}'messages': result_messages,\n"
-        content += f"{tab}{tab}{tab}{tab}'cost': cost,\n"
-        content += f"{tab}{tab}{tab}}}\n"
-        content += f"{tab}{tab})\n"
-        content += "\n"
-        content += f"{tab}results_dict = {{\n"
-        content += f"{tab}{tab}'results': results_dicts,\n"
-        content += f"{tab}}}\n"
-        content += f"{tab}print(json.dumps(results_dict, indent=2))\n"
+        content += (
+            f"{tab}print(json.dumps(results, indent=2, ensure_ascii=False))\n"
+        )
         return content
 
     @staticmethod
@@ -226,3 +206,45 @@ class ExecutionGenerator:
         else:
             content += "    call_main()\n"
         return content
+
+
+def get_result_dicts_string(space: str, is_async: bool) -> str:
+    """Get the result dicts string.
+
+    Parameters
+    ----------
+    space : str
+        The space string to use for indentation.
+    is_async : bool
+        Whether the function is asynchronous.
+
+    Returns
+    -------
+    str
+        The result dicts string.
+    """
+    flow_content = f"{space}for index, result in enumerate(results):\n"
+    if not is_async:
+        flow_content += f"{space}    result_dict = {{\n"
+        flow_content += f"{space}        'index': index,\n"
+        flow_content += f"{space}        'messages': result.messages,\n"
+        flow_content += f"{space}        'summary': result.summary,\n"
+        flow_content += f"{space}        'cost': result.cost.model_dump(mode='json', fallback=str) if result.cost else None,\n"
+        flow_content += f"{space}        'context_variables': result.context_variables.model_dump(mode='json', fallback=str) if result.context_variables else None,\n"
+        flow_content += f"{space}        'last_speaker': result.last_speaker,\n"
+        flow_content += f"{space}        'uuid': str(result.uuid),\n"
+        flow_content += f"{space}    }}\n"
+    else:
+        flow_content += f"{space}    result_dict = {{\n"
+        flow_content += f"{space}        'index': index,\n"
+        flow_content += f"{space}        'messages': await result.messages,\n"
+        flow_content += f"{space}        'summary': await result.summary,\n"
+        flow_content += f"{space}        'cost': (await result.cost).model_dump(mode='json', fallback=str) if await result.cost else None,\n"
+        flow_content += f"{space}        'context_variables': (await result.context_variables).model_dump(mode='json', fallback=str) if await result.context_variables else None,\n"
+        flow_content += (
+            f"{space}        'last_speaker': await result.last_speaker,\n"
+        )
+        flow_content += f"{space}        'uuid': str(result.uuid),\n"
+        flow_content += f"{space}    }}\n"
+    flow_content += f"{space}    result_dicts.append(result_dict)\n"
+    return flow_content

waldiez/exporting/flow/factory.py

@@ -31,9 +31,9 @@ def create_flow_exporter(
     ----------
     waldiez : Waldiez
         The Waldiez instance containing the flow data.
-    output_dir : Path
+    output_dir : Path | None
         The directory where the exported flow will be saved.
-    uploads_root : Path
+    uploads_root : Path | None
         The root directory for uploads, if applicable.
     for_notebook : bool
         Whether the export is intended for a notebook environment.