Skip to main content
Glama

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

Use LEAP for interactive lessons and A4 self-study. In the linear-equations lesson, explore the balance and then work through the matching illustrated handout, workbook, and answer key. The printing guide covers offline printing and reviewed MCP PDF exports.


🚀 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

Related MCP server: Learn Shell

⚡ 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        # run the full suite

Start the MCP server:

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

📦 Install as a package

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:

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); 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.

🧠 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.

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 and the framework's boundaries.

Hosts supporting repository skills can load leap-tutor for the learning workflow and conditional recovery guidance. See setup and acceptance and host configuration 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.

See the content-quality and integration workflow and audit of the reported delivery. 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 and subject knowledge map.

🧩 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. .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

中文说明

docs/ARCHITECTURE.md

Architecture and design decisions

docs/INTEGRATION.md

Host-agent integration guide

docs/EXAMPLES.md

The eight teaching pages and their contract

docs/i18n/

Translations

CHANGELOG.md

Release history

CONTRIBUTING.md

How to contribute

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

Knowledge_Index · README_CN · docs/ARCHITECTURE · docs/FACADE · docs/i18n/README.ar · docs/i18n/README.es · docs/i18n/README.fr · docs/i18n/README.ja · docs/i18n/README.ko · docs/i18n/README.ru · docs/scope-and-limits

Available Tools

58 tools
advance_unitC

Request the next unit.

Every node sharing the unit_tag must pass its own node-level guard; one failure rejects the whole request. There is no unit table.

Inputs: session_id (required), node_id, unit_tag, request_id, +2 more.

assess_misconceptionC

Record an active misconception in its authoritative table.

Inputs: node_id (required), learner_id (required), misconception (required), severity, +2 more.

assess_responseA

Validate dimension scores and compute the weighted overall_score.

Does not persist anything. transfer and hint_dependency are excluded from the aggregate by design.

Inputs: scores (required), session_id (required), raw_answer, assessor_type, +1 more.

check_advance_unitB

Dry-run the State Guard for an advance request without changing state.

Inputs: session_id (required), node_id, unit_tag, manual_override, +1 more.

commit_assessmentB

Commit assessment evidence and update learner state server-side.

raw_answer and assessor_type are mandatory: the original learner response is stored for audit and never discarded. mastery_probability is computed by the runtime, not supplied by the caller.

Inputs: attempt_id (required), raw_answer (required), transfer, confidence, +9 more.

commit_pedagogical_decisionB

Record the decision actually acted on, for later replay.

Inputs: session_id (required), node_id, rationale, request_id, +4 more.

complete_sessionC

Set the session status (active/paused/completed/abandoned).

Inputs: session_id (required), status, request_id.

create_sessionA

Create a learning session. learner_id is required (P0 is single-learner).

Domain-grounding switches are stored per session, not globally. When domain_grounding_warn_user is true the returned notice must be shown to the user before the grounding stage starts.

Inputs: topic (required), learner_id (required), request_id, learner_name, +2 more.

decompose_topicC

Return a DAG template. Node content is generated by the host agent's LLM.

Inputs: session_id (required), topic.

evaluate_pedagogical_policyB

Evaluate the policy for the current state without persisting a decision.

Inputs: session_id (required), node_id, trigger_event.

export_session_dataC

Export the full session bundle as JSON, optionally to a file path.

Inputs: session_id (required), output_path.

find_sessionA

Find existing sessions by learner and optionally topic.

Use this to recover a session id after a chat window is reopened.

Inputs: learner_id (required), topic.

generate_assessmentC

Return an assessment blueprint with the rubric dimensions to score.

Inputs: session_id (required), count, node_id, question_type.

generate_diagnosticB

Return a diagnostic blueprint.

Rejected by the State Guard until Domain Grounding is completed, unless the session was created with allow_skip_domain_grounding=true.

Inputs: session_id (required), request_id.

generate_final_reportB

Generate the closing report, separating observed evidence from estimates.

Inputs: session_id (required), save_as_artifact.

generate_transfer_probeC

Return a transfer-probe blueprint (near / variation / far / integrated).

Inputs: session_id (required), node_id.

get_artifactC

Fetch an artefact by id.

Inputs: artifact_id (required), include_content.

get_assessment_historyC

Return past assessment results, including the raw answer for audit.

Inputs: session_id (required), limit, node_id.

get_available_actionsA

List the concrete teaching actions the host agent may execute.

Inputs: no named parameters.

get_available_strategiesB

List the pedagogical strategies available to the policy engine.

Inputs: no named parameters.

get_decision_logC

Read the pedagogical decision history for a session.

Inputs: session_id (required), limit.

get_diagnostic_resultC

Return the stored diagnostic summary plus every diagnostic attempt.

Inputs: session_id (required).

get_due_reviewsB

List due review items.

A non-empty result does not block new learning globally - blocking is a per-node Policy + State Guard decision.

Inputs: learner_id (required), limit, session_id.

get_evidenceC

Return grounding report metadata, claims and sources for a session.

Inputs: session_id (required), node_id.

get_knowledge_edgesB

List knowledge edges (prerequisite / support / extension / related).

Inputs: session_id (required).

get_knowledge_nodesC

List knowledge nodes, optionally filtered by teaching unit.

Inputs: session_id (required), unit_tag.

get_learning_configurationA

Return the session's active learning mode, overrides and preferences.

Inputs: session_id (required).

get_learning_goalA

Return the most recently saved learning goal for a session.

Inputs: session_id (required).

get_learning_metricsC

Return the section 26.1 learning-outcome indicators.

Covers Immediate Performance, Delayed Retention, Transfer Performance, Time/Attempts to Target Evidence, Hint Dependency, Misconception Resolution, Confidence Calibration and Learning Gain.

Inputs: session_id (required).

get_mastery_statusC

Return the server-estimated learner knowledge state.

Inputs: session_id (required), node_id.

get_obsidian_structureA

Return the static Obsidian vault specification.

Specification only - the runtime never reads or writes local vault files.

Inputs: no named parameters.

get_plugin_infoA

Report which implementation backs each pluggable seam (section 35).

Covers state estimation, assessment aggregation, policy, review scheduling, storage and artifact storage.

Inputs: no named parameters.

get_review_stateB

Return review items with current retrievability and due status.

Inputs: learner_id (required), node_id.

get_session_infoB

Return session state, the latest goal, node count and the next lifecycle step.

Inputs: session_id (required).

get_teaching_contextC

Return the full teaching context in one call to reduce round trips.

Inputs: session_id (required), node_id.

get_web_component_specA

Return the static web-component specification.

Specification only - the runtime never generates HTML or reads front-end sources.

Inputs: no named parameters.

list_artifactsA

List artefacts for a session, optionally filtered by type.

Inputs: session_id (required), artifact_type.

recalculate_review_scheduleC

Recompute retrievability for every review item of a learner.

Inputs: learner_id (required), now.

record_reflectionC

Store a learner reflection as an artifact.

Inputs: reflection (required), session_id (required), node_id, request_id.

record_source_conflictC

Record conflicting sources instead of silently choosing one.

Inputs: claim_id (required), conflicting_sources (required), uncertainty.

record_transfer_resultC

Record a transfer probe result; transfer_type is near/variation/far/integrated.

Inputs: score (required), node_id (required), learner_id (required), transfer_type (required), +4 more.

resolve_misconceptionB

Mark a misconception as resolved and refresh the cached snapshot.

Inputs: misconception_id (required), session_id.

rollback_unitB

Move the teaching focus back to an earlier node.

Inputs: session_id (required), target_node_id (required), reason, request_id.

save_artifactC

Save a learning artefact (HTML, Markdown, chart, code, report...).

Inputs: learner_id (required), artifact_type (required), content, version, +4 more.

save_benchmark_claimC

Save one structured knowledge claim with its source and confidence.

Inputs: claim (required), session_id (required), source_id, confidence, +3 more.

save_benchmark_reportB

Save the agent's domain grounding report and unlock diagnostics.

The full text is stored as an artifact of type agent_benchmark_report; structured claims go to benchmark_claims.

Inputs: session_id (required), report_text (required), request_id, source_refs.

save_diagnostic_resultC

Persist the diagnostic summary and mark the diagnostic phase complete.

Inputs: result (required), session_id (required), request_id.

save_knowledge_edgesC

Persist knowledge edges. The DAG is validated first and rejected if invalid.

Inputs: edges (required), session_id (required), request_id.

save_knowledge_nodesC

Persist knowledge nodes. Each unit_tag must respect unit_concept_budget.

Inputs: nodes (required), session_id (required), request_id.

save_learning_goalC

Persist the learning goal and its constraints (lifecycle Stage 1).

Inputs: session_id (required), goal, materials, request_id, +7 more.

schedule_reviewB

Create a review item for a node if one does not exist yet.

Inputs: node_id (required), learner_id (required), item_ref, request_id, +1 more.

set_learning_configurationA

Apply a learner's requested learning mode (section 32).

Pass the learner's own words in request - e.g. "以项目实战为主", "我要准备考试", "只学核心内容,尽快学会". Recognised modes are project_based / exam_prep / core_only / balanced. Stored as session-level Learning Configuration + Policy Overrides; the program is never modified, and unrecognised requests are reported back.

Inputs: session_id (required), mode, request, overrides, +1 more.

start_unitC

Set the current teaching focus to a unit or node.

Inputs: session_id (required), node_id, unit_tag, request_id.

submit_attemptC

Record a learner attempt and return its attempt_id for assessment.

Inputs: answer (required), session_id (required), item_id, node_id, +4 more.

submit_diagnosticC

Record one diagnostic answer as a learner attempt.

Inputs: answer (required), session_id (required), item_id, node_id, +4 more.

submit_reviewB

Submit an FSRS rating (1=Again, 2=Hard, 3=Good, 4=Easy) and reschedule.

Inputs: rating (required), review_item_id (required), request_id, session_id.

validate_claimC

Check whether a claim is linked to a real evidence source.

Inputs: claim_id (required), verified.

validate_knowledge_dagB

Validate the stored DAG: cycles, dangling edges, self-loops, isolated nodes.

Inputs: session_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients to create spaced-repetition flashcards from material being learned, quiz users aloud, grade answers, and schedule reviews using the FSRS algorithm through a self-hosted MCP server.
      8
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      An authenticated MCP server that lets agents create, edit, search, paginate, and delete flashcards, organize decks, and record FSRS-scheduled reviews with optimistic concurrency and idempotent updates.
      MIT