feat: Add Settings screen for API key configuration

- Create new Settings screen for user-provided API keys (Gemini & HuggingFace)
- Add comprehensive UI with key validation, testing, and usage guides
- Prevent API key exposure via Gradio API using api_name=False
- Add settings navigation button in sidebar
- Update all navigation functions to include settings screen
- Session-only storage for security (no server-side persistence)
- Addresses hackathon judge feedback for credit safety

app.py

@@ -60,6 +60,7 @@ from screens.chat import (
     on_quick_action
 )
 from screens.documentation import create_documentation_screen
+from screens.settings import create_settings_screen
 from screens.mcp_helpers import (
     call_analyze_leaderboard_sync,
     call_debug_trace_sync,
@@ -1593,6 +1594,7 @@ with gr.Blocks(title="TraceMind-AI", theme=theme) as app:
             chat_nav_btn = gr.Button("🤖 Agent Chat", variant="secondary", size="lg")
             synthetic_data_nav_btn = gr.Button("🔬 Synthetic Data", variant="secondary", size="lg")
             docs_nav_btn = gr.Button("📚 Documentation", variant="secondary", size="lg")
+            settings_nav_btn = gr.Button("⚙️ Settings", variant="secondary", size="lg")
 
             gr.Markdown("---")
     
@@ -2419,6 +2421,11 @@ with gr.Blocks(title="TraceMind-AI", theme=theme) as app:
         # ============================================================================
         documentation_screen = create_documentation_screen()
 
+        # ============================================================================
+        # Screen 10: Settings
+        # ============================================================================
+        settings_screen, gemini_api_key_input, hf_token_input = create_settings_screen()
+
         # ============================================================================
         # Evaluation Helper Functions
         # ============================================================================
@@ -2790,6 +2797,7 @@ No historical data available for **{model}**.
                 synthetic_data_screen: gr.update(visible=False),
                 new_evaluation_screen: gr.update(visible=False),
                 documentation_screen: gr.update(visible=False),
+                settings_screen: gr.update(visible=False),
                 dashboard_nav_btn: gr.update(variant="primary"),
                 leaderboard_nav_btn: gr.update(variant="secondary"),
                 new_eval_nav_btn: gr.update(variant="secondary"),
@@ -2797,6 +2805,7 @@ No historical data available for **{model}**.
                 chat_nav_btn: gr.update(variant="secondary"),
                 synthetic_data_nav_btn: gr.update(variant="secondary"),
                 docs_nav_btn: gr.update(variant="secondary"),
+                settings_nav_btn: gr.update(variant="secondary"),
             }
             result.update(dashboard_updates)
             return result
@@ -2813,6 +2822,7 @@ No historical data available for **{model}**.
                 synthetic_data_screen: gr.update(visible=False),
                 new_evaluation_screen: gr.update(visible=False),
                 documentation_screen: gr.update(visible=False),
+                settings_screen: gr.update(visible=False),
                 dashboard_nav_btn: gr.update(variant="secondary"),
                 leaderboard_nav_btn: gr.update(variant="primary"),
                 new_eval_nav_btn: gr.update(variant="secondary"),
@@ -2820,6 +2830,7 @@ No historical data available for **{model}**.
                 chat_nav_btn: gr.update(variant="secondary"),
                 synthetic_data_nav_btn: gr.update(variant="secondary"),
                 docs_nav_btn: gr.update(variant="secondary"),
+                settings_nav_btn: gr.update(variant="secondary"),
             }
 
         def navigate_to_new_evaluation():
@@ -2834,6 +2845,7 @@ No historical data available for **{model}**.
                 synthetic_data_screen: gr.update(visible=False),
                 new_evaluation_screen: gr.update(visible=True),
                 documentation_screen: gr.update(visible=False),
+                settings_screen: gr.update(visible=False),
                 dashboard_nav_btn: gr.update(variant="secondary"),
                 leaderboard_nav_btn: gr.update(variant="secondary"),
                 new_eval_nav_btn: gr.update(variant="primary"),
@@ -2841,6 +2853,7 @@ No historical data available for **{model}**.
                 chat_nav_btn: gr.update(variant="secondary"),
                 synthetic_data_nav_btn: gr.update(variant="secondary"),
                 docs_nav_btn: gr.update(variant="secondary"),
