Skip to content

About

Domain-neutral adaptive learning engine with schema-driven course packs. Socratic tutoring, mastery tracking, multi-subject isolation, and offline Mind Elixir knowledge maps.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

26 Commits

Folders and files

Repository files navigation

๐ŸŽ“ Adaptive Learning Coach

A domain-neutral adaptive learning engine with schema-driven course packs.

Socratic tutoring ยท mastery tracking ยท multi-subject isolation ยท offline Mind Elixir knowledge maps

License Node TypeScript Mind Elixir Tests

Adaptive Learning Coach turns a structured technical subject (programming, mathematics, algorithms & data, and other quantitative disciplines) into an adaptive one-on-one learning path. It separates a domain-neutral engine from schema-driven course packs, so adding a new subject means adding a pack โ€” never touching engine code.

The coach teaches in Chinese while retaining English technical terms, APIs, identifiers, and code.


โœจ Features

  • Domain-neutral engine โ€” zero hard-coded subject facts; every discipline is a validated course pack.
  • Prerequisite graph โ€” a DAG of concepts with stable IDs, stage, objectives, and validator preferences.
  • Adaptive mastery (0โ€“4) โ€” diagnose, unlock, teach, and re-schedule review per learner.
  • Socratic tutoring ladder โ€” reasoning โ†’ minimal hint โ†’ smaller guiding question โ†’ full answer + variation.
  • Active practice โ€” Easy=1 / Medium=2 / Hard=3 exercises per round, revealed one at a time.
  • Deterministic-first validation โ€” compiler/tests/runtime/static analysis, symbolic & numeric math; rubric fallback with exact evidence labels.
  • Multi-subject isolation โ€” per-pack state under .adaptive-learning/<pack-id>/, never cross-contaminated.
  • Offline Mind Elixir maps โ€” single-file HTML knowledge maps (no CDN, no network) with status colors, search, filters, details, zoom, and PNG export.
  • Fail-closed safety โ€” read-only official packs, no arbitrary pack commands, atomic writes, path/symlink containment.

๐Ÿงฑ Architecture

The engine owns orchestration, schemas, persistence, validators, the generated-pack lifecycle, and one domain-neutral viewer. All subject knowledge lives in course packs.

Adaptive Learning Coach โ€” domain-neutral engine SKILL.md ยท schemas/ ยท scripts/ ยท references/ ยท assets/ (state-templates + mind-map-viewer) validate-pack ยท validate-state ยท generate-pack ยท generate-map ยท adapters ยท state ยท map-data reads / validates writes / renders course-packs/ โ€” subject knowledge typescript/ ยท origin: official ยท readOnly: true generated/linear-algebra/ ยท generated ยท calibratable .adaptive-learning/ โ€” per-learner state <pack-id>/ ยท profile.json ยท progress.json ยท mistakes.md knowledge-map.html (offline Mind Elixir)

Engine code contains no subject facts โ€” packs contain no engine code.


๐Ÿ” How a session works

Every subject runs the same ten-step loop.

1 ยท route ่ทฏ็”ฑ่ฏทๆฑ‚ 2 ยท pack ๅ‘็Žฐ/็”Ÿๆˆ+ๆ ก้ชŒ 3 ยท state ้š”็ฆปๅญฆ็ง‘็Šถๆ€ 4 ยท diagnose ่ฏŠๆ–ญๅ…ˆไฟฎ 5 ยท select ้€‰่Š‚็‚น 6 ยท teach ๆŽˆ่ฏพ 7 ยท practice ็ปƒไน ยทไธ€ๆฌกไธ€้ข˜ 8 ยท assess ้ชŒ่ฏ 9 ยท update ๆ›ดๆ–ฐ่ฏๆฎ 10 ยท render ้‡็ป˜ๅ›พ่ฐฑ

๐Ÿ“š The learning model

Mastery levels (0โ€“4)

Level Meaning Unlock
0 Not encountered โ€”
1 Recognizes the concept โ€”
2 Can reproduce with guidance โ€”
3 Can apply independently unlocks dependents
4 Can explain, transfer, combine mastery

Exercise count per round

Difficulty Count
Easy 1
Medium 2
Hard 3

Rounds announce the total but reveal one exercise at a time.

Socratic ladder

