Skip to main content
Glama
README.md
---
title: πŸŽ“ LEAP Framework
tags:
- leap
- engineering
aliases:
- πŸŽ“ LEAP Framework guide
canonical_role: full_knowledge_source
delivery_policy: '3.0'
---

> [!info] Learning resources / 学习衄源
> Core: `LEAP πŸŽ“ LEAP Framework foundations definitions workflow`
> Extension: `LEAP πŸŽ“ LEAP Framework failure cases examples comparison`
> Advanced: `LEAP πŸŽ“ LEAP Framework invariants verification transfer`
> These are search queries; no video has been certified for this note.

Related: [Knowledge_Index](Knowledge_Index.md) Β· [docs/teaching-delivery](docs/teaching-delivery.md)

# πŸŽ“ LEAP Framework

Use LEAP for interactive lessons and A4 self-study. In the [linear-equations lesson](examples/02-math-linear-equation/leap-02-math-linear-equation.html),
explore the balance and then work through the matching [illustrated handout](print-examples/linear-equations/handout.html),
[workbook](print-examples/linear-equations/workbook.html), and [answer key](print-examples/linear-equations/answers.html).
The [printing guide](docs/printing.md) covers offline printing and reviewed MCP PDF exports.

<p align="center">
  <img src="https://img.shields.io/github/stars/Vinger-lee/leap-framework?style=social" alt="Stars">
  <img src="https://github.com/Vinger-lee/leap-framework/actions/workflows/ci.yml/badge.svg" alt="CI">
  <img src="https://img.shields.io/github/v/release/Vinger-lee/leap-framework" alt="Release">
  <img src="https://img.shields.io/badge/license-MIT-blue" alt="License">
  <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
  <img src="https://img.shields.io/badge/MCP-75%20tools-22bb33" alt="MCP Tools">
  [![Tests](https://github.com/Vinger-lee/leap-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/Vinger-lee/leap-framework/actions/workflows/ci.yml)
  <img src="https://img.shields.io/badge/δΈ­ζ–‡-ζ”―ζŒ-ff6600" alt="δΈ­ζ–‡ζ”―ζŒ">
  <br>
  <b>πŸ€– Give your AI agent a real tutoring engine β€” not just a prompt.</b>
</p>

<p align="center">
  <a href="README.md">English</a> Β·
  <a href="README_CN.md">δΈ­ζ–‡</a> Β·
  <a href="docs/i18n/README.ja.md">ζ—₯本θͺž</a> Β·
  <a href="docs/i18n/README.ko.md">ν•œκ΅­μ–΄</a> Β·
  <a href="docs/i18n/README.fr.md">FranΓ§ais</a> Β·
  <a href="docs/i18n/README.es.md">EspaΓ±ol</a> Β·
  <a href="docs/i18n/README.ru.md">Русский</a> Β·
  <a href="docs/i18n/README.ar.md">Ψ§Ω„ΨΉΨ±Ψ¨ΩŠΨ©</a>
</p>

---

## πŸš€ What is LEAP?

**LEAP (Learning Evolution & Adaptation Pipeline) is a state-driven tutoring runtime for AI
agents.** It gives an agent a persistent, auditable learning loop instead of a one-shot
"explain then quiz" prompt.

Your agent keeps doing what it is good at β€” understanding the learner, generating explanations,
writing questions, judging open answers. LEAP owns everything that must be consistent:

- **learner state** and mastery estimation
- **prerequisites** and whether a topic may be entered
- **assessment sufficiency** and evidence quality
- **review scheduling** and long-term retention
- **state transitions** β€” nothing advances without passing the server-side State Guard

```bash
# Your agent asks LEAP what to do next
get_teaching_context(session_id, "py.recursion.base_case")
# πŸ‘‰ strategy: Retrieval Practice Β· action: Generate Practice
#    evidence_stage: practiced Β· mastery: 0.62 Β· hint_dependency: 0.25
#    due_reviews: 2 Β· active_misconceptions: 1
```

## ⚑ Quick Start

```bash
git clone https://github.com/Vinger-lee/leap-framework.git
cd leap-framework
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

Run the test suite:

```bash
pytest -q        # run the full suite
```

Start the MCP server:

```bash
python -m leap.server      # or: leap-mcp
```

### πŸ“¦ Install as a package

```bash
pip install "leap-framework"          # add [examples] only if you verify teaching pages
leap-doctor                           # installation self-check
leap-mcp --tool-profile quickstart    # stdio MCP server (default profile: full)
```

A package install ships the same defaults inside the wheel (`leap/config/default.yaml`), so
`leap-doctor` and the server work without a checkout. Configuration is layered, lowest first:

- the YAML file β€” the repository `config/default.yaml`, otherwise the packaged copy;
- environment overrides such as `LEAP__DATABASE_PATH`, `LEAP__ARTIFACT_ROOT` and
  `LEAP__TOOL_PROFILE` (nested keys use a double underscore);
- tool profile β€” `--tool-profile`, `LEAP_TOOL_PROFILE`, or `tool_profile` in the configuration.

`database_path` and `artifact_root` are resolved against `LEAP_HOME` when it is set, otherwise
against the current working directory β€” never against the installed package, so `data/leap.db` and
`artifacts/` cannot land inside `site-packages`. Set `LEAP_HOME` to a writable directory for a
stable deployment:

```bash
LEAP_HOME=/var/lib/leap leap-mcp --tool-profile quickstart
```

**Tool profiles**: `full` exposes the complete tool catalogue (default); `quickstart` exposes the
coarse teaching path for small hosts. `leap-doctor` prints the counts for the installed version.

**Agent Skill (optional)**: hosts that load repository skills can open
`.agents/skills/leap-tutor/` (see [host configuration](docs/host-config.md)); hosts without skill
support follow the integration guide. The runtime enforces the same gates either way β€” the skill
changes how the agent is guided, not what the server allows.

For teaching-page verification dependencies, commands and acceptance criteria, see
[the contributing guide](CONTRIBUTING.md).

## 🧠 The learning loop

```
1. Goal Specification
2. Domain Grounding          ← the agent reads reviewed sources and solves checks
3. Learner Diagnostic
4. Knowledge Representation  ← DAG of knowledge nodes
5. Learner State Initialisation
6. Dynamic Teaching Loop     ← Read State β†’ Policy β†’ Action β†’ Attempt β†’ Assessment β†’ Update
7. Retention                 ← FSRS spaced review
8. Transfer                  ← near β†’ variation β†’ far β†’ integrated
9. Reflection & Persistence
```

### πŸ”’ State Guard

The State Guard is the only component that may authorise a transition. When a tool returns
`REJECT`, the agent adapts to the reason instead of pushing harder through prompt text.
A failed tool call never becomes a silent state update.

### πŸ“Š Mastery is estimated server-side

`mastery_probability` is a **model estimate, not ground truth**. It is computed by a built-in
forgetting-aware BKT model, never emitted by the host agent's LLM β€” that keeps it numerically
stable and auditable. Each update runs four steps: time decay β†’ evidence update β†’ state
transition β†’ spontaneous forgetting.

Partial credit and low-confidence discounting are supported. Uncertainty is never written in as
`mastery = 0`.

### πŸͺœ Evidence stages (and they can regress)

`estimated β†’ practiced β†’ demonstrated β†’ retained β†’ transferred`

One correct answer produces one piece of evidence β€” not mastery. Stages **regress** when a
learner has been away too long or fails in a new scenario. The criteria live in the Policy layer
and are fully configurable.

### ⏰ Retention and transfer

Due reviews do **not** block everything. Whether to insert, prioritise or block is decided per
node. Retention (FSRS, rating 1–4) and transfer (near / variation / far / integrated) are two
complementary long-term evidence dimensions.

## πŸ”§ MCP tools

Names, parameters, host descriptions and profile membership are maintained in the
[generated MCP tool reference](docs/mcp-tools.md).

The coarse API composes teaching steps server-side and returns `next_call` in each response.
The State Guard decides transitions; refused advances write no state, failed assessments preserve
the stored attempt, and mastery is estimated server-side. New integrations can explicitly select
`--tool-profile quickstart`; the default remains `full`. See [the coarse API and profiles](docs/FACADE.md)
and [the framework's boundaries](docs/scope-and-limits.md).

Hosts supporting repository skills can load
[leap-tutor](.agents/skills/leap-tutor/SKILL.md) for the learning workflow and
conditional recovery guidance. See [setup and acceptance](docs/agent-skill.md) and
[host configuration](docs/host-config.md) for copy-paste `mcpServers` samples and the per-host
discovery matrix (Claude Code, for example, scans `.claude/skills`, not `.agents/skills`).
The skill is a draft. Verify host discovery, activation and the MCP connection separately.
Quickstart records misconceptions, recovers split assessments and closes sessions explicitly.
A closed session stops suggesting teaching calls. Responses carry a compact `policy_version`
instead of the full policy, and `continue_lesson` returns a summary unless `verbose=True`.
Use full for the existing HTML outbox bridge.

Both profiles use the reviewed source library. The first unit covers limits, derivatives and differentiability. Start with `start_learning(..., topic="ι«˜η­‰ζ•°ε­¦")`, then call `get_grounding_sources(session_id)`. Read the source locators and solve the checks independently. Submit `save_benchmark_report` with the actual reading report, `course_revision`, every `chunk_id` and a `check_answers` map from check IDs to answer strings. The runtime rejects legacy host attestations and skip requests. If sources are absent, expired or withdrawn, pause formal teaching.

After calibration, call `get_grounding_sources(session_id, include_lesson=True)`. Register `.lesson.node` with `save_knowledge_nodes`, the returned `subject`, `markdown`, `html` and `manifest` with `save_teaching_package`, then each reviewed item with `save_assessment_item`. Supply the session ID, node ID, a unique item ID and the accepted package ID. Free-text reasoning needs host semantic review. For A4, save `.lesson.print_draft` with `save_print_materials` and the session, node and package IDs.

The same SQLite database keeps calibration receipts and readable learning history across restarts. The first pack has a 180-day review period. Maintainers can run `python scripts/review_grounding_sources.py` to check approved source links and locators on demand, then restart MCP after manually approving and publishing an update. The full profile can save new material as `save_artifact(artifact_type="teaching_draft", ...)` for review. See the [host integration guide](docs/INTEGRATION.md).

See the [content-quality and integration workflow](docs/content-quality.md) and [audit of the reported delivery](docs/quality-audit-2026-10-10.md). Browser scenario checks and real MCP integration checks are separate from content review.

The delivery policy covers depth, controllable diagrams, wide layout, full Obsidian source and precise resources. The 11-domain catalog and example lessons are available for reference and offline preview. See the [delivery policy](docs/teaching-delivery.md) and [subject knowledge map](docs/subject-knowledge-map.md).

## 🧩 Pluggable by design

Six components are resolved through a plugin registry, so an implementation can be swapped from
`config/default.yaml` without touching call sites:

| Seam | Default | Alternatives |
|---|---|---|
| State estimation | `simplified_bkt` | PFA, DKT, Bayesian, hybrid |
| Score aggregation | `weighted` | rubric, model-based |
| Pedagogical policy | `rule_based` | LLM, hybrid, learned |
| Review scheduler | `py-fsrs` | any scheduler |
| Storage | `sqlite` | PostgreSQL, distributed |
| Artifact store | `local` | object storage, knowledge base |

## 🌍 Internationalisation

Learner-facing text comes from a message catalogue (`zh-CN` / `en`). Tool names, field names and
enum values are deliberately **not** translated β€” translating them would break host-agent
integrations. Set `locale` in `config/default.yaml`, or override with `LEAP_LOCALE`.

## πŸ“¦ Configuration

Every parameter lives in `config/default.yaml` and is an engineering heuristic the Policy engine
may override:

| Parameter | Default | Meaning |
|---|---|---|
| `mastery_threshold` | `0.80` | Mastery threshold |
| `max_hint_level` | `3` | Hint ceiling |
| `max_retry_before_example` | `3` | Failures before a worked example |
| `hint_dependency_high` | `0.7` | High hint-dependency cutoff |
| `overall_score_weights` | `0.4/0.3/0.2/0.1` | correctness / conceptual / reasoning / application |
| `review_scheduler` | `py-fsrs` | Spaced-repetition backend |
| `interleaving_enabled` | `conditional` | Interleaved practice |
| `locale` | `zh-CN` | Language of learner-facing text |

## πŸ“š Examples

Eight single-page teaching demos, each verified statically and in headless Chromium:

| Example | Subject |
|---|---|
| `examples/01-python-recursion/` | Programming β€” Python recursion |
| `examples/02-math-linear-equation/` | Mathematics β€” linear equations |
| `examples/03-cs-osi-model/` | Computer science β€” OSI model |
| `examples/04-physics-free-fall/` | Physics β€” free fall |
| `examples/05-logic-flowchart/` | Logic β€” flowcharts |
| `examples/06-statistics-probability/` | Statistics β€” conditional probability |
| `examples/07-chemistry-stoichiometry/` | Chemistry β€” stoichiometry |
| `examples/08-electronics-ohms-law/` | Electronics β€” Ohm law |

Every page is a **reference implementation**: zero CDN, zero network requests, and it demonstrates
the real page ↔ runtime bridge β€” `LEAP.hydrate(context)` for state in, `LEAP.drainOutbox()` for
MCP calls out.

## πŸ—‚ Repository layout

```
leap-framework/
β”œβ”€β”€ config/default.yaml      # every engineering parameter
β”œβ”€β”€ src/leap/
β”‚   β”œβ”€β”€ i18n.py              # message catalogue
β”‚   β”œβ”€β”€ server.py            # MCP server (stdio)
β”‚   β”œβ”€β”€ runtime/             # decision core
β”‚   β”‚   β”œβ”€β”€ contracts.py     #   the plugin seams
β”‚   β”‚   β”œβ”€β”€ plugins.py       #   implementation registry
β”‚   β”‚   β”œβ”€β”€ bkt.py           #   mastery estimation
β”‚   β”‚   β”œβ”€β”€ policy.py        #   pedagogical policy
β”‚   β”‚   β”œβ”€β”€ scheduler.py     #   FSRS review scheduling
β”‚   β”‚   β”œβ”€β”€ state_guard.py   #   transition authority
β”‚   β”‚   └── ...
β”‚   β”œβ”€β”€ storage/             # SQLite schema + migrations
β”‚   β”œβ”€β”€ tools/               # tool implementations
β”‚   └── specs/               # Obsidian / web component specs
β”œβ”€β”€ examples/                # eight teaching pages + shared specs
β”œβ”€β”€ docs/                    # architecture, integration, i18n
β”œβ”€β”€ scripts/                 # verifiers, scanner, auditors
└── tests/                   # inspect the current test result
```

## πŸ” Quality gates

The verification sequence, browser setup and acceptance criteria live in [the contributing guide](CONTRIBUTING.md).
`.github/workflows/ci.yml` defines the automated checks, including a byte-for-byte check of the generated tool reference.

AI assistant workspaces (`.workbuddy*/`, `.claude*/`, `.cursor*/`, `agent-state/`, …) and local
scratch directories are excluded from publication by `.gitignore`, scanner rule `AI001`, and a CI
test that asserts the index and full history contain zero such files.

## πŸ“– Documentation

| Document | Contents |
|---|---|
| [README_CN.md](README_CN.md) | δΈ­ζ–‡θ―΄ζ˜Ž |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Architecture and design decisions |
| [docs/INTEGRATION.md](docs/INTEGRATION.md) | Host-agent integration guide |
| [docs/EXAMPLES.md](docs/EXAMPLES.md) | The eight teaching pages and their contract |
| [`docs/i18n/`](docs/i18n/) | Translations |
| [CHANGELOG.md](CHANGELOG.md) | Release history |
| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |
| [SECURITY.md](SECURITY.md) | Reporting a vulnerability |

> The authoritative framework design specification and visual design system are maintained by the
> project author separately and are **not** part of this repository. The implementation here
> follows those documents.

## 🀝 Contributing

Issues and pull requests are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

## πŸ“„ License

[MIT](LICENSE) Β© Vinger-lee

> [!note]- Reading and verification sequence: LEAP πŸŽ“ LEAP Framework
> Start with the definitions and scope in this note. Follow each prerequisite link before applying the workflow.
> Work through a concrete input and retain intermediate results; compare the output with the applicable contract or definition.
> For a failure, preserve the original input, the exact rejection reason and the corrected next action. A successful transport call is evidence of execution, not of domain correctness or learning.
> After the worked case, change one condition and state which conclusion still follows. Store the result as a timestamped observation rather than promoting evidence locally.

<!-- LEAP_BACKLINKS -->

## Backlinks / 反向关联

[Knowledge_Index](Knowledge_Index.md) Β· [README_CN](README_CN.md) Β· [docs/ARCHITECTURE](docs/ARCHITECTURE.md) Β· [docs/FACADE](docs/FACADE.md) Β· [docs/i18n/README.ar](docs/i18n/README.ar.md) Β· [docs/i18n/README.es](docs/i18n/README.es.md) Β· [docs/i18n/README.fr](docs/i18n/README.fr.md) Β· [docs/i18n/README.ja](docs/i18n/README.ja.md) Β· [docs/i18n/README.ko](docs/i18n/README.ko.md) Β· [docs/i18n/README.ru](docs/i18n/README.ru.md) Β· [docs/scope-and-limits](docs/scope-and-limits.md)

TDQS

B3/5.0

Scored across 58 tools

Disambiguation3/5

Most tools target distinct resources and actions, but several pairs overlap: get_review_state and get_due_reviews both report due review items, and get_session_info and get_teaching_context both return session/teaching state. The descriptions help separate them, but with 58 tools an agent is still at risk of misselecting between closely grouped get/save/generate/submit operations.

Naming Consistency5/5

Tool names follow a highly consistent snake_case verb_noun pattern throughout: get_session_info, save_knowledge_nodes, submit_diagnostic, commit_assessment, advance_unit, record_reflection. Despite the large number of tools, the naming convention is uniform and predictable, making the surface easier to navigate.

Tool Count2/5

With 58 tools, the surface is far beyond the 3-15 range that typically indicates a well-scoped server. Many operations could be consolidated (e.g. get_review_state/get_due_reviews, save/get pairs), and the sheer count will burden the agent's tool-selection step even if each tool is individually useful.

Completeness5/5

The tool set covers the full learning lifecycle: session creation, goals, configuration, domain grounding, diagnostics, knowledge graph management, teaching, assessment, review scheduling, misconception tracking, transfer probes, artifacts, evidence, export, and final reporting. There are no obvious dead ends or missing core operations for the apparent domain.

Maintenance

ActivityActive
ResponsivenessNo recent community issues