a4e 0.1.5__py3-none-any.whl

a4e/templates/tool.py.j2

@@ -0,0 +1,60 @@
+"""
+{{ tool_name | replace('_', ' ') | title }} Tool
+
+{{ description }}
+"""
+from typing import Dict, Any, Optional
+import sys
+import os
+
+
+def _ensure_imports():
+    """
+    Add tools directory to sys.path if not already there.
+    This enables imports of support files (db.py, models.py, etc.) when exec()'d.
+    """
+    if '__file__' in globals():
+        tools_dir = os.path.dirname(globals()['__file__'])
+        if tools_dir not in sys.path:
+            sys.path.insert(0, tools_dir)
+
+
+def {{ tool_name }}(params: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    {{ description }}
+
+    Args:
+        params: Dictionary containing:
+{% for param_name, param_info in parameters.items() %}
+            - {{ param_name }}: {{ param_info.description if param_info.description else param_info.type }}{% if not param_info.is_required %} (optional){% endif %}
+
+{% endfor %}
+    Returns:
+        Dict with operation result
+    """
+    # Extract parameters from params dict
+{% for param_name, param_info in parameters.items() %}
+{% if param_info.is_required %}
+    {{ param_name }} = params.get("{{ param_name }}")
+{% else %}
+    {{ param_name }} = params.get("{{ param_name }}")
+{% endif %}
+{% endfor %}
+
+    # Ensure imports work in exec() context
+    _ensure_imports()
+
+    # TODO: Implement {{ tool_name }} logic here
+    # Example: Import support modules if needed
+    # try:
+    #     import db
+    # except ImportError:
+    #     return {"status": "error", "message": "Database module not available"}
+
+    return {
+        "status": "success",
+        "message": "{{ tool_name | replace('_', ' ') | title }} executed successfully",
+{% for param_name, param_info in parameters.items() %}
+        "{{ param_name }}": {{ param_name }},
+{% endfor %}
+    }

a4e/templates/tools/agent.md.j2

@@ -0,0 +1,192 @@
+# AGENTS.md — Tools Directory
+
+> This file provides context and instructions for AI coding agents working on tools in this A4E agent project.
+
+## Overview
+
+This `tools/` directory contains Python functions decorated with `@tool` that give the agent the ability to perform actions or retrieve information. Each tool is a self-contained Python file that gets automatically discovered and registered.
+
+## Directory Structure
+
+```
+tools/
+├── AGENTS.md           # This file
+├── schemas.json        # Auto-generated schemas (do not edit manually)
+├── example_tool.py     # Example tool (if template includes it)
+└── <your_tools>.py     # Your custom tools
+```
+
+## Code Style
+
+- Python 3.11+ required
+- Use type hints for ALL function parameters and return types
+- Use `Optional[T]` for optional parameters, not `T | None`
+- Snake_case for function and file names
+- Each tool must return a `dict` with a clear response structure
+
+## Tool Structure
+
+Every tool file must follow this pattern:
+
+```python
+from a4e.sdk import tool
+from typing import Optional, List, Any
+
+@tool
+def tool_name(
+    required_param: str,
+    optional_param: Optional[int] = None
+) -> dict:
+    """
+    Brief description of what the tool does.
+
+    Args:
+        required_param: Description of this parameter
+        optional_param: Description of this optional parameter
+    """
+    # Implementation here
+    return {
+        "status": "success",
+        "message": "Result message",
+        "data": {}  # Optional: include relevant data
+    }
+```
+
+## Type Mapping
+
+When creating tools, use these Python types:
+
+| Use Case          | Type                     | Example                        |
+| ----------------- | ------------------------ | ------------------------------ |
+| Text              | `str`                    | `name: str`                    |
+| Integer           | `int`                    | `count: int`                   |
+| Decimal           | `float`                  | `price: float`                 |
+| Boolean           | `bool`                   | `active: bool`                 |
+| List              | `List[T]`                | `items: List[str]`             |
+| Dictionary        | `dict`                   | `config: dict`                 |
+| Optional          | `Optional[T]`            | `limit: Optional[int] = None`  |
+| Literal choices   | `Literal["a", "b"]`      | `mode: Literal["fast", "slow"]`|
+| Any type          | `Any`                    | `data: Any`                    |
+
+## Return Value Conventions
+
+Always return a dictionary with consistent keys:
+
+```python
+# Success response
+return {
+    "status": "success",
+    "message": "Human-readable success message",
+    "data": {...}  # Tool-specific data
+}
+
+# Error response
+return {
+    "status": "error",
+    "message": "Human-readable error message",
+    "error_code": "SPECIFIC_ERROR"  # Optional: machine-readable code
+}
+```
+
+## Naming Conventions
+
+- **File names**: `snake_case.py` (e.g., `calculate_bmi.py`, `fetch_weather.py`)
+- **Function names**: Match file name exactly (e.g., `def calculate_bmi(...)`)
+- **Parameter names**: Descriptive snake_case (e.g., `user_weight_kg`, `max_results`)
+
+## Adding a New Tool
+
+1. Create a new file: `tools/<tool_name>.py`
+2. Use the `@tool` decorator from `a4e.sdk`
+3. Add comprehensive docstring with Args section
+4. Implement the logic returning a dict
+5. Run schema generation to update `schemas.json`
+
+## Schema Generation
+
+Schemas are auto-generated from your tool code. After adding or modifying tools:
+
+- Schemas are regenerated automatically when using MCP tools
+- The `schemas.json` file is auto-generated — **do not edit manually**
+- Docstrings become the tool's description in the schema
+
+## Testing Your Tools
+
+Before deployment, verify your tools:
+
+1. Check syntax: `python -m py_compile tools/<tool_name>.py`
+2. Import test: `python -c "from tools.<tool_name> import <tool_name>; print('OK')"`
+3. Run via dev server to test integration
+
+## Common Patterns
+
+### API Calls
+
+```python
+import requests
+
+@tool
+def fetch_data(endpoint: str) -> dict:
+    """Fetch data from an API endpoint."""
+    try:
+        response = requests.get(endpoint, timeout=10)
+        response.raise_for_status()
+        return {"status": "success", "data": response.json()}
+    except Exception as e:
+        return {"status": "error", "message": str(e)}
+```
+
+### Calculations
+
+```python
+@tool
+def calculate_bmi(weight_kg: float, height_m: float) -> dict:
+    """Calculate Body Mass Index."""
+    if height_m <= 0:
+        return {"status": "error", "message": "Height must be positive"}
+    
+    bmi = weight_kg / (height_m ** 2)
+    return {
+        "status": "success",
+        "bmi": round(bmi, 2),
+        "category": "normal" if 18.5 <= bmi < 25 else "other"
+    }
+```
+
+### Data Transformation
+
+```python
+from typing import List
+
+@tool
+def format_list(items: List[str], separator: str = ", ") -> dict:
+    """Format a list of items into a string."""
+    return {
+        "status": "success",
+        "result": separator.join(items),
+        "count": len(items)
+    }
+```
+
+## Security Considerations
+
+- Never hardcode sensitive data (API keys, passwords)
+- Validate and sanitize all user inputs
+- Use try/except for external calls
+- Limit resource usage (timeouts, max sizes)
+
+## Troubleshooting
+
+### Tool not appearing in schema
+
+- Verify the `@tool` decorator is present
+- Check for syntax errors in the file
+- Ensure the function has type hints and docstring
+- Run schema generation manually
+
+### Import errors
+
+- Check all imports are available in the environment
+- Use absolute imports when possible
+- Verify dependency is in the project requirements
+

a4e/templates/view.tsx.j2

@@ -0,0 +1,21 @@
+"use client";
+import React from "react";
+import { a4e } from "@/lib/sdk";
+
+interface {{ view_name }}Props {
+{% for prop_name, prop_info in props.items() %}
+  {{ prop_name }}: {{ prop_info.type }};
+{% endfor %}
+}
+
+export default function {{ view_name }}View(props: {{ view_name }}Props) {
+  const { {% for prop_name in props.keys() %}{{ prop_name }}{% if not loop.last %}, {% endif %}{% endfor %} } = props;
+
+  return (
+    <div className="p-6">
+      <h2>{{ description }}</h2>
+      {/* View content */}
+      <pre>{JSON.stringify(props, null, 2)}</pre>
+    </div>
+  );
+}

a4e/templates/views/agent.md.j2

@@ -0,0 +1,219 @@
+# AGENTS.md — Views Directory
+
+> This file provides context and instructions for AI coding agents working on views in this A4E agent project.
+
+## Overview
+
+This `views/` directory contains React components that provide rich graphical interfaces for the agent's responses. Each view is a self-contained directory with a `view.tsx` file.
+
+## Directory Structure
+
+```
+views/
+├── AGENTS.md           # This file
+├── schemas.json        # Auto-generated schemas (do not edit manually)
+├── welcome/            # Mandatory welcome view
+│   └── view.tsx
+└── <view_id>/          # Your custom views
+    └── view.tsx
+```
+
+## Code Style
+
+- TypeScript with React
+- Use functional components with hooks
+- camelCase for variables and functions
+- PascalCase for component names
+- Props interface must be explicitly defined
+
+## View Structure
+
+Every view file must follow this pattern:
+
+```tsx
+"use client";
+import React from "react";
+import { a4e } from "@/lib/sdk";
+
+interface ViewNameProps {
+  title: string;
+  count: number;
+  items?: string[];
+}
+
+export default function ViewNameView(props: ViewNameProps) {
+  const { title, count, items = [] } = props;
+
+  return (
+    <div className="p-6">
+      <h2 className="text-xl font-bold">{title}</h2>
+      <p>Count: {count}</p>
+      {items.length > 0 && (
+        <ul>
+          {items.map((item, i) => (
+            <li key={i}>{item}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+## Naming Conventions
+
+- **Directory names**: `snake_case` (e.g., `meal_plan`, `bmi_result`)
+- **Component names**: `PascalCase + View` (e.g., `MealPlanView`, `BmiResultView`)
+- **Prop names**: `camelCase` (e.g., `userName`, `maxItems`)
+
+## Type Mapping
+
+When defining props, use TypeScript types:
+
+| Use Case          | Type               | Example                     |
+| ----------------- | ------------------ | --------------------------- |
+| Text              | `string`           | `title: string`             |
+| Integer/Decimal   | `number`           | `count: number`             |
+| Boolean           | `boolean`          | `isActive: boolean`         |
+| Array             | `T[]`              | `items: string[]`           |
+| Object            | `object`           | `user: object`              |
+| Optional          | `T?` or `T \| undefined` | `subtitle?: string`   |
+| Union             | `"a" \| "b"`       | `status: "active" \| "inactive"` |
+
+## Adding a New View
+
+1. Create directory: `views/<view_id>/`
+2. Create file: `views/<view_id>/view.tsx`
+3. Define props interface at the top
+4. Export default functional component
+5. Run schema generation to update `schemas.json`
+
+## Schema Generation
+
+Schemas are auto-generated from your TypeScript interfaces:
+
+- Props interface becomes the view's input schema
+- Type annotations are converted to JSON Schema types
+- Comments become descriptions in the schema
+- The `schemas.json` file is auto-generated — **do not edit manually**
+
+## Styling Guidelines
+
+Use Tailwind CSS classes for styling:
+
+```tsx
+// Good: Tailwind utilities
+<div className="p-4 bg-white rounded-lg shadow-md">
+  <h2 className="text-lg font-semibold text-gray-900">Title</h2>
+</div>
+
+// Prefer Tailwind over inline styles
+<div className="p-4">Content</div>
+```
+
+## Common Patterns
+
+### Card Layout
+
+```tsx
+export default function CardView(props: { title: string; content: string }) {
+  return (
+    <div className="bg-white rounded-xl shadow-lg p-6 max-w-md">
+      <h3 className="text-xl font-bold mb-4">{props.title}</h3>
+      <p className="text-gray-600">{props.content}</p>
+    </div>
+  );
+}
+```
+
+### List Display
+
+```tsx
+interface ListViewProps {
+  title: string;
+  items: Array<{ id: string; name: string }>;
+}
+
+export default function ListView({ title, items }: ListViewProps) {
+  return (
+    <div className="space-y-4">
+      <h2 className="text-2xl font-bold">{title}</h2>
+      <ul className="divide-y divide-gray-200">
+        {items.map((item) => (
+          <li key={item.id} className="py-3">
+            {item.name}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+### Data Visualization
+
+```tsx
+interface ChartViewProps {
+  data: Array<{ label: string; value: number }>;
+}
+
+export default function ChartView({ data }: ChartViewProps) {
+  return (
+    <div className="space-y-2">
+      {data.map((item, i) => (
+        <div key={i} className="flex items-center gap-4">
+          <span className="w-24 text-sm">{item.label}</span>
+          <div className="h-6 bg-blue-500 rounded w-full" />
+          <span className="text-sm font-medium">{item.value}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## A4E SDK Integration
+
+Use the A4E SDK for agent interactions:
+
+```tsx
+import { a4e } from "@/lib/sdk";
+
+export default function InteractiveView(props: { query: string }) {
+  const handleAction = async () => {
+    // Trigger agent action
+    await a4e.triggerAction("perform_search", { query: props.query });
+  };
+
+  return (
+    <button onClick={handleAction} className="btn-primary">
+      Search
+    </button>
+  );
+}
+```
+
+## Accessibility
+
+- Use semantic HTML elements (`<main>`, `<nav>`, `<article>`)
+- Add `alt` text to images
+- Ensure sufficient color contrast
+- Support keyboard navigation
+- Use ARIA labels where needed
+
+## Troubleshooting
+
+### View not appearing in schema
+
+- Verify the props interface is exported or defined at module level
+- Check for TypeScript syntax errors
+- Ensure the component is the default export
+- Run schema generation manually
+
+### Styling not applied
+
+- Verify Tailwind classes are valid
+- Check for typos in class names
+- Ensure the build process includes Tailwind
+- Use browser dev tools to inspect applied styles
+

a4e/tools/__init__.py

@@ -0,0 +1,70 @@
+"""
+A4E MCP Tools - All tools for agent creation and management.
+
+Structure:
+- project/      : Project initialization (initialize_project, get_agent_info)
+- agent_tools/  : Tool management (add_tool, list_tools, remove_tool, update_tool)
+- views/        : View management (add_view, list_views, remove_view, update_view)
+- skills/       : Skill management (add_skill, list_skills, remove_skill, update_skill)
+- schemas/      : Schema generation (generate_schemas)
+- validation/   : Validation (validate)
+- dev/          : Development server (dev_start, dev_stop, check_environment)
+- deploy/       : Deployment (deploy)
+"""
+
+# Project tools
+from .project import initialize_project, get_agent_info, get_instructions
+
+# Agent tools management
+from .agent_tools import add_tool, list_tools, remove_tool, update_tool
+
+# Views management
+from .views import add_view, list_views, remove_view, update_view
+
+# Skills management
+from .skills import add_skill, list_skills, remove_skill, update_skill
+
+# Schema generation
+from .schemas import generate_schemas
+
+# Validation
+from .validation import validate
+
+# Development
+from .dev import dev_start, dev_stop, check_environment
+
+# Deployment
+from .deploy import deploy
+
+__all__ = [
+    # Project
+    "initialize_project",
+    "get_agent_info",
+    "get_instructions",
+    # Agent tools
+    "add_tool",
+    "list_tools",
+    "remove_tool",
+    "update_tool",
+    # Views
+    "add_view",
+    "list_views",
+    "remove_view",
+    "update_view",
+    # Skills
+    "add_skill",
+    "list_skills",
+    "remove_skill",
+    "update_skill",
+    # Schemas
+    "generate_schemas",
+    # Validation
+    "validate",
+    # Development
+    "dev_start",
+    "dev_stop",
+    "check_environment",
+    # Deployment
+    "deploy",
+]
+

a4e/tools/agent_tools/__init__.py

@@ -0,0 +1,12 @@
+"""
+Agent tools management.
+"""
+
+from .add_tool import add_tool
+from .add_support_module import add_support_module
+from .list_tools import list_tools
+from .remove_tool import remove_tool
+from .update_tool import update_tool
+
+__all__ = ["add_tool", "add_support_module", "list_tools", "remove_tool", "update_tool"]
+

a4e/tools/agent_tools/add_support_module.py

@@ -0,0 +1,95 @@
+"""
+Add support module tool.
+
+Creates support modules (db.py, models.py, etc.) with exec() compatibility
+for proper loading in the A4E main application.
+"""
+
+from typing import Optional
+
+from ...core import mcp, jinja_env, get_project_dir
+
+
+@mcp.tool()
+def add_support_module(
+    module_name: str,
+    description: str,
+    agent_name: Optional[str] = None
+) -> dict:
+    """
+    Add a support module (db.py, models.py, etc.) with exec() compatibility
+
+    Args:
+        module_name: Name of the module (snake_case, e.g., "db", "models", "helpers")
+        description: What the module does
+        agent_name: Optional agent ID if not in agent directory
+    
+    Support modules are loaded by all tools and need special handling
+    to work in the exec() context used by the A4E main application.
+    
+    The generated module includes:
+    - __name__ definition for exec() compatibility
+    - sys.path manipulation for imports
+    - Self-test code that only runs when executed directly
+    """
+    # Validate module name
+    if not module_name.replace("_", "").isalnum():
+        suggested = module_name.replace("-", "_").replace(" ", "_").lower()
+        return {
+            "success": False,
+            "error": "Module 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",
+        }
+
+    module_file = tools_dir / f"{module_name}.py"
+    if module_file.exists():
+        return {
+            "success": False,
+            "error": f"Module '{module_name}' already exists",
+            "fix": "Edit the existing file or remove it first",
+        }
+
+    try:
+        # Get agent name for template
+        metadata_file = project_dir / "metadata.json"
+        agent_display_name = module_name
+        if metadata_file.exists():
+            import json
+            try:
+                metadata = json.loads(metadata_file.read_text())
+                agent_display_name = metadata.get("name", module_name)
+            except Exception:
+                pass
+
+        template = jinja_env.get_template("support_module.py.j2")
+        code = template.render(
+            module_name=module_name,
+            description=description,
+            agent_name=agent_display_name
+        )
+        module_file.write_text(code)
+
+        return {
+            "success": True,
+            "message": f"Created support module '{module_name}' with exec() compatibility",
+            "path": str(module_file),
+            "notes": [
+                "Module includes __name__ fix for exec() context",
+                "Module includes sys.path manipulation for imports",
+                "Self-test code only runs when executed directly",
+                "This module will NOT be included in tools/schemas.json"
+            ]
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+