traia-iatp 0.1.1__py3-none-any.whl

traia_iatp/server/iatp_server_agent_generator.py

@@ -0,0 +1,237 @@
+"""Utility agent generator for A2A servers.
+
+This module generates utility agents that wrap MCP servers and expose them via A2A protocol.
+"""
+
+import json
+import logging
+import shutil
+from pathlib import Path
+from typing import Dict, Any, Optional
+from datetime import datetime
+
+from ..core.models import MCPServer, UtilityAgent, UtilityAgentStatus
+from .iatp_server_template_generator import IATPServerTemplateGenerator
+
+logger = logging.getLogger(__name__)
+
+
+class IATPServerAgentGenerator:
+    """Generate utility agents from MCP servers using templates."""
+    
+    def __init__(self, output_base_dir: Optional[Path] = None):
+        """Initialize the generator.
+        
+        Args:
+            output_base_dir: Base directory for generated agents
+        """
+        self.output_base_dir = output_base_dir or Path("generated_agents")
+        self.template_generator = IATPServerTemplateGenerator()
+    
+    def _convert_datetime_to_string(self, obj: Any) -> Any:
+        """Convert datetime objects to strings recursively.
+        
+        Args:
+            obj: Object that may contain datetime objects
+            
+        Returns:
+            Object with datetime objects converted to strings
+        """
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+        elif isinstance(obj, dict):
+            return {key: self._convert_datetime_to_string(value) for key, value in obj.items()}
+        elif isinstance(obj, list):
+            return [self._convert_datetime_to_string(item) for item in obj]
+        elif isinstance(obj, tuple):
+            return tuple(self._convert_datetime_to_string(item) for item in obj)
+        else:
+            return obj
+    
+    def generate_agent(
+        self,
+        mcp_server: MCPServer,
+        agent_name: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        agent_description: Optional[str] = None,
+        expose_individual_tools: bool = False,
+        auth_required: bool = False,
+        auth_schemes: Optional[list] = None,
+        use_simple_server: bool = True,
+        **kwargs
+    ) -> UtilityAgent:
+        """Generate a utility agent from an MCP server.
+        
+        Args:
+            mcp_server: MCP server to wrap
+            agent_name: Name for the agent (defaults to MCP server name)
+            agent_id: Unique ID for the agent (defaults to generated)
+            agent_description: Description of the agent
+            expose_individual_tools: Whether to expose individual MCP tools
+            auth_required: Whether authentication is required
+            auth_schemes: Authentication schemes if required
+            use_simple_server: Whether to use simplified server template
+            **kwargs: Additional template variables
+            
+        Returns:
+            Generated UtilityAgent object
+        """
+        # Generate defaults
+        if agent_name is None:
+            agent_name = f"{mcp_server.name} Utility Agent"
+        
+        if agent_id is None:
+            # Generate a clean ID based on MCP server name without timestamp
+            base_id = mcp_server.name.lower().replace(' ', '-').replace('_', '-')
+            agent_id = f"{base_id}-traia-utility-agent"
+        
+        if agent_description is None:
+            agent_description = f"A2A utility agent that exposes {mcp_server.name} capabilities"
+        
+        # Prepare capabilities list
+        capabilities = []
+        if hasattr(mcp_server, 'capabilities') and mcp_server.capabilities:
+            if isinstance(mcp_server.capabilities, dict):
+                capabilities = list(mcp_server.capabilities.keys())
+            elif isinstance(mcp_server.capabilities, list):
+                capabilities = mcp_server.capabilities
+        
+        # Prepare skill examples based on MCP server type
+        skill_examples = kwargs.get('skill_examples', [])
+        if not skill_examples:
+            skill_examples = self._generate_skill_examples(mcp_server)
+        
+        # Generate output directory path
+        output_dir = self.output_base_dir / agent_id
+        
+        # Get MCP server metadata and convert datetime objects to strings
+        mcp_server_metadata = getattr(mcp_server, 'metadata', {})
+        mcp_server_metadata_serializable = self._convert_datetime_to_string(mcp_server_metadata)
+        
+        # Use template generator to create the agent
+        generated_path = self.template_generator.generate_agent(
+            output_dir=output_dir,
+            agent_name=agent_name,
+            agent_id=agent_id,
+            agent_description=agent_description,
+            agent_version="0.1.0",
+            mcp_server_name=mcp_server.name,
+            mcp_server_url=mcp_server.url,
+            mcp_server_description=mcp_server.description,
+            mcp_server_type=getattr(mcp_server, 'server_type', 'streamable-http'),
+            mcp_server_capabilities=capabilities,
+            mcp_server_metadata=mcp_server_metadata_serializable,
+            expose_individual_tools=expose_individual_tools,
+            auth_required=auth_required,
+            auth_schemes=auth_schemes or [],
+            skill_examples=skill_examples,
+            use_simple_server=use_simple_server,
+            **kwargs
+        )
+        
+        # Create UtilityAgent object
+        utility_agent = UtilityAgent(
+            id=agent_id,
+            name=agent_name,
+            description=agent_description,
+            mcp_server_id=mcp_server.id,
+            capabilities=capabilities,
+            status=UtilityAgentStatus.GENERATED,
+            code_path=str(generated_path),
+            created_at=datetime.now(),
+            metadata={
+                "generated_from": mcp_server.name,
+                "use_simple_server": use_simple_server,
+                "auth_required": auth_required,
+            }
+        )
+        
+        logger.info(f"Generated utility agent '{agent_name}' at {generated_path}")
+        return utility_agent
+    
+    def _generate_skill_examples(self, mcp_server: MCPServer) -> list:
+        """Generate example prompts based on MCP server type.
+        
+        Args:
+            mcp_server: MCP server object
+            
+        Returns:
+            List of example prompts
+        """
+        # Default examples
+        examples = [
+            f"Help me use {mcp_server.name}",
+            f"What can {mcp_server.name} do?",
+        ]
+        
+        # Add type-specific examples
+        server_type = mcp_server.name.lower()
+        
+        if 'search' in server_type:
+            examples.extend([
+                "Search for information about AI",
+                "Find recent news about technology"
+            ])
+        elif 'file' in server_type or 'filesystem' in server_type:
+            examples.extend([
+                "List files in the current directory",
+                "Read the contents of a file"
+            ])
+        elif 'database' in server_type or 'db' in server_type:
+            examples.extend([
+                "Query the database for user information",
+                "Show me the database schema"
+            ])
+        elif 'api' in server_type:
+            examples.extend([
+                "Call the API to get data",
+                "Send a request to the endpoint"
+            ])
+        elif 'trading' in server_type or 'finance' in server_type:
+            examples.extend([
+                "Get the current market data",
+                "Show me trading opportunities"
+            ])
+        else:
+            # Generic examples
+            examples.extend([
+                f"Execute a {mcp_server.name} operation",
+                f"Process this request using {mcp_server.name}"
+            ])
+        
+        return examples[:5]  # Limit to 5 examples
+    
+    def update_agent_files(
+        self,
+        agent_path: Path,
+        updates: Dict[str, Any]
+    ) -> None:
+        """Update existing agent files with new configuration.
+        
+        Args:
+            agent_path: Path to the agent directory
+            updates: Dictionary of updates to apply
+        """
+        # Update agent_config.json if it exists
+        config_path = agent_path / "agent_config.json"
+        if config_path.exists():
+            with open(config_path, 'r') as f:
+                config = json.load(f)
+            
+            # Merge updates
+            config.update(updates)
+            
+            with open(config_path, 'w') as f:
+                json.dump(config, f, indent=2)
+            
+            logger.info(f"Updated agent configuration at {config_path}")
+    
+    def cleanup_agent(self, agent_path: Path) -> None:
+        """Clean up generated agent files.
+        
+        Args:
+            agent_path: Path to the agent directory
+        """
+        if agent_path.exists():
+            shutil.rmtree(agent_path)
+            logger.info(f"Cleaned up agent at {agent_path}") 

