api endpoints for UI migration v2

API_DOCUMENTATION.md

@@ -0,0 +1,1257 @@
+# Research AI Assistant - API Documentation
+
+**Version:** 1.0.0  
+**Base URL:** `https://huggingface.co/spaces/JatinAutonomousLabs/Research_AI_Assistant`  
+**API Type:** Gradio Client API  
+**Last Updated:** December 2024
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Getting Started](#getting-started)
+3. [Authentication](#authentication)
+4. [API Endpoints](#api-endpoints)
+5. [Error Handling](#error-handling)
+6. [Code Examples](#code-examples)
+7. [Integration Guide](#integration-guide)
+8. [Testing](#testing)
+9. [Rate Limits & Best Practices](#rate-limits--best-practices)
+10. [Support & Troubleshooting](#support--troubleshooting)
+
+---
+
+## Overview
+
+The Research AI Assistant provides a RESTful-like API interface through Gradio's client library. All endpoints are accessible via the `gradio_client` Python package or HTTP requests.
+
+### Key Features
+
+- **Chat Interface**: Interactive conversation with AI assistant
+- **Session Management**: Create and manage conversation sessions
+- **Context Control**: Toggle between fresh and relevant context modes
+- **Preferences**: Save and manage user preferences
+- **Settings Control**: Toggle UI settings panel
+
+### Response Format
+
+All endpoints return data in standardized formats:
+- **Chat endpoints**: Return tuples matching Gradio component outputs
+- **Other endpoints**: Return strings or dictionaries
+- **Errors**: Return standardized error messages with metadata
+
+---
+
+## Getting Started
+
+### Installation
+
+```bash
+pip install gradio_client
+```
+
+### Basic Setup
+
+```python
+from gradio_client import Client
+
+# Initialize client
+client = Client("JatinAutonomousLabs/Research_AI_Assistant")
+
+# Or for private spaces (requires HF token)
+client = Client(
+    "JatinAutonomousLabs/Research_AI_Assistant",
+    hf_token="your_hf_token_here"
+)
+```
+
+---
+
+## Authentication
+
+### Public Space Access
+
+Public spaces require no authentication:
+
+```python
+client = Client("JatinAutonomousLabs/Research_AI_Assistant")
+```
+
+### Private Space Access
+
+For private spaces, pass your Hugging Face token:
+
+```python
+client = Client(
+    "JatinAutonomousLabs/Research_AI_Assistant",
+    hf_token=os.getenv("HF_TOKEN")
+)
+```
+
+### Token Management
+
+1. Get token from: https://huggingface.co/settings/tokens
+2. Store securely (environment variables recommended)
+3. Never commit tokens to version control
+
+---
+
+## API Endpoints
+
+### 1. Chat Handler - `/safe_gpu_chat_handler`
+
+Process user messages and get AI responses.
+
+#### Endpoint Details
+
+- **API Name:** `/safe_gpu_chat_handler`
+- **Method:** POST (via Gradio client)
+- **Description:** Main chat interface that processes user messages and returns AI responses with metadata
+
+#### Request Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `message` | `str` | Yes | - | User message (max 10,000 characters) |
+| `history` | `list[dict]` | No | `[]` | Chat history in Gradio format |
+| `user_id` | `Literal[str]` | No | `"Test_Any"` | User identifier: `'Admin_J'`, `'Dev_K'`, `'Dev_H'`, `'Dev_A'`, `'Test_Any'` |
+| `session_text` | `str` | No | `"Session: ... \| User: ... \| Interactions: 0"` | Session information string |
+
+#### Response Structure
+
+Returns a tuple of **7 elements**:
+
+```python
+(
+    chatbot_history,      # list[dict] - Updated chat history
+    message_input,        # str - Empty string (cleared after send)
+    reasoning_data,       # dict - Chain of thought and reasoning
+    performance_data,    # dict - Agent trace, token count, timing
+    context_data,        # dict - Session context, interaction ID
+    session_info,        # str - Updated session information
+    skills_html          # str - HTML for identified skills display
+)
+```
+
+#### Response Format Details
+
+**1. `chatbot_history` (list[dict])**
+```python
+[
+    {
+        "role": "user",
+        "content": "What is machine learning?"
+    },
+    {
+        "role": "assistant",
+        "content": "Machine learning is a subset of artificial intelligence..."
+    }
+]
+```
+
+**2. `reasoning_data` (dict)**
+```python
+{
+    "chain_of_thought": {
+        "step_1": {
+            "hypothesis": "User intent classification",
+            "evidence": ["Keywords detected", "Context analyzed"],
+            "confidence": 0.85,
+            "reasoning": "Intent identified as information_request"
+        }
+    },
+    "confidence_calibration": {
+        "overall_confidence": 0.85,
+        "calibration_method": "temperature_scaling"
+    }
+}
+```
+
+**3. `performance_data` (dict)**
+```python
+{
+    "agent_trace": [
+        {"agent": "intent_recognition", "duration": 0.234, "status": "success"},
+        {"agent": "response_synthesis", "duration": 1.456, "status": "success"}
+    ],
+    "token_count": 1250,
+    "processing_time": 2.34,
+    "confidence_score": 0.85,
+    "agents_used": ["intent_recognition", "response_synthesis"]
+}
+```
+
+**4. `context_data` (dict)**
+```python
+{
+    "interaction_id": "uuid-string",
+    "session_id": "abc12345",
+    "timestamp": "2024-12-28T10:30:00",
+    "warnings": [],
+    "context_mode": "relevant"
+}
+```
+
+**5. `session_info` (str)**
+```python
+"Session: abc12345 | User: Test_Any | Interactions: 5"
+```
+
+**6. `skills_html` (str)**
+```html
+"<div class='skills-header'>🎯 Relevant Skills:</div>
+ <span class='skill-tag high-confidence'>Machine Learning</span>
+ <span class='skill-tag medium-confidence'>Python</span>"
+```
+
+#### Code Example
+
+```python
+from gradio_client import Client
+
+client = Client("JatinAutonomousLabs/Research_AI_Assistant")
+
+# Make chat request
+result = client.predict(
+    message="Explain quantum computing in simple terms",
+    history=[],
+    user_id="Test_Any",
+    session_text="Session: abc12345 | User: Test_Any | Interactions: 0",
+    api_name="/safe_gpu_chat_handler"
+)
+
+# Unpack results
+chatbot_history, message_input, reasoning, performance, context, session_info, skills = result
+
+# Access response
+latest_message = chatbot_history[-1]["content"]
+print(f"Assistant: {latest_message}")
+
+# Access metadata
+processing_time = performance.get("processing_time", 0)
+print(f"Response time: {processing_time:.2f}s")
+```
+
+#### Validation Rules
+
+- **Message**: Must be non-empty string, max 10,000 characters
+- **User ID**: Must be one of: `Admin_J`, `Dev_K`, `Dev_H`, `Dev_A`, `Test_Any`
+- **History**: Must be list (empty list if None)
+- **Session Text**: Format: `"Session: <8-char-id> | User: <user_id> | Interactions: <count>"`
+
+#### Error Responses
+
+If validation fails or processing errors occur:
+
+```python
+{
+    "error": "Message cannot be empty"  # or other error message
+}
+```
+
+Error responses maintain the same tuple structure with error information in metadata fields.
+
+---
+
+### 2. New Session - `/new_session`
+
+Create a new conversation session.
+
+#### Endpoint Details
+
+- **API Name:** `/new_session`
+- **Method:** POST (via Gradio client)
+- **Description:** Creates a new session ID and initializes it in the database
+
+#### Request Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `user_id` | `Literal[str]` | No | `"Test_Any"` | User identifier |
+
+#### Response
+
+Returns a single string:
+
+```python
+"Session: abc12345 | User: Test_Any | Interactions: 0"
+```
+
+#### Code Example
+
+```python
+result = client.predict(
+    user_id="Admin_J",
+    api_name="/new_session"
+)
+
+session_info = result
+print(session_info)  # "Session: xyz67890 | User: Admin_J | Interactions: 0"
+```
+
+#### Behavior
+
+- Generates new 8-character hexadecimal session ID
+- Validates and normalizes user_id
+- Initializes session in database via context_manager
+- Returns formatted session info string
+- Continues execution even if database initialization fails
+
+---
+
+### 3. Update Session Info - `/update_session_info`
+
+Update session metadata (typically called when user changes).
+
+#### Endpoint Details
+
+- **API Name:** `/update_session_info`
+- **Method:** POST (via Gradio client)
+- **Description:** Updates session information, typically when user_id changes
+
+#### Request Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `user_id` | `Literal[str]` | No | `"Test_Any"` | New user identifier |
+| `session_text` | `str` | No | `"Session: ... \| User: ... \| Interactions: 0"` | Current session text |
+
+#### Response
+
+Returns updated session info string:
+
+```python
+"Session: abc12345 | User: Admin_J | Interactions: 5"
+```
+
+#### Code Example
+
+```python
+result = client.predict(
+    user_id="Admin_J",
+    session_text="Session: abc12345 | User: Test_Any | Interactions: 3",
+    api_name="/update_session_info"
+)
+
+updated_session = result
+print(updated_session)  # "Session: abc12345 | User: Admin_J | Interactions: 3"
+```
+
+#### Important Notes
+
+- **Session Continuity**: Never generates new session ID
+- **Interaction Count**: Fetches actual count from database
+- **Preservation**: Returns original session_text if parsing fails
+
+---
+
+### 4. Toggle Settings - `/toggle_settings`
+
+Toggle the settings panel visibility.
+
+#### Endpoint Details
+
+- **API Name:** `/toggle_settings`
+- **Method:** POST (via Gradio client)
+- **Description:** Toggles the settings panel visibility state
+
+#### Request Parameters
+
+None required.
+
+#### Response
+
+Returns Gradio update object (handled internally by client).
+
+#### Code Example
+
+```python
+client.predict(
+    api_name="/toggle_settings"
+)
+```
+
+#### Behavior
+
+- Uses global state tracking (`_settings_panel_visible`)
+- Toggles between visible/hidden states
+- Falls back to visible on error
+
+---
+
+### 5. Toggle Settings from Nav - `/toggle_settings_from_nav`
+
+Toggle settings panel from mobile navigation.
+
+#### Endpoint Details
+
+- **API Name:** `/toggle_settings_from_nav`
+- **Method:** POST (via Gradio client)
+- **Description:** Same as `/toggle_settings` but triggered from mobile nav
+
+#### Request Parameters
+
+None required.
+
+#### Response
+
+Returns Gradio update object.
+
+#### Code Example
+
+```python
+client.predict(
+    api_name="/toggle_settings_from_nav"
+)
+```
+
+---
+
+### 6. Handle Mode Change - `/handle_mode_change`
+
+Change context mode (Fresh or Relevant).
+
+#### Endpoint Details
+
+- **API Name:** `/handle_mode_change`
+- **Method:** POST (via Gradio client)
+- **Description:** Updates the context mode for the current session
+
+#### Request Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `mode` | `Literal['fresh', 'relevant']` | Yes | `"fresh"` | Context mode: `'fresh'` = no user context, `'relevant'` = only relevant context |
+| `session_id_text` | `str` | Yes | `"Session: ... \| User: ... \| Interactions: 0"` | Session information string |
+
+#### Response
+
+Returns status message string:
+
+```python
+"*Current: Fresh Context*"  # or "*Current: Relevant Context*"
+```
+
+#### Code Example
+
+```python
+result = client.predict(
+    mode="relevant",
+    session_id_text="Session: abc12345 | User: Test_Any | Interactions: 3",
+    api_name="/handle_mode_change"
+)
+
+status = result
+print(status)  # "*Current: Relevant Context*"
+```
+
+#### Mode Descriptions
+
+- **`fresh`**: Each response generated without user context from previous sessions
+- **`relevant`**: System identifies and includes only relevant past discussions related to current topic
+
+#### Validation
+
+- Invalid mode values default to `'fresh'`
+- Returns error message if session ID extraction fails
+
+---
+
+### 7. Save Preferences - `/save_preferences`
+
+Save user preferences to database.
+
+#### Endpoint Details
+
+- **API Name:** `/save_preferences`
+- **Method:** POST (via Gradio client)
+- **Description:** Saves user preferences with database persistence
+
+#### Request Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `param_0` | `bool` | No | `True` | Show reasoning chain |
+| `param_1` | `bool` | No | `False` | Show agent execution trace |
+| `param_2` | `Literal['Fast', 'Balanced', 'Thorough']` | No | `"Balanced"` | Response speed preference |
+| `param_3` | `bool` | No | `True` | Enable context caching |
+
+#### Response
+
+Returns status dictionary:
+
+```python
+{
+    "status": "success",  # or "partial" if cache-only
+    "message": "Preferences saved"
+}
+```
+
+#### Code Example
+
+```python
+result = client.predict(
+    param_0=True,      # show_reasoning
+    param_1=False,     # show_agent_trace
+    param_2="Fast",    # response_speed
+    param_3=True,      # cache_enabled
+    api_name="/save_preferences"
+)
+
+status = result["status"]
+message = result["message"]
+```
+
+#### Preferences Schema
+
+Preferences are stored as JSON:
+
+```json
+{
+    "show_reasoning": true,
+    "show_agent_trace": false,
+    "response_speed": "Fast",
+    "cache_enabled": true,
+    "timestamp": "2024-12-28T10:30:00.123456"
+}
+```
+
+#### Storage
+
+- **Primary**: Database table `user_preferences`
+- **Fallback**: In-memory cache (if database unavailable)
+- **Scope**: Session-specific or global (if no session_id)
+
+---
+
+## Error Handling
+
+### Error Response Format
+
+All endpoints return standardized error information:
+
+```python
+# Chat endpoints - errors in metadata
+{
+    "error": "Error message here",
+    "type": "validation_error" | "processing_error" | "database_error"
+}
+
+# Other endpoints - error strings or error dictionaries
+"*Error: Invalid session information*"
+```
+
+### Error Types
+
+#### 1. Validation Errors
+
+**Cause**: Invalid input parameters  
+**HTTP Equivalent**: 400 Bad Request  
+**Recovery**: Fix input parameters and retry
+
+```python
+# Example
+{
+    "error": "Message cannot be empty",
+    "type": "validation_error"
+}
+```
+
+#### 2. Processing Errors
+
+**Cause**: Internal processing failures  
+**HTTP Equivalent**: 500 Internal Server Error  
+**Recovery**: Retry request, check system status
+
+```python
+# Example
+{
+    "error": "Processing error: LLM API timeout",
+    "type": "processing_error"
+}
+```
+
+#### 3. Database Errors
+
+**Cause**: Database connection or query failures  
+**HTTP Equivalent**: 503 Service Unavailable  
+**Recovery**: System falls back to in-memory cache, retry if needed
+
+```python
+# Example
+{
+    "error": "Failed to save preferences to database",
+    "type": "database_error",
+    "fallback": "saved_to_cache"
+}
+```
+
+### Error Handling Best Practices
+
+```python
+from gradio_client import Client
+import time
+
+client = Client("JatinAutonomousLabs/Research_AI_Assistant")
+
+def safe_chat_request(message, history, max_retries=3):
+    """Chat request with retry logic"""
+    for attempt in range(max_retries):
+        try:
+            result = client.predict(
+                message=message,
+                history=history,
+                user_id="Test_Any",
+                session_text="Session: abc12345 | User: Test_Any | Interactions: 0",
+                api_name="/safe_gpu_chat_handler"
+            )
+            
+            # Check for errors in metadata
+            if isinstance(result[3], dict) and "error" in result[3]:
+                error_msg = result[3]["error"]
+                if "timeout" in error_msg.lower() and attempt < max_retries - 1:
+                    time.sleep(2 ** attempt)  # Exponential backoff
+                    continue
+                raise Exception(error_msg)
+            
+            return result
+            
+        except Exception as e:
+            if attempt == max_retries - 1:
+                raise
+            time.sleep(2 ** attempt)
+    
+    raise Exception("Max retries exceeded")
+```
+
+---
+
+## Code Examples
+
+### Complete Integration Example
+
+```python
+from gradio_client import Client
+import os
+from typing import List, Dict, Optional
+
+class ResearchAIAssistant:
+    """Wrapper class for Research AI Assistant API"""
+    
+    def __init__(self, hf_token: Optional[str] = None):
+        """Initialize client"""
+        self.client = Client(
+            "JatinAutonomousLabs/Research_AI_Assistant",
+            hf_token=hf_token or os.getenv("HF_TOKEN")
+        )
+        self.session_info = None
+        self.user_id = "Test_Any"
+        self.chat_history = []
+    
+    def create_session(self, user_id: str = "Test_Any") -> str:
+        """Create new session"""
+        self.user_id = user_id
+        self.session_info = self.client.predict(
+            user_id=user_id,
+            api_name="/new_session"
+        )
+        self.chat_history = []
+        return self.session_info
+    
+    def send_message(self, message: str) -> Dict:
+        """Send message and get response"""
+        if not self.session_info:
+            self.create_session()
+        
+        result = self.client.predict(
+            message=message,
+            history=self.chat_history,
+            user_id=self.user_id,
+            session_text=self.session_info,
+            api_name="/safe_gpu_chat_handler"
+        )
+        
+        # Unpack results
+        history, _, reasoning, performance, context, session_info, skills = result
+        
+        # Update state
+        self.chat_history = history
+        self.session_info = session_info
+        
+        return {
+            "response": history[-1]["content"] if history else "",
+            "reasoning": reasoning,
+            "performance": performance,
+            "context": context,
+            "skills": skills
+        }
+    
+    def set_context_mode(self, mode: str) -> str:
+        """Change context mode"""
+        if not self.session_info:
+            raise ValueError("No active session")
+        
+        result = self.client.predict(
+            mode=mode,
+            session_id_text=self.session_info,
+            api_name="/handle_mode_change"
+        )
+        
+        return result
+    
+    def save_preferences(self, **preferences) -> Dict:
+        """Save user preferences"""
+        return self.client.predict(
+            param_0=preferences.get("show_reasoning", True),
+            param_1=preferences.get("show_agent_trace", False),
+            param_2=preferences.get("response_speed", "Balanced"),
+            param_3=preferences.get("cache_enabled", True),
+            api_name="/save_preferences"
+        )
+
+# Usage
+assistant = ResearchAIAssistant(hf_token="your_token")
+
+# Create session
+session = assistant.create_session(user_id="Admin_J")
+print(f"Session created: {session}")
+
+# Set context mode
+assistant.set_context_mode("relevant")
+print("Context mode set to relevant")
+
+# Send message
+response = assistant.send_message("Explain machine learning")
+print(f"Response: {response['response']}")
+print(f"Processing time: {response['performance'].get('processing_time', 0):.2f}s")
+
+# Save preferences
+assistant.save_preferences(
+    show_reasoning=True,
+    response_speed="Fast",
+    cache_enabled=True
+)
+```
+
+### Async Integration Example
+
+```python
+import asyncio
+from gradio_client import Client
+
+async def async_chat_request(message: str, history: List, session_text: str):
+    """Async wrapper for chat requests"""
+    loop = asyncio.get_event_loop()
+    
+    client = Client("JatinAutonomousLabs/Research_AI_Assistant")
+    
+    # Run in thread pool to avoid blocking
+    result = await loop.run_in_executor(
+        None,
+        lambda: client.predict(
+            message=message,
+            history=history,
+            user_id="Test_Any",
+            session_text=session_text,
+            api_name="/safe_gpu_chat_handler"
+        )
+    )
+    
+    return result
+
+# Usage
+async def main():
+    result = await async_chat_request(
+        message="Hello",
+        history=[],
+        session_text="Session: abc12345 | User: Test_Any | Interactions: 0"
+    )
+    print(result[0][-1]["content"])
+
+asyncio.run(main())
+```
+
+---
+
+## Integration Guide
+
+### Step 1: Install Dependencies
+
+```bash
+pip install gradio_client requests
+```
+
+### Step 2: Initialize Client
+
+```python
+from gradio_client import Client
+
+client = Client("JatinAutonomousLabs/Research_AI_Assistant")
+```
+
+### Step 3: Create Session
+
+```python
+session_info = client.predict(
+    user_id="Test_Any",
+    api_name="/new_session"
+)
+```
+
+### Step 4: Send Messages
+
+```python
+result = client.predict(
+    message="Your question here",
+    history=[],
+    user_id="Test_Any",
+    session_text=session_info,
+    api_name="/safe_gpu_chat_handler"
+)
+
+chatbot_history, _, reasoning, performance, context, session_info, skills = result
+```
+
+### Step 5: Handle Context Mode
+
+```python
+# Switch to relevant context mode
+client.predict(
+    mode="relevant",
+    session_id_text=session_info,
+    api_name="/handle_mode_change"
+)
+```
+
+### Step 6: Save Preferences
+
+```python
+client.predict(
+    param_0=True,
+    param_1=False,
+    param_2="Balanced",
+    param_3=True,
+    api_name="/save_preferences"
+)
+```
+
+---
+
+## Testing
+
+### Unit Test Example
+
+```python
+import unittest
+from gradio_client import Client
+
+class TestResearchAIAssistant(unittest.TestCase):
+    
+    def setUp(self):
+        self.client = Client("JatinAutonomousLabs/Research_AI_Assistant")
+        self.session_info = None
+    
+    def test_create_session(self):
+        """Test session creation"""
+        result = self.client.predict(
+            user_id="Test_Any",
+            api_name="/new_session"
+        )
+        self.assertIsInstance(result, str)
+        self.assertIn("Session:", result)
+        self.session_info = result
+    
+    def test_chat_message(self):
+        """Test chat message processing"""
+        if not self.session_info:
+            self.test_create_session()
+        
+        result = self.client.predict(
+            message="Hello",
+            history=[],
+            user_id="Test_Any",
+            session_text=self.session_info,
+            api_name="/safe_gpu_chat_handler"
+        )
+        
+        self.assertEqual(len(result), 7)
+        self.assertIsInstance(result[0], list)  # history
+        self.assertIsInstance(result[2], dict)   # reasoning
+    
+    def test_context_mode_change(self):
+        """Test context mode change"""
+        if not self.session_info:
+            self.test_create_session()
+        
+        result = self.client.predict(
+            mode="relevant",
+            session_id_text=self.session_info,
+            api_name="/handle_mode_change"
+        )
+        
+        self.assertIn("Context", result)
+
+if __name__ == '__main__':
+    unittest.main()
+```
+
+### Integration Test Example
+
+```python
+def test_full_conversation_flow():
+    """Test complete conversation flow"""
+    client = Client("JatinAutonomousLabs/Research_AI_Assistant")
+    
+    # 1. Create session
+    session = client.predict(user_id="Test_Any", api_name="/new_session")
+    assert "Session:" in session
+    
+    # 2. Set context mode
+    client.predict(mode="relevant", session_id_text=session, api_name="/handle_mode_change")
+    
+    # 3. Send messages
+    history = []
+    for message in ["Hello", "What is AI?", "Explain further"]:
+        result = client.predict(
+            message=message,
+            history=history,
+            user_id="Test_Any",
+            session_text=session,
+            api_name="/safe_gpu_chat_handler"
+        )
+        history = result[0]
+        session = result[5]  # Updated session info
+    
+    # 4. Verify conversation context
+    assert len(history) == 6  # 3 user + 3 assistant messages
+    
+    # 5. Save preferences
+    prefs = client.predict(
+        param_0=True,
+        param_1=False,
+        param_2="Fast",
+        param_3=True,
+        api_name="/save_preferences"
+    )
+    assert prefs["status"] in ["success", "partial"]
+    
+    print("✅ All integration tests passed")
+```
+
+---
+
+## Rate Limits & Best Practices
+
+### Rate Limits
+
+Currently, there are **no explicit rate limits** enforced. However, best practices:
+
+- **Chat Requests**: Limit to 1-2 requests per second per session
+- **Session Creation**: No strict limit, but avoid rapid session creation
+- **Preference Updates**: Limit to reasonable frequency (not per-request)
+
+### Best Practices
+
+#### 1. Session Management
+
+```python
+# ✅ Good: Reuse sessions
+session = create_session()
+for message in messages:
+    send_message(message, session)
+
+# ❌ Bad: Create new session for each message
+for message in messages:
+    session = create_session()  # Don't do this
+    send_message(message, session)
+```
+
+#### 2. Error Handling
+
+```python
+# ✅ Good: Handle errors gracefully
+try:
+    result = send_message(message)
+except Exception as e:
+    logger.error(f"Request failed: {e}")
+    # Implement retry or fallback
+
+# ❌ Bad: Ignore errors
+result = send_message(message)  # No error handling
+```
+
+#### 3. Context Mode
+
+```python
+# ✅ Good: Set mode once at session start
+set_context_mode("relevant")  # Once per session
+send_message("Question 1")
+send_message("Question 2")  # Mode persists
+
+# ❌ Bad: Change mode frequently
+set_context_mode("fresh")
+send_message("Q1")
+set_context_mode("relevant")  # Unnecessary switching
+send_message("Q2")
+```
+
+#### 4. Message Length
+
+```python
+# ✅ Good: Reasonable message length
+message = "Your question here"  # < 1000 chars typically
+
+# ❌ Bad: Extremely long messages
+message = "A" * 10000  # Max allowed but not recommended
+```
+
+---
+
+## Support & Troubleshooting
+
+### Common Issues
+
+#### 1. Connection Errors
+
+**Symptom**: `ConnectionError` or timeout  
+**Solution**:
+```python
+# Add retry logic
+import time
+max_retries = 3
+for attempt in range(max_retries):
+    try:
+        result = client.predict(...)
+        break
+    except Exception as e:
+        if attempt < max_retries - 1:
+            time.sleep(2 ** attempt)
+        else:
+            raise
+```
+
+#### 2. Invalid Session ID
+
+**Symptom**: `ValueError: Could not extract session_id`  
+**Solution**: Ensure session_text format is correct:
+```
+"Session: abc12345 | User: Test_Any | Interactions: 0"
+```
+
+#### 3. Empty Responses
+
+**Symptom**: Response tuple contains empty strings  
+**Possible Causes**:
+- LLM API timeout
+- Invalid message format
+- System overload
+
+**Solution**: Check `performance_data` for error information
+
+#### 4. Preferences Not Saving
+
+**Symptom**: Preferences return "partial" status  
+**Cause**: Database unavailable, using cache fallback  
+**Solution**: Preferences still work via cache, database will sync when available
+
+### Debugging Tips
+
+#### Enable Detailed Logging
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+# Client will show detailed request/response logs
+```
+
+#### Check Response Metadata
+
+```python
+result = client.predict(...)
+reasoning = result[2]  # Check for errors
+performance = result[3]  # Check processing info
+context = result[4]  # Check session context
+```
+
+#### Validate Session Info
+
+```python
+session_info = "Session: abc12345 | User: Test_Any | Interactions: 0"
+
+# Validate format
+import re
+match = re.search(r'Session: ([a-f0-9]{8})', session_info)
+if not match:
+    raise ValueError("Invalid session format")
+```
+
+---
+
+## API Versioning
+
+### Current Version: 1.0.0
+
+- **Base URL**: Stable (Hugging Face Spaces URL)
+- **Endpoint Names**: Stable
+- **Response Formats**: Stable
+- **Parameters**: Backward compatible additions only
+
+### Version History
+
+- **v1.0.0** (2024-12-28): Initial stable release with all endpoints
+
+### Breaking Changes Policy
+
+- Major version increments indicate breaking changes
+- Deprecated endpoints will be announced 30 days in advance
+- Old endpoint versions maintained for compatibility
+
+---
+
+## Additional Resources
+
+### Documentation
+
+- **Implementation Details**: See `API_ENDPOINTS_IMPLEMENTATION_COMPLETE.md`
+- **Application Features**: See `APPLICATION_FEATURES_REPORT.md`
+- **Context Management**: See `CONTEXT_RELEVANCE_IMPLEMENTATION_MILESTONE.md`
+
+### Support Channels
+
+- **GitHub Issues**: [Repository Link]
+- **Email Support**: [Support Email]
+- **Documentation**: [Documentation Link]
+
+### Changelog
+
+See `CHANGELOG.md` for detailed change history.
+
+---
+
+## Appendix
+
+### A. Complete Request/Response Examples
+
+#### Chat Request (Complete)
+
+```python
+from gradio_client import Client
+
+client = Client("JatinAutonomousLabs/Research_AI_Assistant")
+
+# Full request
+result = client.predict(
+    message="What are the applications of quantum computing?",
+    history=[
+        {"role": "user", "content": "Hello"},
+        {"role": "assistant", "content": "Hello! How can I help you?"}
+    ],
+    user_id="Admin_J",
+    session_text="Session: abc12345 | User: Admin_J | Interactions: 1",
+    api_name="/safe_gpu_chat_handler"
+)
+
+# Response unpacking
+history = result[0]
+reasoning = result[2]
+performance = result[3]
+context = result[4]
+session_info = result[5]
+skills = result[6]
+
+print(f"Latest response: {history[-1]['content']}")
+print(f"Processing time: {performance.get('processing_time', 0):.2f}s")
+print(f"Tokens used: {performance.get('token_count', 0)}")
+```
+
+### B. Session Lifecycle Example
+
+```python
+# 1. Initialize
+client = Client("JatinAutonomousLabs/Research_AI_Assistant")
+session = None
+history = []
+
+# 2. Create session
+session = client.predict(user_id="Test_Any", api_name="/new_session")
+print(f"Created: {session}")
+
+# 3. Set context mode
+client.predict(mode="relevant", session_id_text=session, api_name="/handle_mode_change")
+
+# 4. Conversation loop
+for i in range(3):
+    user_message = input("You: ")
+    
+    result = client.predict(
+        message=user_message,
+        history=history,
+        user_id="Test_Any",
+        session_text=session,
+        api_name="/safe_gpu_chat_handler"
+    )
+    
+    history = result[0]
+    session = result[5]  # Updated session with interaction count
+    
+    print(f"Assistant: {history[-1]['content']}")
+    print(f"Session: {session}")
+
+# 5. Save preferences
+client.predict(
+    param_0=True,
+    param_1=False,
+    param_2="Balanced",
+    param_3=True,
+    api_name="/save_preferences"
+)
+```
+
+### C. Error Recovery Patterns
+
+```python
+def robust_chat_request(message, history, session_info, max_retries=3):
+    """Chat request with comprehensive error handling"""
+    client = Client("JatinAutonomousLabs/Research_AI_Assistant")
+    
+    for attempt in range(max_retries):
+        try:
+            result = client.predict(
+                message=message,
+                history=history,
+                user_id="Test_Any",
+                session_text=session_info,
+                api_name="/safe_gpu_chat_handler"
+            )
+            
+            # Check for errors in response
+            if isinstance(result[3], dict) and "error" in result[3]:
+                error = result[3]["error"]
+                if attempt < max_retries - 1 and "timeout" in error.lower():
+                    time.sleep(2 ** attempt)
+                    continue
+                raise Exception(error)
+            
+            return result
+            
+        except ConnectionError as e:
+            if attempt < max_retries - 1:
+                time.sleep(2 ** attempt)
+                continue
+            raise
+        except Exception as e:
+            if attempt < max_retries - 1:
+                time.sleep(1)
+                continue
+            raise
+    
+    raise Exception("Max retries exceeded")
+```
+
+---
+
+**Document End**  
+*For questions or issues, please refer to the Support section above.*
+

API_QUICK_REFERENCE.md

@@ -0,0 +1,224 @@
+# API Quick Reference Guide
+
+**Quick lookup for engineering team integration**
+
+---
+
+## Installation
+
+```bash
+pip install gradio_client
+```
+
+---
+
+## Client Initialization
+
+```python
+from gradio_client import Client
+
+client = Client("JatinAutonomousLabs/Research_AI_Assistant")
+```
+
+---
+
+## All Available Endpoints
+
+### 1. Chat Handler
+```python
+result = client.predict(
+    message="Your question",
+    history=[],
+    user_id="Test_Any",
+    session_text="Session: abc12345 | User: Test_Any | Interactions: 0",
+    api_name="/safe_gpu_chat_handler"
+)
+# Returns: (history, input, reasoning, performance, context, session_info, skills)
+```
+
+### 2. New Session
+```python
+session = client.predict(
+    user_id="Test_Any",
+    api_name="/new_session"
+)
+# Returns: "Session: xyz67890 | User: Test_Any | Interactions: 0"
+```
+
+### 3. Update Session Info
+```python
+updated = client.predict(
+    user_id="Admin_J",
+    session_text="Session: abc12345 | User: Test_Any | Interactions: 3",
+    api_name="/update_session_info"
+)
+# Returns: "Session: abc12345 | User: Admin_J | Interactions: 3"
+```
+
+### 4. Toggle Settings
+```python
+client.predict(api_name="/toggle_settings")
+```
+
+### 5. Toggle Settings from Nav
+```python
+client.predict(api_name="/toggle_settings_from_nav")
+```
+
+### 6. Handle Mode Change
+```python
+status = client.predict(
+    mode="relevant",
+    session_id_text="Session: abc12345 | User: Test_Any | Interactions: 3",
+    api_name="/handle_mode_change"
+)
+# Returns: "*Current: Relevant Context*"
+```
+
+### 7. Save Preferences
+```python
+result = client.predict(
+    param_0=True,      # show_reasoning
+    param_1=False,     # show_agent_trace
+    param_2="Fast",    # response_speed: 'Fast', 'Balanced', 'Thorough'
+    param_3=True,      # cache_enabled
+    api_name="/save_preferences"
+)
+# Returns: {"status": "success", "message": "Preferences saved"}
+```
+
+---
+
+## Response Structures
+
+### Chat Response Tuple
+```python
+(
+    list[dict],  # chatbot_history - [{"role": "user/assistant", "content": "..."}]
+    str,         # message_input - "" (cleared)
+    dict,        # reasoning_data - Chain of thought
+    dict,        # performance_data - Timing, tokens, agents
+    dict,        # context_data - Session context
+    str,         # session_info - "Session: ... | User: ... | Interactions: N"
+    str          # skills_html - HTML string for skills display
+)
+```
+
+### Reasoning Data Structure
+```python
+{
+    "chain_of_thought": {
+        "step_1": {
+            "hypothesis": "...",
+            "evidence": [...],
+            "confidence": 0.85,
+            "reasoning": "..."
+        }
+    },
+    "confidence_calibration": {"overall_confidence": 0.85}
+}
+```
+
+### Performance Data Structure
+```python
+{
+    "agent_trace": [...],
+    "processing_time": 2.34,
+    "token_count": 1250,
+    "confidence_score": 0.85,
+    "agents_used": [...]
+}
+```
+
+---
+
+## Validation Rules
+
+| Parameter | Validation |
+|-----------|------------|
+| `message` | Non-empty, max 10,000 chars |
+| `user_id` | One of: `Admin_J`, `Dev_K`, `Dev_H`, `Dev_A`, `Test_Any` |
+| `mode` | One of: `'fresh'`, `'relevant'` |
+| `response_speed` | One of: `'Fast'`, `'Balanced'`, `'Thorough'` |
+| `session_text` | Format: `"Session: <8-hex> | User: <user_id> | Interactions: <num>"` |
+
+---
+
+## Common Patterns
+
+### Full Conversation Flow
+```python
+# 1. Create session
+session = client.predict(user_id="Test_Any", api_name="/new_session")
+
+# 2. Set context mode
+client.predict(mode="relevant", session_id_text=session, api_name="/handle_mode_change")
+
+# 3. Send messages
+history = []
+for msg in ["Q1", "Q2", "Q3"]:
+    result = client.predict(
+        message=msg, history=history,
+        user_id="Test_Any", session_text=session,
+        api_name="/safe_gpu_chat_handler"
+    )
+    history = result[0]
+    session = result[5]  # Update session
+    print(result[0][-1]["content"])  # Print response
+```
+
+### Error Handling
+```python
+try:
+    result = client.predict(...)
+    if isinstance(result[3], dict) and "error" in result[3]:
+        print(f"Error: {result[3]['error']}")
+except Exception as e:
+    print(f"Request failed: {e}")
+```
+
+---
+
+## Parameter Quick Reference
+
+### `/safe_gpu_chat_handler`
+- `message` (str, required)
+- `history` (list, default: [])
+- `user_id` (str, default: "Test_Any")
+- `session_text` (str, default: "Session: ... | User: ... | Interactions: 0")
+
+### `/new_session`
+- `user_id` (str, default: "Test_Any")
+
+### `/update_session_info`
+- `user_id` (str, default: "Test_Any")
+- `session_text` (str, required)
+
+### `/handle_mode_change`
+- `mode` (str, required: "fresh" | "relevant")
+- `session_id_text` (str, required)
+
+### `/save_preferences`
+- `param_0` (bool, default: True) - show_reasoning
+- `param_1` (bool, default: False) - show_agent_trace
+- `param_2` (str, default: "Balanced") - response_speed
+- `param_3` (bool, default: True) - cache_enabled
+
+---
+
+## Status Codes / Return Values
+
+### Success Indicators
+- Chat: Valid tuple with 7 elements
+- Preferences: `{"status": "success"}` or `{"status": "partial"}`
+- Mode Change: `"*Current: Fresh Context*"` or `"*Current: Relevant Context*"`
+
+### Error Indicators
+- Chat: Error message in `performance_data` or `context_data`
+- Mode Change: `"*Error: Invalid session information*"`
+- Other: Error strings or dictionaries with `"error"` key
+
+---
+
+**See `API_DOCUMENTATION.md` for complete documentation.**
+

app.py

@@ -1906,6 +1906,9 @@ if __name__ == "__main__":
     demo.launch(
         server_name="0.0.0.0",
         server_port=7860,
-        share=False
+        share=False,
+        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)
     )