Level Generator Web Application

A web application that generates new programming task levels based on existing examples from Code.org's curriculum. Uses Google's Gemini AI to analyze example levels and create similar new tasks with instructions and starter code.

🌟 Features

• Web-based Interface: User-friendly frontend for adding and managing example levels
• Batch Processing: Generate multiple levels at once from JSON or CSV files
• Multiple Level Support: Add multiple example levels to generate more contextually relevant results
• Bubble Choice Support: Automatically expands bubble choice levels to include all sub-levels
• Real-time Generation: Uses Gemini AI to generate new tasks on-demand
• Easy Copy-Paste: One-click copy functionality for instructions and starter code
• Editable Results: Edit generated instructions and starter code before saving
• Save Functionality: Download generated levels as JSON files locally
• Responsive Design: Works on desktop and mobile browsers

🚀 Quick Start

Prerequisites

• Python 3.8+
• Google API Key (Get one here)

Installation

1. Install dependencies:

   pip install -r backend/requirements.txt

2. Set your Google API Key: Create a .env file and use GEMINI_API_KEY=

3. Run the application:

   Windows:

   run.bat

   macOS/Linux:

   chmod +x run.sh
   ./run.sh

4. Open the frontend:

   • Open frontend/index.html in your web browser
   • Or visit http://localhost:8000 if using a local server

📖 Usage

Web Interface

1. Add Example Levels

   • Click "Add Level" to add level input fields
   • Enter the level name (e.g., programming-fundamentals-lesson6-level1_2025-launch_2025)
   • Select the level type (Level or Bubble Choice)
   • Add multiple examples for better results
   • Use "Remove" to delete individual levels
   • Use "Clear All" to start over

2. Generate New Level

   • Click "Generate New Level" button
   • Wait 10-30 seconds for processing
   • View generated results (may include multiple examples)
   • Each result card shows instructions and starter code

3. Edit Generated Content

   • Click "Edit" on any instruction or code block to modify
   • Click "Lock" to save your changes
   • Edits are preserved when saving

4. Save Results

   • Individual Save: Click "Save This Example" on any result card
   • Bulk Save: Enter a base filename and click "Save All Examples"
   • Files are downloaded as JSON to your computer
   • Multiple examples are numbered automatically (e.g., my-level-1.json, my-level-2.json)

5. Load Existing Levels

   • Click "📁 Load JSON File" to load previously generated levels
   • View and edit loaded content
   • Save modifications as needed

6. Copy to Clipboard

   • Click "Copy" on any instruction or code block
   • Paste content directly into Code.org or other tools

🔄 Batch Generation

For generating multiple levels at once, use the batch_generate.py command-line tool.

Quick Start

# Generate from JSON file
python batch_generate.py batch.json

# Generate from CSV file
python batch_generate.py test_levels.csv

Input File Formats

JSON Format

{
  "functions-define-1": [
    {"name": "programming-fundamentals-lesson4-level2_2025-launch_2025", "type": "level"},
    {"name": "programming-fundamentals-lesson4-level3_2025-launch_2025", "type": "bubble_choice"}
  ],
  "variables-intro-1": [
    {"name": "programming-fundamentals-lesson2-level1_2025-launch_2025", "type": "level"}
  ]
}

• Key: Base filename for the generated level (without .json extension)
• Value: Array of source levels to analyze and generate from
• Fields:
  • name: The level name from Code.org repository
  • type: Either level or bubble_choice

CSV Format

name,level_name,type
functions-define-1,programming-fundamentals-lesson4-level2_2025-launch_2025,level
functions-define-1,programming-fundamentals-lesson4-level3_2025-launch_2025,bubble_choice
variables-intro-1,programming-fundamentals-lesson2-level1_2025-launch_2025,level

• Columns:
  • name: Base filename for the generated level
  • level_name: The level name from Code.org repository
  • type: Either level or bubble_choice

Note: When you provide a CSV file, it's automatically converted to JSON format and saved with the same base name (e.g., test_levels.csv → test_levels.json)

Output

Generated levels are saved in the saved/ directory with the filenames specified in your input file:

saved/
├── functions-define-1.json
└── variables-intro-1.json

Batch Processing Features

• Automatic Conversion: CSV files are automatically converted to JSON
• Skip Existing: Files in saved/ directory are skipped if they already exist
• Progress Tracking: Real-time progress output for each batch item
• Summary Report: Complete summary showing successes and failures
• Error Handling: Continues processing even if individual items fail

Example Workflow

1. Create a batch request file (my_levels.csv or my_levels.json)
2. Run the batch generator: python batch_generate.py my_levels.csv
3. Find generated levels in the saved/ directory
4. Review and use the generated levels in your curriculum

📁 Project Structure

level-generator/
├── backend/
│   ├── app.py              # Flask API server
│   ├── requirements.txt    # Python dependencies
│   └── .env                # Environment variables (GEMINI_API_KEY)
├── frontend/
│   ├── index.html          # Main UI
│   ├── styles.css          # Styling
│   └── app.js              # Frontend logic
├── saved/                  # Generated levels from batch processing
├── batch_generate.py       # Batch generation CLI tool
├── level_generator.py      # Core generation functions
├── utils.py                # Shared utility functions
├── batch.json              # Example batch request file (JSON)
├── test_levels.csv         # Example batch request file (CSV)
├── SETUP.md                # Detailed setup guide
├── TEST_GUIDE.md           # Testing documentation
├── run.bat                 # Windows startup script
└── run.sh                  # macOS/Linux startup script

🔧 How It Works

Web Application

1. Frontend (frontend/)

   • User-friendly interface for adding example levels
   • Real-time form validation
   • Multiple result cards for generated examples
   • Edit functionality for instructions and starter code
   • Copy to clipboard and save to file features
   • Load previously generated JSON files

2. Backend (backend/app.py)

   • POST /api/generate: Processes level generation requests
   • POST /api/save: Saves generated levels to server
   • GET /api/health: Health check endpoint
   • Uses CORS for cross-origin requests
   • Returns multiple examples when appropriate

3. Core Logic (level_generator.py)

   • fetch_all_levels(): Fetches level data from Code.org repository
   • analyze_and_generate_file(): Uses Gemini AI to generate new examples
   • Handles both single levels and bubble choice expansion
   • Shared by both web interface and batch processing

Batch Processing

1. CLI Tool (batch_generate.py)

   • Processes JSON or CSV batch files
   • Automatically converts CSV to JSON
   • Generates multiple levels sequentially
   • Saves results to saved/ directory
   • Provides progress tracking and summary report

2. Utility Functions (utils.py)

   • save_level_json(): Saves generated levels with conflict handling
   • save_json_format(): Converts API response to level file format
   • Shared utilities for consistent file operations

🌐 API Reference

POST /api/generate

Generate a new level based on examples.

Request:

{
  "levels": [
    {
      "name": "programming-fundamentals-lesson6-level1_2025-launch_2025",
      "type": "level"
    }
  ]
}

Response:

{
  "success": true,
  "generated": "{\"instructions\": \"...\", \"starter_code\": \"...\"}",
  "examples_used": 3
}

🛠️ Development

Running Backend Only

python backend/app.py

Server runs on http://localhost:5000

Running Frontend with Local Server

cd frontend
python -m http.server 8000

Access at http://localhost:8000

📝 Examples

Web Interface Example

Input:

• Level 1: programming-fundamentals-lesson6-level1_2025-launch_2025 (type: level)
• Level 2: programming-fundamentals-lesson6-level2_2025-launch_2025 (type: level)
• Level 3: programming-fundamentals-lesson6-level3_2025-launch_2025 (type: level)

Output:

• One or more generated examples
• New instructions in markdown format
• New starter code in Python
• Contextually similar to the input examples
• Downloadable as JSON files

Batch Generation Example

Input File (batch.json):

{
  "loops-intro-1": [
    {"name": "programming-fundamentals-lesson8-level1_2025-launch_2025", "type": "level"},
    {"name": "programming-fundamentals-lesson8-level2_2025-launch_2025", "type": "level"}
  ],
  "functions-practice-1": [
    {"name": "programming-fundamentals-lesson4-level5_2025-launch_2025", "type": "level"}
  ]
}

Command:

python batch_generate.py batch.json

Output:

saved/loops-intro-1.json
saved/functions-practice-1.json

🐛 Troubleshooting

Web Interface Issues

Backend won't start?

• Verify GEMINI_API_KEY is set in backend/.env
• Check Python version: python --version (requires 3.8+)
• Install dependencies: pip install -r backend/requirements.txt

CORS errors?

• Ensure backend is running on port 5000
• Try using a local server for frontend
• Check browser console for specific error messages

No results generated?

• Verify level names exactly match Code.org repository
• Check backend console for API errors
• Ensure you have internet connection
• Verify your Gemini API key is valid

Can't save files?

• Browser may block downloads - check browser settings
• Ensure you've entered a valid filename
• Check browser's download location

Batch Generation Issues

batch_generate.py fails to run?

• Verify GEMINI_API_KEY is set in backend/.env
• Check file path to batch JSON/CSV file
• Ensure Python dependencies are installed

CSV conversion errors?

• Verify CSV has required columns: name, level_name, type
• Check for malformed CSV (missing commas, quotes)
• Ensure CSV encoding is UTF-8

Some batch items fail?

• Check that level names exist in Code.org repository
• Review console output for specific error messages
• Verify API rate limits aren't exceeded
• Failed items don't stop processing of other items

Files not saving?

• Check permissions on saved/ directory
• Ensure disk space is available
• Verify filenames don't contain invalid characters

📚 Additional Documentation

See SETUP.md for detailed setup instructions and troubleshooting.

🔒 Notes

• Level names must exactly match those in Code.org's GitHub repository
• Bubble choice levels automatically expand to include sub-levels
• API key (GEMINI_API_KEY) is required for Gemini AI to function
• Generated levels can be edited in the web interface before saving
• Batch generation automatically skips files that already exist in saved/ directory
• CSV files are automatically converted to JSON format during batch processing
• Both web interface and batch generation use the same core level_generator.py functions

📄 License

This project uses the Code.org curriculum data and Google's Gemini AI.