Initial deployment

.gitignore

@@ -0,0 +1,8 @@
+# .gitignore for HF Space
+__pycache__/
+*.py[cod]
+*$py.class
+*.log
+.env
+.venv
+venv/

DEPLOY.md

@@ -0,0 +1,133 @@
+# HF Space Deployment Instructions
+
+## What's in this folder
+
+This `hf_space` directory contains a **complete, standalone** Hugging Face Space ready to deploy.
+
+### Structure
+
+```
+hf_space/
+├── app.py                    # Entry point for HF Space
+├── README.md                 # Space description with metadata
+├── requirements.txt          # Minimal dependencies
+├── .gitignore               # Git ignore patterns
+├── ui/
+│   ├── gradio_interface.py  # Gradio UI components
+│   ├── remote_client.py     # Modal backend client
+│   └── backend.py           # Backend abstraction
+├── core/
+│   └── models.py            # Pydantic data models
+├── visualization/
+│   └── blaxel_generator.py  # 3D visualization
+├── voice/
+│   └── elevenlabs_tts.py    # Voice TTS (stub)
+└── config/
+    └── api_keys.py          # Config (stub)
+```
+
+## Deployment Steps
+
+### Option 1: Push to Existing Space
+
+If you already have a Space created at https://huggingface.co/spaces/Nihal2000/debuggenie:
+
+```bash
+cd hf_space
+
+# Initialize git if needed
+git init
+git add .
+git commit -m "Initial DebugGenie HF Space deployment"
+
+# Add HF remote
+git remote add hf https://huggingface.co/spaces/Nihal2000/debuggenie
+
+# Push
+git push hf main --force
+```
+
+### Option 2: Create New Space
+
+1. Go to https://huggingface.co/new-space
+2. Create Space:
+   - **Name**: `debuggenie`
+   - **License**: MIT
+   - **SDK**: Gradio
+   - **Hardware**: CPU Basic (free) or upgrade to T4 Small for faster performance
+3. Clone the Space locally:
+   ```bash
+   git clone https://huggingface.co/spaces/Nihal2000/debuggenie
+   ```
+4. Copy contents of `hf_space/` into the cloned directory
+5. Commit and push:
+   ```bash
+   git add .
+   git commit -m "Initial deployment"
+   git push
+   ```
+
+### Configure Secrets
+
+**CRITICAL**: Before the Space will work, you must set the `MODAL_API_URL` secret:
+
+1. Go to your Space settings: https://huggingface.co/spaces/Nihal2000/debuggenie/settings
+2. Navigate to **Repository secrets**
+3. Add a new secret:
+   - **Name**: `MODAL_API_URL`
+   - **Value**: Your Modal endpoint URL (e.g., `https://nihal2000--debuggenie-app-analyze-error.modal.run`)
+
+### Get Modal URL
+
+First, deploy your Modal backend:
+
+```bash
+cd ..  # Back to main debuggenie directory
+modal deploy modal_app.py
+```
+
+Copy the URL from the output (looks like `https://[username]--debuggenie-app-analyze-error.modal.run`).
+
+## Testing Locally
+
+You can test the HF Space locally before pushing:
+
+```bash
+cd hf_space
+
+# Set the Modal URL
+set MODAL_API_URL=https://your-modal-url.modal.run
+
+# Run
+python app.py
+```
+
+## Troubleshooting
+
+### Import Errors
+
+All imports should work because we've included stub files for optional dependencies.
+
+### Modal Connection Errors
+
+1. Verify `MODAL_API_URL` is set in HF Space secrets
+2. Check that Modal backend is deployed and running
+3. Test Modal endpoint directly with curl:
+   ```bash
+   curl -X POST https://your-modal-url.modal.run \
+     -H "Content-Type: application/json" \
+     -d '{"error_text": "test error"}'
+   ```
+
+### Space Not Building
+
+Check the Space logs for build errors. Common issues:
+- Missing dependencies in `requirements.txt`
+- Import errors (check all modules have `__init__.py`)
+
+## Next Steps
+
+After deployment:
+1. Visit your Space: https://huggingface.co/spaces/Nihal2000/debuggenie
+2. Test with a sample error
+3. Share with others!

