docs/api_reference.md

# Secure AI Agents Suite - API Reference Documentation

## Overview

The Secure AI Agents Suite provides a comprehensive API for autonomous AI agent interactions. This documentation covers all endpoints, parameters, response formats, and usage examples.

## Table of Contents

1. [Base URL and Authentication](#base-url-and-authentication)
2. [Core Endpoints](#core-endpoints)
3. [Agent Management](#agent-management)
4. [Performance Monitoring](#performance-monitoring)
5. [WebSocket APIs](#websocket-apis)
6. [Error Handling](#error-handling)
7. [Rate Limiting](#rate-limiting)
8. [SDK Reference](#sdk-reference)

## Base URL and Authentication

### Base URL
```
Production: https://your-space-url.hf.space
Local: http://localhost:7860
```

### Authentication
```python
# Headers
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "User-Agent": "Secure-AI-Agents-Suite/2.0.0"
}
```

### API Versioning
```python
# Current version: v1
headers["API-Version"] = "v1"
```

## Core Endpoints

### 1. Process Request

#### POST /api/v1/process

**Description**: Process a user request through the autonomous agent system.

**Request Body**:
```json
{
    "user_input": "string",
    "context": {
        "budget": "number",
        "timeline": "string",
        "team_size": "number",
        "industry": "string",
        "additional_params": "object"
    },
    "agent_type": "string",
    "max_execution_time": "number",
    "options": {
        "enable_monitoring": "boolean",
        "save_results": "boolean",
        "async_mode": "boolean"
    }
}
```

**Parameters**:

| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `user_input` | string | Yes | The user's request text (max 10,000 chars) | - |
| `context` | object | No | Additional context as key-value pairs | {} |
| `agent_type` | string | No | Agent type ("GeneralAgent", "EnterpriseAgent", etc.) | "GeneralAgent" |
| `max_execution_time` | number | No | Maximum execution time in seconds (30-300) | 120 |
| `options.enable_monitoring` | boolean | No | Enable detailed monitoring | true |
| `options.save_results` | boolean | No | Save results for later retrieval | true |
| `options.async_mode` | boolean | No | Run request asynchronously | false |

**Response**:
```json
{
    "status": "success",
    "request_id": "uuid-string",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "agent_type": "GeneralAgent",
    "processing_time": 0.142,
    "results": {
        "analysis": {
            "intent": {
                "primary": "strategic_planning",
                "secondary": ["content_creation", "market_analysis"],
                "confidence": 0.89
            },
            "complexity": {
                "level": "high",
                "score": 8.5,
                "factors": ["multi_step_planning", "strategic_thinking"],
                "estimated_duration_minutes": 15
            },
            "success_probability": 0.85,
            "risk_factors": ["time_constraint", "resource_availability"],
            "adaptation_requirements": ["dynamic_planning", "feedback_integration"]
        },
        "plan": {
            "tasks": [
                {
                    "id": 1,
                    "description": "Market research and competitor analysis",
                    "priority": "high",
                    "duration_minutes": 120,
                    "dependencies": [],
                    "success_criteria": ["comprehensive_analysis", "actionable_insights"],
                    "fallback_strategies": ["use_previous_data", "simplified_analysis"]
                }
            ],
            "total_estimated_duration": 240,
            "critical_path": [1, 2, 3],
            "resource_requirements": {
                "cpu": "moderate",
                "memory": "high",
                "storage": "low"
            },
            "risk_mitigation": {
                "primary_risks": ["resource_shortage", "time_constraints"],
                "mitigation_strategies": ["resource_pooling", "parallel_processing"]
            }
        },
        "execution": {
            "status": "completed",
            "completed_tasks": 3,
            "total_tasks": 3,
            "success_rate": 1.0,
            "execution_time_minutes": 8.5,
            "adaptations_made": 1,
            "decisions_made": 2,
            "failed_tasks": [],
            "performance_metrics": {
                "efficiency_score": 0.92,
                "quality_score": 0.89,
                "completion_rate": 1.0
            },
            "iterations": [
                {
                    "iteration": 1,
                    "tasks_executed": 2,
                    "success_rate": 0.9,
                    "changes_made": ["refined_strategy", "adjusted_timeline"]
                }
            ]
        },
        "summary": "Comprehensive 3-month marketing strategy created with optimized budget allocation...",
        "recommendations": [
            "Focus on digital channels for cost-effectiveness",
            "Implement A/B testing for campaign optimization",
            "Consider seasonal trends in timing"
        ]
    },
    "monitoring": {
        "memory_usage": "145MB",
        "cpu_utilization": "12.5%",
        "cache_hit_rate": 0.78,
        "error_rate": 0.0
    },
    "metadata": {
        "version": "2.0.0",
        "model_used": "autonomous_engine_v2",
        "processing_mode": "synchronous"
    }
}
```

**Status Codes**:
- `200`: Success
- `400`: Bad Request (validation error)
- `429`: Rate Limit Exceeded
- `500`: Internal Server Error
- `503`: Service Unavailable

**Example Usage**:
```python
import requests
import json

url = "http://localhost:7860/api/v1/process"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer your-api-key"
}

payload = {
    "user_input": "Create a comprehensive marketing plan for our new mobile app",
    "context": {
        "budget": 50000,
        "timeline": "3 months",
        "team_size": 5,
        "industry": "technology"
    },
    "agent_type": "EnterpriseAgent",
    "max_execution_time": 180,
    "options": {
        "enable_monitoring": True,
        "save_results": True,
        "async_mode": False
    }
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()
print(json.dumps(result, indent=2))
```

### 2. Get Request Status

#### GET /api/v1/status/{request_id}

**Description**: Get the status of an asynchronous request.

**Path Parameters**:
- `request_id` (string): The unique request identifier

**Response**:
```json
{
    "status": "completed",
    "request_id": "uuid-string",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "progress": {
        "stage": "execution",
        "completed_percentage": 75,
        "current_task": "content generation",
        "estimated_completion": "2024-11-29T17:05:00.000Z"
    },
    "partial_results": {
        "analysis": "completed",
        "plan": "completed",
        "execution": "in_progress"
    },
    "errors": [],
    "estimated_total_time": 120
}
```

### 3. Get Results

#### GET /api/v1/results/{request_id}

**Description**: Retrieve the complete results of a completed request.

**Path Parameters**:
- `request_id` (string): The unique request identifier

**Query Parameters**:
- `format` (string): Response format ("json", "summary", "detailed") - default: "json"

**Response**: Same as POST /api/v1/process response format.

## Agent Management

### 4. List Available Agents

#### GET /api/v1/agents

**Description**: Get list of available agent types and their capabilities.

**Response**:
```json
{
    "agents": [
        {
            "name": "GeneralAgent",
            "type": "general",
            "description": "Multi-domain task handling with balanced capabilities",
            "capabilities": [
                "task_planning",
                "context_analysis",
                "adaptive_execution"
            ],
            "specialties": ["general_purpose", "flexible_thinking"],
            "max_context_length": 5000,
            "typical_response_time": 0.15,
            "success_rate": 0.98
        },
        {
            "name": "EnterpriseAgent",
            "type": "enterprise",
            "description": "Strategic business planning and enterprise-level decision making",
            "capabilities": [
                "strategic_planning",
                "business_analysis",
                "risk_assessment",
                "compliance_awareness"
            ],
            "specialties": ["business_strategy", "financial_planning", "operational_optimization"],
            "max_context_length": 10000,
            "typical_response_time": 0.20,
            "success_rate": 0.96
        }
    ],
    "total_agents": 5,
    "default_agent": "GeneralAgent"
}
```

### 5. Get Agent Info

#### GET /api/v1/agents/{agent_name}

**Description**: Get detailed information about a specific agent.

**Path Parameters**:
- `agent_name` (string): Name of the agent

**Response**:
```json
{
    "name": "EnterpriseAgent",
    "configuration": {
        "temperature": 0.7,
        "max_tokens": 2000,
        "top_p": 0.9,
        "frequency_penalty": 0.0,
        "presence_penalty": 0.0
    },
    "capabilities": [
        {
            "name": "strategic_planning",
            "description": "Long-term strategic planning and roadmap development",
            "supported_contexts": ["business", "finance", "operations"],
            "quality_score": 0.95
        }
    ],
    "performance_metrics": {
        "total_requests": 1250,
        "success_rate": 0.96,
        "average_response_time": 0.20,
        "memory_efficiency": 0.85,
        "error_rate": 0.04
    },
    "limitations": {
        "max_input_length": 10000,
        "max_execution_time": 300,
        "context_overflow_handling": "truncate"
    }
}
```

## Performance Monitoring

### 6. System Health

#### GET /api/v1/health

**Description**: Get system health and status information.

**Response**:
```json
{
    "status": "healthy",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "uptime_seconds": 86400,
    "version": "2.0.0",
    "system": {
        "memory": {
            "total_gb": 8.0,
            "used_gb": 2.5,
            "available_gb": 5.5,
            "usage_percentage": 31.25
        },
        "cpu": {
            "cores": 4,
            "usage_percentage": 12.5,
            "load_average": [0.5, 0.3, 0.2]
        },
        "disk": {
            "total_gb": 100.0,
            "used_gb": 15.0,
            "available_gb": 85.0,
            "usage_percentage": 15.0
        }
    },
    "services": {
        "api_server": "healthy",
        "agent_manager": "healthy",
        "cache_server": "healthy",
        "database": "not_configured"
    },
    "metrics": {
        "total_requests": 1250,
        "requests_per_minute": 5.2,
        "average_response_time": 0.142,
        "error_rate": 0.02
    }
}
```

### 7. Performance Metrics

#### GET /api/v1/metrics

**Description**: Get detailed performance metrics.

**Query Parameters**:
- `time_range` (string): Time range for metrics ("1h", "24h", "7d", "30d") - default: "1h"
- `include_agent_details` (boolean): Include per-agent metrics - default: false

**Response**:
```json
{
    "time_range": "1h",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "overall_metrics": {
        "total_requests": 125,
        "successful_requests": 123,
        "failed_requests": 2,
        "success_rate": 0.984,
        "average_response_time": 0.142,
        "p50_response_time": 0.120,
        "p95_response_time": 0.280,
        "p99_response_time": 0.450,
        "requests_per_minute": 2.1,
        "peak_requests_per_minute": 8.5
    },
    "agent_metrics": {
        "GeneralAgent": {
            "requests": 75,
            "success_rate": 0.987,
            "average_response_time": 0.138,
            "error_rate": 0.013
        }
    },
    "system_metrics": {
        "memory_usage": {
            "peak_gb": 3.2,
            "average_gb": 2.1,
            "current_gb": 2.5
        },
        "cpu_usage": {
            "peak_percentage": 25.0,
            "average_percentage": 12.5,
            "current_percentage": 15.0
        }
    },
    "error_breakdown": {
        "validation_errors": 1,
        "timeout_errors": 1,
        "system_errors": 0
    },
    "cache_performance": {
        "hit_rate": 0.78,
        "total_requests": 125,
        "cache_hits": 98,
        "cache_misses": 27
    }
}
```

### 8. Analytics Dashboard Data

#### GET /api/v1/analytics

**Description**: Get data for analytics dashboard.

**Query Parameters**:
- `dashboard_type` (string): Type of dashboard ("overview", "performance", "agents")
- `time_range` (string): Time range for data
- `granularity` (string): Data granularity ("minute", "hour", "day")

**Response**:
```json
{
    "dashboard_type": "overview",
    "time_range": "24h",
    "granularity": "hour",
    "data": {
        "response_times": [
            {"timestamp": "2024-11-29T16:00:00.000Z", "value": 0.145},
            {"timestamp": "2024-11-29T17:00:00.000Z", "value": 0.142}
        ],
        "success_rates": [
            {"timestamp": "2024-11-29T16:00:00.000Z", "value": 0.98},
            {"timestamp": "2024-11-29T17:00:00.000Z", "value": 0.984}
        ],
        "request_counts": [
            {"timestamp": "2024-11-29T16:00:00.000Z", "value": 65},
            {"timestamp": "2024-11-29T17:00:00.000Z", "value": 60}
        ],
        "agent_distribution": [
            {"agent": "GeneralAgent", "count": 85, "percentage": 68},
            {"agent": "EnterpriseAgent", "count": 25, "percentage": 20}
        ]
    },
    "trends": {
        "response_time_trend": "decreasing",
        "success_rate_trend": "stable",
        "request_volume_trend": "increasing"
    }
}
```

## WebSocket APIs

### 9. Real-time Metrics Stream

#### WebSocket /ws/metrics

**Description**: Stream real-time performance metrics.

**Connection**:
```javascript
const ws = new WebSocket('ws://localhost:7860/ws/metrics');
```

**Message Format**:
```json
{
    "type": "metrics_update",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "data": {
        "response_time": 0.142,
        "memory_usage": 67.2,
        "cpu_usage": 12.5,
        "active_requests": 3,
        "queue_size": 0
    }
}
```

### 10. Execution Progress Stream

#### WebSocket /ws/progress/{request_id}

**Description**: Stream execution progress for a specific request.

**Message Types**:

**Progress Update**:
```json
{
    "type": "progress_update",
    "request_id": "uuid",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "data": {
        "stage": "execution",
        "current_task": "generating_content",
        "completed_tasks": 2,
        "total_tasks": 5,
        "progress_percentage": 40,
        "estimated_time_remaining": 45
    }
}
```

**Completion**:
```json
{
    "type": "completion",
    "request_id": "uuid",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "status": "success",
    "summary": "Request completed successfully"
}
```

## Error Handling

### Error Response Format

```json
{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Input validation failed",
        "details": {
            "field": "user_input",
            "reason": "Input too long",
            "max_length": 10000,
            "current_length": 15000
        },
        "timestamp": "2024-11-29T17:04:26.632Z",
        "request_id": "uuid-string",
        "documentation_url": "https://docs.example.com/errors/VALIDATION_ERROR"
    }
}
```

### Error Codes

| Code | Description | HTTP Status | Recovery |
|------|-------------|-------------|----------|
| `VALIDATION_ERROR` | Input validation failed | 400 | Fix input parameters |
| `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | 429 | Wait and retry |
| `AGENT_UNAVAILABLE` | Requested agent unavailable | 503 | Try different agent |
| `EXECUTION_TIMEOUT` | Request execution timed out | 504 | Increase timeout or simplify |
| `MEMORY_LIMIT_EXCEEDED` | System memory limit exceeded | 507 | Reduce concurrent requests |
| `INTERNAL_ERROR` | Internal server error | 500 | Contact support |

## Rate Limiting

### Rate Limits

- **Global**: 100 requests per minute
- **Per IP**: 100 requests per minute
- **Per Agent**: 200 requests per minute per agent type
- **Burst Limit**: 20 requests per second

### Rate Limit Headers

```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
X-RateLimit-Window: 60
```

### Rate Limit Response

```json
{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Rate limit exceeded. Try again in 30 seconds.",
        "retry_after": 30,
        "limit": 100,
        "window": 60
    }
}
```

## SDK Reference

### Python SDK

#### Installation
```bash
pip install secure-ai-agents-suite
```

#### Basic Usage
```python
from secure_ai_agents import AgentClient

# Initialize client
client = AgentClient(
    base_url="http://localhost:7860",
    api_key="your-api-key"
)

# Process request
result = client.process_request(
    user_input="Create a marketing strategy",
    context={"budget": 50000, "timeline": "3 months"},
    agent_type="EnterpriseAgent"
)

print(result.summary)
```

#### Async Usage
```python
import asyncio
from secure_ai_agents import AsyncAgentClient

async def main():
    client = AsyncAgentClient(base_url="http://localhost:7860")
    
    # Submit async request
    request_id = await client.submit_request(
        user_input="Complex multi-step workflow",
        context={"priority": "high"}
    )
    
    # Monitor progress
    async for progress in client.monitor_progress(request_id):
        print(f"Progress: {progress.progress_percentage}%")
    
    # Get results
    result = await client.get_results(request_id)
    print(result.summary)

asyncio.run(main())
```

### JavaScript SDK

#### Installation
```bash
npm install secure-ai-agents-suite
```

#### Basic Usage
```javascript
import { AgentClient } from 'secure-ai-agents-suite';

const client = new AgentClient({
    baseUrl: 'http://localhost:7860',
    apiKey: 'your-api-key'
});

// Process request
const result = await client.processRequest({
    userInput: 'Create a business plan',
    context: { industry: 'technology', size: 'startup' },
    agentType: 'EnterpriseAgent'
});

console.log(result.summary);
```

#### WebSocket Usage
```javascript
// Real-time progress monitoring
const progressStream = client.monitorProgress('request-id');

progressStream.on('progress', (progress) => {
    console.log(`Progress: ${progress.completedTasks}/${progress.totalTasks}`);
});

progressStream.on('complete', (result) => {
    console.log('Request completed:', result.summary);
});
```

### Response Streaming

For large responses, you can enable streaming:

```python
client = AgentClient(base_url="http://localhost:7860", stream=True)

async for chunk in client.process_request_stream(
    user_input="Complex analysis request"
):
    print(chunk)  # Process each chunk as it arrives
```

## Rate Limiting and Performance

### Best Practices

1. **Use Async Mode**: For complex requests, use `async_mode: true`
2. **Batch Processing**: Group similar requests when possible
3. **Context Optimization**: Keep context data minimal and relevant
4. **Timeout Management**: Set appropriate timeouts based on request complexity
5. **Error Handling**: Implement proper error handling with exponential backoff

### Performance Optimization

```python
# Enable response caching
client = AgentClient(
    base_url="http://localhost:7860",
    cache_responses=True,
    cache_ttl=3600
)

# Use connection pooling
client = AgentClient(
    base_url="http://localhost:7860",
    max_connections=10,
    max_keepalive_connections=5
)

# Enable compression
client = AgentClient(
    base_url="http://localhost:7860",
    compression=True
)
```

## Changelog

### Version 2.0.0 (2024-11-29)

- Added autonomous planning and reasoning capabilities
- Implemented real-time performance monitoring
- Added WebSocket APIs for streaming
- Enhanced security with input validation
- Improved error handling and recovery
- Added comprehensive API documentation

### Version 1.5.0

- Basic agent functionality
- Simple request/response API
- Performance monitoring