| # 🏗️ Architecture Overview | |
| ## System Architecture | |
| This Hugging Face Space implements a comparative agent system with three reasoning modes. Here's how everything works together: | |
| ``` | |
| ┌─────────────────────────────────────────────────────────────┐ | |
| │ Gradio UI Layer │ | |
| │ - Question Input │ | |
| │ - Mode Selection (Think/Act/ReAct/All) │ | |
| │ - Three Output Panels (side-by-side comparison) │ | |
| └──────────────────┬──────────────────────────────────────────┘ | |
| │ | |
| ▼ | |
| ┌─────────────────────────────────────────────────────────────┐ | |
| │ Agent Controller │ | |
| │ run_comparison() - Routes to appropriate mode handler │ | |
| └──────────────────┬──────────────────────────────────────────┘ | |
| │ | |
| ┌──────────┴──────────┬──────────────┐ | |
| ▼ ▼ ▼ | |
| ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ | |
| │ Think-Only │ │ Act-Only │ │ ReAct │ | |
| │ Mode │ │ Mode │ │ Mode │ | |
| └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ | |
| │ │ │ | |
| ▼ ▼ ▼ | |
| ┌─────────────────────────────────────────────────────────────┐ | |
| │ LLM Interface │ | |
| │ call_llm() - Communicates with openai/gpt-oss-20b │ | |
| └──────────────────┬──────────────────────────────────────────┘ | |
| │ | |
| ▼ (Act-Only & ReAct modes only) | |
| ┌─────────────────────────────────────────────────────────────┐ | |
| │ Tool Executor │ | |
| │ - parse_action() │ | |
| │ - call_tool() │ | |
| └──────────────────┬──────────────────────────────────────────┘ | |
| │ | |
| ┌───────────┴───────────┬───────────┬───────────┬──────┐ | |
| ▼ ▼ ▼ ▼ ▼ | |
| ┌────────────┐ ┌────────────┐ ┌──────┐ ┌────┐ ┌─────────┐ | |
| │ DuckDuckGo │ │ Wikipedia │ │Weather│ │Calc│ │ Python │ | |
| │ Search │ │ Search │ │ API │ │ │ │ REPL │ | |
| └────────────┘ └────────────┘ └──────┘ └────┘ └─────────┘ | |
| ``` | |
| ## Component Details | |
| ### 1. **Tool Layer** | |
| Each tool is wrapped in a `Tool` class with: | |
| - **name**: Identifier for the LLM to reference | |
| - **description**: Instructions for when/how to use the tool | |
| - **func**: The actual implementation | |
| **Tool Implementations:** | |
| - `duckduckgo_search()`: Uses DuckDuckGo's JSON API | |
| - `wikipedia_search()`: Uses the Wikipedia Python library | |
| - `get_weather()`: Queries wttr.in API for weather data | |
| - `calculate()`: Safe AST-based math expression evaluator | |
| - `python_repl()`: Sandboxed Python execution with whitelisted builtins | |
| ### 2. **Agent Modes** | |
| #### Think-Only Mode (`think_only_mode`) | |
| ``` | |
| User Question → System Prompt → LLM → Thoughts → Answer | |
| ``` | |
| - Single LLM call with CoT prompt | |
| - No tool access | |
| - Shows reasoning steps | |
| - Best for knowledge-based questions | |
| #### Act-Only Mode (`act_only_mode`) | |
| ``` | |
| User Question → System Prompt → LLM → Action | |
| ↓ | |
| Execute Tool → Observation | |
| ↓ | |
| LLM → Action/Answer | |
| ↓ | |
| ... | |
| ``` | |
| - Iterative loop: Action → Observation | |
| - No explicit "Thought" step | |
| - Maximum 5 iterations | |
| - Best for information gathering | |
| #### ReAct Mode (`react_mode`) | |
| ``` | |
| User Question → System Prompt → LLM → Thought → Action | |
| ↓ | |
| Execute Tool → Observation | |
| ↓ | |
| LLM → Thought → Action/Answer | |
| ↓ | |
| ... | |
| ``` | |
| - Full Thought-Action-Observation cycle | |
| - Most comprehensive reasoning | |
| - Maximum 5 iterations | |
| - Best for complex multi-step problems | |
| ### 3. **LLM Interface** | |
| **`call_llm()` Function:** | |
| - Uses Hugging Face Inference API | |
| - Model: openai/gpt-oss-20b | |
| - Supports chat format (messages list) | |
| - Configurable temperature and max_tokens | |
| **Authentication:** | |
| - Requires `HF_TOKEN` environment variable | |
| - Set in Space secrets (secure) | |
| ### 4. **Parsing & Control Flow** | |
| **`parse_action()` Function:** | |
| - Extracts `Action:` and `Action Input:` from LLM response | |
| - Uses regex to handle various formats | |
| - Returns (action_name, action_input) tuple | |
| **Iteration Control:** | |
| - Max 5 iterations per mode to prevent infinite loops | |
| - Early termination when "Answer:" detected | |
| - Error handling for malformed responses | |
| ### 5. **UI Layer (Gradio)** | |
| **Components:** | |
| - **Input Section**: Question textbox + mode dropdown | |
| - **Example Buttons**: Pre-filled question templates | |
| - **Output Panels**: Three side-by-side Markdown displays | |
| - **Streaming**: Generator functions for real-time updates | |
| **User Flow:** | |
| 1. User enters question or clicks example | |
| 2. Selects mode (or "All" for comparison) | |
| 3. Clicks "Run" | |
| 4. Sees real-time updates in output panel(s) | |
| 5. Views final answer and complete reasoning trace | |
| ## Data Flow Example | |
| ### Example: "What's the weather in Paris?" | |
| **Mode: ReAct** | |
| 1. User submits question | |
| 2. `react_mode()` called with question | |
| 3. Prompt formatted with question + tool descriptions | |
| 4. First LLM call: | |
| ``` | |
| Thought: I need to check the current weather in Paris | |
| Action: get_weather | |
| Action Input: Paris | |
| ``` | |
| 5. `parse_action()` extracts tool call | |
| 6. `call_tool("get_weather", "Paris")` executes | |
| 7. Observation: "Weather in Paris: Cloudy, 15°C..." | |
| 8. Second LLM call with observation | |
| 9. LLM responds: | |
| ``` | |
| Thought: I have the weather information | |
| Answer: The current weather in Paris is... | |
| ``` | |
| 10. Generator yields formatted output to UI | |
| 11. User sees complete trace in ReAct panel | |
| ## Key Design Patterns | |
| ### 1. **Generator Pattern for Streaming** | |
| ```python | |
| def mode(question: str) -> Generator[str, None, None]: | |
| yield "Step 1..." | |
| # process | |
| yield "Step 2..." | |
| # etc | |
| ``` | |
| Enables real-time UI updates without blocking | |
| ### 2. **Tool Registry Pattern** | |
| ```python | |
| TOOLS = [Tool(name, description, func), ...] | |
| ``` | |
| Easy to add new tools - just append to list | |
| ### 3. **Prompt Templates** | |
| ```python | |
| PROMPT = """...""".format(question=q, tools=t) | |
| ``` | |
| Modular prompts for each mode | |
| ### 4. **Safe Execution** | |
| - AST parsing for calculator (no `eval()`) | |
| - Whitelisted builtins for Python REPL | |
| - Timeout limits on API calls | |
| - Error handling with fallback messages | |
| ## Extensibility | |
| ### Adding a New Tool | |
| ```python | |
| def my_tool(input: str) -> str: | |
| # Implementation | |
| return result | |
| TOOLS.append(Tool( | |
| name="my_tool", | |
| description="When to use this tool...", | |
| func=my_tool | |
| )) | |
| ``` | |
| ### Adding a New Mode | |
| ```python | |
| def hybrid_mode(question: str) -> Generator[str, None, None]: | |
| # Custom logic mixing elements | |
| yield "Starting hybrid mode..." | |
| # ... | |
| # Add to run_comparison() and UI dropdown | |
| ``` | |
| ### Customizing Prompts | |
| Edit the `*_PROMPT` constants to change agent behavior: | |
| - Add constraints | |
| - Change format | |
| - Provide examples | |
| - Adjust tone | |
| ## Performance Considerations | |
| 1. **API Latency**: Model calls take 2-5 seconds | |
| 2. **Tool Latency**: External APIs add 1-2 seconds per call | |
| 3. **Iteration Count**: 5 iterations max = ~30 seconds worst case | |
| 4. **Parallel Modes**: "All" mode runs sequentially (not parallel) | |
| ## Security Notes | |
| 1. **API Keys**: Never commit `HF_TOKEN` to repo | |
| 2. **Python REPL**: Sandboxed with limited builtins | |
| 3. **User Input**: Sanitized before tool execution | |
| 4. **Rate Limits**: Consider adding rate limiting for production | |
| ## Testing Strategy | |
| 1. **Unit Tests**: Test individual tool functions | |
| 2. **Integration Tests**: Test mode handlers end-to-end | |
| 3. **Prompt Tests**: Verify LLM responses parse correctly | |
| 4. **UI Tests**: Test Gradio interface components | |
| ## Future Enhancements | |
| - [ ] Add memory/conversation history | |
| - [ ] Implement parallel tool calling | |
| - [ ] Add caching layer for repeated queries | |
| - [ ] Support custom user tools | |
| - [ ] Add performance metrics/timing | |
| - [ ] Implement token counting/cost tracking | |
| - [ ] Add export functionality for reasoning traces | |