traia-iatp 0.1.29__py3-none-any.whl

traia_iatp/core/models.py

@@ -0,0 +1,172 @@
+"""Core data models for IATP."""
+
+from datetime import datetime
+from typing import Optional, Dict, Any, List
+from pydantic import BaseModel, Field, HttpUrl
+from enum import Enum
+
+
+class MCPServerType(str, Enum):
+    """Types of MCP servers."""
+    STREAMABLE_HTTP = "streamable-http"
+
+
+class MCPServer(BaseModel):
+    """MCP Server specification."""
+    id: Optional[str] = Field(default=None, description="Unique identifier")
+    name: str = Field(..., description="Name of the MCP server")
+    url: str = Field(..., description="URL or path to connect to the MCP server")
+    server_type: MCPServerType = Field(default=MCPServerType.STREAMABLE_HTTP, description="Type of MCP server connection")
+    description: str = Field(..., description="Description of what the server enables")
+    capabilities: List[str] = Field(default_factory=list, description="List of capabilities/APIs")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+    
+    class ConfigDict:
+        json_encoders = {HttpUrl: str}
+
+
+class AgentSkill(BaseModel):
+    """IATP Agent skill definition."""
+    id: str = Field(..., description="Unique skill identifier")
+    name: str = Field(..., description="Human-readable skill name")
+    description: str = Field(..., description="Detailed skill description")
+    examples: List[str] = Field(default_factory=list, description="Example usage patterns")
+    input_modes: List[str] = Field(default_factory=list, description="Supported input modes")
+    output_modes: List[str] = Field(default_factory=list, description="Supported output modes")
+    tags: List[str] = Field(default_factory=list, description="Tags for categorization")
+
+
+class AgentCapabilities(BaseModel):
+    """IATP Agent capabilities."""
+    streaming: bool = Field(default=False, description="Supports SSE streaming")
+    push_notifications: bool = Field(default=False, description="Supports push notifications")
+    state_transition_history: bool = Field(default=False, description="Maintains state history")
+    custom_features: Dict[str, Any] = Field(default_factory=dict, description="Custom capabilities")
+
+
+class AgentCard(BaseModel):
+    """IATP Agent card for discovery and initialization."""
+    name: str = Field(..., description="Agent name")
+    description: str = Field(..., description="Agent description")
+    version: str = Field(..., description="Agent version")
+    skills: List[AgentSkill] = Field(default_factory=list, description="Available skills")
+    capabilities: AgentCapabilities = Field(default_factory=AgentCapabilities, description="Agent capabilities")
+    default_input_modes: List[str] = Field(default_factory=list, description="Default input modes")
+    default_output_modes: List[str] = Field(default_factory=list, description="Default output modes")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+
+class IATPEndpoints(BaseModel):
+    """IATP server endpoints configuration.
+    
+    Note: The A2A protocol only defines a minimal set of endpoints:
+    - Root path (/) for JSON-RPC
+    - /.well-known/agent.json for agent card
+    - /a2a/tasks/* for SSE subscriptions (if streaming is supported)
+    
+    Health and info endpoints are NOT part of the A2A protocol standard.
+    """
+    base_url: str = Field(..., description="Base URL of the IATP server")
+    iatp_endpoint: str = Field(..., description="Main IATP JSON-RPC endpoint (usually at root path)")
+    streaming_endpoint: Optional[str] = Field(None, description="SSE streaming endpoint (same as iatp_endpoint when supported)")
+    health_endpoint: Optional[str] = Field(None, description="Health check endpoint (not part of A2A protocol)")
+    info_endpoint: Optional[str] = Field(None, description="Agent info endpoint (not part of A2A protocol)")
+    agent_card_endpoint: str = Field(..., description="Agent card endpoint (.well-known/agent.json)")
+    subscribe_endpoint: Optional[str] = Field(None, description="SSE subscription endpoint (/a2a/tasks/subscribe)")
+    resubscribe_endpoint: Optional[str] = Field(None, description="SSE resubscription endpoint (/a2a/tasks/resubscribe)")
+
+
+class UtilityAgentStatus(str, Enum):
+    """Status of a utility agent."""
+    GENERATED = "generated"
+    DEPLOYING = "deploying"
+    DEPLOYED = "deployed"
+    RUNNING = "running"
+    STOPPED = "stopped"
+    ERROR = "error"
+
+
+#this is the model for internal management of utility agents by their creator and traia protocol (should be persisted into db)
+class UtilityAgent(BaseModel):
+    """Utility Agent configuration and metadata."""
+    id: str = Field(..., description="Unique identifier for the agent")
+    name: str = Field(..., description="Name of the utility agent")
+    description: str = Field(..., description="Description of the agent's purpose")
+    mcp_server_id: str = Field(..., description="ID of the associated MCP server")
+    
+    # IATP specific fields
+    agent_card: Optional[AgentCard] = Field(None, description="IATP agent card for discovery")
+    endpoints: Optional[IATPEndpoints] = Field(None, description="IATP endpoints configuration")
+    
+    capabilities: List[str] = Field(default_factory=list, description="List of exposed capabilities")
+    status: UtilityAgentStatus = Field(default=UtilityAgentStatus.GENERATED)
+    code_path: Optional[str] = Field(None, description="Path to generated code")
+    docker_image: Optional[str] = Field(None, description="Docker image name when built")
+    github_repo: Optional[str] = Field(None, description="GitHub repository URL")
+    cloud_run_url: Optional[str] = Field(None, description="Cloud Run deployment URL")
+    
+    # X402 payment configuration
+    contract_address: Optional[str] = Field(None, description="On-chain utility agent contract address")
+    operator_address: Optional[str] = Field(None, description="Operator address for signing attestations")
+    d402_enabled: bool = Field(default=False, description="Whether d402 payments are enabled")
+    d402_config: Optional[Dict[str, Any]] = Field(None, description="X402 payment configuration")
+    
+    # Search and discovery
+    search_text: Optional[str] = Field(None, description="Concatenated searchable text")
+    tags: List[str] = Field(default_factory=list, description="Tags for search and categorization")
+    
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+    
+    class ConfigDict:
+        json_encoders = {HttpUrl: str, datetime: lambda v: v.isoformat()}
+
+
+#this is a model for registry discovery that will be used by the mongodb indexes
+class UtilityAgentRegistryEntry(BaseModel):
+    """Registry entry for a deployed utility agent."""
+    agent_id: str = Field(..., description="ID of the utility agent")
+    name: str = Field(..., description="Name for discovery")
+    description: str = Field(..., description="Description for search")
+    
+    # Base URL for the agent - all endpoints are derived from this
+    base_url: Optional[str] = Field(None, description="Base URL of the deployed agent")
+    
+    # Enhanced IATP discovery fields
+    agent_card: Optional[AgentCard] = Field(None, description="IATP agent card")
+    endpoints: Optional[IATPEndpoints] = Field(None, description="IATP endpoints")
+    
+    capabilities: List[str] = Field(..., description="List of capabilities")
+    skills: List[AgentSkill] = Field(default_factory=list, description="Detailed skills from agent card")
+    tags: List[str] = Field(default_factory=list, description="Tags for search")
+    
+    # X402 payment information
+    contract_address: Optional[str] = Field(None, description="On-chain utility agent contract address")
+    d402_enabled: bool = Field(default=False, description="Whether d402 payments are enabled")
+    d402_payment_info: Optional[Dict[str, Any]] = Field(None, description="X402 payment information")
+    
+    # Search optimization
+    search_text: Optional[str] = Field(None, description="Full text for search")
+    
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+    registered_at: datetime = Field(default_factory=datetime.utcnow)
+    last_health_check: Optional[datetime] = Field(None, description="Last successful health check")
+    is_active: bool = Field(default=True, description="Whether the agent is active")
+    
+    class ConfigDict:
+        json_encoders = {HttpUrl: str, datetime: lambda v: v.isoformat()}
+
+
+class IATPRequest(BaseModel):
+    """IATP protocol request."""
+    action: str = Field(..., description="Action to perform")
+    parameters: Dict[str, Any] = Field(default_factory=dict, description="Action parameters")
+    context: Dict[str, Any] = Field(default_factory=dict, description="Request context")
+
+
+class IATPResponse(BaseModel):
+    """IATP protocol response."""
+    result: Any = Field(..., description="Result of the action")
+    status: str = Field(..., description="Status of the response")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Response metadata") 

