Update app.py

app.py

@@ -22,10 +22,11 @@ from langchain_core.utils.utils import secret_from_env
 from io import BytesIO
 from pathlib import Path
 import os
-from utils.block_relation_builder import block_builder, separate_scripts, transform_logic_to_action_flow, analyze_opcode_counts#, variable_adder_main
+from utils.block_relation_builder import block_builder, separate_scripts, transform_logic_to_action_flow, analyze_opcode_counts
 from langchain.chat_models import ChatOpenAI
 from langchain_openai import ChatOpenAI
 from pydantic import Field, SecretStr
+from difflib import get_close_matches
 
 os.environ["OPENROUTER_API_KEY"] = os.getenv("OPENROUTER_API_KEY", "default_key_or_placeholder")
 class ChatOpenRouter(ChatOpenAI):
@@ -165,76 +166,118 @@ class GameState(TypedDict):
     
 # Refined SYSTEM_PROMPT with more explicit Scratch JSON rules, especially for variables
 SYSTEM_PROMPT = """
-You are an expert AI assistant named GameScratchAgent, specialized in generating and modifying Scratch-VM 3.x game project JSON.
-Your core task is to process game descriptions and existing Scratch JSON structures, then produce or update JSON segments accurately.
-You possess deep knowledge of Scratch 3.0 project schema, informed by comprehensive reference materials. When generating or modifying the `blocks` section, pay extremely close attention to the following:
-
-**Scratch Project JSON Schema Rules:**
-
-1.  **Target Structure (`project.json`'s `targets` array):**
-    * Each object in the `targets` array represents a Stage or a Sprite.
-    * `isStage`: A boolean indicating if the target is the Stage (`true`) or a Sprite (`false`).
-    * `name`: The name of the Stage (e.g., `"Stage"`) or the Sprite (e.g., `"Cat"`). This property replaces `objName` found in older Scratch versions.
-    * `variables` dictionary: This dictionary maps unique variable IDs to arrays `[variable_name, initial_value, isCloudVariable?]`.
-        * `variable_name`: The user-defined name of the variable.
-        * `initial_value`: The variable's initial value, which can be a number or a string.
-        * `isCloudVariable?`: (Optional) A boolean indicating if it's a cloud variable (`true`) or a local variable (`false` or absent for regular variables).
-        * Example: `"myVarId123": ["score", 0]`, `"cloudVarId456": ["☁ High Score", "54", true]`
-    * `lists` dictionary: This dictionary maps unique list IDs to arrays `[list_name, [item1, item2, ...]]`.
-        * Example: `"myListId789": ["my list", ["apple", "banana"]]`
-    * `broadcasts` dictionary: This dictionary maps unique broadcast IDs to their names.
-        * Example: `"myBroadcastId": "Game Over"`
-    * `blocks` dictionary: This dictionary contains all the blocks belonging to this target. Keys are block IDs, values are block objects.
-
-2.  **Block Structure (within a `target`'s `blocks` dictionary):**
-    * Every block object must have the following core properties:
-        * [cite_start]`opcode`: A unique internal identifier for the block's specific functionality (e.g., `"motion_movesteps"`, `"event_whenflagclicked"`)[cite: 31, 18, 439, 452].
-        * `parent`: The ID of the block directly above it in the script stack (or `null` for a top-level block).
-        * `next`: The ID of the block directly below it in the script stack (or `null` for the end of a stack).
-        * `inputs`: An object defining values or blocks plugged into the block's input slots. Values are **arrays**.
-        * `fields`: An object defining dropdown menu selections or direct internal values within the block. Values are **arrays**.
-        * `shadow`: `true` if it's a shadow block (e.g., a default number input that can be replaced by another block), `false` otherwise.
-        * `topLevel`: `true` if it's a hat block or a standalone block (not connected to a parent), `false` otherwise.
-
-3.  **`inputs` Property Details (for blocks plugged into input slots):**
-    * **Direct Block Connection (Reporter/Boolean block plugged in):**
-        * Format: `"<INPUT_NAME>": [1, "<blockId_of_plugged_block>"]`
-        * Example: `"CONDITION": [1, "someBooleanBlockId"]` (e.g., for an `if` block).
-    * **Literal Value Input (Shadow block with a literal):**
-        * Format: `"<INPUT_NAME>": [1, [<type_code>, "<value_string>"]]`
-        * `type_code`: A numeric code representing the data type. Common codes include: `4` for number, `7` for string/text, `10` for string/message.
-        * `value_string`: The literal value as a string.
-        * Examples:
-            * Number: `"STEPS": [1, [4, "10"]]` (for `move 10 steps` block).
-            * String/Text: `"MESSAGE": [1, [7, "Hello"]]` (for `say Hello` block).
-            * String/Message (common for text inputs): `"MESSAGE": [1, [10, "Hello!"]]` (for `say Hello! for 2 secs`).
-    * **C-Block Substack (blocks within a loop or conditional):**
-        * Format: `"<SUBSTACK_NAME>": [2, "<blockId_of_first_block_in_substack>"]`
-        * Common `SUBSTACK_NAME` values are `SUBSTACK` (for `if`, `forever`, `repeat`) and `SUBSTACK2` (for `else` in `if else`).
-        * Example: `"SUBSTACK": [2, "firstBlockInLoopId"]`
-
-4.  **`fields` Property Details (for dropdowns or direct internal values):**
-    * Used for dropdown menus, variable names, list names, or other static selections directly within the block.
-    * Format: `"<FIELD_NAME>": ["<selected_value>", null]`
-    * Examples:
-        * Dropdown: `"KEY_OPTION": ["space", null]` (for `when space key pressed`).
-        * Variable Name: `"VARIABLE": ["score", null]` (for `set score to 0`).
-        * Direction (specific motion block): `"FORWARD_BACKWARD": ["forward", null]` (for `go forward layers`).
-
-5.  **Unique IDs:**
-    * All block IDs, variable IDs, and list IDs must be unique strings (e.g., "myBlock123", "myVarId456", "myListId789"). Do NOT use placeholder strings like "block_id_here".
-
-6.  **No Nested `blocks` Dictionary:**
-    * The `blocks` dictionary should only appear once per `target` (sprite/stage). Do NOT nest a `blocks` dictionary inside an individual block definition. Blocks that are part of a substack are linked via the `SUBSTACK` input.
-
-7.  **Asset Properties (for Costumes/Sounds):**
-    * `assetId`, `md5ext`, `bitmapResolution`, `rotationCenterX`/`rotationCenterY` should be correctly associated with costume and sound objects within the `costumes` and `sounds` arrays.
-
-**General Principles and Important Considerations:**
-* **Backward Compatibility:** Adhere strictly to existing Scratch 3.0 opcodes and schema to ensure backward compatibility with older projects. [cite_start]Opcodes must remain consistent to prevent previously saved projects from failing to load or behaving unexpectedly[cite: 18, 19, 25, 65].
-* **Forgiving Inputs:** Recognize that Scratch is designed to be "forgiving in its interpretation of inputs." [cite_start]The Scratch VM handles potentially "invalid" inputs gracefully (e.g., converting a number to a string if expected, returning default values like zero or empty strings, or performing no action) rather than crashing[cite: 20, 21, 22, 38, 39, 41]. This implies that precise type matching for inputs might be handled internally by Scratch, allowing for some flexibility in how values are provided, but the agent should aim for the most common and logical type.
+You are GameScratchAgent, an expert in Scratch 3.0 game development.  
+Your task is to process OCR-extracted text from images of Scratch 3.0 code blocks and produce **precisely formatted pseudocode JSON**.  
+
+### Core Role
+- Treat this as an OCR refinement task: the input may contain typos, spacing issues, or incomplete tokens.  
+- Intelligently correct such OCR mistakes to align with valid Scratch 3.0 block syntax.  
+- Always generate logically valid pseudocode consistent with Scratch semantics.  
+
+### Responsibilities
+1. **Code-block detection**
+   - If no Scratch code-blocks are detected → return `"No Code-blocks"`.  
+   - If code-blocks are present → refine into pseudocode.
+
+2. **Script ownership**
+   - Extract the value from `"Script for:"`.  
+   - If it exactly matches any costume in `Stage_costumes`, set `"name_variable": "Stage"`.  
+   - Otherwise, keep the detected target name.
+
+3. **Pseudocode refinement**
+   - Correct OCR artifacts automatically (e.g., “when cliked” → “when green flag clicked”).  
+   - Apply strict Scratch rules for variables, values, dropdowns, reporters, and booleans.  
+   - Ensure indentation of nested blocks (4 spaces).  
+   - Every hat block must end with `end`.  
+   - Do not include explanations or comments.
+
+4. **Formatting precautions**
+   - Numbers → `(5)`, `(-130)`  
+   - Text/strings → `(hello)`  
+   - Variables → `[score v]`  
+   - Dropdowns → `[space v]`, `[Game Over v]`  
+   - Reporter blocks → `((x position))`  
+   - Boolean logic → `<condition>`, `<<cond1> and <cond2>>`, `<not <cond>>`  
+   - Operators → explicit, e.g. `(([speed v]) * (1.1))`  
+
+### Critical Notes
+- Be robust to OCR noise: missing characters, misread symbols, or accidental merges.  
+- Never output raw OCR mistakes—always normalize to valid Scratch pseudocode.  
+- Output only the JSON object, nothing else.
+
 """
 
