waldiez 0.5.1__py3-none-any.whl → 0.5.3__py3-none-any.whl

waldiez/models/tool/predefined/_youtube.py

@@ -0,0 +1,123 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Predefined YouTube search tool for Waldiez."""
+
+import os
+from typing import Any
+
+from ._config import PredefinedToolConfig
+from .protocol import PredefinedTool
+
+
+class YouTubeSearchToolImpl(PredefinedTool):
+    """YouTube search tool for Waldiez."""
+
+    required_secrets: list[str] = ["YOUTUBE_API_KEY"]
+    required_kwargs: dict[str, type] = {
+        "youtube_search_engine_id": str,
+    }
+
+    @property
+    def name(self) -> str:
+        """Tool name."""
+        return "youtube_search"
+
+    @property
+    def description(self) -> str:
+        """Tool description."""
+        return "Search YouTube for a given query."
+
+    @property
+    def kwargs(self) -> dict[str, Any]:
+        """Keyword arguments for the tool, used for initialization."""
+        return {}
+
+    @property
+    def requirements(self) -> list[str]:
+        """Python requirements for the tool."""
+        return ["ag2[google-search, openai]"]
+
+    @property
+    def tags(self) -> list[str]:
+        """Tags for the tool, used for categorization."""
+        return ["youtube", "search", "video", "reference"]
+
+    @property
+    def tool_imports(self) -> list[str]:
+        """Imports required for the tool implementation."""
+        return [
+            "from autogen.tools.experimental import YoutubeSearchTool",
+        ]
+
+    def validate_secrets(self, secrets: dict[str, str]) -> list[str]:
+        """Validate secrets and return list of missing required ones.
+
+        Parameters
+        ----------
+        secrets : dict[str, str]
+            Dictionary of secrets/environment variables.
+
+        Returns
+        -------
+        list[str]
+            List of missing required secrets.
+        """
+        missing: list[str] = []
+        for secret in self.required_secrets:
+            if secret not in secrets:
+                missing.append(secret)
+        return missing
+
+    def validate_kwargs(self, kwargs: dict[str, Any]) -> list[str]:
+        """Validate keyword arguments and return list of missing required ones.
+
+        Parameters
+        ----------
+        kwargs : dict[str, Any]
+            Dictionary of keyword arguments.
+
+        Returns
+        -------
+        list[str]
+            List of missing required keyword arguments.
+        """
+        return []
+
+    def get_content(
+        self,
+        secrets: dict[str, str],
+    ) -> str:
+        """Get content for the tool.
+
+        Parameters
+        ----------
+        secrets : dict[str, str]
+            Dictionary of secrets/environment variables.
+
+        Returns
+        -------
+        str
+            The content for the tool.
+        """
+        os.environ["YOUTUBE_API_KEY"] = secrets.get("YOUTUBE_API_KEY", "")
+        content = f"""
+youtube_api_key = os.environ.get("YOUTUBE_API_KEY", "")
+if not youtube_api_key:
+    raise ValueError("YOUTUBE_API_KEY is required for YouTube search tool.")
+{self.name} = YoutubeSearchTool(
+    youtube_api_key=youtube_api_key,
+)
+"""
+        return content
+
+
+YouTubeSearchTool = YouTubeSearchToolImpl()
+YouTubeSearchConfig = PredefinedToolConfig(
+    name=YouTubeSearchTool.name,
+    description=YouTubeSearchTool.description,
+    required_secrets=YouTubeSearchTool.required_secrets,
+    required_kwargs=YouTubeSearchTool.required_kwargs,
+    requirements=YouTubeSearchTool.requirements,
+    tags=YouTubeSearchTool.tags,
+    implementation=YouTubeSearchTool,
+)

waldiez/models/tool/predefined/protocol.py

@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+
+"""Predefined tool protocol definition for Waldiez."""
+
+# pyright: reportReturnType=false
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class PredefinedTool(Protocol):
+    """Protocol for predefined tools in Waldiez."""
+
+    required_secrets: list[str]
+    required_kwargs: dict[str, type]
+
+    @property
+    def name(self) -> str:
+        """Tool name."""
+
+    @property
+    def description(self) -> str:
+        """Tool description."""
+
+    @property
+    def requirements(self) -> list[str]:
+        """Python requirements for the tool."""
+
+    @property
+    def tags(self) -> list[str]:
+        """Tags for the tool, used for categorization."""
+
+    @property
+    def tool_imports(self) -> list[str]:
+        """Imports required for the tool implementation."""
+
+    def get_content(
+        self,
+        secrets: dict[str, str],
+    ) -> str:
+        """Get the content of the tool.
+
+        Parameters
+        ----------
+        secrets : dict[str, str]
+            Dictionary of secrets/environment variables.
+
+        Returns
+        -------
+        str
+            Content of the tool.
+        """
+
+    def validate_secrets(self, secrets: dict[str, str]) -> list[str]:
+        """Validate secrets and return list of missing required ones.
+
+        Parameters
+        ----------
+        secrets : dict[str, str]
+            Dictionary of secrets/environment variables.
+
+        Returns
+        -------
+        list[str]
+            List of missing required secrets.
+        """
+
+    def validate_kwargs(self, kwargs: dict[str, Any]) -> list[str]:
+        """Validate keyword arguments and return list of missing required ones.
+
+        Parameters
+        ----------
+        kwargs : dict[str, Any]
+            Dictionary of keyword arguments.
+
+        Returns
+        -------
+        list[str]
+            List of missing required keyword arguments.
+
+        Raises
+        ------
+        ValueError
+            If any required keyword arguments are missing or of incorrect type.
+        """

waldiez/models/tool/predefined/registry.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Predefined tools registry for Waldiez."""
+
+from ._config import PredefinedToolConfig
+from ._google import GoogleSearchConfig
+from ._tavily import TavilySearchConfig
+from ._wikipedia import WikipediaSearchConfig
+from ._youtube import YouTubeSearchConfig
+
+PREDEFINED_TOOLS: dict[str, PredefinedToolConfig] = {
+    GoogleSearchConfig.name: GoogleSearchConfig,
+    WikipediaSearchConfig.name: WikipediaSearchConfig,
+    YouTubeSearchConfig.name: YouTubeSearchConfig,
+    TavilySearchConfig.name: TavilySearchConfig,
+}
+
+
+def get_predefined_tool_config(tool_name: str) -> PredefinedToolConfig | None:
+    """Get configuration for a predefined tool.
+
+    Parameters
+    ----------
+    tool_name : str
+        Name of the tool to retrieve configuration for.
+
+    Returns
+    -------
+    PredefinedToolConfig | None
+        Configuration of the tool if it exists, otherwise None.
+    """
+    return PREDEFINED_TOOLS.get(tool_name)
+
+
+def get_predefined_tool_requirements(tool_name: str) -> list[str]:
+    """Get requirements for a predefined tool.
+
+    Parameters
+    ----------
+    tool_name : str
+        Name of the tool to retrieve requirements for.
+
+    Returns
+    -------
+    list[str]
+        List of requirements for the tool,
+        or an empty list if the tool does not exist.
+    """
+    config = get_predefined_tool_config(tool_name)
+    return config.requirements if config else []
+
+
+def get_predefined_tool_imports(tool_name: str) -> list[str]:
+    """Get imports for a predefined tool.
+
+    Parameters
+    ----------
+    tool_name : str
+        Name of the tool to retrieve imports for.
+
+    Returns
+    -------
+    list[str]
+        List of imports for the tool,
+        or an empty list if the tool does not exist.
+    """
+    config = get_predefined_tool_config(tool_name)
+    return config.implementation.tool_imports if config else []
+
+
+def list_predefined_tools() -> list[str]:
+    """List all available predefined tools.
+
+    Returns
+    -------
+    list[str]
+        List of all predefined tool names.
+    """
+    return list(PREDEFINED_TOOLS.keys())

