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

waldiez/exporting/core/types.py

@@ -0,0 +1,329 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+
+"""Core dataclasses for the exporting system."""
+
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+from typing import Any, Optional, TypeVar
+
+from .enums import (
+    ImportPosition,
+)
+
+# Generic type for extras
+Extras = TypeVar("Extras")
+
+
+# Sentinel for exporters that do not require extras
+# pylint: disable=too-few-public-methods
+class _NoExtrasType:
+    """Sentinel for exporters that do not require extras."""
+
+    def __repr__(self) -> str:
+        """Get the string representation of NoExtras."""
+        return "<NoExtras>"
+
+
+NoExtras = _NoExtrasType()
+
+
+# Core Data Structures
+@dataclass
+class ImportStatement:
+    """Represents an import statement with its position."""
+
+    statement: str
+    position: ImportPosition = ImportPosition.THIRD_PARTY
+    metadata: Optional[dict[str, Any]] = None
+
+    def __hash__(self) -> int:
+        """Hash based on the import statement.
+
+        Returns
+        -------
+        int
+            The hash value of the import statement.
+        """
+        return hash(self.statement)
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality based on the import statement.
+
+        Parameters
+        ----------
+        other : object
+            The object to compare against.
+
+        Returns
+        -------
+        bool
+            True if the other object is an
+            ImportStatement with the same statement.
+        """
+        if isinstance(other, ImportStatement):
+            return self.statement == other.statement
+        return False
+
+    def __lt__(self, other: "ImportStatement") -> bool:
+        """Enable sorting by position then statement.
+
+        Parameters
+        ----------
+        other : ImportStatement
+            The other import statement to compare against.
+
+        Returns
+        -------
+        bool
+            True if this import statement should come before the other.
+        """
+        if self.position.value != other.position.value:
+            return self.position.value < other.position.value
+        return self.statement < other.statement
+
+
+@dataclass
+class EnvironmentVariable:
+    """Environment variable with metadata."""
+
+    name: str
+    value: str
+    description: Optional[str] = None
+    required: bool = True
+
+    def __post_init__(self) -> None:
+        """Validate environment variable."""
+        if not self.name or not self.value:
+            raise ValueError("Environment variable name and value are required")
+
+    def __hash__(self) -> int:
+        """Hash based on the environment variable name.
+
+        Returns
+        -------
+        int
+            The hash value of the environment variable name.
+        """
+        return hash(self.name)
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality based on the environment variable name.
+
+        Parameters
+        ----------
+        other : object
+            The object to compare against.
+
+        Returns
+        -------
+        bool
+            True if the other object is an
+            EnvironmentVariable with the same name.
+        """
+        if isinstance(other, EnvironmentVariable):
+            return self.name == other.name
+        return False
+
+    def as_tuple(self) -> tuple[str, str]:
+        """Get the environment variable as a tuple.
+
+        Returns
+        -------
+        tuple[str, str]
+            The environment variable as a tuple.
+        """
+        return (self.name, self.value)
+
+
+# Instance Argument
+@dataclass
+class InstanceArgument:
+    """Represents an instance argument for an agent, model or tool."""
+
+    instance_id: str
+    name: str
+    value: Any
+    tabs: int = 0
+    tabs_length: int = 4  # Assuming 4 spaces per tab
+    with_new_line_before: bool = False
+    with_new_line_after: bool = False
+    with_new_line_if_empty: bool = False
+    skip_if_empty_string: bool = True
+    comment: Optional[str] = None
+
+    def has_content(self) -> bool:
+        """Check if the instance argument has content.
+
+        Returns
+        -------
+        bool
+            True if the instance argument has content, otherwise False.
+        """
+        if self.skip_if_empty_string and isinstance(self.value, str):
+            return bool(self.value.strip())
+        return self.value is not None and self.value != ""
+
+    def get_content(
+        self,
+        prepend_new_line: bool = False,
+        append_new_line: bool = False,
+    ) -> str:
+        """Get the content representation of the instance argument.
+
+        Parameters
+        ----------
+        prepend_new_line : bool, optional
+            Whether to prepend a new line before the content,
+            by default False.
+        append_new_line : bool, optional
+            Whether to append a new line at the end of the content,
+            by default False.
+
+        Returns
+        -------
+        str
+            The formatted content string for the instance argument.
+        """
+        if (
+            self.skip_if_empty_string
+            and isinstance(self.value, str)
+            and not self.value.strip()
+        ):
+            return "\n" if self.with_new_line_if_empty else ""
+        space = " " * (self.tabs * self.tabs_length)
+        content = f"{space}{self.name}={self.value}," + (
+            f"  # {self.comment}" if self.comment else ""
+        )
+        if self.with_new_line_before or prepend_new_line:
+            content = "\n" + content
+        if self.with_new_line_after or append_new_line:
+            content += "\n"
+        return content
+
+    def __hash__(self) -> int:
+        """Hash based on the instance ID and name.
+
+        Returns
+        -------
+        int
+            The hash value of the instance argument.
+        """
+        return hash((self.instance_id, self.name))
+
+    def __str__(self) -> str:
+        """Get the string representation of the instance argument.
+
+        Returns
+        -------
+        str
+            The string representation of the instance argument.
+        """
+        return self.get_content()
+
+    def __repr__(self) -> str:
+        """Get the string representation of the instance argument.
+
+        Returns
+        -------
+        str
+            The string representation of the instance argument.
+        """
+        return self.get_content()
+
+
+# Export Configuration
+@dataclass
+class ExportConfig:
+    """Configuration for export operations.
+
+    Attributes
+    ----------
+    output_extension : str
+        The file extension for the exported content.
+    is_async : bool
+        Whether the exported content should be asynchronous.
+    """
+
+    name: str = "Waldiez Flow"
+    description: str = (
+        "Make AG2 Agents Collaborate: Drag, Drop, and Orchestrate with Waldiez"
+    )
+    requirements: list[str] = field(default_factory=list[str])
+    tags: list[str] = field(default_factory=list[str])
+    output_extension: str = "py"
+    is_async: bool = False
+    output_directory: Optional[str | Path] = None
+    cache_seed: Optional[int] = None
+
+    @property
+    def for_notebook(self) -> bool:
+        """Check if the export is intended for a notebook environment.
+
+        Returns
+        -------
+        bool
+            True if the output extension is 'ipynb', otherwise False.
+        """
+        return self.output_extension == "ipynb"
+
+    def __post_init__(self) -> None:
+        """Post-initialization validation."""
+        if not self.name:
+            raise ValueError("ExportConfig name cannot be empty")
+        if not self.description:
+            raise ValueError("ExportConfig description cannot be empty")
+        if not self.output_extension:
+            raise ValueError("ExportConfig output_extension cannot be empty")
+
+    @classmethod
+    def create(cls, **kwargs: Any) -> "ExportConfig":
+        """Create a new ExportConfig instance with the provided values.
+
+        Parameters
+        ----------
+        **kwargs : Any
+            Keyword arguments to initialize the ExportConfig.
+
+        Returns
+        -------
+        ExportConfig
+            A new instance of 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:
+            output_extension = "ipynb"
+        cache_seed = kwargs.pop("cache_seed", None)
+        if cache_seed is not None and not isinstance(cache_seed, int):
+            cache_seed = None
+        return cls(
+            cache_seed=cache_seed,
+            output_extension=output_extension,
+            **{k: v for k, v in kwargs.items() if k in valid_fields},
+        )
+
+    def update(self, **kwargs: Any) -> None:
+        """Update the export configuration with new values.
+
+        Parameters
+        ----------
+        **kwargs : Any
+            Keyword arguments to update the configuration.
+
+        Raises
+        ------
+        ValueError
+            If an invalid configuration key is provided.
+        """
+        valid_fields = {f.name for f in fields(self)}
+        for key, value in kwargs.items():
+            if key in valid_fields:
+                setattr(self, key, value)
+        if (
+            "for_notebook" in kwargs
+            and isinstance(kwargs["for_notebook"], bool)
+            and "output_extension" not in kwargs
+        ):  # pragma: no cover
+            self.output_extension = "ipynb" if kwargs["for_notebook"] else "py"

waldiez/exporting/core/utils/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Utility functions for Waldiez exporting."""
+
+from .comment import get_comment
+from .llm_config import get_agent_llm_config_arg
+
+__all__ = [
+    "get_comment",
+    "get_agent_llm_config_arg",
+]