+# SYSTEM_PROMPT = """
+# You are an expert AI assistant named GameScratchAgent, specialized in generating and modifying Scratch-VM 3.x game project JSON.
+# Your core task is to process game descriptions and existing Scratch JSON structures, then produce or update JSON segments accurately.
+# You possess deep knowledge of Scratch 3.0 project schema, informed by comprehensive reference materials. When generating or modifying the `blocks` section, pay extremely close attention to the following:
+
+# **Scratch Project JSON Schema Rules:**
+
+# 1.  **Target Structure (`project.json`'s `targets` array):**
+#     * Each object in the `targets` array represents a Stage or a Sprite.
+#     * `isStage`: A boolean indicating if the target is the Stage (`true`) or a Sprite (`false`).
+#     * `name`: The name of the Stage (e.g., `"Stage"`) or the Sprite (e.g., `"Cat"`). This property replaces `objName` found in older Scratch versions.
+#     * `variables` dictionary: This dictionary maps unique variable IDs to arrays `[variable_name, initial_value, isCloudVariable?]`.
+#         * `variable_name`: The user-defined name of the variable.
+#         * `initial_value`: The variable's initial value, which can be a number or a string.
+#         * `isCloudVariable?`: (Optional) A boolean indicating if it's a cloud variable (`true`) or a local variable (`false` or absent for regular variables).
+#         * Example: `"myVarId123": ["score", 0]`, `"cloudVarId456": ["☁ High Score", "54", true]`
+#     * `lists` dictionary: This dictionary maps unique list IDs to arrays `[list_name, [item1, item2, ...]]`.
+#         * Example: `"myListId789": ["my list", ["apple", "banana"]]`
+#     * `broadcasts` dictionary: This dictionary maps unique broadcast IDs to their names.
+#         * Example: `"myBroadcastId": "Game Over"`
+#     * `blocks` dictionary: This dictionary contains all the blocks belonging to this target. Keys are block IDs, values are block objects.
+
+# 2.  **Block Structure (within a `target`'s `blocks` dictionary):**
+#     * Every block object must have the following core properties:
+#         * [cite_start]`opcode`: A unique internal identifier for the block's specific functionality (e.g., `"motion_movesteps"`, `"event_whenflagclicked"`)[cite: 31, 18, 439, 452].
+#         * `parent`: The ID of the block directly above it in the script stack (or `null` for a top-level block).
+#         * `next`: The ID of the block directly below it in the script stack (or `null` for the end of a stack).
+#         * `inputs`: An object defining values or blocks plugged into the block's input slots. Values are **arrays**.
+#         * `fields`: An object defining dropdown menu selections or direct internal values within the block. Values are **arrays**.
+#         * `shadow`: `true` if it's a shadow block (e.g., a default number input that can be replaced by another block), `false` otherwise.
+#         * `topLevel`: `true` if it's a hat block or a standalone block (not connected to a parent), `false` otherwise.
+
+# 3.  **`inputs` Property Details (for blocks plugged into input slots):**
+#     * **Direct Block Connection (Reporter/Boolean block plugged in):**
+#         * Format: `"<INPUT_NAME>": [1, "<blockId_of_plugged_block>"]`
+#         * Example: `"CONDITION": [1, "someBooleanBlockId"]` (e.g., for an `if` block).
+#     * **Literal Value Input (Shadow block with a literal):**
+#         * Format: `"<INPUT_NAME>": [1, [<type_code>, "<value_string>"]]`
+#         * `type_code`: A numeric code representing the data type. Common codes include: `4` for number, `7` for string/text, `10` for string/message.
+#         * `value_string`: The literal value as a string.
+#         * Examples:
+#             * Number: `"STEPS": [1, [4, "10"]]` (for `move 10 steps` block).
+#             * String/Text: `"MESSAGE": [1, [7, "Hello"]]` (for `say Hello` block).
+#             * String/Message (common for text inputs): `"MESSAGE": [1, [10, "Hello!"]]` (for `say Hello! for 2 secs`).
+#     * **C-Block Substack (blocks within a loop or conditional):**
+#         * Format: `"<SUBSTACK_NAME>": [2, "<blockId_of_first_block_in_substack>"]`
+#         * Common `SUBSTACK_NAME` values are `SUBSTACK` (for `if`, `forever`, `repeat`) and `SUBSTACK2` (for `else` in `if else`).
+#         * Example: `"SUBSTACK": [2, "firstBlockInLoopId"]`
+
+# 4.  **`fields` Property Details (for dropdowns or direct internal values):**
+#     * Used for dropdown menus, variable names, list names, or other static selections directly within the block.
+#     * Format: `"<FIELD_NAME>": ["<selected_value>", null]`
+#     * Examples:
+#         * Dropdown: `"KEY_OPTION": ["space", null]` (for `when space key pressed`).
+#         * Variable Name: `"VARIABLE": ["score", null]` (for `set score to 0`).
+#         * Direction (specific motion block): `"FORWARD_BACKWARD": ["forward", null]` (for `go forward layers`).
+
+# 5.  **Unique IDs:**
+#     * All block IDs, variable IDs, and list IDs must be unique strings (e.g., "myBlock123", "myVarId456", "myListId789"). Do NOT use placeholder strings like "block_id_here".
+
+# 6.  **No Nested `blocks` Dictionary:**
+#     * The `blocks` dictionary should only appear once per `target` (sprite/stage). Do NOT nest a `blocks` dictionary inside an individual block definition. Blocks that are part of a substack are linked via the `SUBSTACK` input.
+
+# 7.  **Asset Properties (for Costumes/Sounds):**
+#     * `assetId`, `md5ext`, `bitmapResolution`, `rotationCenterX`/`rotationCenterY` should be correctly associated with costume and sound objects within the `costumes` and `sounds` arrays.
+
+# **General Principles and Important Considerations:**
+# * **Backward Compatibility:** Adhere strictly to existing Scratch 3.0 opcodes and schema to ensure backward compatibility with older projects. [cite_start]Opcodes must remain consistent to prevent previously saved projects from failing to load or behaving unexpectedly[cite: 18, 19, 25, 65].
+# * **Forgiving Inputs:** Recognize that Scratch is designed to be "forgiving in its interpretation of inputs." [cite_start]The Scratch VM handles potentially "invalid" inputs gracefully (e.g., converting a number to a string if expected, returning default values like zero or empty strings, or performing no action) rather than crashing[cite: 20, 21, 22, 38, 39, 41]. This implies that precise type matching for inputs might be handled internally by Scratch, allowing for some flexibility in how values are provided, but the agent should aim for the most common and logical type.
+# """
+
 SYSTEM_PROMPT_JSON_CORRECTOR ="""
 You are an assistant that outputs JSON responses strictly following the given schema.  
 If the JSON you produce has any formatting errors, missing required fields, or invalid structure, you must identify the problems and correct them.  
@@ -254,7 +297,6 @@ agent = create_react_agent(
     tools=[], # No specific tools are defined here, but could be added later
     prompt=SYSTEM_PROMPT
 )
-
 agent_2 = create_react_agent(
     model=llm2,
     tools=[], # No specific tools are defined here, but could be added later
@@ -503,56 +545,62 @@ hat_description = hat_block_data["description"]
 #hat_description = hat_block_data.get("description", "No description available")
 # hat_opcodes_functionalities = "\n".join([f"    - Opcode: {block['op_code']}, functionality: {block['functionality']} example: standalone use: {block['example_standalone']}" for block in hat_block_data["blocks"]])
 hat_opcodes_functionalities = "\n".join([
-    f"    - Opcode: {block.get('op_code', 'N/A')}, functionality: {block.get('functionality', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
+    # f"    - Opcode: {block.get('op_code', 'N/A')}, functionality: {block.get('functionality', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
+    f"    - Opcode: {block.get('op_code', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
     for block in hat_block_data.get("blocks", [])
 ]) if isinstance(hat_block_data.get("blocks"), list) else "    No blocks information available."
-hat_opcodes_functionalities = os.path.join(BLOCKS_DIR, "hat_blocks.txt")
+#hat_opcodes_functionalities = os.path.join(BLOCKS_DIR, "hat_blocks.txt")
 print("Hat blocks loaded successfully.", hat_description)
 
 boolean_block_data = _load_block_catalog(BOOLEAN_BLOCKS_PATH)
 boolean_description = boolean_block_data["description"]
 # boolean_opcodes_functionalities = "\n".join([f"    - Opcode: {block['op_code']}, functionality: {block['functionality']} example: standalone use: {block['example_standalone']}" for block in boolean_block_data["blocks"]])
 boolean_opcodes_functionalities = "\n".join([
-    f"    - Opcode: {block.get('op_code', 'N/A')}, functionality: {block.get('functionality', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
+    # f"    - Opcode: {block.get('op_code', 'N/A')}, functionality: {block.get('functionality', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
+    f"    - Opcode: {block.get('op_code', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
     for block in boolean_block_data.get("blocks", [])
 ]) if isinstance(boolean_block_data.get("blocks"), list) else "    No blocks information available."
-boolean_opcodes_functionalities = os.path.join(BLOCKS_DIR, "boolean_blocks.txt")
+#boolean_opcodes_functionalities = os.path.join(BLOCKS_DIR, "boolean_blocks.txt")
 
 c_block_data = _load_block_catalog(C_BLOCKS_PATH)
 c_description = c_block_data["description"]
 # c_opcodes_functionalities = "\n".join([f"    - Opcode: {block['op_code']}, functionality: {block['functionality']} example: standalone use: {block['example_standalone']}" for block in c_block_data["blocks"]])
 c_opcodes_functionalities = "\n".join([
-    f"    - Opcode: {block.get('op_code', 'N/A')}, functionality: {block.get('functionality', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
+    # f"    - Opcode: {block.get('op_code', 'N/A')}, functionality: {block.get('functionality', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
+    f"    - Opcode: {block.get('op_code', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
     for block in c_block_data.get("blocks", [])
 ]) if isinstance(c_block_data.get("blocks"), list) else "    No blocks information available."
-c_opcodes_functionalities = os.path.join(BLOCKS_DIR, "c_blocks.txt")
+#c_opcodes_functionalities = os.path.join(BLOCKS_DIR, "c_blocks.txt")
 
 cap_block_data = _load_block_catalog(CAP_BLOCKS_PATH)
 cap_description = cap_block_data["description"]                                                                                                                                                                                                                                                                                                                                                                                                                                                      
 # cap_opcodes_functionalities = "\n".join([f"    - Opcode: {block['op_code']}, functionality: {block['functionality']} example: standalone use: {block['example_standalone']}" for block in cap_block_data["blocks"]])
 cap_opcodes_functionalities = "\n".join([
-    f"    - Opcode: {block.get('op_code', 'N/A')}, functionality: {block.get('functionality', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
+    # f"    - Opcode: {block.get('op_code', 'N/A')}, functionality: {block.get('functionality', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
+    f"    - Opcode: {block.get('op_code', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
     for block in cap_block_data.get("blocks", [])
 ]) if isinstance(cap_block_data.get("blocks"), list) else "    No blocks information available."
-cap_opcodes_functionalities = os.path.join(BLOCKS_DIR, "cap_blocks.txt")
+#cap_opcodes_functionalities = os.path.join(BLOCKS_DIR, "cap_blocks.txt")
 
 reporter_block_data = _load_block_catalog(REPORTER_BLOCKS_PATH)
 reporter_description = reporter_block_data["description"]
 # reporter_opcodes_functionalities = "\n".join([f"    - Opcode: {block['op_code']}, functionality: {block['functionality']} example: standalone use: {block['example_standalone']}" for block in reporter_block_data["blocks"]])
 reporter_opcodes_functionalities = "\n".join([
-    f"    - Opcode: {block.get('op_code', 'N/A')}, functionality: {block.get('functionality', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
+    # f"    - Opcode: {block.get('op_code', 'N/A')}, functionality: {block.get('functionality', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
+    f"    - Opcode: {block.get('op_code', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
     for block in reporter_block_data.get("blocks", [])
 ]) if isinstance(reporter_block_data.get("blocks"), list) else "    No blocks information available."
-reporter_opcodes_functionalities = os.path.join(BLOCKS_DIR, "reporter_blocks.txt")
+#reporter_opcodes_functionalities = os.path.join(BLOCKS_DIR, "reporter_blocks.txt")
 
 stack_block_data = _load_block_catalog(STACK_BLOCKS_PATH)
 stack_description = stack_block_data["description"]
 # stack_opcodes_functionalities = "\n".join([f"    - Opcode: {block['op_code']}, functionality: {block['functionality']} example: standalone use: {block['example_standalone']}" for block in stack_block_data["blocks"]])
 stack_opcodes_functionalities = "\n".join([
-    f"    - Opcode: {block.get('op_code', 'N/A')}, functionality: {block.get('functionality', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
+    # f"    - Opcode: {block.get('op_code', 'N/A')}, functionality: {block.get('functionality', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
+    f"    - Opcode: {block.get('op_code', 'N/A')}, example: standalone use {block.get('example_standalone', 'N/A')}"
     for block in stack_block_data.get("blocks", [])
 ]) if isinstance(stack_block_data.get("blocks"), list) else "    No blocks information available."
-stack_opcodes_functionalities = os.path.join(BLOCKS_DIR, "stack_blocks.txt")
+#stack_opcodes_functionalities = os.path.join(BLOCKS_DIR, "stack_blocks.txt")
 
 # This makes ALL_SCRATCH_BLOCKS_CATALOG available globally
 ALL_SCRATCH_BLOCKS_CATALOG = _load_block_catalog(BLOCK_CATALOG_PATH)
@@ -623,123 +671,269 @@ def extract_json_from_llm_response(raw_response: str) -> dict:
         logger.error("Sanitized JSON still invalid:\n%s", json_string)
         raise
 
-# def clean_base64_for_model(raw_b64):
+# def reduce_image_size_to_limit(clean_b64_str, max_kb=4000):
 #     """
