a4e 0.1.5__py3-none-any.whl

a4e/tools/skills/update_skill.py

@@ -0,0 +1,150 @@
+"""
+Update skill - modify existing skill's properties.
+"""
+
+import json
+from typing import Optional, List
+
+from ...core import mcp, get_project_dir
+from .helpers import create_skill
+
+
+@mcp.tool()
+def update_skill(
+    skill_id: str,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    intent_triggers: Optional[List[str]] = None,
+    output_view: Optional[str] = None,
+    internal_tools: Optional[List[str]] = None,
+    requires_auth: Optional[bool] = None,
+    agent_name: Optional[str] = None,
+) -> dict:
+    """
+    Update an existing skill's properties.
+
+    Args:
+        skill_id: ID of the skill to update
+        name: New human-readable name (optional)
+        description: New description (optional)
+        intent_triggers: New list of trigger phrases (optional)
+        output_view: New view ID to render (optional)
+        internal_tools: New list of tool names (optional)
+        requires_auth: New auth requirement (optional)
+        agent_name: Optional agent ID if not in agent directory
+    """
+    project_dir = get_project_dir(agent_name)
+    skills_dir = project_dir / "skills"
+
+    if not skills_dir.exists():
+        return {
+            "success": False,
+            "error": f"skills/ directory not found at {skills_dir}",
+            "fix": "Make sure you're in an agent project directory or specify agent_name",
+        }
+
+    # Check if skill exists in schemas.json
+    schemas_file = skills_dir / "schemas.json"
+    if not schemas_file.exists():
+        return {
+            "success": False,
+            "error": "skills/schemas.json not found",
+            "fix": "Create a skill first with add_skill()",
+        }
+
+    try:
+        schemas = json.loads(schemas_file.read_text())
+    except json.JSONDecodeError:
+        return {
+            "success": False,
+            "error": "Failed to parse skills/schemas.json",
+            "fix": "Check the file for JSON syntax errors",
+        }
+
+    if skill_id not in schemas:
+        available = list(schemas.keys())
+        return {
+            "success": False,
+            "error": f"Skill '{skill_id}' not found",
+            "fix": f"Available skills: {', '.join(available) if available else 'none'}",
+        }
+
+    # Get current skill data
+    current = schemas[skill_id]
+
+    # Check if anything to update
+    updates = {
+        "name": name,
+        "description": description,
+        "intent_triggers": intent_triggers,
+        "output_view": output_view,
+        "internal_tools": internal_tools,
+        "requires_auth": requires_auth,
+    }
+    if all(v is None for v in updates.values()):
+        return {
+            "success": False,
+            "error": "Nothing to update",
+            "fix": "Provide at least one of: name, description, intent_triggers, output_view, internal_tools, requires_auth",
+        }
+
+    # Merge with current values
+    final_name = name if name is not None else current.get("name", skill_id)
+    final_description = description if description is not None else current.get("description", "")
+    final_triggers = intent_triggers if intent_triggers is not None else current.get("intent_triggers", [])
+    final_view = output_view if output_view is not None else current.get("output", {}).get("view", "NONE")
+    final_tools = internal_tools if internal_tools is not None else current.get("internal_tools", [])
+    final_auth = requires_auth if requires_auth is not None else current.get("requires_auth", False)
+
+    warnings = []
+
+    # Validate output_view exists
+    view_props = {}
+    if final_view and final_view != "NONE":
+        view_dir = project_dir / "views" / final_view
+        view_schema_file = view_dir / "view.schema.json"
+
+        if not view_dir.exists():
+            return {
+                "success": False,
+                "error": f"View '{final_view}' not found",
+                "fix": f"Create it first with add_view() or use an existing view",
+            }
+
+        if view_schema_file.exists():
+            try:
+                schema = json.loads(view_schema_file.read_text())
+                view_props = schema.get("props", {}).get("properties", {})
+            except Exception:
+                warnings.append(f"Could not parse view schema for '{final_view}'")
+
+    # Remove old skill directory if exists
+    skill_dir = skills_dir / skill_id
+    if skill_dir.exists():
+        import shutil
+        shutil.rmtree(skill_dir)
+
+    # Remove old entry from schemas
+    del schemas[skill_id]
+    schemas_file.write_text(json.dumps(schemas, indent=2))
+
+    # Create updated skill
+    result = create_skill(
+        skill_id=skill_id,
+        name=final_name,
+        description=final_description,
+        intent_triggers=final_triggers,
+        output_view=final_view,
+        internal_tools=final_tools,
+        requires_auth=final_auth,
+        view_props=view_props,
+        project_dir=project_dir,
+    )
+
+    if warnings and result.get("success"):
+        result["warnings"] = warnings
+
+    if result.get("success"):
+        result["message"] = f"Updated skill '{skill_id}'"
+
+    return result

