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

waldiez/exporting/core/exporter.py

@@ -0,0 +1,390 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+# pylint: disable=too-few-public-methods
+"""Base exporter classes."""
+
+import abc
+from typing import Any, Generic, Optional
+
+from .constants import DEFAULT_IMPORT_POSITION
+from .content import PositionedContent
+from .context import DefaultExporterContext, ExporterContext
+from .enums import (
+    AgentPosition,
+    ContentOrder,
+    ExportPosition,
+    ImportPosition,
+)
+from .protocols import ExportContributor
+from .result import ExportResult, ExportResultBuilder
+from .types import (
+    EnvironmentVariable,
+    ExportConfig,
+    Extras,
+    ImportStatement,
+)
+
+
+class Exporter(abc.ABC, Generic[Extras]):
+    """Exporter base class with structured extras and clean interface."""
+
+    def __init__(
+        self,
+        context: Optional[ExporterContext] = None,
+        **kwargs: Any,
+    ):
+        """Initialize the exporter.
+
+        Parameters
+        ----------
+        context : Optional[ExporterContext], optional
+            The exporter context with dependencies, by default None
+        **kwargs : Any
+            Additional keyword arguments for subclasses.
+        """
+        self._context = context or DefaultExporterContext(
+            config=ExportConfig.create(**kwargs)
+        )
+        config = self._context.get_config()
+        config.update(**kwargs)
+        self._context.set_config(config)
+        self._result = ExportResult()
+        self._initialized = False
+        self._builder = ExportResultBuilder()
+        self.config = self._context.get_config()
+
+        # Allow subclasses to handle additional kwargs
+        self._handle_kwargs(**kwargs)
+
+    def _handle_kwargs(self, **kwargs: Any) -> None:
+        """Handle additional keyword arguments.
+
+        Override in subclasses to handle specific arguments.
+
+        Parameters
+        ----------
+        **kwargs : Any
+            Additional keyword arguments.
+        """
+
+    @property
+    def context(self) -> ExporterContext:
+        """Get the exporter context.
+
+        Returns
+        -------
+        ExporterContext
+            The exporter context.
+        """
+        return self._context
+
+    @property
+    @abc.abstractmethod
+    def extras(self) -> Extras:
+        """Get the structured extras for this exporter.
+
+        Returns
+        -------
+        Extras
+            The extras instance.
+        """
+
+    @abc.abstractmethod
+    def generate_main_content(self) -> Optional[str]:
+        """Generate the main export content.
+
+        Returns
+        -------
+        Optional[str]
+            The main content, or None if no content should be generated.
+        """
+
+    def _ensure_initialized(self) -> None:
+        """Ensure the exporter is properly initialized."""
+        if not self._initialized:
+            self._initialize_export()
+            self._initialized = True
+
+    def _initialize_export(self) -> None:
+        """Initialize the export with content from extras and main content."""
+        # Let extras contribute their content first
+        if isinstance(self.extras, ExportContributor):
+            self.extras.contribute_to_export(self._result)
+
+        # Generate and set main content
+        main_content = self.generate_main_content()
+        if main_content:
+            self._result.main_content = main_content
+
+        # Add default imports if available
+        self._add_default_imports()
+
+        # Allow subclasses to add additional content
+        self._add_additional_content()
+
+        # Validate if validator is available
+        self._validate_result()
+
+    def _add_default_imports(self) -> None:
+        """Add default imports for this exporter type.
+
+        Override in subclasses to add type-specific imports.
+        """
+
+    def _add_additional_content(self) -> None:
+        """Additional content (subclasses hook).
+
+        This is called after extras contribution and main content generation.
+        """
+
+    def _validate_result(self) -> None:
+        """Validate the export result if validator is available."""
+        if self._context.validator:
+            validation_result = self._context.validator.validate(self._result)
+            self._result.validation_result = validation_result
+
+    # Convenience methods for adding content
+
+    def add_import(
+        self,
+        statement: str,
+        position: ImportPosition = DEFAULT_IMPORT_POSITION,
+    ) -> None:
+        """Add an import statement.
+
+        Parameters
+        ----------
+        statement : str
+            The import statement to add.
+        position : ImportPosition, optional
+            The position of the import, by default THIRD_PARTY
+        """
+        self._result.add_import(statement, position)
+
+    def add_imports(
+        self,
+        statements: set[str],
+        position: ImportPosition = DEFAULT_IMPORT_POSITION,
+    ) -> None:
+        """Add multiple import statements.
+
+        Parameters
+        ----------
+        statements : Set[str]
+            The import statements to add.
+        position : ImportPosition, optional
+            The position of the imports, by default THIRD_PARTY
+        """
+        self._result.add_imports(statements, position)
+
+    def add_content(
+        self,
+        content: str,
+        position: ExportPosition,
+        order: ContentOrder = ContentOrder.MAIN_CONTENT,
+        agent_id: Optional[str] = None,
+        agent_position: Optional[AgentPosition] = None,
+        skip_strip: bool | None = None,
+        **metadata: Any,
+    ) -> None:
+        """Add positioned content.
+
+        Parameters
+        ----------
+        content : str
+            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
+            Agent ID for agent-relative positioning, by default None
+        agent_position : Optional[AgentPosition], optional
+            Position relative to agent, by default None
+        skip_strip : bool | None, optional
+            Whether to skip stripping whitespace, by default None
+            If None, defaults to True for CHATS position (keep identation),
+        **metadata : Any
+            Additional metadata for the content.
+        """
+        if skip_strip is None:
+            skip_strip = position == ExportPosition.CHATS
+        self._result.add_content(
+            content=content,
+            position=position,
+            order=order,
+            agent_id=agent_id,
+            agent_position=agent_position,
+            skip_strip=skip_strip,
+            **metadata,
+        )
+
+    def add_env_var(
+        self,
+        name: str,
+        value: str,
+        description: Optional[str] = None,
+        required: bool = True,
+    ) -> None:
+        """Add environment variable.
+
+        Parameters
+        ----------
+        name : str
+            The name of the environment variable.
+        value : str
+            The value of the environment variable.
+        description : Optional[str], optional
+            Description of the variable, by default None
+        required : bool, optional
+            Whether the variable is required, by default True
+        """
+        self._result.add_env_var(name, value, description, required)
+
+    def set_metadata(self, key: str, value: Any) -> None:
+        """Set metadata on the export result.
+
+        Parameters
+        ----------
+        key : str
+            The metadata key.
+        value : Any
+            The metadata value.
+        """
+        self._result.metadata[key] = value
+
+    def get_metadata(self, key: str, default: Any = None) -> Any:
+        """Get metadata from the export result.
+
+        Parameters
+        ----------
+        key : str
+            The metadata key.
+        default : Any, optional
+            Default value if key not found, by default None
+
+        Returns
+        -------
+        Any
+            The metadata value or default.
+        """
+        return self._result.metadata.get(key, default)
+
+    # Public interface methods
+
+    def export(self) -> ExportResult:
+        """Export and return the complete result.
+
+        Returns
+        -------
+        ExportResult
+            The complete export result.
+        """
+        self._ensure_initialized()
+        return self._result
+
+    def get_imports(self) -> list[ImportStatement]:
+        """Get sorted imports.
+
+        Returns
+        -------
+        List[ImportStatement]
+            Sorted list of import statements.
+        """
+        self._ensure_initialized()
+        return self._result.get_sorted_imports()
+
+    def get_content_by_position(
+        self, position: ExportPosition
+    ) -> list[PositionedContent]:
+        """Get content for a specific position.
+
+        Parameters
+        ----------
+        position : ExportPosition
+            The position to filter by.
+
+        Returns
+        -------
+        List[PositionedContent]
+            List of content for the specified position.
+        """
+        self._ensure_initialized()
+        return self._result.get_content_by_position(position)
+
+    def get_main_content(self) -> Optional[str]:
+        """Get the main content.
+
+        Returns
+        -------
+        Optional[str]
+            The main content.
+        """
+        self._ensure_initialized()
+        return self._result.main_content
+
+    def get_environment_variables(self) -> list[EnvironmentVariable]:
+        """Get environment variables.
+
+        Returns
+        -------
+        List[EnvironmentVariable]
+            List of environment variables.
+        """
+        self._ensure_initialized()
+        return self._result.environment_variables
+
+    def has_content(self) -> bool:
+        """Check if the exporter has any content.
+
+        Returns
+        -------
+        bool
+            True if there's any content.
+        """
+        self._ensure_initialized()
+        return self._result.has_content()
+
+    def has_errors(self) -> bool:
+        """Check if there are validation errors.
+
+        Returns
+        -------
+        bool
+            True if there are validation errors.
+        """
+        self._ensure_initialized()
+        return self._result.has_errors()
+
+    def has_warnings(self) -> bool:
+        """Check if there are validation warnings.
+
+        Returns
+        -------
+        bool
+            True if there are validation warnings.
+        """
+        self._ensure_initialized()
+        return self._result.has_warnings()
+
+    def get_statistics(self) -> dict[str, int]:
+        """Get statistics about the export.
+
+        Returns
+        -------
+        Dict[str, int]
+            Dictionary with export statistics.
+        """
+        self._ensure_initialized()
+        return self._result.get_statistics()
+
+    def clear(self) -> None:
+        """Clear all export content and reset initialization state."""
+        self._result.clear()
+        self._initialized = False
+
+    def reset(self) -> None:
+        """Reset the exporter to initial state."""
+        self._result = ExportResult()
+        self._initialized = False
+        self._builder = ExportResultBuilder()