+                settings_nav_btn: gr.update(variant="secondary"),
             }
 
         def navigate_to_compare():
@@ -2867,6 +2880,7 @@ No historical data available for **{model}**.
                 synthetic_data_screen: gr.update(visible=False),
                     new_evaluation_screen: gr.update(visible=False),
                     documentation_screen: gr.update(visible=False),
+                settings_screen: gr.update(visible=False),
                     dashboard_nav_btn: gr.update(variant="secondary"),
                     leaderboard_nav_btn: gr.update(variant="secondary"),
                     new_eval_nav_btn: gr.update(variant="secondary"),
@@ -2896,6 +2910,7 @@ No historical data available for **{model}**.
                     chat_nav_btn: gr.update(variant="secondary"),
                 synthetic_data_nav_btn: gr.update(variant="secondary"),
                     docs_nav_btn: gr.update(variant="secondary"),
+                settings_nav_btn: gr.update(variant="secondary"),
                 }
 
         def navigate_to_chat():
@@ -2910,6 +2925,7 @@ No historical data available for **{model}**.
                 synthetic_data_screen: gr.update(visible=False),
                 new_evaluation_screen: gr.update(visible=False),
                 documentation_screen: gr.update(visible=False),
+                settings_screen: gr.update(visible=False),
                 dashboard_nav_btn: gr.update(variant="secondary"),
                 leaderboard_nav_btn: gr.update(variant="secondary"),
                 new_eval_nav_btn: gr.update(variant="secondary"),
@@ -2917,6 +2933,7 @@ No historical data available for **{model}**.
                 chat_nav_btn: gr.update(variant="primary"),
                 synthetic_data_nav_btn: gr.update(variant="secondary"),
                 docs_nav_btn: gr.update(variant="secondary"),
+                settings_nav_btn: gr.update(variant="secondary"),
             }
 
         def navigate_to_synthetic_data():
@@ -2931,6 +2948,7 @@ No historical data available for **{model}**.
                 synthetic_data_screen: gr.update(visible=True),
                 new_evaluation_screen: gr.update(visible=False),
                 documentation_screen: gr.update(visible=False),
+                settings_screen: gr.update(visible=False),
                 dashboard_nav_btn: gr.update(variant="secondary"),
                 leaderboard_nav_btn: gr.update(variant="secondary"),
                 new_eval_nav_btn: gr.update(variant="secondary"),
@@ -2938,6 +2956,7 @@ No historical data available for **{model}**.
                 chat_nav_btn: gr.update(variant="secondary"),
                 synthetic_data_nav_btn: gr.update(variant="primary"),
                 docs_nav_btn: gr.update(variant="secondary"),
+                settings_nav_btn: gr.update(variant="secondary"),
             }
 
         def navigate_to_documentation():
@@ -2952,6 +2971,7 @@ No historical data available for **{model}**.
                 synthetic_data_screen: gr.update(visible=False),
                 new_evaluation_screen: gr.update(visible=False),
                 documentation_screen: gr.update(visible=True),
+                settings_screen: gr.update(visible=False),
                 dashboard_nav_btn: gr.update(variant="secondary"),
                 leaderboard_nav_btn: gr.update(variant="secondary"),
                 new_eval_nav_btn: gr.update(variant="secondary"),
@@ -2959,6 +2979,30 @@ No historical data available for **{model}**.
                 chat_nav_btn: gr.update(variant="secondary"),
                 synthetic_data_nav_btn: gr.update(variant="secondary"),
                 docs_nav_btn: gr.update(variant="primary"),
+                settings_nav_btn: gr.update(variant="secondary"),
+            }
+
+        def navigate_to_settings():
+            """Navigate to settings screen"""
+            return {
+                dashboard_screen: gr.update(visible=False),
+                leaderboard_screen: gr.update(visible=False),
+                run_detail_screen: gr.update(visible=False),
+                trace_detail_screen: gr.update(visible=False),
+                compare_screen: gr.update(visible=False),
+                chat_screen: gr.update(visible=False),
+                synthetic_data_screen: gr.update(visible=False),
+                new_evaluation_screen: gr.update(visible=False),
+                documentation_screen: gr.update(visible=False),
+                settings_screen: gr.update(visible=True),
+                dashboard_nav_btn: gr.update(variant="secondary"),
+                leaderboard_nav_btn: gr.update(variant="secondary"),
+                new_eval_nav_btn: gr.update(variant="secondary"),
+                compare_nav_btn: gr.update(variant="secondary"),
+                chat_nav_btn: gr.update(variant="secondary"),
+                synthetic_data_nav_btn: gr.update(variant="secondary"),
+                docs_nav_btn: gr.update(variant="secondary"),
+                settings_nav_btn: gr.update(variant="primary"),
             }
 
         # Synthetic Data Generator Callbacks
