traia-iatp 0.1.1__py3-none-any.whl

traia_iatp/registry/readmes/REFACTORING_SUMMARY.md

@@ -0,0 +1,191 @@
+# Registry and Search API Refactoring Summary
+
+## Overview
+
+This refactoring separates the concerns between registry management (write operations) and search/query operations (read operations) to eliminate duplication and improve maintainability.
+
+## Changes Made
+
+### 1. `mongodb_registry.py` - Write Operations Only
+
+**Removed Methods:**
+- `query_agents()` - Moved to search API
+- `atlas_search()` - Moved to search API  
+- `vector_search()` - Moved to search API
+- `vector_search_text()` - Moved to search API
+- `query_mcp_servers()` - Moved to search API
+- `atlas_search()` (MCP) - Moved to search API
+- `vector_search()` (MCP) - Moved to search API
+- `vector_search_text()` (MCP) - Moved to search API
+
+**Kept Methods:**
+- `add_utility_agent()` - Registry management
+- `update_health_status()` - Registry management
+- `update_agent_base_url()` - Registry management
+- `add_tags()` - Registry management
+- `remove_agent()` - Registry management
+- `update_utility_agent()` - Registry management
+- `get_statistics()` - Registry statistics (read but specific to registry)
+- `add_mcp_server()` - Registry management
+- `get_mcp_server()` - Simple lookup (kept for backward compatibility)
+
+**Updated Documentation:**
+- Updated module docstring to clarify write-only purpose
+- Updated class docstrings to indicate write operations only
+- Added references to `iatp_search_api.py` for search operations
+
+### 2. `iatp_search_api.py` - Search and Query Operations
+
+**Existing Methods (Unchanged):**
+- `find_utility_agent()` - Search by name, capability, tag, or query
+- `list_utility_agents()` - List agents with filters
+- `search_utility_agents()` - Vector search for agents
+- `find_mcp_server()` - Search MCP servers
+- `list_mcp_servers()` - List MCP servers
+- `search_mcp_servers()` - Vector search for MCP servers
+- `get_mcp_server()` - Get MCP server by name
+
+**Features:**
+- Atlas Search integration
+- Vector search with embeddings
+- Fallback to Atlas Search when vector search fails
+- Read-only operations (no MongoDB write access needed)
+- Cached connections for better performance
+
+### 3. Updated Test Files
+
+**`test_discovery_and_usage.py`:**
+- Updated imports to use `iatp_search_api` instead of `mongodb_registry`
+- Modified `discover_hyperliquid_agent()` to use `search_utility_agents()`
+- Updated `create_tools_from_discovered_agent()` to work with `UtilityAgentInfo` structure
+- Removed registry connection management
+
+**`test_refactoring.py`:**
+- New test script to verify refactoring works correctly
+- Tests registry write operations
+- Tests search API operations
+- Tests discovery test imports
+
+## Benefits
+
+### 1. Clear Separation of Concerns
+- **Registry**: Handles data persistence and lifecycle management
+- **Search API**: Handles discovery and querying
+
+### 2. Reduced Duplication
+- Eliminated duplicate search methods between files
+- Single source of truth for search logic
+
+### 3. Better Performance
+- Search API uses read-only connections
+- Cached connections for repeated queries
+- Optimized for search operations
+
+### 4. Improved Maintainability
+- Easier to modify search logic in one place
+- Clearer responsibilities for each module
+- Better testability
+
+### 5. Enhanced Security
+- Search API can use read-only credentials
+- Registry operations require write permissions
+- Reduced attack surface
+
+## Usage Examples
+
+### Registry Operations (Write)
+```python
+from iatp.registry.mongodb_registry import UtilityAgentRegistry
+
+# Add new agent
+registry = UtilityAgentRegistry()
+await registry.add_utility_agent(agent, tags=["trading", "hyperliquid"])
+
+# Update agent
+await registry.update_health_status(agent_id, is_healthy=True)
+await registry.update_agent_base_url(agent_id, new_url)
+```
+
+### Search Operations (Read)
+```python
+from iatp.registry.iatp_search_api import search_utility_agents, find_utility_agent
+
+# Search for agents
+agents = await search_utility_agents("hyperliquid trading", limit=5)
+
+# Find specific agent
+agent = find_utility_agent(capability="market_data")
+```
+
+### Discovery Test
+```python
+# The discovery test now uses the search API
+from iatp.registry.iatp_search_api import search_utility_agents
+
+# Search for Hyperliquid agent
+search_results = await search_utility_agents(
+    query="hyperliquid trading",
+    limit=5,
+    active_only=True
+)
+```
+
+## Migration Guide
+
+### For Existing Code
+
+1. **If using registry for search/query:**
+   ```python
+   # OLD
+   from iatp.registry.mongodb_registry import UtilityAgentRegistry
+   registry = UtilityAgentRegistry()
+   agents = await registry.query_agents(query="trading")
+   
+   # NEW
+   from iatp.registry.iatp_search_api import search_utility_agents
+   agents = await search_utility_agents("trading")
+   ```
+
+2. **If using registry for write operations:**
+   ```python
+   # No changes needed - these methods are still available
+   from iatp.registry.mongodb_registry import UtilityAgentRegistry
+   registry = UtilityAgentRegistry()
+   await registry.add_utility_agent(agent)
+   ```
+
+### Environment Variables
+
+No changes to environment variables are required. Both modules use the same authentication methods:
+- `MONGODB_CONNECTION_STRING`
+- `MONGODB_USER` + `MONGODB_PASSWORD`
+- `MONGODB_X509_CERT_FILE`
+
+## Testing
+
+Run the refactoring test to verify everything works:
+
+```bash
+cd traia-centralized-backend
+python test_refactoring.py
+```
+
+This will test:
+- Registry write operations
+- Search API operations
+- Discovery test imports
+
+## Future Improvements
+
+1. **Connection Pooling**: Implement connection pooling for better performance
+2. **Caching**: Add Redis caching for frequently accessed data
+3. **Rate Limiting**: Add rate limiting for search operations
+4. **Metrics**: Add metrics collection for search performance
+5. **API Versioning**: Consider API versioning for future changes
+
+## Backward Compatibility
+
+- All existing registry write operations remain unchanged
+- Search operations now use the dedicated search API
+- No breaking changes to existing functionality
+- Clear migration path provided 

