AutoTutor Sessions

Last Updated: 2026-10-09 | For: Teachers, content authors, experimenters, and researchers | Level: Advanced

Audience: Advanced authors and researchers. AutoTutor sessions require structured content authoring, an OpenRouter model configuration, and study/privacy review before learner use.

Overview

An AutoTutor session is a conversational unit configured with autotutorsession. Instead of selecting ordinary cards, MoFaCTS shows an AutoTutor chat surface where the learner answers in their own words and the tutor guides them toward authored expectations while detecting authored misconceptions.

This page covers the dedicated autotutorsession unit and its curriculum script. SPARC AutoTutor uses a SPARC document and an explicitly selected production-rule controller; its authoring contract is described in TutorScript. Both separate response evaluation, instructional decisions, and tutor wording. In the dedicated unit, the scorer supplies semantic evidence, the application planner chooses the target and move, and the utterance model realizes that selected move.

Use AutoTutor when you need:

• open-ended conceptual explanation rather than short-answer recall
• a dialogue that can ask hints, prompts, corrections, and repair questions
• researcher-visible turn history with expectation/misconception state
• a bounded conversational activity with explicit completion criteria

Do not use AutoTutor for simple flashcards, fixed pre/post tests, or video checkpoints. Use Learning Sessions, Assessment Sessions, or Video Units and Adaptive Logic for those.

Configuration Shape

AutoTutor configuration is split across the Profile, TDF, and stimulus file:

• Profile OpenRouter API key: user-owned key used by AutoTutor when present. The key is stored encrypted on the MoFaCTS server and returned to the browser for client-side OpenRouter requests.
• TDF tutor.setspec.openRouterApiKey: provider-supplied alternate key used only when the current user has no saved Profile OpenRouter key.
• TDF tutor.setspec.openRouterModel: lesson-level model identifier.
• TDF tutor.unit[].autotutorsession: unit-level AutoTutor settings.
• Stimulus setspec.clusters[].stims[0].display.text: learner-facing opening prompt.
• Stimulus setspec.clusters[].stims[0].autoTutor: structured curriculum script.

Minimal TDF shape:

{
  "tutor": {
    "setspec": {
      "lessonname": "AutoTutor Example",
      "name": "autotutor_example",
      "stimulusfile": "AutoTutor_Example_stims.json",
      "userselect": "true",
      "openRouterModel": "openai/gpt-5.4-nano"
    },
    "unit": [
      {
        "unitname": "Concept AutoTutor",
        "autotutorsession": {
          "cluster": 0,
          "maxTurns": 20,
          "graduation": {
            "requiredExpectationCount": 3,
            "maxActiveMisconceptions": 0
          }
        }
      }
    ]
  }
}

AutoTutor Session Fields

AutoTutor Script Fields

The first stim in the referenced cluster must include autoTutor with:

Each expectation should include an id, label, proposition, hints, prompts, and assertion. Each misconception should include an id, label, misconception, detectionCues, contrastWithExpectations, correction, and repairQuestion.

expectationRelationships is an adjacency object keyed by expectation ID. Each nested key is a related expectation ID and each value is a number from 0 to 1. AI-created AutoTutor content generates this graph as an authoring-time content artifact by embedding each expectation once, normalizing the vectors, and computing local cosine similarities. The preferred OpenRouter embedding model is google/gemini-embedding-001; if that request cannot complete, MoFaCTS tries the configured secondary embedding model, openai/text-embedding-3-large, as an intentional authoring-time multi-model retry.

The generated graph is stored in the lesson content and shared with users of that TDF. It is not private learner inference and is not recomputed during ordinary learner turns.

expectationRelationshipProvenance records the graph version, generation timestamp, model that produced the graph, attempted models, metric, score transform, source key type (tdf or user), and cache key. It never stores the OpenRouter key.

The planner uses these stored relationships to compute:

