Spaces:

JatinAutonomousLabs
/

Research_AI_Assistant

Sleeping

App Files Files Community

Research_AI_Assistant / API_DOCUMENTATION.md

JatsTheAIGen

api endpoints for UI migration v5

e3fd5ce about 1 month ago

preview code

raw

history blame contribute delete

32.9 kB

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

Overview
Getting Started
Authentication
API Endpoints
Error Handling
Code Examples
Integration Guide
Testing
Rate Limits & Best Practices
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

pip install gradio_client

Basic Setup

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:

client = Client("JatinAutonomousLabs/Research_AI_Assistant")

Private Space Access

For private spaces, pass your Hugging Face token:

client = Client(
    "JatinAutonomousLabs/Research_AI_Assistant",
    hf_token=os.getenv("HF_TOKEN")
)

Token Management

Get token from: https://huggingface.co/settings/tokens
Store securely (environment variables recommended)
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:

(
    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])

[
    {
        "role": "user",
        "content": "What is machine learning?"
    },
    {
        "role": "assistant",
        "content": "Machine learning is a subset of artificial intelligence..."
    }
]

2. reasoning_data (dict)

{
    "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)

{
    "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)

{
    "interaction_id": "uuid-string",
    "session_id": "abc12345",
    "timestamp": "2024-12-28T10:30:00",
    "warnings": [],
    "context_mode": "relevant"
}

5. session_info (str)

"Session: abc12345 | User: Admin_J | Interactions: 5"

6. skills_html (str)

"<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

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:

{
    "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:

"Session: abc12345 | User: Admin_J | Interactions: 0"

Code Example

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:

"Session: abc12345 | User: Admin_J | Interactions: 5"

Code Example

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

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

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:

"*Current: Fresh Context*"  # or "*Current: Relevant Context*"

Code Example

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:

{
    "status": "success",  # or "partial" if cache-only
    "message": "Preferences saved"
}

Code Example

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:

{
    "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:

# 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

# 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

# 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

# Example
{
    "error": "Failed to save preferences to database",
    "type": "database_error",
    "fallback": "saved_to_cache"
}

Error Handling Best Practices

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

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

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

pip install gradio_client requests

Step 2: Initialize Client

from gradio_client import Client

client = Client("JatinAutonomousLabs/Research_AI_Assistant")

Step 3: Create Session

session_info = client.predict(
    user_id="Admin_J",
    api_name="/new_session"
)

Step 4: Send Messages

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

# Switch to relevant context mode
client.predict(
    mode="relevant",
    session_id_text=session_info,
    api_name="/handle_mode_change"
)

Step 6: Save Preferences

client.predict(
    param_0=True,
    param_1=False,
    param_2="Balanced",
    param_3=True,
    api_name="/save_preferences"
)

Testing

Unit Test Example

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

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

# ✅ 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

# ✅ 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

# ✅ 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

# ✅ 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:

# 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

import logging
logging.basicConfig(level=logging.DEBUG)

# Client will show detailed request/response logs

Check Response Metadata

result = client.predict(...)
reasoning = result[2]  # Check for errors
performance = result[3]  # Check processing info
context = result[4]  # Check session context

Validate Session Info

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)

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

# 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

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.

Research AI Assistant - API Documentation

Table of Contents

Overview

Key Features

Response Format

Getting Started

Installation

Basic Setup

Authentication

Public Space Access

Private Space Access

Token Management

User Management

Base User

Dynamic User Creation

UI Restriction

API Endpoints

1. Chat Handler - /safe_gpu_chat_handler

Endpoint Details

Request Parameters

Response Structure

Response Format Details

Code Example

Validation Rules

Error Responses

2. New Session - /new_session

Endpoint Details

Request Parameters

Response

Code Example

Behavior

3. Update Session Info - /update_session_info

Endpoint Details

Request Parameters

Response

Code Example

Important Notes

4. Toggle Settings - /toggle_settings

Endpoint Details

Request Parameters

Response

Code Example

Behavior

5. Toggle Settings from Nav - /toggle_settings_from_nav

Endpoint Details

Request Parameters

Response

Code Example

6. Handle Mode Change - /handle_mode_change

Endpoint Details

Request Parameters

Response

Code Example

Mode Descriptions

Validation

7. Save Preferences - /save_preferences

Endpoint Details

Request Parameters

Response

Code Example

Preferences Schema

Storage

Error Handling

Error Response Format

Error Types

1. Validation Errors

2. Processing Errors

3. Database Errors

Error Handling Best Practices

Code Examples

Complete Integration Example

Async Integration Example

Integration Guide

Step 1: Install Dependencies

Step 2: Initialize Client

Step 3: Create Session

Step 4: Send Messages

Step 5: Handle Context Mode

Step 6: Save Preferences

Testing

1. Chat Handler - `/safe_gpu_chat_handler`

2. New Session - `/new_session`

3. Update Session Info - `/update_session_info`

4. Toggle Settings - `/toggle_settings`

5. Toggle Settings from Nav - `/toggle_settings_from_nav`

6. Handle Mode Change - `/handle_mode_change`

7. Save Preferences - `/save_preferences`