Upload 24 files

utils/action_node.py

@@ -0,0 +1,452 @@
+import json
+import uuid
+import logging
+from typing import Dict, Any, List
+
+# Assume GameState is a TypedDict or similar for clarity
+# from typing import TypedDict
+# class GameState(TypedDict):
+#     description: str
+#     project_json: Dict[str, Any]
+#     action_plan: Dict[str, Any]
+#     sprite_initial_positions: Dict[str, Any]
+
+# Placeholder for actual GameState in your application
+GameState = Dict[str, Any]
+
+logger = logging.getLogger(__name__)
+
+# --- Mock Agent for demonstration ---
+class MockAgent:
+    def invoke(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Mocks an LLM agent invocation. In a real scenario, this would call your
+        actual LLM API (e.g., through LangChain, LlamaIndex, etc.).
+        """
+        user_message = payload["messages"][-1]["content"]
+        print(f"\n--- Mock Agent Received Prompt (partial) ---\n{user_message[:500]}...\n------------------------------------------")
+
+        # Simplified mock responses for demonstration purposes
+        # In a real scenario, the LLM would generate actual Scratch block JSON
+        if "Propose a high-level action flow" in user_message:
+            return {
+                "messages": [{
+                    "content": json.dumps({
+                        "action_overall_flow": {
+                            "Sprite1": {
+                                "description": "Basic movement and interaction",
+                                "plans": [
+                                    {
+                                        "event": "when flag clicked",
+                                        "logic": "forever loop: move 10 steps, if touching Edge then turn 15 degrees"
+                                    },
+                                    {
+                                        "event": "when space key pressed",
+                                        "logic": "say Hello! for 2 seconds"
+                                    }
+                                ]
+                            },
+                            "Ball": {
+                                "description": "Simple bouncing behavior",
+                                "plans": [
+                                    {
+                                        "event": "when flag clicked",
+                                        "logic": "move 5 steps, if on edge bounce"
+                                    }
+                                ]
+                            }
+                        }
+                    })
+                }]
+            }
+        elif "You are an AI assistant generating Scratch 3.0 block JSON" in user_message:
+            # This mock response is highly simplified. A real LLM would generate
+            # valid Scratch blocks based on the provided relevant catalog and plan.
+            # We're just demonstrating the *mechanism* of filtering the catalog.
+            if "Sprite1" in user_message:
+                return {
+                    "messages": [{
+                        "content": json.dumps({
+                            f"block_id_{generate_block_id()}": {
+                                "opcode": "event_whenflagclicked",
+                                "next": f"block_id_{generate_block_id()}_forever",
+                                "parent": None,
+                                "inputs": {}, "fields": {}, "shadow": False, "topLevel": True, "x": 100, "y": 100
+                            },
+                            f"block_id_{generate_block_id()}_forever": {
+                                "opcode": "control_forever",
+                                "next": None,
+                                "parent": f"block_id_{generate_block_id()}",
+                                "inputs": {
+                                    "SUBSTACK": [2, f"block_id_{generate_block_id()}_move"]
+                                }, "fields": {}, "shadow": False, "topLevel": False
+                            },
+                            f"block_id_{generate_block_id()}_move": {
+                                "opcode": "motion_movesteps",
+                                "next": f"block_id_{generate_block_id()}_if",
+                                "parent": f"block_id_{generate_block_id()}_forever",
+                                "inputs": {
+                                    "STEPS": [1, [4, "10"]]
+                                }, "fields": {}, "shadow": False, "topLevel": False
+                            },
+                             f"block_id_{generate_block_id()}_if": {
+                                "opcode": "control_if",
+                                "next": None,
+                                "parent": f"block_id_{generate_block_id()}_forever",
+                                "inputs": {
+                                    "CONDITION": [2, f"block_id_{generate_block_id()}_touching"],
+                                    "SUBSTACK": [2, f"block_id_{generate_block_id()}_turn"]
+                                }, "fields": {}, "shadow": False, "topLevel": False
+                            },
+                            f"block_id_{generate_block_id()}_touching": {
+                                "opcode": "sensing_touchingobject",
+                                "next": None,
+                                "parent": f"block_id_{generate_block_id()}_if",
+                                "inputs": {
+                                    "TOUCHINGOBJECTMENU": [1, f"block_id_{generate_block_id()}_touching_menu"]
+                                }, "fields": {}, "shadow": False, "topLevel": False
+                            },
+                            f"block_id_{generate_block_id()}_touching_menu": {
+                                "opcode": "sensing_touchingobjectmenu",
+                                "next": None,
+                                "parent": f"block_id_{generate_block_id()}_touching",
+                                "inputs": {},
+                                "fields": {"TOUCHINGOBJECTMENU": ["_edge_", None]},
+                                "shadow": True, "topLevel": False
+                            },
+                            f"block_id_{generate_block_id()}_turn": {
+                                "opcode": "motion_turnright",
+                                "next": None,
+                                "parent": f"block_id_{generate_block_id()}_if",
+                                "inputs": {
+                                    "DEGREES": [1, [4, "15"]]
+                                }, "fields": {}, "shadow": False, "topLevel": False
+                            },
+                            f"block_id_{generate_block_id()}_say": {
+                                "opcode": "looks_sayforsecs",
+                                "next": None,
+                                "parent": None, # This block would typically be part of a separate script
+                                "inputs": {
+                                    "MESSAGE": [1, [10, "Hello!"]],
+                                    "SECS": [1, [4, "2"]]
+                                }, "fields": {}, "shadow": False, "topLevel": True, "x": 300, "y": 100
+                            }
+                        })
+                    }]
+                }
+            elif "Ball" in user_message:
+                 return {
+                    "messages": [{
+                        "content": json.dumps({
+                            f"block_id_{generate_block_id()}": {
+                                "opcode": "event_whenflagclicked",
+                                "next": f"block_id_{generate_block_id()}_moveball",
+                                "parent": None,
+                                "inputs": {}, "fields": {}, "shadow": False, "topLevel": True, "x": 100, "y": 100
+                            },
+                            f"block_id_{generate_block_id()}_moveball": {
+                                "opcode": "motion_movesteps",
+                                "next": f"block_id_{generate_block_id()}_edgebounce",
+                                "parent": f"block_id_{generate_block_id()}",
+                                "inputs": {
+                                    "STEPS": [1, [4, "5"]]
+                                }, "fields": {}, "shadow": False, "topLevel": False
+                            },
+                            f"block_id_{generate_block_id()}_edgebounce": {
+                                "opcode": "motion_ifonedgebounce",
+                                "next": None,
+                                "parent": f"block_id_{generate_block_id()}_moveball",
+                                "inputs": {}, "fields": {}, "shadow": False, "topLevel": False
+                            }
+                        })
+                    }]
+                }
+        return {"messages": [{"content": "[]"}]} # Default empty response
+
+agent = MockAgent()
+
+# Helper function to generate a unique block ID
+def generate_block_id():
+    return str(uuid.uuid4())[:10].replace('-', '') # Shorten for readability, ensure uniqueness
+
+# Placeholder for your extract_json_from_llm_response function
+def extract_json_from_llm_response(response_string):
+    try:
+        # Assuming the LLM response is ONLY the JSON string within triple backticks
+        json_match = response_string.strip().replace("```json", "").replace("```", "").strip()
+        return json.loads(json_match)
+    except json.JSONDecodeError as e:
+        logger.error(f"Failed to decode JSON from LLM response: {e}")
+        logger.error(f"Raw response: {response_string}")
+        raise ValueError("Invalid JSON response from LLM")
+
+# --- GLOBAL CATALOG OF ALL SCRATCH BLOCKS ---
+# This is where you would load your block_content.json
+# For demonstration, I'm using your provided snippets and adding some common ones.
+# In a real application, you'd load this once at startup.
+ALL_SCRATCH_BLOCKS_CATALOG = {
+    "motion_movesteps": {
+        "opcode": "motion_movesteps", "next": None, "parent": None,
+        "inputs": {"STEPS": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True, "x": 464, "y": -416
+    },
+    "motion_turnright": {
+        "opcode": "motion_turnright", "next": None, "parent": None,
+        "inputs": {"DEGREES": [1, [4, "15"]]}, "fields": {}, "shadow": False, "topLevel": True, "x": 467, "y": -316
+    },
+    "motion_ifonedgebounce": {
+        "opcode": "motion_ifonedgebounce", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True, "x": 467, "y": -316
+    },
+    "event_whenflagclicked": {
+        "opcode": "event_whenflagclicked", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True, "x": 10, "y": 10
+    },
+    "event_whenkeypressed": {
+        "opcode": "event_whenkeypressed", "next": None, "parent": None,
+        "inputs": {}, "fields": {"KEY_OPTION": ["space", None]}, "shadow": False, "topLevel": True, "x": 10, "y": 10
+    },
+    "control_forever": {
+        "opcode": "control_forever", "next": None, "parent": None,
+        "inputs": {"SUBSTACK": [2, "some_id"]}, "fields": {}, "shadow": False, "topLevel": True, "x": 10, "y": 10
+    },
+    "control_if": {
+        "opcode": "control_if", "next": None, "parent": None,
+        "inputs": {"CONDITION": [2, "some_id"], "SUBSTACK": [2, "some_id_2"]}, "fields": {}, "shadow": False, "topLevel": True, "x": 10, "y": 10
+    },
+    "looks_sayforsecs": {
+        "opcode": "looks_sayforsecs", "next": None, "parent": None,
+        "inputs": {"MESSAGE": [1, [10, "Hello!"]], "SECS": [1, [4, "2"]]}, "fields": {}, "shadow": False, "topLevel": True, "x": 10, "y": 10
+    },
+    "looks_say": {
+        "opcode": "looks_say", "next": None, "parent": None,
+        "inputs": {"MESSAGE": [1, [10, "Hello!"]]}, "fields": {}, "shadow": False, "topLevel": True, "x": 10, "y": 10
+    },
+    "sensing_touchingobject": {
+        "opcode": "sensing_touchingobject", "next": None, "parent": None,
+        "inputs": {"TOUCHINGOBJECTMENU": [1, "some_id"]}, "fields": {}, "shadow": False, "topLevel": True, "x": 10, "y": 10
+    },
+    "sensing_touchingobjectmenu": {
+        "opcode": "sensing_touchingobjectmenu", "next": None, "parent": None,
+        "inputs": {}, "fields": {"TOUCHINGOBJECTMENU": ["_mouse_", None]}, "shadow": True, "topLevel": True, "x": 10, "y": 10
+    },
+    # Add more blocks from your block_content.json here...
+}
+
+# --- Heuristic-based block selection ---
+def get_relevant_blocks_for_plan(action_plan: Dict[str, Any], all_blocks_catalog: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Analyzes the natural language action plan and selects relevant Scratch blocks
+    from the comprehensive catalog. This is a heuristic approach and might need
+    to be refined based on your specific use cases and LLM capabilities.
+    """
+    relevant_opcodes = set()
+
+    # Always include common event blocks
+    relevant_opcodes.add("event_whenflagclicked")
+    relevant_opcodes.add("event_whenkeypressed") # Could be more specific if key is mentioned
+
+    # Keyword to opcode mapping (can be expanded)
+    keyword_map = {
+        "move": "motion_movesteps",
+        "steps": "motion_movesteps",
+        "turn": "motion_turnright",
+        "rotate": "motion_turnright",
+        "bounce": "motion_ifonedgebounce",
+        "edge": "motion_ifonedgebounce",
+        "forever": "control_forever",
+        "loop": "control_forever",
+        "if": "control_if",
+        "condition": "control_if",
+        "say": "looks_say",
+        "hello": "looks_say", # Simple example, might need more context
+        "touching": "sensing_touchingobject",
+        "mouse pointer": "sensing_touchingobjectmenu",
+        "edge": "sensing_touchingobjectmenu", # For touching edge
+    }
+
+    # Iterate through the action plan to find keywords
+    for sprite_name, sprite_actions in action_plan.get("action_overall_flow", {}).items():
+        for plan in sprite_actions.get("plans", []):
+            event_logic = plan.get("event", "").lower() + " " + plan.get("logic", "").lower()
+
+            # Check for direct opcode matches (if the LLM somehow outputs opcodes in its plan)
+            for opcode in all_blocks_catalog.keys():
+                if opcode in event_logic:
+                    relevant_opcodes.add(opcode)
+
+            # Check for keywords
+            for keyword, opcode in keyword_map.items():
+                if keyword in event_logic:
+                    relevant_opcodes.add(opcode)
+                    # Add associated shadow blocks if known
+                    if opcode == "sensing_touchingobject":
+                        relevant_opcodes.add("sensing_touchingobjectmenu")
+                    if opcode == "event_whenkeypressed":
+                         relevant_opcodes.add("event_whenkeypressed") # It's already there but good to be explicit
+
+    # Construct the filtered catalog
+    relevant_blocks_catalog = {
+        opcode: all_blocks_catalog[opcode]
+        for opcode in relevant_opcodes if opcode in all_blocks_catalog
+    }
+    return relevant_blocks_catalog
+
+# --- New Action Planning Node ---
+def plan_sprite_actions(state: GameState):
+    logger.info("--- Running PlanSpriteActionsNode ---")
+
+    planning_prompt = (
+        f"You are an AI assistant tasked with planning Scratch 3.0 block code for a game. "
+        f"The game description is: '{state['description']}'.\n\n"
+        f"Here are the sprites currently in the project: {', '.join(target['name'] for target in state['project_json']['targets'] if not target['isStage']) if len(state['project_json']['targets']) > 1 else 'None'}.\n"
+        f"Initial positions: {json.dumps(state.get('sprite_initial_positions', {}), indent=2)}\n\n"
+        f"Consider the main actions and interactions required for each sprite. "
+        f"Think step-by-step about what each sprite needs to *do*, *when* it needs to do it (events), "
+        f"and if any actions need to *repeat* or depend on *conditions*.\n\n"
+        f"Propose a high-level action flow for each sprite in the following JSON format. "
+        f"Do NOT generate Scratch block JSON yet. Only describe the logic using natural language or simplified pseudo-code.\n\n"
+        f"Example format:\n"
+        f"```json\n"
+        f"{{\n"
+        f"  \"action_overall_flow\": {{\n"
+        f"    \"Sprite1\": {{\n"
+        f"      \"description\": \"Main character actions\",\n"
+        f"      \"plans\": [\n"
+        f"        {{\n"
+        f"          \"event\": \"when flag clicked\",\n"
+        f"          \"logic\": \"forever loop: move 10 steps, if on edge bounce\"\n"
+        f"        }},\n"
+        f"        {{\n"
+        f"          \"event\": \"when space key pressed\",\n"
+        f"          \"logic\": \"change y by 10, wait 0.1 seconds, change y by -10\"\n"
+        f"        }}\n"
+        f"      ]\n"
+        f"    }},\n"
+        f"    \"Ball\": {{\n"
+        f"      \"description\": \"Projectile movement\",\n"
+        f"      \"plans\": [\n"
+        f"        {{\n"
+        f"          \"event\": \"when I start as a clone\",\n"
+        f"          \"logic\": \"glide 1 sec to random position, if touching Sprite1 then stop this script\"\n"
+        f"        }}\n"
+        f"      ]\n"
+        f"    }}\n"
+        f"  }}\n"
+        f"}}\n"
+        f"```\n\n"
+        f"Return ONLY the JSON object for the action overall flow."
+    )
+
+    try:
+        response = agent.invoke({"messages": [{"role": "user", "content": planning_prompt}]})
+        raw_response = response["messages"][-1].content
+        print("Raw response from LLM [PlanSpriteActionsNode]:", raw_response)
+        action_plan = extract_json_from_llm_response(raw_response)
+        logger.info("Sprite action plan generated by PlanSpriteActionsNode.")
+        return {"action_plan": action_plan}
+    except Exception as e:
+        logger.error(f"Error in PlanSpriteActionsNode: {e}")
+        raise
+
+# --- Updated Action Node Builder (to consume the plan and build blocks) ---
+def build_action_nodes(state: GameState):
+    logger.info("--- Running ActionNodeBuilder ---")
+
+    action_plan = state.get("action_plan", {})
+    if not action_plan:
+        raise ValueError("No action plan found in state. Run PlanSpriteActionsNode first.")
+
+    # Convert the Scratch project JSON to a mutable Python object
+    project_json = state["project_json"]
+    targets = project_json["targets"]
+
+    # We need a way to map sprite names to their actual target objects in project_json
+    sprite_map = {target["name"]: target for target in targets if not target["isStage"]}
+
+    # --- NEW: Get only the relevant blocks for the entire action plan ---
+    relevant_scratch_blocks_catalog = get_relevant_blocks_for_plan(action_plan, ALL_SCRATCH_BLOCKS_CATALOG)
+    logger.info(f"Filtered {len(relevant_scratch_blocks_catalog)} relevant blocks out of {len(ALL_SCRATCH_BLOCKS_CATALOG)} total.")
+
+
+    # Iterate through the planned actions for each sprite
+    for sprite_name, sprite_actions in action_plan.get("action_overall_flow", {}).items():
+        if sprite_name in sprite_map:
+            current_sprite_target = sprite_map[sprite_name]
+            # Ensure 'blocks' field exists for the sprite
+            if "blocks" not in current_sprite_target:
+                current_sprite_target["blocks"] = {}
+
+            # Generate block JSON based on the detailed action plan for this sprite
+            # This is where the LLM's role becomes crucial: translating logic to blocks
+            llm_block_generation_prompt = (
+                f"You are an AI assistant generating Scratch 3.0 block JSON based on a provided plan. "
+                f"The current sprite is '{sprite_name}'.\n"
+                f"Its planned actions are:\n"
+                f"```json\n{json.dumps(sprite_actions, indent=2)}\n```\n\n"
+                f"Here is a **curated catalog of only the most relevant Scratch 3.0 blocks** for this plan:\n"
+                f"```json\n{json.dumps(relevant_scratch_blocks_catalog, indent=2)}\n```\n\n"
+                f"Current Scratch project JSON (for context, specifically this sprite's existing blocks if any):\n"
+                f"```json\n{json.dumps(current_sprite_target, indent=2)}\n```\n\n"
+                f"**Instructions:**\n"
+                f"1.  For each planned event and its associated logic, generate the corresponding Scratch 3.0 block JSON.\n"
+                f"2.  **Generate unique block IDs** for every new block. Use a format like 'block_id_abcdef12'.\n" # Updated ID format hint
+                f"3.  Properly link blocks using `next` and `parent` fields to form execution stacks. Hat blocks (`topLevel: true`, `parent: null`).\n"
+                f"4.  Correctly fill `inputs` and `fields` based on the catalog and the plan's logic (e.g., specific values for motion, keys for events, conditions for controls).\n"
+                f"5.  For C-blocks (like `control_repeat`, `control_forever`, `control_if`), use the `SUBSTACK` input to link to the first block inside its loop/conditional.\n"
+                f"6.  If the plan involves operators (e.g., 'if touching Sprite1'), use the appropriate operator blocks from the catalog and link them correctly as `CONDITION` inputs.\n"
+                f"7.  Ensure that any shadow blocks (e.g., for dropdowns like `motion_goto_menu`, `sensing_touchingobjectmenu`) are generated with `shadow: true` and linked correctly as inputs to their parent block.\n"
+                f"8.  Return ONLY the **updated 'blocks' dictionary** for this specific sprite. Do NOT return the full project JSON. ONLY the `blocks` dictionary."
+            )
+
+            try:
+                response = agent.invoke({"messages": [{"role": "user", "content": llm_block_generation_prompt}]})
+                raw_response = response["messages"][-1].content
+                print(f"Raw response from LLM [ActionNodeBuilder - {sprite_name}]:", raw_response)
+                generated_blocks = extract_json_from_llm_response(raw_response)
+                current_sprite_target["blocks"].update(generated_blocks) # Merge new blocks
+                logger.info(f"Action blocks added for sprite '{sprite_name}' by ActionNodeBuilder.")
+            except Exception as e:
+                logger.error(f"Error generating blocks for sprite '{sprite_name}': {e}")
+                # Depending on robustness needed, you might continue or re-raise
+                raise
+
+    return {"project_json": project_json}
+
+# --- Example Usage (to demonstrate the flow) ---
+if __name__ == "__main__":
+    # Initialize a mock game state
+    initial_game_state = {
+        "description": "A simple game where a sprite moves and says hello.",
+        "project_json": {
+            "targets": [
+                {"isStage": True, "name": "Stage", "blocks": {}},
+                {"isStage": False, "name": "Sprite1", "blocks": {}},
+                {"isStage": False, "name": "Ball", "blocks": {}}
+            ]
+        },
+        "sprite_initial_positions": {}
+    }
+
+    # Step 1: Plan Sprite Actions
+    try:
+        state_after_planning = plan_sprite_actions(initial_game_state)
+        initial_game_state.update(state_after_planning)
+        print("\n--- Game State After Planning ---")
+        print(json.dumps(initial_game_state, indent=2))
+    except Exception as e:
+        print(f"Planning failed: {e}")
+        exit()
+
+    # Step 2: Build Action Nodes (Generate Blocks)
+    try:
+        state_after_building = build_action_nodes(initial_game_state)
+        initial_game_state.update(state_after_building)
+        print("\n--- Game State After Building Blocks ---")
+        # Print only the blocks for a specific sprite to keep output manageable
+        for target in initial_game_state["project_json"]["targets"]:
+            if not target["isStage"]:
+                print(f"\nBlocks for {target['name']}:")
+                print(json.dumps(target.get('blocks', {}), indent=2))
+
+    except Exception as e:
+        print(f"Building blocks failed: {e}")

utils/agent.py

@@ -0,0 +1,1647 @@
+#─── Basic imports ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+import os
+import math
+import sqlite3
+import fitz  # PyMuPDF for PDF parsing
+import re
+
+from dotenv import load_dotenv
+# Load environment variables from .env file
+load_dotenv()  # This line ensures .env variables are loaded
+
+from langgraph.graph import START, StateGraph, MessagesState, END
+from langgraph.prebuilt import tools_condition
+from langgraph.prebuilt import ToolNode
+from langgraph.constants import START
+from langchain_core.tools import tool
+from langchain.schema import SystemMessage
+#from langchain.chat_models import init_chat_model
+#from langgraph.prebuilt import create_react_agent
+
+from langchain.embeddings import HuggingFaceEmbeddings
+#from langchain.vectorstores import Pinecone
+from langchain.tools.retriever import create_retriever_tool
+#import pinecone
+#from pinecone import Pinecone as PineconeClient, ServerlessSpec
+#from pinecone import Index  # the blocking‐call client constructor
+#from pinecone import Pinecone as PineconeClient, ServerlessSpec
+from langchain.embeddings import HuggingFaceEmbeddings
+from langchain_community.vectorstores.pinecone import Pinecone as LC_Pinecone
+
+# ─── Langchain Frameworks ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+#from langchain.tools import Tool
+from langchain.chat_models import ChatOpenAI
+from langchain_groq import ChatGroq
+from langchain_mistralai import ChatMistralAI
+from langchain.agents import initialize_agent, AgentType
+from langchain.schema import Document
+from langchain.chains import RetrievalQA
+from langchain.embeddings import OpenAIEmbeddings
+from langchain_community.embeddings import HuggingFaceEmbeddings
+from langchain.vectorstores import FAISS
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain.prompts import PromptTemplate
+from langchain_community.document_loaders import TextLoader, PyMuPDFLoader
+from langchain_community.document_loaders.wikipedia import WikipediaLoader
+from langchain_community.document_loaders.arxiv import ArxivLoader
+from langchain_experimental.tools.python.tool import PythonREPLTool
+
+
+# ─── Memory ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+from langchain.agents import initialize_agent, AgentType
+from langchain.tools import Tool
+from typing import List, Callable
+from langchain.schema import BaseMemory, AIMessage, HumanMessage, SystemMessage
+from langchain.schema import HumanMessage, SystemMessage
+from langchain.llms.base import LLM
+from langchain.memory.chat_memory import BaseChatMemory
+from pydantic import PrivateAttr
+from langchain_core.messages import get_buffer_string
+            
+# ─── Image Processing ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ 
+from PIL import Image
+import pytesseract
+from transformers import pipeline
+from groq import Groq
+import requests
+from io import BytesIO
+from transformers import pipeline, TrOCRProcessor, VisionEncoderDecoderModel
+import requests
+import base64
+from PIL import UnidentifiedImageError
+
+# ─── Browser var ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+from typing import List, Dict
+import json
+from io import BytesIO
+#from langchain.tools import tool  # or langchain_core.tools
+from playwright.sync_api import sync_playwright
+from duckduckgo_search import DDGS
+import time
+import random
+import logging
+from functools import lru_cache, wraps
+import requests
+from playwright.sync_api import sync_playwright
+from bs4 import BeautifulSoup
+import tenacity
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+# Initialize logger
+logger = logging.getLogger(__name__)
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+
+# Additional imports for new functionality
+import pandas as pd
+from PyPDF2 import PdfReader
+import docx
+import pytesseract
+import speech_recognition as sr
+from pydub import AudioSegment
+from pytube import YouTube
+from newspaper import Article
+from langchain.document_loaders import ArxivLoader
+from langchain_community.document_loaders.youtube import YoutubeLoader, TranscriptFormat
+
+from playwright.sync_api import sync_playwright
+# Attempt to import Playwright for dynamic page rendering
+try:
+    from playwright.sync_api import sync_playwright
+    _playwright_available = True
+except ImportError:
+    _playwright_available = False
+
+# Define forbidden keywords for basic NSFW filtering
+_forbidden = ["porn", "sex", "xxx", "nude", "erotic"]
+
+# ─── LLM Setup ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+# Load OpenAI API key from environment (required for LLM and embeddings)
+
+# API Keys from .env file
+os.environ.setdefault("OPENAI_API_KEY", "<YOUR_OPENAI_KEY>")  # Set your own key or env var
+os.environ["GROQ_API_KEY"] = os.getenv("GROQ_API_KEY", "default_key_or_placeholder")
+os.environ["MISTRAL_API_KEY"] = os.getenv("MISTRAL_API_KEY", "default_key_or_placeholder")
+
+# Tavily API Key
+TAVILY_API_KEY = os.getenv("TAVILY_API_KEY", "default_key_or_placeholder")
+_forbidden = ["nsfw", "porn", "sex", "explicit"]
+_playwright_available = True  # set False to disable Playwright
+
+# Globals for RAG system
+vector_store = None
+rag_chain = None
+DB_PATH = None  # will be set when a .db is uploaded
+DOC_PATH = None  # will be set when a document is uploaded
+IMG_PATH = None  # will be set when an image is uploaded
+OTH_PATH = None  # will be set when an other file is uploaded
+
+
+# ─── LLMS ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+#llm = ChatOpenAI(model_name="gpt-3.5-turbo", streaming=True, temperature=0)
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+# Import the RetryingChatGroq client
+from retry_groq import RetryingChatGroq
+
+# Use the retrying version instead
+llm = RetryingChatGroq(model="deepseek-r1-distill-llama-70b", streaming=False, temperature=0)
+#llm = ChatMistralAI(model="mistral-large-latest", streaming=True, temperature=0)
+
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────── Tool for multiply ──────────────────────────────────────────────────────────────────────
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+@tool(parse_docstring=True)
+def multiply(a: int, b: int) -> int:
+    """
+    Multiply two numbers.
+
+    Args:
+        a (int): The first factor.
+        b (int): The second factor.
+
+    Returns:
+        int: The product of a and b.
+    """
+    try:
+        # Direct calculation without relying on LangChain handling
+        result = a * b
+        return result
+    except Exception as e:
+        return f"Error in multiplication: {str(e)}"
+
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────── Tool for add ──────────────────────────────────────────────────────────────────────────
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+@tool(parse_docstring=True)
+def add(a: int, b: int) -> int:
+    """
+    Add two numbers.
+
+    Args:
+        a (int): The first factor.
+        b (int): The second factor.
+
+    Returns:
+        int: The addition of a and b.
+    """
+    try:
+        # Direct calculation without relying on LangChain handling
+        result = a + b
+        return result
+    except Exception as e:
+        return f"Error in addition: {str(e)}"
+
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────── Tool for subtract ──────────────────────────────────────────────────────────────────────
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+@tool(parse_docstring=True)
+def subtract(a: int, b: int) -> int:
+    """
+    Subtract two numbers.
+
+    Args:
+        a (int): The first factor.
+        b (int): The second factor.
+
+    Returns:
+        int: The subtraction of a and b.
+    """
+    try:
+        # Direct calculation without relying on LangChain handling
+        result = a - b
+        return result
+    except Exception as e:
+        return f"Error in subtraction: {str(e)}"
+
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────── Tool for divide ──────────────────────────────────────────────────────────────────────
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+@tool(parse_docstring=True)
+def divide(a: int, b: int) -> int:
+    """
+    Divide two numbers.
+
+    Args:
+        a (int): The numerator.
+        b (int): The denominator.
+
+    Returns:
+        float: The result of a divided by b.
+
+    Raises:
+        ValueError: If b is zero.
+    """
+    try:
+        if b == 0:
+            return "Error: Cannot divide by zero."
+        # Direct calculation without relying on LangChain handling
+        result = a / b
+        return result
+    except Exception as e:
+        return f"Error in division: {str(e)}"
+
+# ──────────────────────────────────────────────────────────────────────────────────────────────────���───────────────────────────────────────
+# ─────────────────────────────────────────────── Tool for modulus ──────────────────────────────────────────────────────────────────────
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+@tool(parse_docstring=True)
+def modulus(a: int, b: int) -> int:
+    """
+    Get the modulus (remainder) of two numbers.
+
+    Args:
+        a (int): The dividend.
+        b (int): The divisor.
+
+    Returns:
+        int: The remainder when a is divided by b.
+    """
+    try:
+        if b == 0:
+            return "Error: Cannot calculate modulus with zero divisor."
+        # Direct calculation without relying on LangChain handling
+        result = a % b
+        return result
+    except Exception as e:
+        return f"Error in modulus calculation: {str(e)}"
+
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────── Tool for browsing ──────────────────────────────────────────────────────────────────────
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+def with_retry(max_attempts: int = 3, backoff_base: int = 2):
+    """
+    Decorator for retrying a function with exponential backoff on exception.
+    """
+    def decorator(fn):
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            for attempt in range(max_attempts):
+                try:
+                    return fn(*args, **kwargs)
+                except Exception as e:
+                    wait = backoff_base ** attempt + random.uniform(0, 1)
+                    logger.warning(f"{fn.__name__} failed (attempt {attempt+1}/{max_attempts}): {e}")
+                    if attempt < max_attempts - 1:
+                        time.sleep(wait)
+            logger.error(f"{fn.__name__} failed after {max_attempts} attempts.")
+            return []
+        return wrapper
+    return decorator
+
+@with_retry()
+@lru_cache(maxsize=128)
+def tavily_search(query: str, top_k: int = 3) -> List[Dict]:
+    """Call Tavily API and return a list of result dicts."""
+    if not TAVILY_API_KEY:
+        logger.info("[Tavily] No API key set. Skipping Tavily search.")
+        return []
+    url = "https://api.tavily.com/search"
+    headers = {
+        "Authorization": f"Bearer {TAVILY_API_KEY}",
+        "Content-Type": "application/json",
+    }
+    payload = {"query": query, "num_results": top_k}
+    resp = requests.post(url, headers=headers, json=payload, timeout=10)
+    resp.raise_for_status()
+    data = resp.json()
+    results = []
+    for item in data.get("results", []):
+        results.append({
+            "title": item.get("title", ""),
+            "url": item.get("url", ""),
+            "content": item.get("content", "")[:200],
+            "source": "Tavily"
+        })
+    return results
+
+@with_retry()
+@lru_cache(maxsize=128)
+def duckduckgo_search(query: str, top_k: int = 3) -> List[Dict]:
+    """Query DuckDuckGo and return up to top_k raw SERP hits."""
+    results = []
+    try:
+        with DDGS(timeout=15) as ddgs:  # Increase timeout from default
+            for hit in ddgs.text(query, safesearch="On", max_results=top_k, timeout=15):
+                results.append({
+                    "title": hit.get("title", ""),
+                    "url": hit.get("href") or hit.get("url", ""),
+                    "content": hit.get("body", ""),
+                    "source": "DuckDuckGo"
+                })
+                if len(results) >= top_k:
+                    break
+    except Exception as e:
+        logger.warning(f"DuckDuckGo search failed: {e}")
+        # Don't re-raise - just return empty results to allow fallbacks to work
+    
+    return results
+
+# Additional fallback search alternative
+def simple_google_search(query: str, top_k: int = 3) -> List[Dict]:
+    """Simplified Google search as a fallback when other methods fail."""
+    try:
+        # Encode the query
+        import urllib.parse
+        import bs4
+        
+        encoded_query = urllib.parse.quote(query)
+        url = f"https://www.google.com/search?q={encoded_query}"
+        
+        headers = {
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36",
+            "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
+            "Accept-Language": "en-US,en;q=0.5",
+            "Referer": "https://www.google.com/",
+            "Connection": "keep-alive",
+        }
+        
+        response = requests.get(url, headers=headers, timeout=20)
+        response.raise_for_status()
+        
+        soup = bs4.BeautifulSoup(response.text, "html.parser")
+        results = []
+        
+        # Extract search results
+        for result in soup.select("div.g")[:top_k]:
+            title_elem = result.select_one("h3")
+            link_elem = result.select_one("a")
+            snippet_elem = result.select_one("div.VwiC3b")
+            
+            if title_elem and link_elem and snippet_elem and "href" in link_elem.attrs:
+                href = link_elem["href"]
+                if href.startswith("/url?q="):
+                    href = href.split("/url?q=")[1].split("&")[0]
+                
+                if href.startswith("http"):
+                    results.append({
+                        "title": title_elem.get_text(),
+                        "url": href,
+                        "content": snippet_elem.get_text(),
+                        "source": "Google"
+                    })
+        
+        return results
+    
+    except Exception as e:
+        logger.warning(f"Simple Google search failed: {e}")
+        return []
+
+def hybrid_search(query: str, top_k: int = 3) -> List[Dict]:
+    """Combine multiple search sources with fallbacks."""
+    # Try primary search methods first
+    results = []
+    
+    # Start with Tavily if API key is available
+    if TAVILY_API_KEY and TAVILY_API_KEY != "default_key_or_placeholder":
+        try:
+            tavily_results = tavily_search(query, top_k)
+            results.extend(tavily_results)
+            logger.info(f"Retrieved {len(tavily_results)} results from Tavily")
+        except Exception as e:
+            logger.warning(f"Tavily search failed: {e}")
+    
+    # If we don't have enough results, try DuckDuckGo
+    if len(results) < top_k:
+        try:
+            ddg_results = duckduckgo_search(query, top_k - len(results))
+            results.extend(ddg_results)
+            logger.info(f"Retrieved {len(ddg_results)} results from DuckDuckGo")
+        except Exception as e:
+            logger.warning(f"DuckDuckGo search failed: {e}")
+    
+    # If we still don't have enough results, try Google
+    if len(results) < top_k:
+        try:
+            google_results = simple_google_search(query, top_k - len(results))
+            results.extend(google_results)
+            logger.info(f"Retrieved {len(google_results)} results from Google")
+        except Exception as e:
+            logger.warning(f"Google search failed: {e}")
+    
+    # If all search methods failed, return a dummy result
+    if not results:
+        results.append({
+            "title": "Search Failed",
+            "url": "",
+            "content": f"Sorry, I couldn't find results for '{query}'. Please try refining your search terms or check your internet connection.",
+            "source": "No results"
+        })
+    
+    return results[:top_k]  # Ensure we only return top_k results
+
+def format_search_docs(search_docs: List[Dict]) -> Dict[str, str]:
+    """
+    Turn a list of {source, page, content} dicts into one big
+    string with <Document ...>…</Document> entries separated by `---`.
+    """
+    formatted_search_docs = "\n\n---\n\n".join(
+        [
+            f'<Document source="{doc["source"]}" page="{doc.get("page", "")}"/>\n'
+            f'{doc.get("content", "")}\n'
+            f'</Document>'
+            for doc in search_docs
+        ]
+    )
+    return {"web_results": formatted_search_docs}
+
+
+@tool(parse_docstring=True)
+def web_search(query: str, top_k: int = 3) -> Dict[str, str]:
+    """
+    Perform a hybrid web search combining multiple search engines with robust fallbacks.
+
+    Args:
+        query: The search query string to look up.
+        top_k: The maximum number of search results to return (default is 3).
+
+    Returns:
+        A dictionary mapping result indices to XML-like <Document> blocks, each containing:
+        - source: The URL of the webpage.
+        - page: Placeholder for page identifier (empty string by default).
+        - content: The first 200 words of the page text, cleaned of HTML tags.
+    """
+    try:
+        # Use our robust hybrid search to get initial results
+        search_results = hybrid_search(query, top_k)
+        results = []
+        
+        # Process each search result to get better content
+        for hit in search_results:
+            url = hit.get("url")
+            if not url:
+                continue
+                
+            # Start with the snippet from search
+            content = hit.get("content", "")
+            title = hit.get("title", "")
+            
+            # Try to scrape additional content if possible
+            try:
+                # Use a random user agent to avoid blocking
+                headers = {
+                    "User-Agent": random.choice([
+                        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36",
+                        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Safari/605.1.15",
+                        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.45 Safari/537.36",
+                        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.71 Safari/537.36 Edg/97.0.1072.62"
+                    ]),
+                    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
+                    "Accept-Language": "en-US,en;q=0.5",
+                    "Referer": "https://www.google.com/",
+                    "DNT": "1",
+                    "Connection": "keep-alive"
+                }
+                
+                # Higher timeout for better reliability
+                resp = requests.get(url, timeout=15, headers=headers)
+                
+                # Only process if successful
+                if resp.status_code == 200:
+                    soup = BeautifulSoup(resp.text, "html.parser")
+                    
+                    # Try to find main content
+                    main_content = soup.find('main') or soup.find('article') or soup.find('div', class_='content')
+                    
+                    # If we found main content, use it
+                    if main_content:
+                        extracted_text = main_content.get_text(separator=" ", strip=True)
+                        # Take first 200 words
+                        content = " ".join(extracted_text.split()[:200])
+                    else:
+                        # Otherwise use all text
+                        all_text = soup.get_text(separator=" ", strip=True)
+                        content = " ".join(all_text.split()[:200])
+                        
+                    # Use content from page only if it's substantial
+                    if len(content) < 50:
+                        content = hit.get("content", "")[:200]
+                
+                # Random delay between 0.5-1.5 seconds to avoid rate limits
+                time.sleep(0.5 + random.random())
+                
+            except requests.exceptions.HTTPError as e:
+                logger.warning(f"HTTP error when scraping {url}: {e}")
+                # Keep the search snippet as a fallback
+            except requests.exceptions.RequestException as e:
+                logger.warning(f"Request error when scraping {url}: {e}")
+                # Keep the search snippet as a fallback
+            except Exception as e:
+                logger.warning(f"Unexpected error when scraping {url}: {e}")
+                # Keep the search snippet as a fallback
+                
+            # Filter out inappropriate content
+            if any(f in content.lower() for f in _forbidden):
+                continue
+                
+            # Add to results
+            results.append({
+                "source": url,
+                "page": "",
+                "content": content
+            })
+            
+        # Return formatted search docs
+        return format_search_docs(results[:top_k])
+    except Exception as e:
+        logger.error(f"Web search failed: {e}")
+        # Return a helpful error message
+        return format_search_docs([{
+            "source": "Error",
+            "page": "",
+            "content": f"Search failed with error: {e}. Please try again with different search terms."
+        }])
+
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────── Tool for File System ───────────────────────────────────────────────────────────────────
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+@tool(parse_docstring=True)
+def download_file(url: str, dest_path: str) -> str:
+    """
+    Download a file from a given URL and save it locally.
+
+    Args:
+        url: The direct URL of the file to download.
+        dest_path: The local path to save the downloaded file.
+
+    Returns:
+        The destination path where the file was saved.
+    """
+    r = requests.get(url, stream=True)
+    r.raise_for_status()
+    with open(dest_path, 'wb') as f:
+        for chunk in r.iter_content(8192):
+            f.write(chunk)
+    return dest_path
+
+@tool(parse_docstring=True)
+def process_excel_to_text(file_path: str) -> str:
+    """
+    Convert an Excel file into CSV-formatted text.
+
+    Args:
+        file_path: Path to the Excel (.xlsx) file.
+
+    Returns:
+        A string of CSV-formatted content extracted from the Excel file.
+    """
+    try:
+        # Check if file exists
+        import os
+        if not os.path.exists(file_path):
+            return f"Error: Excel file '{file_path}' does not exist."
+            
+        # Try different engines
+        engines = ['openpyxl', 'xlrd', None]
+        
+        for engine in engines:
+            try:
+                # For engine=None, pandas will try to auto-detect
+                if engine:
+                    df = pd.read_excel(file_path, engine=engine)
+                else:
+                    df = pd.read_excel(file_path)
+                return df.to_csv(index=False)
+            except Exception as e:
+                print(f"Excel engine {engine} failed: {e}")
+                last_error = e
+                continue
+        
+        # If we got here, all engines failed
+        return f"Error processing Excel file: {str(last_error)}"
+    except Exception as e:
+        return f"Error with Excel file: {str(e)}"
+    
+@tool(parse_docstring=True)
+def read_text_from_pdf(file_path: str, question: str = None) -> str:
+    """
+    Extract text from a PDF file, chunking large documents if needed.
+
+    Args:
+        file_path: Path to the PDF file.
+        question: Optional question to help retrieve relevant parts of long documents.
+
+    Returns:
+        The extracted text content, potentially chunked if the document is large.
+    """
+    try:
+        # Check if file exists
+        import os
+        if not os.path.exists(file_path):
+            return f"Error: PDF file '{file_path}' does not exist."
+            
+        reader = PdfReader(file_path)
+        full_text = "\n".join([page.extract_text() or "" for page in reader.pages])
+        
+        # If a question is provided, use retrieval to get relevant parts
+        if question and len(full_text) > 5000:  # Only chunk if text is large
+            return process_large_document(full_text, question)
+        
+        return full_text
+    except Exception as e:
+        return f"Error reading PDF: {str(e)}"
+
+@tool(parse_docstring=True)
+def read_text_from_docx(file_path: str, question: str = None) -> str:
+    """
+    Extract text from a DOCX (Word) document, chunking large documents if needed.
+
+    Args:
+        file_path: Path to the DOCX file.
+        question: Optional question to help retrieve relevant parts of long documents.
+
+    Returns:
+        The extracted text, potentially chunked if the document is large.
+    """
+    try:
+        # Check if file exists
+        import os
+        if not os.path.exists(file_path):
+            return f"Error: File '{file_path}' does not exist."
+            
+        try:
+            doc = docx.Document(file_path)
+            full_text = "\n".join([para.text for para in doc.paragraphs])
+        except Exception as docx_err:
+            # Handle "Package not found" error specifically
+            if "Package not found" in str(docx_err):
+                # Try to read raw text if possible
+                try:
+                    import zipfile
+                    from xml.etree.ElementTree import XML
+                    
+                    WORD_NAMESPACE = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
+                    PARA = WORD_NAMESPACE + 'p'
+                    TEXT = WORD_NAMESPACE + 't'
+                    
+                    with zipfile.ZipFile(file_path) as docx_file:
+                        with docx_file.open('word/document.xml') as document:
+                            tree = XML(document.read())
+                            paragraphs = []
+                            for paragraph in tree.iter(PARA):
+                                texts = [node.text for node in paragraph.iter(TEXT) if node.text]
+                                if texts:
+                                    paragraphs.append(''.join(texts))
+                            full_text = '\n'.join(paragraphs)
+                except Exception as e:
+                    return f"Error reading DOCX file: {str(e)}"
+            else:
+                return f"Error reading DOCX file: {str(docx_err)}"
+        
+        # If a question is provided, use retrieval to get relevant parts
+        if question and len(full_text) > 5000:  # Only chunk if text is large
+            return process_large_document(full_text, question)
+        
+        return full_text
+    except Exception as e:
+        return f"Error reading DOCX file: {str(e)}"
+
+
+@tool(parse_docstring=True)
+def transcribe_audio(file_path: str) -> str:
+    """
+    Transcribe speech from a local audio file to text.
+
+    Args:
+        file_path: Path to the audio file.
+
+    Returns:
+        Transcribed text using Google Web Speech API.
+    """
+    try:
+        # Check if file exists
+        import os
+        if not os.path.exists(file_path):
+            return f"Error: Audio file '{file_path}' does not exist."
+            
+        # For non-WAV files, convert to WAV first
+        if not file_path.lower().endswith('.wav'):
+            try:
+                from pydub import AudioSegment
+                temp_wav = os.path.splitext(file_path)[0] + "_temp.wav"
+                audio = AudioSegment.from_file(file_path)
+                audio.export(temp_wav, format="wav")
+                file_path = temp_wav
+            except Exception as e:
+                return f"Failed to convert audio to WAV format: {str(e)}"
+                
+        recognizer = sr.Recognizer()
+        with sr.AudioFile(file_path) as src:
+            audio = recognizer.record(src)
+        return recognizer.recognize_google(audio)
+    except Exception as e:
+        if "Audio file could not be read" in str(e):
+            return f"Error: Audio format not supported. Try converting to WAV, MP3, OGG, or FLAC."
+        return f"Error transcribing audio: {str(e)}"
+
+@tool(parse_docstring=True)
+def youtube_audio_processing(youtube_url: str) -> str:
+    """
+    Download and transcribe audio from a YouTube video.
+
+    Args:
+        youtube_url: URL of the YouTube video.
+
+    Returns:
+        Transcription text extracted from the video's audio.
+    """
+    yt = YouTube(youtube_url)
+    audio_stream = yt.streams.filter(only_audio=True).first()
+    out_file = audio_stream.download(output_path='.', filename='yt_audio')
+    wav_path = 'yt_audio.wav'
+    AudioSegment.from_file(out_file).export(wav_path, format='wav')
+    return transcribe_audio(wav_path)
+
+@tool(parse_docstring=True)
+def extract_article_text(url: str, question: str = None) -> str:
+    """
+    Download and extract the main article content from a webpage, chunking large articles if needed.
+
+    Args:
+        url: The URL of the article to extract.
+        question: Optional question to help retrieve relevant parts of long articles.
+
+    Returns:
+        The article's textual content, potentially chunked if large.
+    """
+    try:
+        art = Article(url)
+        art.download()
+        art.parse()
+        full_text = art.text
+        
+        # If a question is provided, use retrieval to get relevant parts
+        if question and len(full_text) > 5000:  # Only chunk if text is large
+            return process_large_document(full_text, question)
+        
+        return full_text
+    except Exception as e:
+        return f"Error extracting article: {str(e)}"
+
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+# ───────────────────────────────────────────────────────────── Tool for ArXiv ────────────────────────────────────────────────────────────
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+@tool(parse_docstring=True)
+def arvix_search(query: str) -> Dict[str, str]:
+    """
+    Search for academic papers on ArXiv.
+
+    Args:
+        query: The search term to look for in ArXiv.
+
+    Returns:
+        A dictionary of up to 3 relevant paper entries in JSON format.
+    """
+    papers = ArxivLoader(query=query, load_max_docs=3).load()
+    results = []
+    for doc in papers:
+        try:
+            # Handle different metadata formats that might be returned
+            source = doc.metadata.get("source", "ArXiv")
+            doc_id = doc.metadata.get("id", doc.metadata.get("entry_id", ""))
+            result = {
+                "source": source,
+                "id": doc_id,
+                "summary": doc.page_content[:1000] if hasattr(doc, "page_content") else str(doc)[:1000],
+            }
+            results.append(result)
+        except Exception as e:
+            # Add error information as a fallback
+            results.append({
+                "source": "ArXiv Error",
+                "id": "error",
+                "summary": f"Error processing paper: {str(e)}"
+            })
+    
+    return {"arvix_results": json.dumps(results)}
+
+@tool(parse_docstring=True)
+def answer_youtube_video_question(
+    youtube_url: str,
+    question: str,
+    chunk_size_seconds: int = 30
+) -> str:
+    """
+    Answer a question based on a YouTube video's transcript.
+
+    Args:
+        youtube_url: URL of the YouTube video.
+        question: The question to be answered using video content.
+        chunk_size_seconds: Duration of each transcript chunk.
+
+    Returns:
+        The answer to the question generated from the video transcript.
+    """
+    loader = YoutubeLoader.from_youtube_url(
+        youtube_url,
+        add_video_info=True,
+        transcript_format=TranscriptFormat.CHUNKS,
+        chunk_size_seconds=chunk_size_seconds,
+    )
+    documents = loader.load()
+    embeddings = HuggingFaceEmbeddings(model_name='sentence-transformers/all-mpnet-base-v2')
+    vectorstore = FAISS.from_documents(documents, embeddings)
+    llm = RetryingChatGroq(model="deepseek-r1-distill-llama-70b", streaming=False)
+    qa_chain = RetrievalQA.from_chain_type(llm=llm, retriever=vectorstore.as_retriever())
+    return qa_chain.run(question)
+
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+# ───────────────────────────────────────────────────────────── Tool for Python REPL tool ────────────────────────────────────────────────
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+python_repl = PythonREPLTool()
+
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+# ───────────────────────────────────────────────────────────── Tool for Wiki ────────────────────────────────────────────────────────────
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+@tool(parse_docstring=True)
+def wiki_search(query: str) -> str:
+    """
+    Search Wikipedia for information on a given topic.
+
+    Args:
+        query: The search term for Wikipedia.
+
+    Returns:
+        A JSON string with up to 3 summary results.
+    """
+    # load up to top_k pages
+    pages = WikipediaLoader(query=query, load_max_docs=3).load()
+    results: List[Dict] = []
+    for doc in pages:
+        results.append({
+            "source": doc.metadata["source"],
+            "page": doc.metadata.get("page", ""),
+            "content": doc.page_content[:1000],  # truncate if you like
+        })
+    return {"wiki_results": format_search_docs(results)}
+
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+# ───────────────────────────────────── Tool for Image (understading, captioning & classification) ─────────────────────────────────────────
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+def _load_image(img_path: str, resize_to=(512, 512)) -> Image.Image:
+    """
+    Load, verify, convert, and resize an image.
+    Raises ValueError on failure.
+    """
+    if not img_path:
+        raise ValueError("No image path provided.")
+    try:
+        with Image.open(img_path) as img:
+            img.verify()
+        img = Image.open(img_path).convert("RGB")
+        img = img.resize(resize_to)
+        return img
+    except UnidentifiedImageError:
+        raise ValueError(f"File at {img_path} is not a valid image.")
+    except Exception as e:
+        raise ValueError(f"Failed to load image at {img_path}: {e}")
+
+def _encode_image_to_base64(img_path: str) -> str:
+    """
+    Load an image, save optimized PNG into memory, and base64‑encode it.
+    """
+    img = _load_image(img_path)
+    buffer = BytesIO()
+    img.save(buffer, format="PNG", optimize=True)
+    return base64.b64encode(buffer.getvalue()).decode("utf-8")
+
+@tool
+def image_processing(prompt: str, img_path: str) -> str:
+    """Process an image using a vision LLM, with OCR fallback.
+
+    Args:
+        prompt: Instruction or question related to the image.
+        img_path: Path to the image file.
+
+    Returns:
+        The model's response or fallback OCR result.
+    """
+    try:
+        import os
+        # Check if file exists
+        if not os.path.exists(img_path):
+            return f"Error: Image file '{img_path}' does not exist."
+            
+        try:
+            b64 = _encode_image_to_base64(img_path)
+            # Build a single markdown string with inline base64 image
+            md = f"{prompt}\n\n![](data:image/png;base64,{b64})"
+            message = HumanMessage(content=md)
+            # Use RetryingChatGroq with Llama 4 Maverick for vision
+            llm = RetryingChatGroq(model="meta-llama/llama-4-maverick-17b-128e-instruct", streaming=False, temperature=0)
+            try:
+                resp = llm.invoke([message])
+                if hasattr(resp, 'content'):
+                    return resp.content.strip()
+                elif isinstance(resp, str):
+                    return resp.strip()
+                else:
+                    # Handle dictionary or other response types
+                    return str(resp)
+            except Exception as invoke_err:
+                print(f"[LLM invoke error] {invoke_err}")
+                # Fall back to OCR
+                raise ValueError("LLM invocation failed")
+        except Exception as llama_err:
+            print(f"[LLM vision failed] {llama_err}")
+            try:
+                img = _load_image(img_path)
+                return pytesseract.image_to_string(img).strip()
+            except Exception as ocr_err:
+                print(f"[OCR fallback failed] {ocr_err}")
+                return "Unable to process the image. Please check the file and try again."
+    except Exception as e:
+        # Catch any other errors
+        print(f"[image_processing error] {e}")
+        return f"Error processing image: {str(e)}"
+
+python_repl_tool = PythonREPLTool()
+
+@tool
+def echo(text: str) -> str:
+    """Echo back the input text.
+
+    Args:
+        text: The string to be echoed.
+        
+    Returns:
+        The same text that was provided as input.
+    """
+    return text
+
+# ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────��───────────────────
+# ─────────────────────────────────────────────── Langgraph Agent ───────────────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+
+# Build graph function
+from langchain_core.tools import tool
+from langchain.chat_models import ChatOpenAI
+from langgraph.prebuilt.chat_agent_executor import create_react_agent, AgentState
+from langchain.chat_models import init_chat_model
+
+
+
+def build_graph(provider: str = "groq"):
+    """Construct and compile the multi‑agent GAIA workflow StateGraph.
+
+    This graph wires together three React‑style agents into a streamlined pipeline:
+    PerceptionAgent → ActionAgent → EvaluationAgent (with appropriate entry/exit points)
+    
+    The agents have the following responsibilities:
+    - PerceptionAgent: Handles web searches, Wikipedia, ArXiv, and image processing
+    - ActionAgent: Performs calculations, file operations, and code analysis
+    - EvaluationAgent: Reviews results and ensures the final answer is properly formatted
+
+    Args:
+        provider: The name of the LLM provider. Must be "groq".
+
+    Returns:
+        CompiledGraph: A compiled LangGraph state machine ready for invocation.
+
+    Raises:
+        ValueError: If `provider` is anything other than "groq".
+    """
+    try:
+        if provider != "groq":
+            raise ValueError("Invalid provider. Expected 'groq'.")
+        
+        # Initialize LLM
+        try:
+            logger.info("Initializing LLM with model: deepseek-r1-distill-llama-70b")
+            api_key = os.getenv("GROQ_API_KEY")
+            if not api_key or api_key == "default_key_or_placeholder":
+                logger.error("GROQ_API_KEY is not set or is using placeholder value")
+                raise ValueError("GROQ_API_KEY environment variable is not set properly. Please set a valid API key.")
+                
+            llm = RetryingChatGroq(model="deepseek-r1-distill-llama-70b", temperature=0)
+            logger.info("LLM initialized successfully")
+        except Exception as e:
+            logger.error(f"Error initializing LLM: {str(e)}")
+            raise
+        
+        # General system message for agents
+        sys_msg = SystemMessage(content="""
+        You are a general AI assistant. I will ask you a question. Report your thoughts, and finish your answer with the following template:
+
+        FINAL ANSWER: [YOUR FINAL ANSWER]
+
+        YOUR FINAL ANSWER should be a number OR as few words as possible OR a comma-separated list of numbers and/or strings.
+
+        If you are asked for a number, don't use commas or units (e.g., $, %, kg) unless specified otherwise.
+
+        If you are asked for a string, don't use articles (a, an, the), and don't use abbreviations (e.g., for states).
+
+        If you are asked for a comma-separated list, apply the above rules to each element in the list.
+                """.strip())
+                
+        # Special system message for the evaluation agent with stricter formatting requirements
+        eval_sys_msg = SystemMessage(content="""
+        You are a specialized evaluation agent. Your job is to review the work done by other agents
+        and provide a final, properly formatted answer.
+        
+        IMPORTANT: You MUST ALWAYS format your answer using this exact template:
+        
+        FINAL ANSWER: [concise answer]
+        
+        Rules for formatting the answer:
+        1. The answer must be extremely concise - use as few words as possible
+        2. For numeric answers, provide only the number without units unless units are specifically requested
+        3. For text answers, avoid articles (a, an, the) and unnecessary words
+        4. For list answers, use a comma-separated format
+        5. NEVER explain your reasoning in the FINAL ANSWER section
+        6. NEVER skip the "FINAL ANSWER:" prefix
+        
+        Example good answers:
+        FINAL ANSWER: 42
+        FINAL ANSWER: Paris
+        FINAL ANSWER: 1912, 1945, 1989
+        
+        Example bad answers (don't do these):
+        - Based on my analysis, the answer is 42.
+        - I think it's Paris because that's the capital of France.
+        - The years were 1912, 1945, and 1989.
+        
+        Remember: ALWAYS include "FINAL ANSWER:" followed by the most concise answer possible.
+        """.strip())
+                
+        # Define tools for each agent
+        logger.info("Setting up agent tools")
+        perception_tools = [web_search, wiki_search, news_article_search, arvix_search, image_processing, echo]
+        execution_tools = [
+            multiply, add, subtract, divide, modulus,
+            download_file, process_excel_to_text,
+            read_text_from_pdf, read_text_from_docx,
+            transcribe_audio, youtube_audio_processing,
+            extract_article_text, answer_youtube_video_question,
+            python_repl_tool, analyze_code, read_code_file, analyze_python_function
+        ]
+        
+        # ─────────────── Agent Creation ───────────────
+        logger.info("Creating agents")
+        try:
+            # Create agents with proper error handling
+            PerceptionAgent = create_react_agent(
+                model=llm,
+                tools=perception_tools,
+                prompt=sys_msg,
+                state_schema=AgentState,
+                name="PerceptionAgent"
+            )
+            logger.info("Created PerceptionAgent successfully")
+            
+            # Combined Planning and Execution agent for better efficiency
+            ActionAgent = create_react_agent(
+                model=llm,
+                tools=execution_tools,  # Has access to all execution tools
+                prompt=sys_msg,
+                state_schema=AgentState,
+                name="ActionAgent"
+            )
+            logger.info("Created ActionAgent successfully")
+            
+            # Evaluation agent with stricter prompt
+            EvaluationAgent = create_react_agent(
+                model=llm,
+                tools=[],  # No tools needed for evaluation
+                prompt=eval_sys_msg,  # Use the specialized evaluation prompt
+                state_schema=AgentState,
+                name="EvaluationAgent"
+            )
+            logger.info("Created EvaluationAgent successfully")
+        except Exception as e:
+            logger.error(f"Error creating agent: {str(e)}")
+            import traceback
+            logger.error(f"Traceback: {traceback.format_exc()}")
+            raise
+        
+        # Build the StateGraph
+        logger.info("Building StateGraph")
+        try:
+            builder = StateGraph(AgentState)
+            
+            # Add agent nodes first
+            builder.add_node("PerceptionAgent", PerceptionAgent)
+            builder.add_node("ActionAgent", ActionAgent)
+            builder.add_node("EvaluationAgent", EvaluationAgent)
+            
+            # Define the flow with a starting edge
+            builder.set_entry_point("PerceptionAgent")
+            
+            # Add the edges for the simpler linear flow
+            builder.add_edge("PerceptionAgent", "ActionAgent")
+            builder.add_edge("ActionAgent", "EvaluationAgent")
+            
+            # Set EvaluationAgent as the end node
+            builder.set_finish_point("EvaluationAgent")
+            
+            logger.info("Compiling StateGraph")
+            return builder.compile()
+        except Exception as e:
+            logger.error(f"Error building graph: {str(e)}")
+            import traceback
+            logger.error(f"Traceback: {traceback.format_exc()}")
+            raise
+    except Exception as e:
+        logger.error(f"Overall error in build_graph: {str(e)}")
+        import traceback
+        logger.error(f"Traceback: {traceback.format_exc()}")
+        raise
+
+def get_final_answer(text):
+    """Extract just the FINAL ANSWER from the model's response.
+    
+    Args:
+        text: The full text response from the LLM
+        
+    Returns:
+        str: The extracted answer without the "FINAL ANSWER:" prefix
+    """
+    # Log the raw text for debugging if needed
+    logger.debug(f"Extracting answer from: {text[:200]}...")
+    
+    if not text:
+        logger.warning("Empty response received")
+        return "No answer provided."
+    
+    # Method 1: Look for "FINAL ANSWER:" with most comprehensive pattern matching
+    pattern = r'(?:^|\n)FINAL ANSWER:\s*(.*?)(?:\n\s*$|$)'
+    match = re.search(pattern, text, re.DOTALL | re.IGNORECASE)
+    if match:
+        # Return just the answer part, cleaned up
+        logger.debug("Found answer using pattern 1")
+        return match.group(1).strip()
+    
+    # Method 2: Try looking for variations on the final answer format
+    for variant in ["FINAL ANSWER:", "FINAL_ANSWER:", "Final Answer:", "Answer:"]:
+        lines = text.split('\n')
+        for i, line in enumerate(reversed(lines)):
+            if variant in line:
+                # Extract everything after the variant text
+                logger.debug(f"Found answer using variant: {variant}")
+                answer = line[line.find(variant) + len(variant):].strip()
+                if answer:
+                    return answer
+                # If the answer is on the next line, return that
+                if i > 0:
+                    next_line = lines[len(lines) - i]
+                    if next_line.strip():
+                        return next_line.strip()
+    
+    # Method 3: Look for phrases that suggest an answer
+    for phrase in ["The answer is", "The result is", "We get", "Therefore,", "In conclusion,"]:
+        phrase_pos = text.find(phrase)
+        if phrase_pos != -1:
+            # Try to extract everything after the phrase until the end of the sentence
+            sentence_end = text.find(".", phrase_pos)
+            if sentence_end != -1:
+                logger.debug(f"Found answer using phrase: {phrase}")
+                return text[phrase_pos + len(phrase):sentence_end].strip()
+    
+    # Method 4: Fall back to taking the last paragraph with actual content
+    paragraphs = text.strip().split('\n\n')
+    for para in reversed(paragraphs):
+        para = para.strip()
+        if para and not para.startswith("I ") and not para.lower().startswith("to "):
+            logger.debug("Using last meaningful paragraph")
+            # If paragraph is very long, try to extract a concise answer
+            if len(para) > 100:
+                sentences = re.split(r'[.!?]', para)
+                for sentence in reversed(sentences):
+                    sent = sentence.strip()
+                    if sent and len(sent) > 5 and not sent.startswith("I "):
+                        return sent
+            return para
+    
+    # Method 5: Last resort - just return the last line with content
+    lines = text.strip().split('\n')
+    for line in reversed(lines):
+        line = line.strip()
+        if line and len(line) > 3:
+            logger.debug("Using last line with content")
+            return line
+    
+    # If everything fails, warn and return the truncated response
+    logger.warning("Could not find a properly formatted answer")
+    return text[:100] + "..." if len(text) > 100 else text
+
+# test
+if __name__ == "__main__":
+    question = "When was a picture of St. Thomas Aquinas first added to the Wikipedia page on the Principle of double effect?"
+    # Build the graph
+    graph = build_graph(provider="groq")
+    # Run the graph
+    messages = [HumanMessage(content=question)]
+    messages = graph.invoke({"messages": messages})
+    for m in messages["messages"]:
+        m.pretty_print()
+
+# ─────────────────────────────────────────────── Tool for Code Analysis ───────────────────────────────────────────────────────────────
+@tool
+def analyze_code(code_string: str) -> str:
+    """Analyze a string of code to understand its structure, functionality, and potential issues.
+
+    Args:
+        code_string: The code to analyze as a string.
+
+    Returns:
+        A structured analysis of the code including functions, classes, and key operations.
+    """
+    try:
+        import ast
+        
+        # Try to parse with Python's AST module
+        try:
+            parsed = ast.parse(code_string)
+            
+            # Extract functions and classes
+            functions = [node.name for node in ast.walk(parsed) if isinstance(node, ast.FunctionDef)]
+            classes = [node.name for node in ast.walk(parsed) if isinstance(node, ast.ClassDef)]
+            imports = [node.names[0].name for node in ast.walk(parsed) if isinstance(node, ast.Import)]
+            imports.extend([f"{node.module}.{name.name}" if node.module else name.name 
+                           for node in ast.walk(parsed) if isinstance(node, ast.ImportFrom)
+                           for name in node.names])
+            
+            # Count various node types for complexity assessment
+            num_loops = len([node for node in ast.walk(parsed) 
+                            if isinstance(node, (ast.For, ast.While))])
+            num_conditionals = len([node for node in ast.walk(parsed) 
+                                   if isinstance(node, (ast.If, ast.IfExp))])
+            
+            analysis = {
+                "language": "Python",
+                "functions": functions,
+                "classes": classes,
+                "imports": imports,
+                "complexity": {
+                    "functions": len(functions),
+                    "classes": len(classes),
+                    "loops": num_loops,
+                    "conditionals": num_conditionals
+                }
+            }
+            return str(analysis)
+        except SyntaxError:
+            # If not valid Python, try some simple pattern matching
+            if "{" in code_string and "}" in code_string:
+                if "function" in code_string or "=>" in code_string:
+                    language = "JavaScript/TypeScript"
+                elif "func" in code_string or "struct" in code_string:
+                    language = "Go or Rust"
+                elif "public" in code_string or "private" in code_string or "class" in code_string:
+                    language = "Java/C#/C++"
+                else:
+                    language = "Unknown C-like language"
+            elif "<" in code_string and ">" in code_string and ("/>" in code_string or "</"):
+                language = "HTML/XML/JSX"
+            else:
+                language = "Unknown"
+                
+            return f"Non-Python code detected ({language}). Basic code structure analysis not available."
+    except Exception as e:
+        return f"Error analyzing code: {str(e)}"
+
+@tool
+def read_code_file(file_path: str) -> str:
+    """Read a code file and return its contents with proper syntax detection.
+
+    Args:
+        file_path: Path to the code file.
+
+    Returns:
+        The file contents and detected language.
+    """
+    try:
+        # Check if file exists
+        import os
+        if not os.path.exists(file_path):
+            return f"Error: File '{file_path}' does not exist."
+            
+        with open(file_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+        
+        # Try to detect language from extension
+        ext = os.path.splitext(file_path)[1].lower()
+        
+        language_map = {
+            '.py': 'Python',
+            '.js': 'JavaScript',
+            '.ts': 'TypeScript',
+            '.html': 'HTML',
+            '.css': 'CSS',
+            '.java': 'Java',
+            '.c': 'C',
+            '.cpp': 'C++',
+            '.cs': 'C#',
+            '.go': 'Go',
+            '.rs': 'Rust',
+            '.php': 'PHP',
+            '.rb': 'Ruby',
+            '.sh': 'Shell',
+            '.bat': 'Batch',
+            '.ps1': 'PowerShell',
+            '.sql': 'SQL',
+            '.json': 'JSON',
+            '.xml': 'XML',
+            '.yaml': 'YAML',
+            '.yml': 'YAML',
+        }
+        
+        language = language_map.get(ext, 'Unknown')
+        
+        return f"File content ({language}):\n\n{content}"
+    except Exception as e:
+        return f"Error reading file: {str(e)}"
+
+@tool
+def analyze_python_function(function_name: str, code_string: str) -> str:
+    """Extract and analyze a specific function from Python code.
+    
+    Args:
+        function_name: The name of the function to analyze.
+        code_string: The complete code containing the function.
+        
+    Returns:
+        Analysis of the function including parameters, return type, and docstring.
+    """
+    try:
+        import ast
+        import inspect
+        from types import CodeType, FunctionType
+        
+        # Parse the code string
+        parsed = ast.parse(code_string)
+        
+        # Find the function definition
+        function_def = None
+        for node in ast.walk(parsed):
+            if isinstance(node, ast.FunctionDef) and node.name == function_name:
+                function_def = node
+                break
+        
+        if not function_def:
+            return f"Function '{function_name}' not found in the provided code."
+        
+        # Extract parameters
+        params = []
+        for arg in function_def.args.args:
+            param_name = arg.arg
+            # Get annotation if it exists
+            if arg.annotation:
+                if isinstance(arg.annotation, ast.Name):
+                    param_type = arg.annotation.id
+                elif isinstance(arg.annotation, ast.Attribute):
+                    param_type = f"{arg.annotation.value.id}.{arg.annotation.attr}"
+                else:
+                    param_type = "complex_type"
+                params.append(f"{param_name}: {param_type}")
+            else:
+                params.append(param_name)
+        
+        # Extract return type if it exists
+        return_type = None
+        if function_def.returns:
+            if isinstance(function_def.returns, ast.Name):
+                return_type = function_def.returns.id
+            elif isinstance(function_def.returns, ast.Attribute):
+                return_type = f"{function_def.returns.value.id}.{function_def.returns.attr}"
+            else:
+                return_type = "complex_return_type"
+        
+        # Extract docstring
+        docstring = ast.get_docstring(function_def)
+        
+        # Create a summary
+        summary = {
+            "function_name": function_name,
+            "parameters": params,
+            "return_type": return_type,
+            "docstring": docstring,
+            "decorators": [d.id if isinstance(d, ast.Name) else "complex_decorator" for d in function_def.decorator_list],
+            "line_count": len(function_def.body)
+        }
+        
+        # Create a more explicit string representation that ensures key terms are included
+        result = f"Function '{function_name}' analysis:\n"
+        result += f"- Parameters: {', '.join(params)}\n"
+        result += f"- Return type: {return_type or 'None specified'}\n"
+        result += f"- Docstring: {docstring or 'None'}\n"
+        result += f"- Line count: {len(function_def.body)}"
+        
+        return result
+    except Exception as e:
+        return f"Error analyzing function: {str(e)}"
+
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────── Tool for News Article Retrieval ──────────────────────────────────────────────────────────────────────
+# ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+@tool
+def news_article_search(query: str, top_k: int = 3) -> Dict[str, str]:
+    """Search for and retrieve news articles with robust error handling for news sites.
+
+    Args:
+        query: The news topic or keywords to search for.
+        top_k: Maximum number of articles to retrieve.
+
+    Returns:
+        A dictionary with search results formatted as XML-like document entries.
+    """
+    # First, get URLs from DuckDuckGo with "news" focus
+    results = []
+    news_sources = [
+        "bbc.com", "reuters.com", "apnews.com", "nasa.gov", 
+        "space.com", "universetoday.com", "nature.com", "science.org",
+        "scientificamerican.com", "nytimes.com", "theguardian.com"
+    ]
+    
+    # Find news from reliable sources
+    try:
+        with DDGS() as ddgs:
+            search_query = f"{query} site:{' OR site:'.join(news_sources)}"
+            for hit in ddgs.text(search_query, safesearch="On", max_results=top_k*2):
+                url = hit.get("href") or hit.get("url", "")
+                if not url:
+                    continue
+                
+                # Add the search snippet first as a fallback
+                result = {
+                    "source": url,
+                    "page": "",
+                    "content": hit.get("body", "")[:250],
+                    "title": hit.get("title", "")
+                }
+                
+                # Try to get better content via a more robust method
+                try:
+                    headers = {
+                        "User-Agent": random.choice([
+                            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36",
+                            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Safari/605.1.15",
+                            "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.45 Safari/537.36"
+                        ]),
+                        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
+                        "Accept-Language": "en-US,en;q=0.5",
+                        "Referer": "https://www.google.com/",
+                        "DNT": "1",
+                        "Connection": "keep-alive",
+                        "Upgrade-Insecure-Requests": "1"
+                    }
+                    
+                    # Add a short delay between requests
+                    time.sleep(1 + random.random())
+                    
+                    # Try to use newspaper3k for more reliable article extraction
+                    from newspaper import Article
+                    article = Article(url)
+                    article.download()
+                    article.parse()
+                    
+                    # If we got meaningful content, update the result
+                    if article.text and len(article.text) > 100:
+                        # Get a summary - first paragraph + some highlights
+                        paragraphs = article.text.split('\n\n')
+                        first_para = paragraphs[0] if paragraphs else ""
+                        summary = first_para[:300]
+                        if len(paragraphs) > 1:
+                            summary += "... " + paragraphs[1][:200]
+                            
+                        result["content"] = summary
+                        if article.title:
+                            result["title"] = article.title
+                
+                except Exception as article_err:
+                    logger.warning(f"Article extraction failed for {url}: {article_err}")
+                    # Fallback to simple requests-based extraction
+                    try:
+                        resp = requests.get(url, timeout=12, headers=headers)
+                        resp.raise_for_status()
+                        soup = BeautifulSoup(resp.text, "html.parser")
+                        
+                        # Try to get main content
+                        main_content = soup.find('main') or soup.find('article') or soup.find('div', class_='content')
+                        
+                        if main_content:
+                            content = " ".join(main_content.get_text(separator=" ", strip=True).split()[:250])
+                            result["content"] = content
+                    except Exception as req_err:
+                        logger.warning(f"Fallback extraction failed for {url}: {req_err}")
+                        # Keep the original snippet as fallback
+                
+                results.append(result)
+                if len(results) >= top_k:
+                    break
+    
+    except Exception as e:
+        logger.error(f"News search failed: {e}")
+        return format_search_docs([{
+            "source": "Error",
+            "page": "",
+            "content": f"Failed to retrieve news articles for '{query}': {str(e)}"
+        }])
+    
+    if not results:
+        # Fallback to regular web search
+        logger.info(f"No news results found, falling back to web_search for {query}")
+        return web_search(query, top_k)
+    
+    return format_search_docs(results[:top_k])
+
+# ───────────────────────────────────────────────────────────── Document Chunking Utilities ──────────────────────────────────────────────────────────
+def chunk_document(text: str, chunk_size: int = 1000, overlap: int = 100) -> List[str]:
+    """
+    Split a large document into smaller chunks with overlap to maintain context across chunks.
+    
+    Args:
+        text: The document text to split into chunks
+        chunk_size: Maximum size of each chunk in characters
+        overlap: Number of characters to overlap between chunks
+        
+    Returns:
+        List of text chunks
+    """
+    # If text is smaller than chunk_size, return it as is
+    if len(text) <= chunk_size:
+        return [text]
+    
+    chunks = []
+    start = 0
+    
+    while start < len(text):
+        # Get chunk with overlap
+        end = min(start + chunk_size, len(text))
+        
+        # Try to find sentence boundary for cleaner breaks
+        if end < len(text):
+            # Look for sentence endings: period, question mark, or exclamation followed by space
+            for sentence_end in ['. ', '? ', '! ']:
+                last_period = text[start:end].rfind(sentence_end)
+                if last_period != -1:
+                    end = start + last_period + 2  # +2 to include the period and space
+                    break
+        
+        # Add chunk to list
+        chunks.append(text[start:end])
+        
+        # Move start position, accounting for overlap
+        start = end - overlap if end < len(text) else len(text)
+    
+    return chunks
+
+# Document processing utility that uses chunking
+def process_large_document(text: str, question: str, llm=None) -> str:
+    """
+    Process a large document by chunking it and using retrieval to find relevant parts.
+    
+    Args:
+        text: The document text to process
+        question: The question being asked about the document
+        llm: Optional language model to use (defaults to agent's LLM)
+        
+    Returns:
+        Summarized answer based on relevant chunks
+    """
+    if not llm:
+        llm = RetryingChatGroq(model="deepseek-r1-distill-llama-70b", streaming=False, temperature=0)
+    
+    # Split document into chunks
+    chunks = chunk_document(text)
+    
+    # If document is small enough, don't bother with retrieval
+    if len(chunks) <= 1:
+        return text
+    
+    # For larger documents, create embeddings to find relevant chunks
+    try:
+        from langchain_community.embeddings import HuggingFaceEmbeddings
+        from langchain.vectorstores import FAISS
+        from langchain.schema import Document
+        
+        # Create documents with chunk content
+        documents = [Document(page_content=chunk, metadata={"chunk_id": i}) for i, chunk in enumerate(chunks)]
+        
+        # Create embeddings and vector store
+        embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-mpnet-base-v2")
+        vectorstore = FAISS.from_documents(documents, embeddings)
+        
+        # Get most relevant chunks
+        relevant_chunks = vectorstore.similarity_search(question, k=2)  # Get top 2 most relevant chunks
+        
+        # Join the relevant chunks
+        relevant_text = "\n\n".join([doc.page_content for doc in relevant_chunks])
+        
+        # Option 1: Return relevant chunks directly
+        return relevant_text
+        
+        # Option 2: Summarize with LLM (commented out for now)
+        # prompt = f"Using only the following information, answer the question: '{question}'\n\nInformation:\n{relevant_text}"
+        # response = llm.invoke([HumanMessage(content=prompt)])
+        # return response.content
+    
+    except Exception as e:
+        # Fall back to first chunk if retrieval fails
+        logger.warning(f"Retrieval failed: {e}. Falling back to first chunk.")
+        return chunks[0]

utils/agent2.py

@@ -0,0 +1,259 @@
+import os
+from dotenv import load_dotenv
+
+from langchain_core.tools import tool
+from langgraph.prebuilt import tools_condition, ToolNode
+from langgraph.graph import START, StateGraph, MessagesState
+
+from langchain_community.tools.tavily_search import TavilySearchResults
+from langchain_community.document_loaders import WikipediaLoader, ArxivLoader
+from langchain_core.messages import SystemMessage, HumanMessage
+from langchain_community.vectorstores import FAISS 
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_groq import ChatGroq
+from langchain.tools.retriever import create_retriever_tool
+
+"""LangGraph Agent"""
+import os
+from dotenv import load_dotenv
+from langgraph.graph import START, StateGraph, MessagesState
+from langgraph.prebuilt import tools_condition
+from langgraph.prebuilt import ToolNode
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain_groq import ChatGroq
+from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint, HuggingFaceEmbeddings
+from langchain_community.tools.tavily_search import TavilySearchResults
+from langchain_community.document_loaders import WikipediaLoader
+from langchain_community.document_loaders import ArxivLoader
+from langchain_community.vectorstores import SupabaseVectorStore,FAISS 
+from langchain_core.messages import SystemMessage, HumanMessage
+from langchain_core.tools import tool
+from langchain.tools.retriever import create_retriever_tool
+#from supabase.client import Client, create_client
+
+# ──────────────────────────────────────────────────────────
+# ENV
+# ──────────────────────────────────────────────────────────
+load_dotenv()
+# API Keys from .env file
+os.environ.setdefault("OPENAI_API_KEY", "<YOUR_OPENAI_KEY>")  # Set your own key or env var
+os.environ["GROQ_API_KEY"] = os.getenv("GROQ_API_KEY", "default_key_or_placeholder")
+os.environ["MISTRAL_API_KEY"] = os.getenv("MISTRAL_API_KEY", "default_key_or_placeholder")
+
+# Tavily API Key
+TAVILY_API_KEY = os.getenv("TAVILY_API_KEY", "default_key_or_placeholder")
+_forbidden = ["nsfw", "porn", "sex", "explicit"]
+_playwright_available = True  # set False to disable Playwright
+
+embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-mpnet-base-v2")  # dim = 768
+
+@tool
+def multiply(a: int, b: int) -> int:
+    """Multiply two numbers.
+
+    Args:
+        a: first int
+        b: second int
+    """
+    return a * b
+
+@tool
+def add(a: int, b: int) -> int:
+    """Add two numbers.
+    
+    Args:
+        a: first int
+        b: second int
+    """
+    return a + b
+
+@tool
+def subtract(a: int, b: int) -> int:
+    """Subtract two numbers.
+    
+    Args:
+        a: first int
+        b: second int
+    """
+    return a - b
+
+@tool
+def divide(a: int, b: int) -> int:
+    """Divide two numbers.
+    
+    Args:
+        a: first int
+        b: second int
+    """
+    if b == 0:
+        raise ValueError("Cannot divide by zero.")
+    return a / b
+
+@tool
+def modulus(a: int, b: int) -> int:
+    """Get the modulus of two numbers.
+    
+    Args:
+        a: first int
+        b: second int
+    """
+    return a % b
+
+@tool
+def wiki_search(query: str) -> str:
+    """Search Wikipedia for a query and return maximum 2 results.
+    
+    Args:
+        query: The search query."""
+    search_docs = WikipediaLoader(query=query, load_max_docs=2).load()
+    formatted_search_docs = "\n\n---\n\n".join(
+        [
+            f'<Document source="{doc.metadata["source"]}" page="{doc.metadata.get("page", "")}"/>\n{doc.page_content}\n</Document>'
+            for doc in search_docs
+        ])
+    return {"wiki_results": formatted_search_docs}
+
+@tool
+def web_search(query: str) -> str:
+    """Search Tavily for a query and return maximum 3 results.
+    
+    Args:
+        query: The search query."""
+    search_docs = TavilySearchResults(max_results=3).invoke(query=query)
+    formatted_search_docs = "\n\n---\n\n".join(
+        [
+            f'<Document source="{doc.metadata["source"]}" page="{doc.metadata.get("page", "")}"/>\n{doc.page_content}\n</Document>'
+            for doc in search_docs
+        ])
+    return {"web_results": formatted_search_docs}
+
+@tool
+def arvix_search(query: str) -> str:
+    """Search Arxiv for a query and return maximum 3 result.
+    
+    Args:
+        query: The search query."""
+    search_docs = ArxivLoader(query=query, load_max_docs=3).load()
+    formatted_search_docs = "\n\n---\n\n".join(
+        [
+            f'<Document source="{doc.metadata["source"]}" page="{doc.metadata.get("page", "")}"/>\n{doc.page_content[:1000]}\n</Document>'
+            for doc in search_docs
+        ])
+    return {"arvix_results": formatted_search_docs}
+
+
+
+# load the system prompt from the file
+with open("system_prompt.txt", "r", encoding="utf-8") as f:
+    system_prompt = f.read()
+
+# System message
+sys_msg = SystemMessage(content=system_prompt)
+
+# build a retriever
+embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-mpnet-base-v2") #  dim=768
+
+INDEX_PATH = "faiss_index"
+if os.path.exists(INDEX_PATH):
+    vector_store = FAISS.load_local(INDEX_PATH, embeddings, allow_dangerous_deserialization=True)
+else:
+    vector_store = FAISS.from_texts(["__init__"], embeddings)
+    vector_store.save_local(INDEX_PATH)
+
+create_retriever_tool = create_retriever_tool(
+    retriever=vector_store.as_retriever(),
+    name="Question Search",
+    description="A tool to retrieve similar questions from a local FAISS vector store."
+)
+
+
+
+tools = [
+    multiply,
+    add,
+    subtract,
+    divide,
+    modulus,
+    wiki_search,
+    web_search,
+    arvix_search,
+]
+
+# Build graph function
+def build_graph(provider: str = "groq"):
+    """Build the graph"""
+    # Load environment variables from .env file
+    if provider == "google":
+        # Google Gemini
+        llm = ChatGoogleGenerativeAI(model="gemini-2.0-flash", temperature=0)
+    elif provider == "groq":
+        # Groq https://console.groq.com/docs/models
+        try:
+            llm = ChatGroq(model="deepseek-r1-distill-llama-70b", temperature=0) # optional : qwen-qwq-32b gemma2-9b-it
+        except Exception as e:
+            print(f"Error initializing Groq: {str(e)}")
+            raise
+    elif provider == "huggingface":
+        # TODO: Add huggingface endpoint
+        llm = ChatHuggingFace(
+            llm=HuggingFaceEndpoint(
+                url="https://api-inference.huggingface.co/models/Meta-DeepLearning/llama-2-7b-chat-hf",
+                temperature=0,
+            ),
+        )
+    else:
+        raise ValueError("Invalid provider. Choose 'google', 'groq' or 'huggingface'.")
+    
+    # Bind tools to LLM
+    llm_with_tools = llm.bind_tools(tools)
+
+    # Node
+    def assistant(state: MessagesState):
+        """Assistant node"""
+        try:
+            if not state["messages"] or not state["messages"][-1].content:
+                raise ValueError("Empty message content")
+            return {"messages": [llm_with_tools.invoke(state["messages"])]}
+        except Exception as e:
+            print(f"Error in assistant node: {str(e)}")
+            raise
+    
+    def retriever(state: MessagesState):
+        """Retriever node"""
+        try:
+            if not state["messages"] or not state["messages"][0].content:
+                raise ValueError("Empty message content")
+            similar_question = vector_store.similarity_search(state["messages"][0].content)
+            example_msg = HumanMessage(
+                content=f"Here I provide a similar question and answer for reference: \n\n{similar_question[0].page_content}",
+            )
+            return {"messages": [sys_msg] + state["messages"] + [example_msg]}
+        except Exception as e:
+            print(f"Error in retriever node: {str(e)}")
+            raise
+
+    builder = StateGraph(MessagesState)
+    builder.add_node("retriever", retriever)
+    builder.add_node("assistant", assistant)
+    builder.add_node("tools", ToolNode(tools))
+    builder.add_edge(START, "retriever")
+    builder.add_edge("retriever", "assistant")
+    builder.add_conditional_edges(
+        "assistant",
+        tools_condition,
+    )
+    builder.add_edge("tools", "assistant")
+
+    # Compile graph
+    return builder.compile()
+
+# test
+if __name__ == "__main__":
+    question = "When was a picture of St. Thomas Aquinas first added to the Wikipedia page on the Principle of double effect?"
+    # Build the graph
+    graph = build_graph(provider="groq")
+    # Run the graph
+    messages = [HumanMessage(content=question)]
+    messages = graph.invoke({"messages": messages})
+    for m in messages["messages"]:
+        m.pretty_print()

utils/all_analysis.txt

@@ -0,0 +1 @@
+{'flow': [{'block_key': 'event_whenflagclicked_1', 'opcode': 'event_whenflagclicked', 'type': 'hat', 'inputs': {}, 'fields': {}}, {'block_key': 'data_setvariableto_1', 'opcode': 'data_setvariableto', 'type': 'stack', 'inputs': {'VALUE': {'kind': 'value', 'value': 0}}, 'fields': {'VARIABLE': ['score', None]}}, {'block_key': 'control_forever_1', 'opcode': 'control_forever', 'type': 'c_block', 'inputs': {'SUBSTACK': [{'block_key': 'control_if_1', 'opcode': 'control_if', 'type': 'c_block', 'inputs': {'CONDITION': [{'block_key': 'sensing_touchingobject_1', 'opcode': 'sensing_touchingobject', 'type': 'boolean', 'inputs': {'TOUCHINGOBJECTMENU': [1, 'sensing_touchingobjectmenu_1']}, 'fields': {}}], 'SUBSTACK': [{'block_key': 'data_changevariableby_1', 'opcode': 'data_changevariableby', 'type': 'stack', 'inputs': {'VALUE': {'kind': 'value', 'value': -1}}, 'fields': {'VARIABLE': ['score', None]}}, {'block_key': 'control_wait_1', 'opcode': 'control_wait', 'type': 'stack', 'inputs': {'DURATION': {'kind': 'value', 'value': 0.1}}, 'fields': {}}]}, 'fields': {}}]}, 'fields': {}}]}     

utils/all_generated_blocks.json

@@ -0,0 +1,189 @@
+{
+  "event_whenflagclicked_1": {
+    "block_name": "when green flag pressed",
+    "block_type": "Events",
+    "op_code": "event_whenflagclicked",
+    "block_shape": "Hat Block",
+    "functionality": "This Hat block initiates the script when the green flag is clicked, serving as the common starting point for most Scratch projects.",
+    "inputs": {},
+    "fields": {},
+    "shadow": false,
+    "topLevel": true,
+    "id": "event_whenflagclicked_1",
+    "next": "data_setvariableto_1",
+    "parent": null
+  },
+  "data_setvariableto_1": {
+    "block_name": "set [my variable v] to ()",
+    "block_type": "Data",
+    "block_shape": "Stack Block",
+    "op_code": "data_setvariableto",
+    "functionality": "Assigns a specific value (number, string, or boolean) to a variable.",
+    "inputs": {
+      "VALUE": {
+        "kind": "value",
+        "value": 0
+      }
+    },
+    "fields": {
+      "VARIABLE": [
+        "score",
+        null
+      ]
+    },
+    "shadow": false,
+    "topLevel": false,
+    "id": "data_setvariableto_1",
+    "next": "control_forever_1",
+    "parent": "event_whenflagclicked_1"
+  },
+  "data_setvariableto_2": {
+    "block_name": "set [my variable v] to ()",
+    "block_type": "Data",
+    "block_shape": "Stack Block",
+    "op_code": "data_setvariableto",
+    "functionality": "Assigns a specific value (number, string, or boolean) to a variable.",
+    "inputs": {
+      "VALUE": [
+        1,
+        [
+          10,
+          "0"
+        ]
+      ]
+    },
+    "fields": {
+      "VARIABLE": [
+        "my variable",
+        "`jEk@4|i[#Fk?(8x)AV.-my variable"
+      ]
+    },
+    "shadow": false,
+    "topLevel": false,
+    "parent": null,
+    "next": null
+  },
+  "control_forever_1": {
+    "block_name": "forever",
+    "block_type": "Control",
+    "block_shape": "C-Block",
+    "op_code": "control_forever",
+    "functionality": "Continuously runs the blocks inside it.",
+    "inputs": {
+      "SUBSTACK": [
+        2,
+        "control_if_1"
+      ]
+    },
+    "fields": {},
+    "shadow": false,
+    "topLevel": false,
+    "id": "control_forever_1",
+    "next": null,
+    "parent": "event_whenflagclicked_1"
+  },
+  "control_if_1": {
+    "block_name": "if <> then",
+    "block_type": "Control",
+    "block_shape": "C-Block",
+    "op_code": "control_if",
+    "functionality": "Executes the blocks inside it only if the specified boolean condition is true. [NOTE: it takes boolean blocks as input]",
+    "inputs": {
+      "CONDITION": {
+        "kind": "block",
+        "block": "sensing_touchingobject_1"
+      },
+      "SUBSTACK": [
+        2,
+        "data_changevariableby_1"
+      ]
+    },
+    "fields": {},
+    "shadow": false,
+    "topLevel": false,
+    "id": "control_if_1",
+    "next": null,
+    "parent": "control_forever_1"
+  },
+  "control_wait_1": {
+    "block_name": "wait () seconds",
+    "block_type": "Control",
+    "block_shape": "Stack Block",
+    "op_code": "control_wait",
+    "functionality": "Pauses the script for a specified duration.",
+    "inputs": {
+      "DURATION": {
+        "kind": "value",
+        "value": 0.1
+      }
+    },
+    "fields": {},
+    "shadow": false,
+    "topLevel": false,
+    "id": "control_wait_1",
+    "next": null,
+    "parent": "control_if_1"
+  },
+  "sensing_touchingobject_1": {
+    "block_name": "<touching [edge v]?>",
+    "block_type": "Sensing",
+    "op_code": "sensing_touchingobject",
+    "block_shape": "Boolean Block",
+    "functionality": "Checks if its sprite is touching the mouse-pointer, edge, or another specified sprite.",
+    "inputs": {
+      "TOUCHINGOBJECTMENU": [
+        1,
+        "sensing_touchingobjectmenu_1"
+      ]
+    },
+    "fields": {},
+    "shadow": false,
+    "topLevel": false,
+    "id": "sensing_touchingobject_1",
+    "parent": "control_if_1",
+    "next": null
+  },
+  "sensing_touchingobjectmenu_1": {
+    "block_name": "touching object menu",
+    "block_type": "Sensing",
+    "block_shape": "Reporter Block",
+    "op_code": "sensing_touchingobjectmenu",
+    "functionality": "Menu for touching object block.",
+    "inputs": {},
+    "fields": {
+      "TOUCHINGOBJECTMENU": [
+        "other sprite",
+        null
+      ]
+    },
+    "shadow": true,
+    "topLevel": false,
+    "id": "sensing_touchingobjectmenu_1",
+    "parent": "sensing_touchingobject_1",
+    "next": null
+  },
+  "data_changevariableby_1": {
+    "block_name": "change [my variable v] by ()",
+    "block_type": "Data",
+    "block_shape": "Stack Block",
+    "op_code": "data_changevariableby",
+    "functionality": "Increases or decreases a variable's numerical value by a specified amount.",
+    "inputs": {
+      "VALUE": {
+        "kind": "value",
+        "value": -1
+      }
+    },
+    "fields": {
+      "VARIABLE": [
+        "score",
+        null
+      ]
+    },
+    "shadow": false,
+    "topLevel": false,
+    "id": "data_changevariableby_1",
+    "next": "control_wait_1",
+    "parent": "control_if_1"
+  }
+}

utils/block_correcter.py

@@ -0,0 +1,410 @@
+import json
+
+def update_and_clean_blocks(all_generated_blocks, generated_output_blocks):
+    """
+    Updates the generated_output_blocks with values from all_generated_blocks
+    and removes specified keys from the updated blocks.
+
+    Args:
+        all_generated_blocks (dict): The dictionary containing all generated block data.
+        generated_output_blocks (dict): The dictionary to be updated and cleaned.
+
+    Returns:
+        dict: The updated and cleaned dictionary.
+    """
+    keys_to_remove = ["functionality", "block_shape", "id", "block_name", "block_type"]
+
+    updated_blocks = {}
+    for block_id, generated_block_data in generated_output_blocks.items():
+        if block_id in all_generated_blocks:
+            all_block_data = all_generated_blocks[block_id]
+
+            # Create a new dictionary for the updated block, including only desired fields
+            current_updated_block = {}
+            for key, value in generated_block_data.items():
+                if key not in keys_to_remove:
+                    current_updated_block[key] = value
+
+            # Update specific values from all_generated_blocks if they exist
+            # and are not among the keys to be removed
+            if "next" in all_block_data and "next" not in keys_to_remove:
+                current_updated_block["next"] = all_block_data["next"]
+            if "parent" in all_block_data and "parent" not in keys_to_remove:
+                current_updated_block["parent"] = all_block_data["parent"]
+            if "topLevel" in all_block_data and "topLevel" not in keys_to_remove:
+                current_updated_block["topLevel"] = all_block_data["topLevel"]
+
+
+            updated_blocks[block_id] = current_updated_block
+        else:
+            # If a block_id from generated_output_blocks is not in all_generated_blocks,
+            # just clean it
+            current_updated_block = {}
+            for key, value in generated_block_data.items():
+                if key not in keys_to_remove:
+                    current_updated_block[key] = value
+            updated_blocks[block_id] = current_updated_block
+
+    return updated_blocks
+
+# Load the provided JSON data
+all_generated_blocks = {
+  "event_whenflagclicked_1": {
+    "block_name": "when green flag pressed",
+    "block_type": "Events",
+    "op_code": "event_whenflagclicked",
+    "block_shape": "Hat Block",
+    "functionality": "This Hat block initiates the script when the green flag is clicked, serving as the common starting point for most Scratch projects.",
+    "inputs": {},
+    "fields": {},
+    "shadow": False,
+    "topLevel": True,
+    "id": "event_whenflagclicked_1",
+    "next": "data_setvariableto_1",
+    "parent": None
+  },
+  "data_setvariableto_1": {
+    "block_name": "set [my variable v] to ()",
+    "block_type": "Data",
+    "block_shape": "Stack Block",
+    "op_code": "data_setvariableto",
+    "functionality": "Assigns a specific value (number, string, or boolean) to a variable.",
+    "inputs": {
+      "VALUE": {
+        "kind": "value",
+        "value": 0
+      }
+    },
+    "fields": {
+      "VARIABLE": [
+        "score",
+        None
+      ]
+    },
+    "shadow": False,
+    "topLevel": False,
+    "id": "data_setvariableto_1",
+    "next": "control_forever_1",
+    "parent": "event_whenflagclicked_1"
+  },
+  "data_setvariableto_2": {
+    "block_name": "set [my variable v] to ()",
+    "block_type": "Data",
+    "block_shape": "Stack Block",
+    "op_code": "data_setvariableto",
+    "functionality": "Assigns a specific value (number, string, or boolean) to a variable.",
+    "inputs": {
+      "VALUE": [
+        1,
+        [
+          10,
+          "0"
+        ]
+      ]
+    },
+    "fields": {
+      "VARIABLE": [
+        "my variable",
+        "`jEk@4|i[#Fk?(8x)AV.-my variable"
+      ]
+    },
+    "shadow": False,
+    "topLevel": False,
+    "parent": None,
+    "next": None
+  },
+  "control_forever_1": {
+    "block_name": "forever",
+    "block_type": "Control",
+    "block_shape": "C-Block",
+    "op_code": "control_forever",
+    "functionality": "Continuously runs the blocks inside it.",
+    "inputs": {
+      "SUBSTACK": [
+        2,
+        "control_if_1"
+      ]
+    },
+    "fields": {},
+    "shadow": False,
+    "topLevel": False,
+    "id": "control_forever_1",
+    "next": None,
+    "parent": "event_whenflagclicked_1"
+  },
+  "control_if_1": {
+    "block_name": "if <> then",
+    "block_type": "Control",
+    "block_shape": "C-Block",
+    "op_code": "control_if",
+    "functionality": "Executes the blocks inside it only if the specified boolean condition is true. [NOTE: it takes boolean blocks as input]",
+    "inputs": {
+      "CONDITION": {
+        "kind": "block",
+        "block": "sensing_touchingobject_1"
+      },
+      "SUBSTACK": [
+        2,
+        "data_changevariableby_1"
+      ]
+    },
+    "fields": {},
+    "shadow": False,
+    "topLevel": False,
+    "id": "control_if_1",
+    "next": None,
+    "parent": "control_forever_1"
+  },
+  "control_wait_1": {
+    "block_name": "wait () seconds",
+    "block_type": "Control",
+    "block_shape": "Stack Block",
+    "op_code": "control_wait",
+    "functionality": "Pauses the script for a specified duration.",
+    "inputs": {
+      "DURATION": {
+        "kind": "value",
+        "value": 0.1
+      }
+    },
+    "fields": {},
+    "shadow": False,
+    "topLevel": False,
+    "id": "control_wait_1",
+    "next": None,
+    "parent": "control_if_1"
+  },
+  "sensing_touchingobject_1": {
+    "block_name": "<touching [edge v]?>",
+    "block_type": "Sensing",
+    "op_code": "sensing_touchingobject",
+    "block_shape": "Boolean Block",
+    "functionality": "Checks if its sprite is touching the mouse-pointer, edge, or another specified sprite.",
+    "inputs": {
+      "TOUCHINGOBJECTMENU": [
+        1,
+        "sensing_touchingobjectmenu_1"
+      ]
+    },
+    "fields": {},
+    "shadow": False,
+    "topLevel": False,
+    "id": "sensing_touchingobject_1",
+    "parent": "control_if_1",
+    "next": None
+  },
+  "sensing_touchingobjectmenu_1": {
+    "block_name": "touching object menu",
+    "block_type": "Sensing",
+    "block_shape": "Reporter Block",
+    "op_code": "sensing_touchingobjectmenu",
+    "functionality": "Menu for touching object block.",
+    "inputs": {},
+    "fields": {
+      "TOUCHINGOBJECTMENU": [
+        "other sprite",
+        None
+      ]
+    },
+    "shadow": True,
+    "topLevel": False,
+    "id": "sensing_touchingobjectmenu_1",
+    "parent": "sensing_touchingobject_1",
+    "next": None
+  },
+  "data_changevariableby_1": {
+    "block_name": "change [my variable v] by ()",
+    "block_type": "Data",
+    "block_shape": "Stack Block",
+    "op_code": "data_changevariableby",
+    "functionality": "Increases or decreases a variable's numerical value by a specified amount.",
+    "inputs": {
+      "VALUE": {
+        "kind": "value",
+        "value": -1
+      }
+    },
+    "fields": {
+      "VARIABLE": [
+        "score",
+        None
+      ]
+    },
+    "shadow": False,
+    "topLevel": False,
+    "id": "data_changevariableby_1",
+    "next": "control_wait_1",
+    "parent": "control_if_1"
+  }
+}
+
+generated_output_blocks = {
+  "event_whenflagclicked_1": {
+    "block_name": "when green flag pressed",
+    "block_type": "Events",
+    "op_code": "event_whenflagclicked",
+    "block_shape": "Hat Block",
+    "functionality": "This Hat block initiates the script when the green flag is clicked, serving as the common starting point for most Scratch projects.",
+    "inputs": {},
+    "fields": {},
+    "shadow": False,
+    "topLevel": True,
+    "parent": None,
+    "next": None
+  },
+  "data_setvariableto_1": {
+    "block_name": "set [my variable v] to ()",
+    "block_type": "Data",
+    "block_shape": "Stack Block",
+    "op_code": "data_setvariableto",
+    "functionality": "Assigns a specific value (number, string, or boolean) to a variable.",
+    "inputs": {
+      "VALUE": [
+        1,
+        [
+          10,
+          "0"
+        ]
+      ]
+    },
+    "fields": {
+      "VARIABLE": [
+        "my variable",
+        "`jEk@4|i[#Fk?(8x)AV.-my variable"
+      ]
+    },
+    "shadow": False,
+    "topLevel": True,
+    "parent": None,
+    "next": None
+  },
+  "data_setvariableto_2": {
+    "block_name": "set [my variable v] to ()",
+    "block_type": "Data",
+    "block_shape": "Stack Block",
+    "op_code": "data_setvariableto",
+    "functionality": "Assigns a specific value (number, string, or boolean) to a variable.",
+    "inputs": {
+      "VALUE": [
+        1,
+        [
+          10,
+          "0"
+        ]
+      ]
+    },
+    "fields": {
+      "VARIABLE": [
+        "my variable",
+        "`jEk@4|i[#Fk?(8x)AV.-my variable"
+      ]
+    },
+    "shadow": False,
+    "topLevel": True,
+    "parent": None,
+    "next": None
+  },
+  "control_forever_1": {
+    "block_name": "forever",
+    "block_type": "Control",
+    "block_shape": "C-Block",
+    "op_code": "control_forever",
+    "functionality": "Continuously runs the blocks inside it.",
+    "inputs": {
+      "SUBSTACK": [
+        2,
+        None
+      ]
+    },
+    "fields": {},
+    "shadow": False,
+    "topLevel": True,
+    "parent": None,
+    "next": None
+  },
+  "control_if_1": {
+    "block_name": "if <> then",
+    "block_type": "Control",
+    "block_shape": "C-Block",
+    "op_code": "control_if",
+    "functionality": "Executes the blocks inside it only if the specified boolean condition is true. [NOTE: it takes boolean blocks as input]",
+    "inputs": {
+      "CONDITION": [
+        2,
+        None
+      ],
+      "SUBSTACK": [
+        2,
+        None
+      ]
+    },
+    "fields": {},
+    "shadow": False,
+    "topLevel": True,
+    "parent": None,
+    "next": None
+  },
+  "control_wait_1": {
+    "block_name": "wait () seconds",
+    "block_type": "Control",
+    "block_shape": "Stack Block",
+    "op_code": "control_wait",
+    "functionality": "Pauses the script for a specified duration.",
+    "inputs": {
+      "DURATION": [
+        1,
+        [
+          5,
+          "1"
+        ]
+      ]
+    },
+    "fields": {},
+    "shadow": False,
+    "topLevel": True,
+    "parent": None,
+    "next": None
+  },
+  "sensing_touchingobject_1": {
+    "block_name": "<touching [edge v]?>",
+    "block_type": "Sensing",
+    "op_code": "sensing_touchingobject",
+    "block_shape": "Boolean Block",
+    "functionality": "Checks if its sprite is touching the mouse-pointer, edge, or another specified sprite.",
+    "inputs": {
+      "TOUCHINGOBJECTMENU": [
+        1,
+        "sensing_touchingobjectmenu_1"
+      ]
+    },
+    "fields": {},
+    "shadow": False,
+    "topLevel": True,
+    "parent": None,
+    "next": None
+  },
+  "sensing_touchingobjectmenu_1": {
+    "block_name": "touching object menu",
+    "block_type": "Sensing",
+    "block_shape": "Reporter Block",
+    "op_code": "sensing_touchingobjectmenu",
+    "functionality": "Menu for touching object block.",
+    "inputs": {},
+    "fields": {
+      "TOUCHINGOBJECTMENU": [
+        "_mouse_",
+        None
+      ]
+    },
+    "shadow": True,
+    "topLevel": False,
+    "next": None,
+    "parent": "sensing_touchingobject_1"
+  }
+}
+
+# Process the blocks
+processed_blocks = update_and_clean_blocks(all_generated_blocks, generated_output_blocks)
+
+# Print the processed blocks in a readable JSON format
+print(json.dumps(processed_blocks, indent=2))

utils/block_function.py

@@ -0,0 +1,1147 @@
+import json
+import copy
+import re
+
+def generate_blocks_from_opcodes(opcode_counts, all_block_definitions):
+    """
+    Generates a dictionary of Scratch-like blocks based on a list of opcodes and a reference block definition.
+    It now correctly links parent and menu blocks using their generated unique keys, and handles various block categories.
+    It ensures that menu blocks are only generated as children of their respective parent blocks.
+
+    Args:
+        opcode_counts (list): An array of objects, each with an 'opcode' and 'count' property.
+                              Example: [{"opcode": "motion_gotoxy", "count": 1}]
+        all_block_definitions (dict): A comprehensive dictionary containing definitions for all block types.
+
+    Returns:
+        tuple: A tuple containing:
+            - dict: A JSON object where keys are generated block IDs and values are the block definitions.
+            - dict: The opcode_occurrences dictionary for consistent unique key generation across functions.
+    """
+    generated_blocks = {}
+    opcode_occurrences = {}  # To keep track of how many times each opcode (main or menu) has been used for unique keys
+
+    # Define explicit parent-menu relationships for linking purposes
+    # This maps main_opcode -> list of (input_field_name, menu_opcode)
+    explicit_menu_links = {
+        "motion_goto": [("TO", "motion_goto_menu")],
+        "motion_glideto": [("TO", "motion_glideto_menu")],
+        "motion_pointtowards": [("TOWARDS", "motion_pointtowards_menu")],
+        "sensing_keypressed": [("KEY_OPTION", "sensing_keyoptions")],
+        "sensing_of": [("OBJECT", "sensing_of_object_menu")],
+        "sensing_touchingobject": [("TOUCHINGOBJECTMENU", "sensing_touchingobjectmenu")],
+        "control_create_clone_of": [("CLONE_OPTION", "control_create_clone_of_menu")],
+        "sound_play": [("SOUND_MENU", "sound_sounds_menu")],
+        "sound_playuntildone": [("SOUND_MENU", "sound_sounds_menu")],
+        "looks_switchcostumeto": [("COSTUME", "looks_costume")],
+        "looks_switchbackdropto": [("BACKDROP", "looks_backdrops")],
+    }
+
+    # --- Step 1: Process explicitly requested opcodes and generate their instances and associated menus ---
+    for item in opcode_counts:
+        opcode = item.get("opcode")
+        count = item.get("count", 1)
+
+        if not opcode:
+            print("Warning: Skipping item with missing 'opcode'.")
+            continue
+
+        if opcode not in all_block_definitions:
+            print(f"Warning: Opcode '{opcode}' not found in all_block_definitions. Skipping.")
+            continue
+
+        for _ in range(count):
+            # Increment occurrence count for the current main opcode
+            opcode_occurrences[opcode] = opcode_occurrences.get(opcode, 0) + 1
+            main_block_instance_num = opcode_occurrences[opcode]
+            
+            main_block_unique_key = f"{opcode}_{main_block_instance_num}"
+            
+            # Create a deep copy of the main block definition
+            main_block_data = copy.deepcopy(all_block_definitions[opcode])
+            
+            # Set properties for a top-level main block
+            main_block_data["parent"] = None
+            main_block_data["next"] = None
+            main_block_data["topLevel"] = True
+            main_block_data["shadow"] = False # Main blocks are typically not shadows
+
+            generated_blocks[main_block_unique_key] = main_block_data
+
+            # If this main block has associated menus, generate and link them now
+            if opcode in explicit_menu_links:
+                for input_field_name, menu_opcode_type in explicit_menu_links[opcode]:
+                    if menu_opcode_type in all_block_definitions:
+                        # Increment the occurrence for the menu block type
+                        opcode_occurrences[menu_opcode_type] = opcode_occurrences.get(menu_opcode_type, 0) + 1
+                        menu_block_instance_num = opcode_occurrences[menu_opcode_type]
+
+                        menu_block_data = copy.deepcopy(all_block_definitions[menu_opcode_type])
+                        
+                        # Generate a unique key for this specific menu instance
+                        menu_unique_key = f"{menu_opcode_type}_{menu_block_instance_num}"
+                        
+                        # Set properties for a shadow menu block
+                        menu_block_data["shadow"] = True
+                        menu_block_data["topLevel"] = False
+                        menu_block_data["next"] = None
+                        menu_block_data["parent"] = main_block_unique_key # Link menu to its parent instance
+
+                        # Update the main block's input to point to this unique menu instance
+                        if input_field_name in main_block_data.get("inputs", {}) and \
+                           isinstance(main_block_data["inputs"][input_field_name], list) and \
+                           len(main_block_data["inputs"][input_field_name]) > 1 and \
+                           main_block_data["inputs"][input_field_name][0] == 1:
+                            
+                            main_block_data["inputs"][input_field_name][1] = menu_unique_key
+                        
+                        generated_blocks[menu_unique_key] = menu_block_data
+            
+    return generated_blocks, opcode_occurrences
+
+def interpret_pseudo_code_and_update_blocks(generated_blocks_json, pseudo_code, all_block_definitions, opcode_occurrences):
+    """
+    Interprets pseudo-code to update the generated Scratch blocks, replacing static values
+    with dynamic values and establishing stacking/nesting logic.
+
+    Args:
+        generated_blocks_json (dict): The JSON object of pre-generated blocks.
+        pseudo_code (str): The pseudo-code string to interpret.
+        all_block_definitions (dict): A comprehensive dictionary containing definitions for all block types.
+        opcode_occurrences (dict): A dictionary to keep track of opcode occurrences for unique key generation.
+
+    Returns:
+        dict: The updated JSON object of Scratch blocks.
+    """
+    updated_blocks = copy.deepcopy(generated_blocks_json)
+    
+    # Helper to find a block by opcode and optionally by a unique part of its key
+    def find_block_by_opcode(opcode_to_find, instance_num=None, parent_key=None):
+        for key, block in updated_blocks.items():
+            if block["opcode"] == opcode_to_find:
+                if instance_num is not None:
+                    # Check if the key ends with the instance number
+                    if key.endswith(f"_{instance_num}"):
+                        return key, block
+                elif parent_key is not None:
+                    # For menu blocks, check if their parent matches
+                    if block.get("shadow") and block.get("parent") == parent_key:
+                        return key, block
+                else:
+                    # Return the first one found if no specific instance is needed
+                    return key, block
+        return None, None
+
+    # Helper to get a unique key for a new block if needed
+    def get_unique_key(opcode_prefix):
+        count = 1
+        while f"{opcode_prefix}_{count}" in updated_blocks:
+            count += 1
+        return f"{opcode_prefix}_{count}"
+
+    lines = [line.strip() for line in pseudo_code.strip().split('\n') if line.strip()]
+
+    # Track the current script and nesting
+    current_script_head = None
+    current_parent_stack = [] # Stores (parent_block_key, indent_level, last_child_key)
+    indent_level = 0
+
+    # Create a mapping from block name patterns to their opcodes and input details
+    # Prioritize more specific patterns first
+    pseudo_code_to_opcode_map = {
+        re.compile(r"when green flag clicked"): {"opcode": "event_whenflagclicked"},
+        re.compile(r"go to x: \((.+?)\) y: \((.+?)\)"): {"opcode": "motion_gotoxy", "input_names": ["X", "Y"]},
+        re.compile(r"set \[(.+?) v\] to (.+)"): {"opcode": "data_setvariableto", "field_name": "VARIABLE", "input_name": "VALUE"},
+        re.compile(r"change \[(.+?) v\] by \((.+)\)"): {"opcode": "data_changevariableby", "field_name": "VARIABLE", "input_name": "VALUE"},
+        re.compile(r"show variable \[(.+?) v\]"): {"opcode": "data_showvariable", "field_name": "VARIABLE"},
+        re.compile(r"hide variable \[(.+?) v\]"): {"opcode": "data_hidevariable", "field_name": "VARIABLE"},
+        re.compile(r"forever"): {"opcode": "control_forever"},
+        re.compile(r"glide \((.+?)\) seconds to x: \((.+?)\) y: \((.+?)\)"): {"opcode": "motion_glidesecstoxy", "input_names": ["SECS", "X", "Y"]},
+        re.compile(r"if <\((.+)\) < \((.+)\)> then"): {"opcode": "control_if", "input_names": ["OPERAND1", "OPERAND2"], "condition_opcode": "operator_lt"},
+        re.compile(r"if <touching \[(.+?) v\]\?> then"): {"opcode": "control_if", "input_name": "TOUCHINGOBJECTMENU", "condition_opcode": "sensing_touchingobject"},
+        re.compile(r"set x to \((.+?)\)"): {"opcode": "motion_setx", "input_name": "X"},
+        re.compile(r"broadcast \[(.+?) v\]"): {"opcode": "event_broadcast", "input_name": "BROADCAST_INPUT"},
+        re.compile(r"stop \[(.+?) v\]"): {"opcode": "control_stop", "field_name": "STOP_OPTION"},
+        re.compile(r"end"): {"opcode": "end_block"}, # Special marker for script end/C-block end
+    }
+
+    # Create a reverse lookup for reporter block opcodes based on their pseudo-code representation
+    reporter_opcode_lookup = {}
+    for opcode, definition in all_block_definitions.items():
+        if definition.get("block_shape") == "Reporter Block":
+            block_name = definition.get("block_name")
+            if block_name:
+                # Remove parentheses for matching
+                clean_name = block_name.replace("(", "").replace(")", "").strip()
+                reporter_opcode_lookup[clean_name] = opcode
+                # Handle cases like "x position" vs "(x position)"
+                if clean_name not in reporter_opcode_lookup:
+                    reporter_opcode_lookup[clean_name] = opcode
+
+    # Function to create a new block instance
+    def create_block_instance(opcode, opcode_occurrences, parent_key=None, is_shadow=False, is_top_level=False):
+        # Ensure unique key generation is consistent
+        opcode_occurrences[opcode] = opcode_occurrences.get(opcode, 0) + 1
+        unique_key = f"{opcode}_{opcode_occurrences[opcode]}"
+        
+        new_block = copy.deepcopy(all_block_definitions.get(opcode, {}))
+        if not new_block:
+            print(f"Error: Definition for opcode '{opcode}' not found.")
+            return None, None
+
+        new_block["parent"] = parent_key
+        new_block["next"] = None # Will be set by stacking logic
+        new_block["topLevel"] = is_top_level
+        new_block["shadow"] = is_shadow
+
+        # Clear inputs/fields to be populated by pseudo-code parsing
+        if "inputs" in new_block:
+            new_block["inputs"] = {k: copy.deepcopy(v) for k, v in new_block["inputs"].items()} # Deep copy inputs
+            for input_name in new_block["inputs"]:
+                if isinstance(new_block["inputs"][input_name], list) and len(new_block["inputs"][input_name]) > 1:
+                    # Reset input value, keep type 1 for block reference or type 4/10 for literal
+                    if new_block["inputs"][input_name][0] == 1:
+                        new_block["inputs"][input_name][1] = None # Placeholder for linked block ID
+                    else:
+                        new_block["inputs"][input_name][1] = ["", ""] # Default empty value
+        if "fields" in new_block:
+            new_block["fields"] = {k: copy.deepcopy(v) for k, v in new_block["fields"].items()} # Deep copy fields
+            for field_name in new_block["fields"]:
+                if isinstance(new_block["fields"][field_name], list) and len(new_block["fields"][field_name]) > 0:
+                    new_block["fields"][field_name][0] = "" # Reset field value
+
+        updated_blocks[unique_key] = new_block
+        return unique_key, new_block
+
+    # Helper to parse input values
+    def parse_input_value(value_str):
+        value_str = value_str.strip()
+        # Handle numeric values (including those with + or - prefix)
+        if re.fullmatch(r"[-+]?\d+(\.\d+)?", value_str):
+            return [4, value_str] # Type 4 for number
+        # Handle string literals (e.g., "Hello!")
+        if value_str.startswith('"') and value_str.endswith('"'):
+            return [10, value_str.strip('"')] # Type 10 for string
+        # Handle variable/list names (e.g., [score v], [my list v])
+        if value_str.startswith('[') and value_str.endswith(']'):
+            var_name = value_str[1:-1].replace(' v', '').strip()
+            # For inputs that expect a variable, we might need a data_variable block
+            # For now, if it's a variable reference in an input, we'll return its name.
+            # The calling context (e.g., set variable's field vs. an input) will determine type.
+            return [12, var_name] # Custom type 12 for variable name, to be resolved later
+
+        # Handle nested reporter blocks (e.g., (x position))
+        if value_str.startswith('(') and value_str.endswith(')'):
+            inner_content = value_str[1:-1].strip()
+            # Check if it's a known reporter block
+            if inner_content in reporter_opcode_lookup:
+                return [3, reporter_opcode_lookup[inner_content]] # Type 3 for reporter block reference
+            # If not a known reporter, treat as a number or string
+            if re.fullmatch(r"[-+]?\d+(\.\d+)?", inner_content):
+                return [4, inner_content]
+            return [10, inner_content] # Default to string if not found in reporters
+        
+        # Handle boolean conditions (e.g., <(x position) < (-235)>) - these are usually handled by parent regex
+        if value_str.startswith('<') and value_str.endswith('>'):
+            inner_condition = value_str[1:-1].strip()
+            # This is typically handled by the regex that matched the 'if' block itself.
+            # If this is called for a standalone boolean, it would be a reporter.
+            for op, def_ in all_block_definitions.items():
+                if def_.get("block_shape") == "Boolean Block" and def_.get("block_name") and \
+                   def_["block_name"].replace("<", "").replace(">", "").strip() == inner_condition:
+                    return [2, op] # Type 2 for boolean block reference
+            return [10, inner_condition] # Default to string if not found
+        
+        return [10, value_str] # Default to string literal
+
+
+    # Main parsing loop
+    block_stack = [] # (block_key, indent_level, last_child_key_in_scope) for tracking nesting
+
+    for line_idx, raw_line in enumerate(lines):
+        current_line_indent = len(raw_line) - len(raw_line.lstrip())
+        line = raw_line.strip()
+
+        # Adjust block_stack based on current indent level
+        while block_stack and current_line_indent <= block_stack[-1][1]:
+            block_stack.pop()
+
+        matched_block_info = None
+        matched_values = None
+        
+        # Try to match the line against known block patterns
+        for pattern_regex, info in pseudo_code_to_opcode_map.items():
+            match = pattern_regex.match(line)
+            if match:
+                matched_block_info = info
+                matched_values = match.groups()
+                break
+        
+        if not matched_block_info:
+            print(f"Warning: Could not interpret line: '{line}'")
+            continue
+
+        opcode = matched_block_info["opcode"]
+
+        # Handle 'end' block separately as it signifies closing a C-block
+        if opcode == "end_block":
+            if block_stack:
+                block_stack.pop() # Pop the C-block parent
+            continue
+
+        parent_key = None
+        if block_stack:
+            parent_key = block_stack[-1][0] # The last block on the stack is the parent
+
+        # Create the new block instance
+        new_block_key, new_block_data = create_block_instance(
+            opcode, 
+            opcode_occurrences, 
+            parent_key=parent_key, 
+            is_top_level=(parent_key is None)
+        )
+        if not new_block_key:
+            continue
+
+        # Link to previous block in the same script/nesting level
+        if block_stack:
+            # Update the 'next' of the previous block in the current scope
+            last_child_key_in_scope = block_stack[-1][2] if len(block_stack[-1]) > 2 else None
+            if last_child_key_in_scope and last_child_key_in_scope in updated_blocks:
+                updated_blocks[last_child_key_in_scope]["next"] = new_block_key
+            
+            # Update the last child in the current scope
+            block_stack[-1] = (block_stack[-1][0], block_stack[-1][1], new_block_key)
+        
+        # Populate inputs and fields
+        if matched_values:
+            # Handle specific block types with their inputs/fields
+            if opcode == "motion_gotoxy":
+                x_val = parse_input_value(matched_values[0])
+                y_val = parse_input_value(matched_values[1])
+                new_block_data["inputs"]["X"][1] = x_val[1]
+                new_block_data["inputs"]["Y"][1] = y_val[1]
+                new_block_data["inputs"]["X"][0] = x_val[0]
+                new_block_data["inputs"]["Y"][0] = y_val[0]
+            elif opcode == "data_setvariableto":
+                var_name = matched_values[0].replace(' v', '').strip()
+                value_parsed = parse_input_value(matched_values[1])
+                new_block_data["fields"]["VARIABLE"][0] = var_name
+                # Assuming variable ID is generated elsewhere or can be looked up
+                new_block_data["fields"]["VARIABLE"][1] = f"`var_{var_name}" # Placeholder for variable ID
+                new_block_data["inputs"]["VALUE"][0] = value_parsed[0]
+                new_block_data["inputs"]["VALUE"][1] = value_parsed[1]
+            elif opcode == "data_showvariable":
+                var_name = matched_values[0].replace(' v', '').strip()
+                new_block_data["fields"]["VARIABLE"][0] = var_name
+                new_block_data["fields"]["VARIABLE"][1] = f"`var_{var_name}" # Placeholder for variable ID
+            elif opcode == "motion_glidesecstoxy":
+                secs_val = parse_input_value(matched_values[0])
+                x_val = parse_input_value(matched_values[1])
+                y_val = parse_input_value(matched_values[2])
+                new_block_data["inputs"]["SECS"][1] = secs_val[1]
+                new_block_data["inputs"]["X"][1] = x_val[1]
+                new_block_data["inputs"]["Y"][1] = y_val[1]
+                new_block_data["inputs"]["SECS"][0] = secs_val[0]
+                new_block_data["inputs"]["X"][0] = x_val[0]
+                new_block_data["inputs"]["Y"][0] = y_val[0]
+            elif opcode == "motion_setx":
+                x_val = parse_input_value(matched_values[0])
+                new_block_data["inputs"]["X"][1] = x_val[1]
+                new_block_data["inputs"]["X"][0] = x_val[0]
+            elif opcode == "control_if":
+                condition_opcode = matched_block_info["condition_opcode"]
+                
+                if condition_opcode == "operator_lt":
+                    op1_str = matched_values[0].strip()
+                    op2_str = matched_values[1].strip()
+
+                    op1_parsed = parse_input_value(op1_str)
+                    op2_parsed = parse_input_value(op2_str)
+
+                    # Create operator_lt block as a shadow input for the IF condition
+                    lt_block_key, lt_block_data = create_block_instance(
+                        "operator_lt", 
+                        opcode_occurrences, 
+                        parent_key=new_block_key, 
+                        is_shadow=True, 
+                        is_top_level=False
+                    )
+                    if lt_block_key:
+                        new_block_data["inputs"]["CONDITION"][1] = lt_block_key
+                        new_block_data["inputs"]["CONDITION"][0] = 2 # Type 2 for boolean block reference
+
+                        # Populate operator_lt inputs
+                        if op1_parsed[0] == 3: # If it's a reporter block
+                            op1_reporter_key, op1_reporter_data = create_block_instance(
+                                op1_parsed[1], # Opcode of the reporter
+                                opcode_occurrences, 
+                                parent_key=lt_block_key, 
+                                is_shadow=True, 
+                                is_top_level=False
+                            )
+                            if op1_reporter_key:
+                                lt_block_data["inputs"]["OPERAND1"][1] = op1_reporter_key
+                                lt_block_data["inputs"]["OPERAND1"][0] = 3
+                        else: # Literal value
+                            lt_block_data["inputs"]["OPERAND1"][1] = op1_parsed[1]
+                            lt_block_data["inputs"]["OPERAND1"][0] = op1_parsed[0]
+                        
+                        lt_block_data["inputs"]["OPERAND2"][1] = op2_parsed[1]
+                        lt_block_data["inputs"]["OPERAND2"][0] = op2_parsed[0]
+
+                elif condition_opcode == "sensing_touchingobject":
+                    sprite_name = matched_values[0].replace(' v', '').strip()
+                    touching_opcode = "sensing_touchingobject"
+                    
+                    touching_block_key, touching_block_data = create_block_instance(
+                        touching_opcode,
+                        opcode_occurrences, 
+                        parent_key=new_block_key,
+                        is_shadow=True,
+                        is_top_level=False
+                    )
+                    if touching_block_key:
+                        new_block_data["inputs"]["CONDITION"][1] = touching_block_key
+                        new_block_data["inputs"]["CONDITION"][0] = 2 # Type 2 for boolean block reference
+
+                        # Create the menu block for TOUCHINGOBJECTMENU
+                        menu_opcode = "sensing_touchingobjectmenu"
+                        menu_key, menu_data = create_block_instance(
+                            menu_opcode,
+                            opcode_occurrences, 
+                            parent_key=touching_block_key,
+                            is_shadow=True,
+                            is_top_level=False
+                        )
+                        if menu_key:
+                            touching_block_data["inputs"]["TOUCHINGOBJECTMENU"][1] = menu_key
+                            touching_block_data["inputs"]["TOUCHINGOBJECTMENU"][0] = 1 # Type 1 for block reference
+                            menu_data["fields"]["TOUCHINGOBJECTMENU"][0] = sprite_name
+                    else:
+                        print(f"Warning: Could not create touching object block for condition: '{line}'")
+
+
+            elif opcode == "control_forever":
+                # Forever blocks are C-blocks, so push them onto the stack
+                block_stack.append((new_block_key, current_line_indent, None)) # (parent_key, indent, last_child_key)
+            elif opcode == "control_stop":
+                option = matched_values[0].replace(' v', '').strip()
+                new_block_data["fields"]["STOP_OPTION"][0] = option
+            elif opcode == "event_broadcast":
+                message = matched_values[0].replace(' v', '').strip()
+                # For broadcast, the input is usually a string literal or a variable
+                new_block_data["inputs"]["BROADCAST_INPUT"][0] = 11 # Type 11 for broadcast input (string or variable)
+                new_block_data["inputs"]["BROADCAST_INPUT"][1] = [10, message] # Assume string literal for now
+                # A more robust solution would create a data_variable block if it's a variable.
+
+        # For C-blocks, push onto stack to track nesting
+        if all_block_definitions[opcode].get("block_shape") == "C-Block" and opcode != "control_if": # if is handled above
+             block_stack.append((new_block_key, current_line_indent, None)) # (parent_key, indent, last_child_key)
+
+
+    return updated_blocks
+
+# --- Consolidated Block Definitions from all provided JSONs ---
+all_block_definitions = {
+    # motion_block.json
+    "motion_movesteps": {
+        "opcode": "motion_movesteps", "next": None, "parent": None,
+        "inputs": {"STEPS": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 464, "y": -416
+    },
+    "motion_turnright": {
+        "opcode": "motion_turnright", "next": None, "parent": None,
+        "inputs": {"DEGREES": [1, [4, "15"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 467, "y": -316
+    },
+    "motion_turnleft": {
+        "opcode": "motion_turnleft", "next": None, "parent": None,
+        "inputs": {"DEGREES": [1, [4, "15"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 464, "y": -210
+    },
+    "motion_goto": {
+        "opcode": "motion_goto", "next": None, "parent": None,
+        "inputs": {"TO": [1, "motion_goto_menu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 465, "y": -95
+    },
+    "motion_goto_menu": {
+        "opcode": "motion_goto_menu", "next": None, "parent": "motion_goto",
+        "inputs": {}, "fields": {"TO": ["_random_", None]}, "shadow": True, "topLevel": False
+    },
+    "motion_gotoxy": {
+        "opcode": "motion_gotoxy", "next": None, "parent": None,
+        "inputs": {"X": [1, [4, "0"]], "Y": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 468, "y": 12
+    },
+    "motion_glideto": {
+        "opcode": "motion_glideto", "next": None, "parent": None,
+        "inputs": {"SECS": [1, [4, "1"]], "TO": [1, "motion_glideto_menu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 470, "y": 129
+    },
+    "motion_glideto_menu": {
+        "opcode": "motion_glideto_menu", "next": None, "parent": "motion_glideto",
+        "inputs": {}, "fields": {"TO": ["_random_", None]}, "shadow": True, "topLevel": False
+    },
+    "motion_glidesecstoxy": {
+        "opcode": "motion_glidesecstoxy", "next": None, "parent": None,
+        "inputs": {"SECS": [1, [4, "1"]], "X": [1, [4, "0"]], "Y": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 476, "y": 239
+    },
+    "motion_pointindirection": {
+        "opcode": "motion_pointindirection", "next": None, "parent": None,
+        "inputs": {"DIRECTION": [1, [8, "90"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 493, "y": 361
+    },
+    "motion_pointtowards": {
+        "opcode": "motion_pointtowards", "next": None, "parent": None,
+        "inputs": {"TOWARDS": [1, "motion_pointtowards_menu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 492, "y": 463
+    },
+    "motion_pointtowards_menu": {
+        "opcode": "motion_pointtowards_menu", "next": None, "parent": "motion_pointtowards",
+        "inputs": {}, "fields": {"TOWARDS": ["_mouse_", None]}, "shadow": True, "topLevel": False
+    },
+    "motion_changexby": {
+        "opcode": "motion_changexby", "next": None, "parent": None,
+        "inputs": {"DX": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 851, "y": -409
+    },
+    "motion_setx": {
+        "opcode": "motion_setx", "next": None, "parent": None,
+        "inputs": {"X": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 864, "y": -194
+    },
+    "motion_changeyby": {
+        "opcode": "motion_changeyby", "next": None, "parent": None,
+        "inputs": {"DY": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 861, "y": -61
+    },
+    "motion_sety": {
+        "opcode": "motion_sety", "next": None, "parent": None,
+        "inputs": {"Y": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 864, "y": 66
+    },
+    "motion_ifonedgebounce": {
+        "opcode": "motion_ifonedgebounce", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1131, "y": -397
+    },
+    "motion_setrotationstyle": {
+        "opcode": "motion_setrotationstyle", "next": None, "parent": None,
+        "inputs": {}, "fields": {"STYLE": ["left-right", None]}, "shadow": False, "topLevel": True,
+        "x": 1128, "y": -287
+    },
+    "motion_xposition": {
+        "opcode": "motion_xposition", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1193, "y": -136
+    },
+    "motion_yposition": {
+        "opcode": "motion_yposition", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1181, "y": -64
+    },
+    "motion_direction": {
+        "opcode": "motion_direction", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1188, "y": 21
+    },
+
+    # control_block.json
+    "control_wait": {
+        "opcode": "control_wait", "next": None, "parent": None,
+        "inputs": {"DURATION": [1, [5, "1"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 337, "y": 129
+    },
+    "control_repeat": {
+        "opcode": "control_repeat", "next": None, "parent": None,
+        "inputs": {"TIMES": [1, [6, "10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 348, "y": 265
+    },
+    "control_forever": {
+        "opcode": "control_forever", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 334, "y": 439
+    },
+    "control_if": {
+        "opcode": "control_if", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 331, "y": 597
+    },
+    "control_if_else": {
+        "opcode": "control_if_else", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 335, "y": 779
+    },
+    "control_wait_until": {
+        "opcode": "control_wait_until", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 676, "y": 285
+    },
+    "control_repeat_until": {
+        "opcode": "control_repeat_until", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 692, "y": 381
+    },
+    "control_stop": {
+        "opcode": "control_stop", "next": None, "parent": None,
+        "inputs": {}, "fields": {"STOP_OPTION": ["all", None]}, "shadow": False, "topLevel": True,
+        "x": 708, "y": 545, "mutation": {"tagName": "mutation", "children": [], "hasnext": "false"}
+    },
+    "control_start_as_clone": {
+        "opcode": "control_start_as_clone", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 665, "y": 672
+    },
+    "control_create_clone_of": {
+        "opcode": "control_create_clone_of", "next": None, "parent": None,
+        "inputs": {"CLONE_OPTION": [1, "control_create_clone_of_menu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 648, "y": 797
+    },
+    "control_create_clone_of_menu": {
+        "opcode": "control_create_clone_of_menu", "next": None, "parent": "control_create_clone_of",
+        "inputs": {}, "fields": {"CLONE_OPTION": ["_myself_", None]}, "shadow": True, "topLevel": False
+    },
+    "control_delete_this_clone": {
+        "opcode": "control_delete_this_clone", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 642, "y": 914
+    },
+
+    # data_block.json
+    "data_setvariableto": {
+        "opcode": "data_setvariableto", "next": None, "parent": None,
+        "inputs": {"VALUE": [1, [10, "0"]]}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True,
+        "x": 348, "y": 241
+    },
+    "data_changevariableby": {
+        "opcode": "data_changevariableby", "next": None, "parent": None,
+        "inputs": {"VALUE": [1, [4, "1"]]}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True,
+        "x": 313, "y": 363
+    },
+    "data_showvariable": {
+        "opcode": "data_showvariable", "next": None, "parent": None,
+        "inputs": {}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True,
+        "x": 415, "y": 473
+    },
+    "data_hidevariable": {
+        "opcode": "data_hidevariable", "next": None, "parent": None,
+        "inputs": {}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True,
+        "x": 319, "y": 587
+    },
+    "data_addtolist": {
+        "opcode": "data_addtolist", "next": None, "parent": None,
+        "inputs": {"ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 385, "y": 109
+    },
+    "data_deleteoflist": {
+        "opcode": "data_deleteoflist", "next": None, "parent": None,
+        "inputs": {"INDEX": [1, [7, "1"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 384, "y": 244
+    },
+    "data_deletealloflist": {
+        "opcode": "data_deletealloflist", "next": None, "parent": None,
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 387, "y": 374
+    },
+    "data_insertatlist": {
+        "opcode": "data_insertatlist", "next": None, "parent": None,
+        "inputs": {"ITEM": [1, [10, "thing"]], "INDEX": [1, [7, "1"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 366, "y": 527
+    },
+    "data_replaceitemoflist": {
+        "opcode": "data_replaceitemoflist", "next": None, "parent": None,
+        "inputs": {"INDEX": [1, [7, "1"]], "ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 365, "y": 657
+    },
+    "data_itemoflist": {
+        "opcode": "data_itemoflist", "next": None, "parent": None,
+        "inputs": {"INDEX": [1, [7, "1"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 862, "y": 117
+    },
+    "data_itemnumoflist": {
+        "opcode": "data_itemnumoflist", "next": None, "parent": None,
+        "inputs": {"ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 883, "y": 238
+    },
+    "data_lengthoflist": {
+        "opcode": "data_lengthoflist", "next": None, "parent": None,
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 876, "y": 342
+    },
+    "data_listcontainsitem": {
+        "opcode": "data_listcontainsitem", "next": None, "parent": None,
+        "inputs": {"ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 871, "y": 463
+    },
+    "data_showlist": {
+        "opcode": "data_showlist", "next": None, "parent": None,
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 931, "y": 563
+    },
+    "data_hidelist": {
+        "opcode": "data_hidelist", "next": None, "parent": None,
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 962, "y": 716
+    },
+
+    # event_block.json
+    "event_whenflagclicked": {
+        "opcode": "event_whenflagclicked", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 166, "y": -422
+    },
+    "event_whenkeypressed": {
+        "opcode": "event_whenkeypressed", "next": None, "parent": None,
+        "inputs": {}, "fields": {"KEY_OPTION": ["space", None]}, "shadow": False, "topLevel": True,
+        "x": 151, "y": -329
+    },
+    "event_whenthisspriteclicked": {
+        "opcode": "event_whenthisspriteclicked", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 156, "y": -223
+    },
+    "event_whenbackdropswitchesto": {
+        "opcode": "event_whenbackdropswitchesto", "next": None, "parent": None,
+        "inputs": {}, "fields": {"BACKDROP": ["backdrop1", None]}, "shadow": False, "topLevel": True,
+        "x": 148, "y": -101
+    },
+    "event_whengreaterthan": {
+        "opcode": "event_whengreaterthan", "next": None, "parent": None,
+        "inputs": {"VALUE": [1, [4, "10"]]}, "fields": {"WHENGREATERTHANMENU": ["LOUDNESS", None]}, "shadow": False, "topLevel": True,
+        "x": 150, "y": 10
+    },
+    "event_whenbroadcastreceived": {
+        "opcode": "event_whenbroadcastreceived", "next": None, "parent": None,
+        "inputs": {}, "fields": {"BROADCAST_OPTION": ["message1", "5O!nei;S$!c!=hCT}0:a"]}, "shadow": False, "topLevel": True,
+        "x": 141, "y": 118
+    },
+    "event_broadcast": {
+        "opcode": "event_broadcast", "next": None, "parent": None,
+        "inputs": {"BROADCAST_INPUT": [1, [11, "message1", "5O!nei;S$!c!=hCT}0:a"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 151, "y": 229
+    },
+    "event_broadcastandwait": {
+        "opcode": "event_broadcastandwait", "next": None, "parent": None,
+        "inputs": {"BROADCAST_INPUT": [1, [11, "message1", "5O!nei;S$!c!=hCT}0:a"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 157, "y": 340
+    },
+
+    # look_block.json
+    "looks_sayforsecs": {
+        "opcode": "looks_sayforsecs", "next": None, "parent": None,
+        "inputs": {"MESSAGE": [1, [10, "Hello!"]], "SECS": [1, [4, "2"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 408, "y": 91
+    },
+    "looks_say": {
+        "opcode": "looks_say", "next": None, "parent": None,
+        "inputs": {"MESSAGE": [1, [10, "Hello!"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 413, "y": 213
+    },
+    "looks_thinkforsecs": {
+        "opcode": "looks_thinkforsecs", "next": None, "parent": None,
+        "inputs": {"MESSAGE": [1, [10, "Hmm..."]], "SECS": [1, [4, "2"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 413, "y": 317
+    },
+    "looks_think": {
+        "opcode": "looks_think", "next": None, "parent": None,
+        "inputs": {"MESSAGE": [1, [10, "Hmm..."]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 412, "y": 432
+    },
+    "looks_switchcostumeto": {
+        "opcode": "looks_switchcostumeto", "next": None, "parent": None,
+        "inputs": {"COSTUME": [1, "8;bti4wv(iH9nkOacCJ|"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 411, "y": 555
+    },
+    "looks_costume": {
+        "opcode": "looks_costume", "next": None, "parent": "Q#a,6LPWHqo9-0Nu*[SV",
+        "inputs": {}, "fields": {"COSTUME": ["costume2", None]}, "shadow": True, "topLevel": False
+    },
+    "looks_nextcostume": {
+        "opcode": "looks_nextcostume", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 419, "y": 687
+    },
+    "looks_switchbackdropto": {
+        "opcode": "looks_switchbackdropto", "next": None, "parent": None,
+        "inputs": {"BACKDROP": [1, "-?yeX}29V*wd6W:unW0i"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 901, "y": 91
+    },
+    "looks_backdrops": {
+        "opcode": "looks_backdrops", "next": None, "parent": "`Wm^p~l[(IWzc1|wNv*.",
+        "inputs": {}, "fields": {"BACKDROP": ["backdrop1", None]}, "shadow": True, "topLevel": False
+    },
+    "looks_changesizeby": {
+        "opcode": "looks_changesizeby", "next": None, "parent": None,
+        "inputs": {"CHANGE": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 895, "y": 192
+    },
+    "looks_setsizeto": {
+        "opcode": "looks_setsizeto", "next": None, "parent": None,
+        "inputs": {"SIZE": [1, [4, "100"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 896, "y": 303
+    },
+    "looks_changeeffectby": {
+        "opcode": "looks_changeeffectby", "next": None, "parent": None,
+        "inputs": {"CHANGE": [1, [4, "25"]]}, "fields": {"EFFECT": ["COLOR", None]}, "shadow": False, "topLevel": True,
+        "x": 892, "y": 416
+    },
+    "looks_seteffectto": {
+        "opcode": "looks_seteffectto", "next": None, "parent": None,
+        "inputs": {"VALUE": [1, [4, "0"]]}, "fields": {"EFFECT": ["COLOR", None]}, "shadow": False, "topLevel": True,
+        "x": 902, "y": 527
+    },
+    "looks_cleargraphiceffects": {
+        "opcode": "looks_cleargraphiceffects", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 902, "y": 638
+    },
+    "looks_show": {
+        "opcode": "looks_show", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 908, "y": 758
+    },
+    "looks_hide": {
+        "opcode": "looks_hide", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 455, "y": 861
+    },
+    "looks_gotofrontback": {
+        "opcode": "looks_gotofrontback", "next": None, "parent": None,
+        "inputs": {}, "fields": {"FRONT_BACK": ["front", None]}, "shadow": False, "topLevel": True,
+        "x": 853, "y": 878
+    },
+    "looks_goforwardbackwardlayers": {
+        "opcode": "looks_goforwardbackwardlayers", "next": None, "parent": None,
+        "inputs": {"NUM": [1, [7, "1"]]}, "fields": {"FORWARD_BACKWARD": ["forward", None]}, "shadow": False, "topLevel": True,
+        "x": 851, "y": 999
+    },
+    "looks_costumenumbername": {
+        "opcode": "looks_costumenumbername", "next": None, "parent": None,
+        "inputs": {}, "fields": {"NUMBER_NAME": ["number", None]}, "shadow": False, "topLevel": True,
+        "x": 458, "y": 1007
+    },
+    "looks_backdropnumbername": {
+        "opcode": "looks_backdropnumbername", "next": None, "parent": None,
+        "inputs": {}, "fields": {"NUMBER_NAME": ["number", None]}, "shadow": False, "topLevel": True,
+        "x": 1242, "y": 753
+    },
+    "looks_size": {
+        "opcode": "looks_size", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1249, "y": 876
+    },
+
+    # operator_block.json
+    "operator_add": {
+        "opcode": "operator_add", "next": None, "parent": None,
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 128, "y": 153
+    },
+    "operator_subtract": {
+        "opcode": "operator_subtract", "next": None, "parent": None,
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 134, "y": 214
+    },
+    "operator_multiply": {
+        "opcode": "operator_multiply", "next": None, "parent": None,
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 134, "y": 278
+    },
+    "operator_divide": {
+        "opcode": "operator_divide", "next": None, "parent": None,
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 138, "y": 359
+    },
+    "operator_random": {
+        "opcode": "operator_random", "next": None, "parent": None,
+        "inputs": {"FROM": [1, [4, "1"]], "TO": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 311, "y": 157
+    },
+    "operator_gt": {
+        "opcode": "operator_gt", "next": None, "parent": None,
+        "inputs": {"OPERAND1": [1, [10, ""]], "OPERAND2": [1, [10, "50"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 348, "y": 217
+    },
+    "operator_lt": {
+        "opcode": "operator_lt", "next": None, "parent": None,
+        "inputs": {"OPERAND1": [1, [10, ""]], "OPERAND2": [1, [10, "50"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 345, "y": 286
+    },
+    "operator_equals": {
+        "opcode": "operator_equals", "next": None, "parent": None,
+        "inputs": {"OPERAND1": [1, [10, ""]], "OPERAND2": [1, [10, "50"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 345, "y": 372
+    },
+    "operator_and": {
+        "opcode": "operator_and", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 701, "y": 158
+    },
+    "operator_or": {
+        "opcode": "operator_or", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 705, "y": 222
+    },
+    "operator_not": {
+        "opcode": "operator_not", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 734, "y": 283
+    },
+    "operator_join": {
+        "opcode": "operator_join", "next": None, "parent": None,
+        "inputs": {"STRING1": [1, [10, "apple "]], "STRING2": [1, [10, "banana"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 663, "y": 378
+    },
+    "operator_letter_of": {
+        "opcode": "operator_letter_of", "next": None, "parent": None,
+        "inputs": {"LETTER": [1, [6, "1"]], "STRING": [1, [10, "apple"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 664, "y": 445
+    },
+    "operator_length": {
+        "opcode": "operator_length", "next": None, "parent": None,
+        "inputs": {"STRING": [1, [10, "apple"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 664, "y": 521
+    },
+    "operator_contains": {
+        "opcode": "operator_contains", "next": None, "parent": None,
+        "inputs": {"STRING1": [1, [10, "apple"]], "STRING2": [1, [10, "a"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 634, "y": 599
+    },
+    "operator_mod": {
+        "opcode": "operator_mod", "next": None, "parent": None,
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 295, "y": 594
+    },
+    "operator_round": {
+        "opcode": "operator_round", "next": None, "parent": None,
+        "inputs": {"NUM": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 307, "y": 674
+    },
+    "operator_mathop": {
+        "opcode": "operator_mathop", "next": None, "parent": None,
+        "inputs": {"NUM": [1, [4, ""]]}, "fields": {"OPERATOR": ["abs", None]}, "shadow": False, "topLevel": True,
+        "x": 280, "y": 754
+    },
+
+    # sensing_block.json
+    "sensing_touchingobject": {
+        "opcode": "sensing_touchingobject", "next": None, "parent": None,
+        "inputs": {"TOUCHINGOBJECTMENU": [1, "sensing_touchingobjectmenu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 359, "y": 116
+    },
+    "sensing_touchingobjectmenu": {
+        "opcode": "sensing_touchingobjectmenu", "next": None, "parent": "sensing_touchingobject",
+        "inputs": {}, "fields": {"TOUCHINGOBJECTMENU": ["_mouse_", None]}, "shadow": True, "topLevel": False
+    },
+    "sensing_touchingcolor": {
+        "opcode": "sensing_touchingcolor", "next": None, "parent": None,
+        "inputs": {"COLOR": [1, [9, "#55b888"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 360, "y": 188
+    },
+    "sensing_coloristouchingcolor": {
+        "opcode": "sensing_coloristouchingcolor", "next": None, "parent": None,
+        "inputs": {"COLOR": [1, [9, "#d019f2"]], "COLOR2": [1, [9, "#2b0de3"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 348, "y": 277
+    },
+    "sensing_askandwait": {
+        "opcode": "sensing_askandwait", "next": None, "parent": None,
+        "inputs": {"QUESTION": [1, [10, "What's your name?"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 338, "y": 354
+    },
+    "sensing_answer": {
+        "opcode": "sensing_answer", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 782, "y": 111
+    },
+    "sensing_keypressed": {
+        "opcode": "sensing_keypressed", "next": None, "parent": None,
+        "inputs": {"KEY_OPTION": [1, "sensing_keyoptions"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 762, "y": 207
+    },
+    "sensing_keyoptions": {
+        "opcode": "sensing_keyoptions", "next": None, "parent": "sensing_keypressed",
+        "inputs": {}, "fields": {"KEY_OPTION": ["space", None]}, "shadow": True, "topLevel": False
+    },
+    "sensing_mousedown": {
+        "opcode": "sensing_mousedown", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 822, "y": 422
+    },
+    "sensing_mousex": {
+        "opcode": "sensing_mousex", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 302, "y": 528
+    },
+    "sensing_mousey": {
+        "opcode": "sensing_mousey", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 668, "y": 547
+    },
+    "sensing_setdragmode": {
+        "opcode": "sensing_setdragmode", "next": None, "parent": None,
+        "inputs": {}, "fields": {"DRAG_MODE": ["draggable", None]}, "shadow": False, "topLevel": True,
+        "x": 950, "y": 574
+    },
+    "sensing_loudness": {
+        "opcode": "sensing_loudness", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 658, "y": 703
+    },
+    "sensing_timer": {
+        "opcode": "sensing_timer", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 459, "y": 671
+    },
+    "sensing_resettimer": {
+        "opcode": "sensing_resettimer", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 462, "y": 781
+    },
+    "sensing_of": {
+        "opcode": "sensing_of", "next": None, "parent": None,
+        "inputs": {"OBJECT": [1, "sensing_of_object_menu"]}, "fields": {"PROPERTY": ["backdrop #", None]}, "shadow": False, "topLevel": True,
+        "x": 997, "y": 754
+    },
+    "sensing_of_object_menu": {
+        "opcode": "sensing_of_object_menu", "next": None, "parent": "sensing_of",
+        "inputs": {}, "fields": {"OBJECT": ["_stage_", None]}, "shadow": True, "topLevel": False
+    },
+    "sensing_current": {
+        "opcode": "sensing_current", "next": None, "parent": None,
+        "inputs": {}, "fields": {"CURRENTMENU": ["YEAR", None]}, "shadow": False, "topLevel": True,
+        "x": 627, "y": 884
+    },
+    "sensing_dayssince2000": {
+        "opcode": "sensing_dayssince2000", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 959, "y": 903
+    },
+    "sensing_username": {
+        "opcode": "sensing_username", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 833, "y": 757
+    },
+
+    # sound_block.json
+    "sound_playuntildone": {
+        "opcode": "sound_playuntildone", "next": None, "parent": None,
+        "inputs": {"SOUND_MENU": [1, "sound_sounds_menu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 253, "y": 17
+    },
+    "sound_sounds_menu": {
+        "opcode": "sound_sounds_menu", "next": None, "parent": "sound_playuntildone and sound_play",
+        "inputs": {}, "fields": {"SOUND_MENU": ["Meow", None]}, "shadow": True, "topLevel": False
+    },
+    "sound_play": {
+        "opcode": "sound_play", "next": None, "parent": None,
+        "inputs": {"SOUND_MENU": [1, "sound_sounds_menu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 245, "y": 122
+    },
+    "sound_stopallsounds": {
+        "opcode": "sound_stopallsounds", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 253, "y": 245
+    },
+    "sound_changeeffectby": {
+        "opcode": "sound_changeeffectby", "next": None, "parent": None,
+        "inputs": {"VALUE": [1, [4, "10"]]}, "fields": {"EFFECT": ["PITCH", None]}, "shadow": False, "topLevel": True,
+        "x": 653, "y": 14
+    },
+    "sound_seteffectto": {
+        "opcode": "sound_seteffectto", "next": None, "parent": None,
+        "inputs": {"VALUE": [1, [4, "100"]]}, "fields": {"EFFECT": ["PITCH", None]}, "shadow": False, "topLevel": True,
+        "x": 653, "y": 139
+    },
+    "sound_cleareffects": {
+        "opcode": "sound_cleareffects", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 651, "y": 242
+    },
+    "sound_changevolumeby": {
+        "opcode": "sound_changevolumeby", "next": None, "parent": None,
+        "inputs": {"VOLUME": [1, [4, "-10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 645, "y": 353
+    },
+    "sound_setvolumeto": {
+        "opcode": "sound_setvolumeto", "next": None, "parent": None,
+        "inputs": {"VOLUME": [1, [4, "100"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1108, "y": 5
+    },
+    "sound_volume": {
+        "opcode": "sound_volume", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1136, "y": 123
+    },
+}
+
+# #Example input with opcodes from various categories
+# input_opcodes = [
+#     {"opcode": "sound_play", "count": 2},         # New: Sound block with menu
+#     {"opcode": "sound_playuntildone", "count": 2}, # New: Sound block with menu
+# ]
+
+# Example input with opcodes from various categories
+# input_opcodes = [
+#     {"opcode": "sound_play", "count": 2},
+#     {"opcode": "sound_playuntildone", "count": 2},
+#     {"opcode":"motion_goto","count":2},
+#     {"opcode":"motion_glideto","count":2},
+#     {"opcode":"looks_switchbackdropto","count":2},
+#     {"opcode":"looks_switchcostumeto","count":2},
+#     {"opcode":"control_create_clone_of","count":2},
+#     {"opcode":"sensing_touchingobject","count":2},
+#     {"opcode":"sensing_of","count":2},
+#     {"opcode":"sensing_keypressed","count":2},
+#     {"opcode":"motion_pointtowards","count":2},
+# ]
+
+# generated_output = generate_blocks_from_opcodes(input_opcodes, all_block_definitions)
+# print(json.dumps(generated_output, indent=2))
+
+initial_opcode_counts = [
+    {"opcode":"event_whenflagclicked","count":1},
+    {"opcode":"motion_gotoxy","count":1},
+    {"opcode":"motion_glidesecstoxy","count":1},
+    {"opcode":"motion_xposition","count":1},
+    {"opcode":"motion_setx","count":1},
+    {"opcode":"control_forever","count":1},
+    {"opcode":"control_if","count":1},
+    {"opcode":"control_stop","count":1},
+    {"opcode":"operator_lt","count":1},
+    {"opcode":"sensing_istouching","count":1},
+    {"opcode":"sensing_touchingobjectmenu","count":1}, # This will now be generated as a child of sensing_touchingobject
+    {"opcode":"event_broadcast","count":1},
+    {"opcode":"data_setvariableto","count":2},
+    {"opcode":"data_showvariable","count":2},
+]
+
+# Generate the initial blocks and get the opcode_occurrences
+generated_output_json, initial_opcode_occurrences = generate_blocks_from_opcodes(initial_opcode_counts, all_block_definitions)
+
+# Pseudo-code to interpret
+pseudo_code_input = """
+when green flag clicked
+  go to x: (240) y: (-135)
+  set [score v] to +1
+  set [speed v] to +1
+  show variable [score v]
+  show variable [speed v]
+  forever
+    glide (2) seconds to x: (-240) y: (-135)
+    if <((x position)) < (-235)> then
+      set x to (240)
+    end
+    if <touching [Sprite1 v]?> then
+      broadcast [Game Over v]
+      stop [all v]
+    end
+  end
+end
+"""
+
+# Interpret the pseudo-code and update the blocks, passing opcode_occurrences
+final_generated_blocks = interpret_pseudo_code_and_update_blocks(generated_output_json, pseudo_code_input, all_block_definitions, initial_opcode_occurrences)
+
+print(json.dumps(final_generated_blocks, indent=2))

utils/block_function_v1.py

@@ -0,0 +1,759 @@
+import json
+import copy
+
+import json
+import copy
+
+def generate_blocks_from_opcodes(opcode_counts, all_block_definitions):
+    """
+    Generates a dictionary of Scratch-like blocks based on a list of opcodes and a reference block definition.
+    It now correctly links parent and menu blocks using their generated unique keys, and handles various block categories.
+    It ensures that menu blocks are only generated as children of their respective parent blocks.
+
+    Args:
+        opcode_counts (list): An array of objects, each with an 'opcode' and 'count' property.
+                              Example: [{"opcode": "motion_gotoxy", "count": 1}]
+        all_block_definitions (dict): A comprehensive dictionary containing definitions for all block types.
+
+    Returns:
+        dict: A JSON object where keys are generated block IDs and values are the block definitions.
+    """
+    generated_blocks = {}
+    opcode_occurrences = {}  # To keep track of how many times each opcode (main or menu) has been used for unique keys
+
+    # Define explicit parent-menu relationships for linking purposes
+    # This maps main_opcode -> list of (input_field_name, menu_opcode)
+    explicit_menu_links = {
+        "motion_goto": [("TO", "motion_goto_menu")],
+        "motion_glideto": [("TO", "motion_glideto_menu")],
+        "motion_pointtowards": [("TOWARDS", "motion_pointtowards_menu")],
+        "sensing_keypressed": [("KEY_OPTION", "sensing_keyoptions")],
+        "sensing_of": [("OBJECT", "sensing_of_object_menu")],
+        "sensing_touchingobject": [("TOUCHINGOBJECTMENU", "sensing_touchingobjectmenu")],
+        "control_create_clone_of": [("CLONE_OPTION", "control_create_clone_of_menu")],
+        "sound_play": [("SOUND_MENU", "sound_sounds_menu")],
+        "sound_playuntildone": [("SOUND_MENU", "sound_sounds_menu")],
+        "looks_switchcostumeto": [("COSTUME", "looks_costume")],
+        "looks_switchbackdropto": [("BACKDROP", "looks_backdrops")],
+    }
+
+    # --- Step 1: Process explicitly requested opcodes and generate their instances and associated menus ---
+    for item in opcode_counts:
+        opcode = item.get("opcode")
+        count = item.get("count", 1)
+
+        if not opcode:
+            print("Warning: Skipping item with missing 'opcode'.")
+            continue
+
+        if opcode not in all_block_definitions:
+            print(f"Warning: Opcode '{opcode}' not found in all_block_definitions. Skipping.")
+            continue
+
+        for _ in range(count):
+            # Increment occurrence count for the current main opcode
+            opcode_occurrences[opcode] = opcode_occurrences.get(opcode, 0) + 1
+            main_block_instance_num = opcode_occurrences[opcode]
+            
+            main_block_unique_key = f"{opcode}_{main_block_instance_num}"
+            
+            # Create a deep copy of the main block definition
+            main_block_data = copy.deepcopy(all_block_definitions[opcode])
+            
+            # Set properties for a top-level main block
+            main_block_data["parent"] = None
+            main_block_data["next"] = None
+            main_block_data["topLevel"] = True
+            main_block_data["shadow"] = False # Main blocks are typically not shadows
+
+            generated_blocks[main_block_unique_key] = main_block_data
+
+            # If this main block has associated menus, generate and link them now
+            if opcode in explicit_menu_links:
+                for input_field_name, menu_opcode_type in explicit_menu_links[opcode]:
+                    if menu_opcode_type in all_block_definitions:
+                        # Increment the occurrence for the menu block type
+                        opcode_occurrences[menu_opcode_type] = opcode_occurrences.get(menu_opcode_type, 0) + 1
+                        menu_block_instance_num = opcode_occurrences[menu_opcode_type]
+
+                        menu_block_data = copy.deepcopy(all_block_definitions[menu_opcode_type])
+                        
+                        # Generate a unique key for this specific menu instance
+                        menu_unique_key = f"{menu_opcode_type}_{menu_block_instance_num}"
+                        
+                        # Set properties for a shadow menu block
+                        menu_block_data["shadow"] = True
+                        menu_block_data["topLevel"] = False
+                        menu_block_data["next"] = None
+                        menu_block_data["parent"] = main_block_unique_key # Link menu to its parent instance
+
+                        # Update the main block's input to point to this unique menu instance
+                        if input_field_name in main_block_data.get("inputs", {}) and \
+                           isinstance(main_block_data["inputs"][input_field_name], list) and \
+                           len(main_block_data["inputs"][input_field_name]) > 1 and \
+                           main_block_data["inputs"][input_field_name][0] == 1:
+                            
+                            main_block_data["inputs"][input_field_name][1] = menu_unique_key
+                        
+                        generated_blocks[menu_unique_key] = menu_block_data
+            
+    return generated_blocks
+
+
+# --- Consolidated Block Definitions from all provided JSONs ---
+all_block_definitions = {
+    # motion_block.json
+    "motion_movesteps": {
+        "opcode": "motion_movesteps", "next": None, "parent": None,
+        "inputs": {"STEPS": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 464, "y": -416
+    },
+    "motion_turnright": {
+        "opcode": "motion_turnright", "next": None, "parent": None,
+        "inputs": {"DEGREES": [1, [4, "15"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 467, "y": -316
+    },
+    "motion_turnleft": {
+        "opcode": "motion_turnleft", "next": None, "parent": None,
+        "inputs": {"DEGREES": [1, [4, "15"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 464, "y": -210
+    },
+    "motion_goto": {
+        "opcode": "motion_goto", "next": None, "parent": None,
+        "inputs": {"TO": [1, "motion_goto_menu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 465, "y": -95
+    },
+    "motion_goto_menu": {
+        "opcode": "motion_goto_menu", "next": None, "parent": "motion_goto",
+        "inputs": {}, "fields": {"TO": ["_random_", None]}, "shadow": True, "topLevel": False
+    },
+    "motion_gotoxy": {
+        "opcode": "motion_gotoxy", "next": None, "parent": None,
+        "inputs": {"X": [1, [4, "0"]], "Y": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 468, "y": 12
+    },
+    "motion_glideto": {
+        "opcode": "motion_glideto", "next": None, "parent": None,
+        "inputs": {"SECS": [1, [4, "1"]], "TO": [1, "motion_glideto_menu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 470, "y": 129
+    },
+    "motion_glideto_menu": {
+        "opcode": "motion_glideto_menu", "next": None, "parent": "motion_glideto",
+        "inputs": {}, "fields": {"TO": ["_random_", None]}, "shadow": True, "topLevel": False
+    },
+    "motion_glidesecstoxy": {
+        "opcode": "motion_glidesecstoxy", "next": None, "parent": None,
+        "inputs": {"SECS": [1, [4, "1"]], "X": [1, [4, "0"]], "Y": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 476, "y": 239
+    },
+    "motion_pointindirection": {
+        "opcode": "motion_pointindirection", "next": None, "parent": None,
+        "inputs": {"DIRECTION": [1, [8, "90"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 493, "y": 361
+    },
+    "motion_pointtowards": {
+        "opcode": "motion_pointtowards", "next": None, "parent": None,
+        "inputs": {"TOWARDS": [1, "motion_pointtowards_menu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 492, "y": 463
+    },
+    "motion_pointtowards_menu": {
+        "opcode": "motion_pointtowards_menu", "next": None, "parent": "motion_pointtowards",
+        "inputs": {}, "fields": {"TOWARDS": ["_mouse_", None]}, "shadow": True, "topLevel": False
+    },
+    "motion_changexby": {
+        "opcode": "motion_changexby", "next": None, "parent": None,
+        "inputs": {"DX": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 851, "y": -409
+    },
+    "motion_setx": {
+        "opcode": "motion_setx", "next": None, "parent": None,
+        "inputs": {"X": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 864, "y": -194
+    },
+    "motion_changeyby": {
+        "opcode": "motion_changeyby", "next": None, "parent": None,
+        "inputs": {"DY": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 861, "y": -61
+    },
+    "motion_sety": {
+        "opcode": "motion_sety", "next": None, "parent": None,
+        "inputs": {"Y": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 864, "y": 66
+    },
+    "motion_ifonedgebounce": {
+        "opcode": "motion_ifonedgebounce", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1131, "y": -397
+    },
+    "motion_setrotationstyle": {
+        "opcode": "motion_setrotationstyle", "next": None, "parent": None,
+        "inputs": {}, "fields": {"STYLE": ["left-right", None]}, "shadow": False, "topLevel": True,
+        "x": 1128, "y": -287
+    },
+    "motion_xposition": {
+        "opcode": "motion_xposition", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1193, "y": -136
+    },
+    "motion_yposition": {
+        "opcode": "motion_yposition", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1181, "y": -64
+    },
+    "motion_direction": {
+        "opcode": "motion_direction", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1188, "y": 21
+    },
+
+    # control_block.json
+    "control_wait": {
+        "opcode": "control_wait", "next": None, "parent": None,
+        "inputs": {"DURATION": [1, [5, "1"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 337, "y": 129
+    },
+    "control_repeat": {
+        "opcode": "control_repeat", "next": None, "parent": None,
+        "inputs": {"TIMES": [1, [6, "10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 348, "y": 265
+    },
+    "control_forever": {
+        "opcode": "control_forever", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 334, "y": 439
+    },
+    "control_if": {
+        "opcode": "control_if", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 331, "y": 597
+    },
+    "control_if_else": {
+        "opcode": "control_if_else", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 335, "y": 779
+    },
+    "control_wait_until": {
+        "opcode": "control_wait_until", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 676, "y": 285
+    },
+    "control_repeat_until": {
+        "opcode": "control_repeat_until", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 692, "y": 381
+    },
+    "control_stop": {
+        "opcode": "control_stop", "next": None, "parent": None,
+        "inputs": {}, "fields": {"STOP_OPTION": ["all", None]}, "shadow": False, "topLevel": True,
+        "x": 708, "y": 545, "mutation": {"tagName": "mutation", "children": [], "hasnext": "false"}
+    },
+    "control_start_as_clone": {
+        "opcode": "control_start_as_clone", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 665, "y": 672
+    },
+    "control_create_clone_of": {
+        "opcode": "control_create_clone_of", "next": None, "parent": None,
+        "inputs": {"CLONE_OPTION": [1, "control_create_clone_of_menu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 648, "y": 797
+    },
+    "control_create_clone_of_menu": {
+        "opcode": "control_create_clone_of_menu", "next": None, "parent": "control_create_clone_of",
+        "inputs": {}, "fields": {"CLONE_OPTION": ["_myself_", None]}, "shadow": True, "topLevel": False
+    },
+    "control_delete_this_clone": {
+        "opcode": "control_delete_this_clone", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 642, "y": 914
+    },
+
+    # data_block.json
+    "data_setvariableto": {
+        "opcode": "data_setvariableto", "next": None, "parent": None,
+        "inputs": {"VALUE": [1, [10, "0"]]}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True,
+        "x": 348, "y": 241
+    },
+    "data_changevariableby": {
+        "opcode": "data_changevariableby", "next": None, "parent": None,
+        "inputs": {"VALUE": [1, [4, "1"]]}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True,
+        "x": 313, "y": 363
+    },
+    "data_showvariable": {
+        "opcode": "data_showvariable", "next": None, "parent": None,
+        "inputs": {}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True,
+        "x": 415, "y": 473
+    },
+    "data_hidevariable": {
+        "opcode": "data_hidevariable", "next": None, "parent": None,
+        "inputs": {}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True,
+        "x": 319, "y": 587
+    },
+    "data_addtolist": {
+        "opcode": "data_addtolist", "next": None, "parent": None,
+        "inputs": {"ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 385, "y": 109
+    },
+    "data_deleteoflist": {
+        "opcode": "data_deleteoflist", "next": None, "parent": None,
+        "inputs": {"INDEX": [1, [7, "1"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 384, "y": 244
+    },
+    "data_deletealloflist": {
+        "opcode": "data_deletealloflist", "next": None, "parent": None,
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 387, "y": 374
+    },
+    "data_insertatlist": {
+        "opcode": "data_insertatlist", "next": None, "parent": None,
+        "inputs": {"ITEM": [1, [10, "thing"]], "INDEX": [1, [7, "1"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 366, "y": 527
+    },
+    "data_replaceitemoflist": {
+        "opcode": "data_replaceitemoflist", "next": None, "parent": None,
+        "inputs": {"INDEX": [1, [7, "1"]], "ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 365, "y": 657
+    },
+    "data_itemoflist": {
+        "opcode": "data_itemoflist", "next": None, "parent": None,
+        "inputs": {"INDEX": [1, [7, "1"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 862, "y": 117
+    },
+    "data_itemnumoflist": {
+        "opcode": "data_itemnumoflist", "next": None, "parent": None,
+        "inputs": {"ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 883, "y": 238
+    },
+    "data_lengthoflist": {
+        "opcode": "data_lengthoflist", "next": None, "parent": None,
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 876, "y": 342
+    },
+    "data_listcontainsitem": {
+        "opcode": "data_listcontainsitem", "next": None, "parent": None,
+        "inputs": {"ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 871, "y": 463
+    },
+    "data_showlist": {
+        "opcode": "data_showlist", "next": None, "parent": None,
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 931, "y": 563
+    },
+    "data_hidelist": {
+        "opcode": "data_hidelist", "next": None, "parent": None,
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True,
+        "x": 962, "y": 716
+    },
+
+    # event_block.json
+    "event_whenflagclicked": {
+        "opcode": "event_whenflagclicked", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 166, "y": -422
+    },
+    "event_whenkeypressed": {
+        "opcode": "event_whenkeypressed", "next": None, "parent": None,
+        "inputs": {}, "fields": {"KEY_OPTION": ["space", None]}, "shadow": False, "topLevel": True,
+        "x": 151, "y": -329
+    },
+    "event_whenthisspriteclicked": {
+        "opcode": "event_whenthisspriteclicked", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 156, "y": -223
+    },
+    "event_whenbackdropswitchesto": {
+        "opcode": "event_whenbackdropswitchesto", "next": None, "parent": None,
+        "inputs": {}, "fields": {"BACKDROP": ["backdrop1", None]}, "shadow": False, "topLevel": True,
+        "x": 148, "y": -101
+    },
+    "event_whengreaterthan": {
+        "opcode": "event_whengreaterthan", "next": None, "parent": None,
+        "inputs": {"VALUE": [1, [4, "10"]]}, "fields": {"WHENGREATERTHANMENU": ["LOUDNESS", None]}, "shadow": False, "topLevel": True,
+        "x": 150, "y": 10
+    },
+    "event_whenbroadcastreceived": {
+        "opcode": "event_whenbroadcastreceived", "next": None, "parent": None,
+        "inputs": {}, "fields": {"BROADCAST_OPTION": ["message1", "5O!nei;S$!c!=hCT}0:a"]}, "shadow": False, "topLevel": True,
+        "x": 141, "y": 118
+    },
+    "event_broadcast": {
+        "opcode": "event_broadcast", "next": None, "parent": None,
+        "inputs": {"BROADCAST_INPUT": [1, [11, "message1", "5O!nei;S$!c!=hCT}0:a"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 151, "y": 229
+    },
+    "event_broadcastandwait": {
+        "opcode": "event_broadcastandwait", "next": None, "parent": None,
+        "inputs": {"BROADCAST_INPUT": [1, [11, "message1", "5O!nei;S$!c!=hCT}0:a"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 157, "y": 340
+    },
+
+    # look_block.json
+    "looks_sayforsecs": {
+        "opcode": "looks_sayforsecs", "next": None, "parent": None,
+        "inputs": {"MESSAGE": [1, [10, "Hello!"]], "SECS": [1, [4, "2"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 408, "y": 91
+    },
+    "looks_say": {
+        "opcode": "looks_say", "next": None, "parent": None,
+        "inputs": {"MESSAGE": [1, [10, "Hello!"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 413, "y": 213
+    },
+    "looks_thinkforsecs": {
+        "opcode": "looks_thinkforsecs", "next": None, "parent": None,
+        "inputs": {"MESSAGE": [1, [10, "Hmm..."]], "SECS": [1, [4, "2"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 413, "y": 317
+    },
+    "looks_think": {
+        "opcode": "looks_think", "next": None, "parent": None,
+        "inputs": {"MESSAGE": [1, [10, "Hmm..."]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 412, "y": 432
+    },
+    "looks_switchcostumeto": {
+        "opcode": "looks_switchcostumeto", "next": None, "parent": None,
+        "inputs": {"COSTUME": [1, "8;bti4wv(iH9nkOacCJ|"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 411, "y": 555
+    },
+    "looks_costume": {
+        "opcode": "looks_costume", "next": None, "parent": "Q#a,6LPWHqo9-0Nu*[SV",
+        "inputs": {}, "fields": {"COSTUME": ["costume2", None]}, "shadow": True, "topLevel": False
+    },
+    "looks_nextcostume": {
+        "opcode": "looks_nextcostume", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 419, "y": 687
+    },
+    "looks_switchbackdropto": {
+        "opcode": "looks_switchbackdropto", "next": None, "parent": None,
+        "inputs": {"BACKDROP": [1, "-?yeX}29V*wd6W:unW0i"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 901, "y": 91
+    },
+    "looks_backdrops": {
+        "opcode": "looks_backdrops", "next": None, "parent": "`Wm^p~l[(IWzc1|wNv*.",
+        "inputs": {}, "fields": {"BACKDROP": ["backdrop1", None]}, "shadow": True, "topLevel": False
+    },
+    "looks_changesizeby": {
+        "opcode": "looks_changesizeby", "next": None, "parent": None,
+        "inputs": {"CHANGE": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 895, "y": 192
+    },
+    "looks_setsizeto": {
+        "opcode": "looks_setsizeto", "next": None, "parent": None,
+        "inputs": {"SIZE": [1, [4, "100"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 896, "y": 303
+    },
+    "looks_changeeffectby": {
+        "opcode": "looks_changeeffectby", "next": None, "parent": None,
+        "inputs": {"CHANGE": [1, [4, "25"]]}, "fields": {"EFFECT": ["COLOR", None]}, "shadow": False, "topLevel": True,
+        "x": 892, "y": 416
+    },
+    "looks_seteffectto": {
+        "opcode": "looks_seteffectto", "next": None, "parent": None,
+        "inputs": {"VALUE": [1, [4, "0"]]}, "fields": {"EFFECT": ["COLOR", None]}, "shadow": False, "topLevel": True,
+        "x": 902, "y": 527
+    },
+    "looks_cleargraphiceffects": {
+        "opcode": "looks_cleargraphiceffects", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 902, "y": 638
+    },
+    "looks_show": {
+        "opcode": "looks_show", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 908, "y": 758
+    },
+    "looks_hide": {
+        "opcode": "looks_hide", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 455, "y": 861
+    },
+    "looks_gotofrontback": {
+        "opcode": "looks_gotofrontback", "next": None, "parent": None,
+        "inputs": {}, "fields": {"FRONT_BACK": ["front", None]}, "shadow": False, "topLevel": True,
+        "x": 853, "y": 878
+    },
+    "looks_goforwardbackwardlayers": {
+        "opcode": "looks_goforwardbackwardlayers", "next": None, "parent": None,
+        "inputs": {"NUM": [1, [7, "1"]]}, "fields": {"FORWARD_BACKWARD": ["forward", None]}, "shadow": False, "topLevel": True,
+        "x": 851, "y": 999
+    },
+    "looks_costumenumbername": {
+        "opcode": "looks_costumenumbername", "next": None, "parent": None,
+        "inputs": {}, "fields": {"NUMBER_NAME": ["number", None]}, "shadow": False, "topLevel": True,
+        "x": 458, "y": 1007
+    },
+    "looks_backdropnumbername": {
+        "opcode": "looks_backdropnumbername", "next": None, "parent": None,
+        "inputs": {}, "fields": {"NUMBER_NAME": ["number", None]}, "shadow": False, "topLevel": True,
+        "x": 1242, "y": 753
+    },
+    "looks_size": {
+        "opcode": "looks_size", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1249, "y": 876
+    },
+
+    # operator_block.json
+    "operator_add": {
+        "opcode": "operator_add", "next": None, "parent": None,
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 128, "y": 153
+    },
+    "operator_subtract": {
+        "opcode": "operator_subtract", "next": None, "parent": None,
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 134, "y": 214
+    },
+    "operator_multiply": {
+        "opcode": "operator_multiply", "next": None, "parent": None,
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 134, "y": 278
+    },
+    "operator_divide": {
+        "opcode": "operator_divide", "next": None, "parent": None,
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 138, "y": 359
+    },
+    "operator_random": {
+        "opcode": "operator_random", "next": None, "parent": None,
+        "inputs": {"FROM": [1, [4, "1"]], "TO": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 311, "y": 157
+    },
+    "operator_gt": {
+        "opcode": "operator_gt", "next": None, "parent": None,
+        "inputs": {"OPERAND1": [1, [10, ""]], "OPERAND2": [1, [10, "50"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 348, "y": 217
+    },
+    "operator_lt": {
+        "opcode": "operator_lt", "next": None, "parent": None,
+        "inputs": {"OPERAND1": [1, [10, ""]], "OPERAND2": [1, [10, "50"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 345, "y": 286
+    },
+    "operator_equals": {
+        "opcode": "operator_equals", "next": None, "parent": None,
+        "inputs": {"OPERAND1": [1, [10, ""]], "OPERAND2": [1, [10, "50"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 345, "y": 372
+    },
+    "operator_and": {
+        "opcode": "operator_and", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 701, "y": 158
+    },
+    "operator_or": {
+        "opcode": "operator_or", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 705, "y": 222
+    },
+    "operator_not": {
+        "opcode": "operator_not", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 734, "y": 283
+    },
+    "operator_join": {
+        "opcode": "operator_join", "next": None, "parent": None,
+        "inputs": {"STRING1": [1, [10, "apple "]], "STRING2": [1, [10, "banana"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 663, "y": 378
+    },
+    "operator_letter_of": {
+        "opcode": "operator_letter_of", "next": None, "parent": None,
+        "inputs": {"LETTER": [1, [6, "1"]], "STRING": [1, [10, "apple"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 664, "y": 445
+    },
+    "operator_length": {
+        "opcode": "operator_length", "next": None, "parent": None,
+        "inputs": {"STRING": [1, [10, "apple"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 664, "y": 521
+    },
+    "operator_contains": {
+        "opcode": "operator_contains", "next": None, "parent": None,
+        "inputs": {"STRING1": [1, [10, "apple"]], "STRING2": [1, [10, "a"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 634, "y": 599
+    },
+    "operator_mod": {
+        "opcode": "operator_mod", "next": None, "parent": None,
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 295, "y": 594
+    },
+    "operator_round": {
+        "opcode": "operator_round", "next": None, "parent": None,
+        "inputs": {"NUM": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 307, "y": 674
+    },
+    "operator_mathop": {
+        "opcode": "operator_mathop", "next": None, "parent": None,
+        "inputs": {"NUM": [1, [4, ""]]}, "fields": {"OPERATOR": ["abs", None]}, "shadow": False, "topLevel": True,
+        "x": 280, "y": 754
+    },
+
+    # sensing_block.json
+    "sensing_touchingobject": {
+        "opcode": "sensing_touchingobject", "next": None, "parent": None,
+        "inputs": {"TOUCHINGOBJECTMENU": [1, "sensing_touchingobjectmenu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 359, "y": 116
+    },
+    "sensing_touchingobjectmenu": {
+        "opcode": "sensing_touchingobjectmenu", "next": None, "parent": "sensing_touchingobject",
+        "inputs": {}, "fields": {"TOUCHINGOBJECTMENU": ["_mouse_", None]}, "shadow": True, "topLevel": False
+    },
+    "sensing_touchingcolor": {
+        "opcode": "sensing_touchingcolor", "next": None, "parent": None,
+        "inputs": {"COLOR": [1, [9, "#55b888"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 360, "y": 188
+    },
+    "sensing_coloristouchingcolor": {
+        "opcode": "sensing_coloristouchingcolor", "next": None, "parent": None,
+        "inputs": {"COLOR": [1, [9, "#d019f2"]], "COLOR2": [1, [9, "#2b0de3"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 348, "y": 277
+    },
+    "sensing_askandwait": {
+        "opcode": "sensing_askandwait", "next": None, "parent": None,
+        "inputs": {"QUESTION": [1, [10, "What's your name?"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 338, "y": 354
+    },
+    "sensing_answer": {
+        "opcode": "sensing_answer", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 782, "y": 111
+    },
+    "sensing_keypressed": {
+        "opcode": "sensing_keypressed", "next": None, "parent": None,
+        "inputs": {"KEY_OPTION": [1, "sensing_keyoptions"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 762, "y": 207
+    },
+    "sensing_keyoptions": {
+        "opcode": "sensing_keyoptions", "next": None, "parent": "sensing_keypressed",
+        "inputs": {}, "fields": {"KEY_OPTION": ["space", None]}, "shadow": True, "topLevel": False
+    },
+    "sensing_mousedown": {
+        "opcode": "sensing_mousedown", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 822, "y": 422
+    },
+    "sensing_mousex": {
+        "opcode": "sensing_mousex", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 302, "y": 528
+    },
+    "sensing_mousey": {
+        "opcode": "sensing_mousey", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 668, "y": 547
+    },
+    "sensing_setdragmode": {
+        "opcode": "sensing_setdragmode", "next": None, "parent": None,
+        "inputs": {}, "fields": {"DRAG_MODE": ["draggable", None]}, "shadow": False, "topLevel": True,
+        "x": 950, "y": 574
+    },
+    "sensing_loudness": {
+        "opcode": "sensing_loudness", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 658, "y": 703
+    },
+    "sensing_timer": {
+        "opcode": "sensing_timer", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 459, "y": 671
+    },
+    "sensing_resettimer": {
+        "opcode": "sensing_resettimer", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 462, "y": 781
+    },
+    "sensing_of": {
+        "opcode": "sensing_of", "next": None, "parent": None,
+        "inputs": {"OBJECT": [1, "sensing_of_object_menu"]}, "fields": {"PROPERTY": ["backdrop #", None]}, "shadow": False, "topLevel": True,
+        "x": 997, "y": 754
+    },
+    "sensing_of_object_menu": {
+        "opcode": "sensing_of_object_menu", "next": None, "parent": "sensing_of",
+        "inputs": {}, "fields": {"OBJECT": ["_stage_", None]}, "shadow": True, "topLevel": False
+    },
+    "sensing_current": {
+        "opcode": "sensing_current", "next": None, "parent": None,
+        "inputs": {}, "fields": {"CURRENTMENU": ["YEAR", None]}, "shadow": False, "topLevel": True,
+        "x": 627, "y": 884
+    },
+    "sensing_dayssince2000": {
+        "opcode": "sensing_dayssince2000", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 959, "y": 903
+    },
+    "sensing_username": {
+        "opcode": "sensing_username", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 833, "y": 757
+    },
+
+    # sound_block.json
+    "sound_playuntildone": {
+        "opcode": "sound_playuntildone", "next": None, "parent": None,
+        "inputs": {"SOUND_MENU": [1, "sound_sounds_menu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 253, "y": 17
+    },
+    "sound_sounds_menu": {
+        "opcode": "sound_sounds_menu", "next": None, "parent": "sound_playuntildone and sound_play",
+        "inputs": {}, "fields": {"SOUND_MENU": ["Meow", None]}, "shadow": True, "topLevel": False
+    },
+    "sound_play": {
+        "opcode": "sound_play", "next": None, "parent": None,
+        "inputs": {"SOUND_MENU": [1, "sound_sounds_menu"]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 245, "y": 122
+    },
+    "sound_stopallsounds": {
+        "opcode": "sound_stopallsounds", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 253, "y": 245
+    },
+    "sound_changeeffectby": {
+        "opcode": "sound_changeeffectby", "next": None, "parent": None,
+        "inputs": {"VALUE": [1, [4, "10"]]}, "fields": {"EFFECT": ["PITCH", None]}, "shadow": False, "topLevel": True,
+        "x": 653, "y": 14
+    },
+    "sound_seteffectto": {
+        "opcode": "sound_seteffectto", "next": None, "parent": None,
+        "inputs": {"VALUE": [1, [4, "100"]]}, "fields": {"EFFECT": ["PITCH", None]}, "shadow": False, "topLevel": True,
+        "x": 653, "y": 139
+    },
+    "sound_cleareffects": {
+        "opcode": "sound_cleareffects", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 651, "y": 242
+    },
+    "sound_changevolumeby": {
+        "opcode": "sound_changevolumeby", "next": None, "parent": None,
+        "inputs": {"VOLUME": [1, [4, "-10"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 645, "y": 353
+    },
+    "sound_setvolumeto": {
+        "opcode": "sound_setvolumeto", "next": None, "parent": None,
+        "inputs": {"VOLUME": [1, [4, "100"]]}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1108, "y": 5
+    },
+    "sound_volume": {
+        "opcode": "sound_volume", "next": None, "parent": None,
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True,
+        "x": 1136, "y": 123
+    },
+}
+
+# #Example input with opcodes from various categories
+# input_opcodes = [
+#     {"opcode": "sound_play", "count": 2},         # New: Sound block with menu
+#     {"opcode": "sound_playuntildone", "count": 2}, # New: Sound block with menu
+# ]
+
+# Example input with opcodes from various categories
+input_opcodes = [
+    {"opcode": "sound_play", "count": 2},
+    {"opcode": "sound_playuntildone", "count": 2},
+    {"opcode":"motion_goto","count":2},
+    {"opcode":"motion_glideto","count":2},
+    {"opcode":"looks_switchbackdropto","count":2},
+    {"opcode":"looks_switchcostumeto","count":2},
+    {"opcode":"control_create_clone_of","count":2},
+    {"opcode":"sensing_touchingobject","count":2},
+    {"opcode":"sensing_of","count":2},
+    {"opcode":"sensing_keypressed","count":2},
+    {"opcode":"motion_pointtowards","count":2},
+]
+
+generated_output = generate_blocks_from_opcodes(input_opcodes, all_block_definitions)
+print(json.dumps(generated_output, indent=2))

utils/generated_output_json.json

@@ -0,0 +1,164 @@
+{
+  "event_whenflagclicked_1": {
+    "block_name": "when green flag pressed",
+    "block_type": "Events",
+    "op_code": "event_whenflagclicked",
+    "block_shape": "Hat Block",
+    "functionality": "This Hat block initiates the script when the green flag is clicked, serving as the common starting point for most Scratch projects.",
+    "inputs": {},
+    "fields": {},
+    "shadow": false,
+    "topLevel": true,
+    "parent": null,
+    "next": null
+  },
+  "data_setvariableto_1": {
+    "block_name": "set [my variable v] to ()",
+    "block_type": "Data",
+    "block_shape": "Stack Block",
+    "op_code": "data_setvariableto",
+    "functionality": "Assigns a specific value (number, string, or boolean) to a variable.",
+    "inputs": {
+      "VALUE": [
+        1,
+        [
+          10,
+          "0"
+        ]
+      ]
+    },
+    "fields": {
+      "VARIABLE": [
+        "my variable",
+        "`jEk@4|i[#Fk?(8x)AV.-my variable"
+      ]
+    },
+    "shadow": false,
+    "topLevel": true,
+    "parent": null,
+    "next": null
+  },
+  "data_setvariableto_2": {
+    "block_name": "set [my variable v] to ()",
+    "block_type": "Data",
+    "block_shape": "Stack Block",
+    "op_code": "data_setvariableto",
+    "functionality": "Assigns a specific value (number, string, or boolean) to a variable.",
+    "inputs": {
+      "VALUE": [
+        1,
+        [
+          10,
+          "0"
+        ]
+      ]
+    },
+    "fields": {
+      "VARIABLE": [
+        "my variable",
+        "`jEk@4|i[#Fk?(8x)AV.-my variable"
+      ]
+    },
+    "shadow": false,
+    "topLevel": true,
+    "parent": null,
+    "next": null
+  },
+  "control_forever_1": {
+    "block_name": "forever",
+    "block_type": "Control",
+    "block_shape": "C-Block",
+    "op_code": "control_forever",
+    "functionality": "Continuously runs the blocks inside it.",
+    "inputs": {
+      "SUBSTACK": [
+        2,
+        null
+      ]
+    },
+    "fields": {},
+    "shadow": false,
+    "topLevel": true,
+    "parent": null,
+    "next": null
+  },
+  "control_if_1": {
+    "block_name": "if <> then",
+    "block_type": "Control",
+    "block_shape": "C-Block",
+    "op_code": "control_if",
+    "functionality": "Executes the blocks inside it only if the specified boolean condition is true. [NOTE: it takes boolean blocks as input]",
+    "inputs": {
+      "CONDITION": [
+        2,
+        null
+      ],
+      "SUBSTACK": [
+        2,
+        null
+      ]
+    },
+    "fields": {},
+    "shadow": false,
+    "topLevel": true,
+    "parent": null,
+    "next": null
+  },
+  "control_wait_1": {
+    "block_name": "wait () seconds",
+    "block_type": "Control",
+    "block_shape": "Stack Block",
+    "op_code": "control_wait",
+    "functionality": "Pauses the script for a specified duration.",
+    "inputs": {
+      "DURATION": [
+        1,
+        [
+          5,
+          "1"
+        ]
+      ]
+    },
+    "fields": {},
+    "shadow": false,
+    "topLevel": true,
+    "parent": null,
+    "next": null
+  },
+  "sensing_touchingobject_1": {
+    "block_name": "<touching [edge v]?>",
+    "block_type": "Sensing",
+    "op_code": "sensing_touchingobject",
+    "block_shape": "Boolean Block",
+    "functionality": "Checks if its sprite is touching the mouse-pointer, edge, or another specified sprite.",
+    "inputs": {
+      "TOUCHINGOBJECTMENU": [
+        1,
+        "sensing_touchingobjectmenu_1"
+      ]
+    },
+    "fields": {},
+    "shadow": false,
+    "topLevel": true,
+    "parent": null,
+    "next": null
+  },
+  "sensing_touchingobjectmenu_1": {
+    "block_name": "touching object menu",
+    "block_type": "Sensing",
+    "block_shape": "Reporter Block",
+    "op_code": "sensing_touchingobjectmenu",
+    "functionality": "Menu for touching object block.",
+    "inputs": {},
+    "fields": {
+      "TOUCHINGOBJECTMENU": [
+        "_mouse_",
+        null
+      ]
+    },
+    "shadow": true,
+    "topLevel": false,
+    "next": null,
+    "parent": "sensing_touchingobject_1"
+  }
+}

utils/opcode_counter.py

@@ -0,0 +1,228 @@
+import json
+import re
+from typing import Any, Dict
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Dummy data for demonstration. You should replace this with your actual opcode data.
+# Each item should have at least an 'opcode' and 'text' field.
+hat_block_data = [
+    {"opcode": "event_whenflagclicked", "text": "when green flag clicked"},
+    {"opcode": "event_whenkeypressed", "text": "when [key] pressed"},
+    {"opcode": "event_whenbroadcastreceived", "text": "when I receive [message]"},
+]
+boolean_block_data = [
+    {"opcode": "operator_gt", "text": "< ( ) > ( ) >"},
+    {"opcode": "sensing_touchingobject", "text": "<touching [object]?>"},
+    {"opcode": "operator_equals", "text": "< ( ) = ( ) >"},
+]
+c_block_data = [
+    {"opcode": "control_forever", "text": "forever"},
+    {"opcode": "control_if", "text": "if < > then"},
+    {"opcode": "control_repeat", "text": "repeat ( )"},
+]
+cap_block_data = [
+    {"opcode": "control_stop", "text": "stop [all]"},
+]
+reporter_block_data = [
+    {"opcode": "motion_xposition", "text": "(x position)"},
+    {"opcode": "motion_yposition", "text": "(y position)"},
+    {"opcode": "data_variable", "text": "(variable)"},
+    {"opcode": "sensing_answer", "text": "(answer)"},
+]
+stack_block_data = [
+    {"opcode": "motion_gotoxy", "text": "go to x: ( ) y: ( )"},
+    {"opcode": "motion_changeyby", "text": "change y by ( )"},
+    {"opcode": "motion_setx", "text": "set x to ( )"},
+    {"opcode": "motion_glidesecstoxy", "text": "glide ( ) secs to x: ( ) y: ( )"},
+    {"opcode": "data_setvariableto", "text": "set [variable] to ( )"},
+    {"opcode": "looks_hide", "text": "hide"},
+    {"opcode": "looks_show", "text": "show"},
+    {"opcode": "event_broadcast", "text": "broadcast [message]"},
+]
+
+# Combine all block data into a single list for easier lookup
+all_opcodes_list = []
+for category_data in [
+    hat_block_data,
+    boolean_block_data,
+    c_block_data,
+    cap_block_data,
+    reporter_block_data,
+    stack_block_data,
+]:
+    all_opcodes_list.extend(category_data)
+
+
+def extract_json_from_llm_response(response_text: str) -> Dict[str, Any]:
+    """Extracts JSON from an LLM response string."""
+    try:
+        json_match = re.search(r"```json\n(.*)\n```", response_text, re.DOTALL)
+        if json_match:
+            return json.loads(json_match.group(1))
+        return json.loads(response_text) # Try parsing directly if no code block
+    except json.JSONDecodeError as e:
+        logger.error(f"Failed to decode JSON: {e} from response: {response_text}")
+        raise
+
+# Node 9:plan with exact count of the opcode used per logic
+def plan_opcode_counter_node(state: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    For each plan in state["action_plan"]["action_overall_flow"], calls the LLM agent
+    to analyze the `logic` string and return a list of {opcode, count} for each category.
+    """
+    logger.info("=== Running OPCODE COUTER LOGIC with LLM counts ===")
+    game_description = state.get("description", "No game description provided.")
+    sprite_name = {target["name"]: target["name"] for target in state["project_json"]["targets"]} # Adjusted for direct use
+    
+    action_flow = state.get("action_plan", {}).get("action_overall_flow", {})
+    if not action_flow:
+        logger.warning("No action_overall_flow found; skipping.")
+        return state
+
+    # Prepare block reference strings for the prompt
+    hat_description = "Blocks that start a script when an event happens."
+    hat_opcodes_functionalities = "\n".join([f"- {block['opcode']}: {block['text']}" for block in hat_block_data])
+
+    boolean_description = "Blocks that report a true or false value and fit into hexagonal inputs."
+    boolean_opcodes_functionalities = "\n".join([f"- {block['opcode']}: {block['text']}" for block in boolean_block_data])
+
+    c_description = "Blocks that run scripts inside them repeatedly or conditionally."
+    c_opcodes_functionalities = "\n".join([f"- {block['opcode']}: {block['text']}" for block in c_block_data])
+
+    cap_description = "Blocks that end a script."
+    cap_opcodes_functionalities = "\n".join([f"- {block['opcode']}: {block['text']}" for block in cap_block_data])
+
+    reporter_description = "Blocks that report a value (number or string) and fit into rounded inputs."
+    reporter_opcodes_functionalities = "\n".join([f"- {block['opcode']}: {block['text']}" for block in reporter_block_data])
+
+    stack_description = "Blocks that perform a main action in a script."
+    stack_opcodes_functionalities = "\n".join([f"- {block['opcode']}: {block['text']}" for block in stack_block_data])
+
+    refined_flow: Dict[str, Any] = {}
+    for sprite, sprite_data in action_flow.items(): # Use .items() for direct iteration
+        refined_plans = []
+        for plan in sprite_data.get("plans", []):
+            logic = plan.get("logic", "")
+            event = plan.get("event", "")
+            
+            # This is where the core change for counting opcodes will happen.
+            # We will use the 'logic' string to determine the actual opcodes and their counts.
+            opcode_counts = {
+                "motion": [],
+                "control": [],
+                "operator": [],
+                "sensing": [],
+                "looks": [],
+                "sounds": [],
+                "events": [],
+                "data": [],
+            }
+            
+            # Initialize a dictionary to hold counts for each opcode
+            temp_opcode_counts = {}
+
+            # Add the event block explicitly
+            if event:
+                event_opcode = event.replace('v', '').strip() # Clean the event string
+                temp_opcode_counts[event_opcode] = temp_opcode_counts.get(event_opcode, 0) + 1
+
+
+            # Iterate through all known opcodes and check if their 'text' appears in the logic
+            for block_info in all_opcodes_list:
+                opcode = block_info["opcode"]
+                # Use a more robust regex for matching, accounting for variable names or block inputs
+                # We need to be careful with common words that are also part of opcodes, e.g., "if"
+                # A more robust solution might involve parsing the Scratch-like logic more deeply.
+                # For now, let's try to match the "text" from the block definition.
+                # Escape special characters in the block text for regex
+                block_text_escaped = re.escape(block_info["text"])
+                
+                # Replace placeholders like [key], [object], ( ) with regex wildcards
+                block_text_pattern = block_text_escaped.replace(r"\[key\]", r".*?").replace(r"\[message\]", r".*?").replace(r"\[object\]", r".*?").replace(r"\( \)", r".*?")
+                block_text_pattern = block_text_pattern.replace(r"\[variable\]", r".*?")
+                
+                # For blocks that might have variations in text (e.g., if-then, if-then-else)
+                if opcode == "control_if":
+                    if_regex = r"if <.+?> then"
+                    if_else_regex = r"if <.+?> then\n.*else"
+                    
+                    if re.search(if_else_regex, logic, re.DOTALL):
+                        temp_opcode_counts["control_if_else"] = temp_opcode_counts.get("control_if_else", 0) + 1
+                    elif re.search(if_regex, logic, re.DOTALL):
+                        temp_opcode_counts["control_if"] = temp_opcode_counts.get("control_if", 0) + 1
+                    continue # Skip general matching for control_if
+
+                if opcode == "control_forever" and "forever" in logic:
+                    temp_opcode_counts[opcode] = temp_opcode_counts.get(opcode, 0) + 1
+                    continue # Skip general matching
+
+                # General regex match for other blocks
+                # We need to make sure we're not just matching substrings of other blocks
+                # A simple word boundary or line-by-line check might be better
+                # For now, a simple count of occurrences of the "text" within the logic
+                # will be used, but this is a simplification.
+                count = len(re.findall(block_text_pattern, logic))
+                if count > 0:
+                    temp_opcode_counts[opcode] = temp_opcode_counts.get(opcode, 0) + count
+
+            # Fill the opcode_counts for each category based on temp_opcode_counts
+            def add_to_category(category_list, opcode_name, count):
+                if count > 0:
+                    category_list.append({"opcode": opcode_name, "count": count})
+
+            for opcode, count in temp_opcode_counts.items():
+                if opcode.startswith("motion_"):
+                    add_to_category(opcode_counts["motion"], opcode, count)
+                elif opcode.startswith("control_"):
+                    add_to_category(opcode_counts["control"], opcode, count)
+                elif opcode.startswith("operator_"):
+                    add_to_category(opcode_counts["operator"], opcode, count)
+                elif opcode.startswith("sensing_"):
+                    add_to_category(opcode_counts["sensing"], opcode, count)
+                elif opcode.startswith("looks_"):
+                    add_to_category(opcode_counts["looks"], opcode, count)
+                elif opcode.startswith("sounds_"):
+                    add_to_category(opcode_counts["sounds"], opcode, count)
+                elif opcode.startswith("event_"):
+                    add_to_category(opcode_counts["events"], opcode, count)
+                elif opcode.startswith("data_"):
+                    add_to_category(opcode_counts["data"], opcode, count)
+
+            # Assign the new opcode_counts to the plan
+            plan["opcode_counts"] = opcode_counts
+            
+            # The original plan structure also had categories as direct keys.
+            # You can choose to keep this or remove it, depending on your downstream needs.
+            # If you want to keep it, you'd populate them based on opcode_counts.
+            # For simplicity, let's keep the new 'opcode_counts' key as requested.
+            
+            # Clear previous lists if you are relying solely on 'opcode_counts'
+            plan["motion"] = []
+            plan["control"] = []
+            plan["operator"] = []
+            plan["sensing"] = []
+            plan["looks"] = []
+            plan["sounds"] = []
+            plan["events"] = []
+            plan["data"] = []
+
+            # Populate the individual lists based on the newly calculated opcode_counts if needed
+            for category, opcodes_list in opcode_counts.items():
+                for item in opcodes_list:
+                    # Append just the opcode string to the category list
+                    plan[category].extend([item['opcode']] * item['count'])
+
+
+            refined_plans.append(plan)
+
+        refined_flow[sprite] = {
+            "description": sprite_data.get("description", ""),
+            "plans": refined_plans
+        }
+        
+    state["temporary_node"] = refined_flow
+    print(f"[OPCODE COUTER LOGIC]: {refined_flow}")
+    logger.info("=== OPCODE COUTER LOGIC completed ===")
+    return state

utils/opcode_occurrence.py

@@ -0,0 +1,981 @@
+import json
+import copy
+import re
+import re
+from collections import defaultdict
+#from opcode_occurrence import generated_output_json
+
+
+def generate_blocks_from_opcodes(opcode_counts, all_block_definitions):
+    """
+    Generates a dictionary of Scratch-like blocks based on a list of opcodes and a reference block definition,
+    and groups all generated block keys by their corresponding opcode.
+
+    Returns:
+        tuple: (generated_blocks, opcode_to_keys)
+            - generated_blocks: dict of block_key -> block_data
+            - opcode_to_keys: dict of opcode -> list of block_keys
+    """
+    generated_blocks = {}
+    opcode_counts_map = {}  # For counting unique suffix per opcode
+    opcode_to_keys = {}     # For grouping block keys by opcode
+
+    explicit_menu_links = {
+        "motion_goto": [("TO", "motion_goto_menu")],
+        "motion_glideto": [("TO", "motion_glideto_menu")],
+        "motion_pointtowards": [("TOWARDS", "motion_pointtowards_menu")],
+        "sensing_keypressed": [("KEY_OPTION", "sensing_keyoptions")],
+        "sensing_of": [("OBJECT", "sensing_of_object_menu")],
+        "sensing_touchingobject": [("TOUCHINGOBJECTMENU", "sensing_touchingobjectmenu")],
+        "control_create_clone_of": [("CLONE_OPTION", "control_create_clone_of_menu")],
+        "sound_play": [("SOUND_MENU", "sound_sounds_menu")],
+        "sound_playuntildone": [("SOUND_MENU", "sound_sounds_menu")],
+        "looks_switchcostumeto": [("COSTUME", "looks_costume")],
+        "looks_switchbackdropto": [("BACKDROP", "looks_backdrops")],
+    }
+
+    for item in opcode_counts:
+        opcode = item.get("opcode")
+        count = item.get("count", 1)
+
+        if opcode == "sensing_istouching":
+            opcode = "sensing_touchingobject"
+
+        if not opcode or opcode not in all_block_definitions:
+            print(f"Warning: Skipping opcode '{opcode}' (missing or not in definitions).")
+            continue
+
+        for _ in range(count):
+            # Count occurrences per opcode for unique key generation
+            opcode_counts_map[opcode] = opcode_counts_map.get(opcode, 0) + 1
+            instance_num = opcode_counts_map[opcode]
+            main_key = f"{opcode}_{instance_num}"
+
+            # Track the generated key
+            opcode_to_keys.setdefault(opcode, []).append(main_key)
+
+            main_block_data = copy.deepcopy(all_block_definitions[opcode])
+            main_block_data["parent"] = None
+            main_block_data["next"] = None
+            main_block_data["topLevel"] = True
+            main_block_data["shadow"] = False
+
+            generated_blocks[main_key] = main_block_data
+
+            # Handle menus
+            if opcode in explicit_menu_links:
+                for input_name, menu_opcode in explicit_menu_links[opcode]:
+                    if menu_opcode not in all_block_definitions:
+                        continue
+
+                    opcode_counts_map[menu_opcode] = opcode_counts_map.get(menu_opcode, 0) + 1
+                    menu_instance_num = opcode_counts_map[menu_opcode]
+                    menu_key = f"{menu_opcode}_{menu_instance_num}"
+
+                    opcode_to_keys.setdefault(menu_opcode, []).append(menu_key)
+
+                    menu_block_data = copy.deepcopy(all_block_definitions[menu_opcode])
+                    menu_block_data["shadow"] = True
+                    menu_block_data["topLevel"] = False
+                    menu_block_data["next"] = None
+                    menu_block_data["parent"] = main_key
+
+                    if input_name in main_block_data.get("inputs", {}) and \
+                       isinstance(main_block_data["inputs"][input_name], list) and \
+                       len(main_block_data["inputs"][input_name]) > 1 and \
+                       main_block_data["inputs"][input_name][0] == 1:
+
+                        main_block_data["inputs"][input_name][1] = menu_key
+
+                    generated_blocks[menu_key] = menu_block_data
+
+    return generated_blocks, opcode_to_keys
+
+all_block_definitions = {
+    # motion_block.json
+    "motion_movesteps": {
+        "block_name": "move () steps", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_movesteps",
+        "functionality": "Moves the sprite forward by the specified number of steps in the direction it is currently facing. A positive value moves it forward, and a negative value moves it backward.",
+        "inputs": {"STEPS": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_turnright": {
+        "block_name": "turn right () degrees", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_turnright",
+        "functionality": "Turns the sprite clockwise by the specified number of degrees.",
+        "inputs": {"DEGREES": [1, [4, "15"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_turnleft": {
+        "block_name": "turn left () degrees", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_turnleft",
+        "functionality": "Turns the sprite counter-clockwise by the specified number of degrees.",
+        "inputs": {"DEGREES": [1, [4, "15"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_goto": {
+        "block_name": "go to ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_goto",
+        "functionality": "Moves the sprite to a specified location, which can be a random position or at the mouse pointer or another to the sprite.",
+        "inputs": {"TO": [1, "motion_goto_menu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_goto_menu": {
+        "block_name": "go to menu", "block_type": "Motion", "block_shape": "Reporter Block", "op_code": "motion_goto_menu",
+        "functionality": "Menu for go to block.",
+        "inputs": {}, "fields": {"TO": ["_random_", None]}, "shadow": True, "topLevel": False
+    },
+    "motion_gotoxy": {
+        "block_name": "go to x: () y: ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_gotoxy",
+        "functionality": "Moves the sprite to the specified X and Y coordinates on the stage.",
+        "inputs": {"X": [1, [4, "0"]], "Y": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_glideto": {
+        "block_name": "glide () secs to ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_glideto",
+        "functionality": "Glides the sprite smoothly to a specified location (random position, mouse pointer, or another sprite) over a given number of seconds.",
+        "inputs": {"SECS": [1, [4, "1"]], "TO": [1, "motion_glideto_menu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_glideto_menu": {
+        "block_name": "glide to menu", "block_type": "Motion", "block_shape": "Reporter Block", "op_code": "motion_glideto_menu",
+        "functionality": "Menu for glide to block.",
+        "inputs": {}, "fields": {"TO": ["_random_", None]}, "shadow": True, "topLevel": False
+    },
+    "motion_glidesecstoxy": {
+        "block_name": "glide () secs to x: () y: ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_glidesecstoxy",
+        "functionality": "Glides the sprite smoothly to the specified X and Y coordinates over a given number of seconds.",
+        "inputs": {"SECS": [1, [4, "1"]], "X": [1, [4, "0"]], "Y": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_pointindirection": {
+        "block_name": "point in direction ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_pointindirection",
+        "functionality": "Sets the sprite's direction to a specified angle in degrees (0 = up, 90 = right, 180 = down, -90 = left).",
+        "inputs": {"DIRECTION": [1, [8, "90"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_pointtowards": {
+        "block_name": "point towards ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_pointtowards",
+        "functionality": "Points the sprite towards the mouse pointer or another specified sprite.",
+        "inputs": {"TOWARDS": [1, "motion_pointtowards_menu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_pointtowards_menu": {
+        "block_name": "point towards menu", "block_type": "Motion", "block_shape": "Reporter Block", "op_code": "motion_pointtowards_menu",
+        "functionality": "Menu for point towards block.",
+        "inputs": {}, "fields": {"TOWARDS": ["_mouse_", None]}, "shadow": True, "topLevel": False
+    },
+    "motion_changexby": {
+        "block_name": "change x by ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_changexby",
+        "functionality": "Changes the sprite's X-coordinate by the specified amount, moving it horizontally.",
+        "inputs": {"DX": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_setx": {
+        "block_name": "set x to ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_setx",
+        "functionality": "Sets the sprite's X-coordinate to a specific value, placing it at a precise horizontal position.",
+        "inputs": {"X": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_changeyby": {
+        "block_name": "change y by ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_changeyby",
+        "functionality": "Changes the sprite's Y-coordinate by the specified amount, moving it vertically.",
+        "inputs": {"DY": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_sety": {
+        "block_name": "set y to ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_sety",
+        "functionality": "Sets the sprite's Y-coordinate to a specific value, placing it at a precise vertical position.",
+        "inputs": {"Y": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_ifonedgebounce": {
+        "block_name": "if on edge, bounce", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_ifonedgebounce",
+        "functionality": "Reverses the sprite's direction if it touches the edge of the stage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_setrotationstyle": {
+        "block_name": "set rotation style ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_setrotationstyle",
+        "functionality": "Determines how the sprite rotates: 'left-right' (flips horizontally), 'don't rotate' (stays facing one direction), or 'all around' (rotates freely).",
+        "inputs": {}, "fields": {"STYLE": ["left-right", None]}, "shadow": False, "topLevel": True
+    },
+    "motion_xposition": {
+        "block_name": "(x position)", "block_type": "Motion", "block_shape": "Reporter Block", "op_code": "motion_xposition",
+        "functionality": "Reports the current X-coordinate of the sprite.[NOTE: not used in stage/backdrops]",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_yposition": {
+        "block_name": "(y position)", "block_type": "Motion", "block_shape": "Reporter Block", "op_code": "motion_yposition",
+        "functionality": "Reports the current Y coordinate of the sprite on the stage.[NOTE: not used in stage/backdrops]",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_direction": {
+        "block_name": "(direction)", "block_type": "Motion", "block_shape": "Reporter Block", "op_code": "motion_direction",
+        "functionality": "Reports the current direction of the sprite in degrees (0 = up, 90 = right, 180 = down, -90 = left).[NOTE: not used in stage/backdrops]",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+
+    # control_block.json
+    "control_wait": {
+        "block_name": "wait () seconds", "block_type": "Control", "block_shape": "Stack Block", "op_code": "control_wait",
+        "functionality": "Pauses the script for a specified duration.",
+        "inputs": {"DURATION": [1, [5, "1"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_repeat": {
+        "block_name": "repeat ()", "block_type": "Control", "block_shape": "C-Block", "op_code": "control_repeat",
+        "functionality": "Repeats the blocks inside it a specified number of times.",
+        "inputs": {"TIMES": [1, [6, "10"]], "SUBSTACK": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_forever": {
+        "block_name": "forever", "block_type": "Control", "block_shape": "C-Block", "op_code": "control_forever",
+        "functionality": "Continuously runs the blocks inside it.",
+        "inputs": {"SUBSTACK": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_if": {
+        "block_name": "if <> then", "block_type": "Control", "block_shape": "C-Block", "op_code": "control_if",
+        "functionality": "Executes the blocks inside it only if the specified boolean condition is true. [NOTE: it takes boolean blocks as input]",
+        "inputs": {"CONDITION": [2, None], "SUBSTACK": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_if_else": {
+        "block_name": "if <> then else", "block_type": "Control", "block_shape": "C-Block", "op_code": "control_if_else",
+        "functionality": "Executes one set of blocks if the specified boolean condition is true, and a different set of blocks if the condition is false. [NOTE: it takes boolean blocks as input]",
+        "inputs": {"CONDITION": [2, None], "SUBSTACK": [2, None], "SUBSTACK2": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_wait_until": {
+        "block_name": "wait until <>", "block_type": "Control", "block_shape": "Stack Block", "op_code": "control_wait_until",
+        "functionality": "Pauses the script until the specified boolean condition becomes true. [NOTE: it takes boolean blocks as input]",
+        "inputs": {"CONDITION": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_repeat_until": {
+        "block_name": "repeat until <>", "block_type": "Control", "block_shape": "C-Block", "op_code": "control_repeat_until",
+        "functionality": "Repeats the blocks inside it until the specified boolean condition becomes true. [NOTE: it takes boolean blocks as input]",
+        "inputs": {"CONDITION": [2, None], "SUBSTACK": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_stop": {
+        "block_name": "stop [v]", "block_type": "Control", "block_shape": "Cap Block", "op_code": "control_stop",
+        "functionality": "Halts all scripts, only the current script, or other scripts within the same sprite. Its shape can dynamically change based on the selected option.",
+        "inputs": {}, "fields": {"STOP_OPTION": ["all", None]}, "shadow": False, "topLevel": True, "mutation": {"tagName": "mutation", "children": [], "hasnext": "false"}
+    },
+    "control_start_as_clone": {
+        "block_name": "When I Start as a Clone", "block_type": "Control", "block_shape": "Hat Block", "op_code": "control_start_as_clone",
+        "functionality": "This Hat block initiates the script when a clone of the sprite is created. It defines the behavior of individual clones.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_create_clone_of": {
+        "block_name": "create clone of ()", "block_type": "Control", "block_shape": "Stack Block", "op_code": "control_create_clone_of",
+        "functionality": "Generates a copy, or clone, of a specified sprite (or 'myself' for the current sprite).",
+        "inputs": {"CLONE_OPTION": [1, "control_create_clone_of_menu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_create_clone_of_menu": {
+        "block_name": "create clone of menu", "block_type": "Control", "block_shape": "Reporter Block", "op_code": "control_create_clone_of_menu",
+        "functionality": "Menu for create clone of block.",
+        "inputs": {}, "fields": {"CLONE_OPTION": ["_myself_", None]}, "shadow": True, "topLevel": False
+    },
+    "control_delete_this_clone": {
+        "block_name": "delete this clone", "block_type": "Control", "block_shape": "Cap Block", "op_code": "control_delete_this_clone",
+        "functionality": "Removes the clone that is executing it from the stage.",
+        "inputs":None, "fields": {}, "shadow": False, "topLevel": True
+    },
+
+    # data_block.json
+    "data_setvariableto": {
+        "block_name": "set [my variable v] to ()", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_setvariableto",
+        "functionality": "Assigns a specific value (number, string, or boolean) to a variable.",
+        "inputs": {"VALUE": [1, [10, "0"]]}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True
+    },
+    "data_changevariableby": {
+        "block_name": "change [my variable v] by ()", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_changevariableby",
+        "functionality": "Increases or decreases a variable's numerical value by a specified amount.",
+        "inputs": {"VALUE": [1, [4, "1"]]}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True
+    },
+    "data_showvariable": {
+        "block_name": "show variable [my variable v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_showvariable",
+        "functionality": "Makes a variable's monitor visible on the stage.",
+        "inputs": {}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True
+    },
+    "data_hidevariable": {
+        "block_name": "hide variable [my variable v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_hidevariable",
+        "functionality": "Hides a variable's monitor from the stage.",
+        "inputs": {}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True
+    },
+    "data_addtolist": {
+        "block_name": "add () to [my list v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_addtolist",
+        "functionality": "Appends an item to the end of a list.",
+        "inputs": {"ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_deleteoflist": {
+        "block_name": "delete () of [my list v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_deleteoflist",
+        "functionality": "Removes an item from a list by its index or by selecting 'all' items.",
+        "inputs": {"INDEX": [1, [7, "1"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_deletealloflist": {
+        "block_name": "delete all of [my list v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_deletealloflist",
+        "functionality": "Removes all items from a list.",
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_insertatlist": {
+        "block_name": "insert () at () of [my list v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_insertatlist",
+        "functionality": "Inserts an item at a specific position within a list.",
+        "inputs": {"ITEM": [1, [10, "thing"]], "INDEX": [1, [7, "1"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_replaceitemoflist": {
+        "block_name": "replace item () of [my list v] with ()", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_replaceitemoflist",
+        "functionality": "Replaces an item at a specific position in a list with a new value.",
+        "inputs": {"INDEX": [1, [7, "1"]], "ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_itemoflist": {
+        "block_name": "(item (2) of [myList v])", "block_type": "Data", "block_shape": "Reporter Block", "op_code": "data_itemoflist",
+        "functionality": "Reports the item located at a specific position in a list.",
+        "inputs": {"INDEX": [1, [7, "1"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_itemnumoflist": {
+        "block_name": "(item # of [Dog] in [myList v])", "block_type": "Data", "block_shape": "Reporter Block", "op_code": "data_itemnumoflist",
+        "functionality": "Reports the index number of the first occurrence of a specified item in a list. If the item is not found, it reports 0.",
+        "inputs": {"ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_lengthoflist": {
+        "block_name": "(length of [myList v])", "block_type": "Data", "block_shape": "Reporter Block", "op_code": "data_lengthoflist",
+        "functionality": "Provides the total number of items contained in a list.",
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_listcontainsitem": {
+        "block_name": "<[my list v] contains ()?>", "block_type": "Data", "block_shape": "Boolean Block", "op_code": "data_listcontainsitem",
+        "functionality": "Checks if a list includes a specific item.",
+        "inputs": {"ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_showlist": {
+        "block_name": "show list [my list v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_showlist",
+        "functionality": "Makes a list's monitor visible on the stage.",
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_hidelist": {
+        "block_name": "hide list [my list v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_hidelist",
+        "functionality": "Hides a list's monitor from the stage.",
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_variable": { # This is a reporter block for a variable's value
+        "block_name": "[variable v]", "block_type": "Data", "block_shape": "Reporter Block", "op_code": "data_variable",
+        "functionality": "Provides the current value stored in a variable.",
+        "inputs": {}, "fields": {"VARIABLE": ["my variable", None]}, "shadow": True, "topLevel": False
+    },
+
+    # event_block.json
+    "event_whenflagclicked": {
+        "block_name": "when green flag pressed", "block_type": "Events", "op_code": "event_whenflagclicked", "block_shape": "Hat Block",
+        "functionality": "This Hat block initiates the script when the green flag is clicked, serving as the common starting point for most Scratch projects.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "event_whenkeypressed": {
+        "block_name": "when () key pressed", "block_type": "Events", "op_code": "event_whenkeypressed", "block_shape": "Hat Block",
+        "functionality": "This Hat block initiates the script when a specified keyboard key is pressed.",
+        "inputs": {}, "fields": {"KEY_OPTION": ["space", None]}, "shadow": False, "topLevel": True
+    },
+    "event_whenthisspriteclicked": {
+        "block_name": "when this sprite clicked", "block_type": "Events", "op_code": "event_whenthisspriteclicked", "block_shape": "Hat Block",
+        "functionality": "This Hat block starts the script when the sprite itself is clicked.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "event_whenbackdropswitchesto": {
+        "block_name": "when backdrop switches to ()", "block_type": "Events", "op_code": "event_whenbackdropswitchesto", "block_shape": "Hat Block",
+        "functionality": "This Hat block triggers the script when the stage backdrop changes to a specified backdrop.",
+        "inputs": {}, "fields": {"BACKDROP": ["backdrop1", None]}, "shadow": False, "topLevel": True
+    },
+    "event_whengreaterthan": {
+        "block_name": "when () > ()", "block_type": "Events", "op_code": "event_whengreaterthan", "block_shape": "Hat Block",
+        "functionality": "This Hat block starts the script when a certain value (e.g., loudness from a microphone, or the timer) exceeds a defined threshold.",
+        "inputs": {"VALUE": [1, [4, "10"]]}, "fields": {"WHENGREATERTHANMENU": ["LOUDNESS", None]}, "shadow": False, "topLevel": True
+    },
+    "event_whenbroadcastreceived": {
+        "block_name": "when I receive ()", "block_type": "Events", "op_code": "event_whenbroadcastreceived", "block_shape": "Hat Block",
+        "functionality": "This Hat block initiates the script upon the reception of a specific broadcast message. This mechanism facilitates indirect communication between sprites or the stage.",
+        "inputs": {}, "fields": {"BROADCAST_OPTION": ["message1", "5O!nei;S$!c!=hCT}0:a"]}, "shadow": False, "topLevel": True
+    },
+    "event_broadcast": {
+        "block_name": "broadcast ()", "block_type": "Events", "block_shape": "Stack Block", "op_code": "event_broadcast",
+        "functionality": "Sends a broadcast message throughout the Scratch program, activating any 'when I receive ()' blocks that are set to listen for that message, enabling indirect communication.",
+        "inputs": {"BROADCAST_INPUT": [1, [11, "message1", "5O!nei;S$!c!=hCT}0:a"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "event_broadcastandwait": {
+        "block_name": "broadcast () and wait", "block_type": "Events", "block_shape": "Stack Block", "op_code": "event_broadcastandwait",
+        "functionality": "Sends a broadcast message and pauses the current script until all other scripts activated by that broadcast have completed their execution, ensuring sequential coordination.",
+        "inputs": {"BROADCAST_INPUT": [1, [11, "message1", "5O!nei;S$!c!=hCT}0:a"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+
+    # looks_block.json
+    "looks_sayforsecs": {
+        "block_name": "say () for () seconds", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_sayforsecs",
+        "functionality": "Displays a speech bubble containing specified text for a set duration.",
+        "inputs": {"MESSAGE": [1, [10, "Hello!"]], "SECS": [1, [4, "2"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_say": {
+        "block_name": "say ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_say",
+        "functionality": "Displays a speech bubble with the specified text indefinitely until another 'say' or 'think' block is activated.",
+        "inputs": {"MESSAGE": [1, [10, "Hello!"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_thinkforsecs": {
+        "block_name": "think () for () seconds", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_thinkforsecs",
+        "functionality": "Displays a thought bubble containing specified text for a set duration.",
+        "inputs": {"MESSAGE": [1, [10, "Hmm..."]], "SECS": [1, [4, "2"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_think": {
+        "block_name": "think ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_think",
+        "functionality": "Displays a thought bubble with the specified text indefinitely until another 'say' or 'think' block is activated.",
+        "inputs": {"MESSAGE": [1, [10, "Hmm..."]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_switchcostumeto": {
+        "block_name": "switch costume to ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_switchcostumeto",
+        "functionality": "Alters the sprite's appearance to a designated costume.",
+        "inputs": {"COSTUME": [1, "looks_costume"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_costume": {
+        "block_name": "costume menu", "block_type": "Looks", "block_shape": "Reporter Block", "op_code": "looks_costume",
+        "functionality": "Menu for switch costume to block.",
+        "inputs": {}, "fields": {"COSTUME": ["costume1", None]}, "shadow": True, "topLevel": False
+    },
+    "looks_nextcostume": {
+        "block_name": "next costume", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_nextcostume",
+        "functionality": "Switches the sprite's costume to the next one in its costume list. If it's the last costume, it cycles back to the first.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_switchbackdropto": {
+        "block_name": "switch backdrop to ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_switchbackdropto",
+        "functionality": "Changes the stage's backdrop to a specified backdrop.",
+        "inputs": {"BACKDROP": [1, "looks_backdrops"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_backdrops": {
+        "block_name": "backdrop menu", "block_type": "Looks", "block_shape": "Reporter Block", "op_code": "looks_backdrops",
+        "functionality": "Menu for switch backdrop to block.",
+        "inputs": {}, "fields": {"BACKDROP": ["backdrop1", None]}, "shadow": True, "topLevel": False
+    },
+    "looks_switchbackdroptowait": {
+        "block_name": "switch backdrop to () and wait", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_switchbackdroptowait",
+        "functionality": "Changes the stage's backdrop to a specified backdrop and pauses the script until any 'When backdrop switches to' scripts for that backdrop have finished.",
+        "inputs": {"BACKDROP": [1, "looks_backdrops"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_nextbackdrop": {
+        "block_name": "next backdrop", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_nextbackdrop",
+        "functionality": "Switches the stage's backdrop to the next one in its backdrop list. If it's the last backdrop, it cycles back to the first.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_changesizeby": {
+        "block_name": "change size by ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_changesizeby",
+        "functionality": "Changes the sprite's size by a specified percentage. Positive values make it larger, negative values make it smaller.",
+        "inputs": {"CHANGE": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_setsizeto": {
+        "block_name": "set size to () %", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_setsizeto",
+        "functionality": "Sets the sprite's size to a specific percentage of its original size.",
+        "inputs": {"SIZE": [1, [4, "100"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_changeeffectby": {
+        "block_name": "change () effect by ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_changeeffectby",
+        "functionality": "Changes a visual effect on the sprite by a specified amount (e.g., color, fisheye, whirl, pixelate, mosaic, brightness, ghost).",
+        "inputs": {"CHANGE": [1, [4, "25"]]}, "fields": {"EFFECT": ["COLOR", None]}, "shadow": False, "topLevel": True
+    },
+    "looks_seteffectto": {
+        "block_name": "set () effect to ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_seteffectto",
+        "functionality": "Sets a visual effect on the sprite to a specific value.",
+        "inputs": {"VALUE": [1, [4, "0"]]}, "fields": {"EFFECT": ["COLOR", None]}, "shadow": False, "topLevel": True
+    },
+    "looks_cleargraphiceffects": {
+        "block_name": "clear graphic effects", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_cleargraphiceffects",
+        "functionality": "Removes all visual effects applied to the sprite.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_show": {
+        "block_name": "show", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_show",
+        "functionality": "Makes the sprite visible on the stage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_hide": {
+        "block_name": "hide", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_hide",
+        "functionality": "Makes the sprite invisible on the stage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_gotofrontback": {
+        "block_name": "go to () layer", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_gotofrontback",
+        "functionality": "Moves the sprite to the front-most or back-most layer of other sprites on the stage.",
+        "inputs": {}, "fields": {"FRONT_BACK": ["front", None]}, "shadow": False, "topLevel": True
+    },
+    "looks_goforwardbackwardlayers": {
+        "block_name": "go () layers", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_goforwardbackwardlayers",
+        "functionality": "Moves the sprite forward or backward a specified number of layers in relation to other sprites.",
+        "inputs": {"NUM": [1, [7, "1"]]}, "fields": {"FORWARD_BACKWARD": ["forward", None]}, "shadow": False, "topLevel": True
+    },
+    "looks_costumenumbername": {
+        "block_name": "(costume ())", "block_type": "Looks", "block_shape": "Reporter Block", "op_code": "looks_costumenumbername",
+        "functionality": "Reports the current costume's number or name.",
+        "inputs": {}, "fields": {"NUMBER_NAME": ["number", None]}, "shadow": False, "topLevel": True
+    },
+    "looks_backdropnumbername": {
+        "block_name": "(backdrop ())", "block_type": "Looks", "block_shape": "Reporter Block", "op_code": "looks_backdropnumbername",
+        "functionality": "Reports the current backdrop's number or name.",
+        "inputs": {}, "fields": {"NUMBER_NAME": ["number", None]}, "shadow": False, "topLevel": True
+    },
+    "looks_size": {
+        "block_name": "(size)", "block_type": "Looks", "block_shape": "Reporter Block", "op_code": "looks_size",
+        "functionality": "Reports the current size of the sprite as a percentage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+
+    # operator_block.json
+    "operator_add": {
+        "block_name": "(() + ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_add",
+        "functionality": "Adds two numerical values.",
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_subtract": {
+        "block_name": "(() - ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_subtract",
+        "functionality": "Subtracts the second numerical value from the first.",
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_multiply": {
+        "block_name": "(() * ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_multiply",
+        "functionality": "Multiplies two numerical values.",
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_divide": {
+        "block_name": "(() / ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_divide",
+        "functionality": "Divides the first numerical value by the second.",
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_random": {
+        "block_name": "(pick random () to ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_random",
+        "functionality": "Generates a random integer within a specified inclusive range.",
+        "inputs": {"FROM": [1, [4, "1"]], "TO": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_gt": {
+        "block_name": "<() > ()>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_gt",
+        "functionality": "Checks if the first value is greater than the second.",
+        "inputs": {"OPERAND1": [1, [10, ""]], "OPERAND2": [1, [10, "50"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_lt": {
+        "block_name": "<() < ()>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_lt",
+        "functionality": "Checks if the first value is less than the second.",
+        "inputs": {"OPERAND1": [1, [10, ""]], "OPERAND2": [1, [10, "50"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_equals": {
+        "block_name": "<() = ()>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_equals",
+        "functionality": "Checks if two values are equal.",
+        "inputs": {"OPERAND1": [1, [10, ""]], "OPERAND2": [1, [10, "50"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_and": {
+        "block_name": "<<> and <>>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_and",
+        "functionality": "Returns 'true' if both provided Boolean conditions are 'true'.",
+        "inputs": {"OPERAND1": [2, None], "OPERAND2": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_or": {
+        "block_name": "<<> or <>>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_or",
+        "functionality": "Returns 'true' if at least one of the provided Boolean conditions is 'true'.",
+        "inputs": {"OPERAND1": [2, None], "OPERAND2": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_not": {
+        "block_name": "<not <>>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_not",
+        "functionality": "Returns 'true' if the provided Boolean condition is 'false', and 'false' if it is 'true'.",
+        "inputs": {"OPERAND": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_join": {
+        "block_name": "(join ()())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_join",
+        "functionality": "Concatenates two strings or values into a single string.",
+        "inputs": {"STRING1": [1, [10, "apple "]], "STRING2": [1, [10, "banana"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_letterof": {
+        "block_name": "letter () of ()", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_letterof",
+        "functionality": "Reports the character at a specific numerical position within a string.",
+        "inputs": {"LETTER": [1, [6, "1"]], "STRING": [1, [10, "apple"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_length": {
+        "block_name": "(length of ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_length",
+        "functionality": "Reports the total number of characters in a given string.",
+        "inputs": {"STRING": [1, [10, "apple"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_contains": {
+        "block_name": "<() contains ()?>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_contains",
+        "functionality": "Checks if one string contains another string.",
+        "inputs": {"STRING1": [1, [10, "apple"]], "STRING2": [1, [10, "a"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_mod": {
+        "block_name": "(() mod ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_mod",
+        "functionality": "Reports the remainder when the first number is divided by the second.",
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_round": {
+        "block_name": "(round ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_round",
+        "functionality": "Rounds a numerical value to the nearest integer.",
+        "inputs": {"NUM": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_mathop": {
+        "block_name": "(() of ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_mathop",
+        "functionality": "Performs various mathematical functions (e.g., absolute value, square root, trigonometric functions).",
+        "inputs": {"NUM": [1, [4, ""]]}, "fields": {"OPERATOR": ["abs", None]}, "shadow": False, "topLevel": True
+    },
+
+    # sensing_block.json
+    "sensing_touchingobject": {
+        "block_name": "<touching [edge v]?>", "block_type": "Sensing", "op_code": "sensing_touchingobject", "block_shape": "Boolean Block",
+        "functionality": "Checks if its sprite is touching the mouse-pointer, edge, or another specified sprite.",
+        "inputs": {"TOUCHINGOBJECTMENU": [1, "sensing_touchingobjectmenu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_touchingobjectmenu": {
+        "block_name": "touching object menu", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_touchingobjectmenu",
+        "functionality": "Menu for touching object block.",
+        "inputs": {}, "fields": {"TOUCHINGOBJECTMENU": ["_mouse_", None]}, "shadow": True, "topLevel": False
+    },
+    "sensing_touchingcolor": {
+        "block_name": "<touching color ()?>", "block_type": "Sensing", "op_code": "sensing_touchingcolor", "block_shape": "Boolean Block",
+        "functionality": "Checks whether its sprite is touching a specified color.",
+        "inputs": {"COLOR": [1, [9, "#55b888"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_coloristouchingcolor": {
+        "block_name": "<color () is touching ()?>", "block_type": "Sensing", "op_code": "sensing_coloristouchingcolor", "block_shape": "Boolean Block",
+        "functionality": "Checks whether a specific color on its sprite is touching another specified color on the stage or another sprite.",
+        "inputs": {"COLOR1": [1, [9, "#d019f2"]], "COLOR2": [1, [9, "#2b0de3"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_askandwait": {
+        "block_name": "Ask () and Wait", "block_type": "Sensing", "block_shape": "Stack Block", "op_code": "sensing_askandwait",
+        "functionality": "Displays an input box with specified text at the bottom of the screen, allowing users to input text, which is stored in the 'Answer' block.",
+        "inputs": {"QUESTION": [1, [10, "What's your name?"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_answer": {
+        "block_name": "(answer)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_answer",
+        "functionality": "Holds the most recent text inputted using the 'Ask () and Wait' block.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_keypressed": {
+        "block_name": "<key () pressed?>", "block_type": "Sensing", "op_code": "sensing_keypressed", "block_shape": "Boolean Block",
+        "functionality": "Checks if a specified keyboard key is currently being pressed.",
+        "inputs": {"KEY_OPTION": [1, "sensing_keyoptions"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_keyoptions": {
+        "block_name": "key options menu", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_keyoptions",
+        "functionality": "Menu for key pressed block.",
+        "inputs": {}, "fields": {"KEY_OPTION": ["space", None]}, "shadow": True, "topLevel": False
+    },
+    "sensing_mousedown": {
+        "block_name": "<mouse down?>", "block_type": "Sensing", "op_code": "sensing_mousedown", "block_shape": "Boolean Block",
+        "functionality": "Checks if the computer mouse's primary button is being clicked while the cursor is over the stage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_mousex": {
+        "block_name": "(mouse x)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_mousex",
+        "functionality": "Reports the mouse-pointer’s current X position on the stage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_mousey": {
+        "block_name": "(mouse y)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_mousey",
+        "functionality": "Reports the mouse-pointer’s current Y position on the stage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_setdragmode": {
+        "block_name": "set drag mode [draggable v]", "block_type": "Sensing", "block_shape": "Stack Block", "op_code": "sensing_setdragmode",
+        "functionality": "Sets whether the sprite can be dragged by the mouse on the stage.",
+        "inputs": {}, "fields": {"DRAG_MODE": ["draggable", None]}, "shadow": False, "topLevel": True
+    },
+    "sensing_loudness": {
+        "block_name": "(loudness)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_loudness",
+        "functionality": "Reports the loudness of noise received by a microphone on a scale of 0 to 100.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_timer": {
+        "block_name": "(timer)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_timer",
+        "functionality": "Reports the elapsed time since Scratch was launched or the timer was reset, increasing by 1 every second.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_resettimer": {
+        "block_name": "Reset Timer", "block_type": "Sensing", "block_shape": "Stack Block", "op_code": "sensing_resettimer",
+        "functionality": "Sets the timer’s value back to 0.0.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_of": {
+        "block_name": "(() of ())", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_of",
+        "functionality": "Reports a specified value (e.g., x position, direction, costume number) of a specified sprite or the Stage to be accessed in current sprite or stage.",
+        "inputs": {"OBJECT": [1, "sensing_of_object_menu"]}, "fields": {"PROPERTY": ["backdrop #", None]}, "shadow": False, "topLevel": True
+    },
+    "sensing_of_object_menu": {
+        "block_name": "of object menu", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_of_object_menu",
+        "functionality": "Menu for of block.",
+        "inputs": {}, "fields": {"OBJECT": ["_stage_", None]}, "shadow": True, "topLevel": False
+    },
+    "sensing_current": {
+        "block_name": "(current ())", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_current",
+        "functionality": "Reports the current local year, month, date, day of the week, hour, minutes, or seconds.",
+        "inputs": {}, "fields": {"CURRENTMENU": ["YEAR", None]}, "shadow": False, "topLevel": True
+    },
+    "sensing_dayssince2000": {
+        "block_name": "(days since 2000)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_dayssince2000",
+        "functionality": "Reports the number of days (and fractions of a day) since 00:00:00 UTC on January 1, 2000.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_username": {
+        "block_name": "(username)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_username",
+        "functionality": "Reports the username of the user currently logged into Scratch. If no user is logged in, it reports nothing.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+
+    # sound_block.json
+    "sound_playuntildone": {
+        "block_name": "play sound () until done", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_playuntildone",
+        "functionality": "Plays a specified sound and pauses the script's execution until the sound has completed.",
+        "inputs": {"SOUND_MENU": [1, "sound_sounds_menu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sound_sounds_menu": {
+        "block_name": "sound menu", "block_type": "Sound", "block_shape": "Reporter Block", "op_code": "sound_sounds_menu",
+        "functionality": "Menu for sound blocks.",
+        "inputs": {}, "fields": {"SOUND_MENU": ["Meow", None]}, "shadow": True, "topLevel": False
+    },
+    "sound_play": {
+        "block_name": "start sound ()", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_play",
+        "functionality": "Initiates playback of a specified sound without pausing the script, allowing other actions to proceed concurrently.",
+        "inputs": {"SOUND_MENU": [1, "sound_sounds_menu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sound_stopallsounds": {
+        "block_name": "stop all sounds", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_stopallsounds",
+        "functionality": "Stops all currently playing sounds.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sound_changeeffectby": {
+        "block_name": "change () effect by ()", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_changeeffectby",
+        "functionality": "Changes the project's sound effect by a specified amount.",
+        "inputs": {"VALUE": [1, [4, "10"]]}, "fields": {"EFFECT": ["PITCH", None]}, "shadow": False, "topLevel": True
+    },
+    "sound_seteffectto": {
+        "block_name": "set () effect to ()", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_seteffectto",
+        "functionality": "Sets the sound effect to a specific value.",
+        "inputs": {"VALUE": [1, [4, "100"]]}, "fields": {"EFFECT": ["PITCH", None]}, "shadow": False, "topLevel": True
+    },
+    "sound_cleareffects": {
+        "block_name": "clear sound effects", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_cleareffects",
+        "functionality": "Removes all sound effects applied to the sprite.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sound_changevolumeby": {
+        "block_name": "change volume by ()", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_changevolumeby",
+        "functionality": "Changes the project's sound volume by a specified amount.",
+        "inputs": {"VOLUME": [1, [4, "-10"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sound_setvolumeto": {
+        "block_name": "set volume to () %", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_setvolumeto",
+        "functionality": "Sets the sound volume to a specific percentage (0-100).",
+        "inputs": {"VOLUME": [1, [4, "100"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sound_volume": {
+        "block_name": "(volume)", "block_type": "Sound", "block_shape": "Reporter Block", "op_code": "sound_volume",
+        "functionality": "Reports the current volume level of the sprite.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+}
+
+# # Example input with opcodes for the initial generation
+initial_opcode_counts = [
+    {"opcode":"event_whenflagclicked","count":1},
+    {"opcode":"motion_gotoxy","count":1},
+    {"opcode":"motion_glidesecstoxy","count":1},
+    {"opcode":"motion_xposition","count":1},
+    {"opcode":"motion_setx","count":1},
+    {"opcode":"control_forever","count":1},
+    {"opcode":"control_if","count":1},
+    {"opcode":"control_stop","count":1},
+    {"opcode":"operator_lt","count":1},
+    {"opcode":"sensing_touchingobject","count":1}, # Changed from sensing_istouching
+    {"opcode":"sensing_touchingobjectmenu","count":1},
+    {"opcode":"event_broadcast","count":1},
+    {"opcode":"data_setvariableto","count":2},
+    {"opcode":"data_showvariable","count":2},
+]
+
+# initial_opcode_counts = [
+#     {"opcode": "sound_play", "count": 2},
+#     {"opcode": "sound_playuntildone", "count": 2},
+#     {"opcode":"motion_goto","count":2},
+#     {"opcode":"motion_glideto","count":2},
+#     {"opcode":"looks_switchbackdropto","count":2},
+#     {"opcode":"looks_switchcostumeto","count":2},
+#     {"opcode":"control_create_clone_of","count":2},
+#     {"opcode":"sensing_touchingobject","count":2},
+#     {"opcode":"sensing_of","count":2},
+#     {"opcode":"sensing_keypressed","count":2},
+#     {"opcode":"motion_pointtowards","count":2},
+# ]
+
+# Generate the initial blocks and get the opcode_occurrences
+generated_output_json, initial_opcode_occurrences = generate_blocks_from_opcodes(initial_opcode_counts, all_block_definitions)
+#print(generated_output_json)
+#print(initial_opcode_occurrences)
+
+
+def build_block_patterns(def_list):
+    """
+    Given a list of block definitions (from one JSON file),
+    return a dict opcode -> { regex:Compiled, inputs:[names], shape, block_name }.
+    """
+    out = {}
+    for d in def_list:
+        # 1) escape the literal text
+        pattern = re.escape(d['block_name'])
+        # 2) replace the escaped "()" placeholders with a capture for anything inside
+        pattern = pattern.replace(r"\(\)", r"\((.+?)\)")
+        # 3) replace the escaped "<>" placeholders likewise
+        pattern = pattern.replace(r"\<\>", r"<(.+?)>")
+        # 4) allow any whitespace where spaces occur
+        pattern = pattern.replace(r"\ ", r"\s+")
+        # anchor from start to end, ignore case
+        regex = re.compile(r"^\s*" + pattern + r"\s*$", re.IGNORECASE)
+
+        inputs = [inp['name'] for inp in (d.get('inputs') or [])]
+        out[d['op_code']] = {
+            'regex':     regex,
+            'inputs':    inputs,
+            'shape':     d['block_shape'],
+            'block_name':d['block_name'],
+            'definition':d
+        }
+    return out
+
+def load_all_definitions():
+    # Load your JSON files here; adjust paths as needed
+    hats      = json.load(open(r'blocks\hat_blocks.json'))['blocks']
+    c_blocks  = json.load(open(r'blocks\c_blocks.json'))['blocks']
+    reporters = json.load(open(r'blocks\reporter_blocks.json'))['blocks']
+    booleans  = json.load(open(r'blocks\boolean_blocks.json'))['blocks']
+    # you can also load stack_blocks.json, cap_blocks.json, etc. if you have them
+    merged = hats + c_blocks + reporters + booleans
+    return build_block_patterns(merged)
+
+def generate_plan(generated_input, opcode_keys, pseudo_code):
+    """
+    A truly generic plan generator.
+    Inputs:
+      - generated_input:  dict of block_key -> block_data
+      - opcode_keys:      dict of opcode -> [block_key,...]
+      - pseudo_code:      multiline string
+    Returns: { flow: [...] }
+    """
+    all_defs = load_all_definitions()
+    # pointer into each opcode_keys list
+    ptrs = defaultdict(int)
+    def pick_key(opcode):
+        lst = opcode_keys.get(opcode, [])
+        if ptrs[opcode] >= len(lst):
+            raise KeyError(f"No more generated keys for opcode {opcode!r}")
+        key = lst[ptrs[opcode]]
+        ptrs[opcode] += 1
+        return key
+
+    # Recursively parse an expression fragment like "(x position)" or "<touching [A]?>"
+    def parse_expression(expr_text):
+        expr_text = expr_text.strip()
+        # Try to match every reporter/boolean pattern
+        for op, info in all_defs.items():
+            m = info['regex'].match(expr_text)
+            if not m: continue
+            # Got a match
+            node = {'op_code': op, 'inputs': {}}
+            groups = m.groups()
+            for name, val in zip(info['inputs'], groups):
+                # decide kind by input type in definition
+                inp_def = next(
+                    (i for i in info['definition'].get('inputs', []) if i['name']==name),
+                    {}
+                )
+                t = inp_def.get('type','any')
+                if t in ('number','any'):
+                    try:
+                        node['inputs'][name] = {'kind':'value',       'value': float(val) if '.' in val else int(val)}
+                    except:
+                        node['inputs'][name] = {'kind':'variable',    'name': val.strip()}
+                elif t in ('dropdown','string','string/number'):
+                    node['inputs'][name] = {'kind':'menu',        'option': val.strip()}
+                elif t=='boolean':
+                    # nested boolean: recurse
+                    node['inputs'][name] = {'kind':'nested', 'expr': parse_expression(val)}
+                else:
+                    node['inputs'][name] = {'kind':'nested', 'expr': parse_expression(val)}
+            return node
+        # fallback: literal?
+        lit = re.match(r"^\(?\s*(-?\d+(\.\d+)?)\s*\)?$", expr_text)
+        if lit:
+            num = lit.group(1)
+            return {'literal': True, 'kind':'value', 'value': float(num) if '.' in num else int(num)}
+        # else treat as raw string
+        return {'literal':True, 'kind':'variable', 'name':expr_text}
+
+    flow = []
+    # stack of (indent, container)
+    stack = [(-1, flow)]
+
+    for raw in pseudo_code.splitlines():
+        if not raw.strip(): continue
+        indent = (len(raw) - len(raw.lstrip())) // 2
+        line = raw.strip()
+        # drop trailing 'then' or 'end'
+        line_clean = re.sub(r'\s*(then|end)\s*$', '', line, flags=re.IGNORECASE)
+
+        # find a matching block definition
+        for opcode, info in all_defs.items():
+            if not info['regex'].match(line_clean):
+                continue
+            # pop up to correct level
+            while stack and stack[-1][0] >= indent:
+                stack.pop()
+            container = stack[-1][1]
+
+            key = pick_key(opcode)
+            node = {'block_key': key}
+            shape = info['shape']
+            # determine node type
+            if 'Hat Block' in shape:
+                node['type'] = 'hat'
+                node['description'] = info['block_name']
+                node['next'] = []
+                target_list = node['next']
+            elif 'C-Block' in shape:
+                node['type'] = 'c_block'
+                node['description'] = info['block_name']
+                node['condition'] = None
+                node['body'] = []
+                target_list = node['body']
+                # the first input is usually the boolean condition
+                if info['inputs']:
+                    cond_name = info['inputs'][0]
+                    # extract the <...> portion
+                    cond_match = re.search(r'<(.+)>', line)
+                    if cond_match:
+                        node['condition'] = parse_expression(cond_match.group(1))
+            elif 'Cap Block' in shape:
+                node['type'] = 'cap'
+                # e.g. stop [all v]
+                if 'inputs' in info['definition'] and info['definition']['inputs']:
+                    fld = info['definition']['inputs'][0]['name']
+                    val = re.search(r'\[\s*([^\]]+)\s*\]', line)
+                    if val:
+                        node['option'] = val.group(1)
+                target_list = None
+            else:
+                node['type'] = 'stack'
+                # parse any inputs in parentheses or brackets
+                node['inputs'] = {}
+                # for each input name in the definition, find its occurrence
+                for inp_name in info['inputs']:
+                    # look for "(...)" after the input name or anywhere
+                    # brute-force: find all "(...)" then map in order
+                    pass
+                target_list = None
+
+            container.append(node)
+            if target_list is not None:
+                stack.append((indent, target_list))
+            break
+        else:
+            # no matching opcode — you can log or raise here
+            raise ValueError(f"Could not classify line: {line!r}")
+
+    return {'flow': flow}
+
+pseudo_code_input = """
+when green flag clicked
+  go to x: (240) y: (-135)
+  set [score v] to (1)
+  set [speed v] to (1)
+  show variable [score v]
+  show variable [speed v]
+  forever
+    glide (2) seconds to x: (-240) y: (-135)
+    if <((x position)) < (-235)> then
+      set x to (240)
+    end
+    if <touching [Sprite1 v]?> then
+      broadcast [Game Over v]
+      stop [all v]
+    end
+  end
+end
+"""
+
+# ── USAGE ──
+plan = generate_plan(generated_output_json, initial_opcode_occurrences, pseudo_code_input)
+import json
+print(json.dumps(plan, indent=2))

utils/pseudo_exampls.txt

@@ -0,0 +1,618 @@
+pseudo_code_examples = [
+    # From motion_block.json
+    """
+when green flag clicked
+  go to x: (0) y: (0)
+  point in direction (90)
+  move (50) steps
+end
+    """,
+    """
+when [right arrow v] key pressed
+  turn right (15) degrees
+end
+    """,
+    """
+when this sprite clicked
+  go to [mouse-pointer v]
+    """,
+    """
+when green flag clicked
+  glide (2) secs to x: (150) y: (-100)
+  glide (2) secs to x: (-150) y: (100)
+end
+    """,
+    """
+when green flag clicked
+  forever
+    point towards [mouse-pointer v]
+    move (5) steps
+  end
+end
+    """,
+    """
+when [right arrow v] key pressed
+  change x by (10)
+end
+    """,
+    """
+when green flag clicked
+  set x to (0)
+  set y to (0)
+end
+    """,
+    """
+when [up arrow v] key pressed
+  change y by (10)
+end
+    """,
+    """
+when green flag clicked
+  forever
+    move (10) steps
+    if on edge, bounce
+  end
+end
+    """,
+    """
+when green flag clicked
+  set rotation style [left-right v]
+  forever
+    move (10) steps
+    if on edge, bounce
+  end
+end
+    """,
+    # From looks_block.json
+    """
+when green flag clicked
+   say [Grr] for (3) seconds
+   say [Have you seen my honey? v] for (3) seconds
+end
+    """,
+    """
+when green flag clicked
+   say [Welcome to my game! v]
+   wait (2) seconds
+   say []
+end
+    """,
+    """
+when this sprite clicked
+   think [What should I do? v] for (2) seconds
+end
+    """,
+    """
+when I receive [correct answer v]
+   think [That's right! v]
+   wait (1) seconds
+   think [good v]
+end
+    """,
+    """
+when I receive [explosion v]
+   repeat (5)
+     next costume
+   end
+   hide
+end
+    """,
+    """
+when green flag clicked
+   forever
+     next costume
+     wait (0.2) seconds
+   end
+end
+    """,
+    """
+when green flag clicked
+   switch backdrop to [start screen v]
+end
+    """,
+    """
+broadcast [game over v]
+   switch backdrop to [game over v] and wait
+   stop [all v]
+end
+    """,
+    """
+when [space v] key pressed
+   next backdrop
+end
+    """,
+    """
+when green flag clicked
+   repeat (10)
+     change size by (5)
+     wait (0.1) seconds
+   end
+end
+    """,
+    """
+when green flag clicked
+   set size to (50) %
+   wait (1) seconds
+   set size to (100) %
+end
+    """,
+    """
+when green flag clicked
+   forever
+     change [color v] effect by (5)
+     wait (0.1) seconds
+  end
+end
+    """,
+    """
+when green flag clicked
+   set [ghost v] effect to (75)
+end
+    """,
+    """
+when green flag clicked
+   change [color v] effect by (50)
+   wait (2) seconds
+   clear graphic effects
+end
+    """,
+    """
+when green flag clicked
+   hide
+when I receive [start game v]
+   show
+end
+    """,
+    """
+when green flag clicked
+   hide
+end
+    """,
+    """
+when green flag clicked
+   go to [front v] layer
+end
+    """,
+    """
+when this sprite clicked
+  go [forward v] (1) layers
+end
+    """,
+    """
+say join [I am costume ] (costume [name v])
+    """,
+    """
+say join [Current backdrop: ] (backdrop [name v]) for (2) seconds
+    """,
+    """
+set size to ( (size) + (10) )
+    """,
+    # From sound_block.json
+    """
+when backdrop switches to [winning screen v]
+  play sound [fanfare v] until done
+  say [You won!] for (2) seconds
+end
+    """,
+    """
+forever
+   play sound [Music v] until done
+end
+    """,
+    """
+when this sprite clicked
+   start sound [Pop v]
+   change [score v] by (1)
+end
+    """,
+    """
+when I receive [game over v]
+   stop all sounds
+end
+    """,
+    """
+when [down arrow v] key pressed
+   change volume by (-5)
+end
+    """,
+    """
+when green flag clicked
+   set volume to (50) %
+end
+    """,
+    """
+say join [Current volume: ] (volume)
+    """,
+    # From event_block.json
+    """
+when green flag clicked
+  go to x: (0) y: (0)
+  say [Hello!] for (2) seconds
+end
+    """,
+    """
+when [space v] key pressed
+  repeat (10)
+    change y by (10)
+    wait (0.1) seconds
+    change y by (-10)
+  end
+end
+    """,
+    """
+when [right arrow v] key pressed
+  point in direction (90)
+  move (10) steps
+end
+    """,
+    """
+when this sprite clicked
+  say [Ouch!] for (1) seconds
+  change [score v] by (-1)
+end
+    """,
+    """
+when backdrop switches to [game over v]
+  stop [all v]
+end
+    """,
+    """
+when [loudness v] > (70)
+  start sound [scream v]
+end
+    """,
+    """
+when I receive [start game v]
+  show
+  go to x: (0) y: (0)
+end
+    """,
+    """
+when I receive [game over v]
+  set score to 0
+  stop [all v]
+end
+    """,
+    """
+if <key [space v] pressed?> then
+  broadcast [jump v]
+end
+    """,
+    """
+broadcast [initialize sprites v] and wait
+  say [Game Started!] for (2) seconds
+    """,
+    # From control_block.json
+    """
+say [Hello!] for (1) seconds
+   wait (0.5) seconds
+   say [Goodbye!] for (1) seconds
+    """,
+    """
+when green flag clicked
+  repeat (10)
+    move (10) steps
+    wait (0.1) seconds
+  end
+end
+    """,
+    """
+when green flag clicked
+  forever
+    move (5) steps
+    if on edge, bounce
+  end
+end
+    """,
+    """
+forever
+  if <touching [color (red) v]?> then
+    stop [this script v]
+  end
+end
+    """,
+    """
+if <(score) > (10)> then
+  say [You win!] for (2) seconds
+else
+  say [Keep trying!] for (2) seconds
+end
+    """,
+    """
+repeat until <touching [edge v]?>
+  move (5) steps
+end
+    """,
+    """
+if <(health) = (0)> then
+  stop [all v]
+end
+    """,
+    """
+when I start as a clone
+  wait until <touching [edge v]?>
+  delete this clone
+end
+    """,
+    """
+when I start as a clone
+  go to x: (pick random -240 to 240) y: (pick random -180 to 180)
+  show
+  forever
+    move (10) steps
+    if on edge, bounce
+  end
+end
+    """,
+    """
+when I start as a clone
+   wait (5) seconds
+   delete this clone
+end
+    """,
+    """
+when green flag clicked
+   hide
+   forever
+     create clone of [myself v]
+     wait (1) seconds
+   end
+    """,
+    # From data_block.json
+    """
+when green flag clicked
+  set [score v] to (0)
+  set [player name v] to [Guest]
+end
+    """,
+    """
+when this sprite clicked
+  change [score v] by (1)
+end
+    """,
+    """
+when green flag clicked
+  add [apple] to [shopping list v]
+  add [banana] to [shopping list v]
+end
+    """,
+    """
+when green flag clicked
+  delete (all) of [my list v]
+end
+    """,
+    """
+insert [orange] at (2) of [fruits v]
+    """,
+    """
+replace item (1) of [colors v] with [blue]
+    """,
+    """
+when green flag clicked
+  show variable [score v]
+end
+    """,
+    """
+when I receive [game over v]
+  hide variable [score v]
+end
+    """,
+    """
+when green flag clicked
+  show list [shopping list v]
+end
+    """,
+    """
+when I receive [game over v]
+  hide list [shopping list v]
+end
+    """,
+    """
+say ([score v]) for (2) seconds
+    """,
+    """
+say ([my list v])
+    """,
+    """
+say (item (2) of [myList v]) for 2 seconds
+    """,
+    """
+say join (length of [shopping list v]) [ items in the list.]
+    """,
+    """
+if <(item # of [Dog] in [myList v])> (0)> then
+  say join [Dog found at position ] (item # of [Dog] in [my list v])
+end
+    """,
+    # From reporter_blocks.json (some already covered by other categories)
+    """
+when green flag clicked
+  say (x position) for (2) seconds
+end
+    """,
+    """
+set [worms v] to (y position)
+    """,
+    """
+when green flag clicked
+  say (direction) for (2) seconds
+end
+    """,
+    """
+say join [I am costume ] (costume [name v])
+    """,
+    """
+set size to ( (size) + (10) )
+    """,
+    """
+say join [Current backdrop: ] (backdrop [name v]) for (2) seconds
+    """,
+    """
+say join [Current volume: ] (volume)
+    """,
+    """
+if <(distance to [Sprite2 v]) < (50)> then
+  say [Too close!]
+end
+    """,
+    """
+ask [What is your name?] and wait
+  say join [Hello ] (answer)
+    """,
+    """
+go to x: (mouse x) y: (mouse y)
+    """,
+    """
+if <(mouse y) < (0)> then
+  say [Below center]
+end
+    """,
+    """
+when green flag clicked
+  forever
+    if <(loudness) > (30)> then
+      start sound [pop v]
+end
+    """,
+    """
+when green flag clicked
+  reset timer
+  wait (5) seconds
+  say join [Time elapsed: ] (timer)
+end
+    """,
+    """
+set [other sprite X v] to ( (x position) of [Sprite2 v] )
+    """,
+    """
+say join [The current hour is ] (current [hour v])
+    """,
+    """
+say join [Days passed: ] (days since 2000)
+    """,
+    """
+say join [Hello, ] (username)
+    """,
+    """
+set [total v] to ( (number 1) + (number 2) )
+    """,
+    """
+set [difference v] to ( (number 1) - (number 2) )
+    """,
+    """
+set [area v] to ( (length) * (width) )
+    """,
+    """
+set [average v] to ( (total score) / (number of students) )
+    """,
+    """
+go to x: (pick random -240 to 240) y: (pick random -180 to 180)
+    """,
+    """
+say (join [Hello ][World!])
+    """,
+    """
+say (letter (1) of [apple])
+    """,
+    """
+say (length of [banana])
+    """,
+    """
+if <([number v] mod (2) = (0))> then
+  say [Even number]
+end
+    """,
+    """
+set [rounded score v] to (round (score))
+    """,
+    """
+set [distance v] to ([sqrt v] of ( ( (x position) * (x position) ) + ( (y position) * (y position) ) ))
+    """,
+    # From boolean_blocks.json (conditions already covered by parse_condition)
+    """
+if <(score) < (10)> then
+  say [Keep trying!]
+end
+    """,
+    """
+if <(answer) = (5)> then
+  say [Correct!]
+end
+    """,
+    """
+if <([health v]) > (0)> then
+  move (10) steps
+else
+  stop [all v]
+end
+    """,
+    """
+if <<mouse down?> and <touching [mouse-pointer]?> > then
+  say [You're clicking me!]
+end
+    """,
+    """
+if <<key [left arrow v] pressed?> or <key [a v] pressed?>> then
+  change x by (-10)
+end
+    """,
+    """
+if <not <touching [Sprite2 v]?>> then
+  say [I'm safe!]
+end
+    """,
+    """
+if <[answer] contains [yes]?> then
+  say [Great!]
+end
+    """,
+    """
+if <touching [Sprite v]?> then
+   broadcast [Game Over v]
+end
+    """,
+    """
+if <touching [edge v]?> then
+  bounce off edge
+end
+    """,
+    """
+if <touching color [#FF0000]?> then
+  change [health v] by (-1)
+end
+    """,
+    """
+if <color [#00FF00] is touching [#FF0000]?> then
+  say [Collision!]
+end
+    """,
+    """
+forever
+  if <key [space v] pressed?> then
+    broadcast [shoot v]
+  end
+end
+    """,
+    """
+if <mouse down?> then
+  go to mouse-pointer
+end
+    """,
+    """
+if <[inventory v] contains [key]?> then
+  say [You have the key!]
+end
+    """,
+    # Custom block example
+    """
+define jump (height)
+  change y by (height)
+  wait (0.5) seconds
+  change y by (0 - (height))
+end
+
+when green flag clicked
+  jump (50)
+end
+    """
+]

utils/script_plan.py

@@ -0,0 +1,1449 @@
+import json
+import copy
+import re
+
+def generate_blocks_from_opcodes(opcode_counts, all_block_definitions):
+    """
+    Generates a dictionary of Scratch-like blocks based on a list of opcodes and a reference block definition.
+    It now correctly links parent and menu blocks using their generated unique keys, and handles various block categories.
+    It ensures that menu blocks are only generated as children of their respective parent blocks.
+
+    Args:
+        opcode_counts (list): An array of objects, each with an 'opcode' and 'count' property.
+                              Example: [{"opcode": "motion_gotoxy", "count": 1}]
+        all_block_definitions (dict): A comprehensive dictionary containing definitions for all block types.
+
+    Returns:
+        tuple: A tuple containing:
+            - dict: A JSON object where keys are generated block IDs and values are the block definitions.
+            - dict: The opcode_occurrences dictionary for consistent unique key generation across functions.
+    """
+    generated_blocks = {}
+    opcode_occurrences = {}  # To keep track of how many times each opcode (main or menu) has been used for unique keys
+
+    # Define explicit parent-menu relationships for linking purposes
+    # This maps main_opcode -> list of (input_field_name, menu_opcode)
+    explicit_menu_links = {
+        "motion_goto": [("TO", "motion_goto_menu")],
+        "motion_glideto": [("TO", "motion_glideto_menu")],
+        "motion_pointtowards": [("TOWARDS", "motion_pointtowards_menu")],
+        "sensing_keypressed": [("KEY_OPTION", "sensing_keyoptions")],
+        "sensing_of": [("OBJECT", "sensing_of_object_menu")],
+        "sensing_touchingobject": [("TOUCHINGOBJECTMENU", "sensing_touchingobjectmenu")],
+        "control_create_clone_of": [("CLONE_OPTION", "control_create_clone_of_menu")],
+        "sound_play": [("SOUND_MENU", "sound_sounds_menu")],
+        "sound_playuntildone": [("SOUND_MENU", "sound_sounds_menu")],
+        "looks_switchcostumeto": [("COSTUME", "looks_costume")],
+        "looks_switchbackdropto": [("BACKDROP", "looks_backdrops")],
+    }
+
+    # --- Step 1: Process explicitly requested opcodes and generate their instances and associated menus ---
+    for item in opcode_counts:
+        opcode = item.get("opcode")
+        count = item.get("count", 1)
+
+        # Special handling for 'sensing_istouching' which maps to 'sensing_touchingobject'
+        if opcode == "sensing_istouching":
+            opcode = "sensing_touchingobject"
+
+        if not opcode:
+            print("Warning: Skipping item with missing 'opcode'.")
+            continue
+
+        if opcode not in all_block_definitions:
+            print(f"Warning: Opcode '{opcode}' not found in all_block_definitions. Skipping.")
+            continue
+
+        for _ in range(count):
+            # Increment occurrence count for the current main opcode
+            opcode_occurrences[opcode] = opcode_occurrences.get(opcode, 0) + 1
+            main_block_instance_num = opcode_occurrences[opcode]
+            
+            main_block_unique_key = f"{opcode}_{main_block_instance_num}"
+            
+            # Create a deep copy of the main block definition
+            main_block_data = copy.deepcopy(all_block_definitions[opcode])
+            
+            # Set properties for a top-level main block
+            main_block_data["parent"] = None
+            main_block_data["next"] = None
+            main_block_data["topLevel"] = True
+            main_block_data["shadow"] = False # Main blocks are typically not shadows
+
+            generated_blocks[main_block_unique_key] = main_block_data
+
+            # If this main block has associated menus, generate and link them now
+            if opcode in explicit_menu_links:
+                for input_field_name, menu_opcode_type in explicit_menu_links[opcode]:
+                    if menu_opcode_type in all_block_definitions:
+                        # Increment the occurrence for the menu block type
+                        opcode_occurrences[menu_opcode_type] = opcode_occurrences.get(menu_opcode_type, 0) + 1
+                        menu_block_instance_num = opcode_occurrences[menu_opcode_type]
+
+                        menu_block_data = copy.deepcopy(all_block_definitions[menu_opcode_type])
+                        
+                        # Generate a unique key for this specific menu instance
+                        menu_unique_key = f"{menu_opcode_type}_{menu_block_instance_num}"
+                        
+                        # Set properties for a shadow menu block
+                        menu_block_data["shadow"] = True
+                        menu_block_data["topLevel"] = False
+                        menu_block_data["next"] = None
+                        menu_block_data["parent"] = main_block_unique_key # Link menu to its parent instance
+
+                        # Update the main block's input to point to this unique menu instance
+                        if input_field_name in main_block_data.get("inputs", {}) and \
+                           isinstance(main_block_data["inputs"][input_field_name], list) and \
+                           len(main_block_data["inputs"][input_field_name]) > 1 and \
+                           main_block_data["inputs"][input_field_name][0] == 1:
+                            
+                            main_block_data["inputs"][input_field_name][1] = menu_unique_key
+                        
+                        generated_blocks[menu_unique_key] = menu_block_data
+            
+    return generated_blocks, opcode_occurrences
+
+def interpret_pseudo_code_and_update_blocks(generated_blocks_json, pseudo_code, all_block_definitions, opcode_occurrences):
+    """
+    Interprets pseudo-code to update the generated Scratch blocks, replacing static values
+    with dynamic values and establishing stacking/nesting logic.
+
+    Args:
+        generated_blocks_json (dict): The JSON object of pre-generated blocks.
+        pseudo_code (str): The pseudo-code string to interpret.
+        all_block_definitions (dict): A comprehensive dictionary containing definitions for all block types.
+        opcode_occurrences (dict): A dictionary to keep track of opcode occurrences for unique key generation.
+
+    Returns:
+        dict: The updated JSON object of Scratch blocks.
+    """
+    updated_blocks = copy.deepcopy(generated_blocks_json)
+    
+    # Helper to create a new block instance (used for shadows/nested blocks)
+    def create_block_instance_for_parsing(opcode, parent_key=None, is_shadow=False, is_top_level=False):
+        opcode_occurrences[opcode] = opcode_occurrences.get(opcode, 0) + 1
+        unique_key = f"{opcode}_{opcode_occurrences[opcode]}"
+        
+        new_block = copy.deepcopy(all_block_definitions.get(opcode, {}))
+        if not new_block:
+            print(f"Error: Definition for opcode '{opcode}' not found when creating instance for parsing.")
+            return None, None
+
+        new_block["parent"] = parent_key
+        new_block["next"] = None
+        new_block["topLevel"] = is_top_level
+        new_block["shadow"] = is_shadow
+
+        # Initialize inputs/fields to default empty values, but preserve structure
+        if "inputs" in new_block:
+            for input_name, input_data in new_block["inputs"].items():
+                if isinstance(input_data, list) and len(input_data) > 1:
+                    if input_data[0] == 1: # Block reference
+                        new_block["inputs"][input_name][1] = None # Placeholder for linked block ID
+                    elif input_data[0] in [4, 5, 6, 7, 8, 9, 10]: # Literal types
+                        new_block["inputs"][input_name][1] = "" # Default empty literal
+        if "fields" in new_block:
+            for field_name, field_data in new_block["fields"].items():
+                if isinstance(field_data, list) and len(field_data) > 0:
+                    new_block["fields"][field_name][0] = "" # Default empty field value
+
+        updated_blocks[unique_key] = new_block
+        return unique_key, new_block
+
+    # Helper to parse input values from pseudo-code and create nested blocks if necessary
+    def parse_and_link_input(parent_block_key, input_type, pseudo_value, input_name_in_parent=None, field_name_in_parent=None):
+        pseudo_value = pseudo_value.strip()
+
+        # 1. Handle literal numbers (e.g., "2", "+1", "-135")
+        if re.fullmatch(r"[-+]?\d+(\.\d+)?", pseudo_value):
+            return [4, pseudo_value] # Type 4 for number literal
+
+        # 2. Handle literal strings (e.g., "Game Over") - often in quotes or simply text
+        # If it's a broadcast message, it's typically a string literal.
+        # If it's a 'say' message, it's a string literal.
+        # If it's a variable name, it's handled by specific patterns later.
+        if pseudo_value.startswith('"') and pseudo_value.endswith('"'):
+            return [10, pseudo_value.strip('"')] # Type 10 for string literal
+        
+        # 3. Handle variable names (e.g., "[score v]", "[Sprite1 v]", "[Game Over v]")
+        # These can be fields or inputs that expect a variable reporter block.
+        var_match = re.match(r"\[(.+?) v\]", pseudo_value)
+        if var_match:
+            var_name = var_match.group(1).strip()
+            # If it's a field (like for set variable, show variable)
+            if field_name_in_parent:
+                return var_name # Return name, parent block will set its field
+            # If it's an input that expects a variable reporter (e.g., 'say (score)')
+            # Create a data_variable shadow block
+            var_reporter_key, var_reporter_data = create_block_instance_for_parsing(
+                "data_variable", parent_key=parent_block_key, is_shadow=True
+            )
+            if var_reporter_key:
+                var_reporter_data["fields"]["VARIABLE"] = [var_name, f"`var_{var_name}"] # Placeholder ID
+                return [1, var_reporter_key] # Type 1 for block reference
+            else:
+                print(f"Warning: Could not create data_variable block for '{var_name}'")
+                return [10, var_name] # Fallback to string literal
+
+        # 4. Handle nested reporter blocks (e.g., "(x position)")
+        reporter_match = re.match(r"\((.+?)\)", pseudo_value)
+        if reporter_match:
+            inner_content = reporter_match.group(1).strip()
+            # Check if it's a known reporter block (like "x position")
+            if inner_content in reporter_opcode_lookup:
+                reporter_opcode = reporter_opcode_lookup[inner_content]
+                reporter_block_key, reporter_block_data = create_block_instance_for_parsing(
+                    reporter_opcode, parent_key=parent_block_key, is_shadow=True
+                )
+                if reporter_block_key:
+                    return [1, reporter_block_key] # Type 1 for block reference
+                else:
+                    print(f"Warning: Could not create reporter block for '{inner_content}'")
+                    return [10, inner_content] # Fallback to string literal
+            else: # It's a literal number or string inside parentheses
+                return parse_and_link_input(parent_block_key, input_type, inner_content) # Recurse for inner content
+
+        # 5. Handle nested boolean blocks (e.g., "<(...) < (...)>")
+        boolean_match = re.match(r"<(.+?)>", pseudo_value)
+        if boolean_match:
+            inner_condition_str = boolean_match.group(1).strip()
+            # This is typically handled by the parent block's parsing (e.g., control_if)
+            # For now, if called directly, it implies a boolean reporter.
+            # We'll need specific logic for operator_lt, operator_and, etc.
+            # This part is complex and often handled by the parent block's specific regex.
+            # For this problem, the 'if' block's logic will create the boolean shadow.
+            print(f"Warning: Direct parsing of standalone boolean '{pseudo_value}' not fully supported here.")
+            return [10, pseudo_value] # Fallback to string literal
+
+        # Default to string literal if no other pattern matches
+        return [10, pseudo_value]
+
+    lines = [line.strip() for line in pseudo_code.strip().split('\n') if line.strip()]
+
+    # Track the current script and nesting
+    current_script_head = None
+    block_stack = [] # Stores (parent_block_key, indent_level, last_child_key_in_scope)
+
+    # Create a mapping from block name patterns to their opcodes and input/field details
+    # The 'input_map' keys are the internal Scratch input names, values are regex group indices.
+    # The 'field_map' keys are the internal Scratch field names, values are regex group indices.
+    # 'condition_opcode' is for 'if' blocks that take a specific boolean reporter.
+    pseudo_code_to_opcode_map = {
+        re.compile(r"when green flag clicked"): {"opcode": "event_whenflagclicked"},
+        re.compile(r"go to x: \((.+?)\) y: \((.+?)\)"): {"opcode": "motion_gotoxy", "input_map": {"X": 0, "Y": 1}},
+        re.compile(r"set \[(.+?) v\] to (.+)"): {"opcode": "data_setvariableto", "field_map": {"VARIABLE": 0}, "input_map": {"VALUE": 1}},
+        re.compile(r"show variable \[(.+?) v\]"): {"opcode": "data_showvariable", "field_map": {"VARIABLE": 0}},
+        re.compile(r"forever"): {"opcode": "control_forever"},
+        re.compile(r"glide \((.+?)\) seconds to x: \((.+?)\) y: \((.+?)\)"): {"opcode": "motion_glidesecstoxy", "input_map": {"SECS": 0, "X": 1, "Y": 2}},
+        re.compile(r"if <\((.+)\) < \((.+)\)> then"): {"opcode": "control_if", "condition_type": "operator_lt", "condition_input_map": {"OPERAND1": 0, "OPERAND2": 1}},
+        re.compile(r"set x to \((.+?)\)"): {"opcode": "motion_setx", "input_map": {"X": 0}},
+        re.compile(r"if <touching \[(.+?) v\]\?> then"): {"opcode": "control_if", "condition_type": "sensing_touchingobject", "condition_field_map": {"TOUCHINGOBJECTMENU": 0}},
+        re.compile(r"broadcast \[(.+?) v\]"): {"opcode": "event_broadcast", "input_map": {"BROADCAST_INPUT": 0}},
+        re.compile(r"stop \[(.+?) v\]"): {"opcode": "control_stop", "field_map": {"STOP_OPTION": 0}},
+        re.compile(r"end"): {"opcode": "end_block"}, # Special marker for script end/C-block end
+    }
+
+    # Create a reverse lookup for reporter block opcodes based on their pseudo-code representation
+    reporter_opcode_lookup = {}
+    for opcode, definition in all_block_definitions.items():
+        if definition.get("block_shape") == "Reporter Block":
+            block_name = definition.get("block_name")
+            if block_name:
+                # Clean up block name for matching: remove parentheses, 'v' for variable, etc.
+                clean_name = block_name.replace("(", "").replace(")", "").replace("[", "").replace("]", "").replace(" v", "").strip()
+                reporter_opcode_lookup[clean_name] = opcode
+                # Add specific entries for common reporters if their pseudo-code differs from clean_name
+                if opcode == "motion_xposition":
+                    reporter_opcode_lookup["x position"] = opcode
+                elif opcode == "motion_yposition":
+                    reporter_opcode_lookup["y position"] = opcode
+                # Add more as needed based on pseudo-code patterns
+
+    for line_idx, raw_line in enumerate(lines):
+        current_line_indent = len(raw_line) - len(raw_line.lstrip())
+        line = raw_line.strip()
+
+        # Adjust block_stack based on current indent level
+        while block_stack and current_line_indent <= block_stack[-1][1]:
+            block_stack.pop()
+
+        matched_block_info = None
+        matched_values = None
+        
+        # Try to match the line against known block patterns
+        for pattern_regex, info in pseudo_code_to_opcode_map.items():
+            match = pattern_regex.match(line)
+            if match:
+                matched_block_info = info
+                matched_values = match.groups()
+                break
+        
+        if not matched_block_info:
+            print(f"Warning: Could not interpret line: '{line}' at line {line_idx + 1}")
+            continue
+
+        opcode = matched_block_info["opcode"]
+
+        # Handle 'end' block separately as it signifies closing a C-block
+        if opcode == "end_block":
+            # This 'end' matches the most recent C-block on the stack.
+            # The while loop at the beginning of the iteration already handles popping.
+            continue
+
+        parent_key = None
+        if block_stack:
+            parent_key = block_stack[-1][0] # The last block on the stack is the parent
+
+        # Create the new block instance
+        new_block_key, new_block_data = create_block_instance_for_parsing(
+            opcode, 
+            parent_key=parent_key, 
+            is_top_level=(parent_key is None)
+        )
+        if not new_block_key:
+            continue
+
+        # Link to previous block in the same script/nesting level
+        if block_stack:
+            # Update the 'next' of the previous block in the current scope
+            last_child_key_in_scope = block_stack[-1][2] if len(block_stack[-1]) > 2 else None
+            if last_child_key_in_scope and last_child_key_in_scope in updated_blocks:
+                updated_blocks[last_child_key_in_scope]["next"] = new_block_key
+            
+            # Update the last child in the current scope
+            block_stack[-1] = (block_stack[-1][0], block_stack[-1][1], new_block_key)
+        
+        # Populate inputs and fields based on matched_block_info and matched_values
+        if matched_values:
+            # Handle fields
+            if "field_map" in matched_block_info:
+                for field_name, group_idx in matched_block_info["field_map"].items():
+                    pseudo_field_value = matched_values[group_idx].replace(' v', '').strip()
+                    if field_name == "VARIABLE":
+                        # For variable fields, the actual variable ID is often derived or generated.
+                        # For now, we use a placeholder and the name.
+                        new_block_data["fields"][field_name] = [pseudo_field_value, f"`var_{pseudo_field_value}"]
+                    elif field_name == "STOP_OPTION":
+                        new_block_data["fields"][field_name] = [pseudo_field_value, None] # No ID needed for dropdown option
+                    else:
+                        new_block_data["fields"][field_name][0] = pseudo_field_value
+
+            # Handle inputs
+            if "input_map" in matched_block_info:
+                for input_name, group_idx in matched_block_info["input_map"].items():
+                    pseudo_input_value = matched_values[group_idx].strip()
+                    
+                    parsed_input_info = parse_and_link_input(new_block_key, new_block_data["inputs"][input_name][0], pseudo_input_value, input_name_in_parent=input_name)
+                    
+                    if parsed_input_info:
+                        if parsed_input_info[0] == 1: # It's a linked block (shadow reporter/boolean/menu)
+                            new_block_data["inputs"][input_name][1] = parsed_input_info[1] # Link block ID
+                            new_block_data["inputs"][input_name][0] = parsed_input_info[0] # Set type to 1 (block)
+                        else: # It's a literal value
+                            new_block_data["inputs"][input_name][1] = parsed_input_info[1]
+                            new_block_data["inputs"][input_name][0] = parsed_input_info[0] # Set appropriate type (4 for number, 10 for string)
+            
+            # Special handling for 'if' block conditions
+            if opcode == "control_if":
+                condition_type = matched_block_info.get("condition_type")
+                if condition_type:
+                    condition_block_key, condition_block_data = create_block_instance_for_parsing(
+                        condition_type, parent_key=new_block_key, is_shadow=True
+                    )
+                    if condition_block_key:
+                        new_block_data["inputs"]["CONDITION"] = [2, condition_block_key] # Type 2 for boolean block reference
+
+                        # Populate inputs for the condition block (e.g., operator_lt)
+                        if "condition_input_map" in matched_block_info:
+                            for cond_input_name, cond_group_idx in matched_block_info["condition_input_map"].items():
+                                pseudo_cond_value = matched_values[cond_group_idx].strip()
+                                parsed_cond_input_info = parse_and_link_input(condition_block_key, condition_block_data["inputs"][cond_input_name][0], pseudo_cond_value)
+                                if parsed_cond_input_info:
+                                    if parsed_cond_input_info[0] == 1:
+                                        condition_block_data["inputs"][cond_input_name][1] = parsed_cond_input_info[1]
+                                        condition_block_data["inputs"][cond_input_name][0] = parsed_cond_input_info[0]
+                                    else:
+                                        condition_block_data["inputs"][cond_input_name][1] = parsed_cond_input_info[1]
+                                        condition_block_data["inputs"][cond_input_name][0] = parsed_cond_input_info[0]
+                        
+                        # Populate fields for the condition block (e.g., sensing_touchingobject's menu)
+                        if "condition_field_map" in matched_block_info:
+                            for cond_field_name, cond_group_idx in matched_block_info["condition_field_map"].items():
+                                pseudo_cond_field_value = matched_values[cond_group_idx].replace(' v', '').strip()
+                                if cond_field_name == "TOUCHINGOBJECTMENU":
+                                    # Create the menu block for TOUCHINGOBJECTMENU
+                                    menu_opcode = "sensing_touchingobjectmenu"
+                                    menu_key, menu_data = create_block_instance_for_parsing(
+                                        menu_opcode,
+                                        parent_key=condition_block_key,
+                                        is_shadow=True
+                                    )
+                                    if menu_key:
+                                        condition_block_data["inputs"]["TOUCHINGOBJECTMENU"] = [1, menu_key] # Link to menu block
+                                        menu_data["fields"]["TOUCHINGOBJECTMENU"] = [pseudo_cond_field_value, None] # Set menu value
+                                    else:
+                                        print(f"Warning: Could not create menu block for touching object: '{pseudo_cond_field_value}'")
+                                else:
+                                    condition_block_data["fields"][cond_field_name][0] = pseudo_cond_field_value
+                    else:
+                        print(f"Warning: Could not create condition block '{condition_type}' for 'if' statement.")
+
+
+        # For C-blocks, push onto stack to track nesting
+        # 'control_if' is a C-block, but its 'next' is inside its substack.
+        # 'control_forever' is also a C-block.
+        if all_block_definitions[opcode].get("block_shape") == "C-Block" and opcode != "control_if":
+            # For C-blocks, the 'next' of the parent is usually null, and children start in 'SUBSTACK'
+            # We add the block to the stack, and its "next" will be its first child.
+            # The 'next' of the *last child* in its substack will point to the block after the C-block.
+            block_stack.append((new_block_key, current_line_indent, None)) # (parent_key, indent, last_child_key_in_substack)
+            
+            # For C-blocks, the first child is linked via the 'SUBSTACK' input
+            new_block_data["inputs"]["SUBSTACK"] = [2, None] # Placeholder for the first child block ID
+
+        # For 'if' blocks, the 'next' of the parent is usually null, and children start in 'SUBSTACK'
+        if opcode == "control_if":
+            block_stack.append((new_block_key, current_line_indent, None))
+            new_block_data["inputs"]["SUBSTACK"] = [2, None] # Placeholder for the first child block ID
+
+
+    # Final pass to ensure topLevel is correctly set for the very first block of a script
+    for key, block in updated_blocks.items():
+        if block.get("parent") is None and block.get("next") is not None:
+            block["topLevel"] = True
+        elif block.get("parent") is None and block.get("next") is None and block.get("opcode") == "event_whenflagclicked":
+             block["topLevel"] = True # Ensure hat blocks are always topLevel
+
+    return updated_blocks
+
+# --- Consolidated Block Definitions from all provided JSONs ---
+# This dictionary should contain ALL block definitions from your JSON files.
+# I'm using the provided definitions from the previous turn.
+all_block_definitions = {
+    # motion_block.json
+    "motion_movesteps": {
+        "block_name": "move () steps", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_movesteps",
+        "functionality": "Moves the sprite forward by the specified number of steps in the direction it is currently facing. A positive value moves it forward, and a negative value moves it backward.",
+        "inputs": {"STEPS": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_turnright": {
+        "block_name": "turn right () degrees", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_turnright",
+        "functionality": "Turns the sprite clockwise by the specified number of degrees.",
+        "inputs": {"DEGREES": [1, [4, "15"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_turnleft": {
+        "block_name": "turn left () degrees", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_turnleft",
+        "functionality": "Turns the sprite counter-clockwise by the specified number of degrees.",
+        "inputs": {"DEGREES": [1, [4, "15"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_goto": {
+        "block_name": "go to ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_goto",
+        "functionality": "Moves the sprite to a specified location, which can be a random position or at the mouse pointer or another to the sprite.",
+        "inputs": {"TO": [1, "motion_goto_menu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_goto_menu": {
+        "block_name": "go to menu", "block_type": "Motion", "block_shape": "Reporter Block", "op_code": "motion_goto_menu",
+        "functionality": "Menu for go to block.",
+        "inputs": {}, "fields": {"TO": ["_random_", None]}, "shadow": True, "topLevel": False
+    },
+    "motion_gotoxy": {
+        "block_name": "go to x: () y: ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_gotoxy",
+        "functionality": "Moves the sprite to the specified X and Y coordinates on the stage.",
+        "inputs": {"X": [1, [4, "0"]], "Y": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_glideto": {
+        "block_name": "glide () secs to ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_glideto",
+        "functionality": "Glides the sprite smoothly to a specified location (random position, mouse pointer, or another sprite) over a given number of seconds.",
+        "inputs": {"SECS": [1, [4, "1"]], "TO": [1, "motion_glideto_menu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_glideto_menu": {
+        "block_name": "glide to menu", "block_type": "Motion", "block_shape": "Reporter Block", "op_code": "motion_glideto_menu",
+        "functionality": "Menu for glide to block.",
+        "inputs": {}, "fields": {"TO": ["_random_", None]}, "shadow": True, "topLevel": False
+    },
+    "motion_glidesecstoxy": {
+        "block_name": "glide () secs to x: () y: ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_glidesecstoxy",
+        "functionality": "Glides the sprite smoothly to the specified X and Y coordinates over a given number of seconds.",
+        "inputs": {"SECS": [1, [4, "1"]], "X": [1, [4, "0"]], "Y": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_pointindirection": {
+        "block_name": "point in direction ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_pointindirection",
+        "functionality": "Sets the sprite's direction to a specified angle in degrees (0 = up, 90 = right, 180 = down, -90 = left).",
+        "inputs": {"DIRECTION": [1, [8, "90"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_pointtowards": {
+        "block_name": "point towards ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_pointtowards",
+        "functionality": "Points the sprite towards the mouse pointer or another specified sprite.",
+        "inputs": {"TOWARDS": [1, "motion_pointtowards_menu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_pointtowards_menu": {
+        "block_name": "point towards menu", "block_type": "Motion", "block_shape": "Reporter Block", "op_code": "motion_pointtowards_menu",
+        "functionality": "Menu for point towards block.",
+        "inputs": {}, "fields": {"TOWARDS": ["_mouse_", None]}, "shadow": True, "topLevel": False
+    },
+    "motion_changexby": {
+        "block_name": "change x by ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_changexby",
+        "functionality": "Changes the sprite's X-coordinate by the specified amount, moving it horizontally.",
+        "inputs": {"DX": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_setx": {
+        "block_name": "set x to ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_setx",
+        "functionality": "Sets the sprite's X-coordinate to a specific value, placing it at a precise horizontal position.",
+        "inputs": {"X": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_changeyby": {
+        "block_name": "change y by ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_changeyby",
+        "functionality": "Changes the sprite's Y-coordinate by the specified amount, moving it vertically.",
+        "inputs": {"DY": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_sety": {
+        "block_name": "set y to ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_sety",
+        "functionality": "Sets the sprite's Y-coordinate to a specific value, placing it at a precise vertical position.",
+        "inputs": {"Y": [1, [4, "0"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_ifonedgebounce": {
+        "block_name": "if on edge, bounce", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_ifonedgebounce",
+        "functionality": "Reverses the sprite's direction if it touches the edge of the stage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_setrotationstyle": {
+        "block_name": "set rotation style ()", "block_type": "Motion", "block_shape": "Stack Block", "op_code": "motion_setrotationstyle",
+        "functionality": "Determines how the sprite rotates: 'left-right' (flips horizontally), 'don't rotate' (stays facing one direction), or 'all around' (rotates freely).",
+        "inputs": {}, "fields": {"STYLE": ["left-right", None]}, "shadow": False, "topLevel": True
+    },
+    "motion_xposition": {
+        "block_name": "(x position)", "block_type": "Motion", "block_shape": "Reporter Block", "op_code": "motion_xposition",
+        "functionality": "Reports the current X-coordinate of the sprite.[NOTE: not used in stage/backdrops]",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_yposition": {
+        "block_name": "(y position)", "block_type": "Motion", "block_shape": "Reporter Block", "op_code": "motion_yposition",
+        "functionality": "Reports the current Y coordinate of the sprite on the stage.[NOTE: not used in stage/backdrops]",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "motion_direction": {
+        "block_name": "(direction)", "block_type": "Motion", "block_shape": "Reporter Block", "op_code": "motion_direction",
+        "functionality": "Reports the current direction of the sprite in degrees (0 = up, 90 = right, 180 = down, -90 = left).[NOTE: not used in stage/backdrops]",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+
+    # control_block.json
+    "control_wait": {
+        "block_name": "wait () seconds", "block_type": "Control", "block_shape": "Stack Block", "op_code": "control_wait",
+        "functionality": "Pauses the script for a specified duration.",
+        "inputs": {"DURATION": [1, [5, "1"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_repeat": {
+        "block_name": "repeat ()", "block_type": "Control", "block_shape": "C-Block", "op_code": "control_repeat",
+        "functionality": "Repeats the blocks inside it a specified number of times.",
+        "inputs": {"TIMES": [1, [6, "10"]], "SUBSTACK": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_forever": {
+        "block_name": "forever", "block_type": "Control", "block_shape": "C-Block", "op_code": "control_forever",
+        "functionality": "Continuously runs the blocks inside it.",
+        "inputs": {"SUBSTACK": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_if": {
+        "block_name": "if <> then", "block_type": "Control", "block_shape": "C-Block", "op_code": "control_if",
+        "functionality": "Executes the blocks inside it only if the specified boolean condition is true. [NOTE: it takes boolean blocks as input]",
+        "inputs": {"CONDITION": [2, None], "SUBSTACK": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_if_else": {
+        "block_name": "if <> then else", "block_type": "Control", "block_shape": "C-Block", "op_code": "control_if_else",
+        "functionality": "Executes one set of blocks if the specified boolean condition is true, and a different set of blocks if the condition is false. [NOTE: it takes boolean blocks as input]",
+        "inputs": {"CONDITION": [2, None], "SUBSTACK": [2, None], "SUBSTACK2": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_wait_until": {
+        "block_name": "wait until <>", "block_type": "Control", "block_shape": "Stack Block", "op_code": "control_wait_until",
+        "functionality": "Pauses the script until the specified boolean condition becomes true. [NOTE: it takes boolean blocks as input]",
+        "inputs": {"CONDITION": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_repeat_until": {
+        "block_name": "repeat until <>", "block_type": "Control", "block_shape": "C-Block", "op_code": "control_repeat_until",
+        "functionality": "Repeats the blocks inside it until the specified boolean condition becomes true. [NOTE: it takes boolean blocks as input]",
+        "inputs": {"CONDITION": [2, None], "SUBSTACK": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_stop": {
+        "block_name": "stop [v]", "block_type": "Control", "block_shape": "Cap Block", "op_code": "control_stop",
+        "functionality": "Halts all scripts, only the current script, or other scripts within the same sprite. Its shape can dynamically change based on the selected option.",
+        "inputs": {}, "fields": {"STOP_OPTION": ["all", None]}, "shadow": False, "topLevel": True, "mutation": {"tagName": "mutation", "children": [], "hasnext": "false"}
+    },
+    "control_start_as_clone": {
+        "block_name": "When I Start as a Clone", "block_type": "Control", "block_shape": "Hat Block", "op_code": "control_start_as_clone",
+        "functionality": "This Hat block initiates the script when a clone of the sprite is created. It defines the behavior of individual clones.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_create_clone_of": {
+        "block_name": "create clone of ()", "block_type": "Control", "block_shape": "Stack Block", "op_code": "control_create_clone_of",
+        "functionality": "Generates a copy, or clone, of a specified sprite (or 'myself' for the current sprite).",
+        "inputs": {"CLONE_OPTION": [1, "control_create_clone_of_menu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "control_create_clone_of_menu": {
+        "block_name": "create clone of menu", "block_type": "Control", "block_shape": "Reporter Block", "op_code": "control_create_clone_of_menu",
+        "functionality": "Menu for create clone of block.",
+        "inputs": {}, "fields": {"CLONE_OPTION": ["_myself_", None]}, "shadow": True, "topLevel": False
+    },
+    "control_delete_this_clone": {
+        "block_name": "delete this clone", "block_type": "Control", "block_shape": "Cap Block", "op_code": "control_delete_this_clone",
+        "functionality": "Removes the clone that is executing it from the stage.",
+        "inputs":None, "fields": {}, "shadow": False, "topLevel": True
+    },
+
+    # data_block.json
+    "data_setvariableto": {
+        "block_name": "set [my variable v] to ()", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_setvariableto",
+        "functionality": "Assigns a specific value (number, string, or boolean) to a variable.",
+        "inputs": {"VALUE": [1, [10, "0"]]}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True
+    },
+    "data_changevariableby": {
+        "block_name": "change [my variable v] by ()", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_changevariableby",
+        "functionality": "Increases or decreases a variable's numerical value by a specified amount.",
+        "inputs": {"VALUE": [1, [4, "1"]]}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True
+    },
+    "data_showvariable": {
+        "block_name": "show variable [my variable v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_showvariable",
+        "functionality": "Makes a variable's monitor visible on the stage.",
+        "inputs": {}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True
+    },
+    "data_hidevariable": {
+        "block_name": "hide variable [my variable v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_hidevariable",
+        "functionality": "Hides a variable's monitor from the stage.",
+        "inputs": {}, "fields": {"VARIABLE": ["my variable", "`jEk@4|i[#Fk?(8x)AV.-my variable"]}, "shadow": False, "topLevel": True
+    },
+    "data_addtolist": {
+        "block_name": "add () to [my list v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_addtolist",
+        "functionality": "Appends an item to the end of a list.",
+        "inputs": {"ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_deleteoflist": {
+        "block_name": "delete () of [my list v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_deleteoflist",
+        "functionality": "Removes an item from a list by its index or by selecting 'all' items.",
+        "inputs": {"INDEX": [1, [7, "1"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_deletealloflist": {
+        "block_name": "delete all of [my list v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_deletealloflist",
+        "functionality": "Removes all items from a list.",
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_insertatlist": {
+        "block_name": "insert () at () of [my list v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_insertatlist",
+        "functionality": "Inserts an item at a specific position within a list.",
+        "inputs": {"ITEM": [1, [10, "thing"]], "INDEX": [1, [7, "1"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_replaceitemoflist": {
+        "block_name": "replace item () of [my list v] with ()", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_replaceitemoflist",
+        "functionality": "Replaces an item at a specific position in a list with a new value.",
+        "inputs": {"INDEX": [1, [7, "1"]], "ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_itemoflist": {
+        "block_name": "(item (2) of [myList v])", "block_type": "Data", "block_shape": "Reporter Block", "op_code": "data_itemoflist",
+        "functionality": "Reports the item located at a specific position in a list.",
+        "inputs": {"INDEX": [1, [7, "1"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_itemnumoflist": {
+        "block_name": "(item # of [Dog] in [myList v])", "block_type": "Data", "block_shape": "Reporter Block", "op_code": "data_itemnumoflist",
+        "functionality": "Reports the index number of the first occurrence of a specified item in a list. If the item is not found, it reports 0.",
+        "inputs": {"ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_lengthoflist": {
+        "block_name": "(length of [myList v])", "block_type": "Data", "block_shape": "Reporter Block", "op_code": "data_lengthoflist",
+        "functionality": "Provides the total number of items contained in a list.",
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_listcontainsitem": {
+        "block_name": "<[my list v] contains ()?>", "block_type": "Data", "block_shape": "Boolean Block", "op_code": "data_listcontainsitem",
+        "functionality": "Checks if a list includes a specific item.",
+        "inputs": {"ITEM": [1, [10, "thing"]]}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_showlist": {
+        "block_name": "show list [my list v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_showlist",
+        "functionality": "Makes a list's monitor visible on the stage.",
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_hidelist": {
+        "block_name": "hide list [my list v]", "block_type": "Data", "block_shape": "Stack Block", "op_code": "data_hidelist",
+        "functionality": "Hides a list's monitor from the stage.",
+        "inputs": {}, "fields": {"LIST": ["MY_LIST", "o6`kIhtT{xWH+rX(5d,A"]}, "shadow": False, "topLevel": True
+    },
+    "data_variable": { # This is a reporter block for a variable's value
+        "block_name": "[variable v]", "block_type": "Data", "block_shape": "Reporter Block", "op_code": "data_variable",
+        "functionality": "Provides the current value stored in a variable.",
+        "inputs": {}, "fields": {"VARIABLE": ["my variable", None]}, "shadow": True, "topLevel": False
+    },
+
+    # event_block.json
+    "event_whenflagclicked": {
+        "block_name": "when green flag pressed", "block_type": "Events", "op_code": "event_whenflagclicked", "block_shape": "Hat Block",
+        "functionality": "This Hat block initiates the script when the green flag is clicked, serving as the common starting point for most Scratch projects.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "event_whenkeypressed": {
+        "block_name": "when () key pressed", "block_type": "Events", "op_code": "event_whenkeypressed", "block_shape": "Hat Block",
+        "functionality": "This Hat block initiates the script when a specified keyboard key is pressed.",
+        "inputs": {}, "fields": {"KEY_OPTION": ["space", None]}, "shadow": False, "topLevel": True
+    },
+    "event_whenthisspriteclicked": {
+        "block_name": "when this sprite clicked", "block_type": "Events", "op_code": "event_whenthisspriteclicked", "block_shape": "Hat Block",
+        "functionality": "This Hat block starts the script when the sprite itself is clicked.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "event_whenbackdropswitchesto": {
+        "block_name": "when backdrop switches to ()", "block_type": "Events", "op_code": "event_whenbackdropswitchesto", "block_shape": "Hat Block",
+        "functionality": "This Hat block triggers the script when the stage backdrop changes to a specified backdrop.",
+        "inputs": {}, "fields": {"BACKDROP": ["backdrop1", None]}, "shadow": False, "topLevel": True
+    },
+    "event_whengreaterthan": {
+        "block_name": "when () > ()", "block_type": "Events", "op_code": "event_whengreaterthan", "block_shape": "Hat Block",
+        "functionality": "This Hat block starts the script when a certain value (e.g., loudness from a microphone, or the timer) exceeds a defined threshold.",
+        "inputs": {"VALUE": [1, [4, "10"]]}, "fields": {"WHENGREATERTHANMENU": ["LOUDNESS", None]}, "shadow": False, "topLevel": True
+    },
+    "event_whenbroadcastreceived": {
+        "block_name": "when I receive ()", "block_type": "Events", "op_code": "event_whenbroadcastreceived", "block_shape": "Hat Block",
+        "functionality": "This Hat block initiates the script upon the reception of a specific broadcast message. This mechanism facilitates indirect communication between sprites or the stage.",
+        "inputs": {}, "fields": {"BROADCAST_OPTION": ["message1", "5O!nei;S$!c!=hCT}0:a"]}, "shadow": False, "topLevel": True
+    },
+    "event_broadcast": {
+        "block_name": "broadcast ()", "block_type": "Events", "block_shape": "Stack Block", "op_code": "event_broadcast",
+        "functionality": "Sends a broadcast message throughout the Scratch program, activating any 'when I receive ()' blocks that are set to listen for that message, enabling indirect communication.",
+        "inputs": {"BROADCAST_INPUT": [1, [11, "message1", "5O!nei;S$!c!=hCT}0:a"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "event_broadcastandwait": {
+        "block_name": "broadcast () and wait", "block_type": "Events", "block_shape": "Stack Block", "op_code": "event_broadcastandwait",
+        "functionality": "Sends a broadcast message and pauses the current script until all other scripts activated by that broadcast have completed their execution, ensuring sequential coordination.",
+        "inputs": {"BROADCAST_INPUT": [1, [11, "message1", "5O!nei;S$!c!=hCT}0:a"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+
+    # looks_block.json
+    "looks_sayforsecs": {
+        "block_name": "say () for () seconds", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_sayforsecs",
+        "functionality": "Displays a speech bubble containing specified text for a set duration.",
+        "inputs": {"MESSAGE": [1, [10, "Hello!"]], "SECS": [1, [4, "2"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_say": {
+        "block_name": "say ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_say",
+        "functionality": "Displays a speech bubble with the specified text indefinitely until another 'say' or 'think' block is activated.",
+        "inputs": {"MESSAGE": [1, [10, "Hello!"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_thinkforsecs": {
+        "block_name": "think () for () seconds", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_thinkforsecs",
+        "functionality": "Displays a thought bubble containing specified text for a set duration.",
+        "inputs": {"MESSAGE": [1, [10, "Hmm..."]], "SECS": [1, [4, "2"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_think": {
+        "block_name": "think ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_think",
+        "functionality": "Displays a thought bubble with the specified text indefinitely until another 'say' or 'think' block is activated.",
+        "inputs": {"MESSAGE": [1, [10, "Hmm..."]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_switchcostumeto": {
+        "block_name": "switch costume to ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_switchcostumeto",
+        "functionality": "Alters the sprite's appearance to a designated costume.",
+        "inputs": {"COSTUME": [1, "looks_costume"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_costume": {
+        "block_name": "costume menu", "block_type": "Looks", "block_shape": "Reporter Block", "op_code": "looks_costume",
+        "functionality": "Menu for switch costume to block.",
+        "inputs": {}, "fields": {"COSTUME": ["costume1", None]}, "shadow": True, "topLevel": False
+    },
+    "looks_nextcostume": {
+        "block_name": "next costume", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_nextcostume",
+        "functionality": "Switches the sprite's costume to the next one in its costume list. If it's the last costume, it cycles back to the first.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_switchbackdropto": {
+        "block_name": "switch backdrop to ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_switchbackdropto",
+        "functionality": "Changes the stage's backdrop to a specified backdrop.",
+        "inputs": {"BACKDROP": [1, "looks_backdrops"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_backdrops": {
+        "block_name": "backdrop menu", "block_type": "Looks", "block_shape": "Reporter Block", "op_code": "looks_backdrops",
+        "functionality": "Menu for switch backdrop to block.",
+        "inputs": {}, "fields": {"BACKDROP": ["backdrop1", None]}, "shadow": True, "topLevel": False
+    },
+    "looks_switchbackdroptowait": {
+        "block_name": "switch backdrop to () and wait", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_switchbackdroptowait",
+        "functionality": "Changes the stage's backdrop to a specified backdrop and pauses the script until any 'When backdrop switches to' scripts for that backdrop have finished.",
+        "inputs": {"BACKDROP": [1, "looks_backdrops"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_nextbackdrop": {
+        "block_name": "next backdrop", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_nextbackdrop",
+        "functionality": "Switches the stage's backdrop to the next one in its backdrop list. If it's the last backdrop, it cycles back to the first.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_changesizeby": {
+        "block_name": "change size by ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_changesizeby",
+        "functionality": "Changes the sprite's size by a specified percentage. Positive values make it larger, negative values make it smaller.",
+        "inputs": {"CHANGE": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_setsizeto": {
+        "block_name": "set size to () %", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_setsizeto",
+        "functionality": "Sets the sprite's size to a specific percentage of its original size.",
+        "inputs": {"SIZE": [1, [4, "100"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_changeeffectby": {
+        "block_name": "change () effect by ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_changeeffectby",
+        "functionality": "Changes a visual effect on the sprite by a specified amount (e.g., color, fisheye, whirl, pixelate, mosaic, brightness, ghost).",
+        "inputs": {"CHANGE": [1, [4, "25"]]}, "fields": {"EFFECT": ["COLOR", None]}, "shadow": False, "topLevel": True
+    },
+    "looks_seteffectto": {
+        "block_name": "set () effect to ()", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_seteffectto",
+        "functionality": "Sets a visual effect on the sprite to a specific value.",
+        "inputs": {"VALUE": [1, [4, "0"]]}, "fields": {"EFFECT": ["COLOR", None]}, "shadow": False, "topLevel": True
+    },
+    "looks_cleargraphiceffects": {
+        "block_name": "clear graphic effects", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_cleargraphiceffects",
+        "functionality": "Removes all visual effects applied to the sprite.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_show": {
+        "block_name": "show", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_show",
+        "functionality": "Makes the sprite visible on the stage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_hide": {
+        "block_name": "hide", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_hide",
+        "functionality": "Makes the sprite invisible on the stage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "looks_gotofrontback": {
+        "block_name": "go to () layer", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_gotofrontback",
+        "functionality": "Moves the sprite to the front-most or back-most layer of other sprites on the stage.",
+        "inputs": {}, "fields": {"FRONT_BACK": ["front", None]}, "shadow": False, "topLevel": True
+    },
+    "looks_goforwardbackwardlayers": {
+        "block_name": "go () layers", "block_type": "Looks", "block_shape": "Stack Block", "op_code": "looks_goforwardbackwardlayers",
+        "functionality": "Moves the sprite forward or backward a specified number of layers in relation to other sprites.",
+        "inputs": {"NUM": [1, [7, "1"]]}, "fields": {"FORWARD_BACKWARD": ["forward", None]}, "shadow": False, "topLevel": True
+    },
+    "looks_costumenumbername": {
+        "block_name": "(costume ())", "block_type": "Looks", "block_shape": "Reporter Block", "op_code": "looks_costumenumbername",
+        "functionality": "Reports the current costume's number or name.",
+        "inputs": {}, "fields": {"NUMBER_NAME": ["number", None]}, "shadow": False, "topLevel": True
+    },
+    "looks_backdropnumbername": {
+        "block_name": "(backdrop ())", "block_type": "Looks", "block_shape": "Reporter Block", "op_code": "looks_backdropnumbername",
+        "functionality": "Reports the current backdrop's number or name.",
+        "inputs": {}, "fields": {"NUMBER_NAME": ["number", None]}, "shadow": False, "topLevel": True
+    },
+    "looks_size": {
+        "block_name": "(size)", "block_type": "Looks", "block_shape": "Reporter Block", "op_code": "looks_size",
+        "functionality": "Reports the current size of the sprite as a percentage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+
+    # operator_block.json
+    "operator_add": {
+        "block_name": "(() + ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_add",
+        "functionality": "Adds two numerical values.",
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_subtract": {
+        "block_name": "(() - ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_subtract",
+        "functionality": "Subtracts the second numerical value from the first.",
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_multiply": {
+        "block_name": "(() * ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_multiply",
+        "functionality": "Multiplies two numerical values.",
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_divide": {
+        "block_name": "(() / ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_divide",
+        "functionality": "Divides the first numerical value by the second.",
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_random": {
+        "block_name": "(pick random () to ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_random",
+        "functionality": "Generates a random integer within a specified inclusive range.",
+        "inputs": {"FROM": [1, [4, "1"]], "TO": [1, [4, "10"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_gt": {
+        "block_name": "<() > ()>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_gt",
+        "functionality": "Checks if the first value is greater than the second.",
+        "inputs": {"OPERAND1": [1, [10, ""]], "OPERAND2": [1, [10, "50"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_lt": {
+        "block_name": "<() < ()>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_lt",
+        "functionality": "Checks if the first value is less than the second.",
+        "inputs": {"OPERAND1": [1, [10, ""]], "OPERAND2": [1, [10, "50"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_equals": {
+        "block_name": "<() = ()>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_equals",
+        "functionality": "Checks if two values are equal.",
+        "inputs": {"OPERAND1": [1, [10, ""]], "OPERAND2": [1, [10, "50"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_and": {
+        "block_name": "<<> and <>>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_and",
+        "functionality": "Returns 'true' if both provided Boolean conditions are 'true'.",
+        "inputs": {"OPERAND1": [2, None], "OPERAND2": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_or": {
+        "block_name": "<<> or <>>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_or",
+        "functionality": "Returns 'true' if at least one of the provided Boolean conditions is 'true'.",
+        "inputs": {"OPERAND1": [2, None], "OPERAND2": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_not": {
+        "block_name": "<not <>>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_not",
+        "functionality": "Returns 'true' if the provided Boolean condition is 'false', and 'false' if it is 'true'.",
+        "inputs": {"OPERAND": [2, None]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_join": {
+        "block_name": "(join ()())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_join",
+        "functionality": "Concatenates two strings or values into a single string.",
+        "inputs": {"STRING1": [1, [10, "apple "]], "STRING2": [1, [10, "banana"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_letterof": {
+        "block_name": "letter () of ()", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_letterof",
+        "functionality": "Reports the character at a specific numerical position within a string.",
+        "inputs": {"LETTER": [1, [6, "1"]], "STRING": [1, [10, "apple"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_length": {
+        "block_name": "(length of ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_length",
+        "functionality": "Reports the total number of characters in a given string.",
+        "inputs": {"STRING": [1, [10, "apple"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_contains": {
+        "block_name": "<() contains ()?>", "block_type": "operator", "block_shape": "Boolean Block", "op_code": "operator_contains",
+        "functionality": "Checks if one string contains another string.",
+        "inputs": {"STRING1": [1, [10, "apple"]], "STRING2": [1, [10, "a"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_mod": {
+        "block_name": "(() mod ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_mod",
+        "functionality": "Reports the remainder when the first number is divided by the second.",
+        "inputs": {"NUM1": [1, [4, ""]], "NUM2": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_round": {
+        "block_name": "(round ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_round",
+        "functionality": "Rounds a numerical value to the nearest integer.",
+        "inputs": {"NUM": [1, [4, ""]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "operator_mathop": {
+        "block_name": "(() of ())", "block_type": "operator", "block_shape": "Reporter Block", "op_code": "operator_mathop",
+        "functionality": "Performs various mathematical functions (e.g., absolute value, square root, trigonometric functions).",
+        "inputs": {"NUM": [1, [4, ""]]}, "fields": {"OPERATOR": ["abs", None]}, "shadow": False, "topLevel": True
+    },
+
+    # sensing_block.json
+    "sensing_touchingobject": {
+        "block_name": "<touching [edge v]?>", "block_type": "Sensing", "op_code": "sensing_touchingobject", "block_shape": "Boolean Block",
+        "functionality": "Checks if its sprite is touching the mouse-pointer, edge, or another specified sprite.",
+        "inputs": {"TOUCHINGOBJECTMENU": [1, "sensing_touchingobjectmenu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_touchingobjectmenu": {
+        "block_name": "touching object menu", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_touchingobjectmenu",
+        "functionality": "Menu for touching object block.",
+        "inputs": {}, "fields": {"TOUCHINGOBJECTMENU": ["_mouse_", None]}, "shadow": True, "topLevel": False
+    },
+    "sensing_touchingcolor": {
+        "block_name": "<touching color ()?>", "block_type": "Sensing", "op_code": "sensing_touchingcolor", "block_shape": "Boolean Block",
+        "functionality": "Checks whether its sprite is touching a specified color.",
+        "inputs": {"COLOR": [1, [9, "#55b888"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_coloristouchingcolor": {
+        "block_name": "<color () is touching ()?>", "block_type": "Sensing", "op_code": "sensing_coloristouchingcolor", "block_shape": "Boolean Block",
+        "functionality": "Checks whether a specific color on its sprite is touching another specified color on the stage or another sprite.",
+        "inputs": {"COLOR1": [1, [9, "#d019f2"]], "COLOR2": [1, [9, "#2b0de3"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_askandwait": {
+        "block_name": "Ask () and Wait", "block_type": "Sensing", "block_shape": "Stack Block", "op_code": "sensing_askandwait",
+        "functionality": "Displays an input box with specified text at the bottom of the screen, allowing users to input text, which is stored in the 'Answer' block.",
+        "inputs": {"QUESTION": [1, [10, "What's your name?"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_answer": {
+        "block_name": "(answer)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_answer",
+        "functionality": "Holds the most recent text inputted using the 'Ask () and Wait' block.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_keypressed": {
+        "block_name": "<key () pressed?>", "block_type": "Sensing", "op_code": "sensing_keypressed", "block_shape": "Boolean Block",
+        "functionality": "Checks if a specified keyboard key is currently being pressed.",
+        "inputs": {"KEY_OPTION": [1, "sensing_keyoptions"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_keyoptions": {
+        "block_name": "key options menu", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_keyoptions",
+        "functionality": "Menu for key pressed block.",
+        "inputs": {}, "fields": {"KEY_OPTION": ["space", None]}, "shadow": True, "topLevel": False
+    },
+    "sensing_mousedown": {
+        "block_name": "<mouse down?>", "block_type": "Sensing", "op_code": "sensing_mousedown", "block_shape": "Boolean Block",
+        "functionality": "Checks if the computer mouse's primary button is being clicked while the cursor is over the stage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_mousex": {
+        "block_name": "(mouse x)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_mousex",
+        "functionality": "Reports the mouse-pointer’s current X position on the stage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_mousey": {
+        "block_name": "(mouse y)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_mousey",
+        "functionality": "Reports the mouse-pointer’s current Y position on the stage.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_setdragmode": {
+        "block_name": "set drag mode [draggable v]", "block_type": "Sensing", "block_shape": "Stack Block", "op_code": "sensing_setdragmode",
+        "functionality": "Sets whether the sprite can be dragged by the mouse on the stage.",
+        "inputs": {}, "fields": {"DRAG_MODE": ["draggable", None]}, "shadow": False, "topLevel": True
+    },
+    "sensing_loudness": {
+        "block_name": "(loudness)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_loudness",
+        "functionality": "Reports the loudness of noise received by a microphone on a scale of 0 to 100.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_timer": {
+        "block_name": "(timer)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_timer",
+        "functionality": "Reports the elapsed time since Scratch was launched or the timer was reset, increasing by 1 every second.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_resettimer": {
+        "block_name": "Reset Timer", "block_type": "Sensing", "block_shape": "Stack Block", "op_code": "sensing_resettimer",
+        "functionality": "Sets the timer’s value back to 0.0.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_of": {
+        "block_name": "(() of ())", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_of",
+        "functionality": "Reports a specified value (e.g., x position, direction, costume number) of a specified sprite or the Stage to be accessed in current sprite or stage.",
+        "inputs": {"OBJECT": [1, "sensing_of_object_menu"]}, "fields": {"PROPERTY": ["backdrop #", None]}, "shadow": False, "topLevel": True
+    },
+    "sensing_of_object_menu": {
+        "block_name": "of object menu", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_of_object_menu",
+        "functionality": "Menu for of block.",
+        "inputs": {}, "fields": {"OBJECT": ["_stage_", None]}, "shadow": True, "topLevel": False
+    },
+    "sensing_current": {
+        "block_name": "(current ())", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_current",
+        "functionality": "Reports the current local year, month, date, day of the week, hour, minutes, or seconds.",
+        "inputs": {}, "fields": {"CURRENTMENU": ["YEAR", None]}, "shadow": False, "topLevel": True
+    },
+    "sensing_dayssince2000": {
+        "block_name": "(days since 2000)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_dayssince2000",
+        "functionality": "Reports the number of days (and fractions of a day) since 00:00:00 UTC on January 1, 2000.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sensing_username": {
+        "block_name": "(username)", "block_type": "Sensing", "block_shape": "Reporter Block", "op_code": "sensing_username",
+        "functionality": "Reports the username of the user currently logged into Scratch. If no user is logged in, it reports nothing.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+
+    # sound_block.json
+    "sound_playuntildone": {
+        "block_name": "play sound () until done", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_playuntildone",
+        "functionality": "Plays a specified sound and pauses the script's execution until the sound has completed.",
+        "inputs": {"SOUND_MENU": [1, "sound_sounds_menu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sound_sounds_menu": {
+        "block_name": "sound menu", "block_type": "Sound", "block_shape": "Reporter Block", "op_code": "sound_sounds_menu",
+        "functionality": "Menu for sound blocks.",
+        "inputs": {}, "fields": {"SOUND_MENU": ["Meow", None]}, "shadow": True, "topLevel": False
+    },
+    "sound_play": {
+        "block_name": "start sound ()", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_play",
+        "functionality": "Initiates playback of a specified sound without pausing the script, allowing other actions to proceed concurrently.",
+        "inputs": {"SOUND_MENU": [1, "sound_sounds_menu"]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sound_stopallsounds": {
+        "block_name": "stop all sounds", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_stopallsounds",
+        "functionality": "Stops all currently playing sounds.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sound_changeeffectby": {
+        "block_name": "change () effect by ()", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_changeeffectby",
+        "functionality": "Changes the project's sound effect by a specified amount.",
+        "inputs": {"VALUE": [1, [4, "10"]]}, "fields": {"EFFECT": ["PITCH", None]}, "shadow": False, "topLevel": True
+    },
+    "sound_seteffectto": {
+        "block_name": "set () effect to ()", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_seteffectto",
+        "functionality": "Sets the sound effect to a specific value.",
+        "inputs": {"VALUE": [1, [4, "100"]]}, "fields": {"EFFECT": ["PITCH", None]}, "shadow": False, "topLevel": True
+    },
+    "sound_cleareffects": {
+        "block_name": "clear sound effects", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_cleareffects",
+        "functionality": "Removes all sound effects applied to the sprite.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sound_changevolumeby": {
+        "block_name": "change volume by ()", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_changevolumeby",
+        "functionality": "Changes the project's sound volume by a specified amount.",
+        "inputs": {"VOLUME": [1, [4, "-10"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sound_setvolumeto": {
+        "block_name": "set volume to () %", "block_type": "Sound", "block_shape": "Stack Block", "op_code": "sound_setvolumeto",
+        "functionality": "Sets the sound volume to a specific percentage (0-100).",
+        "inputs": {"VOLUME": [1, [4, "100"]]}, "fields": {}, "shadow": False, "topLevel": True
+    },
+    "sound_volume": {
+        "block_name": "(volume)", "block_type": "Sound", "block_shape": "Reporter Block", "op_code": "sound_volume",
+        "functionality": "Reports the current volume level of the sprite.",
+        "inputs": {}, "fields": {}, "shadow": False, "topLevel": True
+    },
+}
+
+# Example input with opcodes for the initial generation
+initial_opcode_counts = [
+    {"opcode":"event_whenflagclicked","count":1},
+    {"opcode":"motion_gotoxy","count":1},
+    {"opcode":"motion_glidesecstoxy","count":1},
+    {"opcode":"motion_xposition","count":1},
+    {"opcode":"motion_setx","count":1},
+    {"opcode":"control_forever","count":1},
+    {"opcode":"control_if","count":1},
+    {"opcode":"control_stop","count":1},
+    {"opcode":"operator_lt","count":1},
+    {"opcode":"sensing_touchingobject","count":1}, # Changed from sensing_istouching
+    {"opcode":"sensing_touchingobjectmenu","count":1},
+    {"opcode":"event_broadcast","count":1},
+    {"opcode":"data_setvariableto","count":2},
+    {"opcode":"data_showvariable","count":2},
+]
+
+# Generate the initial blocks and get the opcode_occurrences
+generated_output_json, initial_opcode_occurrences = generate_blocks_from_opcodes(initial_opcode_counts, all_block_definitions)
+
+# Pseudo-code to interpret
+pseudo_code_input = """
+when green flag clicked
+  go to x: (240) y: (-135)
+  set [score v] to (1)
+  set [speed v] to (1)
+  show variable [score v]
+  show variable [speed v]
+  forever
+    glide (2) seconds to x: (-240) y: (-135)
+    if <((x position)) < (-235)> then
+      set x to (240)
+    end
+    if <touching [Sprite1 v]?> then
+      broadcast [Game Over v]
+      stop [all v]
+    end
+  end
+end
+"""
+
+# Interpret the pseudo-code and update the blocks, passing opcode_occurrences
+final_generated_blocks = interpret_pseudo_code_and_update_blocks(generated_output_json, pseudo_code_input, all_block_definitions, initial_opcode_occurrences)
+
+print(initial_opcode_occurrences)
+
+#print(json.dumps(final_generated_blocks, indent=2))
+# ```json
+# {
+#   "event_whenflagclicked_1": {
+#     "block_name": "when green flag pressed",
+#     "block_type": "Events",
+#     "op_code": "event_whenflagclicked",
+#     "block_shape": "Hat Block",
+#     "functionality": "This Hat block initiates the script when the green flag is clicked, serving as the common starting point for most Scratch projects.",
+#     "inputs": {},
+#     "fields": {},
+#     "shadow": false,
+#     "topLevel": true,
+#     "parent": null,
+#     "next": "motion_gotoxy_1"
+#   },
+#   "motion_gotoxy_1": {
+#     "block_name": "go to x: () y: ()",
+#     "block_type": "Motion",
+#     "op_code": "motion_gotoxy",
+#     "functionality": "Moves the sprite to the specified X and Y coordinates on the stage.",
+#     "inputs": {
+#       "X": [
+#         4,
+#         "240"
+#       ],
+#       "Y": [
+#         4,
+#         "-135"
+#       ]
+#     },
+#     "fields": {},
+#     "shadow": false,
+#     "topLevel": false,
+#     "parent": null,
+#     "next": "data_setvariableto_1"
+#   },
+#   "motion_glidesecstoxy_1": {
+#     "block_name": "glide () secs to x: () y: ()",
+#     "block_type": "Motion",
+#     "op_code": "motion_glidesecstoxy",
+#     "functionality": "Glides the sprite smoothly to the specified X and Y coordinates over a given number of seconds.",
+#     "inputs": {
+#       "SECS": [
+#         4,
+#         "2"
+#       ],
+#       "X": [
+#         4,
+#         "-240"
+#       ],
+#       "Y": [
+#         4,
+#         "-135"
+#       ]
+#     },
+#     "fields": {},
+#     "shadow": false,
+#     "topLevel": false,
+#     "parent": "control_forever_1",
+#     "next": "control_if_1"
+#   },
+#   "motion_xposition_1": {
+#     "block_name": "(x position)",
+#     "block_type": "Motion",
+#     "op_code": "motion_xposition",
+#     "functionality": "Reports the current X-coordinate of the sprite.[NOTE: not used in stage/backdrops]",
+#     "inputs": {},
+#     "fields": {},
+#     "shadow": true,
+#     "topLevel": false,
+#     "parent": "operator_lt_1",
+#     "next": null
+#   },
+#   "motion_setx_1": {
+#     "block_name": "set x to ()",
+#     "block_type": "Motion",
+#     "op_code": "motion_setx",
+#     "functionality": "Sets the sprite's X-coordinate to a specific value, placing it at a precise horizontal position.",
+#     "inputs": {
+#       "X": [
+#         4,
+#         "240"
+#       ]
+#     },
+#     "fields": {},
+#     "shadow": false,
+#     "topLevel": false,
+#     "parent": "control_if_1",
+#     "next": null
+#   },
+#   "control_forever_1": {
+#     "block_name": "forever",
+#     "block_type": "Control",
+#     "op_code": "control_forever",
+#     "functionality": "Continuously runs the blocks inside it.",
+#     "inputs": {
+#       "SUBSTACK": [
+#         2,
+#         "motion_glidesecstoxy_1"
+#       ]
+#     },
+#     "fields": {},
+#     "shadow": false,
+#     "topLevel": false,
+#     "parent": null,
+#     "next": null
+#   },
+#   "control_if_1": {
+#     "block_name": "if <> then",
+#     "block_type": "Control",
+#     "op_code": "control_if",
+#     "functionality": "Executes the blocks inside it only if the specified boolean condition is true. [NOTE: it takes boolean blocks as input]",
+#     "inputs": {
+#       "CONDITION": [
+#         2,
+#         "operator_lt_1"
+#       ],
+#       "SUBSTACK": [
+#         2,
+#         "motion_setx_1"
+#       ]
+#     },
+#     "fields": {},
+#     "shadow": false,
+#     "topLevel": false,
+#     "parent": "control_forever_1",
+#     "next": "control_if_2"
+#   },
+#   "control_stop_1": {
+#     "block_name": "stop [v]",
+#     "block_type": "Control",
+#     "op_code": "control_stop",
+#     "functionality": "Halts all scripts, only the current script, or other scripts within the same sprite. Its shape can dynamically change based on the selected option.",
+#     "inputs": {},
+#     "fields": {
+#       "STOP_OPTION": [
+#         "all",
+#         null
+#       ]
+#     },
+#     "shadow": false,
+#     "topLevel": false,
+#     "parent": "control_if_2",
+#     "mutation": {
+#       "tagName": "mutation",
+#       "children": [],
+#       "hasnext": "false"
+#     },
+#     "next": null
+#   },
+#   "operator_lt_1": {
+#     "block_name": "<() < ()>",
+#     "block_type": "operator",
+#     "op_code": "operator_lt",
+#     "functionality": "Checks if the first value is less than the second.",
+#     "inputs": {
+#       "OPERAND1": [
+#         1,
+#         "motion_xposition_1"
+#       ],
+#       "OPERAND2": [
+#         4,
+#         "-235"
+#       ]
+#     },
+#     "fields": {},
+#     "shadow": true,
+#     "topLevel": false,
+#     "parent": "control_if_1",
+#     "next": null
+#   },
+#   "sensing_touchingobject_1": {
+#     "block_name": "<touching [edge v]?>",
+#     "block_type": "Sensing",
+#     "op_code": "sensing_touchingobject",
+#     "functionality": "Checks if its sprite is touching the mouse-pointer, edge, or another specified sprite.",
+#     "inputs": {
+#       "TOUCHINGOBJECTMENU": [
+#         1,
+#         "sensing_touchingobjectmenu_1"
+#       ]
+#     },
+#     "fields": {},
+#     "shadow": true,
+#     "topLevel": false,
+#     "parent": "control_if_2",
+#     "next": null
+#   },
+#   "sensing_touchingobjectmenu_1": {
+#     "block_name": "touching object menu",
+#     "block_type": "Sensing",
+#     "op_code": "sensing_touchingobjectmenu",
+#     "functionality": "Menu for touching object block.",
+#     "inputs": {},
+#     "fields": {
+#       "TOUCHINGOBJECTMENU": [
+#         "Sprite1",
+#         null
+#       ]
+#     },
+#     "shadow": true,
+#     "topLevel": false,
+#     "parent": "sensing_touchingobject_1",
+#     "next": null
+#   },
+#   "event_broadcast_1": {
+#     "block_name": "broadcast ()",
+#     "block_type": "Events",
+#     "op_code": "event_broadcast",
+#     "functionality": "Sends a broadcast message throughout the Scratch program, activating any 'when I receive ()' blocks that are set to listen for that message, enabling indirect communication.",
+#     "inputs": {
+#       "BROADCAST_INPUT": [
+#         10,
+#         "Game Over"
+#       ]
+#     },
+#     "fields": {},
+#     "shadow": false,
+#     "topLevel": false,
+#     "parent": "control_if_2",
+#     "next": "control_stop_1"
+#   },
+#   "data_setvariableto_1": {
+#     "block_name": "set [my variable v] to ()",
+#     "block_type": "Data",
+#     "op_code": "data_setvariableto",
+#     "functionality": "Assigns a specific value (number, string, or boolean) to a variable.",
+#     "inputs": {
+#       "VALUE": [
+#         4,
+#         "1"
+#       ]
+#     },
+#     "fields": {
+#       "VARIABLE": [
+#         "score",
+#         "`var_score"
+#       ]
+#     },
+#     "shadow": false,
+#     "topLevel": false,
+#     "parent": null,
+#     "next": "data_setvariableto_2"
+#   },
+#   "data_setvariableto_2": {
+#     "block_name": "set [my variable v] to ()",
+#     "block_type": "Data",
+#     "op_code": "data_setvariableto",
+#     "functionality": "Assigns a specific value (number, string, or boolean) to a variable.",
+#     "inputs": {
+#       "VALUE": [
+#         4,
+#         "1"
+#       ]
+#     },
+#     "fields": {
+#       "VARIABLE": [
+#         "speed",
+#         "`var_speed"
+#       ]
+#     },
+#     "shadow": false,
+#     "topLevel": false,
+#     "parent": null,
+#     "next": "data_showvariable_1"
+#   },
+#   "data_showvariable_1": {
+#     "block_name": "show variable [my variable v]",
+#     "block_type": "Data",
+#     "op_code": "data_showvariable",
+#     "functionality": "Makes a variable's monitor visible on the stage.",
+#     "inputs": {},
+#     "fields": {
+#       "VARIABLE": [
+#         "score",
+#         "`var_score"
+#       ]
+#     },
+#     "shadow": false,
+#     "topLevel": false,
+#     "parent": null,
+#     "next": "data_showvariable_2"
+#   },
+#   "data_showvariable_2": {
+#     "block_name": "show variable [my variable v]",
+#     "block_type": "Data",
+#     "op_code": "data_showvariable",
+#     "functionality": "Makes a variable's monitor visible on the stage.",
+#     "inputs": {},
+#     "fields": {
+#       "VARIABLE": [
+#         "speed",
+#         "`var_speed"
+#       ]
+#     },
+#     "shadow": false,
+#     "topLevel": false,
+#     "parent": null,
+#     "next": "control_forever_1"
+#   },
+#   "control_if_2": {
+#     "block_name": "if <> then",
+#     "block_type": "Control",
+#     "op_code": "control_if",
+#     "functionality": "Executes the blocks inside it only if the specified boolean condition is true. [NOTE: it takes boolean blocks as input]",
+#     "inputs": {
+#       "CONDITION": [
+#         2,
+#         "sensing_touchingobject_1"
+#       ],
+#       "SUBSTACK": [
+#         2,
+#         "event_broadcast_1"
+#       ]
+#     },
+#     "fields": {},
+#     "shadow": false,
+#     "topLevel": false,
+#     "parent": "control_forever_1",
+#     "next": null
+#   }
+# }

utils/testing.ipynb

@@ -0,0 +1,419 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "9adfcb20",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import re"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "de910107",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'if <not <touching [sprite2 v]?>> then'"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "stmt=\"if <not <touching [Sprite2 v]?>> then\"\n",
+    "s = stmt.lower().strip()\n",
+    "# 1) strip ALL balanced <…>\n",
+    "while s.startswith(\"<\") and s.endswith(\">\"):\n",
+    "    s = s[1:-1].strip()\n",
+    "# 2) strip stray unmatched < or >\n",
+    "while s.startswith(\"<\") and not s.endswith(\">\"):\n",
+    "    s = s[1:].strip()\n",
+    "while s.endswith(\">\") and not s.startswith(\"<\"):\n",
+    "    s = s[:-1].strip()\n",
+    "    \n",
+    "s"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 20,
+   "id": "af367513",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "None\n",
+      "the stmt was this if <<mouse down?> and <touching [mouse-pointer v]?>> then and parsed was this if <<mouse down?> and <touching [mouse-pointer v]?>> then\n"
+     ]
+    },
+    {
+     "ename": "SyntaxError",
+     "evalue": "'return' outside function (234319892.py, line 51)",
+     "output_type": "error",
+     "traceback": [
+      "  \u001b[36mCell\u001b[39m\u001b[36m \u001b[39m\u001b[32mIn[20]\u001b[39m\u001b[32m, line 51\u001b[39m\n\u001b[31m    \u001b[39m\u001b[31mreturn {\"kind\": \"block\", \"block\": block_id}\u001b[39m\n    ^\n\u001b[31mSyntaxError\u001b[39m\u001b[31m:\u001b[39m 'return' outside function\n"
+     ]
+    }
+   ],
+   "source": [
+    "import re\n",
+    "\n",
+    "s = \"if <not <touching [sprite2 v]?>> then\"\n",
+    "\n",
+    "m_touch = re.fullmatch(r\"touching\\s*\\[\\s*([^\\]]+)\\s*v\\]\\??\", s, re.IGNORECASE)\n",
+    "print(m_touch)\n",
+    "if m_touch:\n",
+    "    sprite = m_touch.group(1).strip()\n",
+    "    val = {'mouse-pointer':'_mouse_', 'edge':'_edge_'}.get(sprite, sprite)\n",
+    "    mid = _register_block(\n",
+    "        \"sensing_touchingobjectmenu\", parent_key, True, pick_key_func, all_generated_blocks,\n",
+    "        fields={\"TOUCHINGOBJECTMENU\":[val, None]}\n",
+    "    )\n",
+    "    bid = _register_block(\n",
+    "        \"sensing_touchingobject\", parent_key, False, pick_key_func, all_generated_blocks,\n",
+    "        inputs={\"TOUCHINGOBJECTMENU\":[1, mid]}\n",
+    "    )\n",
+    "    #all_generated_blocks[mid][\"parent\"] = bid \n",
+    "    print(bid)\n",
+    "    #return {\"kind\":\"block\",\"block\":bid}\n",
+    "\n",
+    "s = stmt.lower().strip()\n",
+    "#s = strip_outer_angle_brackets(s)\n",
+    "# 1) strip ALL balanced <…>\n",
+    "while s.startswith(\"<\") and s.endswith(\">\"):\n",
+    "    s = s[1:-1].strip()\n",
+    "# 2) strip stray unmatched < or >\n",
+    "while s.startswith(\"<\") and not s.endswith(\">\"):\n",
+    "    s = s[1:].strip()\n",
+    "while s.endswith(\">\") and not s.startswith(\"<\"):\n",
+    "    s = s[:-1].strip()\n",
+    "    \n",
+    "print(f\"the stmt was this {stmt} and parsed was this {s}\")\n",
+    "# 1a) Comparisons with explicit angle wrappers: < (...) op (...) >\n",
+    "m = re.fullmatch(\n",
+    "    r\"\\s*<\\s*(.+?)\\s*(?P<op><|=|>)\\s*(.+?)\\s*>\\s*\",\n",
+    "    s,\n",
+    "    re.VERBOSE\n",
+    ")\n",
+    "if m:\n",
+    "    left_txt, right_txt = m.group(1), m.group(3)\n",
+    "    operand1_obj = parse_reporter_or_value(unparen(left_txt), None, pick_key_func, all_generated_blocks)\n",
+    "    operand2_obj = parse_reporter_or_value(unparen(right_txt), None, pick_key_func, all_generated_blocks)\n",
+    "    op_map = {'<': 'operator_lt', '=': 'operator_equals', '>': 'operator_gt'}\n",
+    "    \n",
+    "    inputs = {\"OPERAND1\": operand1_obj, \"OPERAND2\": operand2_obj}\n",
+    "    block_id = _register_block(op_map[m.group('op')], parent_key, False, pick_key_func, all_generated_blocks, inputs=inputs)\n",
+    "    # Set parents for nested inputs\n",
+    "    if operand1_obj.get(\"kind\") == \"block\": all_generated_blocks[operand1_obj[\"block\"]][\"parent\"] = block_id\n",
+    "    if operand2_obj.get(\"kind\") == \"block\": all_generated_blocks[operand2_obj[\"block\"]][\"parent\"] = block_id\n",
+    "    return {\"kind\": \"block\", \"block\": block_id}\n",
+    "# 1b) Simple comparisons without angle wrappers: A op B\n",
+    "m_simple = re.fullmatch(r\"\\s*(.+?)\\s*(?P<op><|=|>)\\s*(.+?)\\s*\", s)\n",
+    "if m_simple:\n",
+    "    left_txt, right_txt = m_simple.group(1), m_simple.group(3)\n",
+    "    operand1_obj = parse_reporter_or_value(unparen(left_txt), None, pick_key_func, all_generated_blocks)\n",
+    "    operand2_obj = parse_reporter_or_value(unparen(right_txt), None, pick_key_func, all_generated_blocks)\n",
+    "    op_map = {'<': 'operator_lt', '=': 'operator_equals', '>': 'operator_gt'}\n",
+    "    \n",
+    "    inputs = {\"OPERAND1\": operand1_obj, \"OPERAND2\": operand2_obj}\n",
+    "    block_id = _register_block(op_map[m_simple.group('op')], parent_key, False, pick_key_func, all_generated_blocks, inputs=inputs)\n",
+    "    if operand1_obj.get(\"kind\") == \"block\": all_generated_blocks[operand1_obj[\"block\"]][\"parent\"] = block_id\n",
+    "    if operand2_obj.get(\"kind\") == \"block\": all_generated_blocks[operand2_obj[\"block\"]][\"parent\"] = block_id\n",
+    "    return {\"kind\": \"block\", \"block\": block_id}"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 23,
+   "id": "3a315968",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[TEST] if <mouse down?> then\n",
+      "→ Extracted: 'mouse down?'\n",
+      "  Expected: 'mouse down?'\n",
+      "  ✅ PASS\n",
+      "\n",
+      "[TEST] if <not <mouse down?>> then\n",
+      "→ Extracted: 'not <mouse down?>'\n",
+      "  Expected: 'not <mouse down?>'\n",
+      "  ✅ PASS\n",
+      "\n",
+      "[TEST] if <<mouse down?> and <touching [edge v]?>> then\n",
+      "→ Extracted: 'mouse down?> and <touching [edge v]?'\n",
+      "  Expected: 'mouse down? and touching [edge v]?'\n",
+      "  ❌ FAIL\n",
+      "\n",
+      "[TEST] if <<<mouse down?>> or <not <key pressed?>> >> then\n",
+      "→ Extracted: 'mouse down?>> or <not <key pressed?'\n",
+      "  Expected: 'mouse down? or not <key pressed?>'\n",
+      "  ❌ FAIL\n",
+      "\n",
+      "[TEST] if <(x position) < (100)> then\n",
+      "→ Extracted: '<(x position) < (100)> then'\n",
+      "  Expected: '(x position) < (100)'\n",
+      "  ❌ FAIL\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "def extract_condition_balanced(stmt):\n",
+    "    stmt = stmt.strip()\n",
+    "    if \"if \" in stmt.lower():\n",
+    "        stmt = stmt.lower().split(\"if\", 1)[1].strip()\n",
+    "\n",
+    "    # Handle bracket balancing\n",
+    "    if stmt.startswith(\"<\"):\n",
+    "        count = 0\n",
+    "        condition = \"\"\n",
+    "        for i, ch in enumerate(stmt):\n",
+    "            if ch == \"<\":\n",
+    "                count += 1\n",
+    "            elif ch == \">\":\n",
+    "                count -= 1\n",
+    "            condition += ch\n",
+    "            if count == 0:\n",
+    "                break\n",
+    "\n",
+    "        # Strip outer brackets recursively\n",
+    "        inner = condition\n",
+    "        while inner.startswith(\"<\") and inner.endswith(\">\"):\n",
+    "            inner = inner[1:-1].strip()\n",
+    "\n",
+    "        return inner\n",
+    "    return stmt.strip()\n",
+    "\n",
+    "test_cases = [\n",
+    "    (\"if <mouse down?> then\", \"mouse down?\"),\n",
+    "    (\"if <not <mouse down?>> then\", \"not <mouse down?>\"),\n",
+    "    (\"if <<mouse down?> and <touching [edge v]?>> then\", \"mouse down? and touching [edge v]?\"),\n",
+    "    (\"if <<<mouse down?>> or <not <key pressed?>> >> then\", \"mouse down? or not <key pressed?>\"),\n",
+    "    (\"if <(x position) < (100)> then\", \"(x position) < (100)\"),\n",
+    "]\n",
+    "\n",
+    "for stmt, expected in test_cases:\n",
+    "    result = extract_condition_balanced(stmt)\n",
+    "    print(f\"[TEST] {stmt}\\n→ Extracted: '{result}'\\n  Expected: '{expected}'\\n  {'✅ PASS' if result == expected else '❌ FAIL'}\\n\")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 38,
+   "id": "34ddb52b",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "--- Testing improved function ---\n",
+      "[TEST] if <mouse down?> then\n",
+      "→ Extracted: 'mouse down?'\n",
+      "  Expected: 'mouse down?'\n",
+      "  ✅ PASS\n",
+      "\n",
+      "[TEST] repeat until <touching [edge v]?>\n",
+      "→ Extracted: 'touching [edge v]?'\n",
+      "  Expected: 'touching [edge v]?'\n",
+      "  ✅ PASS\n",
+      "\n",
+      "[TEST] if <key [left arrow v] pressed?> then\n",
+      "→ Extracted: 'key [left arrow v] pressed?'\n",
+      "  Expected: 'key [left arrow v] pressed?'\n",
+      "  ✅ PASS\n",
+      "\n",
+      "[TEST] if <touching [edge v]?> then\n",
+      "→ Extracted: 'touching [edge v]?'\n",
+      "  Expected: 'touching [edge v]?'\n",
+      "  ✅ PASS\n",
+      "\n",
+      "[TEST] if <<mouse down?> and <touching [edge v]?>> then\n",
+      "→ Extracted: '<mouse down?> and <touching [edge v]?>'\n",
+      "  Expected: 'mouse down? and touching [edge v]?'\n",
+      "  ❌ FAIL\n",
+      "\n",
+      "[TEST] if <(x position) < (100)> then\n",
+      "→ Extracted: '(x position) < (100)'\n",
+      "  Expected: '(x position) < (100)'\n",
+      "  ✅ PASS\n",
+      "\n",
+      "[TEST] if <<mouse down?>> then\n",
+      "→ Extracted: '<mouse down?>'\n",
+      "  Expected: 'mouse down?'\n",
+      "  ❌ FAIL\n",
+      "\n",
+      "[TEST] if <not<>> then\n",
+      "→ Extracted: 'not<>'\n",
+      "  Expected: 'not<>'\n",
+      "  ✅ PASS\n",
+      "\n",
+      "[TEST] if <<> or <>> then\n",
+      "→ Extracted: '<> or <>'\n",
+      "  Expected: '<> or <>'\n",
+      "  ✅ PASS\n",
+      "\n",
+      "[TEST] if <> then\n",
+      "→ Extracted: ''\n",
+      "  Expected: ''\n",
+      "  ✅ PASS\n",
+      "\n",
+      "[TEST] if mouse down? then\n",
+      "→ Extracted: 'mouse down?'\n",
+      "  Expected: 'mouse down?'\n",
+      "  ✅ PASS\n",
+      "\n",
+      "[TEST] <mouse down?>\n",
+      "→ Extracted: 'mouse down?'\n",
+      "  Expected: 'mouse down?'\n",
+      "  ✅ PASS\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "import re\n",
+    "\n",
+    "def extract_condition_balanced(stmt):\n",
+    "    # 1. Remove \"if\" and \"then\"\n",
+    "    stmt = stmt.strip()\n",
+    "    if stmt.lower().startswith(\"if \"):\n",
+    "        stmt = stmt[3:].strip()\n",
+    "    if stmt.lower().startswith(\"repeat until\"):\n",
+    "        stmt = stmt[12:].strip()\n",
+    "    if stmt.lower().endswith(\" then\"):\n",
+    "        stmt = stmt[:-5].strip()\n",
+    "\n",
+    "    # Helper to detect and strip single outer balanced angle brackets\n",
+    "    def unwrap_balanced(s):\n",
+    "        if s.startswith(\"<\") and s.endswith(\">\"):\n",
+    "            depth = 0\n",
+    "            for i in range(len(s)):\n",
+    "                if s[i] == \"<\":\n",
+    "                    depth += 1\n",
+    "                elif s[i] == \">\":\n",
+    "                    depth -= 1\n",
+    "                    if depth == 0 and i < len(s) - 1:\n",
+    "                        return s  # Early balance → not a single outer wrapper\n",
+    "            if depth == 0:\n",
+    "                return s[1:-1].strip()\n",
+    "        return s\n",
+    "\n",
+    "    # Recursively simplify things like <not <x>> to not <x>\n",
+    "    def simplify(s):\n",
+    "        s = unwrap_balanced(s)\n",
+    "        s = s.strip()\n",
+    "\n",
+    "        # Match <not <...>> pattern\n",
+    "        m = re.fullmatch(r\"not\\s*<(.+)>\", s, re.IGNORECASE)\n",
+    "        if m:\n",
+    "            inner = m.group(1).strip()\n",
+    "            inner = simplify(inner)\n",
+    "            return f\"not <{inner}>\"\n",
+    "\n",
+    "        # Match comparison operators like <(x position) < (100)>\n",
+    "        m_comp = re.fullmatch(r\"<\\s*\\(([^<>]+?)\\)\\s*([<>=])\\s*\\(([^<>]+?)\\)\\s*>\", stmt)\n",
+    "        if m_comp:\n",
+    "            return f\"({m_comp.group(1).strip()}) {m_comp.group(2)} ({m_comp.group(3).strip()})\"\n",
+    "\n",
+    "        return s\n",
+    "\n",
+    "    return simplify(stmt)\n",
+    "\n",
+    "# Test cases\n",
+    "# test_cases = [\n",
+    "#     (\"if <mouse down?> then\", \"mouse down?\"),\n",
+    "#     (\"if <not <mouse down?>> then\", \"not <mouse down?>\"),\n",
+    "#     (\"if <<mouse down?> and <touching [edge v]?>> then\", \"<mouse down?> and <touching [edge v]?>\"),\n",
+    "#     (\"if <<mouse down?> or <not <key pressed?>>> then\", \"<mouse down?> or <not <key pressed?>>\"),\n",
+    "#     (\"if <(x position) < (100)> then\", \"(x position) < (100)\"),\n",
+    "# ]\n",
+    "test_cases = [\n",
+    "    (\"if <mouse down?> then\", \"mouse down?\"),\n",
+    "    (\"repeat until <touching [edge v]?>\", \"touching [edge v]?\"),\n",
+    "    (\"if <key [left arrow v] pressed?> then\", \"key [left arrow v] pressed?\"),\n",
+    "    (\"if <touching [edge v]?> then\", \"touching [edge v]?\"),\n",
+    "    (\"if <<mouse down?> and <touching [edge v]?>> then\", \"mouse down? and touching [edge v]?\"),\n",
+    "    (\"if <(x position) < (100)> then\", \"(x position) < (100)\"),\n",
+    "    (\"if <<mouse down?>> then\", \"mouse down?\"),\n",
+    "    (\"if <not<>> then\", \"not<>\"),\n",
+    "    (\"if <<> or <>> then\", \"<> or <>\"),\n",
+    "    (\"if <> then\", \"\"),\n",
+    "    (\"if mouse down? then\", \"mouse down?\"),\n",
+    "    (\"<mouse down?>\", \"mouse down?\"),\n",
+    "]\n",
+    "\n",
+    "print(\"--- Testing improved function ---\")\n",
+    "for stmt, expected in test_cases:\n",
+    "    result = extract_condition_balanced(stmt)\n",
+    "    print(f\"[TEST] {stmt}\\n→ Extracted: '{result}'\\n  Expected: '{expected}'\\n  {'✅ PASS' if result == expected else '❌ FAIL'}\\n\")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 40,
+   "id": "1ee313ee",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "when I receive [Game Over v]\n",
+      "    if <(score) > (High Score)> then\n",
+      "        set [High Score v] to (score)\n",
+      "    end\n",
+      "    switch backdrop to [HighScore v]\n",
+      "end\n"
+     ]
+    }
+   ],
+   "source": [
+    "txt = \"when I receive [Game Over v]\\n    if <(score) > (High Score)> then\\n        set [High Score v] to (score)\\n    end\\n    switch backdrop to [HighScore v]\\nend\"\n",
+    "print(str(txt))                       "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4700799d",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "scratch_env",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}