a4e 0.1.5__py3-none-any.whl

a4e/tools/agent_tools/add_tool.py

@@ -0,0 +1,115 @@
+"""
+Add tool tool.
+
+Creates tools with the params: Dict[str, Any] pattern required by the A4E main application.
+Also includes exec() compatibility helpers for proper module loading.
+"""
+
+from typing import Optional
+
+from ...core import mcp, jinja_env, get_project_dir
+
+
+@mcp.tool()
+def add_tool(
+    tool_name: str, description: str, parameters: dict, agent_name: Optional[str] = None
+) -> dict:
+    """
+    Add a new tool with params: Dict[str, Any] signature (A4E compatible)
+
+    Args:
+        tool_name: Name of the tool (snake_case)
+        description: What the tool does
+        parameters: Dictionary of parameters with types and descriptions
+        agent_name: Optional agent ID if not in agent directory
+    
+    The generated tool will use the params dict pattern:
+        def tool_name(params: Dict[str, Any]) -> Dict[str, Any]
+    
+    This is required for compatibility with the A4E main application's
+    exec() context and tool wrapping system.
+    """
+    # Validate tool name
+    if not tool_name.replace("_", "").isalnum():
+        suggested = tool_name.replace("-", "_").replace(" ", "_").lower()
+        return {
+            "success": False,
+            "error": "Tool name must be alphanumeric with underscores",
+            "fix": f"Try: {suggested}",
+        }
+
+    project_dir = get_project_dir(agent_name)
+    tools_dir = project_dir / "tools"
+
+    if not tools_dir.exists():
+        return {
+            "success": False,
+            "error": f"tools/ directory not found at {tools_dir}",
+            "fix": "Initialize an agent first with initialize_project() or specify agent_name",
+        }
+
+    tool_file = tools_dir / f"{tool_name}.py"
+    if tool_file.exists():
+        return {
+            "success": False,
+            "error": f"Tool '{tool_name}' already exists",
+            "fix": "Use update_tool() to modify or remove_tool() first",
+        }
+
+    try:
+        # Prepare parameters with Python types
+        mapped_params = {}
+        type_mapping = {
+            "string": "str",
+            "number": "float",
+            "integer": "int",
+            "boolean": "bool",
+            "array": "List",
+            "object": "dict",
+        }
+
+        for name, info in parameters.items():
+            # Handle both simple format {'a': 'number'} and detailed format {'a': {'type': 'number', 'description': '...'}}
+            if isinstance(info, str):
+                param_info = {"type": info}
+            else:
+                param_info = info.copy()
+            raw_type = param_info.get("type", "Any")
+
+            # Map JSON type to Python type, or use as-is if not in map (allows direct Python types)
+            py_type = type_mapping.get(raw_type, raw_type)
+
+            # Handle optional parameters
+            # Check for "required" key (boolean)
+            is_required = param_info.get("required", False)
+
+            if not is_required:
+                py_type = f"Optional[{py_type}] = None"
+
+            param_info["type"] = py_type
+            param_info["is_required"] = is_required
+            mapped_params[name] = param_info
+
+        # Sort parameters: required first, then optional (to avoid SyntaxError)
+        sorted_params = dict(
+            sorted(mapped_params.items(), key=lambda x: (not x[1]["is_required"], x[0]))
+        )
+
+        template = jinja_env.get_template("tool.py.j2")
+        code = template.render(
+            tool_name=tool_name, description=description, parameters=sorted_params
+        )
+        tool_file.write_text(code)
+
+        # Auto-generate schemas after adding tool
+        from ..schemas import generate_schemas
+        generate_schemas(force=False, agent_name=agent_name)
+
+        return {
+            "success": True,
+            "message": f"Created tool '{tool_name}'",
+            "path": str(tool_file),
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+

a4e/tools/agent_tools/list_tools.py

@@ -0,0 +1,28 @@
+"""
+List tools tool.
+"""
+
+from typing import Optional
+
+from ...core import mcp, get_project_dir
+
+
+@mcp.tool()
+def list_tools(agent_name: Optional[str] = None) -> dict:
+    """
+    List all tools available in the current agent project
+    """
+    project_dir = get_project_dir(agent_name)
+    tools_dir = project_dir / "tools"
+
+    if not tools_dir.exists():
+        return {"tools": [], "count": 0}
+
+    tools = []
+    for tool_file in tools_dir.glob("*.py"):
+        if tool_file.name == "__init__.py":
+            continue
+        tools.append(tool_file.stem)
+
+    return {"tools": sorted(tools), "count": len(tools)}
+

a4e/tools/agent_tools/remove_tool.py

@@ -0,0 +1,69 @@
+"""
+Remove tool tool.
+"""
+
+from pathlib import Path
+from typing import Optional
+import json
+
+from ...core import mcp, get_project_dir
+
+
+@mcp.tool()
+def remove_tool(
+    tool_name: str,
+    agent_name: Optional[str] = None,
+) -> dict:
+    """
+    Remove a tool from the agent
+
+    Args:
+        tool_name: Name of the tool to remove (without .py extension)
+        agent_name: Optional agent ID if not in agent directory
+
+    Returns:
+        Result with success status and removed file path
+    """
+    project_dir = get_project_dir(agent_name)
+    tools_dir = project_dir / "tools"
+
+    if not tools_dir.exists():
+        return {
+            "success": False,
+            "error": f"tools/ directory not found at {tools_dir}",
+            "fix": "Initialize an agent first with initialize_project() or specify agent_name",
+        }
+
+    tool_file = tools_dir / f"{tool_name}.py"
+
+    if not tool_file.exists():
+        # List available tools for helpful error
+        available = [f.stem for f in tools_dir.glob("*.py") if f.stem != "__init__"]
+        return {
+            "success": False,
+            "error": f"Tool '{tool_name}' not found",
+            "fix": f"Available tools: {', '.join(available) if available else 'none'}",
+        }
+
+    try:
+        # Remove the tool file
+        tool_file.unlink()
+
+        # Update schemas.json if it exists
+        schemas_file = tools_dir / "schemas.json"
+        if schemas_file.exists():
+            try:
+                schemas = json.loads(schemas_file.read_text())
+                if tool_name in schemas:
+                    del schemas[tool_name]
+                    schemas_file.write_text(json.dumps(schemas, indent=2))
+            except (json.JSONDecodeError, KeyError):
+                pass  # Ignore schema update errors
+
+        return {
+            "success": True,
+            "message": f"Removed tool '{tool_name}'",
+            "removed_file": str(tool_file),
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}

a4e/tools/agent_tools/update_tool.py

@@ -0,0 +1,123 @@
+"""
+Update tool - modify existing tool's description or parameters.
+"""
+
+from typing import Optional
+
+from ...core import mcp, jinja_env, get_project_dir
+
+
+@mcp.tool()
+def update_tool(
+    tool_name: str,
+    description: Optional[str] = None,
+    parameters: Optional[dict] = None,
+    agent_name: Optional[str] = None,
+) -> dict:
+    """
+    Update an existing tool's description or parameters.
+
+    Args:
+        tool_name: Name of the tool to update
+        description: New description (optional)
+        parameters: New parameters dict (optional, replaces all parameters)
+        agent_name: Optional agent ID if not in agent directory
+    """
+    project_dir = get_project_dir(agent_name)
+    tools_dir = project_dir / "tools"
+
+    if not tools_dir.exists():
+        return {
+            "success": False,
+            "error": f"tools/ directory not found at {tools_dir}",
+            "fix": "Make sure you're in an agent project directory or specify agent_name",
+        }
+
+    tool_file = tools_dir / f"{tool_name}.py"
+    if not tool_file.exists():
+        # List available tools for helpful error
+        available = [f.stem for f in tools_dir.glob("*.py") if f.stem != "__init__"]
+        return {
+            "success": False,
+            "error": f"Tool '{tool_name}' not found",
+            "fix": f"Available tools: {', '.join(available) if available else 'none'}",
+        }
+
+    if description is None and parameters is None:
+        return {
+            "success": False,
+            "error": "Nothing to update",
+            "fix": "Provide at least one of: description, parameters",
+        }
+
+    try:
+        # Read current tool to extract existing values if needed
+        current_content = tool_file.read_text()
+
+        # Extract current description from docstring if not provided
+        if description is None:
+            import re
+            match = re.search(r'"""([^"]+)"""', current_content)
+            if match:
+                description = match.group(1).strip()
+            else:
+                description = f"Tool: {tool_name}"
+
+        # If parameters not provided, we need to extract from current file
+        if parameters is None:
+            # For now, require parameters to be specified for update
+            return {
+                "success": False,
+                "error": "Parameters must be specified when updating",
+                "fix": "Provide the parameters dict with all parameters for the tool",
+            }
+
+        # Prepare parameters with Python types (same logic as add_tool)
+        mapped_params = {}
+        type_mapping = {
+            "string": "str",
+            "number": "float",
+            "integer": "int",
+            "boolean": "bool",
+            "array": "List",
+            "object": "dict",
+        }
+
+        for name, info in parameters.items():
+            if isinstance(info, str):
+                param_info = {"type": info}
+            else:
+                param_info = info.copy()
+            raw_type = param_info.get("type", "Any")
+            py_type = type_mapping.get(raw_type, raw_type)
+            is_required = param_info.get("required", False)
+
+            if not is_required:
+                py_type = f"Optional[{py_type}] = None"
+
+            param_info["type"] = py_type
+            param_info["is_required"] = is_required
+            mapped_params[name] = param_info
+
+        sorted_params = dict(
+            sorted(mapped_params.items(), key=lambda x: (not x[1]["is_required"], x[0]))
+        )
+
+        # Regenerate tool file
+        template = jinja_env.get_template("tool.py.j2")
+        code = template.render(
+            tool_name=tool_name, description=description, parameters=sorted_params
+        )
+        tool_file.write_text(code)
+
+        # Regenerate schemas
+        from ..schemas import generate_schemas
+        generate_schemas(force=True, agent_name=agent_name)
+
+        return {
+            "success": True,
+            "message": f"Updated tool '{tool_name}'",
+            "path": str(tool_file),
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}

a4e/tools/deploy/__init__.py

@@ -0,0 +1,8 @@
+"""
+Deployment tools.
+"""
+
+from .deploy import deploy
+
+__all__ = ["deploy"]
+

a4e/tools/deploy/deploy.py

@@ -0,0 +1,59 @@
+"""
+Deploy agent tool.
+"""
+
+from typing import Optional
+from urllib.parse import urlencode
+
+from ...core import mcp, get_project_dir
+from ..validation import validate
+from ..schemas import generate_schemas
+
+HUB_URL = "https://dev-a4e.global.simetrik.com"
+
+
+@mcp.tool()
+def deploy(
+    environment: str = "production",
+    auto_publish: bool = False,
+    agent_name: Optional[str] = None,
+) -> dict:
+    """
+    Deploy agent to A4E Hub.
+
+    This validates the agent, regenerates schemas, and prepares it for deployment.
+    To test locally with the playground, use `dev_start` instead.
+    """
+    val_result = validate(strict=True, agent_name=agent_name)
+    if not val_result["success"]:
+        return val_result
+
+    gen_result = generate_schemas(force=True, agent_name=agent_name)
+
+    if (
+        gen_result.get("tools", {}).get("status") == "error"
+        or gen_result.get("views", {}).get("status") == "error"
+    ):
+        return {
+            "success": False,
+            "error": "Schema generation failed",
+            "details": gen_result,
+        }
+
+    project_dir = get_project_dir(agent_name)
+    agent_id = project_dir.name
+
+    return {
+        "success": True,
+        "message": f"Agent '{agent_id}' validated and schemas generated for {environment}",
+        "agent_id": agent_id,
+        "next_steps": [
+            f"Run 'a4e dev start' to test locally with the playground",
+            f"The playground URL will be: {HUB_URL}/builder/playground?url=<ngrok_url>&agent={agent_id}",
+        ],
+        "details": {
+            "validation": val_result,
+            "schema_generation": gen_result,
+        },
+    }
+

a4e/tools/dev/__init__.py

@@ -0,0 +1,10 @@
+"""
+Development tools.
+"""
+
+from .dev_start import dev_start
+from .dev_stop import dev_stop
+from .check_environment import check_environment
+
+__all__ = ["dev_start", "dev_stop", "check_environment"]
+

a4e/tools/dev/check_environment.py

@@ -0,0 +1,79 @@
+"""
+Check environment tool.
+"""
+
+import sys
+import shutil
+import os
+from pathlib import Path
+
+from ...core import mcp, get_project_dir, get_configured_project_dir
+
+
+@mcp.tool()
+def check_environment() -> dict:
+    """
+    Diagnose the current environment for agent development
+    """
+    _PROJECT_DIR = get_configured_project_dir()
+    
+    results = {
+        "python": {
+            "version": sys.version.split()[0],
+            "ok": sys.version_info >= (3, 10),
+        },
+        "project_root": {
+            "configured_dir": str(_PROJECT_DIR) if _PROJECT_DIR else None,
+            "effective_dir": str(get_project_dir()),
+            "using_fallback": _PROJECT_DIR is None,
+        },
+        "dependencies": {"pyngrok": False, "message": "Not installed"},
+        "ngrok_binary": {"found": False, "path": None},
+        "ngrok_auth": {"configured": False},
+        "recommendations": [],
+    }
+
+    # Check pyngrok
+    try:
+        import pyngrok
+
+        results["dependencies"]["pyngrok"] = True
+        results["dependencies"]["message"] = f"Installed ({pyngrok.__version__})"
+    except ImportError:
+        results["recommendations"].append("Install pyngrok: 'uv add pyngrok'")
+
+    # Check ngrok binary
+    ngrok_path = shutil.which("ngrok")
+    if ngrok_path:
+        results["ngrok_binary"]["found"] = True
+        results["ngrok_binary"]["path"] = ngrok_path
+    else:
+        results["recommendations"].append("Install ngrok CLI and add to PATH")
+
+    # Check auth token
+    if os.environ.get("NGROK_AUTHTOKEN"):
+        results["ngrok_auth"]["configured"] = True
+        results["ngrok_auth"]["source"] = "env_var"
+    else:
+        try:
+            from pyngrok import conf
+
+            if conf.get_default().auth_token:
+                results["ngrok_auth"]["configured"] = True
+                results["ngrok_auth"]["source"] = "config_file"
+        except ImportError:
+            config_path = Path.home() / ".ngrok2" / "ngrok.yml"
+            config_path_new = (
+                Path.home() / "Library/Application Support/ngrok/ngrok.yml"
+            )
+            if config_path.exists() or config_path_new.exists():
+                results["ngrok_auth"]["configured"] = True
+                results["ngrok_auth"]["source"] = "config_file_detected"
+
+    if not results["ngrok_auth"]["configured"]:
+        results["recommendations"].append(
+            "Configure ngrok auth: 'ngrok config add-authtoken <TOKEN>'"
+        )
+
+    return results
+

a4e/tools/dev/dev_start.py

@@ -0,0 +1,30 @@
+"""
+Start development server tool.
+"""
+
+from pathlib import Path
+from typing import Optional
+import importlib.util
+
+from ...core import mcp, get_project_dir
+
+
+@mcp.tool()
+def dev_start(
+    port: int = 5000, auth_token: Optional[str] = None, agent_name: Optional[str] = None
+) -> dict:
+    """
+    Start development mode with ngrok tunnel
+    """
+    # Import DevManager dynamically
+    dev_manager_path = Path(__file__).parent.parent.parent / "utils" / "dev_manager.py"
+    spec = importlib.util.spec_from_file_location("dev_manager", dev_manager_path)
+    if not spec or not spec.loader:
+        return {"success": False, "error": "Failed to load dev_manager module"}
+    dev_manager_module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(dev_manager_module)
+    DevManager = dev_manager_module.DevManager
+
+    project_dir = get_project_dir(agent_name)
+    return DevManager.start_dev_server(project_dir, port, auth_token)
+

a4e/tools/dev/dev_stop.py

@@ -0,0 +1,26 @@
+"""
+Stop development server tool.
+"""
+
+from pathlib import Path
+import importlib.util
+
+from ...core import mcp
+
+
+@mcp.tool()
+def dev_stop(port: int = 5000) -> dict:
+    """
+    Stop development server and cleanup tunnels
+    """
+    # Import DevManager dynamically
+    dev_manager_path = Path(__file__).parent.parent.parent / "utils" / "dev_manager.py"
+    spec = importlib.util.spec_from_file_location("dev_manager", dev_manager_path)
+    if not spec or not spec.loader:
+        return {"success": False, "error": "Failed to load dev_manager module"}
+    dev_manager_module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(dev_manager_module)
+    DevManager = dev_manager_module.DevManager
+
+    return DevManager.stop_dev_server(port)
+

a4e/tools/project/__init__.py

@@ -0,0 +1,10 @@
+"""
+Project initialization tools.
+"""
+
+from .initialize_project import initialize_project
+from .get_agent_info import get_agent_info
+from .get_instructions import get_instructions
+
+__all__ = ["initialize_project", "get_agent_info", "get_instructions"]
+

a4e/tools/project/get_agent_info.py

@@ -0,0 +1,66 @@
+"""
+Get agent info tool.
+"""
+
+from typing import Optional
+import json
+
+from ...core import mcp, get_project_dir
+
+
+@mcp.tool()
+def get_agent_info(agent_name: Optional[str] = None) -> dict:
+    """
+    Get general metadata and info about the current agent
+    """
+    project_dir = get_project_dir(agent_name)
+    metadata_file = project_dir / "metadata.json"
+
+    if not metadata_file.exists():
+        return {
+            "error": f"metadata.json not found in {project_dir}. Are you in an agent project?"
+        }
+
+    try:
+        metadata = json.loads(metadata_file.read_text())
+
+        # Count structure
+        tools_dir = project_dir / "tools"
+        views_dir = project_dir / "views"
+        skills_dir = project_dir / "skills"
+        prompts_dir = project_dir / "prompts"
+
+        tools = []
+        if tools_dir.exists():
+            tools = [f.stem for f in tools_dir.glob("*.py") if f.stem != "__init__"]
+
+        views = []
+        if views_dir.exists():
+            views = [d.name for d in views_dir.iterdir() if d.is_dir() and (d / "view.tsx").exists()]
+
+        skills = []
+        if skills_dir.exists():
+            skills = [d.name for d in skills_dir.iterdir() if d.is_dir()]
+
+        prompts = []
+        if prompts_dir.exists():
+            prompts = [f.stem for f in prompts_dir.glob("*.md")]
+
+        return {
+            "agent_id": project_dir.name,
+            "metadata": metadata,
+            "path": str(project_dir),
+            "structure": {
+                "tools": tools,
+                "tools_count": len(tools),
+                "views": views,
+                "views_count": len(views),
+                "skills": skills,
+                "skills_count": len(skills),
+                "prompts": prompts,
+                "prompts_count": len(prompts),
+            }
+        }
+    except Exception as e:
+        return {"error": f"Failed to read metadata: {str(e)}"}
+