Skip to content

Training Mode

training_mode -- AI tutoring with SM-2, Socratic questioning, and knowledge grounding.

Cluster: Uncategorised | Type: component | MCP Tools: 27

Overview

AI tutoring system with SM-2 spaced repetition, Socratic questioning, knowledge grounding, and metacognitive competence checking. It supports a one-command starter flow through tm_start_session: the block creates a learner if needed, seeds a starter curriculum from curated grounding-corpus sources, records curated documentation sources for later refresh, starts a session, and returns the first ready-to-answer question. It tracks learner mastery maps and session history.

Pilot-ready tutoring helper, not a comprehensive education engine

Treat training_mode as a pilot-ready training and onboarding helper. The starter curriculum is intentionally narrow and currently aimed at coding-oriented domains such as Python, JavaScript, TypeScript, web development, testing, debugging, and general coding practice. Starter sources are resolved from curated local grounding-corpus material first, with curated ctx_scrapling URLs recorded as trusted source metadata. Live ctx_search results are not treated as canonical first-run teaching sources.

Source coverage and answer assessment still have limits. Corpus snippets are selected with lightweight local heuristics rather than a full indexed retrieval pipeline, curated web sources are not automatically fetched/refreshed during first-run onboarding, and answer critique remains heuristic unless a richer judge is explicitly wired. For production, regulated, or high-stakes education workflows, review the source manifest, add domain-specific trusted material, validate generated questions and feedback against held-out examples, and keep a human reviewer in the loop.

Runtime callers should inspect source_health / tm_source_health before starting high-stakes workflows. The health report is read-only, redacts filesystem paths to memory or file mode, and surfaces LLM reachability, sklearn TF-IDF availability, FastMCP availability, SQLite store availability, and optional human_development / HAT / education backend wiring. Outputs use the canonical envelope states verified, qualified-draft, and blocked-escalated; local fallback behavior such as missing sklearn TF-IDF or missing optional pedagogy backends is surfaced as qualified-draft with warning_card and evidence, not hidden as clean completion.

When to use:

  • Giving new users a grounded starter tutoring workflow in supported coding domains
  • Building AI tutoring or knowledge-transfer pilots for human learners
  • Enforcing evidence-grounded starter explanations in educational agent workflows
  • Tracking individual learner progress with spaced repetition scheduling

Example:

from mvp.training_mode.training_mcp import TrainingModeMCPBlock, MCPTrainingInput

block = TrainingModeMCPBlock(db_path="training.db")
result = block.infer(MCPTrainingInput(
    op="start_session",
    learner_id="student_01",
    domain="python",
    tier="basic",
))
# result.is_ok() -> True
# result.value.session_summary["first_question"] contains the first grounded question.

Works well with: grounding, ctx_rag, ctx_scrapling, human_development, align_verbsamp

Public API

PolyaPhase(str, Enum)

Polya's four problem-solving phases — enforced sequentially.

SM2Card

Single item in the spaced repetition system.

Field Type Default
topic str required
easiness float required
interval_days float required
repetitions int required
next_review datetime required
last_reviewed datetime \| None required

KnowledgeSource

A trusted reference document for grounding.

Field Type Default
source_id str required
title str required
source_type str required
uri str required
domain str required
topics list[str] required
trust_level str required
added_at datetime required
checksum str required

GroundingResult

Result of a grounding check against registered sources.

Field Type Default
grounded bool required
confidence float required
sources_used list[str] required
relevant_passages list[str] required
coverage float required
gaps list[str] required

CompetenceCheck

Can the AI teach this topic? Hard gate.

Field Type Default
topic str required
sources_available int required
min_trust_level str required
coverage_score float required
competent_to_teach bool required
reason str required

Question

A question generated for the learner.

Field Type Default
content str required
domain str required
topic str required
difficulty float required
bloom_level str required
hints list[str] required
polya_phase str required
question_type str required
generated_by str required

AnswerCritique

Assessment of a learner's answer — never reveals the answer.

Field Type Default
correct bool required
partial_credit float required
correct_parts list[str] required
misconceptions list[str] required
reasoning_quality str required
feedback str required
bloom_demonstrated str required

SessionRecord

Record of a completed training session.

Field Type Default
session_id str required
started_at datetime required
ended_at datetime \| None required
questions_asked int required
questions_correct int required
hints_used int required
topics_covered list[str] required
metacognitive_prompts_given int required
difficulty_adjustments list[tuple[str, float, float]] required

LearnerProfile

Persistent learner state across sessions.

Field Type Default
learner_id str required
domain str required
knowledge_map dict[str, float] required
sm2_cards dict[str, SM2Card] required
session_history list[str] required
zpd_estimate float required
sheridan_level int required
skill_phase str required
total_questions int required
total_correct int required
streak int required
created_at datetime required
last_active datetime required

TrainingInput

Tier-1 block input.

Field Type Default
op str required
learner_id str ''
domain str ''
topic str ''
answer str ''
difficulty float \| None None
bloom_level str ''
session_id str ''
metadata dict field(default_factory=dict)

TrainingOutput

Tier-1 block output.

Field Type Default
op str required
question Question \| None None
critique AnswerCritique \| None None
hint str ''
profile LearnerProfile \| None None
mastery_map dict[str, float] field(default_factory=dict)
due_reviews list[str] field(default_factory=list)
message str ''
metadata dict field(default_factory=dict)
requires_review bool False
degraded bool False
degradation_reason str \| None None
agentic_evidence dict \| None None
completion_state Literal['verified', 'qualified-draft', 'blocked-escalated'] 'qualified-draft'
warning_card dict field(default_factory=dict)
evidence dict field(default_factory=dict)
request_id str ''
task_id str ''
run_id str ''

TrainingModeBlock(AIBlock)

Tier-1 block for AI tutoring.

Field Type Default
name str 'training_mode'
state dict field(default_factory=dict)
hd_block object None
edu_block object None
hat_block object None
planner TrainingAssessmentPlanner \| None None

Methods:

infer(data: TrainingInput) -> Result

MCPTrainingInput(BaseModel)

Field Type Default
op TrainingOp required
learner_id str ''
session_id str ''
domain str ''
topic str ''
topics list[str] Field(default_factory=list)
answer str ''
difficulty float \| None None
quality int \| None None
bloom_level str ''
polya_phase str ''
tier str 'basic'
source_title str ''
source_uri str ''
source_type str 'documentation'
trust_level str 'community'
metadata dict Field(default_factory=dict)

MCPTrainingOutput(BaseModel)

Field Type Default
op str required
success bool True
message str ''
question dict \| None None
critique dict \| None None
hint str ''
profile dict \| None None
mastery_map dict[str, float] Field(default_factory=dict)
due_reviews list[str] Field(default_factory=list)
schedule_preview list[str] Field(default_factory=list)
session_summary dict \| None None
competence dict \| None None
grounding dict \| None None
sources list[dict] Field(default_factory=list)
curriculum dict \| None None
stats dict \| None None
metadata dict Field(default_factory=dict)
requires_review bool False
degraded bool False
degradation_reason str \| None None
agentic_evidence dict \| None None
llm_used bool False
completion_state Literal['verified', 'qualified-draft', 'blocked-escalated'] 'qualified-draft'
warning_card dict Field(default_factory=dict)
evidence dict Field(default_factory=dict)
request_id str ''
task_id str ''
run_id str ''

TrainingStore

7-table SQLite store for Training Mode.

Constructor:

Parameter Type Default
db_path str ':memory:'

Methods:

create_learner(user_id: str, domain: str, tier: str) -> str

Create a new learner record and return its id.

get_learner(learner_id: str) -> dict | None

Return learner row as dict, or None if not found.

update_mastery(learner_id: str, topic: str, score: float) -> None

Merge topic:score into the learner's knowledge_map_json.

update_learner_stats(learner_id: str, questions_delta: int = 0, correct_delta: int = 0, streak: int | None = None, skill_phase: str | None = None, zpd_estimate: float | None = None, sheridan_level: int | None = None) -> None

Update aggregate stats on a learner.

upsert_sm2_card(learner_id: str, topic: str, easiness: float, interval_days: float, repetitions: int, next_review: str, last_reviewed: str | None = None) -> None

Insert or replace an SM-2 card for (learner_id, topic).

get_sm2_card(learner_id: str, topic: str) -> dict | None

Return SM-2 card for (learner_id, topic), or None.

get_sm2_cards(learner_id: str) -> list[dict]

Return all SM-2 cards for a learner.

create_session(learner_id: str) -> str

Create a new session. Raises ValueError if one is already active.

get_session(session_id: str) -> dict | None

Return session row as dict, or None.

end_session(session_id: str) -> None

Mark session as completed.

count_sessions_today(learner_id: str) -> int

Count sessions started today (UTC) for learner.

get_session_stats(session_id: str) -> dict | None

Return session stats as dict, or None.

update_session_stats(session_id: str, questions_asked_delta: int = 0, questions_correct_delta: int = 0, hints_used_delta: int = 0) -> None

Increment aggregate counters for a session.

insert_question(session_id: str, learner_id: str, topic: str, content: str, difficulty: float, bloom_level: str, polya_phase: str, question_type: str, generated_by: str, grounding_json: str) -> int

Insert a question and return its rowid.

get_question(question_id: int) -> dict | None

Return question row as dict, or None.

get_questions_for_session(session_id: str) -> list[dict]

Return all questions for a session.

update_question_answer(question_id: int, answer: str, critique_json: str, correct: bool, partial_credit: float) -> None

Record an answer for a question.

update_question_grounding(question_id: int, grounding_json: str) -> None

Replace grounding provenance for a question.

increment_hints(question_id: int) -> None

Increment hints_revealed by 1.

get_current_question(session_id: str) -> dict | None

Return the latest unanswered question for a session.

register_source(source_id: str, title: str, source_type: str, uri: str, domain: str, topics: list[str], trust_level: str, checksum: str) -> None

Register a knowledge source.

list_sources(domain: str) -> list[dict]

List all sources for a domain.

count_sources(domain: str) -> int

Count sources for a domain.

get_sources_for_topic(domain: str, topic: str) -> list[dict]

Return sources that cover a topic (JSON contains check).

create_curriculum(learner_id: str, domain: str, topics_json: str, grounding_coverage: float) -> int

Create a new active curriculum, superseding any existing one.

get_active_curriculum(learner_id: str, domain: str) -> dict | None

Return the active curriculum for (learner_id, domain).

advance_curriculum_index(curriculum_id: int) -> None

Increment current_index by 1.

log_grounding(learner_id: str, session_id: str | None, operation: str, topic: str, grounded: bool, confidence: float, sources_used: list[str], coverage: float, gaps: list) -> None

Log a grounding check event.

get_grounding_logs(topic: str) -> list[dict]

Return all grounding log entries for a topic.

TrainingModeMCPBlock(AIBlock)

27-op MCP block — Tier 2.

Field Type Default
name str 'training_mcp'
state dict field(default_factory=dict)
db_path str ':memory:'

Methods:

infer(data: MCPTrainingInput) -> Result

MCP Tools

Operation Source
start_session training_mcp
next_question training_mcp
submit_answer training_mcp
get_hint training_mcp
end_session training_mcp
assess_knowledge training_mcp
adjust_difficulty training_mcp
get_zpd_estimate training_mcp
get_mastery_map training_mcp
check_competence training_mcp
generate_curriculum training_mcp
schedule_review training_mcp
get_due_reviews training_mcp
interleave_topics training_mcp
register_source training_mcp
ask_socratic training_mcp
prompt_metacognition training_mcp
critique_answer training_mcp
reciprocal_teach training_mcp
polya_guide training_mcp
create_learner training_mcp
get_learner training_mcp
summarize_progress training_mcp
export_session training_mcp
info training_mcp
list_patterns training_mcp
source_health training_mcp