LearningMAP

KO | EN

gitlite — search

#ai-agent #database #agent #list #chatgpt #c #kotlin #artificial-intelligence #github #python

(★ 9)

A production-ready personalized learning tutor.

File Explorer

ZIP Download

- cs_demo.gif
- cs_demo.mov
- logo.png
- math_demo.gif
- math_demo.mov
- phy_demo.gif
- phy_demo.mov
- __init__.py
- build_kc_skills.py
- classba_client.py
- serve.py
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - __init__.py
  - graph.py
  - mastery_annotator.py
  - state.py
- - __init__.py
  - chat.py
  - store.py
  - tasks.py
- - __init__.py
  - pptx_export.py
- - __init__.py
  - base.py
  - ebbinghaus.py
  - registry.py
- - __init__.py
  - client.py
  - schemas.py
  - slide_schemas.py
- - __init__.py
  - grading.j2
  - intent.j2
  - kc_resolver.j2
  - kc_skill_block.j2
  - kc_skill_from_bank.j2
  - knowledge_graph.j2
  - knowledge_skill.j2
  - lesson_plan.j2
  - lesson_point.j2
  - lesson_review.j2
  - loader.py
  - memory_consolidate_system.j2
  - memory_consolidate_user.j2
  - memory_extract_system.j2
  - memory_extract_user.j2
  - quiz_generate.j2
  - review_generate_system.j2
  - slide_content_draft.j2
  - slide_content_system.j2
  - slide_content_user.j2
  - slide_outline.j2
- - __init__.py
  - kc_graph.py
  - kc_loader.py
  - loader.py
- - __init__.py
  - json_repair.py
  - text.py
- __init__.py
- memory_client.py
- progress_aggregator.py
- reviewer.py
- api.js
- diagnosis.html
- index.html
- lesson.html
- results.html
- sidebar.js
- slides.html
- - __init__.py
  - main.py
- - __init__.py
  - rebuild_index.py
- - __init__.py
  - conftest.py
  - test_api.py
  - test_api_notes.py
  - test_api_progress.py
  - test_api_snapshot.py
  - test_e2e_pr1.py
  - test_embedder.py
  - test_errors.py
  - test_formatter.py
  - test_health.py
  - test_hnsw_index.py
  - test_ingest.py
  - test_integration.py
  - test_new_schemas.py
  - test_notes.py
  - test_notes_index.py
  - test_parser_normalizer.py
  - test_progress.py
  - test_reranker.py
  - test_retriever.py
  - test_snapshot.py
  - test_sqlite_repo.py
- .python-version
- pyproject.toml
- README.md
- uv.lock
- - __init__.py
  - smoke_e2e.py
  - smoke_pr2.py
- test_api.py
- test_api_modes.py
- test_baseline_prompts.py
- test_branched_tracks.py
- test_chat_api_review.py
- test_chat_integration.py
- test_classba_client.py
- test_cross_session_memory.py
- test_e2e.py
- test_forgetting.py
- test_graph.py
- test_json_repair.py
- test_kc_graph.py
- test_kc_loader.py
- test_kc_skill_resolver.py
- test_kc_skills_build.py
- test_kg_mastery_e2e.py
- test_knowledge_graph_node_mastery.py
- test_lesson_background_task.py
- test_lesson_parallel.py
- test_lesson_pipeline.py
- test_llm_client.py
- test_mastery_annotator.py
- test_memory_client.py
- test_memory_client_v2.py
- test_product_memory.py
- test_progress_aggregator.py
- test_prompts.py
- test_quiz_background_task.py
- test_quiz_node_weighting.py
- test_quiz_parallel.py
- test_review_node.py
- test_reviewer.py
- test_schemas.py
- test_session_mode.py
- test_skill_integration.py
- test_skills.py
- test_skills_default.py
- test_slide_schemas.py
- test_snapshot_injection.py
- test_store_additional_kwargs.py
.gitignore
.python-version
ARCHITECTURE.md
development_log.md
LICENSE
pyproject.toml
README.md
README_CN.md
uv.lock

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

One topic in → a full adaptive course out. 
Knowledge graph → quiz → diagnosis → lesson → slide deck → review, generated on the fly and remembered across sessions.

---

## Table of Contents

- [Overview](#overview)
- [Demos](#demos)
- [Quickstart](#quickstart)
- [Key Features](#key-features)
- [Capabilities Summary](#capabilities-summary)
- [Installation](#installation)
- [Configuration](#configuration)
- [Status](#status)

> **Technical reference** — architecture, API, frontend pages, repository layout, hardware sizing, and development conventions live in [ARCHITECTURE.md](ARCHITECTURE.md).

---

## Overview

- **One topic in, a full study plan out.** A student enters a topic; LearningMAP builds an adaptive learning loop around it, end to end.
- **Complete, working demo.** Full cycle — chat, quiz, learn, review — with everything streamed live to the browser.
- 🚀 **Personalized to each learner.** Adapts to actual mastery and remembers across sessions via a human-like memory system.
- 🚀 **Focused on what's tested.** Expert-backed, knowledge-level skills keep every lesson on the exam-critical points. **We're open-sourcing `865` distilled K-12 math skills today — with more skills and more subjects on the way.**

LearningMAP takes a topic the learner types in and runs it through one adaptive loop — knowledge graph, quiz, diagnosis, targeted lesson, and slide deck — then remembers what happened for the next session.

---

## Demos

Two end-to-end walkthroughs of the learning loop on different subjects:

> Recordings are sped up (~6×). Click a clip to open the full `.mov` for real-time playback.

### Computer Science

[![Computer Science demo](https://raw.githubusercontent.com/ai-for-edu/LearningMAP/main/resources/cs_demo.gif)](resources/cs_demo.mov)

### Physics

[![Physics demo](https://raw.githubusercontent.com/ai-for-edu/LearningMAP/main/resources/phy_demo.gif)](resources/phy_demo.mov)

---

## Quickstart

Get the main service running in three steps. The human-like memory module is **optional and configured separately** — see [Installation](#installation) for the full setup.

> For the best experience, we recommend using **DeepSeek-V4 or a model of equivalent or higher capability**. Any OpenAI-compatible model works, but weaker models may degrade lesson quality and KC-skill resolution.

```bash
# 1. Install the main service
uv sync

# 2. Configure — point at any OpenAI-compatible LLM gateway
cat > .env <<'EOF'
OPENAI_API_KEY=sk-xxxxxxxx
OPENAI_BASE_URL=https://api.deepseek.com/v1
LLM_MODEL=deepseek-chat
EOF

# 3. Run, then open http://localhost:8080
uv run python run/serve.py
```

---

## Key Features

### 📚 Learning Content Pipeline

A linear loop converts a topic into multi-format study materials:

- **Knowledge Graph** — entity/skill graph with mastery annotations (`mastery_annotator.py`).
- **Adaptive Quiz** — questions calibrated to the current KG mastery state.
- **Grading & Diagnosis** — per-question grading feeds a diagnosis card and a learning radar chart.
- **Markdown Lesson** — targeted to the weak points exposed by diagnosis; streamed via SSE.
- **Slide Deck** — outline-first pipeline, exported to `.pptx` via `python-pptx`. The post-processing chain enforces a 1000 × 562.5 canvas, repairs LaTeX/CJK elements, and assigns stable IDs (see [ARCHITECTURE.md](ARCHITECTURE.md#slide-post-processing-chain)).

### 🧠 Persistent Memory

An independent FastAPI microservice (`student_memory/`) provides:

- `POST /retrieve` — semantic recall injected into the chat node's system prompt.
- `POST /ingest` — sub-topic-level MemoryUnits written at end of diagnosis / lesson.
- `POST /notes` and `GET /notes/{uid}/neighbors` — 4-category L2 reflection notes for wrong-answer review.

The seam is a single file, `src/memory_client.py`. **When the service is unavailable, the main service degrades gracefully** — no context injection, no ingest writes, no blocking.

### 🎓 Pluggable Pedagogy Skills

Teaching style is a swappable artifact, not code:

- Each pedagogy is a directory containing one `SKILL.md` (e.g. `skills/feynman/`, `skills/scaffolding/`, `skills/socratic/`).
- Adding a new pedagogy is **one new directory + one `SKILL.md` — zero Python changes**.
- A separate **KC-skill bank** (built offline via `run/build_kc_skills.py`) is resolved per topic by `kc_skill_resolver.py`, allowing skill injections to be scoped to specific knowledge components.
- Skills are toggled at runtime via `POST /api/chat/{sid}/set-skill`.

### 🔁 Review Loop (L2 Reflection)

After the main learning loop, the review node:

- Generates 4-category wrong-answer summaries.
- Persists them to `student_memory` via `/notes`.
- Subsequent sessions surface these notes through `/retrieve`, closing the cross-session feedback loop.

The minimum gap between review runs is bounded by `REVIEW_MIN_AGE_SECONDS` (default 24 h).

---

## Capabilities Summary

Three selling points — and what each is built on.

### 1 · Personalized learning experience

Adapts to each student's actual mastery, powered by a human-like memory system that remembers across sessions — prior sessions resurface as system-prompt augmentations, and teaching style is switchable at runtime.

> **Built on:** knowledge graph + cross-session memory (`student_memory/`, decoupled behind a single seam and degraded gracefully when offline) + pluggable pedagogy (`skills/<name>/SKILL.md`).

### 2 · Expert-backed, knowledge-level skills

Distilled from real exam questions and expert teaching, scoped to specific knowledge components — so materials hit what's tested, never generic.

> **Built on:** the KC-skill bank (built offline via `run/build_kc_skills.py`, resolved per topic by `kc_skill_resolver.py`).

### 3 · Full-cycle, production-ready

A working end-to-end demo covering the complete journey: chat → quiz → grading → diagnosis → lesson → review, all derivable from session state on refresh and streamed live to the browser.

> **Built on:** FastAPI + SSE streaming everywhere (chat / lesson / slides), with Markdown lessons re-rendered as 16:9 slide decks (1000 × 562.5 canvas, LaTeX/CJK-aware) and `.pptx` export.

---

## Installation

### Prerequisites

| Dependency | Version | Notes |
|---|---|---|
| Python | 3.11 | Locked by `.python-version` |
| [uv](https://docs.astral.sh/uv/) | 0.4+ | Only supported package manager |
| SQLite | 3.35+ | Bundled with Python |
| OpenAI-compatible LLM | — | DeepSeek / Moonshot / any OpenAI-compatible gateway |

### Local

```bash
uv sync                                # main service
cd student_memory && uv sync && cd ..  # memory subservice (optional)
```

### Running

**Main service (port 8080)**

```bash
uv run python run/serve.py
# Uvicorn → http://0.0.0.0:8080
```

**Memory subservice (port 8090, optional)**

```bash
cd student_memory
SM_USE_FAKE_EMBEDDER=1 uv run uvicorn app.main:app --host 127.0.0.1 --port 8090
```

> When the memory service is unavailable, the main service **gracefully degrades** (no `context_text` injection, no `ingest` writes) without blocking the conversation.

Open `http://localhost:8080/` once the main service is running — FastAPI serves `static/` from the root.

---

## Configuration

All variables read by the main service (set in `.env` or process environment):

| Variable | Default | Purpose |
|---|---|---|
| `OPENAI_API_KEY` | — | **Required**. LLM authentication. |
| `OPENAI_BASE_URL` | — | **Required**. OpenAI-compatible endpoint. |
| `LLM_MODEL` | — | **Required**. Model name. |
| `MEMORY_SERVICE_URL` | `http://127.0.0.1:8090` | `student_memory` service address. |
| `ALLOWED_ORIGINS` | `*` | Comma-separated CORS whitelist. |
| `REVIEW_MIN_AGE_SECONDS` | `86400` | Minimum interval between review-node invocations (seconds). |
| `CLASSBA_AUTH` / `CLASSBA_API_URL` / `CLASSBA_AGENT_NAME` | — | Optional. For ClassBA external Agent calls. |

The LLM client is hardcoded to **bypass the OS HTTP proxy** (see commit `fc7e51c`); no additional proxy configuration is needed.

Example `.env`:

```bash
OPENAI_API_KEY=sk-xxxxxxxx
OPENAI_BASE_URL=https://api.deepseek.com/v1
LLM_MODEL=deepseek-chat

# Optional — defaults are used if omitted
MEMORY_SERVICE_URL=http://127.0.0.1:8090
ALLOWED_ORIGINS=*
REVIEW_MIN_AGE_SECONDS=86400
```

---

For repository layout, hardware sizing, and development conventions, see **[ARCHITECTURE.md](ARCHITECTURE.md)**.

LearningMAP

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

LearningMAP

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README