a4e/tools/validation/__init__.py

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

a4e/tools/validation/validate.py

@@ -0,0 +1,389 @@
+"""
+Validate agent structure tool.
+
+Enhanced validation based on lessons learned from production deployments:
+- Tool signature must use params: Dict[str, Any] pattern
+- Schemas must be in dictionary format (not array)
+- Support files must have __name__ compatibility for exec() context
+- Agent prompt should include language policy
+"""
+
+from typing import Optional
+from collections import defaultdict
+import ast
+import json
+import re
+
+from ...core import mcp, get_project_dir
+
+
+@mcp.tool()
+def validate(strict: bool = True, agent_name: Optional[str] = None) -> dict:
+    """
+    Validate agent structure before deployment
+
+    Checks:
+    - Required files exist
+    - Python syntax valid
+    - Tool signatures use params: Dict pattern (A4E compatibility)
+    - Schemas are in dictionary format (not array)
+    - Support files have exec() compatibility
+    - Skills integrity (triggers, dependencies, orphans)
+    - Agent prompt includes language policy
+    """
+    project_dir = get_project_dir(agent_name)
+    required_files = [
+        "agent.py",
+        "metadata.json",
+        "prompts/agent.md",
+        "views/welcome/view.tsx",
+    ]
+
+    missing = []
+    for f in required_files:
+        if not (project_dir / f).exists():
+            missing.append(f)
+
+    if missing:
+        return {
+            "success": False,
+            "error": f"Missing required files in {project_dir}: {', '.join(missing)}",
+        }
+
+    errors = []
+    warnings = []
+
+    tools_dir = project_dir / "tools"
+    views_dir = project_dir / "views"
+
+    if strict:
+        # 1. Check Python syntax and tool signatures
+        python_files = [project_dir / "agent.py"]
+        if tools_dir.exists():
+            python_files.extend(list(tools_dir.glob("*.py")))
+
+        for py_file in python_files:
+            if py_file.name == "__init__.py":
+                continue
+
+            try:
+                content = py_file.read_text()
+                tree = ast.parse(content)
+
+                # Check type hints and tool signatures
+                for node in ast.walk(tree):
+                    if isinstance(node, ast.FunctionDef):
+                        # Skip private functions or __init__
+                        if node.name.startswith("_"):
+                            continue
+                        
+                        # For tool files, check if using params: Dict pattern
+                        if py_file.parent == tools_dir and py_file.name not in ["db.py", "models.py", "seed_data.py", "__init__.py"]:
+                            tool_errors = _validate_tool_signature(node, py_file.name)
+                            errors.extend(tool_errors)
+
+                        # Check args for annotations
+                        for arg in node.args.args:
+                            if arg.annotation is None and arg.arg != "self":
+                                errors.append(
+                                    f"Missing type hint for argument '{arg.arg}' in {py_file.name}:{node.name}"
+                                )
+
+                # Check exec() compatibility for support files
+                if py_file.name in ["db.py", "models.py", "seed_data.py"]:
+                    compat_warnings = _check_exec_compatibility(content, py_file.name)
+                    warnings.extend(compat_warnings)
+
+            except SyntaxError as e:
+                errors.append(f"Syntax error in {py_file.name}: {e}")
+            except Exception as e:
+                errors.append(f"Error analyzing {py_file.name}: {e}")
+
+        # 2. Check if schemas exist and are in correct format
+        if tools_dir.exists():
+            tool_files = [f for f in tools_dir.glob("*.py") if f.name not in ["__init__.py", "db.py", "models.py", "seed_data.py"]]
+            schemas_file = tools_dir / "schemas.json"
+            
+            if not schemas_file.exists() and tool_files:
+                errors.append(
+                    "Tools exist but tools/schemas.json is missing. Run generate_schemas."
+                )
+            elif schemas_file.exists():
+                schema_errors = _validate_tools_schema_format(schemas_file)
+                errors.extend(schema_errors)
+
+        # 3. Check view schemas
+        if views_dir.exists():
+            view_dirs = [
+                d
+                for d in views_dir.iterdir()
+                if d.is_dir() and (d / "view.tsx").exists()
+            ]
+            if not (views_dir / "schemas.json").exists() and view_dirs:
+                errors.append(
+                    "Views exist but views/schemas.json is missing. Run generate_schemas."
+                )
+
+        # 4. Validate skills integrity
+        skills_dir = project_dir / "skills"
+        if skills_dir.exists():
+            skill_errors, skill_warnings = _validate_skills(
+                skills_dir, tools_dir, views_dir
+            )
+            errors.extend(skill_errors)
+            warnings.extend(skill_warnings)
+
+        # 5. Check agent prompt for language policy
+        agent_prompt = project_dir / "prompts" / "agent.md"
+        if agent_prompt.exists():
+            prompt_warnings = _check_agent_prompt(agent_prompt)
+            warnings.extend(prompt_warnings)
+
+    if errors:
+        result = {
+            "success": False,
+            "error": "Validation failed",
+            "details": errors,
+        }
+        if warnings:
+            result["warnings"] = warnings
+        return result
+
+    result = {"success": True, "message": "Agent structure is valid"}
+    if warnings:
+        result["warnings"] = warnings
+    return result
+
+
+def _validate_tool_signature(func_node: ast.FunctionDef, filename: str) -> list:
+    """
+    Validate that tool function uses the params: Dict[str, Any] pattern.
+    
+    The A4E main application expects tools with signature:
+        def tool_name(params: Dict[str, Any]) -> Dict[str, Any]
+    """
+    errors = []
+    func_name = func_node.name
+    
+    # Get function arguments (excluding self)
+    args = [arg for arg in func_node.args.args if arg.arg != "self"]
+    
+    # Check if using params: Dict pattern
+    if len(args) == 1 and args[0].arg == "params":
+        # Good - using params dict pattern
+        return errors
+    
+    # Check if using multiple parameters (legacy pattern)
+    if len(args) > 1:
+        errors.append(
+            f"Tool '{func_name}' in {filename} uses individual parameters. "
+            f"A4E requires params: Dict[str, Any] pattern. "
+            f"Fix: Change signature to 'def {func_name}(params: Dict[str, Any]) -> Dict[str, Any]'"
+        )
+    elif len(args) == 1 and args[0].arg != "params":
+        errors.append(
+            f"Tool '{func_name}' in {filename} has single param named '{args[0].arg}'. "
+            f"A4E expects the param to be named 'params'. "
+            f"Fix: Rename to 'params: Dict[str, Any]'"
+        )
+    
+    return errors
+
+
+def _check_exec_compatibility(content: str, filename: str) -> list:
+    """
+    Check if support file has exec() context compatibility.
+    
+    Support files (db.py, models.py, etc.) need:
+    1. __name__ definition for exec() context
+    2. sys.path manipulation for imports
+    """
+    warnings = []
+    
+    # Check for __name__ compatibility
+    if "if '__name__' not in" not in content and "if \"__name__\" not in" not in content:
+        warnings.append(
+            f"{filename} may not work in exec() context. "
+            f"Add at top: if '__name__' not in dir(): __name__ = \"{filename.replace('.py', '')}\""
+        )
+    
+    # Check for if __name__ == "__main__" pattern
+    if 'if __name__ == "__main__"' in content or "if __name__ == '__main__'" in content:
+        # Make sure it's using globals().get pattern
+        if "globals().get('__name__')" not in content:
+            warnings.append(
+                f"{filename} uses 'if __name__ == \"__main__\"' which may fail in exec() context. "
+                f"Change to: if globals().get('__name__') == '__main__'"
+            )
+    
+    return warnings
+
+
+def _validate_tools_schema_format(schema_file) -> list:
+    """
+    Validate that tools/schemas.json is in dictionary format.
+    
+    The A4E main application expects:
+    {
+        "tool_name": {
+            "function": {...},
+            "returns": {...}
+        }
+    }
+    
+    NOT an array format:
+    [{"name": "tool_name", ...}]
+    """
+    errors = []
+    
+    try:
+        with open(schema_file) as f:
+            schemas = json.load(f)
+        
+        if isinstance(schemas, list):
+            errors.append(
+                "tools/schemas.json is in array format but A4E expects dictionary format. "
+                "Run 'generate_schemas(force=True)' to regenerate in correct format."
+            )
+        elif isinstance(schemas, dict):
+            # Check each tool has the correct structure
+            for tool_name, tool_schema in schemas.items():
+                if "function" not in tool_schema:
+                    errors.append(
+                        f"Tool '{tool_name}' schema missing 'function' key. "
+                        "Expected format: {\"function\": {...}, \"returns\": {...}}"
+                    )
+    except json.JSONDecodeError as e:
+        errors.append(f"Invalid JSON in tools/schemas.json: {e}")
+    except Exception as e:
+        errors.append(f"Error reading tools/schemas.json: {e}")
+    
+    return errors
+
+
+def _check_agent_prompt(prompt_file) -> list:
+    """
+    Check agent prompt for recommended patterns.
+    """
+    warnings = []
+    
+    try:
+        content = prompt_file.read_text()
+        
+        # Check for language policy
+        language_patterns = [
+            "english only",
+            "respond in english",
+            "language policy",
+            "always respond in english",
+        ]
+        has_language_policy = any(
+            pattern in content.lower() for pattern in language_patterns
+        )
+        
+        if not has_language_policy:
+            warnings.append(
+                "Agent prompt (prompts/agent.md) doesn't specify language policy. "
+                "Consider adding: '## Language Policy\\n**ALWAYS respond in English only.**'"
+            )
+        
+    except Exception:
+        pass
+    
+    return warnings
+
+
+def _validate_skills(skills_dir, tools_dir, views_dir) -> tuple:
+    """
+    Validate skills for integrity issues.
+    
+    Returns:
+        Tuple of (errors, warnings)
+    """
+    errors = []
+    warnings = []
+    
+    schema_file = skills_dir / "schemas.json"
+    
+    # Check if schemas.json exists when skill folders exist
+    skill_folders = [d for d in skills_dir.iterdir() if d.is_dir()]
+    if skill_folders and not schema_file.exists():
+        errors.append("Skills exist but skills/schemas.json is missing.")
+        return errors, warnings
+    
+    if not schema_file.exists():
+        return errors, warnings
+    
+    try:
+        schemas = json.loads(schema_file.read_text())
+    except json.JSONDecodeError as e:
+        errors.append(f"Invalid JSON in skills/schemas.json: {e}")
+        return errors, warnings
+    
+    # Get existing tools and views for dependency validation
+    existing_tools = set()
+    if tools_dir.exists():
+        tools_schema = tools_dir / "schemas.json"
+        if tools_schema.exists():
+            try:
+                ts = json.loads(tools_schema.read_text())
+                if isinstance(ts, dict):
+                    existing_tools = set(ts.keys())
+                else:
+                    existing_tools = {t.get("name") for t in ts if isinstance(t, dict)}
+            except Exception:
+                pass
+    
+    existing_views = set()
+    if views_dir.exists():
+        existing_views = {d.name for d in views_dir.iterdir() if d.is_dir() and (d / "view.tsx").exists()}
+    
+    # Track triggers for duplicate detection
+    trigger_to_skills = defaultdict(list)
+    
+    for skill_id, skill_data in schemas.items():
+        # Check SKILL.md exists
+        skill_md = skills_dir / skill_id / "SKILL.md"
+        if not skill_md.exists():
+            warnings.append(f"Skill '{skill_id}' missing SKILL.md documentation")
+        else:
+            # Check SKILL.md content for correct tool calling pattern
+            try:
+                skill_content = skill_md.read_text()
+                if "render_view(" in skill_content:
+                    warnings.append(
+                        f"Skill '{skill_id}' SKILL.md references non-existent 'render_view()' function. "
+                        "Update to use actual tool names with params dict pattern."
+                    )
+            except Exception:
+                pass
+        
+        # Check output view exists
+        output = skill_data.get("output", {})
+        view_id = output.get("view")
+        if view_id and view_id != "NONE" and view_id not in existing_views:
+            errors.append(f"Skill '{skill_id}' references non-existent view '{view_id}'")
+        
+        # Check internal tools exist
+        internal_tools = skill_data.get("internal_tools", [])
+        for tool in internal_tools:
+            if tool not in existing_tools:
+                warnings.append(f"Skill '{skill_id}' references tool '{tool}' not in schemas")
+        
+        # Collect triggers for duplicate detection
+        triggers = skill_data.get("intent_triggers", [])
+        for trigger in triggers:
+            trigger_lower = trigger.lower().strip()
+            trigger_to_skills[trigger_lower].append(skill_id)
+    
+    # Check for orphan SKILL.md (folder exists but not in schemas.json)
+    for skill_folder in skill_folders:
+        if skill_folder.name not in schemas:
+            warnings.append(f"Orphan skill folder '{skill_folder.name}' not in schemas.json")
+    
+    # Detect duplicate triggers
+    for trigger, skills in trigger_to_skills.items():
+        if len(skills) > 1:
+            warnings.append(f"Duplicate trigger '{trigger}' in skills: {', '.join(skills)}")
+    
+    return errors, warnings

