Repository navigation
API_INTEGRATION
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.
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 │
└──────────────┘ └──────────────┘ └──────────────┘
- Base URL: http://localhost:8003/api/
- Authentication: JWT Bearer tokens
- Content Type: application/json
- Error Format: Standard HTTP status codes with JSON error bodies
- URL: ws://localhost:8006/ws
- Protocol: JSON-based messaging
- Authentication: Token-based handshake
- Real-time Data: Continuous streaming of system state
- Endpoint: /graphql
- Query Language: GraphQL
- Real-time Subscriptions: Subscription-based updates
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
}'Include the API key in the Authorization header:
curl -H "Authorization: Bearer YOUR_API_KEY" \
http://localhost:8003/api/consciousnessimport 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')# Include token in Authorization header
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
http://localhost:8003/api/stateFor 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_STATEEndpoint: 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"
}
}Endpoint: GET /docs Description: Interactive API documentation (Swagger UI) Authentication: None required Response: Swagger UI interface
Endpoint: GET /openapi.json Description: OpenAPI 3.0 specification Authentication: None required Response: JSON OpenAPI specification
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
}
}
}
}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
}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
}
}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"
}
}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
}
}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
}
}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
}
}
]
}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
}// 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);
};{
"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}
}
}
}{
"type": "agi_response",
"timestamp": 1234567890.123,
"data": {
"session_id": "session_abc123",
"response": "Based on the current consciousness state...",
"confidence": 0.87
}
}{
"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"]
}
}
}- 200 OK: Request successful
- 201 Created: Resource created successfully
- 204 No Content: Request successful, no content to return
- 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
- 500 Internal Server Error: Unexpected server error
- 503 Service Unavailable: Service temporarily unavailable
{
"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
}
}All API responses include rate limiting information:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1234567890
Retry-After: 60
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")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())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);
});# 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, networkimport 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")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()# 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_sslimport 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)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)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)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)
raiseThe 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:
- Unified Interface: Single API layer for all system components
- Real-time Data: WebSocket streaming for live updates
- Robust Security: Authentication, authorization, and encryption
- Comprehensive Documentation: Interactive API docs and examples
- Client Libraries: Ready-to-use libraries for major languages
- Error Handling: Comprehensive error management and recovery
- Performance Optimization: Caching, batching, and monitoring
- 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.