• centrality: the mean relationship strength from one expectation to the other expectations
• coherence: the relationship between the current candidate expectation and the current or last covered expectation
• frontier: (1 - expectation coverage) * coherence

These planner values are not scored from the learner answer. The AI scorer estimates learner coverage and misconception state; traversal comes from the authored relationship graph. The stored expectationRelationships matrix is the auditable runtime contract.

Once the planner selects an instructional target, that expectation or misconception remains the active focus until it reaches its release criterion. An expectation is released when its coverage reaches the configured coverage threshold. A misconception is released when its support falls below 1 - coverageThreshold (for a coverage threshold of 0.8, support must fall below 0.2). Prompts, hints, assertions, and corrections address only that active target; graph priority is used to choose the next target after the current focus is released, not to switch among unfinished targets.

The progressive scaffold moves from pump to prompt to hint to assertion when the learner does not make progress. A pump names the active concept in learner-facing language and then invites open elaboration within that concept. Assertion is the bottom-out stage: while the target remains unresolved, subsequent turns remain assertions with direct content and focused uptake checks instead of cycling back to a pump. Reaching the target criterion releases the focus and starts the next target at its normal opening stage.

Runtime Behavior

AutoTutor uses a dedicated chat surface. The runtime:

1. loads the opening prompt and structured script from the configured cluster
2. scores each learner answer against authored expectations and misconceptions
3. chooses a tutor move such as hint, prompt, assertion, correction, answer-question, or summary
4. writes each turn through the canonical history path with eventType: "autotutor-turn"
5. resumes from saved AutoTutor history for the same user, TDF, unit, and script ID

Completion can end by mastery, maximum turns, or the runtime cost cap. Saved history must match the current script, end-state flags, operational phase, pedagogical state, and transition shape; otherwise AutoTutor fails clearly rather than continuing with mismatched state.

Runtime State Map

The map below summarizes the AutoTutor runtime state transitions and the control variables that determine learner-turn routing, target selection, completion, and end-state resolution.

Data and Research Notes

AutoTutor history rows include learner text, tutor response text, turn timing, unit context, and an AutoTutor note in CFNote with state/progress metadata. Researchers should treat AutoTutor data as open-ended text data and review Data Privacy, IRB, and FERPA Notes before collecting identifiable responses.

For exports and analysis, also see:

• Data Output
• Learning Algorithms Reference
• Experiment Routes

Citation diagnostics

If the AI cites a nonempty quotation with the wrong conversation reference (including a tutor or missing history entry), or wording that does not exactly match the referenced learner statement, AutoTutor continues using the otherwise valid score unchanged. Administrators can inspect these events under Admin Tests → Recoverable system warnings. The quotation and reference remain unverified and are not automatically corrected. Citation format, evaluation direction, and score validation remain in place. The warning log stores counts and lesson references, not student answers or quoted text.

For citation troubleshooting, enable client logging at verbosity level 1 and preserve browser console output. Citation diagnostics include the actual AI quotation, latest student answer, recent conversation text, and any older referenced or matching entries, with original indices and an omitted-entry count. Credential patterns are redacted. These detailed browser logs contain learner data; they are distinct from the persisted Admin Tests warning counts. Validation and scoring behavior are unchanged by the additional diagnostics.

Operational Validation

1. Validate that the user has a Profile OpenRouter key or the TDF has tutor.setspec.openRouterApiKey, and that the TDF has an effective openRouterModel.
2. Validate the referenced cluster exists and its first stim has display.text and autoTutor.
3. Check every expectationRelationships source and target ID references an authored expectation and every value is from 0 to 1.
4. Check graduation.requiredExpectationCount does not exceed dialogPolicy.requiredExpectations.
5. Check graduation.maxActiveMisconceptions does not exceed authored misconceptions.
6. Run a short learner test and confirm AutoTutor turn rows appear in Data Output.

See Also

• Stimulus Files
• TDF field tables
• Data Privacy, IRB, and FERPA Notes
• Developer Reference Guide