a4e 0.1.5__py3-none-any.whl

a4e/templates/agents.md.j2

@@ -0,0 +1,99 @@
+# AGENTS.md — {{ display_name }}
+
+> **⚠️ IMPORTANT:** Keep this file updated as you modify the agent. This ensures AI coding agents can work effectively with your agent project.
+
+## Overview
+
+**{{ display_name }}** is an A4E agent in the **{{ category }}** category.
+
+{{ description }}
+
+## Project Structure
+
+```
+{{ agent_id }}/
+├── AGENTS.md           # This file - context for AI coding agents
+├── agent.py            # Agent factory and initialization
+├── metadata.json       # Agent metadata for the marketplace
+├── prompts/
+│   ├── agent.md        # Main agent personality and instructions
+│   ├── reviewer.md     # Review/validation prompts
+│   └── view_renderer.md # View rendering instructions
+├── tools/
+│   ├── AGENTS.md       # Tool-specific instructions
+│   ├── schemas.json    # Auto-generated tool schemas
+│   └── *.py            # Python tool files
+└── views/
+    ├── AGENTS.md       # View-specific instructions
+    ├── schemas.json    # Auto-generated view schemas
+    └── */view.tsx      # React view components
+```
+
+## Quick Reference
+
+| Action                  | Command / Location                        |
+| ----------------------- | ----------------------------------------- |
+| Add a tool              | Create `tools/<tool_name>.py` with @tool  |
+| Add a view              | Create `views/<view_id>/view.tsx`         |
+| Modify personality      | Edit `prompts/agent.md`                   |
+| Update metadata         | Edit `metadata.json`                      |
+| Regenerate schemas      | Run `generate_schemas` MCP tool           |
+| Start dev server        | Run `dev_start` MCP tool                  |
+
+## Code Style
+
+- Python 3.11+ for tools
+- TypeScript/React for views
+- Use type hints for all function parameters
+- Snake_case for Python, camelCase for TypeScript
+- All code and comments in English
+
+## Tools
+
+Tools are Python functions that give the agent capabilities. Each tool:
+- Lives in `tools/<tool_name>.py`
+- Uses the `@tool` decorator from `a4e.sdk`
+- Returns a dictionary with `status` and relevant data
+- Has comprehensive docstrings for schema generation
+
+See `tools/AGENTS.md` for detailed tool development guide.
+
+## Views
+
+Views are React components for rich UI responses. Each view:
+- Lives in `views/<view_id>/view.tsx`
+- Exports a default React component
+- Receives props defined in the component interface
+- Uses the A4E SDK for integrations
+
+See `views/AGENTS.md` for detailed view development guide.
+
+## Schema Generation
+
+Schemas are auto-generated from code:
+- `tools/schemas.json` - Generated from Python tool decorators and docstrings
+- `views/schemas.json` - Generated from TypeScript prop interfaces
+
+**Never edit schema files manually** — they are regenerated automatically.
+
+## Development Workflow
+
+1. **Edit code** — Modify tools, views, or prompts as needed
+2. **Regenerate schemas** — Run `generate_schemas` after tool/view changes
+3. **Test locally** — Use `dev_start` to run the agent locally
+4. **Deploy** — Use `deploy` to publish to A4E Hub
+
+## Security Notes
+
+- Never hardcode API keys or secrets in code
+- Use environment variables for sensitive configuration
+- Validate all user inputs in tools
+- Sanitize data before rendering in views
+
+## Category: {{ category }}
+
+This agent is designed for {{ category }} use cases. Keep this focus in mind when:
+- Adding new tools (should relate to {{ category }})
+- Designing views (should serve {{ category }} needs)
+- Writing prompts (should maintain {{ category }} expertise)
+

a4e/templates/metadata.json.j2

