a4e 0.1.5__py3-none-any.whl

a4e/tools/schemas/generate_schemas.py

@@ -0,0 +1,278 @@
+"""
+Schema generation tool.
+
+NOTE: This tool may be called by the MCP server which uses stdio.
+All logging MUST go to stderr to avoid breaking the MCP protocol.
+"""
+
+from pathlib import Path
+from typing import Optional
+import json
+import inspect
+import re
+import sys
+import importlib.util
+from types import ModuleType
+
+from ...core import mcp, get_project_dir
+
+
+def _log(message: str) -> None:
+    """Log to stderr (stdout is reserved for MCP protocol)."""
+    print(message, file=sys.stderr)
+
+
+@mcp.tool()
+def generate_schemas(force: bool = False, agent_name: Optional[str] = None) -> dict:
+    """
+    Auto-generate all schemas from code
+
+    Args:
+        force: If True, overwrite existing schema files. If False, skip generation if schemas exist.
+        agent_name: Optional agent ID if not in agent directory
+
+    Generates:
+    - tools/schemas.json (from @tool functions)
+    - views/*/view.schema.json (from TypeScript props)
+    - views/schemas.json (aggregated summary for backend)
+    """
+    # Import schema_generator dynamically from utils directory
+    schema_gen_path = Path(__file__).parent.parent.parent / "utils" / "schema_generator.py"
+    spec = importlib.util.spec_from_file_location("schema_generator", schema_gen_path)
+    if not spec or not spec.loader:
+        return {"success": False, "error": "Failed to load schema_generator module"}
+    schema_gen_module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(schema_gen_module)
+    generate_schema = schema_gen_module.generate_schema
+
+    project_dir = get_project_dir(agent_name)
+    tools_dir = project_dir / "tools"
+    views_dir = project_dir / "views"
+
+    results = {
+        "tools": {"count": 0, "status": "skipped", "errors": []},
+        "views": {"count": 0, "status": "skipped", "errors": []},
+    }
+
+    # Check for existing schemas if force is False
+    tools_schema_file = tools_dir / "schemas.json" if tools_dir.exists() else None
+    views_schema_file = views_dir / "schemas.json" if views_dir.exists() else None
+
+    if not force:
+        # Check if tool schemas exist
+        if tools_schema_file and tools_schema_file.exists():
+            _log(
+                f"Skipping tool schema generation - {tools_schema_file} exists (use force=True to overwrite)"
+            )
+            results["tools"]["status"] = "skipped"
+
+        # Check if view schemas exist
+        if views_schema_file and views_schema_file.exists():
+            _log(
+                f"Skipping view schema generation - {views_schema_file} exists (use force=True to overwrite)"
+            )
+            results["views"]["status"] = "skipped"
+
+        # If both are skipped, return early
+        if (
+            tools_schema_file
+            and tools_schema_file.exists()
+            and views_schema_file
+            and views_schema_file.exists()
+        ):
+            return results
+
+    # Generate Tool Schemas
+    if tools_dir.exists() and (
+        force or not (tools_schema_file and tools_schema_file.exists())
+    ):
+        tool_schemas = []
+        has_errors = False
+
+        # Add project dir to sys.path to allow imports
+        if str(project_dir) not in sys.path:
+            sys.path.insert(0, str(project_dir))
+
+        # Mock a4e SDK to avoid backend dependency hell (psycopg2, etc.)
+        # We only need the @tool decorator to mark functions
+        if "a4e" not in sys.modules:
+            a4e_module = ModuleType("a4e")
+            a4e_sdk_module = ModuleType("a4e.sdk")
+
+            def mock_tool(func):
+                func._is_tool = True
+                return func
+
+            a4e_sdk_module.tool = mock_tool
+            a4e_module.sdk = a4e_sdk_module
+
+            sys.modules["a4e"] = a4e_module
+            sys.modules["a4e.sdk"] = a4e_sdk_module
+
+        for tool_file in tools_dir.glob("*.py"):
+            if tool_file.name == "__init__.py":
+                continue
+
+            try:
+                # Dynamic import
+                spec = importlib.util.spec_from_file_location(tool_file.stem, tool_file)
+                if spec and spec.loader:
+                    module = importlib.util.module_from_spec(spec)
+                    spec.loader.exec_module(module)
+
+                    # Find @tool decorated functions or functions matching filename convention
+                    for name, obj in inspect.getmembers(module):
+                        if not inspect.isfunction(obj):
+                            continue
+
+                        is_decorated_tool = getattr(obj, "_is_tool", False)
+                        matches_filename = name == tool_file.stem
+
+                        if is_decorated_tool or matches_filename:
+                            schema = generate_schema(obj)
+                            tool_schemas.append(schema)
+                            results["tools"]["count"] += 1
+                            if is_decorated_tool:
+                                break
+            except Exception as e:
+                error_msg = f"Error processing {tool_file}: {e}"
+                _log(error_msg)
+                results["tools"]["errors"].append(error_msg)
+                has_errors = True
+
+        try:
+            schema_file = tools_dir / "schemas.json"
+            if schema_file.exists() and force:
+                _log(f"Overwriting {schema_file}")
+            
+            # Convert list to dictionary format with tool names as keys
+            # This is the format expected by the A4E main application
+            schemas_dict = {}
+            for schema in tool_schemas:
+                tool_name = schema.get("function", {}).get("name")
+                if not tool_name:
+                    # Fallback for legacy format
+                    tool_name = schema.get("name", "unknown")
+                    # Convert legacy format to new format
+                    schema = {
+                        "function": {
+                            "name": tool_name,
+                            "description": schema.get("description", ""),
+                            "parameters": schema.get("inputSchema", schema.get("parameters", {}))
+                        },
+                        "returns": schema.get("returns", {
+                            "type": "object",
+                            "properties": {"status": {"type": "string"}}
+                        })
+                    }
+                schemas_dict[tool_name] = schema
+            
+            schema_file.write_text(json.dumps(schemas_dict, indent=2))
+            results["tools"]["status"] = "error" if has_errors else "success"
+        except Exception as e:
+            error_msg = f"Error writing schemas.json: {e}"
+            _log(error_msg)
+            results["tools"]["errors"].append(error_msg)
+            results["tools"]["status"] = "error"
+
+    # Generate View Schemas
+    if views_dir.exists() and (
+        force or not (views_schema_file and views_schema_file.exists())
+    ):
+        has_errors = False
+        aggregated_views = {}
+
+        for view_dir in views_dir.iterdir():
+            if not view_dir.is_dir():
+                continue
+
+            view_file = view_dir / "view.tsx"
+            if not view_file.exists():
+                continue
+
+            try:
+                content = view_file.read_text()
+
+                # Simple regex to find interface Props
+                props_match = re.search(r"interface\s+(\w+Props)\s*{([^}]+)}", content)
+
+                properties = {}
+                required = []
+
+                if props_match:
+                    props_body = props_match.group(2)
+                    for line in props_body.split("\n"):
+                        line = line.strip()
+                        if not line or line.startswith("//"):
+                            continue
+
+                        prop_match = re.match(r"(\w+)(\?)?:\s*([^;]+);", line)
+                        if prop_match:
+                            name = prop_match.group(1)
+                            optional = prop_match.group(2) == "?"
+                            ts_type = prop_match.group(3).strip()
+
+                            json_type = "string"
+                            if "number" in ts_type:
+                                json_type = "number"
+                            elif "boolean" in ts_type:
+                                json_type = "boolean"
+                            elif "Array" in ts_type or "[]" in ts_type:
+                                json_type = "array"
+
+                            properties[name] = {
+                                "type": json_type,
+                                "description": f"From {ts_type}",
+                            }
+
+                            if not optional:
+                                required.append(name)
+
+                schema = {
+                    "name": view_dir.name,
+                    "description": f"View for {view_dir.name}",
+                    "props": {
+                        "type": "object",
+                        "properties": properties,
+                        "required": required,
+                    },
+                }
+
+                # Write individual schema
+                view_schema_file = view_dir / "view.schema.json"
+                if view_schema_file.exists() and force:
+                    _log(f"Overwriting {view_schema_file}")
+                view_schema_file.write_text(json.dumps(schema, indent=2))
+
+                # Add to aggregated dict
+                # Backend expects: { "view_id": { "id": "...", "description": "...", "params": {...} } }
+                aggregated_views[view_dir.name] = {
+                    "id": view_dir.name,
+                    "description": f"View for {view_dir.name}",
+                    "params": properties,
+                }
+
+                results["views"]["count"] += 1
+
+            except Exception as e:
+                error_msg = f"Error processing view {view_dir}: {e}"
+                _log(error_msg)
+                results["views"]["errors"].append(error_msg)
+                has_errors = True
+
+        # Write aggregated schemas.json
+        try:
+            aggregated_schema_file = views_dir / "schemas.json"
+            if aggregated_schema_file.exists() and force:
+                _log(f"Overwriting {aggregated_schema_file}")
+            aggregated_schema_file.write_text(json.dumps(aggregated_views, indent=2))
+        except Exception as e:
+            error_msg = f"Error writing views/schemas.json: {e}"
+            _log(error_msg)
+            results["views"]["errors"].append(error_msg)
+            has_errors = True
+
+        results["views"]["status"] = "error" if has_errors else "success"
+
+    return results
+