waldiez/models/tool/tool.py

@@ -17,6 +17,10 @@ from ..common import (
     now,
     parse_code_string,
 )
+from .predefined import (
+    get_predefined_tool_config,
+    list_predefined_tools,
+)
 from .tool_data import WaldiezToolData
 from .tool_type import WaldiezToolType
 
@@ -179,6 +183,17 @@ class WaldiezTool(WaldiezBase):
         """
         return self.tool_type == "shared" or self.name == SHARED_TOOL_NAME
 
+    @property
+    def is_predefined(self) -> bool:
+        """Check if the tool is predefined.
+
+        Returns
+        -------
+        bool
+            True if the tool is predefined, False otherwise.
+        """
+        return self.tool_type == "predefined"
+
     @property
     def is_interop(self) -> bool:
         """Check if the tool is interoperability.
@@ -190,6 +205,16 @@ class WaldiezTool(WaldiezBase):
         """
         return self.tool_type in ("langchain", "crewai")
 
+    @property
+    def content(self) -> str:
+        """Get the content (source) of the tool."""
+        return self.data.content
+
+    @property
+    def secrets(self) -> dict[str, str]:
+        """Get the secrets (environment variables) of the tool."""
+        return self.data.secrets or {}
+
     def get_content(self) -> str:
         """Get the content of the tool.
 
@@ -198,11 +223,26 @@ class WaldiezTool(WaldiezBase):
         str
             The content of the tool.
         """
+        if self.is_predefined:
+            return self._generate_predefined_content()
         if self.is_shared or self.is_interop:
             return self.data.content
         # if custom, only the function content
         return get_function(self.data.content, self.name)
 
+    def _generate_predefined_content(self) -> str:
+        """Generate the content for a predefined tool.
+
+        Returns
+        -------
+        str
+            The content of the predefined tool.
+        """
+        config = get_predefined_tool_config(self.name)
+        if not config:
+            return ""
+        return config.get_content(self.data.secrets)
+
     def _validate_interop_tool(self) -> None:
         """Validate the interoperability tool.
 
@@ -253,6 +293,50 @@ class WaldiezTool(WaldiezBase):
             if error is not None or tree is None:
                 raise ValueError(f"Invalid tool content: {error}")
 
+    def _validate_predefined_tool(self) -> None:
+        """Validate a predefined tool.
+
+        Raises
+        ------
+        ValueError
+            If the tool name is not in the content.
+            If the tool content is invalid.
+        """
+        if self.is_predefined:
+            config = get_predefined_tool_config(self.name)
+            if not config:
+                available_tools = list_predefined_tools()
+                raise ValueError(
+                    f"Unknown predefined tool: {self.name}. "
+                    f"Available tools: {available_tools}"
+                )
+            missing_secrets = config.validate_secrets(self.data.secrets)
+            if missing_secrets:
+                raise ValueError(
+                    f"Missing required secrets for {self.name}: "
+                    f"{missing_secrets}"
+                )
+            invalid_kwargs = config.validate_kwargs(self.data.kwargs)
+            if invalid_kwargs:
+                raise ValueError(
+                    f"Invalid keyword arguments for {self.name}: "
+                    f"{invalid_kwargs}"
+                )
+            # Update tool metadata from predefined config
+            if not self.description:
+                self.description = config.description
+
+            # Merge requirements
+            predefined_reqs = set(config.requirements)
+            existing_reqs = set(self.requirements)
+            self.requirements = list(predefined_reqs | existing_reqs)
+
+            # Merge tags
+            predefined_tags = set(config.tags)
+            existing_tags = set(self.tags)
+            self.tags = list(predefined_tags | existing_tags)
+            self.data.content = config.get_content(self.data.secrets)
+
     @model_validator(mode="after")
     def validate_data(self) -> Self:
         """Validate the data.
@@ -270,9 +354,18 @@ class WaldiezTool(WaldiezBase):
         """
         self._validate_custom_tool()
         self._validate_interop_tool()
-        self._tool_imports = gather_code_imports(
-            self.data.content, self.is_interop
-        )
+        self._validate_predefined_tool()
+        if self.is_predefined:
+            config = get_predefined_tool_config(self.name)
+            if config:
+                self._tool_imports = (
+                    ["import os"],
+                    config.implementation.tool_imports,
+                )
+        else:
+            self._tool_imports = gather_code_imports(
+                self.data.content, self.is_interop
+            )
         # remove the imports from the content
         # we will place them at the top of the file
         all_imports = self._tool_imports[0] + self._tool_imports[1]