traia_iatp/server/iatp_server_template_generator.py

@@ -0,0 +1,235 @@
+"""Template generator for A2A utility agents.
+
+This module provides functionality to generate utility agent code from templates.
+"""
+
+import os
+import json
+import shutil
+from pathlib import Path
+from typing import Dict, Any, List, Optional
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class IATPServerTemplateGenerator:
+    """Generate utility agent code from Jinja2 templates."""
+    
+    def __init__(self, templates_dir: Optional[Path] = None):
+        """Initialize the template generator.
+        
+        Args:
+            templates_dir: Directory containing the Jinja2 templates
+        """
+        if templates_dir is None:
+            templates_dir = Path(__file__).parent / "templates"
+        
+        self.templates_dir = templates_dir
+        self.env = Environment(
+            loader=FileSystemLoader(self.templates_dir),
+            autoescape=select_autoescape(['html', 'xml']),
+            trim_blocks=True,
+            lstrip_blocks=True
+        )
+    
+    def generate_agent(
+        self,
+        output_dir: Path,
+        agent_name: str,
+        agent_id: str,
+        mcp_server_name: str,
+        mcp_server_url: str,
+        mcp_server_description: str,
+        mcp_server_capabilities: List[str],
+        agent_description: Optional[str] = None,
+        agent_version: str = "0.1.0",
+        mcp_server_type: str = "streamable-http",
+        mcp_server_metadata: Optional[Dict[str, Any]] = None,
+        expose_individual_tools: bool = False,
+        auth_required: bool = False,
+        auth_schemes: Optional[List[str]] = None,
+        skill_examples: Optional[List[str]] = None,
+        additional_dependencies: Optional[List[str]] = None,
+        environment_variables: Optional[List[Dict[str, str]]] = None,
+        use_simple_server: bool = True,
+        additional_ignores: Optional[List[str]] = None,
+        **kwargs
+    ) -> Path:
+        """Generate a complete utility agent from templates.
+        
+        Args:
+            output_dir: Directory to write the generated agent
+            agent_name: Human-readable name of the agent
+            agent_id: Unique identifier for the agent
+            mcp_server_name: Name of the MCP server
+            mcp_server_url: URL or path to the MCP server
+            mcp_server_description: Description of the MCP server
+            mcp_server_capabilities: List of capabilities provided by the MCP server
+            agent_description: Description of the agent (defaults to auto-generated)
+            agent_version: Version of the agent
+            mcp_server_type: Type of MCP server (stdio, http, etc.)
+            mcp_server_metadata: Additional metadata for the MCP server
+            expose_individual_tools: Whether to expose individual MCP tools as A2A skills
+            auth_required: Whether authentication is required
+            auth_schemes: List of authentication schemes if auth is required
+            skill_examples: Example prompts for the main skill
+            additional_dependencies: Extra Python dependencies
+            environment_variables: Environment variables for Dockerfile
+            use_simple_server: Whether to use the simplified server.py template
+            additional_ignores: Additional patterns to add to .gitignore
+            **kwargs: Additional template variables
+            
+        Returns:
+            Path to the generated agency directory
+        """
+        # Create output directory
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Generate default values
+        if agent_description is None:
+            agent_description = f"Utility agent that exposes {mcp_server_name} capabilities via A2A protocol"
+        
+        if skill_examples is None:
+            skill_examples = [
+                f"Help me use {mcp_server_name}",
+                f"Process this request with {mcp_server_name}",
+                "Execute this operation"
+            ]
+        
+        if mcp_server_metadata is None:
+            mcp_server_metadata = {}
+        
+        if additional_dependencies is None:
+            additional_dependencies = []
+        
+        if environment_variables is None:
+            environment_variables = []
+        
+        if additional_ignores is None:
+            additional_ignores = []
+        
+        # Convert agent name to valid Python identifiers
+        class_name = ''.join(word.capitalize() for word in agent_name.replace('-', ' ').split())
+        package_name = agent_name.lower().replace(' ', '_').replace('-', '_')
+        module_name = package_name
+        docker_image = f"traia/{agent_id}:latest"
+        
+        # Prepare template context
+        context = {
+            "agent_name": agent_name,
+            "agent_id": agent_id,
+            "agent_description": agent_description,
+            "agent_version": agent_version,
+            "mcp_server_name": mcp_server_name,
+            "mcp_server_url": mcp_server_url,
+            "mcp_server_description": mcp_server_description,
+            "mcp_server_type": mcp_server_type,
+            "mcp_server_capabilities": mcp_server_capabilities,
+            "mcp_server_metadata": mcp_server_metadata,
+            "expose_individual_tools": expose_individual_tools,
+            "auth_required": auth_required,
+            "auth_schemes": auth_schemes or [],
+            "skill_examples": skill_examples,
+            "class_name": class_name,
+            "package_name": package_name,
+            "module_name": module_name,
+            "docker_image": docker_image,
+            "additional_dependencies": additional_dependencies,
+            "environment_variables": environment_variables,
+            "additional_ignores": additional_ignores,
+            "use_uv_lock": False,  # Will be true after first uv sync
+            **kwargs
+        }
+        
+        # Generate files
+        files_to_generate = []
+        
+        # Common files for both approaches
+        common_files = [
+            ("agent_config.json.j2", "agent_config.json"),
+            ("pyproject.toml.j2", "pyproject.toml"),
+            ("Dockerfile.j2", "Dockerfile"),
+            ("README.md.j2", "README.md"),
+            ("docker-compose.yml.j2", "docker-compose.yml"),
+            ("env.example.j2", ".env.example"),
+            ("gitignore.j2", ".gitignore"),
+            (".dockerignore.j2", ".dockerignore"),
+            ("run_local_docker.sh.j2", "run_local_docker.sh"),
+        ]
+        
+        if use_simple_server:
+            # Simple single-file approach
+            files_to_generate = [
+                ("server.py.j2", "server.py"),
+            ] + common_files
+        else:
+            # Modular approach with separate files
+            # Create package directory
+            pkg_dir = output_dir / package_name
+            pkg_dir.mkdir(exist_ok=True)
+            
+            files_to_generate = [
+                ("agent.py.j2", f"{package_name}/agent.py"),
+                ("agent_executor.py.j2", f"{package_name}/agent_executor.py"),
+                ("__main__.py.j2", f"{package_name}/__main__.py"),
+            ] + common_files
+            
+            # Create __init__.py
+            (output_dir / package_name / "__init__.py").write_text("")
+        
+        # Render and write templates
+        for template_name, output_name in files_to_generate:
+            try:
+                template = self.env.get_template(template_name)
+                content = template.render(context)
+                output_path = output_dir / output_name
+                output_path.parent.mkdir(parents=True, exist_ok=True)
+                output_path.write_text(content)
+                logger.info(f"Generated {output_path}")
+                
+                # Make run_local_docker.sh executable
+                if output_name == "run_local_docker.sh":
+                    output_path.chmod(0o755)
+                    logger.info(f"Made {output_path} executable")
+            except Exception as e:
+                logger.error(f"Error generating {output_name} from {template_name}: {e}")
+                raise
+        
+        # # Copy mcp_agent_template.py
+        # self._copy_mcp_agent_template(output_dir)
+        
+        logger.info(f"Successfully generated utility agent at {output_dir}")
+        return output_dir
+    
+    # def _copy_mcp_agent_template(self, output_dir: Path):
+    #     """Copy the mcp_agent_template.py file to the generated agent.
+        
+    #     Args:
+    #         output_dir: Output directory for the agent
+    #     """
+    #     # Find the mcp_agent_template.py file
+    #     mcp_template_path = Path(__file__).parent.parent / "mcp" / "mcp_agent_template.py"
+    #     agent_adapter_path = Path(__file__).parent.parent / "mcp" / "traia_mcp_adapter.py"
+        
+    #     if mcp_template_path.exists():
+    #         # Copy to output directory
+    #         dest_path_one = output_dir / "mcp_agent_template.py"
+    #         dest_path_two = output_dir / "traia_mcp_adapter.py"
+    #         shutil.copy2(mcp_template_path, dest_path_one)
+    #         shutil.copy2(agent_adapter_path, dest_path_two)
+    #         logger.info(f"Copied mcp_agent_template.py to {dest_path_one}")
+    #         logger.info(f"Copied traia_mcp_adapter.py to {dest_path_two}")
+    #     else:
+    #         logger.warning(f"Could not find mcp_agent_template.py at {mcp_template_path}")
+    #         logger.warning(f"Could not find traia_mcp_adapter.py at {agent_adapter_path}")
+    
+    def list_templates(self) -> List[str]:
+        """List available templates.
+        
+        Returns:
+            List of template file names
+        """
+        return [f.name for f in self.templates_dir.glob("*.j2")] 

