Skip to content

API_INTEGRATION

RealDaniG edited this page Oct 13, 2025 · 2 revisions

AEGIS API Integration Guide

Overview

This guide provides comprehensive documentation for integrating external applications with the AEGIS (Autonomous Governance and Intelligent Systems) platform through its RESTful API and WebSocket interfaces. It covers authentication, available endpoints, request/response formats, error handling, and best practices for building robust integrations.

API Architecture

Unified API Layer

The AEGIS system exposes a unified API layer that provides access to all system components through a single interface:

┌─────────────────────────────────────────────────────────────┐
│                    External Applications                    │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                    Unified API Server                       │
│                    (FastAPI + Uvicorn)                      │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                 API Client & Orchestration                  │
└─────────────────────────┬───────────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
┌───────▼──────┐  ┌───────▼──────┐  ┌───────▼──────┐
│ Consciousness│  │      AGI     │  │  Consensus   │
│    Engine    │  │   Framework  │  │   Protocol   │
└──────────────┘  └──────────────┘  └──────────────┘

Communication Protocols

RESTful API

  • Base URL: http://localhost:8003/api/
  • Authentication: JWT Bearer tokens
  • Content Type: application/json
  • Error Format: Standard HTTP status codes with JSON error bodies

WebSocket Streaming

  • URL: ws://localhost:8006/ws
  • Protocol: JSON-based messaging
  • Authentication: Token-based handshake
  • Real-time Data: Continuous streaming of system state

GraphQL (Future)

  • Endpoint: /graphql
  • Query Language: GraphQL
  • Real-time Subscriptions: Subscription-based updates

Authentication

API Key Authentication

Obtaining API Keys

API keys can be generated through the administrative interface or configuration files:

# Generate new API key
curl -X POST http://localhost:8003/api/auth/key \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Application",
    "permissions": ["read", "write"],
    "expires_in": 86400
  }'

Using API Keys

Include the API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     http://localhost:8003/api/consciousness

JWT Token Authentication

Token Generation

import jwt
import datetime

def generate_token(user_id, permissions, secret_key):
    """Generate JWT token for API access."""
    payload = {
        'user_id': user_id,
        'permissions': permissions,
        'exp': datetime.datetime.utcnow() + datetime.timedelta(hours=24),
        'iat': datetime.datetime.utcnow()
    }
    
    return jwt.encode(payload, secret_key, algorithm='HS256')

Token Usage

# Include token in Authorization header
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
     http://localhost:8003/api/state

OAuth 2.0 Integration (Future)

For third-party applications, OAuth 2.0 integration will be available:

# OAuth 2.0 authorization endpoint
GET http://localhost:8003/oauth/authorize?
    response_type=code&
    client_id=YOUR_CLIENT_ID&
    redirect_uri=YOUR_REDIRECT_URI&
    scope=read+write&
    state=RANDOM_STATE

RESTful API Endpoints

Health and Status

System Health Check

Endpoint: GET /health Description: Check overall system health status Authentication: None required Response:

{
  "status": "healthy",
  "timestamp": 1234567890.123,
  "api_client_initialized": true,
  "components": {
    "consciousness_engine": "running",
    "agi_framework": "operational",
    "p2p_network": "connected",
    "consensus_protocol": "active"
  }
}

API Documentation

Endpoint: GET /docs Description: Interactive API documentation (Swagger UI) Authentication: None required Response: Swagger UI interface

API Schema

Endpoint: GET /openapi.json Description: OpenAPI 3.0 specification Authentication: None required Response: JSON OpenAPI specification

Consciousness Metrics

Get Consciousness State

Endpoint: GET /api/consciousness Description: Retrieve current consciousness metrics Authentication: Required Response:

