a4e 0.1.5__py3-none-any.whl

a4e/tools/project/get_instructions.py

@@ -0,0 +1,216 @@
+"""
+Get instructions for AI agents on how to use A4E tools.
+"""
+
+from ...core import mcp
+
+
+AGENT_INSTRUCTIONS = '''
+# A4E Agent Creator - Instructions for AI Assistants
+
+You have access to the **A4E MCP Server** for creating conversational AI agents.
+
+## Architecture Overview
+
+A4E agents use a **Skills V2** architecture with three layers:
+
+```
+USER MESSAGE → SKILL SELECTOR → VIEW RENDERER → VIEW DISPLAY
+```
+
+1. **Skill Selector**: Matches user intent to a skill based on `intent_triggers`
+2. **View Renderer**: Calls `internal_tools`, processes results, maps to view props
+3. **View Display**: Renders React component with the props
+
+## Core Concepts
+
+### Tools (Python Functions)
+Backend logic - calculations, API calls, data retrieval.
+
+### Views (React Components)
+Frontend display - what users see. Each view has:
+- `view.tsx` - React component
+- `view.schema.json` - Props schema
+
+### Skills (Intent → View Mapping)
+Connect user intents to views:
+- `intent_triggers` - phrases that activate the skill
+- `internal_tools` - tools to call
+- `output_view` - view to render
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `initialize_project(name, display_name, description, category, template)` | Create new agent |
+| `add_tool(agent_name, tool_name, description, parameters)` | Add Python tool |
+| `add_view(agent_name, view_id, description, props)` | Add React view |
+| `add_skill(agent_name, skill_id, name, description, intent_triggers, output_view, internal_tools, requires_auth)` | Add skill |
+| `update_tool/view/skill(...)` | Update existing components |
+| `remove_tool/view/skill(...)` | Remove components |
+| `list_tools/views/skills(agent_name)` | List components |
+| `validate(agent_name)` | Validate configuration |
+| `generate_schemas(agent_name, force)` | Regenerate schemas |
+| `dev_start(agent_name, port)` | Start dev server |
+
+## Workflow
+
+### Step 1: Initialize Project
+```python
+initialize_project(
+    name="my-agent",           # lowercase-hyphens
+    display_name="My Agent",
+    description="What the agent does",
+    category="category",
+    template="basic",          # basic | with-tools | with-views | full
+    project_path="/path/to/workspace"  # IMPORTANT: Pass the current workspace path
+)
+```
+
+**IMPORTANT**: Always pass `project_path` with the user's current workspace/project directory.
+The agent will be created at `{project_path}/file-store/agent-store/{name}/`.
+
+### Step 2: Add Tools
+```python
+add_tool(
+    agent_name="my-agent",
+    tool_name="calculate_something",    # snake_case
+    description="What it does",
+    parameters={
+        "param1": {"type": "string", "description": "...", "required": True},
+        "param2": {"type": "number", "description": "..."}
+    }
+)
+```
+
+**Parameter types:** `string`, `number`, `integer`, `boolean`, `array`, `object`
+
+### Step 3: Add Views
+```python
+add_view(
+    agent_name="my-agent",
+    view_id="result_view",              # snake_case
+    description="What it displays",
+    props={
+        "title": {"type": "string", "description": "..."},
+        "items": {"type": "array", "description": "..."}
+    }
+)
+```
+
+### Step 4: Add Skills (AFTER creating views)
+```python
+add_skill(
+    agent_name="my-agent",
+    skill_id="show_result",             # snake_case
+    name="Show Result",                 # Display name
+    description="When to use this skill",
+    intent_triggers=[
+        "show result",
+        "display data",
+        "mostrar resultado"             # Multiple languages supported
+    ],
+    output_view="result_view",          # Must match existing view_id
+    internal_tools=["calculate_something"],
+    requires_auth=False
+)
+```
+
+### Step 5: Validate
+```python
+validate(agent_name="my-agent")
+```
+
+## Important Rules
+
+1. **Create views BEFORE skills** - Skills reference views by ID
+2. **Use snake_case** for tool_name, view_id, skill_id
+3. **Use lowercase-hyphens** for agent name
+4. **Write diverse intent_triggers** - variations, synonyms, multiple languages
+5. **Check errors** - All tools return `{"success": bool, "error": str, "fix": str}`
+
+## Data Flow Example
+
+User: "Calculate my BMI"
+
+1. Skill Selector → matches "show_bmi_result" skill
+2. View Renderer:
+   - Calls `calculate_bmi(weight=70, height=1.75)`
+   - Gets `{"bmi": 22.9, "category": "normal"}`
+   - Maps to view props
+3. View Display → renders BMI result component
+
+## Project Structure
+
+```
+{agent}/
+├── agent.py
+├── metadata.json
+├── tools/
+│   ├── {tool_name}.py
+│   └── schemas.json
+├── views/
+│   ├── {view_id}/
+│   │   ├── view.tsx
+│   │   └── view.schema.json
+│   └── schemas.json
+├── skills/
+│   ├── {skill_id}/
+│   │   └── SKILL.md
+│   └── schemas.json
+└── prompts/
+    └── agent.md
+```
+
+## Quick Example
+
+```python
+# 1. Initialize (ALWAYS pass project_path!)
+initialize_project(
+    name="calculator", 
+    display_name="Calculator", 
+    description="Math calculator", 
+    category="Productivity", 
+    template="basic",
+    project_path="/Users/me/my-project"  # Current workspace path
+)
+
+# 2. Add tool
+add_tool(agent_name="calculator", tool_name="add_numbers", description="Add two numbers", parameters={"a": "number", "b": "number"})
+
+# 3. Add view
+add_view(agent_name="calculator", view_id="sum_result", description="Show sum", props={"result": "number", "expression": "string"})
+
+# 4. Add skill
+add_skill(agent_name="calculator", skill_id="show_sum", name="Show Sum", description="Display addition result", intent_triggers=["add", "sum", "plus"], output_view="sum_result", internal_tools=["add_numbers"])
+
+# 5. Validate
+validate(agent_name="calculator")
+```
+'''
+
+
+@mcp.tool()
+def get_instructions() -> dict:
+    """
+    Get instructions for AI agents on how to use A4E MCP tools.
+
+    Call this tool first to understand how to create A4E agents.
+    Returns comprehensive documentation on architecture, tools, and workflows.
+    """
+    return {
+        "success": True,
+        "instructions": AGENT_INSTRUCTIONS,
+        "summary": "A4E Agent Creator instructions loaded. Use initialize_project() to start, then add tools, views, and skills.",
+        "quick_reference": {
+            "workflow": ["initialize_project", "add_tool", "add_view", "add_skill", "validate"],
+            "naming": {
+                "agent_name": "lowercase-hyphens",
+                "tool_name": "snake_case",
+                "view_id": "snake_case",
+                "skill_id": "snake_case"
+            },
+            "parameter_types": ["string", "number", "integer", "boolean", "array", "object"],
+            "templates": ["basic", "with-tools", "with-views", "full"]
+        }
+    }

