FLASK_API_SETUP.md

# Flask API Setup Guide

## Overview

The Flask API (`flask_api.py`) provides a simple REST API interface to the Research AI Assistant orchestrator. It runs on port 5001, separate from Gradio (port 7860).

## Architecture

```
┌─────────────────┐
│  Express.js UI  │ Port 3000
│  (or other      │ - User interface
│   frontend)     │ - Session management
└────────┬────────┘
         │ HTTP POST /api/chat
         ↓
┌─────────────────┐
│  Flask API      │ Port 5001
│  flask_api.py   │ - REST endpoints
│                 │ - Imports from app.py
└────────┬────────┘ - Direct Python access
         │
┌─────────────────┐
│  Orchestrator   │ Python
│  (from app.py)  │ - AI agents
│                 │ - Context management
└─────────────────┘

┌─────────────────┐
│  Gradio UI      │ Port 7860
│  (optional)     │ - Alternative UI
│  app.py         │ - Can run alongside
└─────────────────┘
```

## Quick Start

### Automatic Start (Hugging Face Spaces)

**Flask API starts automatically** when you deploy to HF Spaces using `main.py` as the entry point.

No additional configuration needed - it runs in the background alongside Gradio.

### Manual Start (Local Development)

### Step 1: Install Dependencies

```bash
pip install flask flask-cors
```

Or install all requirements:
```bash
pip install -r requirements.txt
```

### Step 2: Start Flask API (Optional - Only if not using main.py)

```bash
# Default port 5001
python flask_api.py

# Or specify custom port
FLASK_PORT=5001 python flask_api.py
```

**Note:** If using `main.py` (HF Spaces entry point), Flask API starts automatically. Only run `flask_api.py` directly if you want Flask API without Gradio.

You should see:
```
INITIALIZING FLASK API ORCHESTRATOR
✓ AI ORCHESTRATOR READY (shared with Gradio)
Starting Flask API on port 5001
```

### Step 3: Test the API

```bash
# Health check
curl http://localhost:5001/health

# Chat endpoint
curl -X POST http://localhost:5001/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, how are you?",
    "session_id": "test-session-123",
    "user_id": "test-user"
  }'
```

## API Endpoints

### `GET /health`

Health check endpoint.

**Response:**
```json
{
  "status": "ok",
  "orchestrator_available": true,
  "service": "flask_api"
}
```

### `POST /api/chat`

Main chat endpoint for processing user messages.

**Request:**
```json
{
  "message": "What is machine learning?",
  "history": [],  // optional
  "session_id": "session-123",  // optional, auto-generated if not provided
  "user_id": "user-123"  // optional, defaults to "Admin_J"
}
```

**Response:**
```json
{
  "response": "Machine learning is...",
  "history": [
    {"role": "user", "content": "What is machine learning?"},
    {"role": "assistant", "content": "Machine learning is..."}
  ],
  "reasoning": {
    "chain_of_thought": {...},
    "confidence_calibration": {...}
  },
  "performance": {
    "processing_time": 1.23,
    "tokens_used": 456
  },
  "context": {
    "session_context": "...",
    "relevant_interactions": [...]
  },
  "session_id": "session-123",
  "skills": "<div>...</div>"  // HTML for skills display
}
```

### `GET /api/orchestrator/status`

Check if orchestrator is available.

**Response:**
```json
{
  "orchestrator_available": true,
  "orchestrator_type": "MVPOrchestrator"
}
```

## Configuration

### Environment Variables

```bash
# Flask configuration (for HF Spaces or manual start)
ENABLE_FLASK_API=true   # Enable/disable Flask API (default: true)
FLASK_PORT=5001          # Port for Flask API (default: 5001)
FLASK_HOST=0.0.0.0      # Host to bind to (default: 0.0.0.0)

# AI configuration (used by orchestrator)
HF_TOKEN=your_token_here  # Hugging Face token for API access
```

### Ports

- **Flask API**: 5001 (configurable via `FLASK_PORT`, starts automatically with `main.py`)
- **Gradio UI**: 7860 (separate, can run alongside)
- **Express.js** (external): 3000 (your frontend)

### Disable Flask API

To disable Flask API on HF Spaces:
```bash
ENABLE_FLASK_API=false
```

This prevents Flask from starting (only Gradio will run).

## Running with Gradio

### On Hugging Face Spaces (Automatic)

When using `main.py` as the entry point:
- **Gradio UI**: Runs on port 7860 (primary interface)
- **Flask API**: Starts automatically in background thread on port 5001
- Both run together, sharing the same orchestrator instance

### Local Development (Manual)

