Applied Learning AI Notebooks (ALAIN)

AI manuals for AI models.

Turn developer docs into active learning, powered by OpenAI gpt‑oss 20B. Paste any Hugging Face model link or ID → get an interactive training notebook. Run locally or in the cloud.

About The Project

Inspiration: AI models progress daily, but practical adoption lags. Documentation is scattered, inconsistent, and often not runnable. Organizations need repeatable onboarding, not one‑off demos. ALAIN turns any model reference into a guided, runnable lesson with clear steps, guardrails, and transparent costs, so teams can ship faster on any stack, online or offline.

What It Does

The Problem: AI models advance daily; human onboarding lags. Current materials favor passive consumption over interactive practice, limiting effective learning.
The Solution: ALAIN uses gpt‑oss‑20b to automatically generate interactive tutorials for any model. Input a model reference, receive a complete lesson with setup instructions, runnable code, and assessments, export to Jupyter or Colab, and run anywhere.

How We Built It

Architecture Overview

├── Teacher Model: gpt-oss-20b with schema validation
├── Backend: Encore (TypeScript) + PostgreSQL (Neon)
│   ├── Execution service (provider routing/fallbacks)
│   ├── Tutorial service (CRUD)
│   └── Export service (Jupyter/Colab notebook generation)
├── Frontend: Next.js + React
│   ├── Model picker with instant preview
│   ├── Real‑time streaming output
│   └── Directory with search/filters
└── Deployment: Vercel (web) + Encore Cloud (backend)

Teacher model: gpt‑oss‑20b (teacher). Strong instruction‑following and JSON reliability.
Local or hosted: identical UX with Poe and OpenAI‑compatible endpoints (Ollama, LM Studio, vLLM).
ALAIN‑Kit (schema‑first):
- Research: ingest model card or text; normalize specs
- Design: draft Lesson JSON (Setup / Example / Verify / Guardrails)
- Develop: add runnable examples and assessments; parameterized API calls
- Validate: JSON schema validate; auto‑repair; preflight; export (nbformat Jupyter/Colab)
Prompting formats:
- OpenAI‑compatible (Ollama / LM Studio / vLLM): Harmony roles (system + developer)
- Poe: OpenAI Chat Completions; developer content folded into system
Reliability guarantees: parameterized backend execution only (no server‑side arbitrary code), reproducible prompts (hosted or local), and export to Jupyter/Colab.

Challenges We Overcame

Unstructured Inputs: Model cards vary widely; solved with schema‑first generation + repair loop
Provider Differences: Normalized on OpenAI‑compatible requests with intelligent routing/fallbacks
Safety vs. Interactivity: Kept server execution strictly parameterized while preserving hands‑on learning (client‑side runners use browser sandboxes)
Cost Transparency: Added rough token/cost estimates and provider smoke tests so users understand trade‑offs before they run

What We Learned

AI Teaching AI Works: gpt‑oss can synthesize high‑quality tutorials from heterogeneous sources
Schema‑First Wins: JSON schemas with validation/repair deliver reliability under messy real‑world inputs
Abstraction Matters: A clean provider layer unlocks seamless hosted <-> local switching
Offline Is Empowering: True local capability enables classrooms, air‑gapped labs, and low‑connectivity regions
Community Effects: Standardized, shareable "blueprints" compound learning and reduce onboarding from hours to minutes

Why Now

Models ship daily; documentation lags. ALAIN turns model cards into runnable lessons.
OpenAI-compatible APIs unify Poe, vLLM, Ollama, and LM Studio. ALAIN runs hosted and local with one instruction layer.
Consumer NVIDIA GPUs and mature runtimes make local learning practical. ALAIN keeps the UX identical offline.
gpt-oss-20b follows instructions and outputs reliable JSON. ALAIN uses it to synthesize lessons online or offline.
Teams need privacy and cost control. ALAIN uses parameterized execution, preflight checks, and notebooks for compliance and budgeting.
Educators need reusable content. ALAIN standardizes lessons from Hugging Face and exports to Jupyter and Colab.