README.md

@@ -0,0 +1,55 @@
+---
+title: DebugGenie
+emoji: 🧞
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 5.0.0
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# DebugGenie 🧞 - AI Debugging Assistant
+
+**Multi-Agent AI System for Intelligent Error Analysis**
+
+Powered by Claude, Gemini, and GPT-4 working together to solve your bugs.
+
+## Features
+
+- 🤖 **Multi-Agent Analysis**: Three specialized AI agents collaborate to debug your errors
+- 🎨 **3D Error Flow Visualization**: Interactive visualization of execution paths
+- 🔊 **Voice Explanations**: AI-generated voice walkthroughs of solutions
+- 📊 **Confidence Scoring**: Each solution ranked by probability of success
+- 🧩 **Context-Aware**: Upload screenshots, code files, and stack traces
+
+## Architecture
+
+This Space is the **frontend** for DebugGenie. The heavy AI processing runs on Modal's serverless infrastructure.
+
+- **Frontend**: Lightweight Gradio UI (this Space)
+- **Backend**: Modal serverless functions with GPU support
+- **Communication**: Secure HTTPS API calls
+
+## Usage
+
+1. Paste your error message or stack trace
+2. Optionally upload a screenshot or code files
+3. Click "Analyze Error"
+4. Get AI-powered solutions with confidence scores
+
+## Configuration
+
+This Space requires a `MODAL_API_URL` secret pointing to the deployed Modal backend.
+
+## Tech Stack
+
+- Gradio 5.0
+- Pydantic for data validation
+- Plotly for visualizations
+- Requests for backend communication
+
+## License
+
+MIT License - See LICENSE file for details

app.py

@@ -0,0 +1,19 @@
+import os
+import gradio as gr
+from ui.gradio_interface import create_interface
+from ui.remote_client import RemoteBackend
+
+# Get Modal API URL from environment variable
+MODAL_API_URL = os.environ.get("MODAL_API_URL")
+
+if not MODAL_API_URL:
+    raise ValueError("MODAL_API_URL environment variable is not set. Please configure it in Hugging Face Space secrets.")
+
+# Initialize remote backend
+backend = RemoteBackend(api_url=MODAL_API_URL)
+
+# Create interface
+demo = create_interface(backend)
+
+if __name__ == "__main__":
+    demo.launch()

config/__init__.py

@@ -0,0 +1 @@
+# Empty __init__.py file

config/api_keys.py

@@ -0,0 +1,10 @@
+# Stub for api_keys module to avoid import errors in HF Space
+# In the HF deployment, we don't need the full api_keys config since
+# the UI only talks to the remote Modal backend.
+
+class APIConfig:
+    def __init__(self):
+        # Stub - only needed for imports, not actually used
+        self.elevenlabs_api_key = ""
+
+api_config = APIConfig()

core/__init__.py

@@ -0,0 +1 @@
+# Empty __init__.py file

core/models.py

@@ -0,0 +1,21 @@
+from typing import List, Dict, Any, Optional
+from pydantic import BaseModel, Field
+
+class DebugResult(BaseModel):
+    root_cause: str
+    solutions: List[Dict[str, Any]]
+    fix_instructions: str
+    confidence_score: float
+    agent_metrics: Dict[str, Any]
+    execution_time: float
+
+class RankedSolution(BaseModel):
+    rank: int
+    title: str
+    description: str
+    steps: List[str]
+    code_changes: List[dict] = Field(default_factory=list)
+    confidence: float
+    sources: List[str] = Field(default_factory=list)
+    why_ranked_here: str
+    trade_offs: List[str] = Field(default_factory=list)

