API_QUICK_REFERENCE.md

# 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")
```

---

## 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
```python
# 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
```python
# 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
```python
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
```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: Admin_J | 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` | 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> | User: <user_id> | Interactions: <num>"` |

---

## Common Patterns

### Full Conversation Flow
```python
# 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
```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: "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.**