GRADIO_API_CONFLICT_DIAGNOSIS.md

# Gradio API Endpoint Conflict Diagnosis Guide

## Overview

This document helps diagnose and resolve conflicts with Gradio API endpoints in the Research AI Assistant application.

## Current Setup

- **Framework**: Gradio (Python), NOT Express/Node.js
- **Port**: 7860 (configurable via `GRADIO_PORT` env var)
- **Host**: 0.0.0.0 (all interfaces)
- **API Enabled**: Yes (`show_api=True`)
- **Deployment**: Hugging Face Spaces / Local

## Common Conflict Scenarios

### 1. Port Conflicts

**Symptoms:**
- Error: "Address already in use"
- Application fails to start
- Port binding errors in logs

**Diagnosis:**
```bash
# Check if port 7860 is already in use
# Windows
netstat -ano | findstr :7860

# Linux/Mac
lsof -i :7860
# or
netstat -tulpn | grep 7860
```

**Solutions:**

**Option A: Change Gradio Port**
```python
# In app.py, modify demo.launch():
demo.launch(
    server_name="0.0.0.0",
    server_port=7861,  # Use different port
    show_api=True
)
```

**Option B: Use Environment Variable**
```bash
# Set before running
export GRADIO_PORT=7861
python app.py
```

**Option C: Kill Conflicting Process**
```bash
# Windows (find PID from netstat)
taskkill /PID <PID> /F

# Linux/Mac
kill -9 <PID>
```

---

### 2. Multiple Gradio Instances Running

**Symptoms:**
- Multiple instances competing for the same port
- Unpredictable endpoint routing
- Some endpoints work, others don't

**Diagnosis:**
Check for multiple Python processes:
```bash
# Windows
tasklist | findstr python

# Linux/Mac
ps aux | grep python | grep app.py
```

**Solution:**
Ensure only one instance is running:
```bash
# Kill all Python processes (use with caution!)
# Windows
taskkill /IM python.exe /F

# Linux/Mac
pkill -f app.py
```

---

### 3. API Endpoint Routing Conflicts

**Symptoms:**
- 404 errors on `/api/*` endpoints
- Endpoints return wrong responses
- API documentation not accessible at `/docs`

**Diagnosis:**

**Check 1: Verify API is Enabled**
```python
# Add to app.py after demo creation
print(f"API Open: {demo.config.api_open}")
print(f"Show API: {demo.config.show_api}")
```

**Check 2: Verify Endpoint Registration**
Look for this in logs:
```
✓ API endpoint '/api/safe_gpu_chat_handler' registered with api_name
✓ API handler function initialized: True
```

**Check 3: Test Endpoint Directly**
```bash
# Check if API docs are accessible
curl http://localhost:7860/docs

# Test endpoint
curl -X POST http://localhost:7860/api/safe_gpu_chat_handler \
  -H "Content-Type: application/json" \
  -d '{"data": ["test", [], "Admin_J", ""]}'
```

**Solutions:**

**Ensure API is Explicitly Enabled:**
```python
# In app.py (line 2109-2116)
demo.launch(
    server_name="0.0.0.0",
    server_port=7860,
    share=False,
    show_api=True,  # ✅ This must be True
    # ... other settings
)
```

**Verify Handler Function is Set:**
```python
# Check that _api_chat_handler_fn is not None
# This is set at lines 1899-1900 or 2002-2003 in app.py
```

---

### 4. CORS Issues (Cross-Origin Resource Sharing)

**Symptoms:**
- Browser console shows CORS errors
- API calls from external domains fail
- "Access-Control-Allow-Origin" errors

**Solutions:**

**Option A: Enable CORS in Gradio Launch**
```python
demo.launch(
    server_name="0.0.0.0",
    server_port=7860,
    show_api=True,
    # Add CORS configuration
    allowed_paths=["*"],  # Allow all paths (or specify)
    # Note: Gradio handles CORS automatically when show_api=True
)
```

**Option B: Use Gradio's Share Feature (for external access)**
```python
demo.launch(
    server_name="0.0.0.0",
    server_port=7860,
    share=True,  # Creates public Gradio link
    show_api=True
)
```

**Option C: Add CORS Headers Manually (if needed)**
```python
# If using FastAPI/Flask alongside Gradio, add CORS middleware
# But this app doesn't use FastAPI/Flask, so this shouldn't be needed
```

---

### 5. Hugging Face Spaces Deployment Conflicts

**Symptoms:**
- Works locally but not on HF Spaces
- Port conflicts in container
- API endpoints unavailable

**Solutions:**

**Check HF Spaces Configuration:**
1. Ensure `Dockerfile.hf` exposes correct port:
   ```dockerfile
   EXPOSE 7860
   ```

2. Verify `app.py` is the main entry point (check `README.md` for `sdk: gradio`)

3. Check HF Spaces logs for startup errors:
   - Go to your Space settings
   - View Logs tab
   - Look for "LAUNCHING GRADIO APP" message

**Common HF Spaces Issues:**
- Port 7860 is required (cannot be changed on HF Spaces)
- `server_name="0.0.0.0"` is correct
- `share=True` is automatically disabled on HF Spaces (they provide their own public URL)
- The code automatically detects HF Spaces and disables share to prevent warnings

