Offline AI Integration

UbuntuPlay features native, on-device AI capabilities—including the Gogo AI Student Tutor and Adaptive Difficulty Engine—running entirely without internet.

How It Works — Three Tiers

Every AI request tries the richest available tier and falls back gracefully, so AI features never hard-fail:

The bridge page resolves its WebSocket endpoint from GET /api/ai/bridge-info (default port 3001, configurable via WS_BRIDGE_PORT; also served as wss://host:HTTPS_PORT/gogo-bridge). If the Gogo tab is closed or the device has no WebGPU, requests fall through to the lower tiers automatically.

Language Coverage

Tier 3 lookup data is built from FLORES+ (CC-BY-SA-4.0, NLLB Team / Open Language Data Initiative):

Untranslated strings always fail safely to English, so games remain fully playable in every language.

Capabilities

As of v10.48.0, the platform includes advanced local AI features powered by LiteRT-LM (Google AI Edge) and the Gemma 4 model family, designed for the African classroom context:

• Gogo AI Tutor: Context-aware hints and support for students during gameplay powered by Gemma 4 E2B.
• Local Language Translation: Game UIs translate into Bemba, Nyanja, Tonga, and Lozi (see coverage above).
• AI Level Generation: Dynamic content generation based on curriculum topics.
• Adaptive Difficulty: Recommends easy/medium/hard from the student's rolling accuracy.
• Vision Interface: Gesture-controlled interaction via MediaPipe Vision tasks (used by Rangi hand tracking).
• Voice Input: Web Speech API voice commands where the browser supports it.

Developer API

Games can access AI features via the UbuntuAI global object. The API is resilient and handles lazy-loading of models automatically.

1. Automated Translation

Batch translate multiple strings at once using local language models:

const translations = await window.UbuntuAI.batchTranslate(
  ["Level 1", "Score", "Game Over"],
  "Bemba"
);
console.log(translations["Level 1"]); // "Ilingi 1"

2. Content Generation

Generate structured level JSON for a game at a chosen difficulty and theme:

const level = await window.UbuntuAI.generateLevel(
  'nzelu',      // game id
  'medium',     // difficulty
  'Wildlife'    // optional theme
);
// Returns parsed JSON, or null if the engine is unavailable

3. Gesture Tracking

Initialize hand tracking for gesture-based gameplay:

const tracker = await window.UbuntuAI.initVision('hand');

Installation — Classroom Server

Two equivalent paths install the AI assets on a school server:

ubuntuplay setup-ai

Or use the model manager in the Teacher Dashboard's Gogo tab, which downloads each model with progress and validates file sizes (placeholder/stub files are never reported as installed). Assets land in public/js/ai/ — the LiteRT-LM runtime, the Gemma model, and MediaPipe vision tasks. The runtime loads with zero CDN dependencies, so it works on fully offline LANs.

Installation — Hub (Browser-Local AI)

The cloud Hub cannot host a teacher's Gogo tab, so it uses a browser-local mode instead: the Hub Admin toggles AI on (Hub Admin → Config), the hub downloads the same asset set to its data volume, and each visitor's browser runs the engine itself via WebGPU. This powers marketplace game demos ("Ask Gogo") and the parent tutor's on-device upgrade.

• GET /api/ai/status — advertises readiness and the client asset map
• Downloads resume automatically after an interrupted provisioning run
• Operators can tune behaviour with the HUB_AI_* environment variables — see Environment Variables →

Troubleshooting