Tools

🔧 batch-generate.js

Batch image generation for lesson assets. Reads asset manifests and generates all images with consistent cartoon style.

What It Does

• Reads assets-manifest.json for each lesson
• Generates images via Fireworks AI API (Stable Diffusion XL)
• Auto-applies style template for visual consistency
• Organizes outputs by category (characters, objects, letters, backgrounds, UI)
• Generates report with success/failure tracking

Prompt Template (Auto-Applied)

Example: How an Apple Gets Generated

From manifest:

{
  "id": "apple",
  "prompt": "Cartoon red apple, friendly face, simple 2D style",
  "size": "512x512"
}

Full prompt sent to API:

Cartoon red apple, friendly face, simple 2D style, 
2D cartoon illustration for children, friendly and warm, 
simple shapes, bold outlines, flat colors, no gradients, 
educational style, suitable for kindergarten, high contrast, 
cheerful, isolated on transparent background

Usage

# Generate all images for a lesson
node batch-generate.js --lesson quest-001-letter-a

# Force regeneration (overwrite existing)
node batch-generate.js --lesson quest-001-letter-a --force

# Use custom manifest path
node batch-generate.js --lesson quest-001-letter-a \
  --manifest ../../lessons/quest-001-letter-a/assets-manifest.json

Features

• Automatic style template application (consistent cartoon look)
• Organized output by lesson and category
• Generation report with success/failure tracking
• Resume support (skips existing files, use --force to override)
• Rate limiting (1 second delay between API calls)
• Transparent PNG backgrounds for characters/objects

API Configuration

{
  "image_api": {
    "provider": "fireworks",
    "api_key": "YOUR_FIREWORKS_KEY",
    "model": "stable-diffusion-xl-1024-v1-0",
    "default_params": {
      "width": 1024,
      "height": 1024,
      "steps": 30,
      "cfg_scale": 7.5,
      "style_preset": "digital-art"
    }
  }
}

Output Structure

assets/images/quest-001-letter-a/
├── characters/
│   ├── tutor-neutral.png
│   ├── tutor-happy.png
│   └── ...
├── objects/
│   ├── apple.png
│   ├── ant.png
│   └── ...
├── letters/
│   ├── letter-a.png
│   └── ...
├── backgrounds/
│   └── classroom.png
└── ui/
    ├── button-play.png
    └── ...

# Plus generation-report.json with stats

🔊 batch-audio.js

Batch audio generation for lesson narration and feedback. Supports ElevenLabs (high quality) or Amazon Polly (budget).

What It Does

• Reads narration and feedback text from manifest
• Generates MP3 audio via TTS API
• Organizes by category (narration, feedback, sfx)
• Tracks emotion/pace metadata for future use

Usage

# Generate with ElevenLabs (recommended for MVP)
node batch-audio.js --lesson quest-001-letter-a --provider elevenlabs

# Generate with Polly (cheaper for scale)
node batch-audio.js --lesson quest-001-letter-a --provider polly

# Force regeneration
node batch-audio.js --lesson quest-001-letter-a --force

Features

• Multi-provider support (ElevenLabs, Amazon Polly)
• Voice settings optimization (stability: 0.5, similarity_boost: 0.75)
• Emotion/tone tags in manifest (cheerful, encouraging, calm)
• MP3 output, 64-128kbps, <10MB per lesson
• Generation report tracking success/failure

Cost Comparison

• ElevenLabs: ~$2.05 per lesson (natural quality)
• Amazon Polly: ~$0.13 per lesson (robotic but functional)

API Configuration

{
  "audio_api": {
    "provider": "elevenlabs",
    "api_key": "sk_...",
    "voice_id": "XB0fDUnXU5powFXDhCwa",
    "model": "eleven_multilingual_v2"
  }
}

Output Structure

assets/audio/quest-001-letter-a/
├── narration/
│   ├── intro-welcome.mp3
│   ├── challenge-1-instruction.mp3
│   └── ...
└── feedback/
    ├── correct-01.mp3
    ├── correct-02.mp3
    ├── encourage-01.mp3
    └── ...

# Plus audio-report.json with stats

Example Manifest Entry

{
  "audio": {
    "narration": [
      {
        "id": "intro-welcome",
        "text": "Hello! I'm excited to learn with you today!",
        "emotion": "cheerful",
        "pace": "normal"
      }
    ],
    "feedback": [
      {
        "id": "correct-01",
        "text": "That's right! Great job!",
        "emotion": "celebrating"
      }
    ]
  }
}

📦 lesson-assembler/package.js

Compiles generated assets into deployable lesson packages for the Flow Education Android app.

What It Does

• Validates all required assets exist
• Copies images and audio to organized output folder
• Generates SHA-256 checksums for integrity verification
• Calculates package size
• Creates deployment manifest

Usage

# Package a complete lesson
node lesson-assembler/package.js --lesson quest-001-letter-a

# Package with detailed manifest
node lesson-assembler/package.js --lesson quest-001-letter-a --include-manifest

# Package all lessons
node lesson-assembler/package.js --all

Features

• Asset validation (checks all required files present)
• Manifest generation (JSON for app consumption)
• Checksum generation (SHA-256, 16-char hex)
• Size reporting (MB per lesson)
• Dependency resolution (prerequisite quests)
• Package report with success/failure tracking

Output Structure

output/quest-001-letter-a/
├── images/
│   ├── characters/
│   ├── objects/
│   ├── letters/
│   ├── backgrounds/
│   └── ui/
├── audio/
│   ├── narration/
│   └── feedback/
└── manifest.json (if --include-manifest)

# Plus quest-001-letter-a-package-report.json

🧠 adaptive-logic.js

Simple rule-based adaptive algorithm for Phase 0 MVP. Adjusts difficulty based on student performance in real-time. NOT machine learning — explicit rules for transparency and debugging.

What It Does

• Tracks error rates per skill
• Adjusts challenge difficulty up/down
• Triggers review lessons when needed
• Never lets a child get stuck

5 Difficulty Levels

1. EASIEST   - Extra scaffolding, more hints, longer time
2. EASY      - Standard scaffolding, extra time allowed
3. NORMAL    - Default challenge (starting level)
4. HARD      - Faster pace, less scaffolding, fewer hints
5. HARDEST   - Timed, no hints, minimal scaffolding

Adaptation Triggers

3 consecutive errors  → Reduce difficulty (make easier)
5 consecutive correct → Increase difficulty (make harder)
<30% success rate      → Trigger review lesson
>80% success rate       → Mark skill mastered
>30 seconds stuck      → Offer hint/help

Usage

const { AdaptiveEngine } = require('./tools/adaptive-logic');

const engine = new AdaptiveEngine('student-001');

// Record an attempt
engine.recordAttempt('letter-b-recognition', true, 3000);

// Check if adaptation needed
const adaptations = engine.shouldAdapt('letter-b-recognition');
// Returns: [{ type: 'INCREASE_DIFFICULTY', reason: '5 consecutive correct' }]

// Get session summary
const summary = engine.getSessionSummary();
// { durationMinutes: 6, challengesCompleted: 4, successRate: "85%" }

📊 progress-tracker.js

Student session tracking and recommendations. Stores progress locally (AsyncStorage for React Native) with skill mastery, streak tracking, and next quest recommendations.

What It Does

• Tracks session time and challenge completion
• Records success/error rates per skill
• Identifies skills needing review
• Maintains daily streaks
• Recommends next quest

Tracked Metrics

- Total sessions per student
- Total learning time (minutes)
- Quests completed
- Skills mastered (80%+ over 5+ attempts)
- Success rate per skill
- Daily streak
- Skills needing review (<50% success)

Usage

const { ProgressTracker } = require('./tools/progress-tracker');

const tracker = new ProgressTracker(AsyncStorage);
await tracker.init('student-001');

// Start a quest
await tracker.startQuest('quest-001-letter-a');

// Record challenge completion
await tracker.completeChallenge('challenge-1', true, 'letter-a', 5000);

// Complete quest
await tracker.completeQuest('quest-001-letter-a', 85);

// Get recommendations
const next = await tracker.getNextRecommendation();
// { nextQuest: 'quest-002-letter-b', reason: 'next_in_sequence' }

// Check stats
const stats = await tracker.getStats();
// { totalSessions: 12, completedQuests: 5, streakDays: 3, ... }