waldiez 0.5.5__py3-none-any.whl → 0.5.7__py3-none-any.whl

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/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.

waldiez/exporting/flow/file_generator.py

@@ -17,6 +17,7 @@ from .execution_generator import ExecutionGenerator
 from .utils.common import generate_header
 
 
+# noinspection PyProtocol
 class FileGenerator(ContentGenerator):
     """Generate the complete flow notebook content."""
 
@@ -34,7 +35,7 @@ class FileGenerator(ContentGenerator):
         self.context = context
         self.config = context.get_config()
 
-    # pylint: disable=too-many-locals
+    # pylint: disable=too-many-locals,unused-argument
     def generate(
         self,
         merged_result: ExportResult,
@@ -42,26 +43,26 @@ class FileGenerator(ContentGenerator):
         after_run: str,
         skip_logging: bool,
         **kwargs: Any,
-    ) -> str:
-        """Generate the complete flow notebook content.
+    ) -> str:  # pyright: ignore
+        """Generate content based on provided parameters.
 
         Parameters
         ----------
         merged_result : ExportResult
             The merged export result containing all content.
         is_async : bool
-            Whether to generate async conten
+            Whether to generate async content.
         after_run : str
             Additional content to add after the main flow execution.
         skip_logging : bool
             Whether to skip logging setup.
         **kwargs : Any
-            Additional keyword arguments for the generator.
+            Parameters to influence content generation.
 
         Returns
         -------
         str
-            The complete flow notebook content.
+            The generated content.
 
         Raises
         ------
@@ -214,7 +215,7 @@ class FileGenerator(ContentGenerator):
                 tags=self.config.tags,
                 for_notebook=self.config.for_notebook,
             )
-        header_string = "\n".join(content.content for content in from_result)
+        header_string = "\n".join(item.content for item in from_result)
         while not header_string.endswith("\n\n"):
             header_string += "\n"
         return header_string

waldiez/exporting/flow/merger.py

@@ -4,7 +4,6 @@
 """Content merger for combining multiple export results."""
 
 from dataclasses import dataclass, field
-from typing import Optional, Union
 
 from ..core import (
     ContentOrder,
@@ -34,12 +33,12 @@ class MergeStatistics:
 class ContentMerger:
     """Intelligently merges multiple ExportResult objects."""
 
-    def __init__(self, context: Optional[ExporterContext] = None):
+    def __init__(self, context: ExporterContext | None = None):
         """Initialize the content merger.
 
         Parameters
         ----------
-        context : Optional[ExporterContext], optional
+        context : ExporterContext | None, optional
             The exporter context, by default None
         """
         self.context = context or ExporterContext()
@@ -245,12 +244,13 @@ class ContentMerger:
         )
 
     # pylint: disable=no-self-use
-    def _get_order_value(self, order: Union[int, ContentOrder]) -> int:
+    # noinspection PyMethodMayBeStatic
+    def _get_order_value(self, order: int | ContentOrder) -> int:
         """Get numeric value from order for sorting.
 
         Parameters
         ----------
-        order : Union[int, ContentOrder]
+        order : int | ContentOrder
             The order value
 
         Returns
@@ -352,7 +352,8 @@ class ContentMerger:
             warnings=all_warnings,
         )
 
-    def _merge_main_content(self, results: list[ExportResult]) -> Optional[str]:
+    # noinspection PyMethodMayBeStatic
+    def _merge_main_content(self, results: list[ExportResult]) -> str | None:
         """Merge main content from results.
 
         For flow exports, main content is typically empty since all content
@@ -365,7 +366,7 @@ class ContentMerger:
 
         Returns
         -------