waldiez/exporting/core/exporters.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+
+"""Exporters for Waldiez."""
+
+from typing import Any, Optional
+
+from .exporter import Exporter
+from .types import Extras
+
+
+class SimpleExporter(Exporter[None]):
+    """Simple exporter that doesn't use extras system."""
+
+    @property
+    def extras(self) -> None:
+        """Simple exporters don't have extras."""
+        return None
+
+    def _add_additional_content(self) -> None:
+        """Override this for custom content in simple exporters."""
+
+
+class ConfigurableExporter(Exporter[Extras]):
+    """Exporter with configuration support."""
+
+    def __init__(self, config: Optional[dict[str, Any]] = None, **kwargs: Any):
+        """Initialize with configuration.
+
+        Parameters
+        ----------
+        config : Optional[Dict[str, Any]], optional
+            Configuration dictionary, by default None
+        **kwargs : Any
+            Additional keyword arguments.
+        """
+        super().__init__(**kwargs)
+        self._config = config or {}
+
+    def get_config_value(self, key: str, default: Any = None) -> Any:
+        """Get a configuration value.
+
+        Parameters
+        ----------
+        key : str
+            The configuration key.
+        default : Any, optional
+            Default value if key not found, by default None
+
+        Returns
+        -------
+        Any
+            The configuration value or default.
+        """
+        return self._config.get(key, default)
+
+    def set_config_value(self, key: str, value: Any) -> None:
+        """Set a configuration value.
+
+        Parameters
+        ----------
+        key : str
+            The configuration key.
+        value : Any
+            The configuration value.
+        """
+        self._config[key] = value