traia_iatp/server/templates/Dockerfile.j2

@@ -0,0 +1,49 @@
+FROM python:3.12-slim
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+RUN chmod +x /usr/local/bin/uv
+
+# Create non-root user
+RUN useradd -m -u 1000 appuser
+
+# Create app directory and set ownership
+RUN mkdir -p /app && chown -R appuser:appuser /app
+
+# Set working directory
+WORKDIR /app
+
+# Switch to non-root user
+USER appuser
+
+# Copy project files
+COPY --chown=appuser:appuser . .
+
+# Install Python dependencies
+RUN uv venv .venv && \
+    uv pip install -r pyproject.toml
+
+# Set environment variables
+ENV PATH="/app/.venv/bin:$PATH"
+ENV PYTHONPATH=/app
+ENV HOST=0.0.0.0
+ENV PYTHONUNBUFFERED=1
+ENV UV_SYSTEM_PYTHON=1
+{% for env_var in environment_variables %}
+ENV {{ env_var.name }}="{{ env_var.value }}"
+{% endfor %}
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+    CMD curl -f http://localhost:${PORT:-8000}/.well-known/agent.json || exit 1
+
+# Expose port (uses PORT environment variable with default)
+EXPOSE ${PORT:-8000}
+
+# Run the application
+CMD ["uv", "run", "python", "-m", "{{ module_name }}"] 