traia_iatp/d402/__init__.py

@@ -0,0 +1,55 @@
+"""D402 payment integration for IATP protocol.
+
+This module provides d402 (HTTP 402 Payment Required) payment capabilities
+for the Inter-Agent Transfer Protocol (IATP). It enables utility agents to
+accept payments and client agents to send payments for API access.
+
+Components:
+- middleware: FastAPI middleware for accepting d402 payments
+- client: d402 client integration for sending payments
+- facilitator: Custom facilitator that interfaces with IATPSettlementLayer
+- models: Payment configuration models
+"""
+
+from .models import (
+    D402Config,
+    D402PaymentInfo,
+    D402ServicePrice,
+    PaymentScheme,
+)
+from .middleware import D402IATPMiddleware, require_iatp_payment
+from .client import D402IATPClient
+from .facilitator import IATPSettlementFacilitator
+from .fastmcp_middleware import (
+    D402MCPMiddleware,
+    create_d402_mcp_middleware,
+)
+from .mcp_middleware import (
+    EndpointPaymentInfo,
+    get_active_api_key,
+    require_payment_for_tool,
+    settle_payment
+)
+from .clients.httpx import d402_payment_hooks, d402HttpxClient
+from .clients.base import decode_x_payment_response
+
+__all__ = [
+    "D402Config",
+    "D402PaymentInfo",
+    "D402ServicePrice",
+    "PaymentScheme",
+    "D402IATPMiddleware",
+    "require_iatp_payment",
+    "D402IATPClient",
+    "IATPSettlementFacilitator",
+    "D402MCPMiddleware",
+    "create_d402_mcp_middleware",
+    "EndpointPaymentInfo",
+    "get_active_api_key",
+    "require_payment_for_tool",
+    "settle_payment",
+    "d402_payment_hooks",
+    "d402HttpxClient",
+    "decode_x_payment_response",
+]
+

