Add comprehensive Flask API documentation for integration

API_DOCUMENTATION.md

@@ -0,0 +1,745 @@
+# Flask API Documentation
+
+## Overview
+
+The Research AI Assistant API provides a RESTful interface for interacting with an AI-powered research assistant. The API uses local GPU models for inference and supports conversational interactions with context management.
+
+**Base URL:** `https://huggingface.co/spaces/JatinAutonomousLabs/Research_AI_Assistant_API`
+
+**API Version:** 1.0
+
+**Content-Type:** `application/json`
+
+## Features
+
+- 🤖 **AI-Powered Responses** - Local GPU model inference (Tesla T4)
+- 💬 **Conversational Context** - Maintains conversation history and user context
+- 🔒 **CORS Enabled** - Ready for web integration
+- ⚡ **Async Processing** - Efficient request handling
+- 📊 **Transparent Reasoning** - Returns reasoning chains and performance metrics
+
+---
+
+## Authentication
+
+Currently, the API does not require authentication. However, for production use, you should:
+
+1. Set `HF_TOKEN` environment variable for Hugging Face model access
+2. Implement API key authentication if needed
+
+---
+
+## Endpoints
+
+### 1. Get API Information
+
+**Endpoint:** `GET /`
+
+**Description:** Returns API information, version, and available endpoints.
+
+**Request:**
+```http
+GET / HTTP/1.1
+Host: huggingface.co
+```
+
+**Response:**
+```json
+{
+  "name": "AI Assistant Flask API",
+  "version": "1.0",
+  "status": "running",
+  "orchestrator_ready": true,
+  "features": {
+    "local_gpu_models": true,
+    "max_workers": 4,
+    "hardware": "NVIDIA T4 Medium"
+  },
+  "endpoints": {
+    "health": "GET /api/health",
+    "chat": "POST /api/chat",
+    "initialize": "POST /api/initialize"
+  }
+}
+```
+
+**Status Codes:**
+- `200 OK` - Success
+
+---
+
+### 2. Health Check
+
+**Endpoint:** `GET /api/health`
+
+**Description:** Checks if the API and orchestrator are ready to handle requests.
+
+**Request:**
+```http
+GET /api/health HTTP/1.1
+Host: huggingface.co
+```
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "orchestrator_ready": true
+}
+```
+
+**Status Codes:**
+- `200 OK` - API is healthy
+  - `orchestrator_ready: true` - Ready to process requests
+  - `orchestrator_ready: false` - Still initializing
+
+**Example Response (Initializing):**
+```json
+{
+  "status": "initializing",
+  "orchestrator_ready": false
+}
+```
+
+---
+
+### 3. Chat Endpoint
+
+**Endpoint:** `POST /api/chat`
+
+**Description:** Send a message to the AI assistant and receive a response with reasoning and context.
+
+**Request Headers:**
+```http
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "message": "Explain quantum entanglement in simple terms",
+  "history": [
+    ["User message 1", "Assistant response 1"],
+    ["User message 2", "Assistant response 2"]
+  ],
+  "session_id": "session-123",
+  "user_id": "user-456"
+}
+```
+
+**Request Fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `message` | string | ✅ Yes | User's message/question (max 10,000 characters) |
+| `history` | array | ❌ No | Conversation history as array of `[user, assistant]` pairs |
+| `session_id` | string | ❌ No | Unique session identifier for context continuity |
+| `user_id` | string | ❌ No | User identifier (defaults to "anonymous") |
+
+**Response (Success):**
+```json
+{
+  "success": true,
+  "message": "Quantum entanglement is when two particles become linked...",
+  "history": [
+    ["Explain quantum entanglement", "Quantum entanglement is when two particles become linked..."]
+  ],
+  "reasoning": {
+    "intent": "educational_query",
+    "steps": ["Understanding request", "Gathering information", "Synthesizing response"],
+    "confidence": 0.95
+  },
+  "performance": {
+    "response_time_ms": 2345,
+    "tokens_generated": 156,
+    "model_used": "mistralai/Mistral-7B-Instruct-v0.2"
+  }
+}
+```
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | boolean | Whether the request was successful |
+| `message` | string | AI assistant's response |
+| `history` | array | Updated conversation history including the new exchange |
+| `reasoning` | object | AI reasoning process and confidence metrics |
+| `performance` | object | Performance metrics (response time, tokens, model used) |
+
+**Status Codes:**
+- `200 OK` - Request processed successfully
+- `400 Bad Request` - Invalid request (missing message, empty message, too long, wrong type)
+- `500 Internal Server Error` - Server error processing request
+- `503 Service Unavailable` - Orchestrator not ready (still initializing)
+
+**Error Response:**
+```json
+{
+  "success": false,
+  "error": "Message is required",
+  "message": "Error processing your request. Please try again."
+}
+```
+
+---
+
+### 4. Initialize Orchestrator
+
+**Endpoint:** `POST /api/initialize`
+
+**Description:** Manually trigger orchestrator initialization (useful if initialization failed on startup).
+
+**Request:**
+```http
+POST /api/initialize HTTP/1.1
+Host: huggingface.co
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{}
+```
+
+**Response (Success):**
+```json
+{
+  "success": true,
+  "message": "Orchestrator initialized successfully"
+}
+```
+
+**Response (Failure):**
+```json
+{
+  "success": false,
+  "message": "Initialization failed. Check logs for details."
+}
+```
+
+**Status Codes:**
+- `200 OK` - Initialization successful
+- `500 Internal Server Error` - Initialization failed
+
+---
+
+## Code Examples
+
+### Python
+
+```python
+import requests
+import json
+
+BASE_URL = "https://huggingface.co/spaces/JatinAutonomousLabs/Research_AI_Assistant_API"
+
+# Check health
+def check_health():
+    response = requests.get(f"{BASE_URL}/api/health")
+    return response.json()
+
+# Send chat message
+def send_message(message, session_id=None, user_id=None, history=None):
+    payload = {
+        "message": message,
+        "session_id": session_id,
+        "user_id": user_id or "anonymous",
+        "history": history or []
+    }
+    
+    response = requests.post(
+        f"{BASE_URL}/api/chat",
+        json=payload,
+        headers={"Content-Type": "application/json"}
+    )
+    
+    if response.status_code == 200:
+        return response.json()
+    else:
+        raise Exception(f"API Error: {response.status_code} - {response.text}")
+
+# Example usage
+if __name__ == "__main__":
+    # Check if API is ready
+    health = check_health()
+    print(f"API Status: {health}")
+    
+    if health.get("orchestrator_ready"):
+        # Send a message
+        result = send_message(
+            message="What is machine learning?",
+            session_id="my-session-123",
+            user_id="user-456"
+        )
+        
+        print(f"Response: {result['message']}")
+        print(f"Reasoning: {result.get('reasoning', {})}")
+        
+        # Continue conversation
+        history = result['history']
+        result2 = send_message(
+            message="Can you explain neural networks?",
+            session_id="my-session-123",
+            user_id="user-456",
+            history=history
+        )
+        print(f"Follow-up Response: {result2['message']}")
+```
+
+### JavaScript (Fetch API)
+
+```javascript
+const BASE_URL = 'https://huggingface.co/spaces/JatinAutonomousLabs/Research_AI_Assistant_API';
+
+// Check health
+async function checkHealth() {
+    const response = await fetch(`${BASE_URL}/api/health`);
+    return await response.json();
+}
+
+// Send chat message
+async function sendMessage(message, sessionId = null, userId = null, history = []) {
+    const payload = {
+        message: message,
+        session_id: sessionId,
+        user_id: userId || 'anonymous',
+        history: history
+    };
+    
+    const response = await fetch(`${BASE_URL}/api/chat`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(payload)
+    });
+    
+    if (!response.ok) {
+        const error = await response.json();
+        throw new Error(`API Error: ${response.status} - ${error.error || error.message}`);
+    }
+    
+    return await response.json();
+}
+
+// Example usage
+async function main() {
+    try {
+        // Check if API is ready
+        const health = await checkHealth();
+        console.log('API Status:', health);
+        
+        if (health.orchestrator_ready) {
+            // Send a message
+            const result = await sendMessage(
+                'What is machine learning?',
+                'my-session-123',
+                'user-456'
+            );
+            
+            console.log('Response:', result.message);
+            console.log('Reasoning:', result.reasoning);
+            
+            // Continue conversation
+            const result2 = await sendMessage(
+                'Can you explain neural networks?',
+                'my-session-123',
+                'user-456',
+                result.history
+            );
+            console.log('Follow-up Response:', result2.message);
+        }
+    } catch (error) {
+        console.error('Error:', error);
+    }
+}
+
+main();
+```
+
+### cURL
+
+```bash
+# Check health
+curl -X GET "https://huggingface.co/spaces/JatinAutonomousLabs/Research_AI_Assistant_API/api/health"
+
+# Send chat message
+curl -X POST "https://huggingface.co/spaces/JatinAutonomousLabs/Research_AI_Assistant_API/api/chat" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "What is machine learning?",
+    "session_id": "my-session-123",
+    "user_id": "user-456",
+    "history": []
+  }'
+
+# Continue conversation
+curl -X POST "https://huggingface.co/spaces/JatinAutonomousLabs/Research_AI_Assistant_API/api/chat" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "Can you explain neural networks?",
+    "session_id": "my-session-123",
+    "user_id": "user-456",
+    "history": [
+      ["What is machine learning?", "Machine learning is a subset of artificial intelligence..."]
+    ]
+  }'
+```
+
+### Node.js (Axios)
+
+```javascript
+const axios = require('axios');
+
+const BASE_URL = 'https://huggingface.co/spaces/JatinAutonomousLabs/Research_AI_Assistant_API';
+
+// Check health
+async function checkHealth() {
+    const response = await axios.get(`${BASE_URL}/api/health`);
+    return response.data;
+}
+
+// Send chat message
+async function sendMessage(message, sessionId = null, userId = null, history = []) {
+    try {
+        const response = await axios.post(`${BASE_URL}/api/chat`, {
+            message: message,
+            session_id: sessionId,
+            user_id: userId || 'anonymous',
+            history: history
+        }, {
+            headers: {
+                'Content-Type': 'application/json'
+            }
+        });
+        
+        return response.data;
+    } catch (error) {
+        if (error.response) {
+            throw new Error(`API Error: ${error.response.status} - ${error.response.data.error || error.response.data.message}`);
+        }
+        throw error;
+    }
+}
+
+// Example usage
+(async () => {
+    try {
+        const health = await checkHealth();
+        console.log('API Status:', health);
+        
+        if (health.orchestrator_ready) {
+            const result = await sendMessage(
+                'What is machine learning?',
+                'my-session-123',
+                'user-456'
+            );
+            
+            console.log('Response:', result.message);
+        }
+    } catch (error) {
+        console.error('Error:', error.message);
+    }
+})();
+```
+
+---
+
+## Error Handling
+
+### Common Error Responses
+
+#### 400 Bad Request
+
+**Missing Message:**
+```json
+{
+  "success": false,
+  "error": "Message is required"
+}
+```
+
+**Empty Message:**
+```json
+{
+  "success": false,
+  "error": "Message cannot be empty"
+}
+```
+
+**Message Too Long:**
+```json
+{
+  "success": false,
+  "error": "Message too long. Maximum length is 10000 characters"
+}
+```
+
+**Invalid Type:**
+```json
+{
+  "success": false,
+  "error": "Message must be a string"
+}
+```
+
+#### 503 Service Unavailable
+
+**Orchestrator Not Ready:**
+```json
+{
+  "success": false,
+  "error": "Orchestrator not ready",
+  "message": "AI system is initializing. Please try again in a moment."
+}
+```
+
+**Solution:** Wait a few seconds and retry, or check the `/api/health` endpoint.
+
+#### 500 Internal Server Error
+
+**Generic Error:**
+```json
+{
+  "success": false,
+  "error": "Error message here",
+  "message": "Error processing your request. Please try again."
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Session Management
+
+- **Use consistent session IDs** for maintaining conversation context
+- **Generate unique session IDs** per user conversation thread
+- **Include conversation history** in subsequent requests for better context
+
+```python
+# Good: Maintains context
+session_id = "user-123-session-1"
+history = []
+
+# First message
+result1 = send_message("What is AI?", session_id=session_id, history=history)
+history = result1['history']
+
+# Follow-up message (includes context)
+result2 = send_message("Can you explain more?", session_id=session_id, history=history)
+```
+
+### 2. Error Handling
+
+Always implement retry logic for 503 errors:
+
+```python
+import time
+
+def send_message_with_retry(message, max_retries=3, retry_delay=2):
+    for attempt in range(max_retries):
+        try:
+            result = send_message(message)
+            return result
+        except Exception as e:
+            if "503" in str(e) and attempt < max_retries - 1:
+                time.sleep(retry_delay)
+                continue
+            raise
+```
+
+### 3. Health Checks
+
+Check API health before sending requests:
+
+```python
+def is_api_ready():
+    try:
+        health = check_health()
+        return health.get("orchestrator_ready", False)
+    except:
+        return False
+
+if is_api_ready():
+    # Send request
+    result = send_message("Hello")
+else:
+    print("API is not ready yet")
+```
+
+### 4. Rate Limiting
+
+- **No explicit rate limits** are currently enforced
+- **Recommended:** Implement client-side rate limiting (e.g., 1 request per second)
+- **Consider:** Implementing request queuing for high-volume applications
+
+### 5. Message Length
+
+- **Maximum:** 10,000 characters per message
+- **Recommended:** Keep messages concise for faster processing
+- **For long content:** Split into multiple messages or summarize
+
+### 6. Context Management
+
+- **Include history** in requests to maintain conversation context
+- **Session IDs** help track conversations across multiple requests
+- **User IDs** enable personalization and user-specific context
+
+---
+
+## Integration Examples
+
+### React Component
+
+```jsx
+import React, { useState, useEffect } from 'react';
+
+const AIAssistant = () => {
+    const [message, setMessage] = useState('');
+    const [history, setHistory] = useState([]);
+    const [loading, setLoading] = useState(false);
+    const [sessionId] = useState(`session-${Date.now()}`);
+    
+    const sendMessage = async () => {
+        if (!message.trim()) return;
+        
+        setLoading(true);
+        try {
+            const response = await fetch('https://huggingface.co/spaces/JatinAutonomousLabs/Research_AI_Assistant_API/api/chat', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    message: message,
+                    session_id: sessionId,
+                    user_id: 'user-123',
+                    history: history
+                })
+            });
+            
+            const data = await response.json();
+            if (data.success) {
+                setHistory(data.history);
+                setMessage('');
+            }
+        } catch (error) {
+            console.error('Error:', error);
+        } finally {
+            setLoading(false);
+        }
+    };
+    
+    return (
+        <div>
+            <div className="chat-history">
+                {history.map(([user, assistant], idx) => (
+                    <div key={idx}>
+                        <div><strong>You:</strong> {user}</div>
+                        <div><strong>Assistant:</strong> {assistant}</div>
+                    </div>
+                ))}
+            </div>
+            <input
+                value={message}
+                onChange={(e) => setMessage(e.target.value)}
+                onKeyPress={(e) => e.key === 'Enter' && sendMessage()}
+                disabled={loading}
+            />
+            <button onClick={sendMessage} disabled={loading}>
+                {loading ? 'Sending...' : 'Send'}
+            </button>
+        </div>
+    );
+};
+```
+
+### Python CLI Tool
+
+```python
+#!/usr/bin/env python3
+import requests
+import sys
+
+BASE_URL = "https://huggingface.co/spaces/JatinAutonomousLabs/Research_AI_Assistant_API"
+
+class ChatCLI:
+    def __init__(self):
+        self.session_id = f"cli-session-{hash(__file__)}"
+        self.history = []
+    
+    def chat(self, message):
+        response = requests.post(
+            f"{BASE_URL}/api/chat",
+            json={
+                "message": message,
+                "session_id": self.session_id,
+                "user_id": "cli-user",
+                "history": self.history
+            }
+        )
+        
+        if response.status_code == 200:
+            data = response.json()
+            self.history = data['history']
+            return data['message']
+        else:
+            return f"Error: {response.status_code} - {response.text}"
+    
+    def run(self):
+        print("AI Assistant CLI (Type 'exit' to quit)")
+        print("=" * 50)
+        
+        while True:
+            user_input = input("\nYou: ").strip()
+            if user_input.lower() in ['exit', 'quit']:
+                break
+            
+            print("Assistant: ", end="", flush=True)
+            response = self.chat(user_input)
+            print(response)
+
+if __name__ == "__main__":
+    cli = ChatCLI()
+    cli.run()
+```
+
+---
+
+## Response Times
+
+- **Typical Response:** 2-10 seconds
+- **First Request:** May take longer due to model loading (10-30 seconds)
+- **Subsequent Requests:** Faster due to cached models (2-5 seconds)
+
+**Factors Affecting Response Time:**
+- Message length
+- Model loading (first request)
+- GPU availability
+- Concurrent requests
+
+---
+
+## Support
+
+For issues, questions, or contributions:
+- **Repository:** [GitHub Repository URL]
+- **Hugging Face Space:** [https://huggingface.co/spaces/JatinAutonomousLabs/Research_AI_Assistant_API](https://huggingface.co/spaces/JatinAutonomousLabs/Research_AI_Assistant_API)
+
+---
+
+## Changelog
+
+### Version 1.0 (Current)
+- Initial API release
+- Chat endpoint with context management
+- Health check endpoint
+- Local GPU model inference
+- CORS enabled for web integration
+
+---
+
+## License
+
+This API is provided as-is. Please refer to the main project README for license information.
+