a4e/tools/skills/__init__.py

@@ -0,0 +1,12 @@
+"""
+Skills management tools.
+"""
+
+from .add_skill import add_skill
+from .list_skills import list_skills
+from .remove_skill import remove_skill
+from .update_skill import update_skill
+from .helpers import create_skill
+
+__all__ = ["add_skill", "list_skills", "remove_skill", "update_skill", "create_skill"]
+

a4e/tools/skills/add_skill.py

@@ -0,0 +1,105 @@
+"""
+Add skill tool.
+"""
+
+from typing import Optional, List
+import json
+
+from ...core import mcp, get_project_dir
+from .helpers import create_skill
+
+
+@mcp.tool()
+def add_skill(
+    skill_id: str,
+    name: str,
+    description: str,
+    intent_triggers: List[str],
+    output_view: str,
+    internal_tools: Optional[List[str]] = None,
+    requires_auth: bool = False,
+    agent_name: Optional[str] = None,
+) -> dict:
+    """
+    Add a new skill to the agent
+
+    Args:
+        skill_id: ID of the skill (snake_case, e.g., "show_welcome")
+        name: Human-readable name (e.g., "Show Welcome")
+        description: What the skill does and when to use it
+        intent_triggers: List of phrases that trigger this skill
+        output_view: View ID to render (e.g., "welcome") or "NONE" for no view
+        internal_tools: List of tool names this skill uses (e.g., ["get_agents"])
+        requires_auth: Whether this skill requires user authentication
+        agent_name: Optional agent ID if not in agent directory
+    """
+    # Validate skill ID
+    if not skill_id.replace("_", "").isalnum():
+        return {
+            "success": False,
+            "error": "Skill ID must be alphanumeric with underscores",
+        }
+
+    if not intent_triggers or len(intent_triggers) == 0:
+        return {
+            "success": False,
+            "error": "At least one intent trigger is required",
+        }
+
+    project_dir = get_project_dir(agent_name)
+    warnings = []
+
+    # Validate output_view exists
+    view_props = {}
+    if output_view and output_view != "NONE":
+        view_dir = project_dir / "views" / output_view
+        view_schema_file = view_dir / "view.schema.json"
+        
+        if not view_dir.exists():
+            return {
+                "success": False,
+                "error": f"View '{output_view}' not found. Create it first with add_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 '{output_view}'")
+
+    # Validate internal_tools exist
+    if internal_tools:
+        tools_schema_file = project_dir / "tools" / "schemas.json"
+        if tools_schema_file.exists():
+            try:
+                tools_schemas = json.loads(tools_schema_file.read_text())
+                # Support both formats: dict (keys are tool names) or list (objects with 'name' field)
+                if isinstance(tools_schemas, dict):
+                    existing_tools = set(tools_schemas.keys())
+                else:
+                    existing_tools = {t.get("name") for t in tools_schemas if isinstance(t, dict)}
+                
+                for tool in internal_tools:
+                    if tool not in existing_tools:
+                        warnings.append(f"Tool '{tool}' not found in tools/schemas.json. Make sure it exists.")
+            except Exception:
+                warnings.append("Could not validate internal_tools against tools/schemas.json")
+
+    result = create_skill(
+        skill_id=skill_id,
+        name=name,
+        description=description,
+        intent_triggers=intent_triggers,
+        output_view=output_view,
+        internal_tools=internal_tools,
+        requires_auth=requires_auth,
+        view_props=view_props,
+        project_dir=project_dir,
+    )
+
+    # Add warnings to result if any
+    if warnings and result.get("success"):
+        result["warnings"] = warnings
+
+    return result