traia_iatp/d402/chains.py

@@ -0,0 +1,102 @@
+NETWORK_TO_ID = {
+    "sepolia": "11155111",  # Ethereum Sepolia testnet
+    "base-sepolia": "84532",
+    "base": "8453",
+    "avalanche-fuji": "43113",
+    "avalanche": "43114",
+}
+
+
+def get_chain_id(network: str) -> str:
+    """Get the chain ID for a given network
+    Supports string encoded chain IDs and human readable networks
+    """
+    try:
+        int(network)
+        return network
+    except ValueError:
+        pass
+    if network not in NETWORK_TO_ID:
+        raise ValueError(f"Unsupported network: {network}")
+    return NETWORK_TO_ID[network]
+
+
+KNOWN_TOKENS = {
+    "11155111": [  # Sepolia testnet
+        {
+            "human_name": "usdc",
+            "address": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+            "name": "USD Coin",
+            "decimals": 6,
+            "version": "2",
+        }
+    ],
+    "84532": [
+        {
+            "human_name": "usdc",
+            "address": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+            "name": "USDC",
+            "decimals": 6,
+            "version": "2",
+        }
+    ],
+    "8453": [
+        {
+            "human_name": "usdc",
+            "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+            "name": "USD Coin",  # needs to be exactly what is returned by name() on contract
+            "decimals": 6,
+            "version": "2",
+        }
+    ],
+    "43113": [
+        {
+            "human_name": "usdc",
+            "address": "0x5425890298aed601595a70AB815c96711a31Bc65",
+            "name": "USD Coin",
+            "decimals": 6,
+            "version": "2",
+        }
+    ],
+    "43114": [
+        {
+            "human_name": "usdc",
+            "address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
+            "name": "USDC",
+            "decimals": 6,
+            "version": "2",
+        }
+    ],
+}
+
+
+def get_token_name(chain_id: str, address: str) -> str:
+    """Get the token name for a given chain and address"""
+    for token in KNOWN_TOKENS[chain_id]:
+        if token["address"] == address:
+            return token["name"]
+    raise ValueError(f"Token not found for chain {chain_id} and address {address}")
+
+
+def get_token_version(chain_id: str, address: str) -> str:
+    """Get the token version for a given chain and address"""
+    for token in KNOWN_TOKENS[chain_id]:
+        if token["address"] == address:
+            return token["version"]
+    raise ValueError(f"Token not found for chain {chain_id} and address {address}")
+
+
+def get_token_decimals(chain_id: str, address: str) -> int:
+    """Get the token decimals for a given chain and address"""
+    for token in KNOWN_TOKENS[chain_id]:
+        if token["address"] == address:
+            return token["decimals"]
+    raise ValueError(f"Token not found for chain {chain_id} and address {address}")
+
+
+def get_default_token_address(chain_id: str, token_type: str = "usdc") -> str:
+    """Get the default token address for a given chain and token type"""
+    for token in KNOWN_TOKENS[chain_id]:
+        if token["human_name"] == token_type:
+            return token["address"]
+    raise ValueError(f"Token type '{token_type}' not found for chain {chain_id}")

traia_iatp/d402/client.py