@@ -0,0 +1,20 @@
+{
+  "id": {{ agent_id|tojson }},
+  "name": {{ display_name|tojson }},
+  "shortDescription": {{ description|tojson }},
+  "description": {{ description|tojson }},
+  "avatar": "",
+  "icon": "",
+  "category": {{ category|tojson }},
+  "rating": 0.0,
+  "reviewCount": 0,
+  "featured": false,
+  "tags": [],
+  "capabilities": [],
+  "pricing": "free",
+  "author": "Unknown",
+  "version": "1.0.0",
+  "status": "draft",
+  "longDescription": {{ description|tojson }},
+  "reviews": []
+}

a4e/templates/prompt.md.j2

@@ -0,0 +1,20 @@
+# {{ display_name }}
+
+You are {{ display_name }}, a specialized AI assistant for {{ category }}.
+
+## Your Mission
+
+{{ description }}
+
+## Capabilities
+
+- Helpful assistance
+- Tool usage
+- View display
+
+## Conversation Guidelines
+
+1. Be helpful and clear
+2. Use views to display rich information
+3. Use tools to perform actions
+4. Hand over to other agents when appropriate

a4e/templates/prompts/agent.md.j2

@@ -0,0 +1,206 @@
+# AGENTS.md — Prompts Directory
+
+> This file provides context and instructions for AI coding agents working on prompts in this A4E agent project.
+
+## Overview
+
+This `prompts/` directory contains markdown files that define the agent's personality, behavior, and specialized instructions. These prompts are loaded and used by the A4E runtime.
+
+## Directory Structure
+
+```
+prompts/
+├── AGENTS.md           # This file
+├── agent.md            # Main agent personality and instructions
+├── reviewer.md         # Review/validation prompts (optional)
+└── view_renderer.md    # View rendering instructions (optional)
+```
+
+## Prompt Files
+
+### agent.md (Required)
+
+The main prompt that defines the agent's:
+- **Identity**: Who the agent is and its expertise
+- **Mission**: Primary goals and purpose
+- **Capabilities**: What the agent can do
+- **Guidelines**: How to interact with users
+- **Constraints**: What the agent should avoid
+
+### reviewer.md (Optional)
+
+Used for review and validation workflows:
+- Quality checks on agent responses
+- Fact verification instructions
+- Style and tone guidelines
+
+### view_renderer.md (Optional)
+
+Instructions for rendering views:
+- When to use specific views
+- Data formatting for views
+- Fallback behavior
+
+## Writing Effective Prompts
+
+### Structure
+
+Use clear markdown structure:
+
+```markdown
+# Agent Name
+
+You are [Agent Name], a specialized AI assistant for [domain].
+
+## Your Mission
+
+[Clear statement of purpose]
+
+## Capabilities
+
+- Capability 1
+- Capability 2
+- Capability 3
+
+## Guidelines
+
+1. Be helpful and clear
+2. Use tools appropriately
+3. Display rich views when beneficial
+
+## Constraints
+
+- Never do X
+- Always verify Y
+- Avoid Z in responses
+```
+
+### Best Practices
+
+1. **Be specific**: Define exact behaviors, not vague guidelines
+2. **Use examples**: Show expected input/output patterns
+3. **Set boundaries**: Clearly state what the agent should NOT do
+4. **Maintain consistency**: Keep tone and style uniform
+5. **Reference tools**: Mention available tools and when to use them
+
+### Variables and Templates
+
+Prompts can use template variables:
+
+```markdown
+# {{ display_name }}
+
+You are {{ display_name }}, specialized in {{ category }}.
+
+{{ description }}
+```
+
+Available variables:
+- `{{ display_name }}` - Human-readable agent name
+- `{{ category }}` - Agent category
+- `{{ description }}` - Agent description
+
+## Tool Integration
+
+Reference tools in your prompts:
+
+```markdown
+## Available Tools
+
+- **calculate_bmi**: Use when user asks about BMI calculations
+- **fetch_nutrition**: Use to get nutritional information
+- **create_meal_plan**: Use for meal planning requests
+
+When a user asks about nutrition, first use `fetch_nutrition` to get data,
+then present it using the `NutritionView` component.
+```
+
+## View Integration
+
+Guide view usage in prompts:
+
+```markdown
+## View Usage
+
+When displaying results, use appropriate views:
+
+- **Welcome**: Show on first interaction
+- **MealPlan**: Display meal plans with full details
+- **NutritionFacts**: Show nutritional breakdowns
+
+Always prefer views over plain text for structured data.
+```
+
+## Prompt Engineering Tips
+
+### Context Setting
+
+```markdown
+You are an expert nutritionist with 20 years of experience.
+You specialize in personalized meal planning and dietary advice.
+Your approach is warm, encouraging, and evidence-based.
+```
+
+### Behavioral Guidelines
+
+```markdown
+## Response Format
+
+1. Acknowledge the user's question
+2. Provide relevant information
+3. Offer actionable next steps
+4. Ask follow-up questions if needed
+
+## Tone
+
+- Professional but friendly
+- Encouraging, not judgmental
+- Clear and concise
+- Use simple language
+```
+
+### Error Handling
+
+```markdown
+## When You Don't Know
+
+If you cannot answer a question:
+1. Acknowledge the limitation honestly
+2. Suggest alternative resources
+3. Offer to help with related topics
+4. Never make up information
+```
+
+## Testing Prompts
+
+Before deployment:
+
+1. **Read through** the entire prompt for clarity
+2. **Test edge cases** - unusual inputs and requests
+3. **Check consistency** - does the agent maintain character?
+4. **Verify tool usage** - are tools called appropriately?
+5. **Review view rendering** - are views displayed correctly?
+
+## Troubleshooting
+
+### Agent not following instructions
+
+- Make instructions more explicit
+- Add examples of expected behavior
+- Reduce ambiguity in guidelines
+- Check for conflicting instructions
+
+### Inconsistent personality
+
+- Strengthen identity statements
+- Add more context about the character
+- Include sample responses
+- Review and remove conflicting guidelines
+
+### Tool misuse
+
+- Clarify when each tool should be used
+- Provide examples of correct tool invocation
+- Add constraints about tool usage
+- Define fallback behavior
+

