A complete adaptive-learning platform built on the six-method learning model (Asterios Raptis, From Theory to Practice: The Series, Medium series). Pick the method that fits the learner — deductive, inductive, error-based, dialogic, contextual, or AI-adaptive — walk through a seven-step cycle on every session, and let a dual-prompt AI decide when the learner is ready to advance. Auto-loop into a new cycle once the topic is integrated. Bring your own AI key (Anthropic / OpenAI / Gemini) and enter it under Settings > AI.
Full documentation (German default at /docs/, English at
/docs/en/):
astrapi69.github.io/adaptive-learner/docs/en/
- User Guide — how to use the app
- The Learning Method — why adaptive learning works
- Developer Guide — architecture, plugins, contributing
- API Reference — all endpoints and models
- Configuration — three-layer config
chain (env >
secrets.yaml> DB) - App Flow: every screen, how it is reached, and the main journeys through the app
- Design Brief: audience, design principles, visual system and open design questions
The full, canonical feature list lives on the docs site: Feature overview (one source, kept current with every release; this README only summarizes). In short:
- Learning core - six learning methods, a seven-step session cycle with a dual-prompt evaluator, auto-loop, method switching.
- AI tutor chat - assistant-ui thread with streaming replies, voice input, read-aloud, imported-conversation continuation; bring your own key (Anthropic / OpenAI / Gemini).
- Exercises - six core types (matching, picture choice, free text, cloze, word tiles, multiple choice) plus five extension types (categorization, error correction, reading comprehension, graded quiz, audio dictation).
- Lessons - seven play modes (Practice / Exam / Timed / Reverse / Shuffle / Endless / train-errors), SRS review, adaptive lessons from your own errors, pause/resume.
- Authoring - the Create-Lesson wizard: editable exercises, book-text ingestion (paste or EPUB/DOCX/TXT/MD upload with chapter picker and batch generation), AI exercise generation with a quality gate.
- Content - downloadable lesson sets from federated GitHub content repos, community sharing via pull request, per-set deep links and QR codes.
- Import + analysis - chat-history import (ChatGPT / Claude / Gemini / markdown) with AI analysis into curricula, sessions, or offline lessons.
- Gamification - XP, tiered badges, streaks, daily missions, celebrations.
- Exports + backup - Anki, NotebookLM, learning repository,
Markdown/PDF reports,
.albbackups and encrypted.alkkey export. - Platform - installable offline PWA, dual storage (browser IndexedDB or self-hosted server), local-network sync, desktop launcher for Linux/macOS/Windows, eleven UI languages.
- Accessibility - WCAG-AA themes, keyboard-first navigation, screen-reader support, reduced motion, TTS.
329 lessons · 28 sets · 2 domain(s) (language, software) — bundled offline into the GitHub Pages build from astrapi69/adaptive-learner-content.
| Set | Source | Target | Level | Lessons | Review |
|---|---|---|---|---|---|
| Englisch A1 (für Deutschsprachige) | de | en | A1 | 15 | authored |
| Englisch A2 - Grundlagen | de | en | A2 | 15 | authored |
| Englisch B1 - Mittelstufe | de | en | B1 | 15 | authored |
| Spanisch A1 (für Deutschsprachige) | de | es | A1 | 15 | authored |
| Spanisch A2 - Grundlagen | de | es | A2 | 15 | authored |
| Spanisch B1 - Mittelstufe | de | es | B1 | 15 | authored |
| Französisch A1 (für Deutschsprachige) | de | fr | A1 | 16 | authored |
| Französisch A2 - Grundlagen | de | fr | A2 | 16 | authored |
| Französisch B1 - Mittelstufe | de | fr | B1 | 16 | authored |
| Italienisch A1 (für Deutschsprachige) | de | it | A1 | 10 | authored |
| Japanisch Schrift: Hiragana (Vorstufe) | de | ja | A0 | 10 | authored |
| Japanisch A1 (für Deutschsprachige) | de | ja | A1 | 10 | generated |
| Koreanisch A1 (für Deutschsprachige) | de | ko | A1 | 10 | generated |
| Portugiesisch (Brasilianisch) A1 (für Deutschsprachige) | de | pt | A1 | 10 | authored |
| Chinesisch A1 (für Deutschsprachige) | de | zh | A1 | 10 | generated |
| German A1 (for English speakers) | en | de | A1 | 5 | authored |
| German A2 (for English speakers) | en | de | A2 | 5 | authored |
| Spanish A1 (for English speakers) | en | es | A1 | 15 | authored |
| Spanish A2 - Elementary | en | es | A2 | 15 | authored |
| Spanish B1 - Intermediate | en | es | B1 | 15 | authored |
| Spanish B2 (for English speakers) | en | es | B2 | 5 | authored |
| French A1 (for English speakers) | en | fr | A1 | 16 | authored |
| French A2 - Elementary | en | fr | A2 | 15 | authored |
| French B1 (for English speakers) | en | fr | B1 | 5 | authored |
| Γαλλικά A1 (για ελληνόφωνους) | el | fr | A1 | 8 | authored |
| अंग्रेज़ी A1 (हिंदी भाषियों के लिए) | hi | en | A1 | 10 | authored |
| अंग्रेज़ी A2 (हिंदी भाषियों के लिए) | hi | en | A2 | 5 | authored |
| Adaptive Learner - App-Tutorial | de | de | none | 12 | authored |
3 AI-generated sets excluded from the badge pending native-speaker review.
The content system is open: beyond the bundled library, anyone can host their own content repository on GitHub, connect it in Settings > Data > Content repositories, and have it browsed (and optionally recommended) in the app. The official library and user repos share the exact same format, so a validating repo is a first-class content source.
Want to create your own lessons? See the Content-Repo Guide — what a content repo is, the directory layout, local validation, trust levels, and the ready-made starter kit.
Four ways to run Adaptive Learner, in order of friction.
The public PWA runs in Local mode — all your data stays in your browser (IndexedDB), AI calls fire direct from the page to Anthropic / OpenAI / Gemini using your own API key. No backend, no install.
On Chrome / Edge / Safari you'll see an "Add to home screen" prompt the first time — accept and Adaptive Learner becomes a standalone PWA you launch from your desktop or phone home screen.
Pre-built single-binary executables that manage the backend for you and open the app in your default browser. The launcher drives Docker itself, so you still need Docker installed and running, but no manual Docker or Compose commands. The per-platform start guide (set the execute bit on Linux, get past Gatekeeper on macOS or SmartScreen on Windows, verify the checksum) is at Start the desktop launcher.
Download from the latest GitHub release:
| OS | Asset | How to run |
|---|---|---|
| Linux | adaptive-learner-launcher |
chmod +x adaptive-learner-launcher && ./adaptive-learner-launcher |
| macOS | adaptive-learner-launcher-macos.zip |
Unzip, then double-click (or ./adaptive-learner-launcher from Terminal) |
| Windows | adaptive-learner-launcher.exe |
Double-click |
Each release also ships a .sha256 next to each binary for
integrity verification. On first run the launcher pulls the
published app image from ghcr.io/astrapi69/adaptive-learner
(nothing is built on your machine) and starts the app on
http://localhost:8501. Enter your provider API keys under
Settings > AI; they are stored encrypted in the app's data
volume and survive updates. A secrets.yaml on the host is not
read by the launcher's container; that file applies only to a
backend run from source (see
configuration).
Prerequisite: Docker (Docker Desktop or Docker Engine with Compose).
Linux / macOS:
curl -fsSL https://raw.githubusercontent.com/astrapi69/adaptive-learner/main/install.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/astrapi69/adaptive-learner/main/install.ps1 | iexBoth scripts clone the tagged release into ~/adaptive-learner/,
generate an ADAPTIVE_LEARNER_SECRET_KEY (Fernet at-rest
encryption), build the Docker images, and start the stack at
http://localhost:8501 (single port, single container; FastAPI
serves the static frontend and /api/* itself). By default the
port is bound to 127.0.0.1, so the app is reachable only from
this machine. It has no authentication: to reach it from other
devices, deliberately set ADAPTIVE_LEARNER_BIND_ADDRESS=0.0.0.0
in ~/adaptive-learner/.env - only in a network you trust, or
behind your own auth layer (reverse proxy with basic auth, VPN).
cd ~/adaptive-learner
./stop.sh # docker compose down
./start.sh # docker compose up -d
# uninstall: ./stop.sh && cd ~ && rm -rf adaptive-learnerManual Poetry + Bun setup for contributors. Prerequisites: Python 3.11+, Node ≥24, Poetry, Bun 1.3+, Make.
git clone git@github.com:astrapi69/adaptive-learner.git
cd adaptive-learner
make install # Poetry + Bun + all 14 plugins as path-deps
make dev # backend :18001 + frontend :15174 (Vite dev server)To check the app on a real iPhone/Android without deploying, use the single-origin LAN mode. Your computer and phone must be on the same Wi-Fi:
make dev-lan # builds the frontend, then serves it + the API on one origin at 0.0.0.0:18001It prints a URL like http://<your-PC-LAN-IP>:18001 — open that in mobile
Safari/Chrome. The frontend and API share one origin (no CORS hop, no
second server), and the backend runs without --reload so app state
survives. This is a dev build served over plain HTTP, not the
installed PWA — for the PWA install flow, deploy or use the launcher.
Stop with Ctrl+C.
New contributors should start with the Developer Onboarding guide — a step-by-step walkthrough of your first bug-fix. The full setup reference lives at docs/developer/setup.
| Layer | Tech |
|---|---|
| Backend | Python 3.11+, FastAPI ^0.136, SQLAlchemy ^2.0, Pydantic v2, Alembic, aiosqlite, cryptography (Fernet), platformdirs, Poetry |
| Frontend | React 19, TypeScript 6 (strict), Vite 8, react-router-dom 7, react-toastify, Recharts 3, TipTap 2 + 15 extensions, Dexie 4 (IndexedDB), html5-qrcode, sql.js + jszip |
| PWA | vite-plugin-pwa, Workbox SW, manifest + maskable PNG icons |
| Plugins | pluginforge ^0.10.0 (PyPI), identity-gated target_application = "adaptive_learner" |
| AI providers | Anthropic SDK, OpenAI SDK, google.genai 2.x |
| Launcher | PyInstaller, cross-OS (Linux + macOS + Windows) |
| Testing | pytest ^9, Vitest 4 (happy-dom), Playwright (E2E smoke) |
| Tooling | Poetry, Bun, Docker, Make, ruff, pre-commit |
14 plugins, all under plugins/. Routes mounted at
/api/plugins/<name>/*.
| Plugin | Routes | Purpose |
|---|---|---|
| ai-anthropic | hook-only | ai_complete* for claude-* |
| ai-openai | hook-only | ai_complete* for gpt-* |
| ai-gemini | hook-only | ai_complete* for gemini-* |
| assessment | /questions, /evaluate, /profile/{id} | 12-question profile → six-method weights |
| session | /start, /{id}/message, /message/stream, /rate, /end, /switch, /pronunciation/* | 7-step cycles, dual-prompt eval, streaming, auto-loop, pronunciation judge |
| tracking | /progress/{id}, /commits/{id} | Per-project aggregates + step-evaluation insights |
| tools | /recommendations/{id}, /spaced/{id} | Method-tailored tool list + spaced practice |
| gamification | /xp/, /badges/, /streak/*, /reset | XP + 28 tiered badges + streak heatmap |
| anki | /cards CRUD, /extract/{session,conversation}, /mark-exported | AI-extracted flashcards + .apkg export |
| notebooklm | /questions CRUD, /generate/{session,project}, /study-guide/{id} | Active-recall questions + study guide + ZIP export |
| learning-repo | /render/{id}, /export-zip/{id}, /persist/{id} | Git-backed Learning Repository (Markdown artefacts + opt-in commit) |
| content-loader | /sets, /sets/{src}/{id}/download, /sets/{src}/{id}/lessons | Downloads structured lesson sets from public GitHub repos; caches locally |
| missions | /templates, /today/{user_id}, /regenerate/{user_id} | Daily adaptive missions evaluated against existing data |
make dev # backend (18001) + frontend (15174)
make test # backend + plugins + Vitest (9708 tests)
make test-coverage # opt-in coverage (CI runs it nightly)
make sync-versions # propagate version across 18 files
make sync-i18n # backend YAML → frontend JSON bundles
make docs-serve # MkDocs preview on :8000 with hot-reload
make prod / prod-down # docker compose stackE2E smoke: cd e2e && npx playwright test --project=smoke
(17 spec files).
The badge above states a size, not a strength: it counts passing tests. How much the suite actually catches is probed by mutation testing (frontend logic layers, nightly interleaved shards via Stryker); its per-shard reports are CI artifacts, not a single rate, which is why no mutation-score badge exists (#2257).
Verified 2026-09-17 (v2.15.0):
| Suite | Count |
|---|---|
| Backend (pytest) | 1858 |
| Plugins (14 × pytest) | 1137 |
| Frontend (Vitest) | 10438 |
| Total | 13433 |
Plus 17 Playwright smoke spec files covering: landing,
onboarding+assessment, session (3-chunk SSE), curriculum,
settings, mobile viewports, sync pairing, backup roundtrip,
multi-cycle auto-loop, import + analysis, MD export,
subjects/tags filter, rich-text notes, model picker — and a
separate Dexie-mode release gate (make test-dexie-smoke)
walking every nav-reachable route against the GH-Pages build.
CLAUDE.md— development guide for Claude Code (under 10K, single-line state pointer).docs/configuration.md— the three-layer config chain.docs/ROADMAP.md— phase history + next.docs/backlog.md— daily-planning view (P0–P5 tiers + blocked items).docs/adaptive-learner-project-reference.md— original plan + shipped architecture.
User-facing prose lives on the docs site; the in-repo files above are for contributors.
Active development. The current release is v2.16.0: errors that used to
vanish now say what went wrong. A failed tutor reply shows a message with
a retry, a history that could not load says so, a crashed page offers a way
back and a report button, and Settings actions, exports and lesson progress
no longer fail silently. The exercise editor, the share check and repository
validation follow one set of rules, the content engine's, and the desktop
app resolves matchings built from cards. Backups carry every stored field
and restore across the desktop app and the browser version, and a round of
phone fixes covers the compact menu below 1280 px and the dashboard. Full
notes: changelog/releases/v2.16.0.md.
Earlier releases, newest first (full details in
changelog/releases/):
- v2.14.0 - optional Game Mode (combo streaks, checkpoints, answer physics, hearts/countdown) with XP-unlocked arcade minigames, mascot colour variants and avatar presets/frames, set pages with lesson progress and a set-completion review, three audio/speech extension types adoptable from the creation wizard.
- v2.13.0 - in-place exercise-type conversion in the lesson editor, a discoverable "Edit as a copy" action on downloaded content sets, a large UI-consolidation pass (shared Settings/Modal/DashboardCard components, shadcn Button), FastAPI 0.141 + TipTap 3.30 dependency refresh.
- v2.12.0 - restart a finished set as a fresh run (a "Durchgang") with the spaced-repetition history carried along, key import from a Topos
.alkexport, Perplexity as a backend AI provider. - v2.11.0 - learning progress anchored to stable identities (one-time local migration), so content corrections no longer orphan review cards; a reworked matching-exercise layout.
- v2.10.0 - security release: the app binds to
127.0.0.1and is reachable only from your own computer instead of on every network interface. - v2.9.0 - the downloaded launcher can be closed again on desktops without a system tray.
- v2.8.2 - security patch on v2.8.0: no more white page in image mode, and the bare container no longer defaults to debug mode.
- v2.8.0 - distribution switch: the desktop launcher pulls a published, per-architecture verified image from GHCR instead of building on-device, guarded by a volume-migration stop; image-description exercises (
ext:al-image-description), single-lesson deletion, a set-update guard against silently orphaning learning progress. - v2.6.x - session chat rebuilt on assistant-ui, Create-Lesson's book path became a real ingestion tool (book-file upload, chapter multi-select, batch generation), dictation authoring completed with audio-file upload.
- v2.5.0 - Create-Lesson became a full exercise authoring tool (every core type editable, hand-added exercises, an extension-authoring wizard for all AI-authored extension types plus
ext:al-dictation); PWA updates and the AI key vault became consumed npm packages (@astrapi69/pwa-update,@astrapi69/ai-key-vault). - v2.4.0 - Create-Lesson authoring upgrade (knowledge lesson from pasted text, editing/combining lessons, card image upload), free-text multiple accepted answers with an AI second opinion, engine re-pinned to 0.13.0 (schema 1.8) for picture-choice image uploads.
- v2.3.0 - EXP-044 CSS concern-split (byte-identity gated), reworked lesson-player UX, listen-first audio exercises, hardened lesson/set import/export.
- v2.2.0 - an extension-exercise tier (four AI-authored types), native
multiple_choice, lesson schema/types consumed fromlearn-content-engine, a federated content-repository registry.
Also shipped: the Content hub redesign (Discover / My content /
Import tabs, list/grid toggle, a compact search/filter bar), the full
lesson-mode system (Practice / Exam / Timed / Reverse / Shuffle /
Endless + train-errors), cloze multiselect, an exam-mode SRS
interval boost, passphrase-encrypted .alk key export, and a
single-primary-navigation cleanup (one nav per viewport).
Adaptive Learner is built and maintained by a single developer. If it
helps you, donations are welcome and go directly into development
time - see DONATE.md (DONATE-de.md
for German) for all channels (GitHub Sponsors, Liberapay, Ko-fi,
PayPal) and the reasoning behind them.
The plugin-loader infrastructure, layered architecture, test discipline, and Python + React stack were extracted from Bibliogon v0.33.0 in March 2026. The Bibliogon book-domain models and plugins were removed; adaptive-learner has diverged on domain (learning sessions, curricula, assessment, AI integration) entirely. The launcher shape carries over; the application is a separate codebase.
MIT — see LICENSE.