The Individualised Education Plan is the most consequential document in a special-needs learner's school life. It defines accommodations, the assessment trajectory, the therapy hours, the resource allocation, the goal cadence, and the family-school contract. Building an automated IEP generator that satisfies one school board is a tractable engineering project. Building one that satisfies thirty plus is a schema-design problem in disguise. Here is how we ended up structuring it.

Why a single canonical IEP schema fails

The temptation at the start of the project was to design one canonical IEP schema — the deepest, most comprehensive structure we could imagine — and then translate the output to each board's preferred document format at render time. That approach is wrong for three reasons.

First, the boards do not agree on what an IEP is. The UK SEN code of practice treats the document as a child-by-child plan tied to a named coordinator with statutory review obligations. The US IDEA framework treats the document as a procedural agreement between parents and the school district with explicit dispute-resolution clauses. The Australian Disability Standards for Education treats it as an adjustment document with explicit reference to enrolment and participation rights. The Dutch Speciaal Onderwijs framework ties it to an Ontwikkelingsperspectief — a developmental perspective — which is a forward-looking projection rather than a static plan. A single canonical schema either becomes a superset that includes every board's fields (in which case no board produces a clean document), or a subset that excludes board-specific obligations (in which case no board accepts the output).

Second, the boards do not agree on what a goal is. Some boards encode SMART goals as a strict subset of permissible language. Others encode goals as observable behaviours with frequency targets. Others encode goals as criterion-referenced achievement targets with explicit assessment instruments. A single schema for goals reads as plausible at first and falls apart on the first review.

Third, the boards do not agree on review cadence. UK SEN review is annual with interim reviews on request. US IDEA review is at least annual with re-evaluation every three years. Australian DSE adjustment reviews are continuous. The review cadence is part of the document, and a single schema cannot honour all three patterns without an explicit conditional layer.

The structure we ended up with

The pattern that worked is a three-layer design: a structured intermediate representation, a per-board projection layer, and a citation-tracked retrieval substrate.

Layer one — the intermediate representation

The intermediate representation is not an IEP. It is a structured learner profile — a typed graph of diagnostic findings, behavioural observations, classroom adjustments, therapy contacts, and goal candidates. The intermediate representation is generated from the learner's diagnostic intake and assessment history through a RAG layer over the diagnostic corpus. Crucially, it is board-agnostic. The same learner profile can produce a UK SEN document, a US IDEA document, and a UAE School For All document without regeneration.

{
  "learner_id": "uuid",
  "profile": {
    "diagnoses": [
      {"code": "F84.0", "system": "ICD-10", "note": "...", "source": "..."},
      ...
    ],
    "strengths": [...],
    "challenges": [...],
    "support_history": [...]
  },
  "goal_candidates": [
    {
      "domain": "communication",
      "observable": "...",
      "smart_compliant": true,
      "criterion_referenced": false,
      "frequency_target": null,
      "assessment_instruments": [...],
      "evidence_sources": ["doc_id_1", "doc_id_2"]
    }
  ],
  "adjustment_candidates": [...],
  "therapy_contacts": [...]
}

Layer two — the per-board projection

The per-board projection takes the intermediate representation and projects it into the document a specific board expects. The projection is a typed transformation — it knows which goal_candidate fields map to which board fields, which strict subsets are allowed, which review cadence applies, and which signature blocks are required. The projection is implemented as a board-keyed Pydantic schema with explicit validation. A projection that cannot honour the source board's required fields fails at projection time, not at render time, so the system catches schema mismatches before the document reaches the family.

This is where the board diversity is honoured. The UK SEN projection keeps the named coordinator field and the statutory review clauses. The US IDEA projection keeps the procedural agreement language and the dispute-resolution block. The Dutch Speciaal Onderwijs projection generates the Ontwikkelingsperspectief alongside the plan. Each projection is a small, readable, board-specific transformation. There are currently thirty-plus projections live, and adding a new one is a one-day exercise rather than a system rewrite.

Layer three — the citation-tracked retrieval substrate

Every field in the generated IEP carries a citation back to the source. The diagnostic findings cite the assessment documents they were extracted from. The board-specific clauses cite the board specification sections they were drawn from. The goal candidates cite the curricular targets they map to. The citations are not decorative — they are how a school can defend the document to a parent, a regulator, or a tribunal. A teacher who needs to justify a particular adjustment can follow the citation back to the board's published guidance on that adjustment.

What this unlocked operationally

Sub-3-second IEP generation

The intermediate representation is small. The per-board projection is a typed transformation, not a model call. Only the intermediate-representation generation step requires an LLM call against the retrieval substrate. That step is server-sent-event streamed to the teacher's surface so the wait feels conversational rather than batch. End to end, the median IEP generation latency is under three seconds. The previous reality in most schools was three to six weeks of manual drafting.

Regenerate on diagnostic update

When a learner's diagnostic profile updates — a new assessment, a new behaviour observation, a new therapy outcome — the system regenerates the IEP against the updated profile in under three seconds. The teacher signs off the regenerated draft and the document is current with the learner. No IEP in LUMINA is older than the most recent diagnostic update.

Add a new board in a day

Adding a new SEN board to LUMINA is a one-day exercise: ingest the board specification into the retrieval substrate, author the per-board projection schema, validate against the board's published example documents, and ship. The first thirty boards took the longest because the projection abstraction was being designed in parallel. Boards thirty-one through forty-eight (the next set in the pipeline) each took under a day.

Where this pattern generalises

The three-layer pattern — board-agnostic structured intermediate representation, per-board projection schema, citation-tracked retrieval — generalises beyond IEP generation. We are using the same shape inside DRIS for jurisdictional drug regulation differences (the same drug-interaction reasoning, projected per regulator) and inside Phoenix Horizon for jurisdictional employment contract differences (the same agreement reasoning, projected per labour jurisdiction). Anywhere you have one underlying reasoning task and many regulator-specific output formats, the three-layer pattern wins on latency, on maintainability, and on the legibility of the regulatory claim.

What we got wrong on the first attempt

We tried to teach the model the board distinctions directly. Big mistake. Telling the model "you are now generating a UK SEN IEP, follow the UK SEN code of practice" and letting it draft the document end-to-end produced documents that looked plausible and failed on the third clause. The model does not have the published code-of-practice text in working memory at sufficient fidelity. The retrieval substrate has to be where the board knowledge lives, and the projection layer has to be where the board structure is enforced.

The corollary is that LLMs are good at producing structured intermediate representations from unstructured diagnostic input, and bad at honouring detailed regulatory structure end-to-end. Use the LLM where it is strong; use typed projections where the LLM is weak. That is the load-bearing engineering judgment behind the system.

Closing

The IEP is the most consequential document in a special-needs learner's school life. LUMINA produces it in three seconds, citation-traced, board-aligned, regeneratable on diagnostic update. The architecture that got us there is not a single big schema and a clever prompt; it is a small board-agnostic intermediate representation, a per-board typed projection, and a retrieval substrate where the board knowledge actually lives. Three layers. Thirty-plus boards. One pattern.

Companion case study / Read the LUMINA case study