devduck 0.1.0__py3-none-any.whl → 0.1.1766644714__py3-none-any.whl

devduck/tools/fetch_github_tool.py

@@ -0,0 +1,201 @@
+"""GitHub Tool Fetcher for Strands Agent.
+
+This tool fetches Python tool files from GitHub repositories and loads them
+as available tools in the current Strands agent. It combines HTTP fetching
+with the load_tool functionality to enable dynamic tool loading from remote
+GitHub repositories.
+
+Usage with Strands Agents:
+python
+from strands import Agent
+from tools.fetch_github_tool import fetch_github_tool
+
+agent = Agent(tools=[fetch_github_tool])
+
+# Fetch and load a tool from GitHub
+agent.tool.fetch_github_tool(
+    github_url="https://github.com/owner/repo/blob/main/tools/my_tool.py",
+    tool_name="my_tool"
+)
+
+# Now you can use the fetched tool
+agent.tool.my_tool(param1="value")
+
+
+Supported GitHub URL formats:
+- https://github.com/owner/repo/blob/branch/path/to/file.py
+- https://github.com/owner/repo/tree/branch/path/to/file.py
+- https://raw.githubusercontent.com/owner/repo/branch/path/to/file.py
+"""
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import requests
+from strands import tool
+
+
+def parse_github_url(github_url: str) -> dict[str, str]:
+    """Parse GitHub URL to extract repository information.
+
+    Args:
+        github_url: GitHub URL to the file
+
+    Returns:
+        Dictionary with owner, repo, branch, and file_path
+
+    Raises:
+        ValueError: If URL format is not supported
+    """
+    # Handle raw.githubusercontent.com URLs
+    raw_pattern = r"https://raw\.githubusercontent\.com/([^/]+)/([^/]+)/([^/]+)/(.+)"
+    raw_match = re.match(raw_pattern, github_url)
+
+    if raw_match:
+        owner, repo, branch, file_path = raw_match.groups()
+        return {"owner": owner, "repo": repo, "branch": branch, "file_path": file_path}
+
+    # Handle github.com/owner/repo/blob/branch/path URLs
+    blob_pattern = r"https://github\.com/([^/]+)/([^/]+)/(?:blob|tree)/([^/]+)/(.+)"
+    blob_match = re.match(blob_pattern, github_url)
+
+    if blob_match:
+        owner, repo, branch, file_path = blob_match.groups()
+        return {"owner": owner, "repo": repo, "branch": branch, "file_path": file_path}
+
+    raise ValueError(f"Unsupported GitHub URL format: {github_url}")
+
+
+def build_raw_url(owner: str, repo: str, branch: str, file_path: str) -> str:
+    """Build GitHub raw content URL.
+
+    Args:
+        owner: Repository owner
+        repo: Repository name
+        branch: Branch name
+        file_path: Path to file in repository
+
+    Returns:
+        Raw GitHub URL for the file
+    """
+    return f"https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{file_path}"
+
+
+@tool
+def fetch_github_tool(
+    github_url: str,
+    tool_name: str | None = None,
+    local_dir: str = "./github_tools",
+    agent: Any = None,
+) -> dict[str, Any]:
+    """Fetch a Python tool file from GitHub and load it as a Strands tool.
+
+    This tool downloads Python files from GitHub repositories, saves them locally,
+    and registers them as available tools in the current Strands agent. It supports
+    various GitHub URL formats and automatically handles the conversion to raw content URLs.
+
+    Args:
+        github_url: GitHub URL to the Python tool file. Supports formats like:
+            - https://github.com/owner/repo/blob/main/tools/my_tool.py
+            - https://github.com/owner/repo/tree/main/tools/my_tool.py
+            - https://raw.githubusercontent.com/owner/repo/main/tools/my_tool.py
+        tool_name: Name to register the tool under. If not provided, will extract
+            from the filename (e.g., "my_tool.py" becomes "my_tool")
+        local_dir: Local directory to save the fetched tool file. Defaults to "./github_tools"
+        agent: Agent instance (automatically provided by Strands)
+
+    Returns:
+        Dict containing status and response content:
+        {
+            "status": "success|error",
+            "content": [{"text": "Response message"}]
+        }
+
+    Examples:
+        # Fetch a tool from GitHub and load it
+        agent.tool.fetch_github_tool(
+            github_url="https://github.com/cagataycali/my-tools/blob/main/weather_tool.py",
+            tool_name="weather"
+        )
+
+        # Tool name can be auto-detected from filename
+        agent.tool.fetch_github_tool(
+            github_url="https://github.com/cagataycali/my-tools/blob/main/calculator.py"
+        )
+    """
+    try:
+        # Parse the GitHub URL
+        try:
+            url_info = parse_github_url(github_url)
+        except ValueError as e:
+            return {"status": "error", "content": [{"text": f"❌ {e!s}"}]}
+
+        # Extract tool name from filename if not provided
+        if not tool_name:
+            filename = os.path.basename(url_info["file_path"])
+            tool_name = os.path.splitext(filename)[0]
+
+        # Check if it's a Python file first (before making HTTP request)
+        if not url_info["file_path"].endswith(".py"):
+            return {
+                "status": "error",
+                "content": [
+                    {
+                        "text": f"❌ File must be a Python file (.py), got: {url_info['file_path']}"
+                    }
+                ],
+            }
+
+        # Build raw GitHub URL
+        raw_url = build_raw_url(
+            url_info["owner"],
+            url_info["repo"],
+            url_info["branch"],
+            url_info["file_path"],
+        )
+
+        # Create local directory if it doesn't exist
+        local_path = Path(local_dir)
+        local_path.mkdir(parents=True, exist_ok=True)
+
+        # Download the file
+        response = requests.get(raw_url, timeout=30)
+        response.raise_for_status()
+        # Save the file locally
+        local_file_path = local_path / f"{tool_name}.py"
+        with open(local_file_path, "w", encoding="utf-8") as f:
+            f.write(response.text)
+
+        # Load the tool using load_tool functionality
+        if agent and hasattr(agent, "tool_registry"):
+            agent.tool_registry.load_tool_from_filepath(
+                tool_name=tool_name, tool_path=str(local_file_path)
+            )
+
+            success_message = f"""✅ Successfully fetched and loaded GitHub tool!
+
+📂 **Source:** {github_url}
+🏷️  **Tool Name:** {tool_name}
+💾 **Local Path:** {local_file_path}
+🔧 **Status:** Ready to use
+
+You can now use the tool with: agent.tool.{tool_name}(...)"""
+
+            return {"status": "success", "content": [{"text": success_message}]}
+        else:
+            return {
+                "status": "error",
+                "content": [
+                    {"text": "❌ Agent instance not available for tool registration"}
+                ],
+            }
+
+    except requests.RequestException as e:
+        return {
+            "status": "error",
+            "content": [{"text": f"❌ Failed to download file from GitHub: {e!s}"}],
+        }
+    except Exception as e:
+        return {"status": "error", "content": [{"text": f"❌ Unexpected error: {e!s}"}]}

devduck/tools/install_tools.py

@@ -0,0 +1,409 @@
+"""Dynamic Tool Installation for DevDuck.
+
+Install and load tools from any Python package at runtime, expanding DevDuck's
+capabilities on-the-fly without requiring restarts.
+"""
+
+import importlib
+import logging
+import subprocess
+import sys
+from typing import Any, Dict, List, Optional
+
+from strands import tool
+
+logger = logging.getLogger(__name__)
+
+
+@tool
+def install_tools(
+    action: str,
+    package: Optional[str] = None,
+    module: Optional[str] = None,
+    tool_names: Optional[List[str]] = None,
+    agent: Any = None,
+) -> Dict[str, Any]:
+    """Install and load tools from Python packages dynamically.
+
+    This tool allows DevDuck to expand its capabilities by installing Python packages
+    and loading their tools into the agent's registry at runtime.
+
+    Args:
+        action: Action to perform - "install", "load", "install_and_load", "list_loaded", "list_available"
+        package: Python package to install (e.g., "strands-agents-tools", "strands-fun-tools")
+        module: Module to import tools from (e.g., "strands_tools", "strands_fun_tools")
+        tool_names: Optional list of specific tools to load. If None, loads all available tools
+        agent: Parent agent instance (auto-injected by Strands framework)
+
+    Returns:
+        Result dictionary with status and content
+
+    Examples:
+        # List available tools in a package (without loading)
+        install_tools(
+            action="list_available",
+            package="strands-fun-tools",
+            module="strands_fun_tools"
+        )
+
+        # Install and load all tools from strands-agents-tools
+        install_tools(
+            action="install_and_load",
+            package="strands-agents-tools",
+            module="strands_tools"
+        )
+
+        # Install and load specific tools
+        install_tools(
+            action="install_and_load",
+            package="strands-fun-tools",
+            module="strands_fun_tools",
+            tool_names=["clipboard", "cursor", "bluetooth"]
+        )
+
+        # Load tools from already installed package
+        install_tools(
+            action="load",
+            module="strands_tools",
+            tool_names=["shell", "calculator"]
+        )
+
+        # List currently loaded tools
+        install_tools(action="list_loaded")
+    """
+    try:
+        if action == "install":
+            return _install_package(package)
+        elif action == "load":
+            return _load_tools_from_module(module, tool_names, agent)
+        elif action == "install_and_load":
+            # Install first
+            install_result = _install_package(package)
+            if install_result["status"] == "error":
+                return install_result
+
+            # Then load
+            return _load_tools_from_module(module, tool_names, agent)
+        elif action == "list_loaded":
+            return _list_loaded_tools(agent)
+        elif action == "list_available":
+            return _list_available_tools(package, module)
+        else:
+            return {
+                "status": "error",
+                "content": [
+                    {
+                        "text": f"❌ Unknown action: {action}\n\n"
+                        f"Valid actions: install, load, install_and_load, list_loaded, list_available"
+                    }
+                ],
+            }
+
+    except Exception as e:
+        logger.exception("Error in install_tools")
+        return {"status": "error", "content": [{"text": f"❌ Error: {str(e)}"}]}
+
+
+def _install_package(package: str) -> Dict[str, Any]:
+    """Install a Python package using pip."""
+    if not package:
+        return {
+            "status": "error",
+            "content": [
+                {"text": "❌ package parameter is required for install action"}
+            ],
+        }
+
+    try:
+        logger.info(f"Installing package: {package}")
+
+        # Use subprocess to install the package
+        result = subprocess.run(
+            [sys.executable, "-m", "pip", "install", package],
+            capture_output=True,
+            text=True,
+            timeout=300,  # 5 minute timeout
+        )
+
+        if result.returncode != 0:
+            return {
+                "status": "error",
+                "content": [
+                    {"text": f"❌ Failed to install {package}:\n{result.stderr}"}
+                ],
+            }
+
+        logger.info(f"Successfully installed: {package}")
+
+        return {
+            "status": "success",
+            "content": [{"text": f"✅ Successfully installed package: {package}"}],
+        }
+
+    except subprocess.TimeoutExpired:
+        return {
+            "status": "error",
+            "content": [
+                {"text": f"❌ Installation of {package} timed out (>5 minutes)"}
+            ],
+        }
+    except Exception as e:
+        logger.exception(f"Error installing package {package}")
+        return {
+            "status": "error",
+            "content": [{"text": f"❌ Failed to install {package}: {str(e)}"}],
+        }
+
+
+def _load_tools_from_module(
+    module: str, tool_names: Optional[List[str]], agent: Any
+) -> Dict[str, Any]:
+    """Load tools from a Python module into the agent's registry."""
+    if not module:
+        return {
+            "status": "error",
+            "content": [{"text": "❌ module parameter is required for load action"}],
+        }
+
+    if not agent:
+        return {
+            "status": "error",
+            "content": [{"text": "❌ agent instance is required for load action"}],
+        }
+
+    if not hasattr(agent, "tool_registry") or not hasattr(
+        agent.tool_registry, "register_tool"
+    ):
+        return {
+            "status": "error",
+            "content": [{"text": "❌ Agent does not have a tool registry"}],
+        }
+
+    try:
+        # Import the module
+        logger.info(f"Importing module: {module}")
+        imported_module = importlib.import_module(module)
+
+        # Get all tool objects from the module
+        available_tools = {}
+        for attr_name in dir(imported_module):
+            attr = getattr(imported_module, attr_name)
+            # Check if it's a tool (has tool_name and tool_spec attributes)
+            if hasattr(attr, "tool_name") and hasattr(attr, "tool_spec"):
+                available_tools[attr.tool_name] = attr
+
+        if not available_tools:
+            return {
+                "status": "error",
+                "content": [{"text": f"❌ No tools found in module: {module}"}],
+            }
+
+        # Filter tools if specific ones requested
+        if tool_names:
+            tools_to_load = {
+                name: tool
+                for name, tool in available_tools.items()
+                if name in tool_names
+            }
+            missing_tools = set(tool_names) - set(tools_to_load.keys())
+            if missing_tools:
+                return {
+                    "status": "error",
+                    "content": [
+                        {
+                            "text": f"❌ Requested tools not found: {', '.join(missing_tools)}\n\n"
+                            f"Available tools: {', '.join(available_tools.keys())}"
+                        }
+                    ],
+                }
+        else:
+            tools_to_load = available_tools
+
+        # Load tools into agent registry
+        loaded_tools = []
+        skipped_tools = []
+
+        for tool_name, tool_obj in tools_to_load.items():
+            try:
+                # Check if tool already exists
+                existing_tools = agent.tool_registry.get_all_tools_config()
+                if tool_name in existing_tools:
+                    skipped_tools.append(f"{tool_name} (already loaded)")
+                    continue
+
+                # Register the tool
+                agent.tool_registry.register_tool(tool_obj)
+                loaded_tools.append(tool_name)
+                logger.info(f"Loaded tool: {tool_name}")
+
+            except Exception as e:
+                skipped_tools.append(f"{tool_name} (error: {str(e)})")
+                logger.error(f"Failed to load tool {tool_name}: {e}")
+
+        # Build result message
+        result_lines = [f"✅ Loaded {len(loaded_tools)} tools from {module}"]
+
+        if loaded_tools:
+            result_lines.append(f"\n📦 Loaded tools:")
+            for tool_name in loaded_tools:
+                result_lines.append(f"  • {tool_name}")
+
+        if skipped_tools:
+            result_lines.append(f"\n⚠️  Skipped tools:")
+            for skip_msg in skipped_tools:
+                result_lines.append(f"  • {skip_msg}")
+
+        result_lines.append(
+            f"\n🔧 Total available tools: {len(existing_tools) + len(loaded_tools)}"
+        )
+
+        return {"status": "success", "content": [{"text": "\n".join(result_lines)}]}
+
+    except ImportError as e:
+        logger.exception(f"Failed to import module {module}")
+        return {
+            "status": "error",
+            "content": [
+                {
+                    "text": f"❌ Failed to import module {module}: {str(e)}\n\n"
+                    f"Make sure the package is installed first using action='install'"
+                }
+            ],
+        }
+    except Exception as e:
+        logger.exception(f"Error loading tools from {module}")
+        return {
+            "status": "error",
+            "content": [{"text": f"❌ Failed to load tools: {str(e)}"}],
+        }
+
+
+def _list_loaded_tools(agent: Any) -> Dict[str, Any]:
+    """List all currently loaded tools in the agent."""
+    if not agent:
+        return {
+            "status": "error",
+            "content": [{"text": "❌ agent instance is required"}],
+        }
+
+    if not hasattr(agent, "tool_registry"):
+        return {
+            "status": "error",
+            "content": [{"text": "❌ Agent does not have a tool registry"}],
+        }
+
+    try:
+        all_tools = agent.tool_registry.get_all_tools_config()
+
+        result_lines = [f"🔧 **Loaded Tools ({len(all_tools)})**\n"]
+
+        # Group tools by category (if available)
+        for tool_name, tool_spec in sorted(all_tools.items()):
+            description = tool_spec.get("description", "No description available")
+            # Truncate long descriptions
+            if len(description) > 100:
+                description = description[:97] + "..."
+
+            result_lines.append(f"**{tool_name}**")
+            result_lines.append(f"  {description}\n")
+
+        return {"status": "success", "content": [{"text": "\n".join(result_lines)}]}
+
+    except Exception as e:
+        logger.exception("Error listing loaded tools")
+        return {
+            "status": "error",
+            "content": [{"text": f"❌ Failed to list tools: {str(e)}"}],
+        }
+
+
+def _list_available_tools(package: Optional[str], module: str) -> Dict[str, Any]:
+    """List available tools in a package without loading them."""
+    if not module:
+        return {
+            "status": "error",
+            "content": [
+                {"text": "❌ module parameter is required for list_available action"}
+            ],
+        }
+
+    try:
+        # Try to import the module
+        try:
+            imported_module = importlib.import_module(module)
+            logger.info(f"Module {module} already installed")
+        except ImportError:
+            # Module not installed - try to install package first
+            if not package:
+                return {
+                    "status": "error",
+                    "content": [
+                        {
+                            "text": f"❌ Module {module} not found and no package specified to install.\n\n"
+                            f"Please provide the 'package' parameter to install first."
+                        }
+                    ],
+                }
+
+            logger.info(f"Module {module} not found, installing package {package}")
+            install_result = _install_package(package)
+            if install_result["status"] == "error":
+                return install_result
+
+            # Try importing again after installation
+            try:
+                imported_module = importlib.import_module(module)
+            except ImportError as e:
+                return {
+                    "status": "error",
+                    "content": [
+                        {
+                            "text": f"❌ Failed to import {module} even after installing {package}: {str(e)}"
+                        }
+                    ],
+                }
+
+        # Discover tools in the module
+        available_tools = {}
+        for attr_name in dir(imported_module):
+            attr = getattr(imported_module, attr_name)
+            # Check if it's a tool (has tool_name and tool_spec attributes)
+            if hasattr(attr, "tool_name") and hasattr(attr, "tool_spec"):
+                tool_spec = attr.tool_spec
+                description = tool_spec.get("description", "No description available")
+                available_tools[attr.tool_name] = description
+
+        if not available_tools:
+            return {
+                "status": "success",
+                "content": [{"text": f"⚠️  No tools found in module: {module}"}],
+            }
+
+        # Build result message
+        result_lines = [
+            f"📦 **Available Tools in {module} ({len(available_tools)})**\n"
+        ]
+
+        for tool_name, description in sorted(available_tools.items()):
+            # Truncate long descriptions
+            if len(description) > 100:
+                description = description[:97] + "..."
+
+            result_lines.append(f"**{tool_name}**")
+            result_lines.append(f"  {description}\n")
+
+        result_lines.append(f"\n💡 To load these tools, use:")
+        result_lines.append(f"   install_tools(action='load', module='{module}')")
+        result_lines.append(f"   # Or load specific tools:")
+        result_lines.append(
+            f"   install_tools(action='load', module='{module}', tool_names=['tool1', 'tool2'])"
+        )
+
+        return {"status": "success", "content": [{"text": "\n".join(result_lines)}]}
+
+    except Exception as e:
+        logger.exception(f"Error listing available tools from {module}")
+        return {
+            "status": "error",
+            "content": [{"text": f"❌ Failed to list available tools: {str(e)}"}],
+        }