a4e/tools/project/initialize_project.py

@@ -0,0 +1,231 @@
+"""
+Initialize project tool.
+"""
+
+from pathlib import Path
+from typing import Literal, Optional
+import os
+
+from ...core import mcp, jinja_env, sanitize_input, get_project_dir, get_configured_project_dir
+
+
+@mcp.tool()
+def initialize_project(
+    name: str,
+    display_name: str,
+    description: str,
+    category: Literal[
+        "Concierge",
+        "E-commerce",
+        "Fitness & Health",
+        "Education",
+        "Entertainment",
+        "Productivity",
+        "Finance",
+        "Customer Support",
+        "General",
+    ],
+    template: Literal["basic", "with-tools", "with-views", "full"] = "basic",
+    project_path: Optional[str] = None,
+) -> dict:
+    """
+    Initialize a new A4E agent project
+
+    Args:
+        name: Agent ID (lowercase, hyphens, e.g., "nutrition-coach")
+        display_name: Human-readable name (e.g., "Nutrition Coach")
+        description: Short description of the agent
+        category: Agent category for marketplace
+        template: Project template (basic=files only, with-tools=example tool, with-views=example view, full=both)
+        project_path: Base directory where the agent folder will be created.
+                      The agent will be created at {project_path}/{name}/.
+                      If not provided, uses the current workspace directory.
+
+    Returns:
+        Project details with created files and next steps
+    """
+    # Validate name format
+    if not name.replace("-", "").replace("_", "").isalnum():
+        return {
+            "success": False,
+            "error": "Agent name must be alphanumeric with hyphens/underscores only",
+        }
+
+    # Determine project directory
+    if project_path:
+        # Use explicit path provided by the LLM/user
+        base_dir = Path(project_path).resolve()
+        if not base_dir.exists():
+            return {
+                "success": False,
+                "error": f"Project path does not exist: {project_path}",
+            }
+        if not base_dir.is_dir():
+            return {
+                "success": False,
+                "error": f"Project path is not a directory: {project_path}",
+            }
+        # Create agent directly in the provided path
+        project_dir = base_dir / name
+    else:
+        # Use automatic detection (env var, cwd, etc.)
+        project_dir = get_project_dir(name)
+
+    if project_dir.exists():
+        return {"success": False, "error": f"Directory '{project_dir}' already exists"}
+
+    try:
+        # Ensure file-store/agent-store structure exists
+        agent_store_root = project_dir.parent
+        agent_store_root.mkdir(parents=True, exist_ok=True)
+
+        # Create agent directory
+        project_dir.mkdir(exist_ok=True)
+        (project_dir / "prompts").mkdir(exist_ok=True)
+        (project_dir / "tools").mkdir(exist_ok=True)
+        (project_dir / "views").mkdir(exist_ok=True)
+        (project_dir / "skills").mkdir(exist_ok=True)
+
+        # Sanitize inputs before template rendering
+        safe_name = sanitize_input(name)
+
+        # Generate agent.py
+        agent_template = jinja_env.get_template("agent.py.j2")
+        agent_code = agent_template.render(agent_id=safe_name)
+        (project_dir / "agent.py").write_text(agent_code)
+
+        # Generate metadata.json
+        metadata_template = jinja_env.get_template("metadata.json.j2")
+        # Sanitize text inputs (allow spaces and common punctuation for display_name and description)
+        safe_display_name = sanitize_input(display_name, r"a-zA-Z0-9 _-")
+        safe_description = sanitize_input(description, r"a-zA-Z0-9 .,!?_-")
+        metadata = metadata_template.render(
+            agent_id=safe_name,
+            display_name=safe_display_name,
+            description=safe_description,
+            category=category,
+        )
+        (project_dir / "metadata.json").write_text(metadata)
+
+        # Generate prompts/agent.md
+        prompt_template = jinja_env.get_template("prompt.md.j2")
+        prompt = prompt_template.render(
+            display_name=safe_display_name,
+            category=category,
+            description=safe_description,
+        )
+        (project_dir / "prompts/agent.md").write_text(prompt)
+        (project_dir / "prompts/reviewer.md").write_text("")
+        (project_dir / "prompts/view_renderer.md").write_text("")
+
+        # Generate AGENTS.md (root context file)
+        agents_template = jinja_env.get_template("agents.md.j2")
+        agents_md = agents_template.render(
+            agent_id=safe_name,
+            display_name=safe_display_name,
+            category=category,
+            description=safe_description,
+        )
+        (project_dir / "AGENTS.md").write_text(agents_md)
+
+        # Generate subdirectory AGENTS.md files for AI coding agents
+        tools_agents_template = jinja_env.get_template("tools/agent.md.j2")
+        (project_dir / "tools" / "AGENTS.md").write_text(tools_agents_template.render())
+
+        views_agents_template = jinja_env.get_template("views/agent.md.j2")
+        (project_dir / "views" / "AGENTS.md").write_text(views_agents_template.render())
+
+        prompts_agents_template = jinja_env.get_template("prompts/agent.md.j2")
+        (project_dir / "prompts" / "AGENTS.md").write_text(prompts_agents_template.render())
+
+        # Generate skills/AGENTS.md (skills documentation)
+        skills_agents_template = jinja_env.get_template("skills/agents.md.j2")
+        skills_agents_md = skills_agents_template.render(agent_id=safe_name)
+        (project_dir / "skills/AGENTS.md").write_text(skills_agents_md)
+
+        # Create welcome view (MANDATORY)
+        from ..views.helpers import create_view
+        create_view(
+            view_id="welcome",
+            description="Welcome view for the agent",
+            props={"title": {"type": "string", "description": "Welcome title"}},
+            project_dir=project_dir,
+        )
+
+        # Create example content based on template
+        if template in ["with-tools", "full"]:
+            # Create example tool
+            example_tool_code = '''from a4e.sdk import tool
+from typing import Optional, Any
+
+@tool
+def example_tool(
+    query: str,
+    max_results: Optional[int] = 10
+) -> dict:
+    """
+    Example tool that demonstrates basic functionality
+    
+    Args:
+        query: Search query or input text
+        max_results: Maximum number of results to return
+    """
+    # TODO: Implement your tool logic here
+    return {
+        "status": "success",
+        "message": f"Processed query: {query}",
+        "results": []
+    }
+'''
+            (project_dir / "tools" / "example_tool.py").write_text(example_tool_code)
+
+        if template in ["with-views", "full"]:
+            # Create example view (in addition to welcome)
+            create_view(
+                view_id="example_view",
+                description="Example view demonstrating props usage",
+                props={
+                    "title": {"type": "string", "description": "View title"},
+                    "count": {"type": "number", "description": "Count value"},
+                },
+                project_dir=project_dir,
+            )
+
+        # Create welcome skill (connects welcome view)
+        from ..skills.helpers import create_skill
+        create_skill(
+            skill_id="show_welcome",
+            name="Show Welcome",
+            description="Display the welcome screen. Use when user wants to go home or start over.",
+            intent_triggers=["start over", "go home", "main menu", "welcome", "inicio", "volver al inicio"],
+            output_view="welcome",
+            internal_tools=[],
+            requires_auth=False,
+            view_props={"title": {"type": "string", "description": "Welcome title"}},
+            project_dir=project_dir,
+        )
+
+        # Auto-generate schemas after project initialization
+        from ..schemas import generate_schemas
+        generate_schemas(force=False, agent_name=name)
+
+        _PROJECT_DIR = get_configured_project_dir()
+        return {
+            "success": True,
+            "message": f"Initialized agent '{name}'",
+            "path": str(project_dir),
+            "diagnostic": {
+                "workspace_env": os.environ.get("A4E_WORKSPACE"),
+                "project_dir_flag": str(_PROJECT_DIR) if _PROJECT_DIR else None,
+                "detected_root": str(get_project_dir()),
+                "cwd": str(Path.cwd()),
+            },
+            "next_steps": [
+                f"Add tools: add_tool(..., agent_name='{name}')",
+                f"Add views: add_view(..., agent_name='{name}')",
+                f"Add skills: add_skill(..., agent_name='{name}')",
+                "Start dev server using 'dev_start'",
+            ],
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}

a4e/tools/schemas/__init__.py

@@ -0,0 +1,8 @@
+"""
+Schema generation tools.
+"""
+
+from .generate_schemas import generate_schemas
+
+__all__ = ["generate_schemas"]
+