waldiez/exporting/core/extras/__init__.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Extras for Waldiez exporting core module."""
+
+from .agent_extras import (
+    CaptainExtras,
+    CodeExecutionConfig,
+    GroupManagerExtras,
+    RAGUserExtras,
+    ReasoningExtras,
+    StandardExtras,
+    SystemMessageConfig,
+    TerminationConfig,
+)
+from .base import BaseExtras
+from .chat_extras import ChatExtras
+from .flow_extras import FlowExtras
+from .model_extras import ModelExtras
+from .path_resolver import DefaultPathResolver
+from .serializer import DefaultSerializer
+from .tool_extras import ToolExtras
+
+__all__ = [
+    "BaseExtras",
+    "ChatExtras",
+    "FlowExtras",
+    "ModelExtras",
+    "DefaultPathResolver",
+    "DefaultSerializer",
+    "ToolExtras",
+    "StandardExtras",
+    "CaptainExtras",
+    "CodeExecutionConfig",
+    "SystemMessageConfig",
+    "TerminationConfig",
+    "RAGUserExtras",
+    "ReasoningExtras",
+    "GroupManagerExtras",
+]

waldiez/exporting/core/extras/agent_extras/__init__.py

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+# pylint: disable=too-few-public-methods
+"""Agent specific extras module."""
+
+from .captain_extras import CaptainExtras
+from .group_manager_extras import GroupManagerExtras
+from .rag_user_extras import RAGUserExtras
+from .reasoning_extras import ReasoningExtras
+from .standard_extras import (
+    CodeExecutionConfig,
+    StandardExtras,
+    SystemMessageConfig,
+    TerminationConfig,
+)
+
+__all__ = [
+    "StandardExtras",
+    "CaptainExtras",
+    "StandardExtras",
+    "RAGUserExtras",
+    "ReasoningExtras",
+    "GroupManagerExtras",
+    "CodeExecutionConfig",
+    "SystemMessageConfig",
+    "TerminationConfig",
+]

waldiez/exporting/core/extras/agent_extras/captain_extras.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Captain agent extras module."""
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from waldiez.exporting.core.result import ExportResult
+
+from .standard_extras import StandardExtras
+
+
+@dataclass
+class CaptainExtras(StandardExtras):
+    """Extras for captain agents."""
+
+    nested_config: Optional[dict[str, Any]] = None
+
+    def _contribute_specific_content(self, result: ExportResult) -> None:
+        """Contribute captain specific content to the export result.
+
+        Parameters
+        ----------
+        result : ExportResult
+            The export result to contribute to.
+        """
+        super()._contribute_specific_content(result)
+        if self.extra_args:
+            for arg in self.extra_args:
+                result.add_instance_argument(
+                    name=arg.name,
+                    value=arg.value,
+                    instance_id=arg.instance_id,
+                    tabs=arg.tabs,
+                )
+
+    def set_nested_config(self, config: dict[str, Any]) -> None:
+        """Set the nested configuration.
+
+        Parameters
+        ----------
+        config : Dict[str, Any]
+            The nested configuration.
+        """
+        self.nested_config = config
+
+    def has_specific_content(self) -> bool:
+        """Check for captain specific content.
+
+        Returns
+        -------
+        bool
+            True if there's captain specific content.
+        """
+        if not super().has_specific_content():
+            return bool(self.extra_args or self.nested_config)
+        return True