a4e/tools/skills/helpers.py

@@ -0,0 +1,137 @@
+"""
+Helper functions for skill management.
+"""
+
+from pathlib import Path
+import json
+from typing import List, Optional
+
+from ...core import jinja_env
+
+
+def create_skill(
+    skill_id: str,
+    name: str,
+    description: str,
+    intent_triggers: List[str],
+    output_view: str,
+    internal_tools: Optional[List[str]] = None,
+    requires_auth: bool = False,
+    view_props: Optional[dict] = None,
+    project_dir: Path = None,
+) -> dict:
+    """
+    Helper to create a skill directory with SKILL.md file.
+
+    Args:
+        skill_id: ID of the skill (snake_case)
+        name: Human-readable name
+        description: What the skill does
+        intent_triggers: Phrases that trigger this skill
+        output_view: View ID to render (or "NONE" for no view)
+        internal_tools: List of tool names this skill uses
+        requires_auth: Whether auth is required
+        view_props: Expected props for the output view
+        project_dir: Path to the agent project directory
+
+    Returns:
+        Result dictionary with success status
+    """
+    if project_dir is None:
+        return {"success": False, "error": "project_dir is required"}
+
+    skills_dir = project_dir / "skills"
+
+    if not skills_dir.exists():
+        return {
+            "success": False,
+            "error": f"skills/ directory not found at {skills_dir}",
+        }
+
+    skill_dir = skills_dir / skill_id
+    if skill_dir.exists():
+        return {"success": False, "error": f"Skill '{skill_id}' already exists"}
+
+    try:
+        skill_dir.mkdir()
+
+        # Convert snake_case to Title Case for display
+        skill_name = name or " ".join(word.title() for word in skill_id.split("_"))
+
+        # Generate SKILL.md
+        template = jinja_env.get_template("skills/skill.md.j2")
+        skill_md = template.render(
+            skill_name=skill_name,
+            description=description,
+            intent_triggers=intent_triggers,
+            internal_tools=internal_tools or [],
+            output_view=output_view,
+            requires_auth=requires_auth,
+            view_props=view_props or {},
+        )
+        (skill_dir / "SKILL.md").write_text(skill_md)
+
+        # Update skills/schemas.json
+        _update_skills_schema(
+            skills_dir=skills_dir,
+            skill_id=skill_id,
+            name=skill_name,
+            description=description,
+            intent_triggers=intent_triggers,
+            output_view=output_view,
+            internal_tools=internal_tools,
+            requires_auth=requires_auth,
+        )
+
+        return {
+            "success": True,
+            "message": f"Created skill '{skill_id}'",
+            "path": str(skill_dir),
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+def _update_skills_schema(
+    skills_dir: Path,
+    skill_id: str,
+    name: str,
+    description: str,
+    intent_triggers: List[str],
+    output_view: str,
+    internal_tools: Optional[List[str]] = None,
+    requires_auth: bool = False,
+) -> None:
+    """
+    Update the skills/schemas.json file with the new skill.
+    """
+    schema_file = skills_dir / "schemas.json"
+
+    # Load existing schemas or create empty dict
+    if schema_file.exists():
+        try:
+            schemas = json.loads(schema_file.read_text())
+        except json.JSONDecodeError:
+            schemas = {}
+    else:
+        schemas = {}
+
+    # Build output object
+    output = {"view": output_view}
+    if output_view == "NONE":
+        output["view"] = "NONE"
+
+    # Add new skill schema
+    schemas[skill_id] = {
+        "id": skill_id,
+        "name": name,
+        "description": description,
+        "intent_triggers": intent_triggers,
+        "requires_auth": requires_auth,
+        "internal_tools": internal_tools or [],
+        "output": output,
+    }
+
+    # Write updated schemas
+    schema_file.write_text(json.dumps(schemas, indent=2))
+

a4e/tools/skills/list_skills.py

@@ -0,0 +1,54 @@
+"""
+List skills tool.
+"""
+
+from typing import Optional
+import json
+
+from ...core import mcp, get_project_dir
+
+
+@mcp.tool()
+def list_skills(agent_name: Optional[str] = None) -> dict:
+    """
+    List all skills available in the current agent project
+    """
+    project_dir = get_project_dir(agent_name)
+    skills_dir = project_dir / "skills"
+
+    if not skills_dir.exists():
+        return {"skills": [], "count": 0}
+
+    skills = []
+    
+    # Read from schemas.json if exists
+    schema_file = skills_dir / "schemas.json"
+    if schema_file.exists():
+        try:
+            schemas = json.loads(schema_file.read_text())
+            for skill_id, skill_data in schemas.items():
+                skills.append({
+                    "id": skill_id,
+                    "name": skill_data.get("name", skill_id),
+                    "description": skill_data.get("description", ""),
+                    "output_view": skill_data.get("output", {}).get("view", "NONE"),
+                    "internal_tools": skill_data.get("internal_tools", []),
+                    "intent_triggers": skill_data.get("intent_triggers", []),
+                })
+        except json.JSONDecodeError:
+            pass
+
+    # Fallback: list directories with SKILL.md
+    if not skills:
+        for skill_dir in skills_dir.iterdir():
+            if skill_dir.is_dir() and (skill_dir / "SKILL.md").exists():
+                skills.append({
+                    "id": skill_dir.name,
+                    "name": skill_dir.name.replace("_", " ").title(),
+                    "description": "",
+                    "output_view": "unknown",
+                    "internal_tools": [],
+                })
+
+    return {"skills": sorted(skills, key=lambda x: x["id"]), "count": len(skills)}
+

a4e/tools/skills/remove_skill.py

@@ -0,0 +1,74 @@
+"""
+Remove skill tool.
+"""
+
+from pathlib import Path
+from typing import Optional
+import json
+import shutil
+
+from ...core import mcp, get_project_dir
+
+
+@mcp.tool()
+def remove_skill(
+    skill_id: str,
+    agent_name: Optional[str] = None,
+) -> dict:
+    """
+    Remove a skill from the agent
+
+    Args:
+        skill_id: ID of the skill to remove (the folder name)
+        agent_name: Optional agent ID if not in agent directory
+
+    Returns:
+        Result with success status and removed folder path
+    """
+    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}. Are you in an agent project?",
+        }
+
+    skill_folder = skills_dir / skill_id
+
+    if not skill_folder.exists():
+        return {
+            "success": False,
+            "error": f"Skill '{skill_id}' not found at {skill_folder}",
+        }
+
+    # Prevent removing the mandatory show_welcome skill
+    if skill_id == "show_welcome":
+        return {
+            "success": False,
+            "error": "Cannot remove the 'show_welcome' skill - it is required for all agents",
+        }
+
+    try:
+        # Remove the skill folder and all its contents
+        shutil.rmtree(skill_folder)
+
+        # Update schemas.json if it exists
+        schemas_file = skills_dir / "schemas.json"
+        if schemas_file.exists():
+            try:
+                schemas = json.loads(schemas_file.read_text())
+                # Skills schemas is a dict with skill_id as keys
+                if skill_id in schemas:
+                    del schemas[skill_id]
+                    schemas_file.write_text(json.dumps(schemas, indent=2))
+            except (json.JSONDecodeError, KeyError):
+                pass  # Ignore schema update errors
+
+        return {
+            "success": True,
+            "message": f"Removed skill '{skill_id}'",
+            "removed_folder": str(skill_folder),
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}