Category Alignment

🎯 Wildcard - Most Unexpected Use: ALAIN uses OpenAI gpt‑oss 20B to generate interactive lessons for any model — AI teaching AI.

🌍 For Humanity: Democratizes AI education by transforming passive model documentation into active, hands‑on learning experiences. Reduces learning barriers, enabling global access through offline capability and removing cost barriers via open‑source platform.

🏠 Best Local Agent: Identical UX offline via OpenAI‑compatible endpoints (e.g., Ollama, LM Studio/vLLM).

Technology Stack

Languages & Frameworks: TypeScript, React, Next.js, Tailwind CSS
Backend & Runtime: Encore (TypeScript), Node.js
AI & Providers: gpt‑oss‑20b (teacher), Poe API (hosted), OpenAI‑compatible endpoints (Ollama; LM Studio/vLLM where configured)
Data & Auth: PostgreSQL (Neon), Clerk; optional Upstash KV; GitHub export
Notebooks & Tools: nbformat/Jupyter, ipywidgets, Vitest
Dev & Ops: Vercel (web), Encore Cloud (backend)

Try It Out

Live Demo: https://alain-ruddy.vercel.app GitHub: https://github.com/daniel-p-green/alain-ai-learning-platform

No-login core flow:
1. Open https://alain-ruddy.vercel.app/generate
2. Toggle "Force fallback mode (no backend)" to run web-only
3. Paste a model reference (e.g., openai/gpt-oss-20b)
4. Click Generate → open the tutorial → Render to Colab (web) to download a .ipynb
Quick local start:
1. Run npm install
2. Run ollama pull gpt-oss:20b
3. Run npm run dev:offline
4. Open http://localhost:3000 → Generate → Run a step → Export to Colab

Additional Highlights

Key Features:

Adapt Experience (Beginner/Intermediate/Advanced)
Public Gallery with filters
"Show Request" + cURL copy
Schema validation with auto‑repair
Secure Colab export with preflight

Safety:

No server‑side arbitrary code execution; only parameterized API calls
Client‑side code executes in browser sandboxes (Pyodide/Worker); exported notebooks run in the user’s environment
Secrets handled via Encore/Clerk
Notebooks do not embed secrets; users set keys in their environment
Preflight connectivity and smoke tests included

Why gpt-oss-20b

Open model fit: runs locally (Ollama/LM Studio/vLLM) with the same API shape as hosted
Instruction following: produces stepwise, teachable content with minimal prompt overhead
JSON reliability: strong schema adherence; fewer repair passes than smaller models
Cost and latency: fast enough for iterative generation and repair with real‑time previews
Community impact: open weights and local‑first unlock classrooms and air‑gapped labs

Testing Instructions (Judges)

No login required for core flow.

Open https://alain-ruddy.vercel.app/generate
Toggle "Force fallback mode (no backend)" to run web-only
Paste a model reference
- Hugging Face: openai/gpt-oss-20b
- Local (Open Models): select Local, set model to gpt-oss:20b
Click Generate → open the tutorial → “Render to Colab (web)” to download a .ipynb

Optional auth-only features:

Sign in with openmodelhack@aiguykc.com / Ikea4AI!
Visit /upload or /my/notebooks (admin pages are not required)

Local testing (optional):

npm install in web/, then npm run dev
Open http://localhost:3000 → Generate → enable fallback → generate → open tutorial → Render to Colab

How We Apply gpt-oss (Judging Criteria)

Application of gpt‑oss: gpt‑oss‑20b acts as the teacher that synthesizes structured, runnable lessons from model cards/repos; supports local/offline generation with identical API shape (Ollama/LM Studio/vLLM).
Design (incl. safety): Schema‑first with validation + auto‑repair; parameterized backend execution; preflight checks; accessible UI; clear fallback without backend.
Potential Impact: Makes any model “learnable” in minutes; useful for classrooms, low‑connectivity regions, and small labs with limited DevRel.
Novelty: “AI teaching AI” to produce instructional content across arbitrary models with exportable notebooks and uniform hosted <-> local UX.