traia_iatp/server/__init__.py

@@ -0,0 +1,15 @@
+"""IATP server module for creating A2A servers from utility agents."""
+
+from .a2a_server import (
+    UtilityAgencyExecutor,
+    create_a2a_server,
+    create_and_start_a2a_server
+)
+from .iatp_server_agent_generator import IATPServerAgentGenerator
+
+__all__ = [
+    "UtilityAgencyExecutor", 
+    "IATPServerAgentGenerator",
+    "create_a2a_server",
+    "create_and_start_a2a_server",
+]

traia_iatp/server/a2a_server.py

@@ -0,0 +1,215 @@
+"""A2A server implementation for utility agencies using the official a2a-sdk."""
+
+import asyncio
+import logging
+from typing import Dict, Any, Optional, List
+from a2a.server.apps import A2AStarletteApplication
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events.event_queue import EventQueue
+from a2a.server.tasks import InMemoryTaskStore
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.types import AgentCard, AgentSkill, AgentCapabilities
+from a2a.utils import new_agent_text_message, new_text_artifact
+from dataclasses import dataclass
+import uvicorn
+
+from ..core.models import UtilityAgent
+from .iatp_server_agent_generator import IATPServerAgentGenerator
+
+logger = logging.getLogger(__name__)
+
+
+class UtilityAgencyExecutor(AgentExecutor):
+    """Agent executor that wraps a utility agency and executes tasks via CrewAI."""
+    
+    def __init__(self, agency: UtilityAgent, agency_generator: IATPServerAgentGenerator):
+        self.agency = agency
+        self.agency_generator = agency_generator
+        self._crew = None
+    
+    async def _get_crew(self):
+        """Lazily build the crew from agency config."""
+        if self._crew is None:
+            self._crew = await self.agency_generator.build_crew_from_agency(self.agency)
+        return self._crew
+    
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        """Execute a task using the utility agency crew."""
+        try:
+            # Get the user's request from context
+            user_message = context.get_last_user_message()
+            if not user_message:
+                event_queue.enqueue_event(
+                    new_agent_text_message("No user message provided")
+                )
+                return
+            
+            # Extract text from message parts
+            user_text = ""
+            for part in user_message.parts:
+                if hasattr(part, 'text'):
+                    user_text += part.text
+            
+            if not user_text:
+                event_queue.enqueue_event(
+                    new_agent_text_message("No text content in user message")
+                )
+                return
+            
+            # Build crew and execute
+            crew = await self._get_crew()
+            
+            # Run the crew with the request
+            result = crew.kickoff(inputs={"request": user_text})
+            
+            # Send the result as agent message
+            event_queue.enqueue_event(
+                new_agent_text_message(str(result))
+            )
+            
+        except Exception as e:
+            logger.error(f"Error executing task: {e}")
+            event_queue.enqueue_event(
+                new_agent_text_message(f"Error processing request: {str(e)}")
+            )
+
+
+class MCPToolExecutor(AgentExecutor):
+    """Agent executor for individual MCP tool execution."""
+    
+    def __init__(self, agency: UtilityAgent, tool_name: str):
+        self.agency = agency
+        self.tool_name = tool_name
+    
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        """Execute a specific MCP tool."""
+        try:
+            from ..mcp.client import MCPClient
+            
+            # Get tool arguments from context
+            user_message = context.get_last_user_message()
+            if not user_message:
+                event_queue.enqueue_event(
+                    new_agent_text_message("No arguments provided")
+                )
+                return
+            
+            # Extract arguments (assuming they're passed as JSON in text)
+            import json
+            arguments = {}
+            for part in user_message.parts:
+                if hasattr(part, 'text'):
+                    try:
+                        arguments = json.loads(part.text)
+                    except:
+                        arguments = {"query": part.text}  # Fallback to simple text
+            
+            # Connect to MCP server and execute tool
+            mcp_client = MCPClient(self.agency.mcp_server)
+            await mcp_client.connect()
+            
+            try:
+                result = await mcp_client.call_tool(self.tool_name, arguments)
+                event_queue.enqueue_event(
+                    new_agent_text_message(str(result))
+                )
+            finally:
+                await mcp_client.disconnect()
+                
+        except Exception as e:
+            logger.error(f"Error executing MCP tool {self.tool_name}: {e}")
+            event_queue.enqueue_event(
+                new_agent_text_message(f"Error executing tool: {str(e)}")
+            )
+
+
+def create_a2a_server(
+    agency: UtilityAgent,
+    agency_generator: IATPServerAgentGenerator,
+    host: str = "0.0.0.0",
+    port: int = 8000
+) -> A2AStarletteApplication:
+    """Create an A2A server for a utility agency."""
+    
+    # Create skills from agency capabilities
+    skills = []
+    
+    # Add main processing skill
+    main_skill = AgentSkill(
+        id="process_request",
+        name=f"Process request using {agency.name}",
+        description=f"Process a request using {agency.name} capabilities. {agency.description}",
+        examples=[
+            f"Help me with {cap}" for cap in agency.mcp_server.capabilities[:2]
+        ] if agency.mcp_server.capabilities else ["Process this request for me"]
+    )
+    skills.append(main_skill)
+    
+    # Add individual MCP tool skills
+    for capability in agency.mcp_server.capabilities:
+        skill = AgentSkill(
+            id=f"mcp_{capability}",
+            name=f"Execute {capability}",
+            description=f"Execute {capability} tool on MCP server",
+            examples=[f"Run {capability} with these parameters"]
+        )
+        skills.append(skill)
+    
+    # Create capabilities
+    capabilities = AgentCapabilities(
+        streaming=False,  # Not implementing streaming for now
+        pushNotifications=False,  # Not implementing push notifications
+        stateTransitionHistory=False
+    )
+    
+    # Create agent card
+    agent_card = AgentCard(
+        name=agency.name.replace(" ", "_").lower(),
+        description=agency.description,
+        url=f"http://{host}:{port}",
+        version="1.0.0",
+        capabilities=capabilities,
+        skills=skills,
+        # TODO: Add authentication when AgentAuthentication is available
+        # authentication=AgentAuthentication(schemes=["Bearer"]) if agency.auth_type else None
+    )
+    
+    # Create executor mapping
+    executors = {
+        "process_request": UtilityAgencyExecutor(agency, agency_generator)
+    }
+    
+    # Add MCP tool executors
+    for capability in agency.mcp_server.capabilities:
+        executors[f"mcp_{capability}"] = MCPToolExecutor(agency, capability)
+    
+    # Create task store and request handler
+    task_store = InMemoryTaskStore()
+    request_handler = DefaultRequestHandler(
+        agent_card=agent_card,
+        executors=executors,
+        task_store=task_store
+    )
+    
+    # Create the A2A application
+    app = A2AStarletteApplication(
+        agent_card=agent_card,
+        request_handler=request_handler
+    )
+    
+    return app
+
+
+async def create_and_start_a2a_server(
+    agency: UtilityAgent,
+    agency_generator: IATPServerAgentGenerator,
+    host: str = "0.0.0.0",
+    port: int = 8000
+):
+    """Create and start an A2A server for a utility agency."""
+    app = create_a2a_server(agency, agency_generator, host, port)
+    
+    logger.info(f"Starting A2A server for {agency.name} on {host}:{port}")
+    config = uvicorn.Config(app, host=host, port=port, log_level="info")
+    server = uvicorn.Server(config)
+    await server.serve() 