@@ -290,13 +383,3 @@ class WaldiezTool(WaldiezBase):
             valid_lines.pop()
         self.data.content = "\n".join(valid_lines)
         return self
-
-    @property
-    def content(self) -> str:
-        """Get the content (source) of the tool."""
-        return self.data.content
-
-    @property
-    def secrets(self) -> dict[str, str]:
-        """Get the secrets (environment variables) of the tool."""
-        return self.data.secrets or {}

waldiez/models/tool/tool_data.py

@@ -2,6 +2,8 @@
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
 """Waldiez Tool model."""
 
+from typing import Any
+
 from pydantic import Field
 from typing_extensions import Annotated
 
@@ -49,3 +51,13 @@ class WaldiezToolData(WaldiezBase):
             description="The secrets (environment variables) of the tool.",
         ),
     ]
+    kwargs: Annotated[
+        dict[str, Any],
+        Field(
+            default_factory=dict,
+            title="Keyword Arguments",
+            description=(
+                "Keyword arguments for the tool, used for initialization."
+            ),
+        ),
+    ] = {}

waldiez/models/tool/tool_type.py

@@ -4,5 +4,7 @@
 
 from typing_extensions import Literal
 
-WaldiezToolType = Literal["shared", "custom", "langchain", "crewai"]
+WaldiezToolType = Literal[
+    "shared", "custom", "langchain", "crewai", "predefined"
+]
 """Possible types of a Waldiez Tool."""

waldiez/runner.py

@@ -222,6 +222,7 @@ class WaldiezRunner(WaldiezBaseRunner):
         output_file: Path,
         uploads_root: Path | None,
         skip_mmd: bool = False,
