Upload 6 files

Dockerfile

@@ -0,0 +1,30 @@
+# Use an official Python runtime as a parent image
+FROM python:3.9-slim
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Copy the requirements file into the container
+COPY requirements.txt .
+
+# Install any needed packages specified in requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the current directory contents into the container at /app
+COPY . .
+
+# Make port 7860 available (Hugging Face Default)
+EXPOSE 7860
+
+# Define environment variable
+ENV FLASK_APP=backend/main.py
+
+# Create a non-root user (Security Best Practice for Spaces)
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+	PATH=/home/user/.local/bin:$PATH
+
+# Run gunicorn
+# Hugging Face expects port 7860
+CMD gunicorn --workers=${WEB_CONCURRENCY:-4} --bind=0.0.0.0:${PORT:-7860} backend.main:app

backend/agents/adaptive_agent.py

@@ -0,0 +1,78 @@
+from typing import List, Dict, Any
+
+class AdaptiveAgent:
+    """
+    Agent A: The Coach
+    Responsibility: Analyzes user performance history to determine the optimal difficulty level.
+    """
+    
+    DIFFICULTIES = ["Easy", "Intermediate", "Expert"]
+    
+    def evaluate_user(self, history: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Analyzes a list of past match results to determine new difficulty.
+        
+        Args:
+            history: List of dicts, e.g., 
+                     [{'result': 'success', 'time_taken': 45, 'hints_used': 0}, ...]
+        
+        Returns:
+            Dict with 'recommended_difficulty' and 'reasoning'.
+        """
+        if not history:
+            return {"difficulty": "Easy", "reason": "New user"}
+            
+        # Analyze last 5 games
+        recent_games = history[-5:]
+        success_count = sum(1 for game in recent_games if game.get('result') == 'success')
+        avg_time = sum(game.get('time_taken', 0) for game in recent_games) / len(recent_games)
+        total_hints = sum(game.get('hints_used', 0) for game in recent_games)
+        
+        current_difficulty = recent_games[-1].get('difficulty', "Easy")
+        
+        # Promotion Logic
+        if success_count >= 4 and total_hints <= 2:
+            next_diff = self._change_difficulty(current_difficulty, 1)
+            return {
+                "difficulty": next_diff,
+                "reason": "Consistently successful with few hints. Promoting!"
+            }
+            
+        # Demotion Logic
+        if success_count <= 1:
+            next_diff = self._change_difficulty(current_difficulty, -1)
+            return {
+                "difficulty": next_diff,
+                "reason": "Struggling with current tasks. Let's practice basics."
+            }
+            
+        # Maintain
+        return {
+            "difficulty": current_difficulty,
+            "reason": "Steady progress. Maintaining current challenge level."
+        }
+
+    def _change_difficulty(self, current: str, step: int) -> str:
+        try:
+            # Normalize casing just in case
+            current = current.capitalize()
+            if current not in self.DIFFICULTIES:
+                 # Fallback if unknown difficulty comes in
+                 return "Easy"
+                 
+            idx = self.DIFFICULTIES.index(current)
+            new_idx = max(0, min(len(self.DIFFICULTIES) - 1, idx + step))
+            return self.DIFFICULTIES[new_idx]
+        except ValueError:
+            return "Easy"
+
+if __name__ == "__main__":
+    # Test logic
+    agent = AdaptiveAgent()
+    history = [
+        {'result': 'success', 'time_taken': 30, 'hints_used': 0, 'difficulty': 'Beginner'},
+        {'result': 'success', 'time_taken': 25, 'hints_used': 0, 'difficulty': 'Beginner'},
+        {'result': 'success', 'time_taken': 40, 'hints_used': 1, 'difficulty': 'Beginner'},
+        {'result': 'success', 'time_taken': 35, 'hints_used': 0, 'difficulty': 'Beginner'}
+    ]
+    print(agent.evaluate_user(history))

backend/agents/hint_agent.py

@@ -0,0 +1,64 @@
+import google.generativeai as genai
+import os
+from typing import Dict, Any, Optional
+
+class HintAgent:
+    """
+    Agent C: The Mentor
+    Responsibility: Provides context-aware help based on user's current code/state.
+    """
+    
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key or os.getenv("GEMINI_API_KEY")
+        if not self.api_key:
+            # For development, allow initialization without key if just testing logic structure
+            # But actual generation will fail
+            pass
+        else:
+            genai.configure(api_key=self.api_key)
+            self.model = genai.GenerativeModel('gemini-1.5-flash')
+
+    def generate_hint(self, 
+                     level_context: Dict[str, Any], 
+                     user_code: str, 
+                     error_message: Optional[str] = None) -> str:
+        """
+        Generates a hint based on the level and user's current attempt.
+        """
+        if not hasattr(self, 'model'):
+             return "SYSTEM ERROR: API Key missing for Hint Agent."
+
+        prompt = f"""
+        You are a coding tutor. The student is stuck.
+        
+        LEVEL CONTEXT:
+        Title: {level_context.get('title')}
+        Goal: {level_context.get('goal_description') or level_context.get('problem')}
+        
+        USER'S CURRENT CODE:
+        {user_code}
+        
+        ERROR MESSAGE (if any):
+        {error_message}
+        
+        TASK:
+        Provide a helpful, encouraging hint. 
+        DO NOT give the full solution immediately unless they are very stuck.
+        If there is a syntax error, point it out gently.
+        Keep it under 2 sentences.
+        """
+        
+        try:
+            response = self.model.generate_content(prompt)
+            return response.text.strip()
+        except Exception as e:
+            # Fallback Hint (Generic but helpful)
+            return "Try breaking the problem down into smaller steps. Check if your loops and variables are set correctly!"
+
+if __name__ == "__main__":
+    from dotenv import load_dotenv
+    load_dotenv()
+    agent = HintAgent()
+    context = {"title": "Mars Rover", "goal_description": "Move forward 3 times"}
+    code = "move_forward\nturn_left"
+    print(agent.generate_hint(context, code))

backend/agents/scenario_agent.py

@@ -0,0 +1,291 @@
+import google.generativeai as genai
+import json
+import os
+import random
+import time
+from typing import Dict, Any, Optional
+
+class ScenarioAgent:
+    """
+    Agent B: The Creator
+    Responsibility: Generates unique, creative game levels in JSON format.
+    Includes Caching & Fallback for Zero-Lag experience.
+    """
+    
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key or os.getenv("GEMINI_API_KEY")
+        if not self.api_key:
+            print("WARNING: GEMINI_API_KEY not found. Using fallback mode.")
+            self.model = None
+        else:
+            genai.configure(api_key=self.api_key)
+            self.model = genai.GenerativeModel('gemini-1.5-flash')
+        
+        # Simple In-Memory Cache: { "mode_difficulty_topic": { "data": ..., "timestamp": ... } }
+        self.cache = {}
+        self.cache_duration = 3600 # 1 hour
+
+        
+        # STEM Topics to ensure variety
+        self.topics = {
+            "Space": ["Mars Rover Navigation", "Satellite Repair", "Alien Communication", "Black Hole Trajectory"],
+            "Biology": ["DNA Sequencing", "Blood Cell Defense", "Plant Growth Simulation", "Neuronal Network"],
+            "Robotics": ["Assembly Line Logic", "Drone Delivery", "Bomb Defusal", "Warehouse Sorting"],
+            "Cryptography": ["Spy Message Decoding", "Bank Security", "Password Hashing", "Ancient Runes"],
+            "Chemistry": ["Potion Mixing", "Element Bonding", "Acid-Base Neutralization", "Crystal Formation"]
+        }
+
+        # In-Memory "Learning" Storage
+        # In a real app, this would be a Database (Postgres/Firebase)
+        self.high_rated_levels = [] 
+
+    def learn_from_feedback(self, level_data: Dict[str, Any], rating: int):
+        """
+        Ingests user feedback. 
+        If a level gets 5 stars, we save it as a 'Gold Standard' example.
+        """
+        if rating == 5:
+            # Keep only the last 50 awesome levels to save memory
+            if len(self.high_rated_levels) > 50:
+                self.high_rated_levels.pop(0)
+            self.high_rated_levels.append(level_data)
+            print(f"DEBUG: Agent learned from 5-star level: {level_data.get('title')}")
+
+    def _get_few_shot_examples(self, mode: str) -> str:
+        """Returns verified examples + dynamically learned examples."""
+        
+        # 1. Static base examples (The "Textbook" rules)
+        base_examples = ""
+        if mode == "maze":
+            base_examples = """
+            EXAMPLE OUTPUT:
+            {
+                "type": "maze",
+                "level_id": "lvl_mars_01",
+                "title": "Mars Rover Jump",
+                "story": "A crater blocks the path! Use the jump module.",
+                "goal_description": "Reach the solar panel.",
+                "grid_layout": [[0,0,1], [2,0,3]],
+                "allowed_blocks": ["move_forward", "jump", "turn_left"],
+                "optimal_steps": 4,
+                "hint_1": "Jumping skips one tile.",
+                "hint_2": "Jump over the wall (1)."
+            }
+            """
+        elif mode == "blockly":
+            base_examples = """
+            EXAMPLE OUTPUT:
+            {
+                "type": "blockly",
+                "level_id": "lvl_crypto_05",
+                "title": "Caesar Cipher",
+                "story": "The spies sent a shifted message.",
+                "problem": "Shift each letter by +1.",
+                "toolbox_categories": ["Text", "Loops", "Variables"],
+                "initial_code": "message = 'HAL'",
+                "validation_rules": {
+                    "required_concepts": ["loop"],
+                    "expected_output": "IBM"
+                },
+                "hint_1": "Loop through each character.",
+                "hint_2": "Use charCodeAt() + 1"
+            }
+            """
+            
+        # 2. Dynamic "Learned" Examples (The "User Favorites")
+        learned_example = ""
+        # Filter for relevant mode
+        relevant_learnings = [l for l in self.high_rated_levels if l.get('type') == mode]
+        
+        if relevant_learnings:
+            # Pick one random 5-star level to inspire the AI
+            favorite = random.choice(relevant_learnings)
+            learned_example = f"""
+            
+            USER FAVORITE EXAMPLE (The user loved this style!):
+            {json.dumps(favorite)}
+            """
+            
+        return base_examples + learned_example
+
+    def _get_system_prompt(self, mode: str, difficulty: str) -> str:
+        """Constructs the system prompt based on mode and difficulty."""
+        
+        base_prompt = f"""
+        You are the Lead Game Designer for 'CodeCracker', an educational coding game for ages 10-14.
+        Your task is to generate a UNIQUE Level JSON.
+        
+        CURRENT SETTINGS:
+        - Mode: {mode}
+        - Difficulty: {difficulty}
+        
+        Refer to these strict examples for the required JSON structure:
+        {self._get_few_shot_examples(mode)}
+        
+        OUTPUT FORMAT: RAW JSON ONLY (No Markdown).
+        """
+        
+        if mode == "maze":
+            base_prompt += """
+            JSON STRUCTURE FOR MAZE:
+            {
+                "type": "maze",
+                "level_id": "UUID_STRING",
+                "title": "Short Fun Title",
+                "story": "Engaging 1-2 sentence scenario.",
+                "goal_description": "What needs to be achieved.",
+                "grid_layout": [[0,0,1],[2,0,3]], // 0=Path, 1=Wall, 2=Start, 3=Goal, 4=Hazard
+                "allowed_blocks": ["move_forward", "turn_left", "turn_right", "repeat_loop"],
+                "optimal_steps": 5,
+                "hint_1": "Vague hint",
+                "hint_2": "Specific hint"
+            }
+            Constraints:
+            - Easy: 5x5 grid, simple path.
+            - Intermediate: 8x8 grid, more turns.
+            - Expert: 10x10 grid, dead ends, multiple turns.
+            """
+            
+        elif mode == "blockly":
+            base_prompt += """
+            JSON STRUCTURE FOR BLOCKLY (LOGIC PUZZLE):
+            {
+                "type": "blockly",
+                "level_id": "UUID_STRING",
+                "title": "Short Fun Title",
+                "story": "Real-world problem scenario.",
+                "problem": "Clear problem statement.",
+                "toolbox_categories": ["Math", "Loops", "Variables"], // What blocks are available
+                "initial_code": "", // Optional starter code
+                "validation_rules": {
+                    "required_concepts": ["loop", "variable"],
+                    "expected_output": "Value or State"
+                },
+                 "hint_1": "Vague hint",
+                 "hint_2": "Specific hint"
+            }
+            """
+            
+        elif mode == "time_challenge":
+            base_prompt += """
+            JSON STRUCTURE FOR TIME CHALLENGE:
+            This is a fast-paced mode mixing logic and debugging.
+            {
+                "type": "time_challenge",
+                "level_id": "UUID_STRING",
+                "title": "Speed Run Title",
+                "story": "Urgent scenario (e.g., 'Reactor Meltdown!').",
+                "timer_seconds": 60,
+                "buggy_code": "code with syntax or logic error",
+                "task": "Fix the bug before time runs out!",
+                "solution_patch": "Corrected line or logic"
+            }
+            """
+            
+        return base_prompt
+
+    def generate_level(self, mode: str, difficulty: str, specific_topic: Optional[str] = None) -> Dict[str, Any]:
+        """Generates a level config with Cache & Fallback."""
+        
+        # 1. Randomize topic if null
+        if not specific_topic:
+            category = random.choice(list(self.topics.keys()))
+            specific_topic = random.choice(self.topics[category])
+        else:
+            category = "Requested"
+
+        # 2. Check Cache (to prevent lag on repeated requests)
+        cache_key = f"{mode}_{difficulty}_{specific_topic}"
+        if cache_key in self.cache:
+            entry = self.cache[cache_key]
+            if time.time() - entry['timestamp'] < self.cache_duration:
+                print(f"DEBUG: Returning cached level for {cache_key}")
+                return entry['data']
+        
+        prompt = f"""
+        Generate a Level.
+        Topic: {specific_topic}
+        Domain: {category}
+        Ensure the scenario is DIFFERENT from generic coding problems.
+        """
+        
+        try:
+            if not self.model:
+                raise Exception("No API Key or Model available")
+
+            # 3. Fast Timeout generation (Simulated by simple call here, but ideally async)
+            response = self.model.generate_content(
+                self._get_system_prompt(mode, difficulty) + "\n\n" + prompt
+            )
+            text = response.text.strip()
+            if text.startswith("```json"):
+                text = text[7:]
+            if text.endswith("```"):
+                text = text[:-3]
+            
+            level_data = json.loads(text)
+            
+            # 4. Save to Cache
+            self.cache[cache_key] = {
+                "data": level_data,
+                "timestamp": time.time()
+            }
+            return level_data
+
+        except Exception as e:
+            print(f"ERROR: AI Generation failed ({e}). Returning Fallback.")
+            return self._get_fallback_level(mode, difficulty)
+
+    def _get_fallback_level(self, mode, difficulty):
+        """Zero-Crash Fallback: Returns a valid local JSON if AI fails."""
+        if mode == "maze":
+            return {
+                "type": "maze",
+                "level_id": "fallback_001",
+                "title": "Emergency Practice",
+                "story": "The AI navigation system is offline. We need manual override!",
+                "grid_layout": [[2,0,0],[1,1,0],[0,0,3]],
+                "allowed_blocks": ["move", "turn"],
+                "tutorial": "Guide the bot manually."
+            }
+        elif mode == "blockly":
+            return {
+                "type": "blockly",
+                "level_id": "fallback_002",
+                "title": "Logic Repair",
+                "story": "The automated systems are down. We need manual logic configuration.",
+                "problem": "Create a loop that counts to 3.",
+                "toolbox_categories": ["Loops", "Math", "Variables"],
+                "initial_code": "",
+                "validation_rules": {
+                    "required_concepts": ["loop"],
+                    "expected_output": "3"
+                },
+                "hint_1": "Use the 'repeat' block.",
+                "hint_2": "Set the number to 3."
+            }
+        elif mode == "time_challenge":
+            return {
+                "type": "time_challenge",
+                "level_id": "fallback_003",
+                "title": "System Reboot",
+                "story": "Critical Error! Debug the startup sequence immediately.",
+                "timer_seconds": 45,
+                "buggy_code": "print('System Ready'\nstart_engine()",
+                "task": "Fix the syntax error.",
+                "solution_patch": "print('System Ready')\nstart_engine()"
+            }
+        
+        return {
+            "type": "error",
+            "message": "Mode not supported in fallback",
+            "level_id": "error_000"
+        }
+
+if __name__ == "__main__":
+    # fast test
+    from dotenv import load_dotenv
+    load_dotenv()
+    agent = ScenarioAgent()
+    print("Testing Maze Generation...")
+    print(json.dumps(agent.generate_level("maze", "Easy"), indent=2))

backend/main.py

@@ -0,0 +1,117 @@
+from flask import Flask, request, jsonify
+from flask_cors import CORS
+import os
+from dotenv import load_dotenv
+
+# Import our Agents
+from agents.scenario_agent import ScenarioAgent
+from agents.adaptive_agent import AdaptiveAgent
+from agents.hint_agent import HintAgent
+
+# Load environment variables
+load_dotenv()
+
+app = Flask(__name__)
+CORS(app)  # Enable CORS for all routes
+
+# Initialize Agents
+scenario_agent = ScenarioAgent()
+adaptive_agent = AdaptiveAgent()
+hint_agent = HintAgent()
+
+@app.route('/health', methods=['GET'])
+def health_check():
+    return jsonify({"status": "healthy", "service": "CodeCracker AI Backend"})
+
+@app.route('/api/level/generate', methods=['POST'])
+def generate_level():
+    """
+    Generates a new level (Maze, Blockly, or Time Challenge).
+    Expected JSON: { "mode": "maze", "difficulty": "Easy", "topic": "Space" (optional) }
+    """
+    data = request.json
+    mode = data.get('mode', 'maze')
+    difficulty = data.get('difficulty', 'Easy')
+    topic = data.get('topic') 
+    
+    try:
+        level_data = scenario_agent.generate_level(mode, difficulty, topic)
+        if not level_data:
+             raise Exception("Empty level data returned")
+        return jsonify(level_data)
+    except Exception as e:
+        print(f"CRITICAL ERROR /api/level/generate: {e}")
+        # Final Safety Net: Return a basic Maze fallback if everything else explodes
+        fallback = {
+            "type": "maze",
+            "level_id": "emergency_fallback",
+            "title": "System Practice",
+            "story": "System offline. Practice mode engaged.",
+            "grid_layout": [[2,0,3]],
+            "allowed_blocks": ["move_forward"],
+             "tutorial_text": "Move to the goal."
+        }
+        return jsonify(fallback)
+
+@app.route('/api/level/feedback', methods=['POST'])
+def level_feedback():
+    """
+    Receives user feedback (1-5 stars) on a level.
+    Expected JSON: { "level_data": {...}, "rating": 5 }
+    """
+    data = request.json or {}
+    level_data = data.get('level_data')
+    rating = data.get('rating')
+    
+    if not level_data or not rating:
+        return jsonify({"message": "Invalid data ignored"}), 400
+        
+    try:
+        # Teach the agent!
+        scenario_agent.learn_from_feedback(level_data, int(rating))
+        return jsonify({"status": "learned", "message": "Thanks for the feedback!"})
+    except Exception as e:
+        print(f"Feedback Error: {e}")
+        return jsonify({"status": "ignored"}), 200
+
+@app.route('/api/player/evaluate', methods=['POST'])
+def evaluate_player():
+    """
+    Evaluates player history to adjust difficulty.
+    Expected JSON: { "history": [ { "result": "success", "time_taken": 30 }, ... ] }
+    """
+    data = request.json or {}
+    history = data.get('history', [])
+    
+    try:
+        evaluation = adaptive_agent.evaluate_user(history)
+        return jsonify(evaluation)
+    except Exception as e:
+        print(f"CRITICAL ERROR /api/player/evaluate: {e}")
+        # Fallback: Default to current or Easy
+        return jsonify({"difficulty": "Easy", "reason": "System requires calibration."})
+
+@app.route('/api/hint/generate', methods=['POST'])
+def generate_hint():
+    """
+    Generates a context-aware hint.
+    Expected JSON: { "level_context": {...}, "user_code": "...", "error": "..." }
+    """
+    data = request.json or {}
+    if 'user_code' not in data:
+         return jsonify({"error": "Missing user_code"}), 400
+         
+    try:
+        hint = hint_agent.generate_hint(
+            level_context=data.get('level_context', {}),
+            user_code=data.get('user_code'),
+            error_message=data.get('error')
+        )
+        return jsonify({"hint": hint})
+    except Exception as e:
+        print(f"CRITICAL ERROR /api/hint/generate: {e}")
+        return jsonify({"hint": "Try checking your syntax and logic step-by-step."})
+
+if __name__ == '__main__':
+    port = int(os.environ.get('PORT', 5000))
+    app.run(host='0.0.0.0', port=port, debug=True)

requirements.txt

@@ -0,0 +1,5 @@
+flask>=3.0.0
+flask-cors>=4.0.0
+python-dotenv>=1.0.0
+google-generativeai>=0.3.0
+gunicorn>=21.2.0