@@ -3277,24 +3321,24 @@ Result: {result}
             fn=navigate_to_dashboard,
             outputs=[
                 dashboard_screen, leaderboard_screen, run_detail_screen, trace_detail_screen, compare_screen, chat_screen, synthetic_data_screen,
-                new_evaluation_screen, documentation_screen,
-                                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn
+                new_evaluation_screen, documentation_screen, settings_screen,
+                                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn, settings_nav_btn
             ] + list(dashboard_components.values())
         )
 
         leaderboard_nav_btn.click(
             fn=navigate_to_leaderboard,
             outputs=[
-                dashboard_screen, leaderboard_screen, run_detail_screen, trace_detail_screen, compare_screen, chat_screen, synthetic_data_screen, new_evaluation_screen, documentation_screen,
-                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn
+                dashboard_screen, leaderboard_screen, run_detail_screen, trace_detail_screen, compare_screen, chat_screen, synthetic_data_screen, new_evaluation_screen, documentation_screen, settings_screen,
+                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn, settings_nav_btn
             ]
         )
 
         new_eval_nav_btn.click(
             fn=navigate_to_new_evaluation,
             outputs=[
-                dashboard_screen, leaderboard_screen, run_detail_screen, trace_detail_screen, compare_screen, chat_screen, synthetic_data_screen, new_evaluation_screen, documentation_screen,
-                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn
+                dashboard_screen, leaderboard_screen, run_detail_screen, trace_detail_screen, compare_screen, chat_screen, synthetic_data_screen, new_evaluation_screen, documentation_screen, settings_screen,
+                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn, settings_nav_btn
             ]
         )
 
@@ -3302,7 +3346,7 @@ Result: {result}
             fn=navigate_to_compare,
             outputs=[
                 dashboard_screen, leaderboard_screen, run_detail_screen, trace_detail_screen, compare_screen, chat_screen, synthetic_data_screen,
-                new_evaluation_screen, documentation_screen,
+                new_evaluation_screen, documentation_screen, settings_screen,
                                 dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn,
                 compare_components['compare_run_a_dropdown'], compare_components['compare_run_b_dropdown']
             ]
@@ -3312,16 +3356,16 @@ Result: {result}
             fn=navigate_to_chat,
             outputs=[
                 dashboard_screen, leaderboard_screen, run_detail_screen, trace_detail_screen, compare_screen, chat_screen, synthetic_data_screen,
-                new_evaluation_screen, documentation_screen,
-                                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn
+                new_evaluation_screen, documentation_screen, settings_screen,
+                                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn, settings_nav_btn
             ]
         )
         synthetic_data_nav_btn.click(
             fn=navigate_to_synthetic_data,
             outputs=[
                 dashboard_screen, leaderboard_screen, run_detail_screen, trace_detail_screen, compare_screen, chat_screen, synthetic_data_screen,
-                new_evaluation_screen, documentation_screen,
-                                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn
+                new_evaluation_screen, documentation_screen, settings_screen,
+                                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn, settings_nav_btn
             ]
         )
 
@@ -3329,8 +3373,17 @@ Result: {result}
             fn=navigate_to_documentation,
             outputs=[
                 dashboard_screen, leaderboard_screen, run_detail_screen, trace_detail_screen, compare_screen, chat_screen, synthetic_data_screen,
-                new_evaluation_screen, documentation_screen,
-                                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn
+                new_evaluation_screen, documentation_screen, settings_screen,
+                                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn, settings_nav_btn
+            ]
+        )
+
+        settings_nav_btn.click(
+            fn=navigate_to_settings,
+            outputs=[
+                dashboard_screen, leaderboard_screen, run_detail_screen, trace_detail_screen, compare_screen, chat_screen, synthetic_data_screen,
+                new_evaluation_screen, documentation_screen, settings_screen,
+                                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn, settings_nav_btn
             ]
         )
 