-        Optional[str]
+        str | None
             The merged main content, or None
         """
         main_contents: list[str] = []

waldiez/exporting/flow/orchestrator.py

@@ -22,6 +22,7 @@ from .merger import ContentMerger
 from .utils import (
     generate_header,
     get_after_run_content,
+    get_common_env_var_setup,
     get_np_no_nep50_handle,
     get_sqlite_out,
     get_start_logging,
@@ -31,6 +32,7 @@ from .utils import (
 
 
 # pylint: disable=no-self-use,too-many-instance-attributes
+# noinspection PyMethodMayBeStatic
 class ExportOrchestrator:
     """Coordinates the export process."""
 
@@ -168,10 +170,15 @@ class ExportOrchestrator:
             position=ExportPosition.TOP,  # befoe everything
             order=ContentOrder.EARLY_SETUP,
         )
+        merged_result.add_content(
+            get_common_env_var_setup(),
+            position=ExportPosition.IMPORTS,  # after imports (need os)
+            order=ContentOrder.CLEANUP,
+        )
         merged_result.add_content(
             get_np_no_nep50_handle(),
             position=ExportPosition.IMPORTS,  # after imports (need np)
-            order=ContentOrder.CLEANUP,
+            order=ContentOrder.CLEANUP.value + 1,
         )
         if not self.should_skip_logging():
             merged_result.add_content(
@@ -180,7 +187,7 @@ class ExportOrchestrator:
                     for_notebook=self.config.for_notebook,
                 ),
                 position=ExportPosition.IMPORTS,  # after imports, before models
-                order=ContentOrder.CLEANUP.value + 1,  # after imports
+                order=ContentOrder.CLEANUP.value + 2,  # after imports and np
                 skip_strip=True,  # keep newlines
             )
         # merged_result.add_content
@@ -266,6 +273,7 @@ class ExportOrchestrator:
     def _get_chats_exporter(self) -> ChatsExporter:
         """Get or create chats exporter."""
         if self._chats_exporter is None:
+            # noinspection PyTypeChecker
             self._chats_exporter = create_chats_exporter(
                 waldiez=self.waldiez,
                 all_agents=self.agents,
@@ -325,6 +333,7 @@ class ExportOrchestrator:
         agent_arguments: dict[str, list[str]],
     ) -> AgentExporter:
         """Create an exporter for a specific agent."""
+        # noinspection PyTypeChecker
         return create_agent_exporter(
             agent=agent,
             agent_names=self.agent_names,
@@ -343,6 +352,7 @@ class ExportOrchestrator:
             ),
         )
 
+    # noinspection PyMethodMayBeStatic
     def _extract_agent_arguments_from_result(
         self, result: ExportResult
     ) -> dict[str, list[str]]:
@@ -416,14 +426,18 @@ class ExportOrchestrator:
     def should_skip_logging(self) -> bool:
         """Determine if logging should be skipped.
 
+        In case there is any compatibility issue with logging
+        we can skip logging entirely (until handled/fixed).
+
+        e.g:
+        return self.waldiez.has_doc_agents
+        or:
+        if self.waldiez.flow.is_group_chat:
+            return any(tool.is_predefined for tool in self.waldiez.tools)
+
         Returns
         -------
         bool
             True if logging should be skipped, False otherwise.
         """
-        return self.waldiez.has_doc_agents
-        # if not self.waldiez.tools:
-        #     return False
-        # if self.waldiez.flow.is_group_chat:
-        #     return any(tool.is_predefined for tool in self.waldiez.tools)
-        # return False
+        return False

waldiez/exporting/flow/utils/__init__.py

@@ -5,6 +5,7 @@
 from .common import (
     generate_header,
     get_after_run_content,
+    get_common_env_var_setup,
     get_np_no_nep50_handle,
 )
 from .importing import get_sorted_imports, get_the_imports_string
@@ -12,6 +13,7 @@ from .logging import get_sqlite_out, get_start_logging, get_stop_logging
 
 __all__ = [
     "generate_header",
+    "get_common_env_var_setup",
     "get_np_no_nep50_handle",
     "get_after_run_content",
     "get_the_imports_string",