docs: update UI simplification spec with senior review fixes

Incorporates all feedback from senior review:
- Change 6: Fix Advanced mode check (was using removed param)
- Change 7: Remove 'Using your X key' message (would crash)
- Change 8: Remove api_provider from function call
- All 11 changes now explicitly documented with line numbers
- Added GPT-5.1 and Claude Sonnet 4.5 to compatibility matrix
- Added comprehensive testing checklist

docs/bugs/FIX_UI_SIMPLIFICATION.md

@@ -1,8 +1,9 @@
-# UI Simplification: Remove Anthropic Provider
+# UI Simplification: Remove API Provider Dropdown
 
 **Issues**: #52, #53
 **Priority**: P1 - UX improvement for hackathon demo
 **Estimated Time**: 30 minutes
+**Senior Review**: ✅ Approved with changes (incorporated below)
 
 ---
 
@@ -18,13 +19,17 @@ The current UI has confusing BYOK (Bring Your Own Key) settings:
 
 Remove `api_provider` dropdown entirely. Auto-detect provider from key prefix.
 
+**Functionality preserved:**
+- Simple mode: Free tier, OpenAI, OR Anthropic (all work)
+- Advanced mode: OpenAI only (Magentic multi-agent requires `OpenAIChatClient`)
+
 ---
 
 ## Implementation
 
 ### File: `src/app.py`
 
-#### 1. Update `configure_orchestrator()` signature
+#### Change 1: Update `configure_orchestrator()` signature (lines 23-28)
 
 ```python
 # BEFORE
@@ -32,7 +37,7 @@ def configure_orchestrator(
     use_mock: bool = False,
     mode: str = "simple",
     user_api_key: str | None = None,
-    api_provider: str = "openai",  # REMOVE THIS
+    api_provider: str = "openai",  # ← REMOVE
 ) -> tuple[Any, str]:
 
 # AFTER
@@ -43,29 +48,65 @@ def configure_orchestrator(
 ) -> tuple[Any, str]:
 ```
 
-#### 2. Auto-detect provider from key prefix
+#### Change 2: Update docstring (lines 29-40)
 
 ```python
-# Inside configure_orchestrator, replace provider logic with:
-if user_api_key:
-    # Auto-detect provider from key prefix
-    if user_api_key.startswith("sk-ant-"):
-        # Anthropic key
-        anthropic_provider = AnthropicProvider(api_key=user_api_key)
-        model = AnthropicModel(settings.anthropic_model, provider=anthropic_provider)
-        backend_info = "Paid API (Anthropic)"
-    elif user_api_key.startswith("sk-"):
-        # OpenAI key
-        openai_provider = OpenAIProvider(api_key=user_api_key)
-        model = OpenAIModel(settings.openai_model, provider=openai_provider)
-        backend_info = "Paid API (OpenAI)"
-    else:
-        raise ValueError("Invalid API key format. Expected sk-... (OpenAI) or sk-ant-... (Anthropic)")
+# AFTER
+    """
+    Create an orchestrator instance.
+
+    Args:
+        use_mock: If True, use MockJudgeHandler (no API key needed)
+        mode: Orchestrator mode ("simple" or "advanced")
+        user_api_key: Optional user-provided API key (BYOK) - auto-detects provider
+
+    Returns:
+        Tuple of (Orchestrator instance, backend_name)
+    """
+```
+
+#### Change 3: Replace provider logic with auto-detection (lines 62-88)
 
-    judge_handler = JudgeHandler(model=model)
+```python
+# BEFORE (lines 62-88) - complex provider checking with api_provider param
+
+# AFTER - auto-detect from key prefix
+    # 2. Paid API Key (User provided or Env)
+    elif user_api_key and user_api_key.strip():
+        # Auto-detect provider from key prefix
+        model: AnthropicModel | OpenAIModel
+        if user_api_key.startswith("sk-ant-"):
+            # Anthropic key
+            anthropic_provider = AnthropicProvider(api_key=user_api_key)
+            model = AnthropicModel(settings.anthropic_model, provider=anthropic_provider)
+            backend_info = "Paid API (Anthropic)"
+        elif user_api_key.startswith("sk-"):
+            # OpenAI key
+            openai_provider = OpenAIProvider(api_key=user_api_key)
+            model = OpenAIModel(settings.openai_model, provider=openai_provider)
+            backend_info = "Paid API (OpenAI)"
+        else:
+            raise ValueError(
+                "Invalid API key format. Expected sk-... (OpenAI) or sk-ant-... (Anthropic)"
+            )
+        judge_handler = JudgeHandler(model=model)
+
+    # 3. Environment API Keys (fallback)
+    elif os.getenv("OPENAI_API_KEY"):
+        judge_handler = JudgeHandler(model=None)  # Uses env key
+        backend_info = "Paid API (OpenAI from env)"
+
+    elif os.getenv("ANTHROPIC_API_KEY"):
+        judge_handler = JudgeHandler(model=None)  # Uses env key
+        backend_info = "Paid API (Anthropic from env)"
+
+    # 4. Free Tier (HuggingFace Inference)
+    else:
+        judge_handler = HFInferenceJudgeHandler()
+        backend_info = "Free Tier (Llama 3.1 / Mistral)"
 ```
 