waldiez/exporting/core/utils/comment.py

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Get comment string for scripts or notebooks."""
+
+
+def get_comment(
+    comment: str,
+    for_notebook: bool = False,
+    md_headings: int = 3,
+) -> str:
+    """Get a comment for the script or notebook.
+
+    Parameters
+    ----------
+    comment : str
+        The comment to add.
+    for_notebook : bool, optional
+        Whether the comment is for a notebook, by default False
+    md_headings : int, optional
+        The number of markdown headings to use (if for_notebook is True),
+        by default 2
+
+    Returns
+    -------
+    str
+        The formatted comment.
+    """
+    if for_notebook:
+        # For notebooks, we use markdown headings
+        heading = "#" + "#" * md_headings
+        return f"# %% [markdown]\n{heading} {comment}\n# %% \n"
+    # For scripts, we use a simple comment
+    return f"# {comment}\n"

waldiez/exporting/core/utils/llm_config.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""LLM config argument utility functions for Waldiez agents."""
+
+from waldiez.models import WaldiezAgent, WaldiezModel
+
+
+def get_agent_llm_config_arg(
+    agent: WaldiezAgent,
+    all_models: list[WaldiezModel],
+    model_names: dict[str, str],
+    cache_seed: int | None,
+    as_dict: bool = False,
+    tabs: int = 1,
+) -> str:
+    """Get the string representation of the agent's llm config argument.
+
+    Parameters
+    ----------
+    agent : WaldiezAgent
+        The agent.
+    all_models : list[WaldiezModel]
+        All the models in the flow.
+    model_names : dict[str, str]
+        A mapping of model ids to model names.
+    cache_seed : Optional[int]
+        The cache seed.
+    as_dict : bool, optional
+        Whether to return the argument as a dictionary, by default False.
+    tabs : int, optional
+        The number of tabs for indentation, by default 1.
+
+    Returns
+    -------
+    str
+        The agent's llm config argument to use.
+    """
+    if as_dict is False:
+        return _get_agent_llm_config_arg_as_arg(
+            agent,
+            all_models,
+            model_names,
+            cache_seed,
+            tabs=tabs,
+        )
+    return _get_agent_llm_config_arg_as_dict(
+        agent,
+        all_models,
+        model_names,
+        cache_seed,
+        tabs=tabs + 1,
+    )
+
+
+def _get_agent_llm_config_arg_as_arg(
+    agent: WaldiezAgent,
+    all_models: list[WaldiezModel],
+    model_names: dict[str, str],
+    cache_seed: int | None,
+    tabs: int = 1,
+    tab_leng: int = 4,
+) -> str:
+    tab = " " * tab_leng * tabs if tabs > 0 else ""
+    # tab = "    " * tabs if tabs > 0 else ""
+    if not agent.data.model_ids:
+        return f"{tab}llm_config=False,  # pyright: ignore" + "\n"
+    content = f"{tab}llm_config=autogen.LLMConfig(" + "\n"
+    content += f"{tab}    config_list=["
+    got_at_least_one_model = False
+    temperature: float | None = None
+    for model_id in agent.data.model_ids:
+        model = next((m for m in all_models if m.id == model_id), None)
+        if model is not None:
+            temperature = model.data.temperature
+            model_name = model_names[model_id]
+            content += "\n" + f"{tab}        {model_name}_llm_config,"
+            got_at_least_one_model = True
+    if not got_at_least_one_model:  # pragma: no cover
+        return f"{tab}llm_config=False,  # pyright: ignore" + "\n"
+    content += "\n" + f"{tab}    ]," + "\n"
+    content += f"{tab}    cache_seed={cache_seed}," + "\n"
+    if temperature is not None:
+        content += f"{tab}    temperature={temperature}," + "\n"
+    content += tab + "),\n"
+    return content
+
+
+def _get_agent_llm_config_arg_as_dict(
+    agent: WaldiezAgent,
+    all_models: list[WaldiezModel],
+    model_names: dict[str, str],
+    cache_seed: int | None,
+    tabs: int = 1,
+    tab_leng: int = 4,
+) -> str:
+    tab = " " * tab_leng * tabs if tabs > 0 else ""
+    if not agent.data.model_ids:
+        return f'{tab}"llm_config": False' + "\n"
+    content = f'{tab}"llm_config": autogen.LLMConfig(' + "\n"
+    content += f"{tab}    config_list=["
+    got_at_least_one_model = False
+    temperature: float | None = None
+    for model_id in agent.data.model_ids:
+        model = next((m for m in all_models if m.id == model_id), None)
+        if model is not None:  # pragma: no branch
+            temperature = model.data.temperature
+            model_name = model_names[model_id]
+            content += "\n" + f"{tab}        {model_name}_llm_config,"
+            got_at_least_one_model = True
+    if not got_at_least_one_model:  # pragma: no cover
+        return f'{tab}"llm_config": False' + "\n"
+    content += "\n" + f"{tab}    ]," + "\n"
+    content += f"{tab}    cache_seed={cache_seed}," + "\n"
+    if temperature is not None:
+        content += f"{tab}    temperature={temperature}," + "\n"
+    content += tab + "),\n"
+    return content

