Understanding Lab

Explain it. Test it. Understand it.

English · 简体中文

Understanding Lab is a local-first, bilingual AI course with 12 interactive chapters: data splits, regression, overfitting, optimization, classification, neural networks, embeddings, attention, generation, retrieval, evaluation, and responsible deployment. Predict, explore a deterministic experiment, explain a transfer case, and reflect. Course progress stays in this browser. The original overfitting learning loop remains available separately.

Download and start — v0.2.0

Release notes and downloads · Static course archive

1. Download understanding-lab-0.2.0-static.tar.gz and its .sha256 file from the release. Verify the checksum, then extract it.

2. With Python 3.9+ installed, open a terminal in the extracted understanding-lab-0.2.0-static folder and run:

   python3 serve.py

   On Windows, use py serve.py if appropriate.

3. Open http://127.0.0.1:4173/. No npm, Node.js, account, API key or backend is needed. Wait for the cache-ready message before going offline. Do not open index.html directly with file://.

This release is the anonymous, local-first static course, not a hosted account/AI service. Before updating, export both course progress and any original-lesson draft; keep the same browser, hostname and port, and do not clear site data. See release/build checks and packaged usage instructions.

Course map

Chapters	Topics
1–3	Data splits and leakage · regression · overfitting
4–6	Gradient descent · classification · neural networks
7–9	Embeddings · attention weights · language-model generation
10–12	Retrieval-augmented generation · evaluation · responsible deployment

Every chapter includes explanation, prediction with feedback, a deterministic experiment, transfer practice, corrected knowledge checks, reflection and sources. Both languages use the same progress record; suggested prerequisites are not locks.

See the app

  

These screenshots show the retained original overfitting lesson, not the new course catalog. Examples are synthetic, not model-generated teaching feedback.

What you can do

• Learn locally: keep drafts and notes in your browser; cache the built app for offline use.
• Switch languages: use English or 简体中文 without rewriting your answers, notes, experiments, or historical feedback. Your preference stays in this browser.
• Follow a complete course: explore 12 chapters in either language, with predictions, distinct experiment comparisons, knowledge checks, self-review rubrics, and reflections. Suggested time totals about 7 hours; this is an editorial estimate, not measured learner performance.
• Explore the original overfitting lab: compare curves and training/validation error across 324 precomputed configurations, then freeze a choice before revealing test error.
• Stay in control: export course progress and confirm before resetting it. Optional account saving, tutor feedback, and voice transcription apply to the retained original lesson, with separate consent when configured.

How a lesson works

New course: read → predict → experiment → transfer → check and revise → reflect. Prerequisites are suggestions, not locks. Completion records practice evidence and corrected checks, not certified mastery. Transfer/reflection length checks do not grade reasoning; use the provided rubric. No AI service is called by the course.

Original overfitting lesson: Explain → predict → experiment → re-explain → transfer → reflect. You can skip prompts and return to earlier answers. In the overfitting experiment, choose a model before revealing held-out test error. Changing the setup after reveal marks the test result as contaminated. The experiment catalog contains 324 reproducible configurations; its numeric outcomes are generated data, not a claim about every real dataset.

Learning works without an account or AI provider. Sending an answer to the optional tutor and saving an attempt to an account are separate actions with separate consent. Voice transcription is optional too: recording does not send audio until you explicitly request transcription. Tutor and transcription are disabled by default. Enabling the tutor can make a potentially billable provider probe at every server start. Configuration steps are in the getting started guide.

Run locally

Requires Node.js 22.12 or newer and npm. Node 22.23.2 / npm 10.9.8 were used for the verified setup. better-sqlite3 includes a native module; on platforms without a matching prebuilt binary, installation may require local build tools.

git clone --branch codex/understanding-lab-mvp https://github.com/tsumon/understanding-lab.git
cd understanding-lab
npm ci
npm run dev

Open the local URL printed by Vite: / opens the course catalog, /#course/<chapter-id> a chapter, and /#legacy the original lesson. No .env, account, model key, or backend server is needed for local course study. For offline use and optional account, tutor, and transcription services, follow Getting started. The deeper deployment guide is in Chinese.

For offline use, run npm run build:offline and npm run preview:offline, visit the printed URL online once, and wait for the cache-ready status before going offline. External source links still need a connection. Course records are separate from original lesson drafts; browser storage is not a durable backup.

Project checks

npm run typecheck
npm test
npm run experiment:test
npm run build:offline

The experiment checks also require uv and Python 3.12.13; see Contributing for setup and browser checks. CI uses deterministic fixtures, not paid model calls.

Current scope

Twelve bilingual chapters plus the retained original overfitting lesson, delivered as a responsive web app; no hosted service or native app package. Course experiments use synthetic data, fixed examples and explicitly stated simplifications—not production model evaluations. Real-model teaching quality, human review (including the English translation), real OAuth, and physical-device voice acceptance are still pending. An intermittent WebKit draft/summary regression remains open. Engineering checks are not proof of learning outcomes.

Documentation

• v0.2.0 release notes and release/build checklist
• Course plan and platform/storage boundaries
• Getting started: local setup and optional services
• Contributing: changes, checks, and data handling
• Deployment and privacy boundaries (Chinese)
• License and third-party notices

License

Original project source and documentation are offered under the MIT License, subject to the separate terms of dependencies and other materials described in THIRD_PARTY_NOTICES.md.