waldiez 0.1.0__py3-none-any.whl

waldiez/exporting/skills/__init__.py

@@ -0,0 +1,128 @@
+"""Skills/tools related string generation functions.
+
+Functions
+---------
+get_agent_skill_registration
+    Get an agent's skill registration string.
+export_skills
+    Get the skills content and secrets.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple, Union
+
+from waldiez.models import WaldiezSkill
+
+from ..utils import get_escaped_string
+
+
+def get_agent_skill_registration(
+    caller_name: str,
+    executor_name: str,
+    skill_name: str,
+    skill_description: str,
+) -> str:
+    """Get the agent skill string and secrets.
+
+    Parameters
+    ----------
+    caller_name : str
+        The name of the caller (agent).
+    executor_name : str
+        The name of the executor (agent).
+    skill_name : str
+        The name of the skill.
+    skill_description : str
+        The skill description.
+
+    Returns
+    -------
+    str
+        The agent skill string.
+
+    Example
+    -------
+    ```python
+    >>> get_agent_skill_registration(
+    ...     caller_name="agent1",
+    ...     executor_name="agent2",
+    ...     skill_name="skill1",
+    ...     skill_description="A skill that does something.",
+    ... )
+    register_function(
+        skill1,
+        caller=agent1,
+        executor=agent2,
+        name="skill1",
+        description="A skill that does something.",
+    )
+    ```
+    """
+    skill_description = get_escaped_string(skill_description)
+    content = f"""register_function(
+    {skill_name},
+    caller={caller_name},
+    executor={executor_name},
+    name="{skill_name}",
+    description="{skill_description}",
+)"""
+    return content
+
+
+def export_skills(
+    skills: List[WaldiezSkill],
+    skill_names: Dict[str, str],
+    output_dir: Optional[Union[str, Path]] = None,
+) -> Tuple[Set[str], Set[Tuple[str, str]]]:
+    """Get the skills' contents and secrets.
+
+    If `output_dir` is provided, the contents are saved to that directory.
+
+    Parameters
+    ----------
+    skills : List[WaldiezSkill]
+        The skills.
+    skill_names : Dict[str, str]
+        The skill names.
+    output_dir : Optional[Union[str, Path]]
+        The output directory to save the skills to.
+
+    Returns
+    -------
+    Tuple[Set[str], Set[Tuple[str, str]]]
+        - The skill imports to use in the main file.
+        - The skill secrets to set as environment variables.
+
+    Example
+    -------
+    ```python
+    >>> from waldiez.models import WaldiezSkill, WaldiezSkillData
+    >>> skill1 = WaldiezSkill(
+    ...     id="ws-1",
+    ...     name="skill1",
+    ...     description="A skill that does something.",
+    ...     tags=["skill", "skill1"],
+    ...     requirements=[],
+    ...     data=WaldiezSkillData(
+    ...         content="def skill1():\\n    pass",
+    ...         secrets={"API_KEY": "1234567890"},
+    ... )
+    >>> skill_names = {"ws-1": "skill1"}
+    >>> export_skills([skill1], skill_names, None)
+    ({'from skill1 import skill1'}, {('API_KEY', '1234567890')})
+    ```
+    """
+    skill_imports: Set[str] = set()
+    skill_secrets: Set[Tuple[str, str]] = set()
+    for skill in skills:
+        skill_name = skill_names[skill.id]
+        skill_imports.add(f"from {skill_name} import {skill_name}")
+        skill_secrets.update(skill.secrets.items())
+        if not output_dir:
+            continue
+        if not isinstance(output_dir, Path):
+            output_dir = Path(output_dir)
+        skill_file = output_dir / f"{skill_name}.py"
+        with skill_file.open("w", encoding="utf-8") as f:
+            f.write(skill.content)
+    return skill_imports, skill_secrets

waldiez/exporting/utils/__init__.py

@@ -0,0 +1,34 @@
+"""Generic utils to be used for exporting."""
+
+from .comments import comment, get_comment, get_pylint_ignore_comment
+from .importing import add_autogen_dot_import, get_imports_string
+from .logging_utils import (
+    get_logging_start_string,
+    get_logging_stop_string,
+    get_sqlite_to_csv_call_string,
+    get_sqlite_to_csv_string,
+)
+from .method_utils import get_method_string
+from .naming import (
+    get_escaped_string,
+    get_valid_instance_name,
+    get_valid_python_variable_name,
+)
+from .object_string import get_object_string
+
+__all__ = [
+    "add_autogen_dot_import",
+    "comment",
+    "get_logging_start_string",
+    "get_logging_stop_string",
+    "get_pylint_ignore_comment",
+    "get_sqlite_to_csv_string",
+    "get_sqlite_to_csv_call_string",
+    "get_imports_string",
+    "get_comment",
+    "get_escaped_string",
+    "get_method_string",
+    "get_object_string",
+    "get_valid_instance_name",
+    "get_valid_python_variable_name",
+]

waldiez/exporting/utils/comments.py

@@ -0,0 +1,136 @@
+"""Comment related string generation functions.
+Functions
+---------
+comment
+    Get a comment string.
+get_comment
+    Get a comment string for some common keys (notebook headings).
+get_pylint_ignore_comment
+    Get the pylint ignore comment string.
+"""
+
+from typing import List, Optional
+
+from typing_extensions import Literal
+
+PYLINT_RULES = [
+    "line-too-long",
+    "unknown-option-value",
+    "unused-argument",
+    "unused-import",
+    "invalid-name",
+    "import-error",
+    "inconsistent-quotes",
+    "missing-function-docstring",
+    "missing-param-doc",
+    "missing-return-doc",
+]
+
+
+def comment(notebook: bool, hashtags: int = 1) -> str:
+    """Get the comment string.
+
+    Parameters
+    ----------
+    notebook : bool
+        Whether the comment is for a notebook or not.
+    hashtags : int, optional
+        The number of hashtags (for notebooks), by default 1.
+
+    Returns
+    -------
+    str
+        The comment string.
+    Example
+    -------
+    ```python
+    >>> comment(True, 2)
+    '## '
+    >>> comment(False)
+    '# '
+    ```
+    """
+    content = "# "
+    if notebook:
+        content += "#" * hashtags + " "
+    return content
+
+
+def get_comment(
+    key: Literal["agents", "skills", "models", "nested", "run", "logging"],
+    for_notebook: bool,
+) -> str:
+    """Get a comment string for some common keys.
+
+    The key is a heading (in a notebook) or just a comment (in a script).
+
+    Parameters
+    ----------
+    key : Literal["agents", "skills", "models", "nested", "run", "logging"]
+        The key.
+    for_notebook : bool
+        Whether the comment is for a notebook.
+
+    Returns
+    -------
+    str
+        The comment string.
+
+    Example
+    -------
+    ```python
+    >>> get_comment("agents", True)
+
+    '## Agents'
+    >>> get_comment("skills", False)
+
+    '# Skills'
+    ```
+    """
+    # pylint: disable=too-many-return-statements
+    if key == "agents":
+        return "\n" + comment(for_notebook, 2) + "Agents\n"
+    if key == "skills":
+        return "\n" + comment(for_notebook, 2) + "Skills\n"
+    if key == "models":
+        return "\n" + comment(for_notebook, 2) + "Models\n"
+    if key == "nested":
+        return "\n" + comment(for_notebook, 2) + "Nested Chats\n"
+    if key == "run":
+        return "\n" + comment(for_notebook, 2) + "Run the flow\n"
+    if key == "logging":
+        return "\n" + comment(for_notebook, 2) + "Start Logging\n"
+    return comment(for_notebook)
+
+
+def get_pylint_ignore_comment(
+    notebook: bool, rules: Optional[List[str]] = None
+) -> str:
+    """Get the pylint ignore comment string.
+
+    Parameters
+    ----------
+    notebook : bool
+        Whether the comment is for a notebook.
+    rules : Optional[List[str]], optional
+        The pylint rules to ignore, by default None.
+
+    Returns
+    -------
+    str
+        The pylint ignore comment string.
+
+    Example
+    -------
+    ```python
+    >>> get_pylint_ignore_comment(True, ["invalid-name", "line-too-long"])
+
+    # pylint: disable=invalid-name, line-too-long
+    ```
+    """
+    if not rules:
+        rules = PYLINT_RULES
+    line = "# pylint: disable=" + ",".join(rules)
+    if notebook is True:
+        line = "\n" + line
+    return line + "\n"

waldiez/exporting/utils/importing.py

@@ -0,0 +1,267 @@
+"""Importing related string generation functions.
+
+Functions
+---------
+add_autogen_dot_import
+    Add an autogen dot import (from autogen.{x.y} import {z}).
+get_imports_string
+    Get the imports for the whole file/flow.
+"""
+
+from typing import Dict, List, Optional, Set, Tuple
+
+DEFAULT_TYPING_IMPORTS = {
+    "Any",
+    "Callable",
+    "Dict",
+    "List",
+    "Optional",
+    "Tuple",
+    "Union",
+}
+
+
+def add_autogen_dot_import(
+    current_imports: Dict[str, List[str]], new_import: Tuple[str, str]
+) -> Dict[str, List[str]]:
+    """Add an autogen dot import (from autogen.{x} import {y}).
+
+    Parameters
+    ----------
+    current_imports : Dict[str, List[str]]
+        The current autogen dot imports.
+    new_import : Tuple[str, str]
+        The new import.
+
+    Returns
+    -------
+    Dict[str, List[str]]
+        The updated imports.
+
+    Example
+    -------
+    ```python
+    >>> current_imports = {"a": ["b", "c"], "d": ["e"]}
+    >>> new_import = ("a", "f")
+    >>> add_autogen_dot_import(current_imports, new_import)
+    {'a': ['b', 'c', 'f'], 'd': ['e']}
+    # and the final string would be:
+    from autogen.a import b, c, f
+    from autogen.d import e
+    ```
+    """
+    dot_part, module_part = new_import
+    if not module_part:
+        return current_imports
+    imports_copy = current_imports.copy()
+    if dot_part not in current_imports:
+        imports_copy[dot_part] = []
+    imports_copy[dot_part].append(module_part)
+    return imports_copy
+
+
+def get_imports_string(
+    imports: Set[str],
+    skill_imports: Set[str],
+    typing_imports: Optional[Set[str]] = None,
+    builtin_imports: Optional[Set[str]] = None,
+    other_imports: Optional[Set[str]] = None,
+) -> str:
+    """Get the imports.
+
+    Parameters
+    ----------
+    imports : Set[str]
+        The flow imports (e.g. from autogen.{x[y.z]} import {w}).
+    skill_imports : Set[str]
+        The skill imports.
+    typing_imports : Set[str], optional
+        The typing imports, by default None.
+    builtin_imports : Set[str], optional
+        The builtin imports, by default None.
+    other_imports : Set[str], optional
+        Other third party imports, by default None.
+
+    Returns
+    -------
+    str
+        The imports string.
+
+    Example
+    -------
+    ```python
+    >>> autogen_imports = {"from autogen import a", "from autogen.b import c"}
+    >>> skill_imports = {"from skill_name import skill_name"}
+    >>> get_imports_string(autogen_imports, skill_imports)
+
+    from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+    from typing_extensions import Annotated
+
+    from autogen import a
+    from autogen.b import c
+
+    from skill_name import skill_name'
+    ```
+    """
+    if not typing_imports:
+        typing_imports = DEFAULT_TYPING_IMPORTS
+    if not builtin_imports:
+        builtin_imports = set()
+    if not other_imports:
+        other_imports = set()
+    string = _get_builtin_imports_string(builtin_imports, typing_imports)
+    string += _get_third_party_imports_string(imports, other_imports)
+    string += _get_skill_imports_string(skill_imports)
+    string = "\n\n".join([line for line in string.split("\n\n") if line])
+    while not string.endswith("\n\n"):
+        string += "\n"
+    return string
+
+
+# pylint: disable=line-too-long
+def _get_builtin_imports_string(
+    builtin_imports: Set[str],
+    typing_imports: Set[str],
+    include_annotations: bool = True,
+) -> str:
+    """Get the builtin imports."""
+    imports = []
+    from_imports = []
+    for imp in sorted(builtin_imports):
+        if imp.startswith("from "):
+            from_imports.append(imp)
+        elif imp.startswith("import "):
+            imports.append(imp)
+        else:
+            imports.append(f"import {imp}")
+    if typing_imports:
+        without_from_typing = []
+        for typing_import in typing_imports:
+            if typing_import.startswith("from typing import "):
+                without_from_typing.extend(
+                    typing_import.split("from typing import ")[1].split(", ")
+                )
+            else:
+                without_from_typing.append(typing_import)
+        from_imports.append(
+            "from typing import "
+            + ", ".join(sorted(without_from_typing))
+            + "  # noqa"
+        )
+        if include_annotations:
+            from_imports.append("from typing_extensions import Annotated")
+    string = (
+        "\n".join(sorted(imports)) + "\n\n" + "\n".join(sorted(from_imports))
+    )
+    return string
+
+
+def _get_autogen_import(import_string: str) -> List[str]:
+    """Get the autogen import.
+
+    In case the import is a "full" import statement,
+    we keep only the module to import.
+    """
+    things = []
+    if import_string.startswith("from autogen import "):
+        import_part = import_string.split("from autogen import ")[1]
+        things = import_part.split(", ")
+    return things
+
+
+def _prepare_imports(
+    autogen_imports: Set[str],
+    autogen_dot_imports: Dict[str, List[str]],
+    other_imports: Set[str],
+) -> Tuple[List[str], Dict[str, List[str]]]:
+    plain_imports = []  # plain `import {x}`
+    autogen_imports_list = []  # from autogen import {y}
+    for autogen_import in autogen_imports:
+        autogen_imports_list.extend(_get_autogen_import(autogen_import))
+    from_imports_dict: Dict[str, List[str]] = {
+        "autogen": autogen_imports_list,
+    }
+    # from autogen.{z} import {w}  # z could be "a.b.c.."
+    for autogen_dot_package, autogen_dot_modules in autogen_dot_imports.items():
+        sub_package = f"autogen.{autogen_dot_package}"
+        if sub_package not in from_imports_dict:
+            from_imports_dict[sub_package] = []
+        from_imports_dict[sub_package].extend(autogen_dot_modules)
+    for imp in other_imports:
+        if imp.startswith("from "):
+            line_parts = imp.split("from ")
+            package = line_parts[1].split(" import ")[0]
+            if package not in from_imports_dict:
+                from_imports_dict[package] = []
+            import_part = line_parts[1].split(" import ")[1]
+            things = import_part.split(", ")
+            from_imports_dict[package].extend(things)
+        elif imp.startswith("import "):
+            plain_imports.append(imp)
+        else:
+            plain_imports.append(f"import {imp}")
+    plain_imports.sort()
+    return plain_imports, from_imports_dict
+
+
+def _get_autogen_imports(
+    imports: Set[str],
+) -> Tuple[Set[str], Dict[str, List[str]], Set[str]]:
+    """Get the autogen imports."""
+    autogen_imports = set()
+    _autogen_dot_imports: Dict[str, List[str]] = {}
+    remaining_imports: Set[str] = set()
+    for imp in imports:
+        if imp.startswith("from autogen import "):
+            autogen_imports.add(imp)
+        elif imp.startswith("from autogen."):
+            parts = imp.split("from autogen.")[1].split(" import ")
+            if len(parts) == 2:
+                package = parts[0]
+                module = parts[1]
+                if package not in _autogen_dot_imports:
+                    _autogen_dot_imports[package] = []
+                _autogen_dot_imports[package].append(module)
+        else:
+            remaining_imports.add(imp)
+    # sort the autogen imports
+    autogen_imports = set(sorted(list(autogen_imports)))
+    autogen_dot_imports = {}
+    # sort the autogen dot imports (both keys and values)
+    sorted_keys = sorted(_autogen_dot_imports.keys())
+    for key in sorted_keys:
+        autogen_dot_imports[key] = sorted(_autogen_dot_imports[key])
+    return autogen_imports, autogen_dot_imports, remaining_imports
+
+
+def _get_third_party_imports_string(
+    imports: Set[str],
+    other_imports: Set[str],
+) -> str:
+    """Get the third party imports."""
+    autogen_imports, autogen_dot_imports, rest = _get_autogen_imports(imports)
+    rest.update(other_imports)
+    plain_imports, from_imports_dict = _prepare_imports(
+        autogen_imports=autogen_imports,
+        autogen_dot_imports=autogen_dot_imports,
+        other_imports=rest,
+    )
+    from_imports = []
+    # pylint: disable=inconsistent-quotes
+    for package, modules in from_imports_dict.items():
+        # remove duplicates
+        modules = sorted(set(modules))
+        if modules:
+            from_imports.append(f"from {package} import {', '.join(modules)}")
+    string = (
+        "\n\n" + "\n".join(plain_imports) + "\n\n" + "\n".join(from_imports)
+    )
+    return string
+
+
+def _get_skill_imports_string(skill_imports: Set[str]) -> str:
+    """Get the skill imports."""
+    if not skill_imports:
+        return ""
+    string = "\n\n" + "\n".join(sorted(skill_imports)) + "\n"
+    return string