API_ENDPOINT_VERIFICATION.md

# API Endpoint Verification Guide

## Overview

This document explains how to verify that the `api_name="safe_gpu_chat_handler"` endpoint is properly deployed and running.

## Implementation Status

✅ **Code Deployed**: The API endpoint registration code is present in `app.py`:
- Line 845: `api_name="safe_gpu_chat_handler"` is set on the `api_message.submit()` event
- Line 849: Log message confirms registration
- Lines 1899-1900, 2002-2003: Handler functions are initialized and set globally
- Lines 2073-2097: Verification logging on app startup

## Verification Methods

### 1. Check Application Logs

When the application starts, you should see these log messages:

```
============================================================
VERIFYING API ENDPOINTS
============================================================
✓ API is enabled in Gradio config: True
Registered API endpoints:
  - /api/safe_gpu_chat_handler (POST)
  - /api/new_session (POST)
  - /api/update_session_info (POST)
  ...
✓ API handler function initialized: True
  Handler type: function
============================================================
LAUNCHING GRADIO APP
============================================================
API endpoints available at: http://<host>:7860/api/
```

Additionally, during interface creation:
```
✓ API endpoint '/api/safe_gpu_chat_handler' registered with api_name
✓ GPU chat handler initialized and set as API handler
```
OR
```
✓ Non-GPU chat handler initialized and set as API handler
```

### 2. Use the Verification Script

Run the verification script to test the endpoint:

```bash
python verify_api_endpoint.py [base_url]
```

Example:
```bash
# Local testing
python verify_api_endpoint.py http://localhost:7860

# HuggingFace Spaces
python verify_api_endpoint.py https://jatinautonomouslabs-research-ai-assistant.hf.space
```

The script will:
- Check if Gradio API info is accessible
- Verify the endpoint is registered
- Test actual endpoint accessibility
- Return exit code 0 if successful

### 3. Manual HTTP Test

Test the endpoint directly using curl or HTTP client:

```bash
curl -X POST http://localhost:7860/api/safe_gpu_chat_handler \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      "test message",
      [],
      "Admin_J",
      "Session: test123 | User: Admin_J | Interactions: 0"
    ]
  }'
```

Expected responses:
- **200 OK**: Endpoint is working correctly
- **422 Validation Error**: Endpoint exists but validation failed (still confirms deployment)
- **404 Not Found**: Endpoint not registered

### 4. Check Gradio API Documentation

Visit the Gradio API documentation page:
- Local: `http://localhost:7860/docs` or `http://localhost:7860/api/docs`
- Spaces: `https://<your-space>.hf.space/docs`

Look for `/api/safe_gpu_chat_handler` in the list of available endpoints.

### 5. Inspect Gradio Config

If you have access to the running instance, check:

```python
import gradio as gr
# After demo is created
demo.config.api_open  # Should be True
demo.config.show_api  # Should be True
```

## Code Location Reference

| Component | File | Line(s) |
|-----------|------|---------|
| API Endpoint Registration | `app.py` | 838-849 |
| Handler Initialization (GPU) | `app.py` | 1899-1900 |
| Handler Initialization (Non-GPU) | `app.py` | 2002-2003 |
| Startup Verification | `app.py` | 2073-2097 |
| Global Handler Variable | `app.py` | 27-28 |

## Troubleshooting

### Issue: Endpoint not found (404)

**Check:**
1. Application logs show "API endpoint registered" message
2. `show_api=True` is set in `demo.launch()` (line 2108)
3. Handler function is initialized (check logs for handler type)

**Solution:**
- Ensure `api_name` parameter is correctly set on the submit event
- Verify the handler function is defined before the interface is created

### Issue: Handler function is None

**Check:**
1. Logs show handler initialization message
2. `_api_chat_handler_fn` is set after handlers are defined

**Solution:**
- Verify GPU availability check runs correctly
- Check that handler functions are defined (lines 1779-1997)

### Issue: Endpoint accessible but returns errors

**This is expected** - The endpoint is deployed correctly. The errors are validation or processing errors, not deployment issues.

## Expected Behavior

✅ **Deployed Successfully**:
- Application logs show registration messages
- HTTP requests to `/api/safe_gpu_chat_handler` return 200 or 422 (not 404)
- Verification script passes
- Handler function is not None

❌ **Not Deployed**:
- 404 errors on endpoint access
- Logs don't show registration messages
- Handler function is None

## Additional Notes

- The endpoint uses hidden Gradio components (visible=False) to avoid UI interference
- The handler automatically selects GPU or non-GPU handler based on availability
- Fallback to `process_message` ensures endpoint always works
- All API endpoints are registered with `api_name` parameters for REST access