1 ยท Ask for reasoning ่ฏท่ฏดๆ˜ŽๆŽจ็†๏ผŒๆŒ‡ๅ‡บๅ†ณ็ญ–็‚น 2 ยท Minimal hint ๆŒ‡ๅ‘็›ธๅ…ณๆฆ‚ๅฟต๏ผŒ็ป™ๅ‡บๆœ€ๅฐๆ็คบ 3 ยท Smaller guided question ๆ‹†ๆˆไธ€ไธชๆ›ดๅฐ็š„ๅผ•ๅฏผ้—ฎ้ข˜ 4 ยท Full answer + variation ็ฌฌ 3 ๆฌกๅผ•ๅฏผๅคฑ่ดฅๅŽ็ป™ๅฎŒๆ•ด็ญ”ๆกˆไธŽๆŽจ็†๏ผŒๅนถ็ซ‹ๅณๅ˜ๅผ้ข˜

Evidence labels โ€” the three exact labels

Label Meaning
tool-verified verified by a deterministic tool (compiler, tests, runtime, symbolic/numeric math, โ€ฆ)
ๅŸบไบŽ่ฏ„ๅˆ†ๆ ‡ๅ‡†ๅˆคๆ–ญ judged by rubric + reasoning only (no tool)
unverified not verified

A rubric result is never reported as tool-verified; a tool error is never recorded as a learner error.

Node statuses

locked ๆœช่งฃ้” available ๅฏๅญฆไน  learning ๅญฆไน ไธญ mastered ๅทฒๆŽŒๆก current ๅฝ“ๅ‰ review ๅพ…ๅคไน  prereq level < 3 prereqs โ‰ฅ 3 level 1โ€“3 level โ‰ฅ 4 currentNodeId dueAt โ‰ค now

Precedence: review-due > current > mastered > learning > available > locked


๐Ÿ—‚ Directory structure

adaptive-learning-coach/          # the domain-neutral engine (the skill)
โ”œโ”€โ”€ SKILL.md                      # workflow (82 lines) + frontmatter
โ”œโ”€โ”€ agents/openai.yaml            # Codex/OpenAI skill metadata
โ”œโ”€โ”€ schemas/                      # JSON Schema 2020-12 contracts
โ”‚   โ”œโ”€โ”€ pack.schema.json
โ”‚   โ”œโ”€โ”€ graph.schema.json
โ”‚   โ”œโ”€โ”€ profile.schema.json
โ”‚   โ””โ”€โ”€ progress.schema.json
โ”œโ”€โ”€ references/                   # progressive-disclosure guides
โ”‚   โ”œโ”€โ”€ learning-workflow.md
โ”‚   โ”œโ”€โ”€ mastery-and-review.md
โ”‚   โ”œโ”€โ”€ exercise-generation.md
โ”‚   โ”œโ”€โ”€ pack-authoring.md
โ”‚   โ””โ”€โ”€ adapter-selection.md
โ”œโ”€โ”€ scripts/
โ”‚   โ”œโ”€โ”€ validate-pack.mjs
โ”‚   โ”œโ”€โ”€ validate-state.mjs
โ”‚   โ”œโ”€โ”€ generate-pack.mjs
โ”‚   โ”œโ”€โ”€ generate-map.mjs
โ”‚   โ””โ”€โ”€ lib/
โ”‚       โ”œโ”€โ”€ pack.mjs              # manifest/graph/files validators + allowlist
โ”‚       โ”œโ”€โ”€ state.mjs             # index/profile/progress validators + paths
โ”‚       โ”œโ”€โ”€ adapters.mjs          # exercise counts, adapter selection, evidence, calibration
โ”‚       โ”œโ”€โ”€ generator.mjs         # atomic generated-pack writer
โ”‚       โ””โ”€โ”€ map-data.mjs          # graph โ†’ mind-map payload + HTML injection
โ””โ”€โ”€ assets/
    โ”œโ”€โ”€ state-templates/          # index/profile/progress/mistakes templates
    โ””โ”€โ”€ mind-map-viewer/          # TypeScript + Vite + Mind Elixir viewer โ†’ dist/index.html

course-packs/
โ”œโ”€โ”€ typescript/                   # official, read-only โ€” 43 nodes, 5 projects
โ””โ”€โ”€ generated/linear-algebra/     # generated, calibratable โ€” 11 nodes, 1 applied project

tests/
โ””โ”€โ”€ adaptive-learning-coach/      # pack validation, migration, state/adapters,
                                  # generated-pack, map-data, structure, scenarios, forward-results

