THU-MAIC / THU-MAIC/OpenMAIC

Feature: persist quiz attempts and expose assessment context for downstream classroom flow

Open
#57 1 comment 0 reactions 0 assignees View on GitHub
area:generation area:storage enhancement priority:P1 status:in-progress
Dominant language
TypeScript
Stars
37.2k
Forks
5.9k
Avg merge
1d 3h
Merged PRs (30d)
195

Description

### Problem or Motivation

OpenMAIC can generate quiz scenes and grade short-answer questions, but quiz results currently stop at the UI layer.

Today, quiz answers and grading results are kept inside the quiz component state and are not modeled as a durable runtime object such as a submission / attempt / assessment result. This means the system cannot reliably:

- persist quiz outcomes across refreshes / sessions
- feed quiz evidence into later classroom orchestration
- let downstream LLM calls adapt teaching based on what the learner actually got right or wrong

So the current loop is effectively:

`generate quiz -> answer -> grade -> show report`

but not:

`generate quiz -> collect learning evidence -> persist assessment state -> use it to drive next teaching step`

This is related to, but different from, #22:
- #22 is about a learner's prior cognitive profile
- this issue is about runtime learning evidence from quiz attempts

Both can coexist, but quiz-result feedback is the more direct path to adaptive teaching.

### Proposed Solution

Introduce quiz result flow as a first-class product/runtime concept.

Minimum viable direction:

1. Add a durable runtime object such as `QuizAttempt` / `QuizResult`
- includes `stageId`, `sceneId`, `attemptId`, submitted answers, per-question grading result, aggregate score, weak concepts, and timestamps

2. Add a quiz submission API
- e.g. `POST /api/quiz-attempts` or `POST /api/quiz-submit`
- distinct from `/api/quiz-grade`, which can remain a per-question grading helper

3. Persist the result
- at least in local persistence so refresh / scene switching does not lose assessment state
- optionally server-side for hosted / multi-session scenarios

4. Derive an `assessmentContext` summary for downstream model consumption
- example fields: `latestQuizScore`, `incorrectQuestions`, `weakConcepts`, `masteryLevel`, `recommendedNextStep`

5. Inject `assessmentContext` into downstream orchestration / generation
- `/api/chat` for adaptive multi-agent teaching
- later scene generation / regeneration for remediation or branching

### Why This Matters

Without this, quizzes are mainly presentation-layer assessments.
With this, quizzes become a learning signal that can support:

- adaptive remediation after poor performance
- skipping ahead when mastery is high
- better teacher/assistant responses in the current classroom
- more coherent personalized learning flows overall

### Open Questions

- Should the first version be local-only persistence, or should it include server-side persistence too?
- Should `assessmentContext` be injected only into `/api/chat` first, or also into scene generation in the initial MVP?
- Is it better to store full raw answers plus a summarized assessment layer, or only the summary in the first iteration?

### Area

Interactive simulations

### Additional Context

From a product-modeling perspective, the missing piece is not only an API endpoint but a missing abstraction boundary:

- current model: `QuizDefinition`
- missing runtime model: `QuizAttempt` / `AssessmentResult` / `LearnerState`

Once quiz outcomes are modeled as durable learning evidence, they can become a stable input to later LLM-driven classroom behavior.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.