traia_iatp/server/example_template_usage.py

@@ -0,0 +1,72 @@
+"""Example usage of the utility agent template generator.
+
+This script demonstrates how to generate a utility agent from an MCP server.
+"""
+
+from pathlib import Path
+from ..core.models import MCPServer, MCPServerType
+from .iatp_server_agent_generator import IATPServerAgentGenerator
+
+
+def main():
+    """Example of generating a utility agent."""
+    
+    # Create an MCP server specification
+    mcp_server = MCPServer(
+        id="hyperliquid-mcp-001",
+        name="hyperliquid-mcp",
+        url="http://localhost:3000/mcp",
+        server_type=MCPServerType.STREAMABLE_HTTP,
+        description="Implements comprehensive trading tools for Hyperliquid L1",
+        capabilities=[
+            "market_data",
+            "place_order",
+            "cancel_order",
+            "get_positions",
+            "get_account_info"
+        ],
+        metadata={
+            "version": "1.0.0",
+            "author": "Traia"
+        }
+    )
+    
+    # Create the generator
+    generator = IATPServerAgentGenerator(
+        output_base_dir=Path("generated_agents")
+    )
+    
+    # Generate the utility agent
+    agent = generator.generate_agent(
+        mcp_server=mcp_server,
+        agent_name="Hyperliquid Trading",
+        agent_id="hyperliquid-mcp-traia-utility-agent",
+        agent_description="A utility agent that exposes Hyperliquid trading capabilities via A2A protocol",
+        expose_individual_tools=False,  # Just expose one main skill
+        auth_required=False,
+        use_simple_server=True,  # Use the simplified server template
+        skill_examples=[
+            "Get current market data for ETH-USD",
+            "Place a limit order to buy 1 ETH at $3000",
+            "Show my current positions",
+            "Cancel order with ID 12345",
+            "Get my account balance and margin"
+        ]
+    )
+    
+    print(f"Generated utility agent: {agent.name}")
+    print(f"ID: {agent.id}")
+    print(f"Status: {agent.status}")
+    print(f"Code path: {agent.code_path}")
+    print(f"Capabilities: {agent.capabilities}")
+    
+    # The generated agent can now be:
+    # 1. Pushed to GitHub using push_agency_to_repo
+    # 2. Deployed to Cloud Run using cloudrun_deployer
+    # 3. Registered in MongoDB for discovery
+    
+    return agent
+
+
+if __name__ == "__main__":
+    main()