---

### 6. API Endpoint Not Found (404)

**Symptoms:**
- `/api/safe_gpu_chat_handler` returns 404
- Endpoint not listed in `/docs`

**Diagnosis Checklist:**

1. ✅ **Handler Function Initialized?**
   ```python
   # Check logs for:
   # "✓ API handler function initialized: True"
   ```

2. ✅ **api_name Parameter Set?**
   ```python
   # In app.py line 845:
   api_message.submit(
       fn=api_chat_handler,
       inputs=[...],
       outputs=[...],
       api_name="safe_gpu_chat_handler"  # ✅ Must be present
   )
   ```

3. ✅ **show_api=True in launch()?**
   ```python
   demo.launch(show_api=True)  # ✅ Must be True
   ```

4. ✅ **App Restarted After Changes?**
   - Gradio requires restart to register new endpoints

**Solution:**
```python
# Verify in app.py:
# 1. Handler function exists (lines 804-836)
# 2. api_name is set (line 845)
# 3. show_api=True in launch (line 2113)
# 4. Restart the application
```

---

### 7. Gradio vs. FastAPI/Flask Conflicts (Not Applicable Here)

**Note:** This application uses **only Gradio** - there is no FastAPI or Flask server running.

If you're trying to add FastAPI alongside:
```python
# DON'T do this - Gradio handles routing
from fastapi import FastAPI
app = FastAPI()  # This would conflict!
```

Gradio's internal server handles all routing. You don't need Express, FastAPI, or Flask.

---

## Diagnostic Commands

### Complete Health Check

```bash
# 1. Check if app is running
curl http://localhost:7860/

# 2. Check API documentation
curl http://localhost:7860/docs

# 3. Check API info endpoint
curl http://localhost:7860/api_info

# 4. Test chat endpoint
curl -X POST http://localhost:7860/api/safe_gpu_chat_handler \
  -H "Content-Type: application/json" \
  -d '{"data": ["Hello", [], "Admin_J", ""]}'

# 5. Check logs for errors
# Windows
type app.log | findstr ERROR

# Linux/Mac
grep ERROR app.log
```

### Verify Endpoint Registration

```bash
# Use the provided verification script
python verify_api_endpoint.py http://localhost:7860
```

---

## Configuration Reference

### Current Launch Configuration (app.py:2109-2116)

```python
# Automatically detects HF Spaces and adjusts share setting
use_share = not SPACES_GPU_AVAILABLE  # False on HF Spaces, True locally
demo.launch(
    server_name="0.0.0.0",        # Accept connections from all interfaces
    server_port=7860,              # Default Gradio port
    share=use_share,               # Auto: True locally, False on HF Spaces
    show_api=True,                 # Enable API endpoints
    allowed_paths=[],              # Security: don't serve files
    blocked_paths=["/tmp", "/var", "/etc", "/home"]  # Block sensitive paths
)
```

### Environment Variables

```bash
# Port configuration (optional - defaults to 7860)
export GRADIO_PORT=7860

# Host configuration (optional - defaults to 0.0.0.0)
export GRADIO_HOST=0.0.0.0
```

---

## Troubleshooting Checklist

Use this checklist when experiencing issues:

- [ ] Port 7860 is not in use by another process
- [ ] Only one instance of `app.py` is running
- [ ] `show_api=True` is set in `demo.launch()`
- [ ] `api_name` parameter is set on the submit event
- [ ] Handler function (`_api_chat_handler_fn`) is not None
- [ ] Application logs show "API endpoint registered" message
- [ ] `/docs` endpoint is accessible
- [ ] `/api_info` endpoint returns JSON
- [ ] Application was restarted after code changes
- [ ] No CORS errors in browser console (if accessing from browser)
- [ ] HF Spaces configuration is correct (if deploying to Spaces)

---

## Quick Fixes

### Fix 1: Port Conflict
```bash
# Change port in app.py line 2111:
server_port=7861
```

### Fix 2: API Not Enabled
```python
# Ensure in app.py line 2113:
show_api=True  # Not False!
```

### Fix 3: Handler Not Set
```python
# Check lines 1899-1900 or 2002-2003:
# _api_chat_handler_fn must be assigned
```

### Fix 4: Restart Required
```bash
# Stop and restart the application
# Endpoints only register on startup
```

---

## Getting Help

If issues persist:

1. **Check Logs**: Review `app.log` for error messages
2. **Run Verification Script**: `python verify_api_endpoint.py`
3. **Test Manually**: Use curl commands above
4. **Check HF Spaces Logs**: If deploying to Hugging Face

---

## Summary

This is a **Gradio-only** application. There are no Express, FastAPI, or Flask servers. All routing is handled by Gradio's internal server. Common conflicts are:

1. **Port conflicts** → Change port or kill conflicting process
2. **API not enabled** → Set `show_api=True`
3. **Handler not initialized** → Check initialization code
4. **Multiple instances** → Ensure only one is running
5. **CORS issues** → Gradio handles automatically, but check if accessing from external domain

If you're experiencing specific errors, share:
- The exact error message
- Where you're running (local, HF Spaces, etc.)
- The endpoint that's failing
- Log output from app startup