requirements.txt

@@ -0,0 +1,6 @@
+gradio>=5.0
+requests>=2.32.3
+pydantic>=2.0.0
+plotly>=5.0.0
+loguru>=0.7.0
+Pillow>=10.0.0

ui/__init__.py

@@ -0,0 +1 @@
+# Empty __init__.py file

ui/backend.py

@@ -0,0 +1,19 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+from core.models import DebugResult
+
+class DebugBackend(ABC):
+    @abstractmethod
+    async def analyze(self, context: Dict[str, Any]) -> DebugResult:
+        pass
+
+class LocalBackend(DebugBackend):
+    def __init__(self):
+        from core.orchestrator import DebugOrchestrator
+        self.orchestrator = DebugOrchestrator()
+        
+    async def analyze(self, context: Dict[str, Any]) -> DebugResult:
+        return await self.orchestrator.orchestrate_debug(
+            error_context=context,
+            stream_callback=None
+        )

ui/gradio_interface.py

@@ -0,0 +1,342 @@
+import gradio as gr
+import asyncio
+from typing import List, Dict, Any, Optional
+from loguru import logger
+import json
+import os
+
+# Import core components
+from ui.backend import DebugBackend, LocalBackend
+from core.models import RankedSolution
+from visualization.blaxel_generator import ErrorFlowVisualizer
+from voice.elevenlabs_tts import VoiceExplainer
+from config.api_keys import api_config
+
+class DebugGenieUI:
+    def __init__(self, backend: DebugBackend):
+        self.backend = backend
+        self.visualizer = ErrorFlowVisualizer()
+        
+        # Initialize voice explainer if API key is available
+        try:
+            self.voice_explainer = VoiceExplainer(api_key=api_config.elevenlabs_api_key)
+        except:
+            logger.warning("ElevenLabs API key not found - voice features disabled")
+            self.voice_explainer = None
+        
+    async def handle_analyze(
+        self, 
+        error_text: str, 
+        screenshot, 
+        codebase_files,
+        progress=gr.Progress()
+    ):
+        """Main analysis handler with progressive updates."""
+        try:
+            # Initialize outputs
+            chat_history = []
+            solutions_html = ""
+            viz_html = ""
+            voice_audio = None
+            analysis_json = {}
+            
+            # Validate inputs
+            if not error_text and screenshot is None:
+                return (
+                    [["❌ Error", "Please provide either an error message or a screenshot."]],
+                    "<div>No analysis performed.</div>",
+                    "<div>No visualization available.</div>",
+                    None,
+                    {},
+                    "Status: ❌ Missing input"
+                )
+            
+            progress(0.1, desc="Starting analysis...")
+            chat_history.append({"role": "user", "content": f"Analyze this error:\n```\n{error_text[:200]}...\n```"})
+            
+            # Build context
+            context = {
+                'error_text': error_text,
+                'image': screenshot,
+                'code_context': ""
+            }
+            
+            # Add screenshot context if provided
+            if screenshot is not None:
+                context['type'] = 'ide'  # Could be auto-detected
+                
+            progress(0.2, desc="Running multi-agent analysis...")
+            
+            # Run backend analysis
+            result = await self.backend.analyze(context)
+            
+            progress(0.7, desc="Generating visualizations...")
+            
+            # Build chat response
+            response_text = f"""
+## 🎯 Root Cause
+{result.root_cause}
+
+## ✅ Recommended Solutions
+"""
+            for idx, sol in enumerate(result.solutions[:3], 1):
+                response_text += f"\n### {idx}. {sol.get('title', 'Solution')}\n"
+                response_text += f"{sol.get('description', '')}\n"
+                response_text += f"**Confidence:** {sol.get('probability', 0):.0%}\n"
+            
+            chat_history.append({"role": "assistant", "content": response_text})
+            
+            # Generate solutions accordion HTML
+            solutions_html = self._generate_solutions_html(result.solutions)
+            
+            # Generate 3D visualization if we have stack trace
+            # For demo, create a mock trace
+            mock_trace = self.visualizer.generate_mock_trace()
+            viz_html = self.visualizer.generate_flow(mock_trace)
+            
+            # Build analysis JSON
+            analysis_json = {
+                "execution_time": f"{result.execution_time:.2f}s",
+                "confidence": result.confidence_score,
+                "agents_used": list(result.agent_metrics.keys()),
+                "metrics": result.agent_metrics
+            }
+            
+            # Generate voice explanation for top solution
+            progress(0.9, desc="Generating voice explanation...")
+            if self.voice_explainer and result.solutions:
+                try:
+                    # Convert first solution to RankedSolution format
+                    top_solution = result.solutions[0]
+                    ranked_sol = RankedSolution(
+                        rank=1,
+                        title=top_solution.get('title', 'Solution'),
+                        description=top_solution.get('description', ''),
+                        steps=[], # Would parse from fix_instructions
+                        confidence=top_solution.get('probability', 0.5),
+                        sources=[],
+                        why_ranked_here=f"Top ranked solution with {top_solution.get('probability', 0)*100:.0f}% confidence",
+                        trade_offs=[]
+                    )
+                    
+                    audio_bytes = self.voice_explainer.generate_explanation(
+                        ranked_sol, 
+                        mode="walkthrough"
+                    )
+                    
+                    if audio_bytes:
+                        # Save to temp file for Gradio
+                        voice_path = self.voice_explainer.save_audio(
+                            audio_bytes, 
+                            f"explanation_{hash(error_text[:100])}.mp3"
+                        )
+                        voice_audio = voice_path
+                except Exception as e:
+                    logger.warning(f"Voice generation failed: {e}")
+                    voice_audio = None
+            
+            progress(1.0, desc="Complete!")
+            
+            return (
+                chat_history,
+                solutions_html,
+                viz_html,
+                voice_audio,
+                analysis_json,
+                f"Status: ✅ Analysis complete in {result.execution_time:.2f}s"
+            )
+            
+        except Exception as e:
+            logger.error(f"Analysis failed: {e}")
+            return (
+                [[f"❌ Error", f"Analysis failed: {str(e)}"]],
+                f"<div class='error'>Error: {str(e)}</div>",
+                "<div>Visualization unavailable</div>",
+                None,
+                {"error": str(e)},
+                f"Status: ❌ Failed - {str(e)}"
+            )
+    
+    def _generate_solutions_html(self, solutions: List[Dict]) -> str:
+        """Generate HTML for solutions accordion."""
+        if not solutions:
+            return "<div>No solutions found.</div>"
+        
+        html = "<div style='font-family: sans-serif;'>"
+        
+        for idx, sol in enumerate(solutions, 1):
+            title = sol.get('title', f'Solution {idx}')
+            desc = sol.get('description', 'No description')
+            prob = sol.get('probability', 0.5)
+            
+            # Color code by probability
+            color = "green" if prob > 0.7 else "orange" if prob > 0.4 else "red"
+            
+            html += f"""
+            <details style='border: 2px solid {color}; border-radius: 8px; padding: 16px; margin: 12px 0;'>
+                <summary style='font-size: 18px; font-weight: bold; cursor: pointer;'>
+                    {idx}. {title} 
+                    <span style='color: {color}; float: right;'>
+                        {prob:.0%} confidence
+                    </span>
+                </summary>
+                <div style='margin-top: 12px; padding: 12px; background: #f5f5f5; border-radius: 4px;'>
+                    <p>{desc}</p>
+                </div>
+            </details>
+            """
+        
+        html += "</div>"
+        return html
+
+def create_interface(backend: DebugBackend):
+    """Create the main Gradio interface."""
+    ui = DebugGenieUI(backend)
+    
+    with gr.Blocks(
+        title="DebugGenie 🧞",
+        theme=gr.themes.Soft(
+            primary_hue="blue",
+            secondary_hue="purple"
+        ),
+        css="""
+        .gradio-container {
+            font-family: 'Inter', sans-serif;
+        }
+        .error {
+            color: red;
+            padding: 16px;
+            background: #fee;
+            border-radius: 8px;
+        }
+        """
+    ) as demo:
+        
+        gr.Markdown(
+            """
+            # 🧞 DebugGenie - AI Debugging Assistant
+            ### Multi-Agent AI System for Intelligent Error Analysis
+            
+            Powered by Claude, Gemini, and GPT-4 working together to solve your bugs.
+            """
+        )
+        
+        with gr.Row():
+            with gr.Column(scale=1):
+                gr.Markdown("## 📝 Input")
+                
+                error_input = gr.Code(
+                    label="Paste Error Message / Stack Trace",
+                    language="python",
+                    lines=10
+                )
+                
+                screenshot_input = gr.Image(
+                    label="Upload Screenshot (Optional)",
+                    type="pil",
+                    sources=["upload", "clipboard"]
+                )
+                
+                codebase_files = gr.File(
+                    label="Upload Codebase Files (Optional)",
+                    file_count="multiple"
+                )
+                
+                analyze_btn = gr.Button(
+                    "🔍 Analyze Error",
+                    variant="primary",
+                    size="lg"
+                )
+                
+                gr.Markdown(
+                    """
+                    ---
+                    **Tips:**
+                    - Paste complete error traces for best results
+                    - Screenshots help with IDE or browser errors
+                    - Upload related code files for deeper analysis
+                    """
+                )
+            
+            with gr.Column(scale=2):
+                gr.Markdown("## 🎯 Results")
+                
+                status_text = gr.Markdown("**Status:** Ready to analyze")
+                
+                with gr.Tabs():
+                    with gr.Tab("💬 Chat"):
+                        chatbot = gr.Chatbot(
+                            height=500,
+                            type="messages",
+                            avatar_images=(
+                                None,
+                                "https://em-content.zobj.net/thumbs/120/apple/354/genie_1f9de.png"
+                            )
+                        )
+                    
+                    with gr.Tab("🎯 Solutions"):
+                        solutions_accordion = gr.HTML(
+                            value="<div>No solutions yet. Analyze an error to get started.</div>"
+                        )
+                    
+                    with gr.Tab("🎨 3D Error Flow"):
+                        viz_3d = gr.HTML(
+                            value="<div style='text-align: center; padding: 40px;'>Visualization will appear here after analysis.</div>"
+                        )
+                    
+                    with gr.Tab("📊 Analysis Details"):
+                        analysis_details = gr.JSON(
+                            label="Detailed Metrics"
+                        )
+                
+                # Voice explanation (collapsed by default)
+                with gr.Accordion("🔊 Voice Explanation", open=False):
+                    voice_output = gr.Audio(
+                        label="AI-Generated Explanation",
+                        autoplay=False
+                    )
+        
+        # Examples
+        gr.Examples(
+            examples=[
+                [
+                    "Traceback (most recent call last):\n  File \"app.py\", line 42, in process_data\n    result = json.loads(data)\njson.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)",
+                    None,
+                    None
+                ],
+                [
+                    "TypeError: 'NoneType' object is not subscriptable\n  File \"main.py\", line 15, in get_user\n    return users[user_id]['name']",
+                    None,
+                    None
+                ]
+            ],
+            inputs=[error_input, screenshot_input, codebase_files],
+            label="📚 Example Errors"
+        )
+        
+        # Event handlers
+        analyze_btn.click(
+            fn=ui.handle_analyze,
+            inputs=[error_input, screenshot_input, codebase_files],
+            outputs=[
+                chatbot, 
+                solutions_accordion, 
+                viz_3d, 
+                voice_output, 
+                analysis_details, 
+                status_text
+            ]
+        )
+    
+    return demo
+
+if __name__ == "__main__":
+    # Default to local backend for direct execution
+    backend = LocalBackend()
+    demo = create_interface(backend)
+    demo.launch(
+        server_name="127.0.0.1",
+        server_port=7860,
+        share=False,
+        show_error=True
+    )