a4e/tools/views/__init__.py

@@ -0,0 +1,12 @@
+"""
+Views management tools.
+"""
+
+from .add_view import add_view
+from .list_views import list_views
+from .remove_view import remove_view
+from .update_view import update_view
+from .helpers import create_view
+
+__all__ = ["add_view", "list_views", "remove_view", "update_view", "create_view"]
+

a4e/tools/views/add_view.py

@@ -0,0 +1,40 @@
+"""
+Add view tool.
+"""
+
+from typing import Optional
+
+from ...core import mcp, get_project_dir
+from .helpers import create_view
+
+
+@mcp.tool()
+def add_view(
+    view_id: str, description: str, props: dict, agent_name: Optional[str] = None
+) -> dict:
+    """
+    Add a new React view
+
+    Args:
+        view_id: ID of the view (snake_case, e.g., "meal_plan")
+        description: View purpose
+        props: Dictionary of props with types
+        agent_name: Optional agent ID if not in agent directory
+    """
+    # Validate view ID
+    if not view_id.replace("_", "").isalnum():
+        return {
+            "success": False,
+            "error": "View ID must be alphanumeric with underscores",
+        }
+
+    project_dir = get_project_dir(agent_name)
+    result = create_view(view_id, description, props, project_dir)
+
+    # Auto-generate schemas after adding view
+    if result.get("success"):
+        from ..schemas import generate_schemas
+        generate_schemas(force=False, agent_name=agent_name)
+
+    return result
+