a4e/templates/skills/agents.md.j2

@@ -0,0 +1,110 @@
+# Skills
+
+> Skills are the orchestration layer that connects user intents → tools → views.
+
+## Structure
+
+```
+skills/
+├── AGENTS.md           # This file
+├── schemas.json        # All skills definitions
+└── {skill_id}/
+    └── SKILL.md        # Instructions for View Renderer
+```
+
+## How Skills Work
+
+```
+User Message → Skill Selector → Matched Skill → View Renderer → Output
+                    ↓                  ↓              ↓
+              schemas.json        SKILL.md      tools/ + views/
+```
+
+1. **Skill Selector** reads `schemas.json` to find matching skill by `intent_triggers`
+2. **View Renderer** reads `SKILL.md` for instructions on how to call tools and prepare view params
+3. **Output** is rendered using the specified view from `views/`
+
+## Creating Skills
+
+Use the MCP tool `add_skill`:
+
+```python
+add_skill(
+    skill_id="show_products",
+    name="Show Products",
+    description="Display product catalog when user wants to browse",
+    intent_triggers=["show products", "ver productos", "browse catalog"],
+    output_view="products_list",
+    internal_tools=["get_products"],
+    agent_name="{{ agent_id }}"
+)
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `skill_id` | ✅ | Unique ID (snake_case) |
+| `name` | ✅ | Human-readable name |
+| `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 (or "NONE") |
+| `internal_tools` | ❌ | List of tools the skill uses |
+| `requires_auth` | ❌ | Whether auth is required (default: false) |
+
+## schemas.json Format
+
+```json
+{
+  "skill_id": {
+    "id": "skill_id",
+    "name": "Skill Name",
+    "description": "What this skill does",
+    "intent_triggers": ["phrase 1", "phrase 2"],
+    "requires_auth": false,
+    "internal_tools": ["tool_name"],
+    "output": {
+      "view": "view_id"
+    }
+  }
+}
+```
+
+## SKILL.md Format
+
+Each skill folder contains a `SKILL.md` that documents:
+
+1. **Purpose** - What the skill does
+2. **When to Use** - Intent triggers
+3. **Instructions for View Renderer** - How to call tools and prepare params
+4. **Expected Output** - Example code
+5. **Parameter Extraction Rules** - How to map user intents to parameters
+
+## Dependencies
+
+Skills connect to:
+
+- **Tools** (`tools/`) - Python functions that fetch/process data
+- **Views** (`views/`) - React components that render the UI
+
+### Validation
+
+Before creating a skill:
+1. The `output_view` must exist in `views/`
+2. The `internal_tools` should exist in `tools/schemas.json`
+
+## Listing Skills
+
+Use the MCP tool `list_skills`:
+
+```python
+list_skills(agent_name="{{ agent_id }}")
+```
+
+## Best Practices
+
+1. **Specific triggers** - Avoid generic phrases that could match multiple skills
+2. **Clear descriptions** - Help the Skill Selector understand when to use this skill
+3. **Document SKILL.md** - The View Renderer relies on this for execution
+4. **Validate dependencies** - Ensure tools and views exist before creating skills
+