๐Ÿš€ Quick start

Requirements

  • Node.js โ‰ฅ 22.12 (the skill CLIs are dependency-free; the viewer build uses npm)

Install the skill into DSH

DSH discovers directory-bundle skills (<dir>/SKILL.md with name + description frontmatter) from project and user roots:

Root Path
project <repo>/.dsh/skills/ (or <repo>/.agents/skills/)
user ~/.dsh/skills/ (or ~/.agents/skills/)

From this repository's root:

New-Item -ItemType Directory -Force -Path ".dsh\skills" | Out-Null
New-Item -ItemType SymbolicLink -Path ".dsh\skills\adaptive-learning-coach" -Target "..\adaptive-learning-coach"

A symlink (not a copy) keeps the generator's course-packs/generated/ default rooted at the repo. On Windows use cmd /c mklink /J if symlinks need Developer Mode.

The skill is also Codex-compatible (agents/openai.yaml), installable under ~/.codex/skills/ the same way.

Validate everything

node adaptive-learning-coach/scripts/validate-pack.mjs --pack course-packs/typescript
node adaptive-learning-coach/scripts/validate-pack.mjs --pack course-packs/generated/linear-algebra
node --test tests/adaptive-learning-coach/*.test.mjs

Generate an offline knowledge map

node adaptive-learning-coach/scripts/generate-map.mjs `
  --pack course-packs/typescript `
  --progress .adaptive-learning/typescript/progress.json `
  --template adaptive-learning-coach/assets/mind-map-viewer/dist/index.html `
  --out .adaptive-learning/typescript/knowledge-map.html

๐Ÿงฐ CLI reference

Script Purpose
validate-pack.mjs --pack <root> validate a course pack (schema + files + containment), exit 0/1
validate-state.mjs --pack --graph --index --profile --progress validate learner state + cross-check pack IDs
generate-pack.mjs --draft <json> --out <dir> atomically write a generated pack into course-packs/generated/
generate-map.mjs --pack --progress --template --out render an offline Mind Elixir map
generate-map.mjs --landing <json> --out render the multi-subject landing page

๐Ÿงช Testing

node --test tests/adaptive-learning-coach/*.test.mjs   # 64 tests
npm test  --prefix adaptive-learning-coach/assets/mind-map-viewer                                   # 5 vitest tests
npx tsc --noEmit --prefix adaptive-learning-coach/assets/mind-map-viewer                            # type check
npm run build --prefix adaptive-learning-coach/assets/mind-map-viewer                               # single-file dist

Coverage: pack schema/validation, TypeScript pack migration, state & adapter contracts, generated-pack safety, map data/escaping, skill structure & domain-neutrality, plus four forward scenarios (TypeScript, linear algebra, multi-subject, read-only).


๐Ÿ›ก Safety & design principles

  • Read-only by default โ€” official/user-locked packs are never calibrated; calibration only bumps revision on generated packs.
  • No arbitrary code โ€” packs declare built-in adapter IDs only; any command not mapped to an adapter is rejected.
  • Fail closed โ€” every pack path passes lexical + canonical filesystem containment checks; symlink escape and canonicalization failure reject.
  • Preserve on failure โ€” atomic writes (temp + rename with backup) and state preserved on corruption.
  • Offline viewer โ€” Mind Elixir (not Mermaid), single-file HTML, no CDN requests.
  • No subject leakage โ€” the engine is scanned by a test to contain zero subject-specific tokens.

๐Ÿงญ Project status

All planned tasks are complete and review-clean: generic engine skeleton & pack validation โ†’ TypeScript official pack โ†’ state/adapters โ†’ generated linear-algebra pack โ†’ offline Mind Elixir viewer โ†’ generic SKILL.md workflow โ†’ forward scenarios & delivery.

The TypeScript pack is the first official fixture; linear algebra is the first generated fixture proving the engine has no hidden TypeScript coupling.

๐Ÿค Contributing

Contributions welcome. This project follows a strict test-first, review-clean discipline โ€” run the full test suite before opening a PR.

๐Ÿ“„ License

MIT ยฉ Adaptive Learning Coach contributors

About

Domain-neutral adaptive learning engine with schema-driven course packs. Socratic tutoring, mastery tracking, multi-subject isolation, and offline Mind Elixir knowledge maps.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages