waldiez 0.4.6__py3-none-any.whl → 0.4.8__py3-none-any.whl

waldiez/models/common/method_utils.py

@@ -1,5 +1,7 @@
 # SPDX-License-Identifier: Apache-2.0.
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
+# pyright: reportUnknownMemberType=false,reportUnknownVariableType=false
+# pyright: reportUnknownArgumentType=false
 """Function related utilities."""
 
 import ast
@@ -7,15 +9,25 @@ import importlib.util
 import sys
 import sysconfig
 from pathlib import Path
-from typing import List, Optional, Tuple
+from typing import NamedTuple, Optional
 
+# parso for extracting function bodies
+# (keeps comments, docstrings and formatting as-is)
 import parso
-import parso.python
-import parso.tree
+import parso.python  # pyright: ignore
+import parso.tree  # pyright: ignore
 
+# let's limit the variable name length
 MAX_VAR_NAME_LENGTH = 64
 
 
+class ParseResult(NamedTuple):
+    """Result of parsing a code string."""
+
+    error: Optional[str]
+    tree: Optional[ast.Module]
+
+
 def is_standard_library(module_name: str) -> bool:
     """Check if the module is part of the standard library.
 
@@ -33,21 +45,21 @@ def is_standard_library(module_name: str) -> bool:
         return True
     try:
         spec = importlib.util.find_spec(module_name)
-    except BaseException:  # pylint: disable=broad-except
+    except (ImportError, ValueError, ModuleNotFoundError):  # pragma: no cover
         return False
-    if spec is None or not spec.origin:
+    if spec is None or not spec.origin:  # pragma: no cover
         return False
     if "site-packages" in spec.origin:
         return False
-    if spec.origin.startswith(sys.prefix) or spec.origin == "frozen":
+    if spec.origin == "frozen":
         return True
-    stdlib_path = str(Path(sysconfig.get_path("stdlib")).resolve())
-    return spec.origin.startswith(stdlib_path)
+    stdlib_path = Path(sysconfig.get_path("stdlib")).resolve()
+    return Path(spec.origin).resolve().is_relative_to(stdlib_path)
 
 
 def parse_code_string(
     code_string: str,
-) -> Tuple[Optional[str], Optional[ast.Module]]:
+) -> ParseResult:
     """Parse the code string.
 
     Parameters
@@ -57,7 +69,7 @@ def parse_code_string(
 
     Returns
     -------
-    Tuple[Optional[str], Optional[ast.Module]]
+    ParseResult
         If valid, None and the ast module.
         If invalid, the error message and None.
     """
@@ -65,16 +77,95 @@ def parse_code_string(
     try:
         tree = ast.parse(code_string)
     except SyntaxError as e:
-        return f"SyntaxError: {e}, in " + "\n" + f"{code_string}", None
+        return ParseResult(
+            f"SyntaxError: {e}, in " + "\n" + f"{code_string}", None
+        )
     except BaseException as e:  # pragma: no cover
-        return f"Invalid code: {e}, in " + "\n" + f"{code_string}", None
-    return None, tree
+        return ParseResult(
+            f"Invalid code: {e}, in " + "\n" + f"{code_string}", None
+        )
+    return ParseResult(None, tree)
+
+
+def _extract_module_name(node: ast.AST) -> Optional[str]:
+    """Extract the root module name from an import node."""
+    if isinstance(node, ast.Import):
+        return node.names[0].name.split(".")[0]
+    if isinstance(node, ast.ImportFrom):
+        if node.module:
+            # Handle relative imports
+            if node.module.startswith("."):  # pragma: no cover
+                return None  # Skip relative imports for stdlib check
+            return node.module.split(".")[0]
+    return None  # pragma: no cover
+
+
+def _extract_imports_from_ast(code_string: str) -> tuple[list[str], list[str]]:
+    """Extract import statements from code using AST.
+
+    Parameters
+    ----------
+    code_string : str
+        The code string to parse.
+
+    Returns
+    -------
+    tuple[list[str], list[str]]
+        Standard library imports and third party imports (unsorted).
+    """
+    standard_lib_imports: list[str] = []
+    third_party_imports: list[str] = []
+
+    try:
+        tree = ast.parse(code_string)
+    except SyntaxError:  # pragma: no cover
+        return [], []
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            full_import_statement = ast.get_source_segment(code_string, node)
+            if not full_import_statement:  # pragma: no cover
+                continue
+            full_import_statement = full_import_statement.strip()
+
+            module_name = _extract_module_name(node)
+            if not module_name:  # pragma: no cover
+                continue
+
+            if is_standard_library(module_name):
+                standard_lib_imports.append(full_import_statement)
+            else:
+                third_party_imports.append(full_import_statement)
+
+    return standard_lib_imports, third_party_imports
+
+
+def _sort_imports(imports: list[str]) -> list[str]:
+    """Sort import statements with 'import' statements before 'from' statements.
+
+    Parameters
+    ----------
+    imports : list[str]
+        List of import statements to sort.
+
+    Returns
+    -------
+    list[str]
+        Sorted import statements.
+    """
+    import_statements = sorted(
+        [stmt for stmt in imports if stmt.startswith("import ")]
+    )
+    from_statements = sorted(
+        [stmt for stmt in imports if stmt.startswith("from ")]
+    )
+    return import_statements + from_statements
 
 
 def gather_code_imports(
     code_string: str,
     is_interop: bool,
-) -> Tuple[List[str], List[str]]:
+) -> tuple[list[str], list[str]]:
     """Gather the imports from the code string.
 
     Parameters
@@ -86,35 +177,13 @@ def gather_code_imports(
 
     Returns
     -------
-    Tuple[List[str], List[str]]
+    tuple[list[str], list[str]]
         The standard library imports and the third party imports.
     """
-    standard_lib_imports: List[str] = []
-    third_party_imports: List[str] = []
-    tree = parso.parse(code_string)  # type: ignore
-    for node in tree.iter_imports():
-        if node.type == "import_name":
-            full_import_statement = node.get_code().strip()
-            module_name = (
-                node.get_code().replace("import", "").strip().split(" ")[0]
-            )
-            if not module_name:
-                continue
-            if is_standard_library(module_name):
-                standard_lib_imports.append(full_import_statement)
-            else:
-                third_party_imports.append(full_import_statement)
-        elif node.type == "import_from":
-            full_import_statement = node.get_code().strip()
-            module_name = (
-                node.get_code().replace("from", "").strip().split(" ")[0]
-            )
-            if not module_name:
-                continue
-            if is_standard_library(module_name):
-                standard_lib_imports.append(full_import_statement)
-            else:
-                third_party_imports.append(full_import_statement)
+    standard_lib_imports, third_party_imports = _extract_imports_from_ast(
+        code_string
+    )
+
     if is_interop and (
         "from autogen.interop import Interoperability"
         not in third_party_imports
@@ -122,25 +191,18 @@ def gather_code_imports(
         third_party_imports.append(
             "from autogen.interop import Interoperability"
         )
-    # sorted_standard_lib_imports =  # first import x, then from a import b
-    sorted_standard_lib_imports = sorted(
-        [stmt for stmt in standard_lib_imports if stmt.startswith("import ")]
-    ) + sorted(
-        [stmt for stmt in standard_lib_imports if stmt.startswith("from ")]
-    )
-    sorted_third_party_imports = sorted(
-        [stmt for stmt in third_party_imports if stmt.startswith("import ")]
-    ) + sorted(
-        [stmt for stmt in third_party_imports if stmt.startswith("from ")]
-    )
+
+    sorted_standard_lib_imports = _sort_imports(standard_lib_imports)
+    sorted_third_party_imports = _sort_imports(third_party_imports)
+
     return sorted_standard_lib_imports, sorted_third_party_imports
 
 
 def check_function(
     code_string: str,
     function_name: str,
-    function_args: List[str],
-) -> Tuple[bool, str]:
+    function_args: list[str],
+) -> tuple[bool, str]:
     """Check the function.
 
     Parameters
@@ -149,12 +211,12 @@ def check_function(
         The code string to check.
     function_name : str
         The expected method name.
-    function_args : List[str]
+    function_args : list[str]
         The expected method arguments.
 
     Returns
     -------
-    Tuple[bool, str]
+    tuple[bool, str]
         If valid, True and the function body (only), no extra lines.
         If invalid, False and the error message.
     """
@@ -173,24 +235,24 @@ def _validate_function_body(
     tree: ast.Module,
     code_string: str,
     function_name: str,
-    function_args: List[str],
-) -> Tuple[bool, str]:
+    function_args: list[str],
+) -> tuple[bool, str]:
     """Get the function body.
 
     Parameters
     ----------
     tree : ast.Module
         The ast module.
-    function_body : str
+    code_string : str
         The function body.
     function_name : str
         The expected method name.
-    function_args : List[str]
+    function_args : list[str]
         The expected method arguments.
 
     Returns
     -------
-    Tuple[bool, str]
+    tuple[bool, str]
         If valid, True and the function body (only), no extra lines.
         If invalid, False and the error message.
     """
@@ -277,13 +339,13 @@ def _get_function_body(
     Raises
     ------
     ValueError
-        If no body found in the function.
+        If the function's body is empty.
     """
     lines = code_string.splitlines()
     signature_start_line = node.lineno - 1
     body_start_line = node.body[0].lineno - 1
     signature_end_line = signature_start_line
-    for i in range(signature_start_line, body_start_line):
+    for i in range(signature_start_line, body_start_line):  # pragma: no branch
         if ")" in lines[i]:
             signature_end_line = i
             break
@@ -301,8 +363,8 @@ def _get_function_body(
 
 def generate_function(
     function_name: str,
-    function_args: List[str],
-    function_types: Tuple[List[str], str],
+    function_args: list[str],
+    function_types: tuple[list[str], str],
     function_body: str,
     types_as_comments: bool = False,
 ) -> str:
@@ -312,9 +374,9 @@ def generate_function(
     ----------
     function_name : str
         The function name.
-    function_args : List[str]
+    function_args : list[str]
         The function arguments.
-    function_types : Tuple[List[str], str]
+    function_types : tuple[list[str], str]
         The function types.
     function_body : str
         The function body.
@@ -349,6 +411,6 @@ def generate_function(
         function_string += " -> " + function_types[1] + ":"
     function_string += "\n" if not function_body.startswith("\n") else ""
     function_string += f"{function_body}"
-    if not function_string.endswith("\n"):
+    if not function_string.endswith("\n"):  # pragma: no branch
         function_string += "\n"
     return function_string

waldiez/{exporting/base/utils → models/common}/naming.py

@@ -1,19 +1,8 @@
 # SPDX-License-Identifier: Apache-2.0.
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
-"""Utilities for naming.
-
-Functions
----------
-get_valid_python_variable_name
-    Make sure a string is a valid Python variable name.
-get_valid_instance_name
-    Get a valid instance name.
-get_escaped_string
-    Get a string with escaped quotes and newlines.
-"""
+"""Ensure unique names for agents, models, tools, and chats."""
 
 import re
-from typing import Dict, Tuple
 
 MAX_VARIABLE_LENGTH = 46
 
@@ -29,10 +18,8 @@ def get_valid_python_variable_name(
     ----------
     possible : str
         The possible name.
-
     prefix : str, optional
         The prefix to use if the name starts with a digit or special character
-
     max_length : int, optional
         The maximum length of the variable name.
 
@@ -41,47 +28,48 @@ def get_valid_python_variable_name(
     str
         The valid Python variable name.
     """
+    if not possible or not possible.strip():
+        return prefix + "_"
+
+    # First handle arrow operators specifically
+    possible = possible.replace("->", "to")
+    possible = possible.replace("=>", "to")
+    possible = possible.replace("<-", "from")
+    possible = possible.replace("<=", "from")
+
+    # Replace non-ASCII characters and non-word characters with underscores
+    # \W matches any non-word character, but in Python's re module,
+    # \w includes Unicode letters by default, so we need to be more explicit
+    # to replace Unicode letters with underscores for valid Python identifiers
+    possible = re.sub(r"[^\w]", "_", possible)  # Replace non-word chars
+    possible = re.sub(r"[^\x00-\x7F]", "_", possible)  # Replace non-ASCII chars
+
+    # Convert to lowercase and truncate
+    possible = possible.lower()[:max_length]
 
-    def replacement(match: re.Match[str]) -> str:
-        """Get the replacement for the match.
-
-        Parameters
-        ----------
-        match : re.Match[str]
-            The match.
-
-        Returns
-        -------
-        str
-            The replacement
-        """
-        if match.group(0) in ["->", "=>"]:
-            return "to"
-        if match.group(0) in ["<-", "<="]:
-            return "from"
-        if re.match(r"\W|^(?=\d)", match.group(0)):
-            return "_"
-        return match.group(0)
-
-    possible = re.sub(r"->|=>|<-|<=|\W|^(?=\d)", replacement, possible)[
-        :max_length
-    ].lower()
+    # Remove trailing underscores from truncation
+    possible = possible.rstrip("_")
 
     if not possible:
         return prefix + "_"
+
+    # Handle names starting with underscore
     if possible.startswith("_"):
         return f"{prefix}{possible}"
+
+    # Handle names starting with digit
     if possible[0].isdigit():
         return f"{prefix}_{possible}"
+
     return possible
 
 
 def get_valid_instance_name(
-    instance: Tuple[str, str],
-    current_names: Dict[str, str],
+    instance: tuple[str, str],
+    current_names: dict[str, str],
     prefix: str = "w",
     max_length: int = MAX_VARIABLE_LENGTH,
-) -> Dict[str, str]:
+) -> dict[str, str]:
     """Get a valid instance name.
 
     If the instance id is already in the current names nothing is done.
@@ -90,9 +78,9 @@ def get_valid_instance_name(
 
     Parameters
     ----------
-    instance : Tuple[str, str]
+    instance : tuple[str, str]
         The instance id and possible name.
-    current_names : Dict[str, str]
+    current_names : dict[str, str]
         The current names.
     prefix : str, optional
         The prefix to use if the name starts with a digit,
@@ -103,39 +91,28 @@ def get_valid_instance_name(
 
     Returns
     -------
-    Dict[str, str]
+    dict[str, str]
         The updated names.
     """
     instance_id, possible_name = instance[0], instance[1][:max_length]
+
     if instance_id in current_names:
-        # already in the current names (it's id)
+        # already in the current names (by its id)
         return current_names
+
     new_names = current_names.copy()
     name = get_valid_python_variable_name(
         possible_name, prefix=prefix, max_length=max_length
     )
+
     if name in current_names.values():
         name = f"{prefix}_{name}"
+
     if name in current_names.values():
         index = 1
         while f"{name}_{index}" in current_names.values():
             index += 1
         name = f"{name}_{index}"
+
     new_names[instance_id] = name
     return new_names
-
-
-def get_escaped_string(string: str) -> str:
-    """Get a string with escaped quotes and newlines.
-
-    Parameters
-    ----------
-    string : str
-        The original string.
-
-    Returns
-    -------
-    str
-        The escaped string.
-    """
-    return string.replace('"', '\\"').replace("\n", "\\n")

waldiez/models/common/waldiez_version.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+
+"""Read the version from the version file."""
+
+from pathlib import Path
+
+
+def get_waldiez_version() -> (
+    str
+):  # pragma: no cover  # depends on file existence
+    """Read the version from the version file.
+
+    Returns
+    -------
+    str
+        The version.
+    """
+    here = Path(__file__).parent  # waldiez/models/common
+    package_dir = here.parent.parent  # waldiez/models -> waldiez
+    version_file = package_dir / "_version.py"
+    if not version_file.exists():
+        return "0.0.0"  # dev / ignored
+    with version_file.open() as f:
+        for line in f:
+            if line.startswith("__version__"):
+                version = line.split("=")[1].strip().strip('"').strip("'")
+                # send version without "v" prefix
+                if version.startswith("v"):
+                    version = version[1:]
+                # make sure it is a valid semver
+                if not version or not all(
+                    part.isdigit() for part in version.split(".")
+                ):
+                    return "0.0.0"
+                return version
+    return "0.0.0"  # fallback if not found

waldiez/models/flow/__init__.py

@@ -2,12 +2,19 @@
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
 """Waldiez flow related models."""
 
+from .connection import WaldiezAgentConnection
 from .flow import WaldiezFlow
-from .flow_data import WaldiezFlowData
-from .utils import get_flow_data
+from .flow_data import WaldiezFlowData, get_flow_data
+from .info import WaldiezAgentInfo, WaldiezFlowInfo
+from .naming import WaldiezUniqueNames, ensure_unique_names
 
 __all__ = [
     "get_flow_data",
+    "ensure_unique_names",
+    "WaldiezAgentConnection",
+    "WaldiezAgentInfo",
     "WaldiezFlow",
+    "WaldiezFlowInfo",
     "WaldiezFlowData",
+    "WaldiezUniqueNames",
 ]

waldiez/models/flow/connection.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Waldiez agent connection model."""
+
+from typing import TypedDict
+
+from ..agents import (
+    WaldiezAgent,
+)
+from ..chat import WaldiezChat
+
+
+class WaldiezAgentConnection(TypedDict):
+    """Agent connection."""
+
+    source: WaldiezAgent
+    target: WaldiezAgent
+    chat: WaldiezChat