traia-iatp 0.1.29__py3-none-any.whl

traia_iatp/utils/general.py

@@ -0,0 +1,64 @@
+"""General utility functions for traia_iatp package."""
+
+import logging
+from datetime import datetime
+import pytz
+
+
+def get_logger() -> logging.Logger:
+    """Get a logger instance configured for the traia_iatp package.
+    
+    Returns:
+        logging.Logger: Configured logger instance
+    """
+    logger = logging.getLogger(__name__)
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter(
+            '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+    return logger
+
+
+def get_now_in_utc() -> datetime:
+    """Get the current datetime in UTC timezone.
+    
+    Returns:
+        datetime: Current UTC datetime
+    """
+    return datetime.now(tz=pytz.utc)
+
+
+def is_empty(obj) -> bool:
+    """Check if an object is empty.
+    
+    Args:
+        obj: Object to check
+        
+    Returns:
+        bool: True if object is None or has length 0
+    """
+    try:
+        if obj is None:
+            return True
+        if len(obj) == 0:
+            return True
+    except TypeError:
+        # Object doesn't have length (e.g., numbers, booleans)
+        return obj is None
+    return False
+
+
+def not_empty(obj) -> bool:
+    """Check if an object is not empty.
+    
+    Args:
+        obj: Object to check
+        
+    Returns:
+        bool: True if object is not None and has length > 0
+    """
+    return not is_empty(obj) 

traia_iatp/utils/iatp_utils.py

@@ -0,0 +1,126 @@
+"""IATP utility functions for agent card handling and endpoint creation."""
+
+import logging
+from typing import Dict, Any, Optional, List
+import httpx
+
+from ..core.models import AgentCard, AgentSkill, AgentCapabilities, IATPEndpoints
+
+logger = logging.getLogger(__name__)
+
+
+async def fetch_agent_card(service_url: str, timeout: int = 30) -> Optional[Dict[str, Any]]:
+    """Fetch the agent card from a deployed utility agent.
+    
+    Args:
+        service_url: Base URL of the deployed service
+        timeout: Timeout in seconds
+        
+    Returns:
+        Agent card data or None if fetch fails
+    """
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            # Try the standard .well-known location
+            response = await client.get(f"{service_url}/.well-known/agent.json")
+            if response.status_code == 200:
+                return response.json()
+            
+            # Try the /info endpoint as fallback
+            response = await client.get(f"{service_url}/info")
+            if response.status_code == 200:
+                return response.json()
+                
+    except Exception as e:
+        logger.error(f"Error fetching agent card from {service_url}: {e}")
+    
+    return None
+
+
+def parse_agent_card(agent_card_data: Dict[str, Any]) -> Optional[AgentCard]:
+    """Parse agent card data into an AgentCard model.
+    
+    Args:
+        agent_card_data: Raw agent card data
+        
+    Returns:
+        AgentCard instance or None if parsing fails
+    """
+    try:
+        # Parse skills
+        skills = []
+        for skill_data in agent_card_data.get("skills", []):
+            skill = AgentSkill(
+                id=skill_data.get("id", ""),
+                name=skill_data.get("name", ""),
+                description=skill_data.get("description", ""),
+                examples=skill_data.get("examples", []),
+                input_modes=skill_data.get("inputModes", []),
+                output_modes=skill_data.get("outputModes", []),
+                tags=skill_data.get("tags", [])
+            )
+            skills.append(skill)
+        
+        # Parse capabilities
+        cap_data = agent_card_data.get("capabilities", {})
+        capabilities = AgentCapabilities(
+            streaming=cap_data.get("streaming", False),
+            push_notifications=cap_data.get("pushNotifications", False),
+            state_transition_history=cap_data.get("stateTransitionHistory", False),
+            custom_features=cap_data.get("customFeatures", {})
+        )
+        
+        # Create agent card
+        agent_card = AgentCard(
+            name=agent_card_data.get("name", ""),
+            description=agent_card_data.get("description", ""),
+            version=agent_card_data.get("version", "1.0.0"),
+            skills=skills,
+            capabilities=capabilities,
+            default_input_modes=agent_card_data.get("defaultInputModes", []),
+            default_output_modes=agent_card_data.get("defaultOutputModes", []),
+            metadata=agent_card_data.get("metadata", {})
+        )
+        
+        return agent_card
+        
+    except Exception as e:
+        logger.error(f"Error parsing agent card: {e}")
+        return None
+
+
+def create_iatp_endpoints(base_url: str, supports_streaming: bool = False) -> IATPEndpoints:
+    """Create IATP endpoints configuration from base URL.
+    
+    The A2A protocol defines specific endpoints:
+    - JSON-RPC endpoint at root path (/)
+    - Agent card at /.well-known/agent.json
+    - SSE endpoints at /a2a/tasks/* (if streaming is supported)
+    
+    Note: The A2A library creates the main JSON-RPC endpoint at the root path (/),
+    not at /a2a as might be expected.
+    
+    Args:
+        base_url: Base URL of the service (e.g., "http://localhost:8000" or "https://service.run.app")
+        supports_streaming: Whether the service supports streaming
+        
+    Returns:
+        IATPEndpoints instance with all endpoint URLs configured
+    """
+    # Ensure base_url doesn't end with a slash
+    base_url = base_url.rstrip('/')
+    
+    endpoints = IATPEndpoints(
+        base_url=base_url,
+        iatp_endpoint=base_url,  # A2A JSON-RPC endpoint is at root path
+        health_endpoint=None,    # Not part of A2A protocol
+        info_endpoint=None,      # Not part of A2A protocol
+        agent_card_endpoint=f"{base_url}/.well-known/agent.json"
+    )
+    
+    if supports_streaming:
+        endpoints.streaming_endpoint = base_url  # Same root endpoint, different output_mode
+        endpoints.subscribe_endpoint = f"{base_url}/a2a/tasks/subscribe"
+        endpoints.resubscribe_endpoint = f"{base_url}/a2a/tasks/resubscribe"
+    
+    return endpoints 

traia_iatp-0.1.29.dist-info/METADATA

@@ -0,0 +1,423 @@
+Metadata-Version: 2.4
+Name: traia-iatp
+Version: 0.1.29
+Summary: Inter-Agent Transfer Protocol (IATP) - Enable AI Agents to utilize other AI Agents as tools
+Project-URL: Documentation, https://pypi.org/project/traia-iatp
+Project-URL: Source, https://github.com/Traia-IO/IATP
+Keywords: crewai,iatp,agent-to-agent,a2a,mcp,web3,cryptocurrency,tools
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: a2a-sdk==0.2.6
+Requires-Dist: aiohttp>=3.12.13
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: crewai>=0.203.1
+Requires-Dist: crewai-tools[mcp]>=0.76.0
+Requires-Dist: docker>=7.1.0
+Requires-Dist: fastapi>=0.119.0
+Requires-Dist: httpx[http2]>=0.28.1
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: mcp>=1.1.2
+Requires-Dist: openai>=1.109.1
+Requires-Dist: pydantic>=2.12.2
+Requires-Dist: pymongo[aws]>=4.13.0
+Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: pytz>=2025.2
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich>=14.2.0
+Requires-Dist: starlette>=0.45.0
+Requires-Dist: typer>=0.19.2
+Requires-Dist: uvicorn>=0.37.0
+Requires-Dist: agentops>=0.4.21
+Requires-Dist: dnspython==2.6.1
+Requires-Dist: eth-account>=0.11.0
+Requires-Dist: web3>=6.15.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4.2; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Provides-Extra: publish
+Requires-Dist: wheel; extra == "publish"
+Requires-Dist: twine; extra == "publish"
+Requires-Dist: build; extra == "publish"
+Dynamic: license-file
+
+# Traia IATP
+
+[![PyPI version](https://badge.fury.io/py/traia-iatp.svg)](https://badge.fury.io/py/traia-iatp)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Traia IATP** is an Inter-Agent Transfer Protocol (IATP) package that enables AI agents to utilize other AI agents as tools via the A2A (Agent-to-Agent) protocol. This implementation allows CrewAI agents to act as both IATP servers (utility agents) and clients.
+
+## Features
+
+- 🤖 **Utility Agent Creation**: Convert MCP servers into IATP-compatible utility agents
+- 🔌 **IATP Client Tools**: Enable CrewAI crews to use utility agents as tools via IATP protocol
+- 🌐 **Protocol Support**: HTTP/2 with SSE streaming and optional gRPC for high-performance scenarios
+- 📊 **Registry Management**: MongoDB-based registry for discovering utility agents
+- 🐳 **Docker Support**: Complete containerization for deployment
+- 🐳 **Local Docker Deployment**: Complete containerization for local deployment
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install traia-iatp
+```
+
+### From Source
+
+```bash
+git clone https://github.com/Traia-IO/IATP.git
+cd IATP
+pip install -e .
+```
+
+### Development Installation
+
+```bash
+# Install with all dependencies for development
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Creating a Utility Agency (IATP Server)
+
+```python
+import asyncio
+from traia_iatp import MCPServer, MCPServerType, IATPServerAgentGenerator
+
+async def create_utility_agency():
+    # Define an MCP server
+    mcp_server = MCPServer(
+        name="example-mcp-server",
+        url="http://example-mcp-server:8080",
+        server_type=MCPServerType.STREAMABLE_HTTP,
+        description="Example MCP server that provides utility functions"
+    )
+    
+    # Generate and deploy utility agency
+    generator = IATPServerAgentGenerator()
+    agency = await generator.create_from_mcp(mcp_server)
+    
+    # Deploy locally with Docker
+    await generator.deploy_local(agency)
+```
+
+### 2. Using Utility Agencies in CrewAI (IATP Client)
+
+```python
+from crewai import Agent, Task, Crew
+from traia_iatp import find_utility_agent
+from traia_iatp.client import A2AToolkit
+
+# Find available utility agents by agent_id
+agent = find_utility_agent(agent_id="finbert-mcp-traia-utility-agent")
+
+if agent:
+    # Get the IATP endpoint
+    endpoint = agent.base_url
+    if agent.endpoints and 'iatp_endpoint' in agent.endpoints:
+        endpoint = agent.endpoints['iatp_endpoint']
+    
+    # Create tool from agent endpoint
+    finbert_tool = A2AToolkit.create_tool_from_endpoint(
+        endpoint=endpoint,
+        name=agent.name,
+        description=agent.description,
+        timeout=300,
+        retry_attempts=1,
+        supports_streaming=False,
+        iatp_endpoint=endpoint
+    )
+    
+    # Use in CrewAI agent
+    sentiment_analyst = Agent(
+        role="Financial Sentiment Analyst",
+        goal="Analyze sentiment of financial texts using FinBERT models",
+        backstory="Expert financial sentiment analyst with deep knowledge of market psychology",
+        tools=[finbert_tool],
+        verbose=True,
+        allow_delegation=False
+    )
+    
+    # Create task
+    task = Task(
+        description="Analyze the sentiment of: 'Apple Inc. reported record quarterly earnings'",
+        expected_output="Sentiment classification with confidence score and investment implications",
+        agent=sentiment_analyst
+    )
+    
+    # Run crew
+    crew = Crew(agents=[sentiment_analyst], tasks=[task])
+    result = crew.kickoff()
+```
+
+#### Alternative: Batch Tool Creation
+
+For creating multiple tools at once, you can use the convenience function:
+
+```python
+from traia_iatp.client import create_utility_agency_tools
+
+# Search and create tools in batch
+tools = create_utility_agency_tools(
+    query="sentiment analysis",
+    tags=["finbert", "nlp"],
+    capabilities=["sentiment_analysis"]
+)
+
+# Use all found tools in an agent
+agent = Agent(
+    role="Multi-Tool Analyst",
+    tools=tools,
+    goal="Analyze using multiple available utility agents"
+)
+```
+
+### 3. CLI Usage
+
+The package includes a powerful CLI for managing utility agencies:
+
+```bash
+# First, register an MCP server in the registry
+traia-iatp register-mcp \
+    --name "Trading MCP" \
+    --url "http://localhost:8000/mcp" \
+    --description "Trading MCP server" \
+    --capability "trading" \
+    --capability "crypto"
+
+# Create a utility agency from registered MCP server
+traia-iatp create-agency \
+    --name "My Trading Agent" \
+    --description "Advanced trading utility agent" \
+    --mcp-name "Trading MCP" \
+    --deploy
+
+# List available utility agencies
+traia-iatp list-agencies
+
+# Search for agencies by capability
+traia-iatp search-agencies --query "trading crypto"
+
+# Deploy from a generated agency directory
+traia-iatp deploy ./utility_agencies/my-trading-agent --port 8001
+
+# Find available tools for CrewAI
+traia-iatp find-tools --tag "trading" --capability "crypto"
+
+# List registered MCP servers
+traia-iatp list-mcp-servers
+
+# Show example CrewAI integration code
+traia-iatp example-crew
+```
+
+## Architecture
+
+### IATP Operation Modes
+
+The IATP protocol supports two distinct operation modes:
+
+#### 1. Synchronous JSON-RPC Mode
+For simple request-response patterns:
+- Client sends: `message/send` request via JSON-RPC
+- Server processes the request using CrewAI agents  
+- Server returns: A single `Message` result
+
+#### 2. Streaming SSE Mode
+For real-time data and long-running operations:
+- Client sends: `message/send` request via JSON-RPC
+- Server returns: Stream of events via Server-Sent Events (SSE)
+- Supports progress updates, partial results, and completion notifications
+
+### Component Overview
+
+```
+┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
+│   CrewAI Agent      │───▶│   IATP Client       │───▶│   Utility Agency    │
+│   (A2A Client)      │    │   (HTTP/2 + gRPC)   │    │   (A2A Server)      │
+└─────────────────────┘    └─────────────────────┘    └─────────────────────┘
+                                                                │
+                                                                ▼
+                                                       ┌─────────────────────┐
+                                                       │   MCP Server        │
+                                                       │   (Tools Provider)  │
+                                                       └─────────────────────┘
+```
+
+## Key Components
+
+### Server Components (`traia_iatp.server`)
+- **Template Generation**: Jinja2 templates for creating utility agents
+- **HTTP/2 + SSE Support**: Modern protocol support with streaming
+- **gRPC Integration**: Optional high-performance protocol support
+- **Docker Containerization**: Complete deployment packaging
+
+### Client Components (`traia_iatp.client`)
+- **CrewAI Integration**: Native tools for CrewAI agents
+- **HTTP/2 Client**: Persistent connections with multiplexing
+- **SSE Streaming**: Real-time data consumption
+- **Connection Management**: Pooling and retry logic
+
+### Registry Components (`traia_iatp.registry`)
+- **MongoDB Integration**: Persistent storage and search
+- **Vector Search**: Embedding-based capability discovery
+- **Atlas Search**: Full-text search capabilities
+- **Agent Discovery**: Find agents by capability, tags, or description
+
+## Environment Variables
+
+```bash
+# MongoDB Configuration (choose one method)
+MONGODB_CONNECTION_STRING="mongodb+srv://..."
+# OR
+MONGODB_USER="username"
+MONGODB_PASSWORD="password"
+# OR X.509 Certificate
+MONGODB_X509_CERT_FILE="/path/to/cert.pem"
+
+# Optional: Custom MongoDB cluster
+MONGODB_CLUSTER_URI="custom-cluster.mongodb.net"
+MONGODB_DATABASE_NAME="custom_db"
+
+# OpenAI for embeddings (optional)
+OPENAI_API_KEY="your-openai-key"
+
+# MCP Server Authentication (as needed)
+MCP_API_KEY="your-mcp-api-key"
+```
+
+## Examples
+
+### Advanced IATP Integration
+
+```python
+from traia_iatp import find_utility_agent
+from traia_iatp.client import A2AToolkit
+
+# Find multiple utility agents
+trading_agent = find_utility_agent(agent_id="trading-mcp-agent")
+sentiment_agent = find_utility_agent(agent_id="finbert-mcp-agent") 
+
+tools = []
+for agent in [trading_agent, sentiment_agent]:
+    if agent:
+        # Get endpoint and create tool
+        endpoint = agent.endpoints.get('iatp_endpoint', agent.base_url)
+        tool = A2AToolkit.create_tool_from_endpoint(
+            endpoint=endpoint,
+            name=agent.name,
+            description=agent.description,
+            iatp_endpoint=endpoint
+        )
+        tools.append(tool)
+
+# Use multiple IATP tools in one agent
+multi_tool_agent = Agent(
+    role="Multi-Domain Analyst", 
+    goal="Analyze markets using multiple specialized AI agents",
+    tools=tools,
+    backstory="Expert analyst with access to specialized AI agents for trading and sentiment analysis"
+)
+```
+
+### Local Docker Deployment
+
+```python
+from traia_iatp.utils.docker_utils import LocalDockerRunner
+from pathlib import Path
+
+# Deploy a generated agency locally (not yet configured properly)
+runner = LocalDockerRunner()
+deployment_info = await runner.run_agent_docker(
+    agent_path=Path("./utility_agencies/my-trading-agent"),
+    port=8000,
+    detached=True
+)
+
+if deployment_info["success"]:
+    print(f"Agency deployed at: {deployment_info['iatp_endpoint']}")
+    print(f"Container: {deployment_info['container_name']}")
+    print(f"Stop with: {deployment_info['stop_command']}")
+```
+
+## Development
+
+### Setting Up Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/Traia-IO/IATP.git
+cd IATP
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in development mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run linting
+black .
+flake8 .
+mypy .
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test file
+pytest tests/test_client.py
+
+# Run with coverage
+pytest --cov=traia_iatp --cov-report=html
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+This is a private code base hence only members of Dcentralab can contribute
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- 📖 **Documentation**: [https://pypi.org/project/traia-iatp](https://pypi.org/project/traia-iatp)
+- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/Traia-IO/IATP/issues)
+- 💬 **Community**: [Visit our website](https://traia.io)
+- 📧 **Email**: support@traia.io
+
+## Related Projects
+
+- [A2A Protocol](https://github.com/google-a2a/A2A) - Agent-to-Agent communication protocol
+- [CrewAI](https://github.com/joaomdmoura/crewAI) - Framework for orchestrating role-playing AI agents
+- [FastMCP](https://github.com/modelcontextprotocol/fastmcp) - Fast implementation of Model Context Protocol
+
+---
+
+**Made with ❤️ by the Traia Team**