How OpenMAIC Implements Math Text Rendering and Grading in Its Quiz System

OpenMAIC processes quiz content through a three-stage pipeline that parses LaTeX math delimiters using a custom tokenizer, renders expressions server-side with KaTeX for deterministic output, and grades answers via normalized string comparison with optional symbolic evaluation.

The OpenMAIC quiz system handles mathematical expressions as first-class objects, ensuring that inline equations like $f(x)=x^2$ and display blocks like $$\int_0^1 x\,dx$$ render consistently across web, video, and PDF outputs. According to the THU-MAIC/OpenMAIC source code, the implementation separates parsing, rendering, and grading into discrete modules that operate through a shared tokenization contract.

Parsing Math Expressions in Quiz Content

The foundation of the quiz system lies in the parseQuizMathText function located in lib/quiz/math-text.ts. This module scans raw quiz text for math delimiters ($…$ for inline math and $$…$$ for display equations) while distinguishing genuine mathematical notation from false positives such as currency symbols ($5) or URL components.

The parser implements a tiny state machine that tokenizes input strings into a sequence of objects with the following structure:

{type: 'text'|'math', value: string, displayMode?: boolean, html?: string}

When the parser encounters opening delimiters, it verifies matching closing delimiters before extracting the content. For delimiter-free algebra (e.g., x^2+1), the system falls back to heuristic detection of pure algebraic tokens. Each identified math segment is immediately processed through KaTeX's renderToString method to generate static HTML, ensuring that the resulting tokens carry pre-computed presentation markup.

Rendering Mathematical Notation

React Component Integration

Once parsing completes, React components in components/scene-renderers/quiz-renderer.tsx and components/scene-renderers/quiz-view.tsx consume the token array. These renderers iterate over segments and inject the KaTeX-generated HTML directly into the DOM for math tokens while rendering plain text nodes unchanged.

The components enforce the KaTeX_Math font family across all outputs, guaranteeing typographic consistency whether the quiz appears in a browser or embedded media. By handling math as pre-rendered HTML strings rather than client-side JavaScript execution, the system eliminates runtime layout shifts and ensures accessibility.

Font Embedding for Video Export

For offline formats, lib/video-export/emit-hyperframes/quiz-script-font-plan.ts manages the embedding of required KaTeX font files during video and PowerPoint export operations. This ensures that mathematical symbols render correctly even when the content is viewed outside of a web environment with network access.

Grading Logic and Answer Evaluation

Normalization and Comparison Pipeline

When learners submit answers, the gradeQuizAnswer helper in lib/chat/quiz-results-for-store-state.ts orchestrates the evaluation process. The function receives the learner's raw string input and applies the same parseQuizMathText routine used during content creation to isolate mathematical portions from surrounding text.

The grading pipeline normalizes both the submitted answer and the stored solution by stripping whitespace and evaluating LaTeX-escaped characters. For basic equality checks, the system performs direct string comparison after normalization. When questions require more sophisticated evaluation, the pipeline supports symbolic comparison algorithms that recognize equivalent forms of the same expression.

Store State Management

Grading results are persisted in a Redux-style store, where pass/fail flags and partial credit scores are maintained alongside the original answer text. The UI layer subscribes to these state changes to display immediate feedback without re-executing the parsing logic.

Testing Coverage and Reliability

Over 30 targeted unit tests validate the math handling system across edge cases. The test suite in tests/quiz/math-text.test.ts verifies that currency symbols remain unparsed while legitimate math delimiters trigger tokenization. Additional tests in tests/chat/quiz-results-for-store-state.test.ts confirm that grading produces accurate boolean results even when inputs contain mixed LaTeX and plain text.

The tests/video-export/quiz-question-list-emitter.test.ts file ensures that font embedding logic correctly identifies all required glyph subsets during export operations, preventing missing character issues in generated videos.

Summary

• OpenMAIC implements a three-stage pipeline for quiz math: parsing via lib/quiz/math-text.ts, rendering through React components in components/scene-renderers/, and grading via lib/chat/quiz-results-for-store-state.ts.
• KaTeX provides deterministic server-side rendering, generating static HTML that remains consistent across web, video, and PDF outputs.
• The tokenizer distinguishes math from currency using delimiter verification and heuristic algebra detection, preventing false positives while supporting concise syntax.
• Comprehensive test coverage across tests/quiz/ and tests/chat/ directories ensures robust handling of escaped delimiters, code fences, and delimiter-free expressions.

Frequently Asked Questions

How does OpenMAIC distinguish math delimiters from currency symbols?

The parseQuizMathText function in lib/quiz/math-text.ts employs a state machine that requires matching opening and closing $ delimiters with valid mathematical content between them. Currency patterns like $5 fail to meet the matching criteria or contain non-mathematical characters, causing the parser to treat them as plain text tokens rather than math expressions.

What rendering engine powers the math display?

OpenMAIC uses KaTeX to convert LaTeX math strings into static HTML. The renderToString method generates markup with specific CSS classes (katex, mathnormal) that the React components in quiz-renderer.tsx inject directly into the DOM, ensuring zero client-side JavaScript execution during rendering.

How does the grading system handle equivalent mathematical expressions?

The gradeQuizAnswer function normalizes both submitted and stored answers by removing whitespace and processing LaTeX escapes before comparison. For questions requiring semantic equivalence rather than syntactic identity, the system supports symbolic comparison algorithms that recognize different representations of the same mathematical value.

Can the quiz system render math correctly in exported videos?

Yes. The lib/video-export/emit-hyperframes/quiz-script-font-plan.ts module embeds necessary KaTeX font files during the video export pipeline, ensuring that mathematical notation displays correctly in offline environments without requiring network access to external font servers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}