{
  "timestamp": 1234567890.123,
  "consciousness_level": 0.856,
  "phi": 0.789,
  "coherence": 0.923,
  "stability": 0.876,
  "divergence": 0.123,
  "state_classification": "heightened-awareness",
  "is_conscious": true,
  "nodes": {
    "0": {
      "output": 0.8765,
      "oscillator": {
        "phase": 2.345678,
        "amplitude": 0.987654
      },
      "dimensions": {
        "physical": 0.123456,
        "emotional": 0.234567,
        "mental": 0.345678,
        "spiritual": 0.456789,
        "temporal": 0.567890
      }
    }
  }
}

Send Consciousness Input

Endpoint: POST /api/input Description: Send sensory input to consciousness system Authentication: Required Request Body:

{
  "visual": 0.75,
  "auditory": 0.65,
  "tactile": 0.80,
  "emotional": 0.70,
  "timestamp": 1234567890.123
}

Response:

{
  "success": true,
  "message": "Input processed successfully",
  "processed_at": 1234567891.456
}

AGI Framework

Get AGI State

Endpoint: GET /api/agi Description: Retrieve current AGI system status Authentication: Required Response:

{
  "status": "operational",
  "models_loaded": ["gpt-4", "llama-2-70b", "mistral-7b"],
  "active_sessions": 15,
  "total_decisions": 12547,
  "modules_running": 8,
  "plugins_loaded": 12,
  "resource_usage": {
    "cpu_percent": 45.2,
    "memory_mb": 2048,
    "gpu_utilization": 67.8
  }
}

Send Chat Message

Endpoint: POST /api/chat Description: Send message to AGI system for processing Authentication: Required Request Body:

{
  "message": "What is the current state of consciousness in the system?",
  "session_id": "session_abc123",
  "context": {
    "user_id": "user_xyz789",
    "preferences": {
      "detail_level": "detailed",
      "technical_depth": "intermediate"
    }
  }
}

Response:

{
  "response": "The current consciousness level is 0.856, indicating a heightened-awareness state. The phi metric is 0.789, showing strong integrated information processing...",
  "session_id": "session_abc123",
  "confidence": 0.87,
  "processing_time": 0.456,
  "consciousness_influence": {
    "awareness_level": "heightened-awareness",
    "response_tone": "informative"
  }
}

Make Consciousness-Aware Decision

Endpoint: POST /api/decision Description: Request a decision influenced by consciousness metrics Authentication: Required Request Body:

{
  "context": "Should we proceed with the network expansion?",
  "options": ["Yes", "No", "Delay"],
  "constraints": ["budget < 10000", "timeline < 30 days"],
  "importance": "high"
}

Response:

{
  "decision": "Delay",
  "confidence": 0.78,
  "reasoning": "Based on current resource constraints and consciousness metrics indicating a need for more information gathering before major decisions...",
  "alternative": "Yes",
  "consciousness_factors": {
    "phi": 0.789,
    "coherence": 0.923,
    "stability": 0.876
  }
}

System State

Get Unified System State

Endpoint: GET /api/state Description: Retrieve complete system state including consciousness and AGI Authentication: Required Response:

{
  "timestamp": 1234567890.123,
  "consciousness_state": {
    "consciousness_level": 0.856,
    "phi": 0.789,
    "coherence": 0.923,
    "stability": 0.876,
    "divergence": 0.123,
    "state_classification": "heightened-awareness",
    "is_conscious": true
  },
  "agi_state": {
    "status": "operational",
    "models_loaded": ["gpt-4", "llama-2-70b"],
    "active_sessions": 15,
    "total_decisions": 12547
  },
  "network_state": {
    "connected_peers": 23,
    "consensus_status": "active",
    "message_queue_size": 5
  }
}

Consensus Protocol

Get Proposals

Endpoint: GET /api/consensus/proposals Description: Retrieve list of active consensus proposals Authentication: Required Query Parameters:

  • status: Filter by status (active, approved, rejected)
  • limit: Maximum number of proposals to return Response:
{
  "proposals": [
    {
      "proposal_id": "prop_12345",
      "title": "Update Consciousness Threshold",
      "description": "Propose increasing minimum consciousness level for critical decisions",
      "status": "voting",
      "author": "node_abc",
      "created_at": "2023-01-01T12:00:00Z",
      "voting_deadline": "2023-12-31T23:59:59Z",
      "votes": {
        "for": 15,
        "against": 3,
        "abstain": 2,
        "total": 20
      }
    }
  ]
}