waldiez/exporting/core/extras/agent_extras/group_manager_extras.py

@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+
+"""Group manager agent specific extras module."""
+
+from dataclasses import dataclass, field
+
+from ...enums import (
+    AgentPosition,
+    ContentOrder,
+    ExportPosition,
+    GroupManagerStrategy,
+    ImportPosition,
+)
+from ...result import ExportResult
+from .standard_extras import StandardExtras
+
+
+@dataclass
+class GroupManagerExtras(StandardExtras):
+    """Extras for group manager agents."""
+
+    # Strategy determination
+    strategy: GroupManagerStrategy = GroupManagerStrategy.PATTERN
+
+    # Pattern-based content
+    pattern_definition: str = ""
+    pattern_class_name: str = "AutoPattern"
+    pattern_imports: set[str] = field(default_factory=set[str])
+
+    # Traditional GroupChat content
+    group_chat_definition: str = ""
+    group_chat_name: str = ""
+    group_chat_argument: str = ""
+    custom_speaker_selection: str = ""
+
+    # Shared content
+    context_variables_content: str = ""
+    after_work_content: str = ""
+
+    def has_specific_content(self) -> bool:
+        """Check if group manager has specific content.
+
+        Returns
+        -------
+        bool
+            True if there is specific content for the group manager,
+        """
+        if not super().has_specific_content():
+            return bool(
+                self.pattern_definition.strip()
+                or self.group_chat_definition.strip()
+                or self.custom_speaker_selection.strip()
+            )
+        return True
+
+    def _contribute_specific_content(self, result: ExportResult) -> None:
+        """Contribute group manager content to export.
+
+        Parameters
+        ----------
+        result : ExportResult
+            The export result to contribute to.
+        """
+        super()._contribute_specific_content(result)
+        # Add pattern imports
+        for import_stmt in self.pattern_imports:
+            result.add_import(import_stmt, position=ImportPosition.THIRD_PARTY)
+
+        # Add pattern definition or group chat definition
+        if (
+            self.strategy == GroupManagerStrategy.PATTERN
+            and self.pattern_definition
+        ):
+            result.add_content(
+                self.pattern_definition,
+                ExportPosition.AGENTS,
+                agent_position=AgentPosition.AFTER_ALL,
+                order=ContentOrder.LATE_CLEANUP,
+            )
+        elif self.strategy == GroupManagerStrategy.TRADITIONAL:
+            # Add custom speaker selection function first
+            if self.custom_speaker_selection:
+                result.add_content(
+                    self.custom_speaker_selection,
+                    ExportPosition.AGENTS,
+                    agent_position=AgentPosition.AFTER_ALL,
+                    order=ContentOrder.LATE_CLEANUP,
+                )
+
+            # Add grop chat argument if specified
+            if self.group_chat_argument:
+                self.add_arg(self.group_chat_argument, tabs=1)
+
+            # Add group chat definition
+            if self.group_chat_definition:
+                result.add_content(
+                    self.group_chat_definition,
+                    ExportPosition.AGENTS,
+                    agent_position=AgentPosition.AFTER_ALL,
+                    order=ContentOrder.LATE_CLEANUP.value - 1,
+                )