Technical architecture

AI-powered question engine

A model-agnostic architecture where AI generates curriculum-aligned questions through a contract-driven component system with programmatic validation.

Compatible with any LLM that supports structured output via JSON Schema — from cloud-hosted reasoning models to locally-run open-source models like Gemma 3.

System architecture

The complete pipeline from AI model to student-facing questions, with validation at every stage.

AI MODELLLM EngineStructured output / JSON SchemaVECTOR DATABASEComponent RegistrySchemas + metadata + embeddingsCURRICULUM DATABASEKnowledge GraphModules / submodules / prerequisitesAI QUESTION GENERATION PIPELINEQuery ContextComponent SearchSchema AssemblyValidationQUESTION ENGINERenderComponentsAnswerComponentsDifficultyEngineAnswerValidationGenerated questionsBASELINE TESTSCross-submodule coverageADAPTIVE PRACTICEPersonalised learning pathsSKILL HARDENINGPredecessor reinforcementMASTERYKnowledge graph

Question engine anatomy

Every question is a composable unit — single or multi-part — where each component has defined contracts for rendering, answering, and knowledge node impact.

QUESTION CLUSTER (MULTI-PART QUESTION)PART 1Render componentLaTeX + Cartesian gridAnswer componentMultiple choiceAffects: Fractions (Y7) + Ratios (Y7)Knowledge nodes updated on resolutionPART 2Render componentLaTeX formulaAnswer componentNumeric inputAffects: Algebra (Y8)Knowledge node updated on resolutionlinkedALL ANSWER COMPONENTS MUST RESOLVEEach component validates independently — the cluster resolves when all parts passANSWER COMPONENT TYPESMultiplechoiceTrue / falseNumericinputPairingsmatchInteractivemath componentText / freeresponse

Question Render Components

Display layer combining LaTeX mathematical notation, Cartesian grids, number lines, and rich text. Each component renders the question visually.

  • LaTeX formulas
  • Cartesian grids
  • Number lines
  • Geometric shapes
  • Data tables

Answer Components

Interactive input layer where students provide responses. Each type has its own validation logic and can embed mathematical components in read-only mode.

  • Multiple choice
  • True/false
  • Numeric input
  • Pairings/matching
  • Interactive math
  • Free text

Difficulty Engine

Non-AI parametric system that determines value ranges, complexity, and constraints for each question type based on year level and difficulty setting.

  • Parameter matrices
  • Year-level calibration
  • Value range selection
  • Complexity scaling
  • Component suitability filtering

Component composability

Each multiple choice option is itself a separate entity that can contain its own mathematical render component in read-only mode. This means an answer option can display a LaTeX formula, a graph, or a geometric diagram — not just text. The same composability applies to all answer types, enabling arbitrarily rich assessment formats while maintaining a consistent validation contract.

Difficulty engine

Deterministic, not AI-driven

Behind every question for every module, there is a difficulty engine calibrated per year level. This engine is not AI-driven — it uses fine-tuned parameters based on aggregate student performance data.

  • Determines value ranges and numerical constraints based on difficulty setting
  • Maintains a matrix of compatible components per question type
  • Filters out inappropriate component combinations automatically
  • Parameters continuously refined based on overall cohort results
  • For AI-generated questions, difficulty is set by the AI input — the engine validates solvability

Difficulty parameter matrix

Very Easy
Easy
Medium
Hard
Very Hard

AI generation pipeline

How AI transforms a query into a validated, curriculum-aligned question set.

STEP 1QueryUser or systemrequestSTEP 2UnderstandCurriculum DB lookupsubmodule + conceptSTEP 3SearchVector DB retrievalbest-fit componentsSTEP 4GenerateLLM assembles question setusing component schemasSTEP 5ValidateEngine checks all params solvableOUTPUTValid question setReady for student deliveryJSON SCHEMA CONTRACTEvery component has a defined input/output schema — the LLM generates conforming data, the engine validates

Where AI is used

Question Generation

AI generates individual questions by selecting appropriate components, setting parameters within schema constraints, and producing valid question data.

Question Set Assembly

For multi-part questions spanning multiple submodules, AI selects and combines components that assess different concepts while maintaining pedagogical coherence.

Baseline Test Optimisation

AI designs diagnostic tests that maximise submodule coverage with minimal questions. Year 8 has 44 submodules — AI generates questions touching multiple submodules simultaneously.

Predecessor Reinforcement

Based on mastery data, AI generates questions from prerequisite submodules to harden potentially atrophied skills that underpin current learning goals.

Component Generation

AI is used to build the components themselves — creating new question and answer types that conform to the system's schema contracts and validation requirements.

Vector database

Component registry & search

All question and answer components are stored in a vector database with rich metadata. When AI needs to generate a question, it performs a semantic search to find the most appropriate components for the target concept, year level, and question type.

Each component entry includes its full JSON schema contract — defining exactly what inputs it accepts and what outputs it produces. This is the bridge between AI creativity and system reliability.

Component metadata

Year Level Which year levels the component is designed for
Submodule Specific curriculum submodule it assesses
Pillar Curriculum pillar (e.g. Number & Algebra)
Description Full natural language description of the component
Input Schema JSON Schema defining all accepted parameters
Output Schema JSON Schema defining the answer validation contract
Answer Matrix Which answer components are compatible
Embeddings Semantic vector for similarity search

Knowledge hardening

Practising higher-level concepts automatically strengthens the prerequisite chain — the engine identifies and reinforces atrophied skills.

YEAR 5YEAR 7YEAR 8BasicFractionsWholeNumbersBasicDecimalsFractionOperationsRatiosDecimalArithmeticLinearEquationsTARGETAUTOMATIC HARDENINGPractising Year 8 Linear Equations automatically reinforces Year 5 fractions, decimals, and Year 7 prerequisitesAI generates predecessor questions to harden atrophied or forgotten skills

Baseline test optimisation

Year 8 Maths has 44 submodules. Testing each individually would require at minimum 44 questions. AI generates questions that touch multiple submodules simultaneously, dramatically reducing the number of questions needed while maintaining comprehensive diagnostic coverage.

Predecessor reinforcement

When mastery data shows a student struggling with a higher-level concept, AI generates targeted questions from prerequisite submodules across previous years. This hardens the foundation before re-attempting the advanced material.

Model agnostic

The architecture works with any LLM that supports structured output via JSON Schema — plug in any model, from frontier to local.

CORE REQUIREMENTStructured output (JSON Schema)MODEL COMPATIBILITY SPECTRUMOPTIMALHigher reasoning modelsClaude Opus / Sonnet, Gemini 3 ProGPT-5Best question quality + complexityCAPABLEMid-tier modelsClaude Haiku, Gemini 3 FlashGPT-5 miniGood for standard question typesMINIMUM VIABLELightweight / local modelsGemma 3, Phi-4Other local / open-sourceSimpler questions, validated output

Why model agnostic?

Because every component interaction is governed by a strict JSON Schema contract, the system doesn't depend on any specific model's capabilities beyond structured output. The LLM's role is to make intelligent selections and fill in parameters — the engine handles all validation and rendering.

Schema

Defines the contract

LLM

Fills the contract

Engine

Validates the contract

Architecture at a glance

JSON Schema

Contract System

Every component defined

Vector DB

Component Search

Semantic retrieval

Any LLM

Model Agnostic

Structured output required

Validated

Every Question

Engine-verified solvable

Kick the tyres properly

Bring your most sceptical maths teacher to the demo. The architecture holds up — that's the point of building it this way.

Book a demo