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]] · [[docs/teaching-delivery]]

🎓 LEAP Framework

[](https://github.com/Vinger-lee/leap-framework/actions/workflows/ci.yml)
🤖 Give your AI agent a real tutoring engine — not just a prompt.

[[README|English]] · [[README_CN|中文]] · [[docs/i18n/README.ja|日本語]] · [[docs/i18n/README.ko|한국어]] · [[docs/i18n/README.fr|Français]] · [[docs/i18n/README.es|Español]] · [[docs/i18n/README.ru|Русский]] · [[docs/i18n/README.ar|العربية]]

---

🚀 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

# 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

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:

pytest -q        # inspect the current test result

Start the MCP server:

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

Verify the bundled teaching pages:

python scripts/verify_example.py --all          # static spec compliance
python scripts/verify_example_runtime.py --all  # headless runtime + JSON Schema

🧠 The learning loop

1. Goal Specification
2. Domain Grounding          ← the agent studies the topic before teaching it
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

70 tools over stdio, grouped by domain:

🚀 Start with eight calls

The fine-grained tools exist so every state change is auditable on its own. A host agent does not have to drive them one by one: eight coarse tools compose them server-side, and every response returns next_call — the next tool to call, with its arguments.

Coarse tool	Composes
start_learning	create_session + save_learning_goal + set_learning_configuration
continue_lesson	get_teaching_context + get_session_info
log_teaching_action	commit_pedagogical_decision
submit_answer	submit_attempt + commit_assessment + get_mastery_status
advance_lesson	check_advance_unit + advance_unit (guard dry-run first)
get_review_queue	get_due_reviews
review_answer	submit_review
get_learner_snapshot	get_session_info + get_mastery_status + get_knowledge_nodes + get_due_reviews

The facade relaxes nothing: the State Guard still decides, a refused advance writes nothing, a failed assessment keeps the stored attempt recoverable, the raw answer is preserved verbatim and mastery is still estimated server-side. Tool profiles narrow the catalog — --tool-profile quickstart exposes 25 tools instead of 70. See the [[docs/FACADE|coarse tutor API and tool profiles]], and [[docs/scope-and-limits]] for what LEAP does and does not guarantee.

Group	Examples
Session & goal	create_session, save_learning_goal, set_learning_configuration
Diagnostic	generate_diagnostic, submit_diagnostic, save_diagnostic_result
Knowledge	decompose_topic, save_knowledge_nodes, validate_knowledge_dag
Policy	get_teaching_context, evaluate_pedagogical_policy, commit_pedagogical_decision
Assessment	generate_assessment, save_assessment_item, submit_attempt, commit_assessment, assess_response
Retention	schedule_review, get_due_reviews, submit_review
State Guard	start_unit, check_advance_unit, advance_unit, rollback_unit
Evidence	save_benchmark_report, get_evidence, validate_claim
Teaching delivery	get_teaching_delivery_policy, get_subject_catalog, save_teaching_package
Artifacts	save_artifact, get_obsidian_structure, get_web_component_spec
Reflection	record_reflection
Reporting	generate_final_report, get_learning_metrics

The table shows examples, not the complete catalog. The [[docs/mcp-tools|generated tool reference]] lists every registered tool and its exact parameters; CI checks it against the MCP catalog.

Domain Grounding now requires source locators, excerpts, linked claims, checked examples and limitations in save_benchmark_report(verification=...). Text alone remains pending; teaching entry points are guarded too. Hosts must read sources themselves and register checked questions with save_assessment_item before delivery. Free-text reasoning needs host semantic review: LEAP validates submitted records and estimates state; it does not prove subject-matter correctness.

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

Every mode uses the permanent depth, controllable diagrams, wide layout, complete Obsidian source and precise resource policy. Register the actual Markdown/HTML pair with save_teaching_package before registering questions. See [[docs/teaching-delivery]], the 11-domain catalog in [[docs/subject-knowledge-map]], and the reproducible calculus chapter in [[curricula/math1-2028-ch01/README]].

🧩 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

pytest -q                                        # inspect the current test result
python scripts/security_scan.py --root .         # secrets & PII (CI gate)
python scripts/verify_example.py --all           # example static compliance
python scripts/verify_teaching_repository.py     # canonical notes, reciprocal links and full paired bodies
python scripts/verify_mcp_bridge.py              # actual stdio Runtime + shipped page
python scripts/verify_example_runtime.py --all   # example runtime compliance
python scripts/spec_coverage.py                  # spec vs. code coverage
python scripts/apply_leap_bridge.py --check      # host-bridge completeness

Exit codes are 0 clean / 1 blocking / 2 warnings only. The first four run in CI on every push.

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	README_CN.md]]
[[docs/ARCHITECTURE	docs/ARCHITECTURE.md]]
[[docs/INTEGRATION	docs/INTEGRATION.md]]
[[docs/EXAMPLES	docs/EXAMPLES.md]]
docs/i18n/	Translations
[[CHANGELOG	CHANGELOG.md]]
[[CONTRIBUTING	CONTRIBUTING.md]]
[[SECURITY	SECURITY.md]]

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|CONTRIBUTING.md]] first.

📄 License

MIT © 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.

Backlinks / 反向关联

[[Knowledge_Index]] · [[README_CN]] · [[docs/ARCHITECTURE]] · [[docs/i18n/README.ar]] · [[docs/i18n/README.es]] · [[docs/i18n/README.fr]] · [[docs/i18n/README.ja]] · [[docs/i18n/README.ko]] · [[docs/i18n/README.ru]]