a4e/templates/skills/skill.md.j2

@@ -0,0 +1,120 @@
+# {{ skill_name }} Skill
+
+## Purpose
+
+{{ description }}
+
+## When to Use
+
+This skill is triggered by phrases like:
+{% for trigger in intent_triggers %}
+- "{{ trigger }}"
+{% endfor %}
+
+## Instructions for View Renderer
+
+{% if internal_tools %}
+### 1. Call Internal Tools
+
+**IMPORTANT**: All tools use the `params: Dict[str, Any]` pattern. Pass parameters as a dictionary:
+
+{% for tool in internal_tools %}
+```python
+# Call {{ tool }} with required parameters
+{{ tool }}_result = {{ tool }}({
+    # Add required parameters here as key-value pairs
+    # Example: "param_name": value
+})
+```
+{% endfor %}
+
+### 2. Prepare View Parameters
+
+Extract data from tool results and build the view params object:
+
+{% else %}
+### 1. Prepare View Parameters
+
+This skill has no internal tools. Build the view params directly:
+
+{% endif %}
+{% if view_props %}
+```python
+view_params = {
+{% for prop_name, prop_info in view_props.items() %}
+{% set prop_type = prop_info.get('type', 'string') if prop_info is mapping else prop_info %}
+{% if internal_tools %}
+    "{{ prop_name }}": {{ internal_tools[0] }}_result.get("{{ prop_name }}"),  # {{ prop_type }}
+{% else %}
+    "{{ prop_name }}": ...,  # {{ prop_type }}{% if prop_info is mapping and prop_info.get('description') %} - {{ prop_info.get('description') }}{% endif %}
+
+{% endif %}
+{% endfor %}
+}
+```
+
+### View Props Reference
+
+| Property | Type | Description |
+|----------|------|-------------|
+{% for prop_name, prop_info in view_props.items() %}
+| `{{ prop_name }}` | {{ prop_info.get('type', 'any') if prop_info is mapping else prop_info }} | {{ prop_info.get('description', '-') if prop_info is mapping else '-' }} |
+{% endfor %}
+{% else %}
+```python
+view_params = {
+    # Define view parameters based on tool results
+}
+```
+{% endif %}
+
+## Example Implementation
+
+```python
+{% if internal_tools %}
+# Step 1: Call the required tools with params dict pattern
+{% for tool in internal_tools %}
+{{ tool }}_data = {{ tool }}({
+    # Add your parameters here
+})
+{% endfor %}
+
+# Step 2: Extract data and build view_params
+{% endif %}
+view_params = {
+{% for prop_name, prop_info in view_props.items() %}
+{% set prop_type = prop_info.get('type', 'string') if prop_info is mapping else prop_info %}
+{% if prop_type == 'string' %}
+    "{{ prop_name }}": "Sample {{ prop_name }}",
+{% elif prop_type == 'number' or prop_type == 'integer' %}
+    "{{ prop_name }}": 0,
+{% elif prop_type == 'boolean' %}
+    "{{ prop_name }}": False,
+{% elif prop_type == 'array' %}
+    "{{ prop_name }}": [],
+{% elif prop_type == 'object' %}
+    "{{ prop_name }}": {},
+{% else %}
+    "{{ prop_name }}": None,
+{% endif %}
+{% endfor %}
+}
+```
+
+## Parameter Extraction Rules
+
+When extracting parameters from the user's message:
+
+| User Intent | Parameters to Extract |
+|-------------|----------------------|
+{% for trigger in intent_triggers[:3] %}
+| "{{ trigger }}" | Analyze message for relevant values |
+{% endfor %}
+
+## Important Notes
+
+- **Output view:** `{{ output_view }}`
+{% if requires_auth %}- **Authentication:** Required - ensure user is authenticated{% else %}- **Authentication:** Not required{% endif %}
+{% if internal_tools %}- **Tool dependencies:** {{ internal_tools | join(', ') }}{% endif %}
+- **Tool calling pattern:** Always use `tool_name({"param": value})` format
+- **Error handling:** Check tool results for `status: "success"` before using data

