Python SDK Reference

from aim_sdk import secure

# Zero-configuration mode (uses embedded credentials)
agent = secure("my-agent")

# The SDK automatically:
# - Registers the agent with AIM
# - Manages authentication tokens
# - Handles token refresh
# - Reports capabilities
# - Tracks operations

# Use the agent
result = agent.execute("process_data", {"input": "data"})

# Core Classes and Functions

from aim_sdk import (
    secure,           # Enterprise-grade security function
    AIMAgent,         # Main agent class
    AIMConfig,        # Configuration class
    AIMClient,        # Low-level API client
    Capability,       # Capability decorator
    MCPServer,        # MCP server registration
    TrustScore,       # Trust score utilities
    AIMException,     # Base exception class
)

# Type hints
from aim_sdk.types import (
    AgentMetadata,
    CapabilityDefinition,
    MCPServerConfig,
    TrustMetrics,
    TokenPair,
    ExecutionContext,
)

# AIMAgent Class Methods

class AIMAgent:
    """Main agent class for interacting with AIM"""

    # Registration & Lifecycle
    def register(self) -> Dict[str, Any]:
        """Register agent with AIM server"""

    def unregister(self) -> bool:
        """Unregister agent from AIM"""

    def refresh_registration(self) -> Dict[str, Any]:
        """Refresh agent registration"""

    # Capability Management
    def add_capability(
        self,
        name: str,
        handler: Callable,
        description: str = None,
        parameters: Dict = None
    ) -> None:
        """Add a capability to the agent"""

    def remove_capability(self, name: str) -> bool:
        """Remove a capability"""

    def list_capabilities(self) -> List[CapabilityDefinition]:
        """List all registered capabilities"""

    # MCP Server Management
    def register_mcp_server(
        self,
        name: str,
        url: str,
        public_key: str = None
    ) -> MCPServerConfig:
        """Register an MCP server"""

    def list_mcp_servers(self) -> List[MCPServerConfig]:
        """List registered MCP servers"""

    # Execution & Operations
    def execute(
        self,
        capability: str,
        parameters: Dict = None,
        timeout: float = 30.0
    ) -> Any:
        """Execute a capability"""

    async def execute_async(
        self,
        capability: str,
        parameters: Dict = None
    ) -> Any:
        """Execute capability asynchronously"""

    # Trust & Security
    def get_trust_score(self) -> TrustScore:
        """Get current trust score"""

    def report_verification_event(
        self,
        event_type: str,
        success: bool,
        metadata: Dict = None
    ) -> bool:
        """Report verification event"""

    # Status & Health
    def get_status(self) -> Dict[str, Any]:
        """Get agent status"""

    def health_check(self) -> bool:
        """Perform health check"""

    def get_metrics(self) -> Dict[str, Any]:
        """Get agent metrics"""

# Configuration Options

from aim_sdk import AIMConfig, secure

# 1. Environment Variables (Recommended)
# Set these in your environment:
# AIM_API_URL=https://api.aim.example.com
# AIM_API_KEY=your-api-key
# AIM_AGENT_NAME=my-agent
# AIM_PRIVATE_KEY_PATH=/path/to/key.pem

# 2. Configuration Object
config = AIMConfig(
    api_url="https://api.aim.example.com",
    api_key="your-api-key",  # Optional if using key auth
    agent_name="my-agent",
    private_key_path="/path/to/ed25519_key.pem",

    # Optional settings
    auto_refresh=True,  # Auto-refresh tokens
    refresh_buffer=300,  # Refresh 5 min before expiry
    retry_attempts=3,    # API retry attempts
    timeout=30.0,        # Request timeout

    # Logging
    log_level="INFO",
    log_file="/var/log/aim/agent.log",

    # Security
    verify_ssl=True,
    ca_bundle="/path/to/ca-bundle.pem",
)

agent = secure("my-agent", config=config)

# 3. Configuration File (aim.yaml)
"""
api:
  url: https://api.aim.example.com
  key: ${AIM_API_KEY}  # Support env vars

agent:
  name: my-agent
  private_key: /path/to/key.pem

security:
  verify_ssl: true
  ca_bundle: /etc/ssl/certs/ca-certificates.crt

logging:
  level: INFO
  file: /var/log/aim/agent.log
"""

# Load from file
agent = secure("my-agent", config_file="aim.yaml")

# Async/Await Support

import asyncio
from aim_sdk import secure

# Async agent registration
async def main():
    agent = await secure("async-agent", async_mode=True)

    # Async capability execution
    result = await agent.execute_async(
        "process_data",
        {"input": "data"}
    )

    # Async batch operations
    tasks = []
    for i in range(10):
        task = agent.execute_async(
            "process_item",
            {"item_id": i}
        )
        tasks.append(task)

    results = await asyncio.gather(*tasks)

    # Async context manager
    async with secure("context-agent") as agent:
        await agent.execute_async("operation")
        # Auto cleanup on exit

# Run async code
asyncio.run(main())

# Async decorator support
class AsyncProcessor:
    @capability(async_mode=True)
    async def process(self, data):
        result = await self.async_operation(data)
        return result

# MCP Server Integration

from aim_sdk import secure, MCPServer

agent = secure("mcp-agent")

# Register MCP server
mcp_server = agent.register_mcp_server(
    name="data-processor",
    url="http://localhost:8080",
    public_key="""-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
-----END PUBLIC KEY-----""",
    capabilities=[
        "process_text",
        "analyze_data",
        "export_results"
    ]
)

# List MCP servers
servers = agent.list_mcp_servers()
for server in servers:
    print(f"{server.name}: {server.url}")
    print(f"  Capabilities: {server.capabilities}")
    print(f"  Verified: {server.is_verified}")

# Call MCP tool
result = agent.call_mcp_tool(
    server="data-processor",
    tool="process_text",
    parameters={"text": "Hello, World!"}
)

# MCP discovery
discovered = agent.discover_mcp_servers()
for server in discovered:
    if server.trust_score > 0.8:
        agent.register_mcp_server(
            name=server.name,
            url=server.url,
            auto_verify=True
        )

# Testing & Development

import pytest
from unittest.mock import Mock, patch
from aim_sdk import secure, AIMAgent
from aim_sdk.testing import MockAIMServer, TestAgent

# Unit testing with mocks
def test_agent_registration():
    with MockAIMServer() as mock_server:
        agent = secure("test-agent", api_url=mock_server.url)

        assert agent.is_registered
        assert mock_server.received_registration("test-agent")

        # Test capability
        agent.add_capability("test_cap", lambda x: x * 2)
        result = agent.execute("test_cap", {"x": 5})
        assert result == 10

# Integration testing
@pytest.fixture
def test_agent():
    """Fixture for test agent"""
    return TestAgent("integration-agent")

def test_end_to_end(test_agent):
    # TestAgent provides isolated environment
    test_agent.register()
    test_agent.add_capability("process", process_func)

    result = test_agent.execute("process", {"data": "test"})
    assert result["status"] == "success"

    # Verify metrics
    metrics = test_agent.get_metrics()
    assert metrics["executions"] == 1
    assert metrics["success_rate"] == 1.0

# Load testing
from aim_sdk.testing import LoadTester

async def test_load():
    tester = LoadTester(
        agent_name="load-test-agent",
        concurrent_requests=100,
        duration_seconds=60
    )

    results = await tester.run()
    assert results.avg_latency < 0.1  # 100ms
    assert results.success_rate > 0.99
    assert results.requests_per_second > 1000