Add Tavily API key UI configuration and update documentation

Major enhancements:
- Add runtime Tavily API key configuration via UI sidebar (no restart required)
- Refactor agent creation to use factory pattern for dynamic configuration
- Add example prompts display in UI to help users get started
- Update README with current code structure and new features
- Keep data directory structure with .gitkeep

Technical changes:
- Convert MCP server configs to factory functions for dynamic instantiation
- Change agent initialization from singleton to factory pattern
- Add update_api_key() method to CustomGradioUI for runtime reconfiguration
- Increase max_steps from 6 to 10 for more complex reasoning tasks
- Use get_token() from huggingface_hub for cleaner token management
- Format code with ruff

Documentation updates:
- Update all line number references in README architecture section
- Document new Tavily UI configuration option as recommended approach
- Clarify that Tavily API key is now optional (can be set via UI or env var)
- Update CLI command from huggingface-cli to hf auth login
- Fix repository clone URL to use MCP-1st-Birthday namespace
- Update acknowledgments from DuckDuckGo to Tavily search

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.gitignore

@@ -80,3 +80,4 @@ dmypy.json
 
 # Project Files
 data/*
+!data/.gitkeep

README.md

@@ -41,36 +41,44 @@ An agentic deep research application powered by [smolagents](https://huggingface
 
 DeepSpaceSearch consists of two main Python files working together:
 
-### MCP Integration (`app.py:55-95`)
+### MCP Integration (`app.py:57-96`)
+
 - **MCP Servers**: Three integrated MCP servers for extended capabilities
-  - **Gradio Upload MCP** (`upload_files_to_gradio`): Uploads files to Gradio Space for processing
-  - **Sa2VA Image Analysis** (`image_analysis_mcp`): Visual question answering and image segmentation
-  - **Tavily Search** (`tavily_search_mcp`): High-quality web search API
+  - **Gradio Upload MCP** (`get_upload_files_to_gradio_server`): Uploads files to Gradio Space for processing
+  - **Sa2VA Image Analysis** (`get_image_analysis_mcp`): Visual question answering and image segmentation
+  - **Tavily Search** (`get_tavily_search_mcp`): High-quality web search API (optional, requires API key)
 - **`MCPClient`**: Manages MCP server connections and provides tools to the agent
-- **Structured Output**: Enabled for consistent tool responses
+- **Dynamic Agent Creation**: Agent factory function allows runtime API key configuration
+
+### Agent System (`app.py:99-157`)
 
-### Agent System (`app.py:98-142`)
-- **`CodeAgent`**: Core reasoning engine from smolagents (line 118-133)
+- **`CodeAgent`**: Core reasoning engine from smolagents (line 133-148)
 - Orchestrates multi-step tasks with planning intervals
-- Configuration: max_steps=6, verbosity_level=1, planning_interval=3
+- Configuration: max_steps=10, verbosity_level=1, planning_interval=3
 - Loads custom instructions from `instructions.txt` for agent behavior guidance
 - Additional authorized imports enabled for code execution flexibility
 
-### Tool Ecosystem (`app.py:36-42, 92-95`)
+### Tool Ecosystem (`app.py:38-42, 136-142`)
+
 - **`image_generation_tool`**: Remote tool from HF Space (black-forest-labs/FLUX.1-schnell)
 - **MCP Tools**: Dynamically loaded from MCP servers (Tavily search, image analysis, file upload)
 - **`FinalAnswerTool`**: Required for agent to return structured responses
 - **Base Tools Disabled**: Custom tool selection for optimized performance
 
-### Model Layer (`app.py:98-110`)
+### Model Layer (`app.py:118-125`)
+
 - **`InferenceClientModel`**: Wrapper around Hugging Face Inference API
 - Default model: `Qwen/Qwen2.5-Coder-32B-Instruct` (configurable via `HF_MODEL_ID` env var)
 - Parameters: max_tokens=2096, temperature=0.5, top_p=0.95
+- Token authentication via `get_token()` from huggingface_hub
+
+### Custom UI (`my_ui.py:7-176`)
 
-### Custom UI (`my_ui.py:7-124`)
 - **`CustomGradioUI`**: Extends smolagents' `GradioUI` with custom features
 - **Sidebar Layout**: Text input, submit button, and file upload in sidebar
 - **File Upload**: Supports multiple file types with custom allowed extensions
+- **Tavily API Key Input**: Runtime configuration of Tavily search without environment variables
+- **Examples Display**: Pre-configured example prompts to help users get started
 - **Ocean Theme**: Professional blue gradient interface
 - **Streaming Chat**: Real-time display of agent reasoning with LaTeX support
 
@@ -88,7 +96,7 @@ DeepSpaceSearch consists of two main Python files working together:
 
 ```bash
 # Clone the repository
-git clone https://huggingface.co/spaces/YOUR_USERNAME/DeepSpaceSearch
+git clone https://huggingface.co/spaces/MCP-1st-Birthday/DeepSpaceSearch
 cd DeepSpaceSearch
 
 # Create and activate virtual environment
@@ -108,7 +116,7 @@ pip install -r requirements.txt
 The easiest and most secure way to authenticate locally is using the Hugging Face CLI:
 
 ```bash
-huggingface-cli login
+hf auth login
 ```
 
 This will prompt you to paste your HF token (get one at <https://huggingface.co/settings/tokens> with `inference-api` scope) and securely store it in `~/.cache/huggingface/token`.
@@ -121,10 +129,17 @@ If you prefer environment variables, create a `.env` file:
 HF_TOKEN=hf_...  # Your HF token with inference-api scope
 ```
 
-**2. Tavily API Key (Required for Web Search)**
+**2. Tavily API Key (Optional for Web Search)**
+
+DeepSpaceSearch uses Tavily for high-quality web search via MCP. Get a free API key at <https://tavily.com>.
+
+You can configure Tavily in two ways:
 
-DeepSpaceSearch uses Tavily for high-quality web search via MCP. Get a free API key at <https://tavily.com>:
+**Option A: Via the UI (Recommended)**
+- Simply enter your API key in the "Tavily API Key" field in the sidebar when using the application
+- No need to set environment variables or restart the app
 
+**Option B: Via Environment Variable**
 ```bash
 # Add to your .env file
 TAVILY_API_KEY=tvly-...  # Your Tavily API key
@@ -143,6 +158,8 @@ Example `.env` with all variables:
 ```env
 # Required
 HF_TOKEN=hf_...
+
+# Optional: Configure Tavily API key (can also be set via UI)
 TAVILY_API_KEY=tvly-...
 
 # Optional: Use a different model
@@ -155,7 +172,7 @@ HF_MODEL_ID=meta-llama/Llama-3.3-70B-Instruct
 python app.py
 ```
 
-The application will launch at http://127.0.0.1:7860
+The application will launch at <http://127.0.0.1:7860>
 
 ## Usage
 
@@ -272,6 +289,7 @@ your_tool = Tool.from_space(
 ## TODO
 
 ### MCP Server Integration
+
 - [x] **Integrate MCP servers using smolagents** ✅
   - Implemented three MCP servers: Tavily search, Sa2VA image analysis, and Gradio file upload
   - Using both stdio and HTTP-based MCP transports
@@ -289,6 +307,7 @@ your_tool = Tool.from_space(
   - Social media trend analysis
 
 ### Enhanced Research Capabilities
+
 - [ ] **Multi-source verification**
   - Cross-reference information across multiple sources
   - Add confidence scoring for research findings
@@ -305,6 +324,7 @@ your_tool = Tool.from_space(
   - Export to PDF/DOCX
 
 ### Tool Improvements
+
 - [ ] **Add calculator tool** for mathematical queries
 - [ ] **Add code execution tool** for running Python snippets
 - [ ] **Add data visualization tool** for charts and graphs
@@ -312,6 +332,7 @@ your_tool = Tool.from_space(
   - Implemented with support for PDF, DOCX, TXT, MD, JSON, CSV, and images
 
 ### UI/UX Enhancements
+
 - [ ] **Add conversation history** persistence
 - [ ] **Add export chat** functionality
 - [ ] **Add model selection** dropdown for different LLMs
@@ -319,12 +340,14 @@ your_tool = Tool.from_space(
 - [ ] **Dark mode** support
 
 ### Performance & Reliability
+
 - [ ] **Add caching** for repeated searches
 - [ ] **Implement retry logic** for failed API calls
 - [ ] **Add rate limiting** dashboard
 - [ ] **Optimize token usage** with streaming truncation
 
 ### Testing & Documentation
+
 - [ ] **Add unit tests** for core functions
 - [ ] **Add integration tests** for tools
 - [ ] **Create video demo** of capabilities
@@ -343,4 +366,4 @@ Apache 2.0 - See LICENSE file for details
 - Built with [smolagents](https://huggingface.co/docs/smolagents) by Hugging Face
 - UI powered by [Gradio](https://gradio.app)
 - Image generation by [FLUX.1-schnell](https://huggingface.co/black-forest-labs/FLUX.1-schnell)
-- Search powered by [DuckDuckGo](https://duckduckgo.com)
+- Search powered by [Tavily](https://app.tavily.com)

app.py

@@ -2,6 +2,7 @@ import os
 import warnings
 
 from dotenv import load_dotenv
+from huggingface_hub import get_token
 from mcp import StdioServerParameters
 from smolagents import (
     CodeAgent,
@@ -52,19 +53,23 @@ image_generation_tool = Tool.from_space(
 #     api_name="/image_vision",
 # )
 
+
 # MCP Servers
-upload_files_to_gradio = StdioServerParameters(
-    command="uvx",  # Using uvx ensures dependencies are available
-    args=[
-        "--from",
-        "gradio[mcp]",
-        "gradio",
-        "upload-mcp",
-        "https://fffiloni-sa2va-simple-demo.hf.space/",
-        "./data",
-    ],
-    env={"UV_PYTHON": "3.12", **os.environ},
-)
+def get_upload_files_to_gradio_server():
+    """Get the upload files to Gradio MCP server configuration."""
+    return StdioServerParameters(
+        command="uvx",  # Using uvx ensures dependencies are available
+        args=[
+            "--from",
+            "gradio[mcp]",
+            "gradio",
+            "upload-mcp",
+            "https://fffiloni-sa2va-simple-demo.hf.space/",
+            "./data",
+        ],
+        env={"UV_PYTHON": "3.12", **os.environ},
+    )
+
 
 # groq_compount_beta = StdioServerParameters(
 #     command="uvx",  # Using uvx ensures dependencies are available
@@ -78,26 +83,40 @@ upload_files_to_gradio = StdioServerParameters(
 #     },
 # )
 
-image_analysis_mcp = {
-    "url": "https://fffiloni-sa2va-simple-demo.hf.space/gradio_api/mcp/",
-    "transport": "streamable-http",
-}
 
-tavily_search_mcp = {
-    "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=" + TAVILY_API_KEY,
-    "transport": "streamable-http",
-}
+def get_image_analysis_mcp():
+    """Get the image analysis MCP configuration."""
+    return {
+        "url": "https://fffiloni-sa2va-simple-demo.hf.space/gradio_api/mcp/",
+        "transport": "streamable-http",
+    }
 
 
-# Initialize MCP client at module level to keep it alive
-mcp_client = MCPClient(
-    [upload_files_to_gradio, image_analysis_mcp, tavily_search_mcp], structured_output=True
-)
+def get_tavily_search_mcp(api_key):
+    """Get the Tavily search MCP configuration with the provided API key."""
+    return {
+        "url": f"https://mcp.tavily.com/mcp/?tavilyApiKey={api_key}",
+        "transport": "streamable-http",
+    }
+
+
+def create_agent(tavily_api_key=None):
+    """Create an agent with the specified Tavily API key (or use environment variable)."""
+    # Use provided API key or fall back to environment variable
+    api_key = tavily_api_key or TAVILY_API_KEY
 
+    # Build list of MCP servers - only include Tavily if API key is provided
+    mcp_servers = [
+        get_upload_files_to_gradio_server(),
+        get_image_analysis_mcp(),
+    ]
 
-def create_agent():
-    # Get token from OAuth (HF Spaces) or environment variable (local dev)
-    token = os.getenv("HF_TOKEN")
+    # Only add Tavily search if we have an API key
+    if api_key:
+        mcp_servers.append(get_tavily_search_mcp(api_key))
+
+    # Create MCP client with the appropriate servers
+    mcp_client = MCPClient(mcp_servers, structured_output=False)
 
     # Create model with user-specified parameters
     model = InferenceClientModel(
@@ -106,7 +125,7 @@ def create_agent():
         top_p=0.95,
         model_id=HF_MODEL_ID,
         custom_role_conversions=None,
-        token=token,
+        token=get_token(),  # Get token from HF login (huggingface-cli login) or environment variable (HF_TOKEN)
     )
 
     # Load instructions from file.  This text will be appended to the system prompt.
@@ -120,14 +139,14 @@ def create_agent():
         additional_authorized_imports=["*"],
         tools=[
             image_generation_tool,
-            *mcp_client.get_tools(),  # Use tools from the global MCP client
+            *mcp_client.get_tools(),  # Use tools from the MCP client
             # web_search,
             # visit_webpage,
             final_answer,
         ],
         instructions=instructions,
         add_base_tools=False,
-        max_steps=6,
+        max_steps=10,
         verbosity_level=1,
         planning_interval=3,
     )
@@ -142,8 +161,15 @@ def create_agent():
     return agent
 
 
+# Example prompts for users
+EXAMPLES = [
+    "Search the web for the latest developments in quantum computing and summarize the key findings",
+    "Generate an image of a futuristic city with flying cars and neon lights",
+    "What are the current trends in artificial intelligence research?",
+]
+
 gradio_ui = CustomGradioUI(
-    create_agent(),
+    create_agent,  # Pass the factory function, not the agent instance
     file_upload_folder="./data",
     reset_agent_memory=True,
     allowed_file_types=[
@@ -157,6 +183,7 @@ gradio_ui = CustomGradioUI(
         ".jpeg",
         ".jpg",
     ],  # Customize this list!
+    examples=EXAMPLES,
 )
 
 if __name__ == "__main__":

my_ui.py

@@ -8,10 +8,33 @@ class CustomGradioUI(GradioUI):
     """Custom GradioUI that allows customization of the smolagents default interface."""
 
     def __init__(
-        self, agent, file_upload_folder=None, reset_agent_memory=False, allowed_file_types=None
+        self,
+        agent_factory,
+        file_upload_folder=None,
+        reset_agent_memory=False,
+        allowed_file_types=None,
+        examples=None,
     ):
-        super().__init__(agent, file_upload_folder, reset_agent_memory)
+        # Store the factory function instead of the agent directly
+        self.agent_factory = agent_factory
+        # Create initial agent with no API key (will use env var if available)
+        super().__init__(agent_factory(), file_upload_folder, reset_agent_memory)
         self.allowed_file_types = allowed_file_types or [".pdf", ".docx", ".txt"]
+        self.examples = examples or []
+
+    def update_api_key(self, api_key, current_key):
+        """Update the agent with a new API key."""
+        if api_key and api_key != current_key:
+            # Recreate the agent with the new API key
+            self.agent = self.agent_factory(tavily_api_key=api_key)
+            return api_key, gr.Markdown("✓ API key updated successfully", visible=True)
+        elif not api_key and current_key:
+            # Reset to default (env var)
+            self.agent = self.agent_factory()
+            return "", gr.Markdown(
+                "API key cleared, using environment variable if set", visible=True
+            )
+        return current_key, gr.Markdown("", visible=False)
 
     def create_app(self):
         """Override create_app to use custom allowed_file_types."""
@@ -21,6 +44,7 @@ class CustomGradioUI(GradioUI):
             session_state = gr.State({})
             stored_messages = gr.State([])
             file_uploads_log = gr.State([])
+            current_api_key = gr.State("")  # Store current Tavily API key
 
             with gr.Sidebar():
                 gr.Markdown(
@@ -62,6 +86,28 @@ class CustomGradioUI(GradioUI):
                         [upload_status, file_uploads_log],
                     )
 
+                # Tavily API Key section
+                with gr.Group():
+                    gr.Markdown("**Tavily API Key**", container=True)
+                    gr.Markdown(
+                        "Get your free API key at [tavily.com](https://app.tavily.com/home)",
+                        container=False,
+                    )
+                    tavily_api_key_input = gr.Textbox(
+                        label="API Key (optional)",
+                        type="password",
+                        placeholder="Enter your Tavily API key to enable web search",
+                        container=False,
+                    )
+                    api_key_status = gr.Markdown("", visible=False)
+
+                    # Update agent when API key changes
+                    tavily_api_key_input.change(
+                        self.update_api_key,
+                        [tavily_api_key_input, current_api_key],
+                        [current_api_key, api_key_status],
+                    )
+
                 gr.HTML(
                     "<br><br><h4><center>Powered by <a target='_blank' href='https://github.com/huggingface/smolagents'><b>smolagents</b></a></center></h4>"
                 )
@@ -84,6 +130,14 @@ class CustomGradioUI(GradioUI):
                 ],
             )
 
+            # Add examples if provided
+            if self.examples:
+                gr.Examples(
+                    examples=self.examples,
+                    inputs=text_input,
+                    cache_examples=False,
+                )
+
             # Set up event handlers
             text_input.submit(
                 self.log_user_message,