a4e/tools/views/helpers.py

@@ -0,0 +1,91 @@
+"""
+Helper functions for view management.
+"""
+
+import json
+from pathlib import Path
+
+from ...core import jinja_env
+
+
+def create_view(
+    view_id: str, description: str, props: dict, project_dir: Path
+) -> dict:
+    """
+    Helper to create a view directory with view.tsx and view.schema.json files.
+
+    Args:
+        view_id: ID of the view (snake_case)
+        description: View purpose
+        props: Dictionary of props with types (e.g., {"title": "string", "count": "number"})
+        project_dir: Path to the agent project directory
+
+    Returns:
+        Result dictionary with success status
+    """
+    views_dir = project_dir / "views"
+
+    if not views_dir.exists():
+        return {
+            "success": False,
+            "error": f"views/ directory not found at {views_dir}",
+        }
+
+    view_dir = views_dir / view_id
+    if view_dir.exists():
+        return {"success": False, "error": f"View '{view_id}' already exists"}
+
+    try:
+        view_dir.mkdir()
+
+        # Convert snake_case to PascalCase for component name
+        view_name = "".join(word.title() for word in view_id.split("_"))
+
+        # Create view.tsx
+        template = jinja_env.get_template("view.tsx.j2")
+        code = template.render(
+            view_name=view_name, description=description, props=props
+        )
+        (view_dir / "view.tsx").write_text(code)
+
+        # Create view.schema.json (required by A4E View Renderer)
+        schema_properties = {}
+        required_props = []
+        for prop_name, prop_type in props.items():
+            # Handle both simple types ("string") and detailed types ({"type": "string", "description": "..."})
+            if isinstance(prop_type, dict):
+                schema_properties[prop_name] = {
+                    "type": prop_type.get("type", "string"),
+                    "description": prop_type.get("description", f"The {prop_name} prop"),
+                }
+                if prop_type.get("required", True):
+                    required_props.append(prop_name)
+            else:
+                schema_properties[prop_name] = {
+                    "type": prop_type,
+                    "description": f"The {prop_name} prop",
+                }
+                required_props.append(prop_name)
+
+        view_schema = {
+            "name": view_id,
+            "description": description,
+            "props": {
+                "type": "object",
+                "properties": schema_properties,
+                "required": required_props,
+            },
+        }
+        (view_dir / "view.schema.json").write_text(
+            json.dumps(view_schema, indent=2)
+        )
+
+        return {
+            "success": True,
+            "message": f"Created view '{view_id}' with view.tsx and view.schema.json",
+            "path": str(view_dir),
+            "files": ["view.tsx", "view.schema.json"],
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+