API_DOCUMENTATION.md

# 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

---

## User Management

### Base User
- `Admin_J` is the base/default API user
- Used when no `user_id` is provided or invalid format is provided

### Dynamic User Creation
The API supports dynamic user creation - any valid format `user_id` is automatically accepted and created in the database.

**Valid Format:**
- Alphanumeric characters + underscore only
- Length: 1-50 characters
- Pattern: `^[a-zA-Z0-9_]{1,50}$`
- Examples: `User123`, `External_API`, `MyUser_2024`, `API_Client_01`

**Auto-Creation:**
- New users are automatically inserted into the `user_contexts` database table on first use
- No manual user registration required
- User information is maintained by the backend database

**Validation:**
- Valid formats are accepted and auto-created
- Invalid formats default to `Admin_J`
- Database automatically maintains user information

### UI Restriction
- The HuggingFace Spaces UI is restricted to `ADMINONLY` user only
- Dynamic user creation is available **only via API calls**
- UI users cannot use dynamic user IDs

---

## 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` | `str` | No | `"Admin_J"` | User identifier. Base user is `Admin_J`. Any valid format user_id (alphanumeric + underscore, 1-50 chars) is accepted and automatically created in the database. |
| `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: Admin_J | 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 (using base Admin_J user)
result = client.predict(
    message="Explain quantum computing in simple terms",
    history=[],
    user_id="Admin_J",
    session_text="Session: abc12345 | User: Admin_J | Interactions: 0",
    api_name="/safe_gpu_chat_handler"
)

# Make chat request (using dynamic user - auto-created)
result = client.predict(
    message="What is machine learning?",
    history=[],
    user_id="MyNewUser_123",  # New user - automatically created in DB
    session_text="Session: abc12345 | User: MyNewUser_123 | 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**: 
  - Base user: `Admin_J` (default)
  - Dynamic users: Any alphanumeric + underscore format (1-50 characters)
  - New users are automatically created in the database on first use
  - Invalid formats default to `Admin_J`
  - Format validation: `^[a-zA-Z0-9_]{1,50}$`
- **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` | `str` | No | `"Admin_J"` | User identifier. Base user is `Admin_J`. Any valid format user_id is accepted and automatically created in the database. |

#### Response

Returns a single string:

```python
"Session: abc12345 | User: Admin_J | 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 (defaults to `Admin_J` if invalid)
- Auto-creates new users in database on first use
- 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` | `str` | No | `"Admin_J"` | New user identifier. Base user is `Admin_J`. Any valid format user_id is accepted and automatically created in the database. |
| `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: Admin_J | 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: Admin_J | 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="Admin_J",
                session_text="Session: abc12345 | User: Admin_J | 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 = "Admin_J"
        self.chat_history = []
    
    def create_session(self, user_id: str = "Admin_J") -> 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="Admin_J",
            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: Admin_J | 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="Admin_J",
    api_name="/new_session"
)
```

### Step 4: Send Messages

```python
result = client.predict(
    message="Your question here",
    history=[],
    user_id="Admin_J",
    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="Admin_J",
            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="Admin_J",
            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="Admin_J", 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="Admin_J",
            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: Admin_J | 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: Admin_J | 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="Admin_J", 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="Admin_J",
        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="Admin_J",
                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.*