**Option 1: Use main.py (recommended - matches HF Spaces)**
```bash
python main.py
```
This starts both Gradio and Flask API automatically.

**Option 2: Run separately**
```bash
# Terminal 1: Flask API
python flask_api.py

# Terminal 2: Gradio UI
python app.py
```

Both can run simultaneously on different ports.

## Integration Examples

### Express.js Integration

See `EXPRESS_FLASK_INTEGRATION.md` for Express.js setup.

### Python Client

```python
import requests

def chat_with_flask(message, session_id=None):
    url = "http://localhost:5001/api/chat"
    data = {
        "message": message,
        "session_id": session_id or "python-client-session"
    }
    response = requests.post(url, json=data)
    return response.json()

# Usage
result = chat_with_flask("Hello, how are you?")
print(result["response"])
```

### JavaScript/Node.js Client

```javascript
const axios = require('axios');

async function chatWithFlask(message, sessionId = null) {
    const response = await axios.post('http://localhost:5001/api/chat', {
        message: message,
        session_id: sessionId || `node-client-session-${Date.now()}`
    });
    return response.data;
}

// Usage
chatWithFlask("Hello, how are you?")
    .then(result => console.log(result.response))
    .catch(error => console.error(error));
```

## Troubleshooting

### Issue: "Orchestrator not available"

**Check:**
1. Flask API logs show initialization errors
2. `HF_TOKEN` environment variable is set
3. All dependencies are installed

**Solution:**
```bash
# Check logs
# Look for "INITIALIZING AI ORCHESTRATOR" section

# Verify HF token
echo $HF_TOKEN

# Reinstall dependencies
pip install -r requirements.txt
```

### Issue: "Port already in use"

**Solution:**
```bash
# Use different port
FLASK_PORT=5002 python flask_api.py
```

### Issue: "Module not found"

**Check:**
1. You're in the correct directory (same as `app.py`)
2. All imports are available

**Solution:**
```bash
# Make sure you're in the project root
cd /path/to/Research_AI_Assistant

# Verify Python path
python -c "import app; print('✓ app.py importable')"
```

### Issue: "CORS errors"

**Solution:** Flask-CORS is enabled by default. If issues persist:

```python
# In flask_api.py, customize CORS:
from flask_cors import CORS
CORS(app, resources={r"/api/*": {"origins": "*"}})
```

## Advantages Over Gradio API

| Feature | Flask API | Gradio HTTP |
|---------|-----------|-------------|
| **Simplicity** | ✅ Simple JSON | ⚠️ Gradio-specific format |
| **Control** | ✅ Full control | ⚠️ Limited by Gradio |
| **Path issues** | ✅ None | ⚠️ Can have path problems |
| **Dependencies** | ✅ Just Flask | ⚠️ Requires Gradio client |
| **API design** | ✅ You design it | ⚠️ Gradio's design |
| **Startup** | ✅ Fast | ⚠️ Slower (Gradio overhead) |

## Production Deployment

### Using PM2 (Process Manager)

```bash
# Install PM2
npm install -g pm2

# Start Flask API
pm2 start flask_api.py --interpreter python3 --name flask-api

# Start Express (if using)
pm2 start server.js --name express

# View status
pm2 status
```

### Using systemd (Linux)

Create `/etc/systemd/system/flask-api.service`:
```ini
[Unit]
Description=Research AI Assistant Flask API
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/Research_AI_Assistant
Environment="FLASK_PORT=5001"
Environment="HF_TOKEN=your-token"
ExecStart=/usr/bin/python3 flask_api.py
Restart=always

[Install]
WantedBy=multi-user.target
```

Then:
```bash
sudo systemctl enable flask-api
sudo systemctl start flask-api
```

## Security Considerations

1. **CORS**: Currently allows all origins (`*`). In production, restrict to your frontend domain:
   ```python
   CORS(app, origins=["https://your-frontend.com"])
   ```

2. **Rate Limiting**: Consider adding rate limiting:
   ```bash
   pip install flask-limiter
   ```

3. **Authentication**: Add API keys or tokens for production:
   ```python
   @app.before_request
   def check_api_key():
       api_key = request.headers.get('X-API-Key')
       if api_key != os.getenv('API_KEY'):
           return jsonify({'error': 'Unauthorized'}), 401
   ```

## Summary

✅ **Simple**: Just Flask, no complex wrappers  
✅ **Flexible**: Your API design, your control  
✅ **Compatible**: Works alongside Gradio  
✅ **Standard**: Standard REST API pattern  
✅ **Fast**: Direct Python imports, no overhead  

Start Flask, integrate your frontend, done! 🚀