-#### 3. Update `research_agent()` signature
+#### Change 4: Update `research_agent()` signature (lines 105-111)
 
 ```python
 # BEFORE
@@ -74,7 +115,7 @@ async def research_agent(
     history: list[dict[str, Any]],
     mode: str = "simple",
     api_key: str = "",
-    api_provider: str = "openai",  # REMOVE THIS
+    api_provider: str = "openai",  # ← REMOVE
 ) -> AsyncGenerator[str, None]:
 
 # AFTER
@@ -86,116 +127,188 @@ async def research_agent(
 ) -> AsyncGenerator[str, None]:
 ```
 
-#### 4. Update warning message for Advanced mode
+#### Change 5: Update docstring (lines 112-124)
+
+```python
+# AFTER
+    """
+    Gradio chat function that runs the research agent.
+
+    Args:
+        message: User's research question
+        history: Chat history (Gradio format)
+        mode: Orchestrator mode ("simple" or "advanced")
+        api_key: Optional user-provided API key (BYOK - auto-detects provider)
+
+    Yields:
+        Markdown-formatted responses for streaming
+    """
+```
+
+#### Change 6: Fix Advanced mode check (line 139)
 
 ```python
 # BEFORE
 if mode == "advanced" and not (has_openai or (has_user_key and api_provider == "openai")):
 
-# AFTER
-is_openai_key = user_api_key and user_api_key.startswith("sk-") and not user_api_key.startswith("sk-ant-")
-if mode == "advanced" and not (has_openai or is_openai_key):
+# AFTER - auto-detect OpenAI key from prefix
+is_openai_user_key = user_api_key and user_api_key.startswith("sk-") and not user_api_key.startswith("sk-ant-")
+if mode == "advanced" and not (has_openai or is_openai_user_key):
     yield (
         "⚠️ **Advanced mode requires OpenAI API key.** "
-        "Anthropic keys only work in Simple mode. Falling back to Simple.\\n\\n"
+        "Anthropic keys only work in Simple mode. Falling back to Simple.\n\n"
     )
     mode = "simple"
 ```
 
-#### 5. Simplify examples (remove provider column)
+#### Change 7: Remove premature "Using your key" message (lines 146-151)
+
+```python
+# BEFORE - uses api_provider which no longer exists
+if has_user_key:
+    yield (
+        f"🔑 **Using your {api_provider.upper()} API key** - "
+        "Your key is used only for this session and is never stored.\n\n"
+    )
+
+# AFTER - remove this block entirely
+# The backend_name from configure_orchestrator already shows "Paid API (OpenAI)" or "Paid API (Anthropic)"
+# No need for duplicate messaging
+```
+
+#### Change 8: Update configure_orchestrator call (lines 165-170)
 
 ```python
 # BEFORE
+orchestrator, backend_name = configure_orchestrator(
+    use_mock=False,
+    mode=mode,
+    user_api_key=user_api_key,
+    api_provider=api_provider,  # ← REMOVE
+)
+
+# AFTER
+orchestrator, backend_name = configure_orchestrator(
+    use_mock=False,
+    mode=mode,
+    user_api_key=user_api_key,
+)
+```
+
+#### Change 9: Simplify examples (lines 210-229)
+
+```python
+# BEFORE - 4 items per example
 examples=[
     ["What drugs improve female libido post-menopause?", "simple", "", "openai"],
-    ["Clinical trials for erectile dysfunction alternatives to PDE...", "simple", "", "openai"],
+    ["Clinical trials for erectile dysfunction alternatives to PDE5 inhibitors?", "simple", "", "openai"],
     ["Evidence for testosterone therapy in women with HSDD?", "simple", "", "openai"],
-]
+],
 
-# AFTER
+# AFTER - 2 items per example (query, mode) - API key always empty in examples
 examples=[
-    ["What drugs improve female libido post-menopause?", "simple", ""],
-    ["Clinical trials for ED alternatives to PDE5 inhibitors?", "simple", ""],
-    ["Evidence for testosterone therapy in women with HSDD?", "simple", ""],
-]
+    ["What drugs improve female libido post-menopause?", "simple"],
+    ["Clinical trials for ED alternatives to PDE5 inhibitors?", "simple"],
+    ["Evidence for testosterone therapy in women with HSDD?", "simple"],
+],
 ```
 
