docs: contributors and users guide for the AI Debugger

AI-Debugger-widget-guide.md

@@ -0,0 +1,177 @@
+# AI-Powered Debugger Widget Guide
+
+<div align= "">
+
+[![AI-Powered Debugger Widget Demo](http://img.youtube.com/vi/G-NfDo_A5PM/0.jpg)](http://www.youtube.com/watch?v=G-NfDo_A5PM "AI-Powered Debugger Widget Demo")
+
+**🎥 [Click to Watch the Demo Video](https://www.youtube.com/watch?v=G-NfDo_A5PM)**
+
+</div>
+
+---
+
+## Introduction
+
+Hey there, MusicBlocks creators! 🎵 
+
+I'm excited to introduce you to the AI-Powered Debugger Widget - a game-changing feature I've built to help you debug your Music Blocks projects with new possibilities and deeper understanding. Whether your melody isn't playing right, your blocks aren't connecting properly, or you're just curious about making your musical creation better, this AI assistant is here to help!
+
+---
+
+## What is the AI-Powered Debugger?
+
+Think of it as your smart musical buddy who understands both your block arrangements and music theory! This intelligent assistant:
+
+- **Analyzes your block projects** and spots issues you might have missed
+- **Explains problems** in simple, friendly language that anyone can understand  
+- **Suggests creative solutions** to make your music sound even better
+- **Teaches you** music and programming concepts through interactive conversations
+- **Understands your musical goals** and helps you achieve them through better block arrangements
+- **Learns from your style** to provide personalized help for your unique projects
+
+---
+
+## Key Features That Make Your Music Blocks Experience Amazing
+
+### 🎯 **Smart Block Analysis**
+- **Automatic Project Understanding**: AI instantly "reads" your block arrangements and connections
+- **Musical Logic Check**: Spots when blocks don't make musical sense together
+- **Connection Issues**: Identifies blocks that should be connected but aren't
+- **Performance Tips**: Suggests ways to make your project run smoother
+
+### 💬 **Chat with Your AI Music Buddy**
+- **Ask Anything**: "Why doesn't my drum beat work?" or "How do I make this melody longer?"
+- **Instant Help**: Get answers in seconds
+- **Remember Everything**: AI keeps track of your conversation for follow-up questions
+- **Friendly Explanations**: No confusing technical jargon - just simple, helpful advice
+
+### 🎵 **Musical Intelligence**
+- **Music Theory Helper**: Learn about scales, rhythms, and harmonies while you create
+- **Instrument Suggestions**: Get advice on which instruments work well together
+- **Creative Ideas**: Discover new ways to arrange your blocks for cooler sounds
+- **Fix Musical "Bugs"**: Spot timing issues, wrong notes, or clashing sounds
+
+### 🔧 **Block Connection Genius**
+- **Connection Problems**: Find blocks that should be linked but aren't
+- **Block Logic**: Understand why certain blocks work together and others don't
+- **Project Flow**: See how your blocks create the musical story from start to finish
+- **Optimization Tips**: Learn better ways to arrange blocks for cleaner projects
+
+---
+
+## How to Use Your AI Debugging Assistant
+
+### Getting Started (Super Easy!)
+
+1. **Find the AI Debugger Block**:
+   - Open your Widgets palette in Music Blocks
+   - Look for the "debugger" block
+   - Drag it to your workspace
+
+2. **Open Your AI Helper**:
+   - Click on the AI Debugger block you just placed
+   - A chat window opens - this is where the magic happens!
+   - Your project is automatically analyzed by AI in the background
+   - The AI welcomes you with an initial understanding of what your project is about
+   - You'll see helpful suggestions and insights appear in the chat
+
+### Start Chatting with AI
+
+Just type your questions like you're talking to a friend:
+
+**Questions That Work Great:**
+- "My piano melody sounds weird, what's wrong?"
+- "Why isn't my drum pattern repeating?"
+- "How do I connect these blocks properly?"
+- "Can you help me make this sound cooler?"
+- "My mouse isn't drawing while the music plays"
+- "Why does my rhythm sound off-beat?"
+
+**AI Responses Include:**
+- Clear explanations of what might be wrong
+- Step-by-step instructions to fix issues  
+- Creative suggestions to improve your project
+- Learning tips about music and block connections
+
+### Advanced Features You'll Love
+
+**🔍 Smart Project Analysis**
+- AI automatically scans all your blocks when you open the chat
+- Finds potential issues before you even ask
+- Suggests improvements for better-sounding music
+- Identifies blocks that could work better together
+
+**📝 Conversation Tools**
+- **Export Chat**: Save your conversation to review later or share with teachers
+- **Reset Chat**: Clear everything and start a fresh conversation
+- **Chat Memory**: AI remembers what you talked about earlier in the same session
+
+---
+
+## Why This AI Debugger is Amazing for Learning
+
+### 🎓 **For Students (That's You!)**
+- **Learn by Doing**: Fix real problems in your music blocks projects and understand why they happened
+- **Build Problem-Solving Skills**: Develop smart ways to think through musical challenges
+- **Music + Programming**: Learn both music theory and block logic at the same time
+- **Confidence Boost**: Get help when stuck instead of giving up on cool projects
+- **Creative Growth**: Discover new musical ideas through AI suggestions
+
+### 👩‍🏫 **For Teachers**
+- **Better Understanding**: See what students struggle with through AI conversation exports
+- **Time Saver**: Let AI handle basic questions while you focus on advanced help
+- **Personalized Help**: Each student gets explanations tailored to their project
+- **Assessment Tool**: Track learning progress through debugging conversations
+- **Curriculum Support**: Integrate AI insights into lesson plans
+
+### 👨‍👩‍👧‍👦 **For Parents**
+- **Support Your Kids**: Understand what they're learning and how to help
+- **Encourage Exploration**: AI suggestions spark new creative directions
+- **Safe Learning**: All AI responses are appropriate and educational
+- **Track Progress**: See how your child's problem-solving skills develop
+
+---
+
+## Simple Debugging Workflow
+
+### Step 1: Open & Analyze
+```
+Create your MusicBlocks project → Add Debugger block → Click it → Chat opens & AI analyzes
+```
+
+### Step 2: Ask Questions  
+```
+"What's wrong with my melody?" → AI explains the issue → Follow the suggestions
+```
+
+### Step 3: Learn & Improve
+```
+"Why did that happen?" → AI teaches the concept → Apply to future projects
+```
+
+### Step 4: Get Creative
+```
+"How can I make this cooler?" → AI suggests enhancements → Try new ideas
+```
+
+---
+
+## Let's Wrap This Up!
+
+I created this AI-Powered Debugger because I believe every Music Blocks user deserves a smart, friendly assistant to help them bring their musical visions to life. Whether you're just starting out or you're already creating amazing compositions, this AI buddy is here to help you debug, learn, and create even cooler projects.
+
+The best part? Every time you chat with the AI, you're not just fixing problems - you're learning music theory, understanding how blocks work together, and developing problem-solving skills that will help you in all kinds of creative projects.
+
+So go ahead, drag that AI Debugger block into your workspace, click it, and start chatting! Ask questions, experiment with suggestions, and most importantly, have fun creating awesome music with your new AI assistant.
+
+Happy debugging !! 🎵✨
+
+---
+
+**About Me & This Project:**
+- **Built by**: Om Santosh Suneri ([GitHub](https://github.com/omsuneri/))
+- **Part of**: Google Summer of Code 2025 with Sugar Labs
+
+*Questions? Ideas? Found a bug? Reach out to me or the MusicBlocks team - we'd love to hear from you!*
+
+*Last updated: August 2025 | Version 1.0*

js/widgets/aidebugger-guide.md

@@ -0,0 +1,150 @@
+# AI-powered Debugger Widget - Contributor Guide
+
+## Overview
+
+The AI-powered Debugger Widget is an intelligent debugging assistant for Music Blocks that provides AI-powered analysis and child-friendly debugging suggestions through an interactive chat interface.
+
+### Key Features
+- Interactive chat interface within Music Blocks
+- Real-time project analysis using AI
+- Educational explanations for children
+- Export/reset conversation functionality
+- Integration with Music Blocks widget system
+
+### Architecture
+```
+Music Blocks Frontend → AI Debugger Widget → FastAPI Backend → Google Gemini AI
+                                         → RAG System → Qdrant Vector DB
+```
+
+**Components:**
+- **Frontend**: `js/widgets/aidebugger.js` (main widget)
+- **Block Definition**: `js/blocks/WidgetBlocks.js` (lines 1643-1719)
+- **Registration**: `js/activity.js` (line 165)
+- **Backend**: External FastAPI server with AI processing
+
+## Quick Start
+
+### Setup
+```bash
+git clone https://github.com/sugarlabs/musicblocks.git
+cd musicblocks
+npm install
+npm run serve  # Access at http://localhost:3000
+```
+
+### Key Files
+- `js/widgets/aidebugger.js` - Main widget implementation
+- `js/blocks/WidgetBlocks.js` - Block definition (lines 1643-1719)
+- `js/activity.js` - Widget registration (line 165)
+
+## Frontend Implementation
+
+### Widget Structure
+```javascript
+function AIDebuggerWidget() {
+    const BACKEND_CONFIG = {
+        BASE_URL: "http://13.49.246.243:8000",
+        ENDPOINTS: { ANALYZE: "/analyze" }
+    };
+
+    this.chatHistory = [];
+    this.promptCount = 0;
+    this.conversationId = null;
+}
+```
+
+### Key Methods
+- `init(activity)` - Initialize widget and UI
+- `_createLayout()` - Build chat interface
+- `_sendMessage()` - Handle user input and AI responses
+- `_convertProjectToLLMFormat()` - Convert Music Blocks JSON to readable text
+
+### API Communication
+```javascript
+const payload = {
+    code: projectData,        // Music Blocks JSON
+    prompt: message,          // User question
+    history: history,         // Chat history
+    prompt_count: this.promptCount
+};
+
+fetch(`${BACKEND_CONFIG.BASE_URL}/analyze`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload)
+});
+```
+
+## Development Workflow
+
+### Adding Features
+1. **Edit Widget**: Modify `js/widgets/aidebugger.js`
+2. **Test Locally**: Run `npm run serve`
+3. **Block Integration**: Update `js/blocks/WidgetBlocks.js` if needed
+4. **Register Widget**: Ensure listed in `js/activity.js`
+
+### Code Standards
+```javascript
+// Use descriptive names
+this._createChatInterface = function() { ... };
+
+// Add documentation
+/**
+ * Sends message to backend and processes AI response
+ * @param {string} message - User input message
+ */
+this._sendToBackend = function(message) { ... };
+
+// Handle errors gracefully
+.catch(error => {
+    console.error("Backend error:", error.message);
+    this.activity.textMsg(_("Connection error"));
+});
+```
+
+### Code Review Checklist
+- [ ] Widget initializes correctly
+- [ ] Chat interface is responsive  
+- [ ] Backend communication works
+- [ ] Error handling is robust
+- [ ] Language is child-appropriate
+- [ ] No console errors
+
+## Testing
+
+### Manual Testing
+1. Open Music Blocks → Drag AI Debugger block → Click block
+2. Verify widget window opens with chat interface
+3. Type message → Click Send → Check AI response
+4. Test export/reset functionality
+5. Verify works with different project types
+
+### Debug Commands
+```javascript
+// Frontend debugging
+console.log("Widget initialized:", this);
+console.log("Backend URL:", BACKEND_CONFIG.BASE_URL);
+
+// Backend testing  
+curl -X POST http://localhost:8000/analyze \
+  -H "Content-Type: application/json" \
+  -d '{"code": "[]", "prompt": "test"}'
+```
+
+## Troubleshooting
+
+### Common Issues
+- **Widget not loading**: Check `activity.js` registration and console errors
+- **Backend connection**: Verify `BACKEND_CONFIG.BASE_URL` and CORS
+- **UI problems**: Check CSS styles and widget window creation
+
+### Resources
+- **GitHub Issues**: [Music Blocks Issues](https://github.com/sugarlabs/musicblocks/issues)
+- **Documentation**: [Music Blocks Guide](https://github.com/sugarlabs/musicblocks/tree/master/guide)
+- **Backend Repo**: [AI Debugger Backend](https://github.com/omsuneri/AI-powered-Debugger-for-Music-Blocks)
+
+---
+
+**Made with ❤️ for Music Blocks and Sugar Labs**  
+**Created by**: [Om Santosh Suneri](https://github.com/omsuneri/) | **[GSoC 2025](https://summerofcode.withgoogle.com/programs/2025/projects/l4402WCJ)**