ui/remote_client.py

@@ -0,0 +1,54 @@
+import requests
+import json
+from typing import Dict, Any
+from core.models import DebugResult
+from ui.backend import DebugBackend
+from loguru import logger
+
+class RemoteBackend(DebugBackend):
+    def __init__(self, api_url: str, token: str = None):
+        self.api_url = api_url
+        self.token = token
+
+    async def analyze(self, context: Dict[str, Any]) -> DebugResult:
+        """
+        Call the remote Modal endpoint.
+        """
+        try:
+            # Prepare payload
+            # The Modal endpoint expects a dict with "error_text" and optional "context"
+            # Our context already has 'error_text', 'image', 'code_context'
+            # We might need to adapt if the endpoint signature is strict, 
+            # but modal_app.py takes `error_info: dict`.
+            
+            # Note: Image handling might need base64 encoding if not already done.
+            # In gradio_interface.py, 'image' is passed as PIL image or None.
+            # We need to serialize it if it's a PIL image.
+            
+            payload = context.copy()
+            if payload.get('image'):
+                # If it's a PIL image, convert to base64
+                import base64
+                from io import BytesIO
+                
+                img = payload['image']
+                if not isinstance(img, str):
+                    buffered = BytesIO()
+                    img.save(buffered, format="PNG")
+                    img_str = base64.b64encode(buffered.getvalue()).decode()
+                    payload['image'] = img_str
+            
+            headers = {"Content-Type": "application/json"}
+            if self.token:
+                headers["Authorization"] = f"Bearer {self.token}"
+
+            logger.info(f"Sending request to {self.api_url}")
+            response = requests.post(self.api_url, json=payload, headers=headers, timeout=600)
+            response.raise_for_status()
+            
+            data = response.json()
+            return DebugResult(**data)
+            
+        except Exception as e:
+            logger.error(f"Remote analysis failed: {e}")
+            raise e