a4e/templates/support_module.py.j2

@@ -0,0 +1,84 @@
+"""
+{{ module_name | replace('_', ' ') | title }} - Support Module for {{ agent_name }}
+
+{{ description }}
+
+This module is designed to work in both:
+1. Direct Python execution
+2. exec() context (when loaded by A4E main application)
+"""
+# Ensure __name__ is defined for exec() context compatibility
+if '__name__' not in dir():
+    __name__ = "{{ module_name }}"
+
+import sys
+import os
+from typing import Dict, Any, Optional, List
+
+
+def _ensure_path():
+    """Add this directory to sys.path if not already there."""
+    if '__file__' in dir():
+        module_dir = os.path.dirname(globals()['__file__'])
+        if module_dir not in sys.path:
+            sys.path.insert(0, module_dir)
+
+
+# Ensure path is set up
+_ensure_path()
+
+
+# =============================================================================
+# {{ module_name | upper }} IMPLEMENTATION
+# =============================================================================
+
+# TODO: Implement your {{ module_name }} logic here
+# Example functions:
+
+def get_data(key: str) -> Optional[Dict[str, Any]]:
+    """
+    Get data by key.
+    
+    Args:
+        key: The data key to retrieve
+        
+    Returns:
+        Data dictionary or None if not found
+    """
+    # TODO: Implement data retrieval
+    return {"key": key, "value": "sample"}
+
+
+def save_data(key: str, data: Dict[str, Any]) -> bool:
+    """
+    Save data with key.
+    
+    Args:
+        key: The data key
+        data: The data to save
+        
+    Returns:
+        True if successful, False otherwise
+    """
+    # TODO: Implement data storage
+    return True
+
+
+# =============================================================================
+# MODULE SELF-TEST
+# =============================================================================
+
+# Only run when executed directly (not when exec'd by the main app)
+if globals().get('__name__') == "__main__":
+    print(f"Testing {__name__} module...")
+    
+    # Test get_data
+    result = get_data("test_key")
+    print(f"get_data result: {result}")
+    
+    # Test save_data
+    success = save_data("test_key", {"test": "data"})
+    print(f"save_data success: {success}")
+    
+    print("All tests passed!")
+