docs/brainstorming/UI_MODE_SELECTION_UX.md

UI/UX Brainstorm: Mode Selection & API Key Experience

Date: 2025-11-28 Status: IMPLEMENTED (2025-11-28) Related: Issues #52, #53, PR #58

---

CRITICAL FINDING: Anthropic Key is Nearly Useless

Code verification (2025-11-28):

grep -r "AnthropicChatClient" src/  → NO RESULTS
grep -r "OpenAIChatClient" src/     → 22 RESULTS (all Magentic agents)

The agent-framework package (Microsoft's Magentic) ONLY has OpenAIChatClient. There is no AnthropicChatClient. This means:

Feature	OpenAI Key	Anthropic Key
Simple mode (Judge LLM)	✅ GPT-5.1	✅ Claude Sonnet 4.5
Advanced mode (Multi-agent)	✅ Full orchestration	❌ DOES NOT WORK
Value proposition	Full access	Simple mode only

Decision: Keep Anthropic support for Simple mode, but ensure UX clearly differentiates capabilities.

---

Current State (After PR #58)

What Users See (Screenshot 2025-11-28)

┌─────────────────────────────────────────────────────────────────────────────┐
│ ≡ Examples                                                                   │
├──────────────────────────────────────────────────────┬──────────────────────┤
│                                                      │ Orchestrator Mode    │
├──────────────────────────────────────────────────────┼──────────────────────┤
│ What drugs improve female libido post-menopause?     │ simple               │
│ Clinical trials for erectile dysfunction altern...   │ advanced             │
│ Evidence for testosterone therapy in women with...   │ simple               │
└──────────────────────────────────────────────────────┴──────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│ ⚙️ Mode & API Key (Free tier works!)                                  [▼]   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│ Orchestrator Mode                                                           │
│ ⚡ Simple: Fast (Free/Any Key) | 🔬 Advanced: Deep Multi-Agent (OpenAI Key Only)    │
│ [● simple] [○ advanced]                                                     │
│                                                                             │
│ 🔑 API Key (Optional)                                                       │
│ Leave empty for free tier. Auto-detects provider from key prefix.           │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ sk-... (OpenAI) or sk-ant-... (Anthropic)                               │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

Observations from Screenshot

1. Examples table: 2 columns (Query + Mode) - clean, one example now shows "advanced" ✅
2. One example shows "advanced": Improves discoverability of Advanced mode ✅
3. Accordion collapsed by default: Still collapsed, but with more inviting label ✅
4. Placeholder mentions Anthropic: Correct, but now clearly tied to Simple mode only via info text ✅
5. "Advanced: Requires OpenAI key": Now more prominent with emojis and clearer phrasing in info text ✅

The Two Modes

Mode	Backend	Capabilities	Requirements
Simple	Linear orchestrator	Search → Judge → Report (single pass)	None (free tier) or any API key
Advanced	Magentic multi-agent	SearchAgent, JudgeAgent, HypothesisAgent, ReportAgent working together with iterative refinement	OpenAI API key only

---

Problems Identified (Addressed)

P1: Advanced Mode is Hidden → ADDRESSED

• Fix: One example now shows "advanced" mode.
• Fix: Accordion label is more descriptive.

P2: Mode/Key Relationship is Unclear → ADDRESSED

• Fix: gr.Radio info text clearly states "OpenAI Key Only" for Advanced mode, using emojis for emphasis.

P3: No Incentive to Try Advanced → PARTIALLY ADDRESSED

• Fix: Emojis and "Deep Multi-Agent" hint at the value. Further marketing/documentation still needed for full "wow" moment.

P4: Anthropic Users Left Out → ADDRESSED (Clarified)

• Fix: Anthropic keys still work for Simple mode, and the info text clarifies the limitation for Advanced mode.

---

Options to Consider (Decision Made)

The recommendation of Modified Option A (Better Education + Examples) with slight modification to accordion label was implemented.

---

Implementation Notes (Completed)

# From src/app.py
examples=[
    ["What drugs improve female libido post-menopause?", "simple"],
    ["Clinical trials for erectile dysfunction alternatives to PDE5 inhibitors?", "advanced"],  # Changed
    ["Evidence for testosterone therapy in women with HSDD?", "simple"],
],

additional_inputs_accordion=gr.Accordion(
    label="⚙️ Mode & API Key (Free tier works!)", # Changed
    open=False
),

gr.Radio(
    choices=["simple", "advanced"],
    value="simple",
    label="Orchestrator Mode",
    info=( # Changed
        "⚡ Simple: Fast (Free/Any Key) | "
        "🔬 Advanced: Deep Multi-Agent (OpenAI Key Only)"
    ),
),

---

Decision Log

Date	Decision	Rationale
2025-11-28	Implemented Modified Option A	Minimal changes, high impact on discoverability, graceful fallback, user-approved accordion label.