api endpoints for UI migration v8

GRADIO_API_CONFLICT_DIAGNOSIS.md

@@ -0,0 +1,414 @@
+# 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` creates an additional public link (HF Spaces also provides its own URL)
+
+---
+
+### 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
+demo.launch(
+    server_name="0.0.0.0",        # Accept connections from all interfaces
+    server_port=7860,              # Default Gradio port
+    share=True,                    # Creates public Gradio link for external access
+    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
+

QUICK_LOG_CHECK.md

@@ -0,0 +1,99 @@
+# Quick Log Check Guide - API Endpoint Deployment
+
+## What to Look For
+
+When the application starts successfully, you should see these log messages **in order**:
+
+### 1. Initial Setup (Early in startup)
+```
+============================================================
+STARTING APP
+============================================================
+```
+
+### 2. Interface Creation
+```
+✓ Interface created
+Orchestrator available: True (or False)
+```
+
+### 3. **API Endpoint Registration** ⭐ KEY CHECKPOINT
+```
+✓ API endpoint '/api/safe_gpu_chat_handler' registered with api_name
+```
+
+### 4. Handler Initialization ⭐ KEY CHECKPOINT
+Either:
+```
+✓ GPU chat handler initialized and set as API handler
+```
+OR
+```
+✓ Non-GPU chat handler initialized and set as API handler
+```
+
+### 5. Startup Verification ⭐ KEY CHECKPOINT
+```
+============================================================
+VERIFYING API ENDPOINTS
+============================================================
+✓ API is enabled in Gradio config: True
+Registered API endpoints:
+  - /api/safe_gpu_chat_handler (POST)
+  - /api/new_session (POST)
+  ...
+✓ API handler function initialized: True
+  Handler type: function
+```
+
+### 6. Application Launch
+```
+============================================================
+LAUNCHING GRADIO APP
+============================================================
+API endpoints available at: http://<host>:7860/api/
+```
+
+## Verification Checklist
+
+- [ ] See "API endpoint '/api/safe_gpu_chat_handler' registered with api_name"
+- [ ] See handler initialization message (GPU or Non-GPU)
+- [ ] See "VERIFYING API ENDPOINTS" section
+- [ ] See "API handler function initialized: True"
+- [ ] See "API endpoints available at: http://<host>:7860/api/"
+
+## If Logs Show Different Messages
+
+### Missing "API endpoint registered" message
+**Problem**: Endpoint might not be registered  
+**Action**: Check if `api_name="safe_gpu_chat_handler"` is in the code (line 845)
+
+### Missing handler initialization
+**Problem**: Handler function might not be set  
+**Action**: Check GPU availability and handler function definition
+
+### Handler function initialized: False
+**Problem**: `_api_chat_handler_fn` is None  
+**Action**: Check if handlers are defined before interface creation
+
+## Current Logs Analysis
+
+Based on your logs:
+- ✅ Application is starting ("starting up user application")
+- ⏳ Need to check for Python/Gradio app logs
+- ⏳ Need to see if API registration messages appear
+
+**Next Steps**: Wait for the Python application to fully start and check for the messages above.
+
+## Quick Test
+
+Once you see the "LAUNCHING GRADIO APP" message, the endpoint should be accessible. You can test with:
+
+```bash
+curl -X POST https://<your-space-url>/api/safe_gpu_chat_handler \
+  -H "Content-Type: application/json" \
+  -d '{"data": ["test", [], "Admin_J", "Session: test | User: Admin_J | Interactions: 0"]}'
+```
+
+Expected: Response (200 or 422 = endpoint exists, 404 = not deployed)
+

app.py

@@ -2106,10 +2106,11 @@ if __name__ == "__main__":
     logger.info("LAUNCHING GRADIO APP")
     logger.info("=" * 60)
     logger.info("API endpoints available at: http://<host>:7860/api/")
+    logger.info("Creating public Gradio share link for external access...")
     demo.launch(
         server_name="0.0.0.0",
         server_port=7860,
-        share=False,
+        share=True,  # Creates public Gradio link for external access
         show_api=True,  # Explicitly enable API (recommended for API access)
         allowed_paths=[],  # Empty list = don't serve any files (prevents file URLs)
         blocked_paths=["/tmp", "/var", "/etc", "/home"]  # Explicitly block sensitive paths (extra security)

main.py

@@ -172,7 +172,7 @@ def main():
     launch_config = {
         'server_name': '0.0.0.0',
         'server_port': 7860,
-        'share': False,
+        'share': True,  # Creates public Gradio link for external access
         'debug': False
     }