@@ -3352,7 +3405,7 @@ Result: {result}
             fn=navigate_to_leaderboard,
             outputs=[
                 dashboard_screen, leaderboard_screen, run_detail_screen, trace_detail_screen, compare_screen, chat_screen, synthetic_data_screen, new_evaluation_screen, documentation_screen,
-                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn
+                dashboard_nav_btn, leaderboard_nav_btn, new_eval_nav_btn, compare_nav_btn, chat_nav_btn, synthetic_data_nav_btn, docs_nav_btn, settings_nav_btn
             ]
         )
 

screens/settings.py

@@ -0,0 +1,214 @@
+"""
+Settings Screen for TraceMind-AI
+Allows users to configure API keys for Gemini and HuggingFace
+"""
+
+import gradio as gr
+import os
+
+
+def create_settings_screen():
+    """
+    Create the settings screen for API key configuration
+
+    Returns:
+        gr.Column: Gradio Column component for settings (can be shown/hidden)
+    """
+    with gr.Column(visible=False) as settings_interface:
+        gr.Markdown("""
+        # ⚙️ Settings
+
+        Configure your API keys to use TraceMind features. These keys are stored only in your browser session and are never saved to our servers.
+        """)
+
+        with gr.Accordion("🔑 API Key Configuration", open=True):
+            gr.Markdown("""
+            ### Why provide API keys?
+
+            TraceMind uses external services to provide intelligent analysis and insights:
+            - **Google Gemini API**: Powers the MCP server for leaderboard analysis, cost estimation, and trace debugging
+            - **HuggingFace Token**: Required to access evaluation datasets and results
+
+            **For Judges & Visitors**: Please enter your own API keys to prevent credit issues during evaluation.
+            """)
+
+            # Gemini API Key
+            with gr.Row():
+                with gr.Column(scale=4):
+                    gemini_api_key = gr.Textbox(
+                        label="Google Gemini API Key",
+                        placeholder="Enter your Gemini API key (starts with 'AIza...')",
+                        type="password",
+                        value=os.environ.get("GEMINI_API_KEY", ""),
+                        info="Get your free API key at: https://ai.google.dev/"
+                    )
+                with gr.Column(scale=1):
+                    gemini_status = gr.Markdown("⚪ Not configured")
+
+            # HuggingFace Token
+            with gr.Row():
+                with gr.Column(scale=4):
+                    hf_token = gr.Textbox(
+                        label="HuggingFace Token",
+                        placeholder="Enter your HF token (starts with 'hf_...')",
+                        type="password",
+                        value=os.environ.get("HF_TOKEN", ""),
+                        info="Get your token at: https://huggingface.co/settings/tokens"
+                    )
+                with gr.Column(scale=1):
+                    hf_status = gr.Markdown("⚪ Not configured")
+
+            # Save button
+            with gr.Row():
+                save_btn = gr.Button("💾 Save API Keys", variant="primary")
+                test_btn = gr.Button("🧪 Test Connection", variant="secondary")
+
+            # Status message
+            status_message = gr.Markdown("")
+
+        with gr.Accordion("📖 How to Get API Keys", open=False):
+            gr.Markdown("""
+            ### Google Gemini API Key
+
+            1. Go to [Google AI Studio](https://ai.google.dev/)
+            2. Click "Get API Key" in the top right
+            3. Create a new project or select an existing one
+            4. Generate an API key
+            5. Copy the key (starts with `AIza...`)
+
+            **Free Tier**: 60 requests per minute, suitable for testing and demos
+
+            ---
+
+            ### HuggingFace Token
+
+            1. Go to [HuggingFace Settings](https://huggingface.co/settings/tokens)
+            2. Click "New token"
+            3. Give it a name (e.g., "TraceMind Access")
+            4. Select "Read" permissions
+            5. Create and copy the token (starts with `hf_...`)
+
+            **Note**: Read-only access is sufficient for viewing datasets
+            """)
+
+        with gr.Accordion("🔒 Privacy & Security", open=False):
+            gr.Markdown("""
+            ### Your Privacy Matters
+
+            - ✅ **Session-only storage**: API keys are stored only in your browser session
+            - ✅ **No server storage**: Keys are never saved to our servers or databases
+            - ✅ **HTTPS encryption**: All API calls are made over secure connections
+            - ✅ **No logging**: API keys are not logged or tracked
+
+            ### Best Practices
+
+            - 🔐 Use dedicated API keys for testing/demos
+            - 🔄 Rotate your keys regularly
+            - 🚫 Don't share your keys publicly
+            - 📊 Monitor your API usage on provider dashboards
+
+            ### Rate Limits
+
+            **Gemini API (Free Tier)**:
+            - 60 requests per minute
+            - 1,500 requests per day
+
+            **HuggingFace**:
+            - Read access: No strict limits
+            - Public datasets: Unlimited reads
+            """)
+
+        # Define save functionality
+        def save_api_keys(gemini_key, hf_key):
+            """Save API keys to session"""
+            messages = []
+
+            # Validate and save Gemini API key
+            if gemini_key and gemini_key.strip():
+                if gemini_key.startswith("AIza"):
+                    os.environ["GEMINI_API_KEY"] = gemini_key.strip()
+                    messages.append("✅ Gemini API key saved")
+                    gemini_status_text = "✅ Configured"
+                else:
+                    messages.append("⚠️ Invalid Gemini API key format (should start with 'AIza')")
+                    gemini_status_text = "❌ Invalid format"
+            else:
+                messages.append("⚠️ Gemini API key not provided")
+                gemini_status_text = "⚪ Not configured"
+
+            # Validate and save HuggingFace token
+            if hf_key and hf_key.strip():
+                if hf_key.startswith("hf_"):
+                    os.environ["HF_TOKEN"] = hf_key.strip()
+                    messages.append("✅ HuggingFace token saved")
+                    hf_status_text = "✅ Configured"
+                else:
+                    messages.append("⚠️ Invalid HuggingFace token format (should start with 'hf_')")
+                    hf_status_text = "❌ Invalid format"
+            else:
+                messages.append("⚠️ HuggingFace token not provided")
+                hf_status_text = "⚪ Not configured"
+
+            status_msg = "\n\n".join(messages)
+            status_msg += "\n\n**Note**: Keys are saved for this session only and will be used for MCP server calls."
+
+            return status_msg, gemini_status_text, hf_status_text
+
+        def test_api_keys(gemini_key, hf_key):
+            """Test API key connections"""
+            results = []
+
+            # Test Gemini API
+            if gemini_key and gemini_key.strip():
+                try:
+                    import google.generativeai as genai
+                    genai.configure(api_key=gemini_key.strip())
+                    # Try to list models as a test
+                    models = genai.list_models()
+                    results.append("✅ **Gemini API**: Connection successful!")
+                except Exception as e:
+                    results.append(f"❌ **Gemini API**: Connection failed - {str(e)}")
+            else:
+                results.append("⚠️ **Gemini API**: No key provided")
+
+            # Test HuggingFace token
+            if hf_key and hf_key.strip():
+                try:
+                    from huggingface_hub import HfApi
+                    api = HfApi(token=hf_key.strip())
+                    # Try to get user info as a test
+                    user_info = api.whoami()
+                    results.append(f"✅ **HuggingFace**: Connection successful! (User: {user_info['name']})")
+                except Exception as e:
+                    results.append(f"❌ **HuggingFace**: Connection failed - {str(e)}")
+            else:
+                results.append("⚠️ **HuggingFace**: No token provided")
+
+            return "\n\n".join(results)
+
+        # Wire up button events (api_name=False to prevent API key exposure)
+        save_btn.click(
+            fn=save_api_keys,
+            inputs=[gemini_api_key, hf_token],
+            outputs=[status_message, gemini_status, hf_status],
+            api_name=False  # IMPORTANT: Prevents API key exposure via Gradio API
+        )
+
+        test_btn.click(
+            fn=test_api_keys,
+            inputs=[gemini_api_key, hf_token],
+            outputs=[status_message],
+            api_name=False  # IMPORTANT: Prevents API key exposure via Gradio API
+        )
+
+        # Return both the interface and the input components for external access
+        return settings_interface, gemini_api_key, hf_token
+
+
+if __name__ == "__main__":
+    # For standalone testing
+    with gr.Blocks() as demo:
+        settings_screen, _, _ = create_settings_screen()
+        # Make it visible for standalone testing
+        settings_screen.visible = True
+    demo.launch()