Create Proposal

Endpoint: POST /api/consensus/proposals Description: Create a new consensus proposal Authentication: Required Request Body:

{
  "title": "New Feature Implementation",
  "description": "Proposal to implement enhanced visualization features",
  "type": "feature_request",
  "content": {
    "feature_spec": "Detailed specification...",
    "implementation_plan": "Step-by-step plan...",
    "resource_requirements": {
      "development_hours": 120,
      "testing_hours": 40
    }
  },
  "voting_deadline_hours": 168  // 1 week
}

WebSocket Integration

Real-time Data Streaming

Connection Setup

// JavaScript WebSocket client
const ws = new WebSocket('ws://localhost:8006/ws');

ws.onopen = function(event) {
    console.log('Connected to AEGIS WebSocket');
    
    // Send authentication token if required
    ws.send(JSON.stringify({
        type: 'auth',
        token: 'YOUR_JWT_TOKEN'
    }));
};

ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    
    switch(message.type) {
        case 'consciousness_update':
            handleConsciousnessUpdate(message.data);
            break;
        case 'agi_response':
            handleAGIResponse(message.data);
            break;
        case 'system_alert':
            handleSystemAlert(message.data);
            break;
        default:
            console.log('Unknown message type:', message.type);
    }
};

ws.onclose = function(event) {
    console.log('WebSocket connection closed');
};

ws.onerror = function(error) {
    console.error('WebSocket error:', error);
};

Message Types

Consciousness Updates
{
  "type": "consciousness_update",
  "timestamp": 1234567890.123,
  "data": {
    "consciousness_level": 0.856,
    "phi": 0.789,
    "coherence": 0.923,
    "nodes": {
      "0": {"output": 0.8765, "phase": 2.345678},
      "1": {"output": 0.7654, "phase": 1.234567}
    }
  }
}
AGI Responses
{
  "type": "agi_response",
  "timestamp": 1234567890.123,
  "data": {
    "session_id": "session_abc123",
    "response": "Based on the current consciousness state...",
    "confidence": 0.87
  }
}
System Alerts
{
  "type": "system_alert",
  "timestamp": 1234567890.123,
  "data": {
    "alert_type": "high_consciousness",
    "level": "warning",
    "message": "Consciousness level exceeded 0.9 threshold",
    "details": {
      "current_level": 0.923,
      "threshold": 0.9,
      "nodes_affected": ["0", "5", "11"]
    }
  }
}

Error Handling

HTTP Status Codes

Success Codes

  • 200 OK: Request successful
  • 201 Created: Resource created successfully
  • 204 No Content: Request successful, no content to return

Client Error Codes

  • 400 Bad Request: Invalid request format or parameters
  • 401 Unauthorized: Authentication required or failed
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 422 Unprocessable Entity: Valid request but semantic errors
  • 429 Too Many Requests: Rate limiting exceeded

Server Error Codes

  • 500 Internal Server Error: Unexpected server error
  • 503 Service Unavailable: Service temporarily unavailable

Error Response Format

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid input parameters provided",
    "details": {
      "field": "consciousness_level",
      "issue": "Value must be between 0 and 1",
      "received": 1.5
    },
    "timestamp": 1234567890.123
  }
}

Rate Limiting

Rate Limit Headers

All API responses include rate limiting information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1234567890
Retry-After: 60

Handling Rate Limits

import time
import requests

def make_api_request(url, headers, max_retries=3):
    """Make API request with rate limit handling."""
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        
        if response.status_code == 429:
            # Rate limited - wait and retry
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Rate limited. Waiting {retry_after} seconds...")
            time.sleep(retry_after)
            continue
            
        return response
    
    raise Exception("Max retries exceeded due to rate limiting")