traia_iatp/server/templates/README.md

@@ -0,0 +1,137 @@
+# A2A Utility Agency Templates
+
+This directory contains Jinja2 templates for generating utility agencies that wrap MCP servers and expose them via the A2A (Agent-to-Agent) protocol.
+
+## Overview
+
+These templates follow the pattern established by the [A2A CrewAI examples](https://github.com/google-a2a/a2a-samples/tree/main/samples/python/agents/crewai) to create standardized A2A servers that:
+
+1. **Wrap MCP Servers**: Connect to any MCP (Model Context Protocol) server
+2. **Use CrewAI**: Leverage CrewAI agents to process requests intelligently
+3. **Expose A2A Interface**: Provide a standard A2A protocol interface for agent-to-agent communication
+
+## Templates
+
+### Core Templates
+
+- **`agent.py.j2`** - CrewAI agent implementation that wraps the MCP server
+- **`agent_executor.py.j2`** - A2A executor that interfaces the CrewAI agent with A2A protocol
+- **`__main__.py.j2`** - Main entry point that initializes and starts the A2A server
+
+### Simple Server Template
+
+- **`server.py.j2`** - All-in-one simplified implementation combining agent, executor, and server
+
+### Configuration Templates
+
+- **`agency_config.json.j2`** - Agency configuration file
+- **`pyproject.toml.j2`** - Python project dependencies
+- **`Dockerfile.j2`** - Docker container configuration
+- **`README.md.j2`** - Documentation for the generated agency
+
+## Template Variables
+
+The templates expect the following variables:
+
+### Required Variables
+- `agency_name` - Human-readable name of the agency
+- `agency_id` - Unique identifier for the agency  
+- `mcp_server_name` - Name of the MCP server
+- `mcp_server_url` - URL or path to the MCP server
+- `mcp_server_description` - Description of the MCP server
+- `mcp_server_capabilities` - List of capabilities provided
+
+### Optional Variables
+- `agency_description` - Description of the agency (auto-generated if not provided)
+- `agency_version` - Version of the agency (default: "0.1.0")
+- `mcp_server_type` - Type of MCP server: "stdio", "http", etc. (default: "stdio")
+- `expose_individual_tools` - Whether to expose each MCP tool as a separate A2A skill
+- `auth_required` - Whether authentication is required
+- `auth_schemes` - List of auth schemes if auth is required
+- `skill_examples` - Example prompts for the main skill
+- `additional_dependencies` - Extra Python dependencies
+- `use_simple_server` - Whether to use the simplified server.py template
+
+### Auto-generated Variables
+- `class_name` - PascalCase class name derived from agency_name
+- `package_name` - Python package name (snake_case)
+- `module_name` - Python module name
+- `docker_image` - Docker image name
+
+## Usage
+
+Use the `UtilityAgencyTemplateGenerator` class to generate agencies:
+
+```python
+from iatp.server.template_generator import UtilityAgencyTemplateGenerator
+
+generator = UtilityAgencyTemplateGenerator()
+output_path = generator.generate_agency(
+    output_dir="path/to/output",
+    agency_name="My MCP Agency",
+    agency_id="my-mcp-agency",
+    mcp_server_name="my-mcp-server",
+    mcp_server_url="http://localhost:3000",
+    mcp_server_description="Description of the MCP server",
+    mcp_server_capabilities=["capability1", "capability2"],
+    use_simple_server=True  # For simpler deployments
+)
+```
+
+## Generated Structure
+
+### Simple Server (use_simple_server=True)
+```
+output_dir/
+├── server.py            # All-in-one A2A server
+├── agency_config.json   # Configuration
+├── pyproject.toml       # Dependencies
+├── Dockerfile           # Container config
+├── README.md           # Documentation
+├── docker-compose.yml   # Local development
+├── .gitignore          # Git ignore rules
+└── .env.example        # Environment variables example
+```
+
+### Modular Structure (use_simple_server=False)
+```
+output_dir/
+├── package_name/
+│   ├── __init__.py
+│   ├── agent.py         # CrewAI agent
+│   ├── agent_executor.py # A2A executor
+│   └── __main__.py      # Entry point
+├── agency_config.json
+├── pyproject.toml
+├── Dockerfile
+├── README.md
+├── docker-compose.yml
+├── .gitignore
+└── .env.example
+```
+
+## A2A Protocol Compliance
+
+The generated agencies follow the A2A protocol by:
+
+1. **Agent Card**: Exposing agent capabilities at `/.well-known/agent.json`
+2. **Task Processing**: Handling tasks via POST to `/tasks/send`
+3. **Text I/O**: Supporting text input and output by default
+4. **Request Context**: Processing request context and metadata
+5. **Error Handling**: Proper error responses in A2A format
+
+## Next Steps
+
+After generating an agency:
+
+1. **Test Locally**: Run with `uv run python -m package_name` or `python server.py`
+2. **Build Docker**: `docker build -t agency-name .`
+3. **Push to GitHub**: Use the push_agency_to_repo functionality
+4. **Deploy to Cloud**: Use cloudrun_deployer for Google Cloud Run
+5. **Register**: Add to MongoDB registry for discovery
+
+## References
+
+- [A2A Protocol Documentation](https://github.com/google-a2a/A2A)
+- [A2A CrewAI Examples](https://github.com/google-a2a/a2a-samples/tree/main/samples/python/agents/crewai)
+- [MCP Protocol](https://github.com/anthropics/model-context-protocol)