A complete adaptive-learning platform built on the six-method
learning model (Asterios Raptis, Von Theorie zur Praxis, 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), or configure
keys in ~/.config/adaptive_learner/secrets.yaml for the
desktop launcher.
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)
- Six learning methods with bespoke per-(method, step) AI prompts — a 42-cell prompt matrix tailored to where the learner is in the cycle and how the chosen method asks them to engage.
- Seven-step cycle on every session — input, focus, attempt, feedback, refine, transfer, integrate. The dual-prompt evaluator judges each turn and decides advance, repeat, skip-ahead, or step back.
- Auto-loop beyond step 7 — when the topic is integrated, a third AI call picks a new subtopic and starts a fresh cycle (capped at 5 cycles per session for runaway protection).
- Method switching — stagnation detection recommends a different method when ratings flatline; one-click accept in the Session header.
- Streaming AI replies — token-by-token rendering via SSE; inline cursor while the assistant thinks; no "Thinking..." placeholder.
- Anthropic Claude, OpenAI GPT, Google Gemini —
shipped as separate plugins, all routed through the
ai_complete/ai_complete_async/ai_complete_streamhooks. - Provider model picker — live model discovery via each
provider's
/v1/modelsendpoint (cached 1h), with chat-only filtering and a Recommended / All grouping in Settings. - Bring-your-own key — three resolution layers:
- Environment variables (CI / Docker).
~/.config/adaptive_learner/secrets.yaml(desktop launcher; auto-generated template withchmod 0600on POSIX).- Settings UI (Fernet-encrypted in SQLite).
- The UI shows the per-provider source ("Key from: secrets.yaml" / "environment" / "Settings") and disables the input when externally managed.
- Server mode (
ApiStorage) — FastAPI backend, SQLite, per-user Fernet-encrypted API keys, sync between devices. - Local-first mode (
DexieStorage) — everything in browser IndexedDB, AI calls fire direct to the providers. No backend needed; the public GH Pages deploy uses this mode. - One
IStorageServiceinterface, 22 namespaces; switch at startup via Settings.
- Local-network sync between devices — bidirectional WiFi sync with AI-merge conflict resolution. QR-code camera scan for pairing (with image-upload fallback for restricted browsers).
- Backup / restore — JSON export + import, automatic rotation, side-by-side compare UI with field-level diffs. API keys stripped from exports.
- Chat-history import from ChatGPT (JSON), Claude (JSON bulk export), Claude (single-conversation Markdown export), Gemini, and arbitrary markdown.
- AI-driven analysis extracts topic, weaknesses, error patterns, recommended method, vocabulary (for language conversations), and a suggested curriculum.
- One click to seed a curriculum + start a targeted session from the analysis.
- Anki .apkg export — AI-extracted flashcards (Basic +
Cloze), reviewed in the
/ankipage, packaged client-side via sql.js + JSZip. - NotebookLM ZIP — summary + vocabulary + rules + errors
- flashcards + sessions packaged for NotebookLM's source upload.
- Markdown + PDF progress reports — Progress, Session Detail, Curriculum Overview, identical wire shape across storage modes.
- XP + levels with an exponential curve, streak multipliers on session completion, first-method bonuses.
- 24 badges across 5 categories (getting started, consistency, method explorer, depth, polyglot), seeded from YAML on first start.
- Streak heatmap (GitHub-style, last 365 days) with weekend-mode toggle + freeze stockpile (1 freeze per 7 streak days, max 3).
- Text-to-speech on AI replies + Assessment results.
- Speech-to-text on the Session input (interim transcripts populate the textarea before send).
- Pronunciation practice for language projects (target phrase → speak → AI judges similarity).
- Installable on Chrome / Edge / Safari — "Add to home screen" prompt, standalone display, no browser tab.
- Offline for past sessions + Dashboard + Progress via the
service worker (24h LRU on GET
/api/); new sessions need network for the AI call. - Swipe gestures — Assessment left/right navigation, Curriculum topic swipe-to-reveal, session cycle peek; reduced-motion respected.
- Mobile-tested at iPhone SE / iPhone 14 / Pixel 7 / iPad viewports.
- TipTap rich text in session notes + curriculum descriptions + lessons (bold/italic, headings, lists, blockquotes, code blocks with lowlight syntax highlight, links, character count).
- 8 languages fully translated: DE, EN, ES, FR, EL, PT,
TR, JA — single-source YAML catalogs in
backend/config/i18n/mirrored to the frontend Dexie bundle viamake sync-i18n.
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 bootstrap the backend and open the app in your default browser. No Docker, no terminal needed.
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. The launcher downloads the matching
tagged source tree on first run, builds the Docker images,
and starts the app on http://localhost:7880. On first start
it also creates ~/.config/adaptive-learner/secrets.yaml as a
commented template — uncomment and fill in your provider API
keys to skip the Settings UI dance.
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:7880 (single port; nginx serves the static
frontend and proxies /api/* to FastAPI).
cd ~/adaptive-learner
./stop.sh # docker compose down
./start.sh # docker compose up -d
# uninstall: ./stop.sh && cd ~ && rm -rf adaptive-learnerManual Poetry + npm setup for contributors. Prerequisites: Python 3.11+, Node ≥24, Poetry, npm, Make.
git clone git@github.com:astrapi69/adaptive-learner.git
cd adaptive-learner
make install # Poetry + npm + all 10 plugins as path-deps
make dev # backend :18001 + frontend :15174 (Vite dev server)Full setup walkthrough 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, npm, Docker, Make, ruff, pre-commit |
10 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 + 24 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 |
make dev # backend (18001) + frontend (15174)
make test # backend + plugins + Vitest (2634 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
(16 spec files at v1.20.0).
| Suite | Count |
|---|---|
| Backend (pytest) | 786 |
| Plugins (10 × pytest) | 615 |
| Frontend (Vitest 4) | 1233 |
| Total | 2634 |
Plus 16 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.
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. v1.20.0 was released 2026-05-22 with
secrets.yaml file-based key configuration. 34 development
phases shipped; per-release notes in
changelog/releases/.
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.