API_QUICK_REFERENCE.md

API Quick Reference Guide

Quick lookup for engineering team integration

---

Installation

pip install gradio_client

---

Client Initialization

from gradio_client import Client

client = Client("JatinAutonomousLabs/Research_AI_Assistant")

---

User Management

Base User: Admin_J (default)
Dynamic Users: Any valid format (alphanumeric + underscore, 1-50 chars) - auto-created in DB
Format: ^[a-zA-Z0-9_]{1,50}$
UI Restriction: HuggingFace Spaces UI limited to ADMINONLY only

---

All Available Endpoints

1. Chat Handler

# Using base Admin_J user
result = client.predict(
    message="Your question",
    history=[],
    user_id="Admin_J",
    session_text="Session: abc12345 | User: Admin_J | Interactions: 0",
    api_name="/safe_gpu_chat_handler"
)
# Returns: (history, input, reasoning, performance, context, session_info, skills)

# Using dynamic user (auto-created)
result = client.predict(
    message="Your question",
    history=[],
    user_id="ExternalAPI_User123",  # New user - auto-created in DB
    session_text="Session: abc12345 | User: ExternalAPI_User123 | Interactions: 0",
    api_name="/safe_gpu_chat_handler"
)

2. New Session

# Base user
session = client.predict(
    user_id="Admin_J",
    api_name="/new_session"
)
# Returns: "Session: xyz67890 | User: Admin_J | Interactions: 0"

# Dynamic user (auto-created)
session = client.predict(
    user_id="MyNewUser_2024",
    api_name="/new_session"
)
# Returns: "Session: xyz67890 | User: MyNewUser_2024 | Interactions: 0"

3. Update Session Info

updated = client.predict(
    user_id="Admin_J",
    session_text="Session: abc12345 | User: Admin_J | Interactions: 3",
    api_name="/update_session_info"
)
# Returns: "Session: abc12345 | User: Admin_J | Interactions: 3"

4. Toggle Settings

client.predict(api_name="/toggle_settings")

5. Toggle Settings from Nav

client.predict(api_name="/toggle_settings_from_nav")

6. Handle Mode Change

status = client.predict(
    mode="relevant",
    session_id_text="Session: abc12345 | User: Admin_J | Interactions: 3",
    api_name="/handle_mode_change"
)
# Returns: "*Current: Relevant Context*"

7. Save Preferences

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

(
    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

{
    "chain_of_thought": {
        "step_1": {
            "hypothesis": "...",
            "evidence": [...],
            "confidence": 0.85,
            "reasoning": "..."
        }
    },
    "confidence_calibration": {"overall_confidence": 0.85}
}

Performance Data Structure

{
    "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	Base: Admin_J (default). Dynamic: Any [a-zA-Z0-9_]{1,50} - auto-created
mode	One of: 'fresh', 'relevant'
response_speed	One of: 'Fast', 'Balanced', 'Thorough'
session_text	Format: `"Session: <8-hex>

---

Common Patterns

Full Conversation Flow

# 1. Create session (using base Admin_J user)
session = client.predict(user_id="Admin_J", 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="Admin_J", session_text=session,
        api_name="/safe_gpu_chat_handler"
    )
    history = result[0]
    session = result[5]  # Update session
    print(result[0][-1]["content"])  # Print response

# Example with dynamic user (auto-created on first use)
dynamic_user = "ExternalAPI_Client01"
session = client.predict(user_id=dynamic_user, api_name="/new_session")
# User automatically created in database

Error Handling

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: "Admin_J") - Base user or any valid format (auto-created)
• session_text (str, default: "Session: ... | User: ... | Interactions: 0")

/new_session

• user_id (str, default: "Admin_J") - Base user or any valid format (auto-created)

/update_session_info

• user_id (str, default: "Admin_J") - Base user or any valid format (auto-created)
• 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.