waldiez/exporting/core/validation.py

@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Validation types and results for Waldiez exporting core."""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# Validation Types
+@dataclass
+class ValidationError:
+    """Represents a validation error."""
+
+    message: str
+    severity: str = "error"  # error, warning, info
+    location: Optional[str] = None
+    suggestion: Optional[str] = None
+
+
+@dataclass
+class ValidationResult:
+    """Result of validation operations."""
+
+    is_valid: bool
+    errors: list[ValidationError] = field(
+        default_factory=list[ValidationError],
+    )
+    warnings: list[ValidationError] = field(
+        default_factory=list[ValidationError],
+    )
+
+    def add_error(
+        self,
+        message: str,
+        location: Optional[str] = None,
+        suggestion: Optional[str] = None,
+    ) -> None:
+        """Add a validation error.
+
+        Parameters
+        ----------
+        message : str
+            The error message to add.
+        location : Optional[str], optional
+            The location in the code where the error occurred, by default None
+        suggestion : Optional[str], optional
+            A suggestion for fixing the error, by default None
+        """
+        self.errors.append(
+            ValidationError(message, "error", location, suggestion)
+        )
+        self.is_valid = False
+
+    def add_warning(self, message: str, location: Optional[str] = None) -> None:
+        """Add a validation warning.
+
+        Parameters
+        ----------
+        message : str
+            The warning message to add.
+        location : Optional[str], optional
+            The location in the code where the warning occurred, by default None
+        """
+        self.warnings.append(ValidationError(message, "warning", location))
+
+    def has_errors(self) -> bool:
+        """Check if there are any errors.
+
+        Returns
+        -------
+        bool
+            True if there are validation errors, otherwise False.
+        """
+        return len(self.errors) > 0
+
+    def has_warnings(self) -> bool:
+        """Check if there are any warnings.
+
+        Returns
+        -------
+        bool
+            True if there are validation warnings, otherwise False.
+        """
+        return len(self.warnings) > 0
+
+    def merge(self, other: "ValidationResult") -> None:
+        """Merge another ValidationResult into this one.
+
+        Parameters
+        ----------
+        other : ValidationResult
+            The other validation result to merge.
+        """
+        self.is_valid = self.is_valid and other.is_valid
+        self.errors.extend(other.errors)
+        self.warnings.extend(other.warnings)

waldiez/exporting/flow/__init__.py

@@ -2,6 +2,10 @@
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
 """Flow exporter."""
 
-from .flow_exporter import FlowExporter
+from .exporter import FlowExporter
+from .factory import create_flow_exporter
 
-__all__ = ["FlowExporter"]
+__all__ = [
+    "FlowExporter",
+    "create_flow_exporter",
+]