Client Libraries

Python Client

import asyncio
import aiohttp
from typing import Dict, Any

class AEGISClient:
    """Python client for AEGIS API."""
    
    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url.rstrip('/')
        self.api_key = api_key
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }
    
    async def get_consciousness_state(self) -> Dict[str, Any]:
        """Get current consciousness state."""
        async with aiohttp.ClientSession() as session:
            async with session.get(
                f'{self.base_url}/api/consciousness',
                headers=self.headers
            ) as response:
                response.raise_for_status()
                return await response.json()
    
    async def send_chat_message(self, message: str, session_id: str = None) -> Dict[str, Any]:
        """Send chat message to AGI system."""
        data = {
            'message': message,
            'session_id': session_id or f'session_{int(time.time())}'
        }
        
        async with aiohttp.ClientSession() as session:
            async with session.post(
                f'{self.base_url}/api/chat',
                headers=self.headers,
                json=data
            ) as response:
                response.raise_for_status()
                return await response.json()
    
    async def make_decision(self, context: Dict[str, Any], options: list) -> Dict[str, Any]:
        """Request consciousness-aware decision."""
        data = {
            'context': context,
            'options': options
        }
        
        async with aiohttp.ClientSession() as session:
            async with session.post(
                f'{self.base_url}/api/decision',
                headers=self.headers,
                json=data
            ) as response:
                response.raise_for_status()
                return await response.json()

# Usage example
async def main():
    client = AEGISClient('http://localhost:8003', 'your_api_key')
    
    # Get consciousness state
    consciousness = await client.get_consciousness_state()
    print(f"Consciousness level: {consciousness['consciousness_level']}")
    
    # Send chat message
    response = await client.send_chat_message(
        "What is the current system status?",
        "session_123"
    )
    print(f"Response: {response['response']}")

# Run the example
# asyncio.run(main())

JavaScript Client

class AEGISClient {
    constructor(baseUrl, apiKey) {
        this.baseUrl = baseUrl.replace(/\/$/, '');
        this.apiKey = apiKey;
        this.headers = {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
        };
    }
    
    async getConsciousnessState() {
        const response = await fetch(`${this.baseUrl}/api/consciousness`, {
            headers: this.headers
        });
        
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        
        return await response.json();
    }
    
    async sendChatMessage(message, sessionId = null) {
        const data = {
            message: message,
            session_id: sessionId || `session_${Date.now()}`
        };
        
        const response = await fetch(`${this.baseUrl}/api/chat`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify(data)
        });
        
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        
        return await response.json();
    }
    
    async makeDecision(context, options) {
        const data = {
            context: context,
            options: options
        };
        
        const response = await fetch(`${this.baseUrl}/api/decision`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify(data)
        });
        
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        
        return await response.json();
    }
}

// Usage example
const client = new AEGISClient('http://localhost:8003', 'your_api_key');

// Get consciousness state
client.getConsciousnessState()
    .then(state => {
        console.log(`Consciousness level: ${state.consciousness_level}`);
    })
    .catch(error => {
        console.error('Error:', error);
    });

// Send chat message
client.sendChatMessage("What is the current system status?", "session_123")
    .then(response => {
        console.log(`Response: ${response.response}`);
    })
    .catch(error => {
        console.error('Error:', error);
    });

Best Practices

API Usage Guidelines

Efficient Request Patterns

# Good: Batch requests when possible
async def get_multiple_metrics(client):
    """Get multiple metrics in parallel."""
    tasks = [
        client.get_consciousness_state(),
        client.get_agi_state(),
        client.get_network_status()
    ]
    
    results = await asyncio.gather(*tasks, return_exceptions=True)
    
    for i, result in enumerate(results):
        if isinstance(result, Exception):
            print(f"Error getting metric {i}: {result}")
        else:
            print(f"Metric {i}: {result}")

# Avoid: Sequential requests
async def get_metrics_sequentially(client):
    """Inefficient sequential requests."""
    consciousness = await client.get_consciousness_state()  # Wait
    agi = await client.get_agi_state()                      # Wait
    network = await client.get_network_status()             # Wait
    return consciousness, agi, network

Error Handling

import asyncio
import logging

logger = logging.getLogger(__name__)

async def robust_api_call(client, method, *args, max_retries=3, backoff_factor=1.0):
    """Make robust API calls with retry logic."""
    for attempt in range(max_retries):
        try:
            return await getattr(client, method)(*args)
        
        except aiohttp.ClientResponseError as e:
            if e.status >= 500:  # Server error - retry
                if attempt < max_retries - 1:
                    wait_time = backoff_factor * (2 ** attempt)
                    logger.warning(f"Server error {e.status}, retrying in {wait_time}s...")
                    await asyncio.sleep(wait_time)
                    continue
                else:
                    logger.error(f"Max retries exceeded for server error {e.status}")
                    raise
            else:  # Client error - don't retry
                logger.error(f"Client error {e.status}: {e.message}")
                raise
        
        except aiohttp.ClientConnectorError as e:
            if attempt < max_retries - 1:
                wait_time = backoff_factor * (2 ** attempt)
                logger.warning(f"Connection error, retrying in {wait_time}s...")
                await asyncio.sleep(wait_time)
                continue
            else:
                logger.error(f"Max retries exceeded for connection error: {e}")
                raise
        
        except Exception as e:
            logger.error(f"Unexpected error: {e}")
            raise
    
    raise Exception("Max retries exceeded")

Caching Strategy

import asyncio
import time
from functools import wraps

def cache_result(ttl_seconds=60):
    """Cache API results to reduce load."""
    def decorator(func):
        cache = {}
        
        @wraps(func)
        async def wrapper(*args, **kwargs):
            # Create cache key
            key = str(args) + str(sorted(kwargs.items()))
            current_time = time.time()
            
            # Check cache
            if key in cache:
                result, timestamp = cache[key]
                if current_time - timestamp < ttl_seconds:
                    return result
            
            # Call function and cache result
            result = await func(*args, **kwargs)
            cache[key] = (result, current_time)
            
            return result
        
        return wrapper
    return decorator

class CachedAEGISClient(AEGISClient):
    @cache_result(ttl_seconds=30)
    async def get_consciousness_state(self):
        return await super().get_consciousness_state()
    
    @cache_result(ttl_seconds=60)
    async def get_agi_state(self):
        return await super().get_agi_state()

Security Considerations

Transport Security

HTTPS in Production

# Production client should use HTTPS
class SecureAEGISClient(AEGISClient):
    def __init__(self, base_url: str, api_key: str, verify_ssl: bool = True):
        # Ensure HTTPS
        if not base_url.startswith('https://'):
            raise ValueError("Production API must use HTTPS")
        
        super().__init__(base_url, api_key)
        self.verify_ssl = verify_ssl

Certificate Validation

import ssl
import certifi

def create_secure_session():
    """Create HTTPS session with proper certificate validation."""
    connector = aiohttp.TCPConnector(
        ssl=ssl.create_default_context(cafile=certifi.where())
    )
    return aiohttp.ClientSession(connector=connector)

Input Validation

Client-Side Validation

import re
from typing import Dict, Any

class ValidatedAEGISClient(AEGISClient):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
    
    def validate_consciousness_input(self, data: Dict[str, Any]) -> Dict[str, Any]:
        """Validate consciousness input data."""
        validated = {}
        
        # Validate numeric values
        for key, value in data.items():
            if key in ['visual', 'auditory', 'tactile', 'emotional']:
                if not isinstance(value, (int, float)) or not 0 <= value <= 1:
                    raise ValueError(f"{key} must be a number between 0 and 1")
                validated[key] = float(value)
        
        # Validate timestamp if present
        if 'timestamp' in data:
            timestamp = data['timestamp']
            if not isinstance(timestamp, (int, float)) or timestamp < 0:
                raise ValueError("timestamp must be a positive number")
            validated['timestamp'] = float(timestamp)
        
        return validated
    
    async def send_consciousness_input(self, data: Dict[str, Any]) -> Dict[str, Any]:
        """Send validated consciousness input."""
        validated_data = self.validate_consciousness_input(data)
        return await super().send_consciousness_input(validated_data)

Monitoring and Debugging

Request Logging

import logging
import time
from functools import wraps

logger = logging.getLogger(__name__)

def log_api_calls(func):
    """Decorator to log API calls."""
    @wraps(func)
    async def wrapper(*args, **kwargs):
        start_time = time.time()
        method_name = func.__name__
        
        logger.info(f"API call started: {method_name}")
        
        try:
            result = await func(*args, **kwargs)
            duration = time.time() - start_time
            logger.info(f"API call completed: {method_name} ({duration:.3f}s)")
            return result
        
        except Exception as e:
            duration = time.time() - start_time
            logger.error(f"API call failed: {method_name} ({duration:.3f}s) - {e}")
            raise
    
    return wrapper

class MonitoredAEGISClient(AEGISClient):
    @log_api_calls
    async def get_consciousness_state(self):
        return await super().get_consciousness_state()
    
    @log_api_calls
    async def send_chat_message(self, message, session_id=None):
        return await super().send_chat_message(message, session_id)

Performance Monitoring

import asyncio
import time
from collections import defaultdict, deque

class PerformanceMonitor:
    """Monitor API performance metrics."""
    
    def __init__(self, window_size=100):
        self.metrics = defaultdict(lambda: deque(maxlen=window_size))
        self.lock = asyncio.Lock()
    
    async def record_call(self, method_name, duration, success=True):
        """Record API call metrics."""
        async with self.lock:
            self.metrics[method_name].append({
                'timestamp': time.time(),
                'duration': duration,
                'success': success
            })
    
    def get_stats(self, method_name):
        """Get performance statistics for a method."""
        calls = list(self.metrics[method_name])
        if not calls:
            return None
        
        successful_calls = [c for c in calls if c['success']]
        durations = [c['duration'] for c in successful_calls]
        
        return {
            'total_calls': len(calls),
            'success_rate': len(successful_calls) / len(calls),
            'avg_duration': sum(durations) / len(durations) if durations else 0,
            'min_duration': min(durations) if durations else 0,
            'max_duration': max(durations) if durations else 0
        }

# Integration with client
class MonitoredAEGISClient(AEGISClient):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.monitor = PerformanceMonitor()
    
    async def _make_monitored_call(self, method_name, coro):
        """Make monitored API call."""
        start_time = time.time()
        try:
            result = await coro
            duration = time.time() - start_time
            await self.monitor.record_call(method_name, duration, success=True)
            return result
        except Exception as e:
            duration = time.time() - start_time
            await self.monitor.record_call(method_name, duration, success=False)
            raise

Conclusion

The AEGIS API integration guide provides a comprehensive framework for building applications that interact with the consciousness-aware distributed AI system. Through RESTful endpoints, WebSocket streaming, and client libraries, developers can access the full power of AEGIS while maintaining security, performance, and reliability.

Key features of the API integration include:

  1. Unified Interface: Single API layer for all system components
  2. Real-time Data: WebSocket streaming for live updates
  3. Robust Security: Authentication, authorization, and encryption
  4. Comprehensive Documentation: Interactive API docs and examples
  5. Client Libraries: Ready-to-use libraries for major languages
  6. Error Handling: Comprehensive error management and recovery
  7. Performance Optimization: Caching, batching, and monitoring
  8. Best Practices: Guidelines for efficient and secure integration

As the AEGIS system continues to evolve, the API will expand to provide even more capabilities while maintaining backward compatibility and ease of use. Developers building on the AEGIS platform can leverage these integration capabilities to create innovative applications that harness the power of consciousness-aware artificial intelligence.

Clone this wiki locally