@@ -0,0 +1,150 @@
+"""D402 client for IATP agent-to-agent payments."""
+
+import logging
+from typing import Optional, Dict, Any
+from eth_account import Account
+from .clients.base import d402Client
+from .types import PaymentRequirements
+
+logger = logging.getLogger(__name__)
+
+
+class D402IATPClient:
+    """Client for making d402 payments in IATP protocol.
+    
+    This wraps the Coinbase d402 client and provides IATP-specific functionality,
+    including integration with utility agent smart contracts.
+    """
+    
+    def __init__(
+        self,
+        account: Account,
+        max_value: Optional[int] = None,
+        agent_contract_address: Optional[str] = None,
+        operator_private_key: Optional[str] = None
+    ):
+        """Initialize the d402 IATP client.
+        
+        Args:
+            account: eth_account.Account instance for signing payments
+            max_value: Optional maximum allowed payment amount in base units
+            agent_contract_address: Optional address of the client agent's smart contract
+            operator_private_key: Optional operator private key for signing service requests
+        """
+        self.account = account
+        self.max_value = max_value
+        self.agent_contract_address = agent_contract_address
+        self.operator_private_key = operator_private_key
+        
+        # Initialize the underlying d402 client
+        self.d402_client = d402Client(
+            account=account,
+            max_value=max_value
+        )
+    
+    def create_payment_header(
+        self,
+        payment_requirements: PaymentRequirements,
+        d402_version: int = 1
+    ) -> str:
+        """Create a payment header for the given requirements.
+        
+        This creates an EIP-3009 signed payment authorization that the facilitator
+        can use to pull funds from the client agent's wallet.
+        
+        Args:
+            payment_requirements: Selected payment requirements from server
+            d402_version: d402 protocol version
+            
+        Returns:
+            Base64-encoded signed payment header for X-PAYMENT header
+        """
+        return self.d402_client.create_payment_header(
+            payment_requirements=payment_requirements,
+            d402_version=d402_version
+        )
+    
+    def select_payment_requirements(
+        self,
+        accepts: list[PaymentRequirements],
+        network_filter: Optional[str] = None,
+        scheme_filter: Optional[str] = "exact"
+    ) -> PaymentRequirements:
+        """Select payment requirements from available options.
+        
+        Args:
+            accepts: List of accepted payment requirements from server
+            network_filter: Optional network to filter by
+            scheme_filter: Optional scheme to filter by (default: "exact")
+            
+        Returns:
+            Selected payment requirements
+            
+        Raises:
+            UnsupportedSchemeException: If no supported scheme found
+            PaymentAmountExceededError: If amount exceeds max_value
+        """
+        return self.d402_client.select_payment_requirements(
+            accepts=accepts,
+            network_filter=network_filter,
+            scheme_filter=scheme_filter
+        )
+    
+    def get_payment_info_for_agent_card(self, agent_card: dict) -> Optional[Dict[str, Any]]:
+        """Extract d402 payment information from an agent card.
+        
+        Args:
+            agent_card: Agent card dictionary
+            
+        Returns:
+            Payment information if available, None otherwise
+        """
+        metadata = agent_card.get("metadata", {})
+        return metadata.get("d402")
+
+
+def create_iatp_payment_client(
+    private_key: str,
+    max_value_usd: Optional[float] = None,
+    agent_contract_address: Optional[str] = None
+) -> D402IATPClient:
+    """Convenience function to create an IATP payment client.
+    
+    Args:
+        private_key: Hex-encoded private key (with or without 0x prefix)
+        max_value_usd: Optional maximum payment in USD
+        agent_contract_address: Optional agent contract address
+        
+    Returns:
+        Configured D402IATPClient
+        
+    Example:
+        client = create_iatp_payment_client(
+            private_key="0x...",
+            max_value_usd=10.0  # Max $10 per request
+        )
+        
+        # Use with httpx
+        from .clients.httpx import Httpd402Client
+        http_client = Httpd402Client(client)
+        response = await http_client.get("https://agent.example.com/api")
+    """
+    # Remove 0x prefix if present
+    if private_key.startswith("0x"):
+        private_key = private_key[2:]
+    
+    # Create eth_account.Account
+    account = Account.from_key(private_key)
+    
+    # Convert USD to atomic units (assuming USDC with 6 decimals)
+    max_value = None
+    if max_value_usd is not None:
+        max_value = int(max_value_usd * 1_000_000)  # USDC has 6 decimals
+    
+    return D402IATPClient(
+        account=account,
+        max_value=max_value,
+        agent_contract_address=agent_contract_address,
+        operator_private_key=private_key
+    )
+

traia_iatp/d402/clients/__init__.py

@@ -0,0 +1,7 @@
+"""D402 client implementations."""
+
+from .base import d402Client, decode_x_payment_response
+from .httpx import d402_payment_hooks, d402HttpxClient
+
+__all__ = ["d402Client", "decode_x_payment_response", "d402_payment_hooks", "d402HttpxClient"]
+