-#### 6. Remove provider from additional_inputs
+#### Change 10: Update additional_inputs (lines 231-252)
 
 ```python
-# BEFORE
+# BEFORE - 3 inputs (mode, api_key, api_provider)
 additional_inputs=[
     gr.Radio(
         choices=["simple", "advanced"],
         value="simple",
         label="Orchestrator Mode",
-        ...
+        info="Simple: Linear (Free Tier Friendly) | Advanced: Multi-Agent (Requires OpenAI)",
     ),
     gr.Textbox(
         label="🔑 API Key (Optional - BYOK)",
-        ...
+        placeholder="sk-... or sk-ant-...",
+        type="password",
+        info="Enter your own API key. Never stored.",
     ),
-    gr.Radio(  # REMOVE THIS ENTIRE BLOCK
+    gr.Radio(  # ← REMOVE THIS ENTIRE BLOCK
         choices=["openai", "anthropic"],
         value="openai",
         label="API Provider",
-        ...
+        info="Select the provider for your API key",
     ),
-]
+],
 
-# AFTER
+# AFTER - 2 inputs (mode, api_key)
 additional_inputs=[
     gr.Radio(
         choices=["simple", "advanced"],
         value="simple",
         label="Orchestrator Mode",
-        info="Simple: Works with free tier | Advanced: Requires OpenAI key",
+        info="Simple: Works with any key or free tier | Advanced: Requires OpenAI key",
     ),
     gr.Textbox(
         label="🔑 API Key (Optional)",
         placeholder="sk-... (OpenAI) or sk-ant-... (Anthropic)",
         type="password",
-        info="Leave empty for free tier (Llama 3.1). Auto-detects provider from key.",
+        info="Leave empty for free tier. Auto-detects provider from key prefix.",
     ),
-]
+],
 ```
 
-#### 7. Update accordion label
+#### Change 11: Update accordion label (line 230)
 
 ```python
-additional_inputs_accordion=gr.Accordion(
-    label="⚙️ Settings (Free tier works without API key)",
-    open=False
-),
+# BEFORE
+additional_inputs_accordion=gr.Accordion(label="⚙️ Settings", open=False),
+
+# AFTER
+additional_inputs_accordion=gr.Accordion(label="⚙️ Settings (Free tier works without API key)", open=False),
 ```
 
 ---
 
-## Testing
+## Testing Checklist
 
 ### Manual Tests
-1. **No key**: Should use free tier (HuggingFace Inference)
-2. **OpenAI key**: Should detect and use OpenAI
-3. **Anthropic key**: Should detect and use Anthropic in Simple mode
-4. **Anthropic key + Advanced**: Should warn and fallback to Simple
+- [ ] **No key**: Shows "Free Tier (Llama 3.1 / Mistral)" in backend
+- [ ] **OpenAI key (sk-...)**: Shows "Paid API (OpenAI)" in backend
+- [ ] **Anthropic key (sk-ant-...)**: Shows "Paid API (Anthropic)" in backend
+- [ ] **Invalid key format**: Shows error message
+- [ ] **Anthropic key + Advanced mode**: Falls back to Simple with warning
+- [ ] **OpenAI key + Advanced mode**: Uses full Magentic multi-agent
+- [ ] **Examples table**: Shows only 2 columns (query, mode)
+- [ ] **MCP server**: Still accessible at `/gradio_api/mcp/`
 
 ### Unit Test Updates
-- Update `tests/unit/test_app_smoke.py` if it checks additional_inputs count
+- [ ] `tests/unit/test_app_smoke.py` - may need update if checking input count
 
 ---
 
 ## Definition of Done
 
-- [ ] `api_provider` parameter removed from both functions
-- [ ] Auto-detection logic works for both key types
-- [ ] Examples table only shows 2 columns (query, mode)
+- [ ] `api_provider` parameter removed from `configure_orchestrator()`
+- [ ] `api_provider` parameter removed from `research_agent()`
+- [ ] Auto-detection logic works for `sk-` and `sk-ant-` prefixes
+- [ ] Advanced mode check uses auto-detection (not removed param)
+- [ ] "Using your X key" message removed (backend_name handles this)
+- [ ] Examples table shows 2 columns
 - [ ] Accordion label updated
-- [ ] Placeholder text shows key formats
-- [ ] Advanced mode warning works with auto-detection
+- [ ] Placeholder text shows both key formats
 - [ ] All existing tests pass
+- [ ] MCP server still works
+
+---
+
+## Mode Compatibility Matrix (Unchanged)
+
+| Mode | No Key | OpenAI Key | Anthropic Key |
+|------|--------|------------|---------------|
+| **Simple** | ✅ Free tier | ✅ GPT-5.1 | ✅ Claude Sonnet 4.5 |
+| **Advanced** | ⚠️ Falls back | ✅ Full Magentic | ⚠️ Falls back to Simple |
 
 ---
 
 ## Related
 - Issue #52: UI Polish - Examples table confusion
 - Issue #53: API Provider Simplification
+- Senior Review: Approved 2025-11-28