visualization/__init__.py

@@ -0,0 +1 @@
+# Empty __init__.py file

visualization/blaxel_generator.py

@@ -0,0 +1,135 @@
+from typing import List, Dict, Any, Optional
+import json
+from pydantic import BaseModel
+from loguru import logger
+
+# Mocking Blaxel SDK for now as it's a hypothetical or external dependency not in requirements
+# In a real scenario, we would import: from blaxel import Scene, Node, Edge, Animation
+# We will generate a Plotly 3D scatter plot as a fallback/implementation of the concept
+import plotly.graph_objects as go
+
+class StackFrame(BaseModel):
+    function: str
+    file: str
+    line: int
+    is_external: bool = False
+
+class ErrorFlowVisualizer:
+    def __init__(self):
+        pass
+
+    def _get_node_color(self, idx: int, total: int, is_external: bool) -> str:
+        if is_external:
+            return "purple"
+        if idx == 0:
+            return "green" # Entry
+        if idx == total - 1:
+            return "red" # Error
+        return "blue" # Normal
+
+    def generate_flow(self, stack_trace: List[Dict[str, Any]]) -> str:
+        """
+        Generate 3D visualization of error flow.
+        Returns HTML string of the visualization.
+        """
+        try:
+            frames = [StackFrame(**f) for f in stack_trace]
+            if not frames:
+                return "<div>No stack trace available for visualization.</div>"
+
+            # Limit nodes for performance
+            if len(frames) > 50:
+                frames = frames[-50:]
+
+            # 3D Coordinates layout (simple spiral or linear)
+            x_coords = []
+            y_coords = []
+            z_coords = []
+            colors = []
+            sizes = []
+            hover_texts = []
+            
+            for idx, frame in enumerate(frames):
+                # Simple linear layout along X axis, with slight spiral
+                x_coords.append(idx * 2)
+                y_coords.append(0) 
+                z_coords.append(0)
+                
+                color = self._get_node_color(idx, len(frames), frame.is_external)
+                colors.append(color)
+                
+                # Pulse effect for error node (simulated by larger size)
+                size = 20 if idx == len(frames) - 1 else 12
+                sizes.append(size)
+                
+                hover_texts.append(
+                    f"<b>{frame.function}</b><br>"
+                    f"{frame.file}:{frame.line}<br>"
+                    f"{'External Library' if frame.is_external else 'User Code'}"
+                )
+
+            # Create Nodes Trace
+            node_trace = go.Scatter3d(
+                x=x_coords, y=y_coords, z=z_coords,
+                mode='markers+text',
+                marker=dict(
+                    size=sizes,
+                    color=colors,
+                    opacity=0.8,
+                    line=dict(width=2, color='white')
+                ),
+                text=[f.function for f in frames],
+                textposition="top center",
+                hoverinfo='text',
+                hovertext=hover_texts
+            )
+
+            # Create Edges Trace
+            edge_x = []
+            edge_y = []
+            edge_z = []
+            
+            for i in range(len(frames) - 1):
+                edge_x.extend([x_coords[i], x_coords[i+1], None])
+                edge_y.extend([y_coords[i], y_coords[i+1], None])
+                edge_z.extend([z_coords[i], z_coords[i+1], None])
+
+            edge_trace = go.Scatter3d(
+                x=edge_x, y=edge_y, z=edge_z,
+                mode='lines',
+                line=dict(color='#888', width=2),
+                hoverinfo='none'
+            )
+
+            # Layout
+            layout = go.Layout(
+                title="3D Error Flow Visualization",
+                showlegend=False,
+                scene=dict(
+                    xaxis=dict(showgrid=False, zeroline=False, showticklabels=False),
+                    yaxis=dict(showgrid=False, zeroline=False, showticklabels=False),
+                    zaxis=dict(showgrid=False, zeroline=False, showticklabels=False),
+                    bgcolor='rgba(0,0,0,0)'
+                ),
+                margin=dict(l=0, r=0, b=0, t=30),
+                height=500
+            )
+
+            fig = go.Figure(data=[edge_trace, node_trace], layout=layout)
+            
+            # Return HTML div
+            return fig.to_html(full_html=False, include_plotlyjs='cdn')
+
+        except Exception as e:
+            logger.error(f"Visualization generation failed: {e}")
+            return f"<div>Error generating visualization: {str(e)}</div>"
+
+    def generate_mock_trace(self) -> List[Dict[str, Any]]:
+        """Generate a mock trace for testing."""
+        return [
+            {"function": "main", "file": "app.py", "line": 10, "is_external": False},
+            {"function": "process_request", "file": "core/handler.py", "line": 45, "is_external": False},
+            {"function": "validate_input", "file": "utils/validation.py", "line": 12, "is_external": False},
+            {"function": "json.loads", "file": "json/decoder.py", "line": 337, "is_external": True},
+            {"function": "decode", "file": "json/decoder.py", "line": 355, "is_external": True},
+        ]

voice/__init__.py

@@ -0,0 +1 @@
+# Empty __init__.py file

voice/elevenlabs_tts.py

@@ -0,0 +1,12 @@
+# Stub for voice module to avoid import errors in HF Space
+# Voice generation is optional and won't be used in the remote backend setup
+
+class VoiceExplainer:
+    def __init__(self, api_key=None):
+        pass
+    
+    def generate_explanation(self, solution, mode="walkthrough"):
+        return None
+    
+    def save_audio(self, audio_bytes, filename):
+        return None