scratch-gpt-oss

GPT-OSS Scratch Extension

License GitHub Pages

A Scratch extension that brings local AI education to schools, enabling students to learn coding with AI through visual blocks. Schools maintain complete privacy and safety control.

🎯 Overview

The GPT-OSS Scratch Extension integrates local AI capabilities into Scratch’s visual programming environment. This open-source platform makes AI tangible and accessible to learners while ensuring complete data privacy through local deployment.

🌟 Key Features

🔒 Privacy-First Architecture

🛡️ Multi-Layer Safety System

🎓 Educational AI Blocks

📊 Comprehensive Admin Dashboard

🚀 Quick Start

# Clone the repository
git clone https://github.com/cindyhuen/scratch-gpt-oss.git
cd scratch-gpt-oss

# Run the setup script
./start-scratch.sh

# Open in browser
open http://localhost:8602

👥 Student Management

Important: After setting up the system, administrators must create student accounts through the admin interface to enable proper AI usage tracking.

Creating Students with Personalized QR Codes

  1. Access Admin Interface: Navigate to http://127.0.0.1:8602/static/admin/ (or use your IP address and port)
  2. Create Students: Use the admin dashboard to add individual students
  3. Generate QR Codes: Each student receives a personalized QR code for easy access
  4. Enable Tracking: Personalized QR codes allow the system to track individual AI usage patterns

Example Student Login URL: http://127.0.0.1:8602?student=12345&class=grade8a (or use your IP address and port)

Benefits of Student Management

📋 Setup Reminder: Always create student accounts through the admin interface before classroom use to ensure proper tracking and analytics functionality.

📖 Installation Guide

Detailed setup guide for administrators to get the complete system running.

Prerequisites

1. Setup GPT-OSS Server

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Download model (choose one)
# For faster performance and basic educational use:
ollama pull gpt-oss:20b

# For advanced reasoning and research-level performance:
ollama pull gpt-oss:120b

# Start server
ollama serve
# Runs on http://localhost:11434

2. Setup NeMo Guardrails (Optional)

# Install NeMo
brew install pipx && pipx install nemoguardrails
pipx inject nemoguardrails langchain-openai

# Start NeMo server
cd nemo-guardrails
./start-nemo.sh
# Runs on http://localhost:8001

3. Configure System

Edit config.js:

module.exports = {
  gptoss: {
    host: 'localhost',    // GPT-OSS server
    port: 11434,
    model: 'gpt-oss:20b'
  },
  nemoGuardrails: {
    enabled: true,        // Line 39 - Set false to disable NeMo
    host: 'localhost',    // NeMo server
    port: 8001
    // If enabled=true but NeMo fails → shows "NeMo unavailable" error
    // If enabled=false → direct GPT-OSS (no filtering)
  }
}

📋 Configuration Update Notes:

4. Install & Start Scratch

# Install dependencies
cd scratch-vm && npm install
cd ../scratch-gui && npm install

# Start Scratch
npm start
# Runs on http://localhost:8602

5. Test Setup

# Test GPT-OSS server
./test-openai.sh

# Test NeMo server (if enabled)
./test-nemo-connection.sh

# Set up students after testing
# Navigate to http://127.0.0.1:8602/static/admin/ to create student accounts with personalized QR codes

🏗️ System Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Student       │    │  NeMo Guardrails │    │    GPT-OSS      │
│   Scratch UI    │───▶│  Content Filter   │───▶│   AI Server     │
│  (Port 8602)    │    │   (Port 8001)     │    │  (Port 11434)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Components:

Request Flow:

📁 Repository Structure

gpt-oss-scratch-extension/
├── README.md
├── config.js
├── start-scratch.sh
├── test-nemo-connection.sh
├── test-nemo-safety.sh  
├── test-openai.sh
├── .gitignore
├── nemo-guardrails/           # NeMo configuration
│   ├── start-nemo.sh
│   ├── generate-flows.js
│   └── nemo-education-config/
├── scratch-gui/               # Modified Scratch GUI
│   ├── src/lib/libraries/extensions/gptoss/  # Extension assets
│   ├── static/                # Static assets and admin interface
│   │   ├── admin/             # Complete admin dashboard
│   │   ├── index.html         # Main documentation
│   │   └── *.css, *.js        # Styling and functionality
│   └── package.json
└── scratch-vm/                # Modified Scratch VM
    ├── src/extensions/scratch3_gptoss/       # AI extension code
    └── package.json

Key Directories:

📚 Documentation

📞 Contact

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright 2025 Cindy Huen. Licensed under the Apache License, version 2.0.

This site is open source. Improve this page.