Merge pull request #4753 from Commanderk3/user-guide

User Guide for Reflection Widget

Author: sum2it

REFLECTION-WIDGET-GUIDE.md

@@ -0,0 +1,53 @@
+# Reflection Widget - User Guide
+
+The Reflection Widget lets you chat with AI mentors to reflect on and analyze your Music Blocks project. Using this tool, you can learn quickly and improve your coding and music skills.
+
+## Getting Started
+
+1. **Open the Reflection Widget**  
+  - You will find the reflection block in the widget palette (available in both beginner and advanced modes).
+  - Drag it to your workspace and click it to open the widget.
+
+2. **Meet Your AI Mentors**  
+
+  There are three AI mentors in the widget:
+  - **Rohan** (Meta) for general project reflection. He is an expert at helping you think about your project as a whole. He will discuss your goals, challenges, and learning.
+
+  - **Beethoven** (Music) for music-specific advice. The famous composer Ludwig van Beethoven is here to help you improve your music compositions and knowledge.
+
+  - **Alan** (Code) for coding help. Alan Kay, a pioneer in computer science, will assist you with coding concepts. He may ask critical questions to help you think about your code structure and logic.
+
+  Click the mentor’s icon to change who you’re chatting with. You can switch mentors at any time.
+
+## Sending Messages
+
+- Your mentor will first read your project and share their initial thoughts. They may ask if their understanding of your project is correct.
+- Confirm their guess to start discussing your project.
+- The AI mentors will ask reflective questions to help you think more deeply about your work.
+- Provide detailed responses to receive better feedback.
+- Press `Enter` or click **Send** to send your message.
+
+## Tips
+
+- The best way to use this tool is to have a detailed and long conversation with your mentor. The more you share, the better the feedback.
+- Let your mentors ask the questions; you can just sit back and answer them thoughtfully.
+- If your mentors are done asking questions, they will ask you if you want to continue the conversation or end it. It is up to you!
+- When you feel satisfied with the conversation, you can generate an analysis report. This report is based on your interactions with the mentors and the previous report. It will discuss your learning outcomes, areas for improvement, and next steps.
+
+## Widget Features
+
+- **Summary:**  
+  Click the notes icon to view or generate a summary (after 10+ messages).
+
+- **Change Mentor:**  
+  Click the mentor icons to switch between Rohan, Beethoven, and Alan.
+
+- **Save Conversation:**  
+  Click the save icon to download your chat as a `.txt` file.
+
+- **Refresh Project:**  
+  Click the refresh icon to update the widget with your latest project code.
+
+---
+
+Enjoy reflecting and improving your projects with the help of AI mentors!

js/widgets/reflection-guide.md

@@ -8,7 +8,7 @@ Backend Code for the widget : [musicblocks_reflection_fastapi](https://github.co
 
 ## Key Features
 
--   **Multi-mentor Chat:** Switch between AI mentors (Meta/Rohan, Music/Beethoven, Code/Steve).
+-   **Multi-mentor Chat:** Switch between AI mentors (Meta/Rohan, Music/Beethoven, Code/Alan).
 -   **Chat History:** Stores and renders conversation history.
 -   **Typing Indicator:** Shows animated "Thinking..." while awaiting responses.
 -   **Markdown Rendering:** Converts Markdown responses to HTML for display.
@@ -92,14 +92,14 @@ Backend Code for the widget : [musicblocks_reflection_fastapi](https://github.co
         "code": "<project code string>"
     }
     ```
--   **Response:**  
+-   **Response:**
     ```json
     {
         "algorithm": "<algorithm string>",
         "message": "<first message>"
     }
     ```
-    or  
+    or
     ```json
     {
         "error": "<error message>"
@@ -164,21 +164,67 @@ Backend Code for the widget : [musicblocks_reflection_fastapi](https://github.co
 
 ---
 
+### 4. `/updatecode`
+
+-   **Method:** `POST`
+-   **Purpose:** Sends updated project code to the backend to refresh the algorithmic summary.
+-   **Payload:**
+    ```json
+    {
+        "oldcode": "<existing project code string>",
+        "newcode": "<new project code string>"
+    }
+    ```
+-   **Response:**
+    ```json
+    {
+        "algorithm": "<new algorithm string>",
+        "message": "<response message>"
+    }
+    ```
+
+---
+
 **All endpoints expect and return JSON.**  
 **The backend is expected to run locally while development.**
 
 ---
 
 ### API testing
 
+code :
+
 ```bash
-curl -X POST http://localhost:PORT/projectcode \
+curl -X GET http://localhost:8000/
+```
+
+output :
+
+```json
+{
+    "message": "Hello, Music Blocks!"
+}
+```
+
+Test `/projectcode` endpoint with sample project code:
+
+```bash
+curl -X POST http://localhost:8000/projectcode \
      -H "Content-Type: application/json" \
      -d '{
-           "code": "MUSICBLOCKS_PROJECT_CODE_HERE"
+           "code": "[[0,[\"start\",{\"id\":123,\"collapsed\":false}],244,80,[null,18,null]],[1,\"plus\",392,440,[10,16,8]]]"
          }'
 ```
 
+Output:
+
+```json
+{
+    "algorithm": "1. Start the program.\n2. Perform an addition operation.",
+    "response": "This looks like a very basic program designed to add two numbers. Is that correct?"
+}
+```
+
 **Note** : Save your Music Blocks project as an HTML file. Open the file to locate the embedded JSON code, and make sure to stringify the JSON before using it for testing.
 
-Written by : [Diwangshu Kakoty](https://github.com/Commanderk3)
+Written by : [Diwangshu Kakoty](https://github.com/Commanderk3)