+        skip_timeline: bool = False,
     ) -> Union[
         "ChatResult",
         list["ChatResult"],
@@ -239,6 +240,8 @@ class WaldiezRunner(WaldiezBaseRunner):
             The runtime uploads root.
         skip_mmd : bool
             Whether to skip generating the mermaid diagram.
+        skip_timeline : bool
+            Whether to skip generating the timeline JSON.
 
         Returns
         -------
@@ -252,6 +255,7 @@ class WaldiezRunner(WaldiezBaseRunner):
             output_file=output_file,
             uploads_root=uploads_root,
             skip_mmd=skip_mmd,
+            skip_timeline=skip_timeline,
         )
 
     async def _a_run(
@@ -260,6 +264,7 @@ class WaldiezRunner(WaldiezBaseRunner):
         output_file: Path,
         uploads_root: Path | None,
         skip_mmd: bool,
+        skip_timeline: bool,
     ) -> Union[
         "ChatResult",
         list["ChatResult"],
@@ -277,6 +282,8 @@ class WaldiezRunner(WaldiezBaseRunner):
             The runtime uploads root.
         skip_mmd : bool
             Whether to skip generating the mermaid diagram.
+        skip_timeline : bool
+            Whether to skip generating the timeline JSON.
 
         Returns
         -------
@@ -290,6 +297,7 @@ class WaldiezRunner(WaldiezBaseRunner):
             output_file=output_file,
             uploads_root=uploads_root,
             skip_mmd=skip_mmd,
+            skip_timeline=skip_timeline,
         )
 
     def _after_run(
@@ -303,6 +311,7 @@ class WaldiezRunner(WaldiezBaseRunner):
         uploads_root: Path | None,
         temp_dir: Path,
         skip_mmd: bool,
+        skip_timeline: bool,
     ) -> None:
         """Actions to perform after running the flow.
 
@@ -322,13 +331,16 @@ class WaldiezRunner(WaldiezBaseRunner):
             The path to the temporary directory created for the run.
         skip_mmd : bool
             Whether to skip generating the mermaid diagram.
+        skip_timeline : bool
+            Whether to skip generating the timeline JSON.
         """
         self._implementation._after_run(
             results,
             output_file,
             uploads_root,
             temp_dir,
-            skip_mmd,
+            skip_mmd=skip_mmd,
+            skip_timeline=skip_timeline,
         )
 
     async def _a_after_run(
@@ -342,6 +354,7 @@ class WaldiezRunner(WaldiezBaseRunner):
         uploads_root: Path | None,
         temp_dir: Path,
         skip_mmd: bool,
+        skip_timeline: bool,
     ) -> None:
         """Asynchronously perform actions after running the flow.
 
@@ -357,13 +370,16 @@ class WaldiezRunner(WaldiezBaseRunner):
             The path to the temporary directory created for the run.
         skip_mmd : bool
             Whether to skip generating the mermaid diagram.
+        skip_timeline : bool
+            Whether to skip generating the timeline JSON.
         """
         await self._implementation._a_after_run(
             results,
             output_file,
             uploads_root,
             temp_dir,
-            skip_mmd,
+            skip_mmd=skip_mmd,
+            skip_timeline=skip_timeline,
         )
 
     def start(
@@ -373,6 +389,7 @@ class WaldiezRunner(WaldiezBaseRunner):
         structured_io: bool | None = None,
         skip_patch_io: bool | None = None,
         skip_mmd: bool = False,
+        skip_timeline: bool = False,
     ) -> None:
         """Start the flow.
 
@@ -390,12 +407,16 @@ class WaldiezRunner(WaldiezBaseRunner):
             If None, it will use the value from the context.
         skip_mmd : bool = False
             Whether to skip generating the mermaid diagram.
+        skip_timeline : bool = False
+            Whether to skip generating the timeline JSON.
         """
         self._implementation.start(
             output_path=output_path,
             uploads_root=uploads_root,
             structured_io=structured_io,
             skip_patch_io=skip_patch_io,
+            skip_mmd=skip_mmd,
+            skip_timeline=skip_timeline,
         )
 
     def _start(
@@ -404,6 +425,7 @@ class WaldiezRunner(WaldiezBaseRunner):
         output_file: Path,
         uploads_root: Path | None,
         skip_mmd: bool,
+        skip_timeline: bool,
     ) -> None:
         """Start the flow.
 
@@ -415,12 +437,15 @@ class WaldiezRunner(WaldiezBaseRunner):
             The runtime uploads root.
         skip_mmd : bool
             Whether to skip generating the mermaid diagram.
+        skip_timeline : bool
+            Whether to skip generating the timeline JSON.
         """
         self._implementation._start(
             temp_dir=temp_dir,
             output_file=output_file,
             uploads_root=uploads_root,
             skip_mmd=skip_mmd,
+            skip_timeline=skip_timeline,
         )
 
     async def a_start(
@@ -430,6 +455,7 @@ class WaldiezRunner(WaldiezBaseRunner):
         structured_io: bool | None = None,
         skip_patch_io: bool | None = None,
         skip_mmd: bool = False,
+        skip_timeline: bool = False,
     ) -> None:
         """Asynchronously start the flow.
 
@@ -445,6 +471,8 @@ class WaldiezRunner(WaldiezBaseRunner):
             Whether to skip patching I/O, by default None.
         skip_mmd : bool = False
             Whether to skip generating the mermaid diagram, by default False.
+        skip_timeline : bool = False
+            Whether to skip generating the timeline JSON, by default False.
         """
         await self._implementation.a_start(
             output_path=output_path,
@@ -452,6 +480,7 @@ class WaldiezRunner(WaldiezBaseRunner):
             structured_io=structured_io,
             skip_patch_io=skip_patch_io,
             skip_mmd=skip_mmd,
+            skip_timeline=skip_timeline,
         )
 
     async def _a_start(
@@ -460,6 +489,7 @@ class WaldiezRunner(WaldiezBaseRunner):
         output_file: Path,
         uploads_root: Path | None,
         skip_mmd: bool,
+        skip_timeline: bool = False,
     ) -> None:
         """Asynchronously start the flow.
 
@@ -473,12 +503,15 @@ class WaldiezRunner(WaldiezBaseRunner):
             The runtime uploads root.
         skip_mmd : bool
             Whether to skip generating the mermaid diagram.
+        skip_timeline : bool, optional
+            Whether to skip generating the timeline JSON, by default False.
         """
         await self._implementation._a_start(
             temp_dir=temp_dir,
             output_file=output_file,
             uploads_root=uploads_root,
             skip_mmd=skip_mmd,
+            skip_timeline=skip_timeline,
         )
 
     def _stop(self) -> None: