> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Interactive Programming Tutorials

> Build Codecademy-style interactive learning with step-by-step code execution, progress tracking, hint systems, and solution validation

Build an interactive programming tutorial platform where students learn by writing and executing code step-by-step. This cookbook demonstrates how to create a Codecademy-style learning experience using HopX.

## Overview

Interactive programming tutorials guide students through learning by executing code at each step. The system validates solutions, provides hints, tracks progress, and ensures students understand concepts before moving forward.

## Prerequisites

* HopX API key ([Get one here](https://console.hopx.dev/api-keys))
* Python 3.8+ or Node.js 16+
* Understanding of educational content structure
* Basic knowledge of progress tracking

## Architecture

```
┌──────────────┐
│   Student    │ Submits code
└──────┬───────┘
       │
       ▼
┌─────────────────┐
│  Tutorial       │ Validate, provide hints
│   Engine        │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  HopX Sandbox   │ Execute & validate
└─────────────────┘
```

## Implementation

### Step 1: Tutorial Step Execution

Execute and validate tutorial steps:

```python Python theme={null}
from hopx_ai import Sandbox
import os
from typing import Dict, List, Any

class TutorialStep:
    def __init__(self, step_id: str, instructions: str, solution: str, hints: List[str]):
        self.step_id = step_id
        self.instructions = instructions
        self.solution = solution
        self.hints = hints

class InteractiveTutorial:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.sandbox = None
        self.current_step = 0
        self.steps = []
    
    def initialize(self):
        """Initialize tutorial session"""
        self.sandbox = Sandbox.create(
            template="code-interpreter",
            api_key=self.api_key,
            timeout_seconds=3600
        )
    
    def add_step(self, step: TutorialStep):
        """Add tutorial step"""
        self.steps.append(step)
    
    def validate_step(self, step_index: int, student_code: str) -> Dict[str, Any]:
        """Validate student code for a step"""
        step = self.steps[step_index]
        
        # Execute student code
        result = self.sandbox.run_code(student_code, timeout=10)
        
        # Check if solution matches
        solution_result = self.sandbox.run_code(step.solution, timeout=10)
        
        # Compare outputs
        student_output = result.stdout.strip() if result.success else ""
        solution_output = solution_result.stdout.strip() if solution_result.success else ""
        
        passed = student_output == solution_output and result.success
        
        return {
            "passed": passed,
            "student_output": student_output,
            "expected_output": solution_output,
            "hint": step.hints[0] if not passed and step.hints else None,
            "success": result.success
        }
    
    def get_next_hint(self, step_index: int, hint_index: int) -> str:
        """Get hint for current step"""
        step = self.steps[step_index]
        if hint_index < len(step.hints):
            return step.hints[hint_index]
        return "No more hints available"
    
    def cleanup(self):
        """Clean up tutorial session"""
        if self.sandbox:
            self.sandbox.kill()
            self.sandbox = None

# Usage
tutorial = InteractiveTutorial(api_key=os.getenv("HOPX_API_KEY"))
tutorial.initialize()

# Add steps
tutorial.add_step(TutorialStep(
    step_id="step_1",
    instructions="Print 'Hello, World!'",
    solution="print('Hello, World!')",
    hints=["Use the print() function", "Remember to use quotes around the text"]
))

# Validate student code
result = tutorial.validate_step(0, "print('Hello, World!')")
print(f"Passed: {result['passed']}")

tutorial.cleanup()
```

```javascript JavaScript theme={null}
import { Sandbox } from '@hopx-ai/sdk';

class TutorialStep {
    constructor(stepId, instructions, solution, hints) {
        this.stepId = stepId;
        this.instructions = instructions;
        this.solution = solution;
        this.hints = hints;
    }
}

class InteractiveTutorial {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.sandbox = null;
        this.currentStep = 0;
        this.steps = [];
    }
    
    async initialize() {
        this.sandbox = await Sandbox.create({
            template: 'code-interpreter',
            apiKey: this.apiKey,
            timeoutSeconds: 3600
        });
    }
    
    addStep(step) {
        this.steps.push(step);
    }
    
    async validateStep(stepIndex, studentCode) {
        const step = this.steps[stepIndex];
        
        // Execute student code
        const result = await this.sandbox.runCode(studentCode, { timeout: 10 });
        
        // Check if solution matches
        const solutionResult = await this.sandbox.runCode(step.solution, { timeout: 10 });
        
        // Compare outputs
        const studentOutput = result.success ? result.stdout.trim() : '';
        const solutionOutput = solutionResult.success ? solutionResult.stdout.trim() : '';
        
        const passed = studentOutput === solutionOutput && result.success;
        
        return {
            passed,
            studentOutput,
            expectedOutput: solutionOutput,
            hint: !passed && step.hints.length > 0 ? step.hints[0] : null,
            success: result.success
        };
    }
    
    getNextHint(stepIndex, hintIndex) {
        const step = this.steps[stepIndex];
        if (hintIndex < step.hints.length) {
            return step.hints[hintIndex];
        }
        return 'No more hints available';
    }
    
    async cleanup() {
        if (this.sandbox) {
            await this.sandbox.kill();
            this.sandbox = null;
        }
    }
}

// Usage
const tutorial = new InteractiveTutorial(process.env.HOPX_API_KEY);
await tutorial.initialize();

// Add steps
tutorial.addStep(new TutorialStep(
    'step_1',
    "Print 'Hello, World!'",
    "print('Hello, World!')",
    ['Use the print() function', 'Remember to use quotes around the text']
));

// Validate student code
const result = await tutorial.validateStep(0, "print('Hello, World!')");
console.log(`Passed: ${result.passed}`);

await tutorial.cleanup();
```

### Step 2: Progress Tracking

Track student progress through tutorials:

```python Python theme={null}
class ProgressTracker:
    def __init__(self):
        self.progress = {}
    
    def update_progress(self, student_id: str, step_id: str, passed: bool):
        """Update student progress"""
        if student_id not in self.progress:
            self.progress[student_id] = {
                "completed_steps": [],
                "current_step": 0,
                "total_steps": 0
            }
        
        if passed and step_id not in self.progress[student_id]["completed_steps"]:
            self.progress[student_id]["completed_steps"].append(step_id)
    
    def get_progress(self, student_id: str) -> Dict[str, Any]:
        """Get student progress"""
        if student_id not in self.progress:
            return {
                "completed_steps": [],
                "current_step": 0,
                "completion_percentage": 0
            }
        
        student_progress = self.progress[student_id]
        total = student_progress.get("total_steps", 1)
        completed = len(student_progress["completed_steps"])
        
        return {
            "completed_steps": student_progress["completed_steps"],
            "current_step": student_progress["current_step"],
            "completion_percentage": (completed / total * 100) if total > 0 else 0
        }

# Usage
tracker = ProgressTracker()
tracker.update_progress("student_1", "step_1", True)
tracker.update_progress("student_1", "step_2", True)

progress = tracker.get_progress("student_1")
print(f"Completion: {progress['completion_percentage']:.1f}%")
```

```javascript JavaScript theme={null}
class ProgressTracker {
    constructor() {
        this.progress = {};
    }
    
    updateProgress(studentId, stepId, passed) {
        if (!this.progress[studentId]) {
            this.progress[studentId] = {
                completedSteps: [],
                currentStep: 0,
                totalSteps: 0
            };
        }
        
        if (passed && !this.progress[studentId].completedSteps.includes(stepId)) {
            this.progress[studentId].completedSteps.push(stepId);
        }
    }
    
    getProgress(studentId) {
        if (!this.progress[studentId]) {
            return {
                completedSteps: [],
                currentStep: 0,
                completionPercentage: 0
            };
        }
        
        const studentProgress = this.progress[studentId];
        const total = studentProgress.totalSteps || 1;
        const completed = studentProgress.completedSteps.length;
        
        return {
            completedSteps: studentProgress.completedSteps,
            currentStep: studentProgress.currentStep,
            completionPercentage: total > 0 ? (completed / total * 100) : 0
        };
    }
}

// Usage
const tracker = new ProgressTracker();
tracker.updateProgress('student_1', 'step_1', true);
tracker.updateProgress('student_1', 'step_2', true);

const progress = tracker.getProgress('student_1');
console.log(`Completion: ${progress.completionPercentage.toFixed(1)}%`);
```

## Best Practices

1. **Step-by-Step Learning**: Break concepts into small, digestible steps
2. **Immediate Feedback**: Provide instant validation feedback
3. **Progressive Hints**: Offer hints that guide without giving away solutions
4. **Progress Persistence**: Save progress so students can resume

## Related Cookbooks

* [Online Coding Platform](https://docs.hopx.ai/cookbooks/educational/online-coding-platform.md) - Full coding platform
* [Coding Interview Platform](https://docs.hopx.ai/cookbooks/educational/coding-interviews.md) - Interview preparation

## Next Steps

1. Create tutorial content management system
2. Implement hint system with multiple levels
3. Add progress persistence
4. Create tutorial authoring tools
5. Add analytics and reporting


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.