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

pip install flask flask-cors

Or install all requirements:

pip install -r requirements.txt

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

# 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

# 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:

{
  "status": "ok",
  "orchestrator_available": true,
  "service": "flask_api"
}

POST /api/chat

Main chat endpoint for processing user messages.

Request:

{
  "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:

{
  "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:

{
  "orchestrator_available": true,
  "orchestrator_type": "MVPOrchestrator"
}

Configuration

Environment Variables

# 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:

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)

python main.py

This starts both Gradio and Flask API automatically.

Option 2: Run separately

# 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

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

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:

# 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:

# 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:

# 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:

# 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)

# 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:

[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:

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:

   CORS(app, origins=["https://your-frontend.com"])
   

2. Rate Limiting: Consider adding rate limiting:

   pip install flask-limiter
   

3. Authentication: Add API keys or tokens for production:

   @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! 🚀