-#     Normalize input into a valid data:image/png;base64,<payload> string.
-
-#     Accepts:
-#       - a list of base64 strings → picks the first element
-#       - a PIL Image instance       → encodes to PNG/base64
-#       - a raw base64 string        → strips whitespace and data URI prefix
+#     Reduce an image's size to be as close as possible to max_kb without exceeding it.
+#     Returns the final base64 string and its size in KB.
 #     """
+#     import re, base64
+#     from io import BytesIO
+#     from PIL import Image
+
+#     # Remove the data URI prefix
+#     base64_data = re.sub(r"^data:image\/[a-zA-Z]+;base64,", "", clean_b64_str)
+#     image_data = base64.b64decode(base64_data)
+
+#     # Load into PIL
+#     img = Image.open(BytesIO(image_data))
+
+#     low, high = 20, 95  # reasonable JPEG quality range
+#     best_b64 = None
+#     best_size_kb = 0
+
+#     while low <= high:
+#         mid = (low + high) // 2
+#         buffer = BytesIO()
+#         img.save(buffer, format="JPEG", quality=mid)
+#         size_kb = len(buffer.getvalue()) / 1024
+
+#         if size_kb <= max_kb:
+#             # This quality is valid, try higher
+#             best_b64 = base64.b64encode(buffer.getvalue()).decode("utf-8")
+#             best_size_kb = size_kb
+#             low = mid + 1
+#         else:
+#             # Too big, try lower
+#             high = mid - 1
+
+#     return f"data:image/jpeg;base64,{best_b64}"
+
+# #clean the base64 model here
+# def clean_base64_for_model(raw_b64):
+#     import io, base64, re
+#     from PIL import Image
+
 #     if not raw_b64:
-#         return ""
+#         return "", ""
 
-#     # 1. If it’s a list, take its first element
 #     if isinstance(raw_b64, list):
 #         raw_b64 = raw_b64[0] if raw_b64 else ""
 #         if not raw_b64:
-#             return ""
+#             return "", ""
 
-#     # 2. If it’s a PIL Image, convert to base64
 #     if isinstance(raw_b64, Image.Image):
 #         buf = io.BytesIO()
 #         raw_b64.save(buf, format="PNG")
 #         raw_b64 = base64.b64encode(buf.getvalue()).decode()
 
-#     # 3. At this point it must be a string
 #     if not isinstance(raw_b64, str):
 #         raise TypeError(f"Expected base64 string or PIL Image, got {type(raw_b64)}")
 
-#     # 4. Strip any existing data URI prefix, whitespace, or newlines
+#     # Remove data URI prefix if present
 #     clean_b64 = re.sub(r"^data:image\/[a-zA-Z]+;base64,", "", raw_b64)
 #     clean_b64 = clean_b64.replace("\n", "").replace("\r", "").strip()
 
-#     # 5. Validate it’s proper base64
-#     try:
-#         base64.b64decode(clean_b64)
-#     except Exception as e:
-#         logger.error(f"Invalid Base64 passed to model: {e}")
-#         raise
-
-#     # 6. Return with the correct data URI prefix
-#     return f"data:image/png;base64,{clean_b64}"
-
-def reduce_image_size_to_limit(clean_b64_str, max_kb=4000):
+#     # Log original size
+#     original_size = len(clean_b64.encode("utf-8"))
+#     print(f"Original Base64 size (bytes): {original_size}")
+#     if original_size > 4000000:
+#         # Reduce size to under 4 MB
+#         reduced_b64 = reduce_image_size_to_limit(clean_b64, max_kb=4000)
+#         clean_b64_2 = re.sub(r"^data:image\/[a-zA-Z]+;base64,", "", reduced_b64)
+#         clean_b64_2 = clean_b64_2.replace("\n", "").replace("\r", "").strip()
+#         reduced_size = len(clean_b64_2.encode("utf-8"))
+#         print(f"Reduced Base64 size (bytes): {reduced_size}")
+#         # Return both prefixed and clean reduced versions
+#         return f"data:image/jpeg;base64,{reduced_b64}"
+#     return f"data:image/jpeg;base64,{clean_b64}"
+
+def reduce_image_size_to_limit(clean_b64_str: str, max_kb: int = 4000) -> str:
     """
-    Reduce an image's size to be as close as possible to max_kb without exceeding it.
-    Returns the final base64 string and its size in KB.
+    Input: clean_b64_str = BASE64 STRING (no data: prefix)
+    Output: BASE64 STRING (no data: prefix), sized as close as possible to max_kb KB.
+    Guarantees: returns a valid base64 string (never None). May still be larger than max_kb
+    if saving at lowest quality cannot get under the limit.
     """
-    import re, base64
-    from io import BytesIO
-    from PIL import Image
+    # sanitize
+    clean = re.sub(r"\s+", "", clean_b64_str).strip()
+    # fix padding
+    missing = len(clean) % 4
+    if missing:
+        clean += "=" * (4 - missing)
 
-    # Remove the data URI prefix
-    base64_data = re.sub(r"^data:image\/[a-zA-Z]+;base64,", "", clean_b64_str)
-    image_data = base64.b64decode(base64_data)
-
-    # Load into PIL
-    img = Image.open(BytesIO(image_data))
-
-    low, high = 20, 95  # reasonable JPEG quality range
-    best_b64 = None
-    best_size_kb = 0
+    try:
+        image_data = base64.b64decode(clean)
+    except Exception as e:
+        raise ValueError("Invalid base64 input to reduce_image_size_to_limit") from e
 
+    try:
+        img = Image.open(io.BytesIO(image_data))
+        img.load()
+    except Exception as e:
+        raise ValueError("Could not open image from base64") from e
+
+    # convert alpha -> RGB because JPEG doesn't support alpha
+    if img.mode in ("RGBA", "LA") or (img.mode == "P" and "transparency" in img.info):
+        background = Image.new("RGB", img.size, (255, 255, 255))
+        background.paste(img, mask=img.split()[-1] if img.mode != "RGB" else None)
+        img = background
+    elif img.mode != "RGB":
+        img = img.convert("RGB")
+
+    low, high = 20, 95
+    best_bytes = None
+    # binary search for best quality
     while low <= high:
         mid = (low + high) // 2
-        buffer = BytesIO()
-        img.save(buffer, format="JPEG", quality=mid)
-        size_kb = len(buffer.getvalue()) / 1024
-
+        buf = io.BytesIO()
+        try:
+            img.save(buf, format="JPEG", quality=mid, optimize=True)
+        except OSError:
+            # some PIL builds/channels may throw on optimize=True; fallback without optimize
+            buf = io.BytesIO()
+            img.save(buf, format="JPEG", quality=mid)
+        size_kb = len(buf.getvalue()) / 1024.0
         if size_kb <= max_kb:
-            # This quality is valid, try higher
-            best_b64 = base64.b64encode(buffer.getvalue()).decode("utf-8")
-            best_size_kb = size_kb
+            best_bytes = buf.getvalue()
             low = mid + 1
         else:
-            # Too big, try lower
             high = mid - 1
 
-    return f"data:image/jpeg;base64,{best_b64}"
+    # if never found a quality <= max_kb, use the smallest we created (quality = 20)
+    if best_bytes is None:
+        buf = io.BytesIO()
+        try:
+            img.save(buf, format="JPEG", quality=20, optimize=True)
+        except OSError:
+            buf = io.BytesIO()
+            img.save(buf, format="JPEG", quality=20)
+        best_bytes = buf.getvalue()
 
-#clean the base64 model here
-def clean_base64_for_model(raw_b64):
-    import io, base64, re
-    from PIL import Image
+    return base64.b64encode(best_bytes).decode("utf-8")
 
+
+def clean_base64_for_model(raw_b64, max_bytes_threshold=4000000) -> str:
+    """
+    Accepts: raw_b64 can be:
+      - a data URI 'data:image/png;base64,...'
+      - a plain base64 string
+      - a PIL Image
+      - a list containing the above (take first)
+    Returns: a data URI string 'data:<mime>;base64,<base64>' guaranteed to be syntactically valid.
+    """
+    # normalize input
     if not raw_b64:
-        return "", ""
+        return ""
 
     if isinstance(raw_b64, list):
         raw_b64 = raw_b64[0] if raw_b64 else ""
         if not raw_b64:
-            return "", ""
+            return ""
 
     if isinstance(raw_b64, Image.Image):
         buf = io.BytesIO()
-        raw_b64.save(buf, format="PNG")
-        raw_b64 = base64.b64encode(buf.getvalue()).decode()
+        # convert to RGB and save as JPEG to keep consistent
+        img = raw_b64.convert("RGB")
+        img.save(buf, format="JPEG")
+        clean_b64 = base64.b64encode(buf.getvalue()).decode("utf-8")
+        mime = "image/jpeg"
+        return f"data:{mime};base64,{clean_b64}"
 
     if not isinstance(raw_b64, str):
         raise TypeError(f"Expected base64 string or PIL Image, got {type(raw_b64)}")
 
-    # Remove data URI prefix if present
-    clean_b64 = re.sub(r"^data:image\/[a-zA-Z]+;base64,", "", raw_b64)
-    clean_b64 = clean_b64.replace("\n", "").replace("\r", "").strip()
-
-    # Log original size
-    original_size = len(clean_b64.encode("utf-8"))
-    print(f"Original Base64 size (bytes): {original_size}")
-    if original_size > 4000000:
-        # Reduce size to under 4 MB
-        reduced_b64 = reduce_image_size_to_limit(clean_b64, max_kb=4000)
-        clean_b64_2 = re.sub(r"^data:image\/[a-zA-Z]+;base64,", "", reduced_b64)
-        clean_b64_2 = clean_b64_2.replace("\n", "").replace("\r", "").strip()
-        reduced_size = len(clean_b64_2.encode("utf-8"))
-        print(f"Reduced Base64 size (bytes): {reduced_size}")
-        # Return both prefixed and clean reduced versions
-        return f"data:image/jpeg;base64,{reduced_b64}"
-    return f"data:image/jpeg;base64,{clean_b64}"
+    # detect mime if present; otherwise default to png
+    m = re.match(r"^data:(image\/[a-zA-Z0-9.+-]+);base64,(.+)$", raw_b64, flags=re.DOTALL)
+    if m:
+        mime = m.group(1)
+        clean_b64 = m.group(2)
+    else:
+        # no prefix; assume png by default (you can change to jpeg if you prefer)
+        mime = "image/png"
+        clean_b64 = raw_b64
+
+    # sanitize base64 string
+    clean_b64 = re.sub(r"\s+", "", clean_b64).strip()
+    missing = len(clean_b64) % 4
+    if missing:
+        clean_b64 += "=" * (4 - missing)
+
+    original_size_bytes = len(clean_b64.encode("utf-8"))
+    # debug print
+    print(f"Original base64 size (bytes): {original_size_bytes}, mime: {mime}")
+
+    if original_size_bytes > max_bytes_threshold:
+        # reduce and return JPEG prefixed data URI (JPEG tends to compress better for photos)
+        reduced_clean = reduce_image_size_to_limit(clean_b64, max_kb=4000)
+        # reduced_clean is plain base64 (no prefix)
+        print(f"Reduced base64 size (bytes): {original_size_bytes}, mime: {mime}")
+        return f"data:image/jpeg;base64,{reduced_clean}"
+
+    # otherwise return original with its mime prefix (ensure prefix exists)
+    return f"data:{mime};base64,{clean_b64}"
+
+
+SCRATCH_OPCODES = [
+    'motion_movesteps', 'motion_turnright', 'motion_turnleft', 'motion_goto',
+    'motion_gotoxy', 'motion_glideto', 'motion_glidesecstoxy', 'motion_pointindirection',
+    'motion_pointtowards', 'motion_changexby', 'motion_setx', 'motion_changeyby',
+    'motion_sety', 'motion_ifonedgebounce', 'motion_setrotationstyle', 'looks_sayforsecs',
+    'looks_say', 'looks_thinkforsecs', 'looks_think', 'looks_switchcostumeto',
+    'looks_nextcostume', 'looks_switchbackdropto', 'looks_switchbackdroptowait',
+    'looks_nextbackdrop', 'looks_changesizeby', 'looks_setsizeto', 'looks_changeeffectby',
+    'looks_seteffectto', 'looks_cleargraphiceffects', 'looks_show', 'looks_hide',
+    'looks_gotofrontback', 'looks_goforwardbackwardlayers', 'sound_playuntildone',
+    'sound_play', 'sound_stopallsounds', 'sound_changevolumeby', 'sound_setvolumeto',
+    'event_broadcast', 'event_broadcastandwait', 'control_wait', 'control_wait_until',
+    'control_stop', 'control_create_clone_of', 'control_delete_this_clone',
+    'data_setvariableto', 'data_changevariableby', 'data_addtolist', 'data_deleteoflist',
+    'data_insertatlist', 'data_replaceitemoflist', 'data_showvariable', 'data_hidevariable',
+    'data_showlist', 'data_hidelist', 'sensing_askandwait', 'sensing_resettimer',
+    'sensing_setdragmode', 'procedures_call', 'operator_lt', 'operator_equals',
+    'operator_gt', 'operator_and', 'operator_or', 'operator_not', 'operator_contains',
+    'sensing_touchingobject', 'sensing_touchingcolor', 'sensing_coloristouchingcolor',
+    'sensing_keypressed', 'sensing_mousedown', 'data_listcontainsitem', 'control_repeat',
+    'control_forever', 'control_if', 'control_if_else', 'control_repeat_until',
+    'motion_xposition', 'motion_yposition', 'motion_direction', 'looks_costumenumbername',
+    'looks_size', 'looks_backdropnumbername', 'sound_volume', 'sensing_distanceto',
+    'sensing_answer', 'sensing_mousex', 'sensing_mousey', 'sensing_loudness',
+    'sensing_timer', 'sensing_of', 'sensing_current', 'sensing_dayssince2000',
+    'sensing_username', 'operator_add', 'operator_subtract', 'operator_multiply',
+    'operator_divide', 'operator_random', 'operator_join', 'operator_letterof',
+    'operator_length', 'operator_mod', 'operator_round', 'operator_mathop',
+    'data_variable', 'data_list', 'data_itemoflist', 'data_lengthoflist',
+    'data_itemnumoflist', 'event_whenflagclicked', 'event_whenkeypressed',
+    'event_whenthisspriteclicked', 'event_whenbackdropswitchesto', 'event_whengreaterthan',
+    'event_whenbroadcastreceived', 'control_start_as_clone', 'procedures_definition'
+]
+
+def validate_and_fix_opcodes(opcode_counts):
+    """
+    Ensures all opcodes are valid. If an opcode is invalid, replace with closest match.
+    """
+    corrected_list = []
+    for item in opcode_counts:
+        opcode = item.get("opcode")
+        count = item.get("count", 1)
+
+        if opcode not in SCRATCH_OPCODES:
+            # Find closest match (case-sensitive)
+            match = get_close_matches(opcode, SCRATCH_OPCODES, n=1, cutoff=0.6)
+            if match:
+                print(f"Opcode '{opcode}' not found. Replacing with '{match[0]}'")
+                opcode = match[0]
+            else:
+                print(f"Opcode '{opcode}' not recognized and no close match found. Skipping.")
+                continue
+        
+        corrected_list.append({"opcode": opcode, "count": count})
+
+    # Merge duplicates after correction
+    merged = {}
+    for item in corrected_list:
+        merged[item["opcode"]] = merged.get(item["opcode"], 0) + item["count"]
+
+    return [{"opcode": k, "count": v} for k, v in merged.items()]
     
 def format_scratch_pseudo_code(code_string):
     """
@@ -879,6 +1073,7 @@ If you find any "Code-Blocks" then,
    
 3. **Pseudo‑code formatting**:
    - Represent each block or nested block on its own line.
+   - Auto-correct invalid OCR phrases to valid Scratch 3.0 block names using the **Scratch 3.0 Block Reference** above.  
    - **Indent nested blocks by 4 spaces under their parent (`forever`, `if`, etc.).This is a critical requirement.**
    - No comments or explanatory text—just the block sequence.
    - a natural language breakdown of each step taken after the event, formatted as a multi-line string representing pseudo-code. Ensure clarity and granularity—each described action should map closely to a Scratch block or tight sequence. 
@@ -1010,6 +1205,7 @@ If you find any "Code-Blocks" then,
     logger.info("Plan refinement and block relation analysis completed for all plans.")
     return state
 
+# Node: Node Optimizer node
 def node_optimizer(state: GameState):
     logger.info("--- Running Node Optimizer Node ---")
     project_json = state["project_json"]
@@ -1055,7 +1251,7 @@ def node_optimizer(state: GameState):
         return state
     except Exception as e:
         logger.error(f"Error in Node Optimizer Node: {e}")
-    
+
 # Node 2: planner node
 def overall_planner_node(state: GameState):
     """
@@ -1133,7 +1329,10 @@ Blocks:
 
 Your task is to  use the `Sprite_name` given and `Pseudo_code` and add it to the specific target name and define the primary actions and movements.
 The output should be a JSON object with a single key 'action_overall_flow'. Each key inside this object should be a sprite or 'Stage' name (e.g., 'Player', 'Enemy', 'Stage'), and its value must include a 'description' and a list of 'plans'.
+The first plan in each stage must start with one Scratch Hat Block (e.g., event_whenflagclicked).
+Other plans may use any hat blocks (including duplicates) to represent different logics or events.
 Each plan must include a **single Scratch Hat Block** (e.g., 'event_whenflagclicked') to start scratch project and should contain:
+
 1. **'event'**: the exact `opcode` of the hat block that initiates the logic.
 [NOTE: INSTRUCTIONN TO FOLLOW IF PSEUDO_CODE HAVING PROBLEM ]
 2. **'logic'**: a natural language breakdown of each step taken after the event, formatted as a multi-line string representing pseudo-code. Ensure clarity and granularity—each described action should map closely to a Scratch block or tight sequence.
@@ -1295,7 +1494,7 @@ Each plan must include a **single Scratch Hat Block** (e.g., 'event_whenflagclic
                         "operator_lt"
                     ],
                     "sensing": [
-                        "sensing_istouching",
+                        "sensing_touchingobject",
                         "sensing_touchingobjectmenu"
                     ],
                     "looks": [],
@@ -1431,6 +1630,8 @@ Here is the overall script available:
 
 * **Your task is to align to description, refine and correct the JSON object 'action_overall_flow'.**
 Use sprite names exactly as provided in `sprite_names` (e.g., 'Sprite1', 'soccer ball'); and also the stage, do **NOT** rename them.
+Other plans may use any hat blocks (including duplicates) to represent different logics or events.
+Each plan must include a **single Scratch Hat Block** (e.g., 'event_whenflagclicked') to start scratch project and should contain:
 1.  **'event'**: the exact `opcode` of the hat block that initiates the logic.
 2. **'logic'**: a natural language breakdown of each step taken after the event, formatted as a multi-line string representing pseudo-code. Ensure clarity and granularity—each described action should map closely to a Scratch block or tight sequence.
     - Do **NOT** include any justification or comments—only the raw logic.
@@ -1599,7 +1800,7 @@ Use sprite names exactly as provided in `sprite_names` (e.g., 'Sprite1', 'soccer
                         "operator_lt"
                     ],
                     "sensing": [
-                        "sensing_istouching",
+                        "sensing_touchingobject",
                         "sensing_touchingobjectmenu"
                     ],
                     "looks": [],
@@ -1806,7 +2007,7 @@ Example output:
     {{"opcode":"control_forever","count":1}},
     {{"opcode":"control_if","count":2}},
     {{"opcode":"operator_lt","count":1}},
-    {{"opcode":"sensing_istouching","count":1}},
+    {{"opcode":"sensing_touchingobject","count":1}},
     {{"opcode":"event_whenflagclicked","count":1}},
     {{"opcode":"event_broadcast","count":1}}
     ]
@@ -1843,7 +2044,7 @@ Example output:
 
             # Directly use the 'opcode_counts' list from the LLM's output
             plan["opcode_counts"] = llm_json.get("opcode_counts", [])
-            
+            plan["opcode_counts"] = validate_and_fix_opcodes(plan["opcode_counts"])
             # Optionally, you can remove the individual category lists from the plan
             # if they are no longer needed after the LLM provides the consolidated list.
             # for key in ["motion", "control", "operator", "sensing", "looks", "sounds", "events", "data"]: