How OpenMAIC Turns a Prompt into a Course Skeleton
OpenMAIC's first important design question is how to turn a request or a source document into a course structure without asking one model call to plan, write, render, and persist everything at once. This chapter follows that boundary: the model call is injected, the outline is produced before page content, and playback actions are generated separately from what a page contains. That separation gives the reader a way to understand where coherence is created, where model variability enters, and where a failed attempt should stop rather than become a misleading course page.
The model call is a seam, not the whole pipeline
The generation package does not choose a model provider, read the application's environment configuration, or own persistence. A caller supplies an AICallFn: a function that receives a system prompt, a user prompt, and optional images, then returns model output. This may sound like a small interface, but it establishes ownership. The package defines how OpenMAIC turns output into course structures; the application decides which model, credentials, transport, and storage policy sit around that transformation.
That division is more precise than saying OpenMAIC is “provider-neutral.” Provider neutrality here means that the generation logic can be used with different model connections because provider selection is outside the package. It does not mean that every provider has the same context window, vision capability, output discipline, speed, or cost. The injected seam removes one kind of coupling—generation code does not need to know which vendor is being called—but it leaves the caller responsible for supplying a call that meets the package's expectations.
The first stage consumes requirements and context rather than attempting to produce finished pages. A requirement may name a subject, a learner, a language, or a teaching goal. Source material can contribute extracted text and images. The outline prompt can also receive research context and teacher context, so the model has information about the course rather than only the title of one page. Images are handled as a bounded input: some can be supplied for vision, while others remain descriptions. This matters because the outline is a course-level decision. It needs to know what evidence and media are available before it decides what each scene should do.
The result is an ordered set of scene outlines. Each outline has an identity and a position, along with a title, description, key points, and the information needed to choose a scene kind. The generator accepts either a direct outline array or a structured response carrying a language directive and optional course title. It then assigns missing identities and normalizes order. If media identifiers collide, it makes them unique before later stages use them. The outline is therefore not decoration around the page generator. It is the first durable expression of course coherence.
That expression divides two kinds of judgment. The outline asks what belongs in the course and how pages relate; the later content pass asks how one page should represent its assigned idea. If those questions are mixed, a visually attractive page can quietly compensate for a missing prerequisite, repeat a point that belongs elsewhere, or use a source image without knowing why it matters. Keeping an ordered outline does not guarantee a good curriculum, but it gives OpenMAIC and its callers a place to see and correct the course shape before detailed generation hides the decision inside page content.
This is also where source material must be treated as context rather than authority. OpenMAIC's broader material pipeline can extract documents, audio, video, or web content, but extracted text can be incomplete, truncated, or untrusted. The outline stage can use that material to inform planning; it cannot turn a failed extraction into proof that a source says nothing, or turn instructions inside a fetched page into commands for the agent. The generation seam is consequently bounded on two sides: the caller controls model access, and the material pipeline controls what evidence is made available.
An outline is deliberately not a finished slide. It says, in effect, “there should be a page here with this purpose and these key points.” That intermediate state allows OpenMAIC to make course-level choices before it spends effort generating detailed visual content, questions, HTML, or project structure. It also creates a clean place for a human or an agent to inspect the planned shape before the page is built. The more complex the classroom, the more valuable that separation becomes: a page-level model should not have to infer the entire course architecture from a title alone.
From one outline to a persisted scene
Once an outline exists, the scene-content stage branches according to its declared kind. Slide content is generated as a structured set of canvas elements and an optional background. Quiz content is generated as questions and options. Interactive content is produced as an HTML experience with a widget type and optional configuration. PBL content is produced as a project structure with its own roles and milestones. The platform uses one generation surface to start these operations, but the branches are not interchangeable. Each kind has a different consumer and a different failure surface.
A slide illustrates why model output cannot be written directly to storage. The model may omit required fields, emit a null where a field should be absent, refer to an image by a temporary identifier, or produce an element whose geometry is malformed. The generation path first parses the response, normalizes elements, resolves image references, processes formulas, assigns element identities, and removes elements that cannot be repaired safely. Dropping one malformed element can degrade a page; preserving it can make a renderer or exporter fail on the whole scene. That is a deliberate boundary choice: a local loss is preferable to a corrupted page being treated as valid.
The same principle appears in the other branches, in different forms. Quiz options and answer representations are normalized because a model may express them in more than one shape. Interactive outlines that lack the configuration needed to build a widget can fall back rather than pretending that an incomplete interactive page is ready. PBL generation uses a structured planner and can return a clear failure rather than persisting an empty or misleading project. These are not guarantees that the model's explanation is correct. They are controls over whether its response is structurally usable.
Interactive pages add a second layer of translation. The model returns HTML, but OpenMAIC post-processes that HTML for features such as formula rendering. Before generating widget actions, the system derives an inventory of real interactive elements from the current HTML: identifiers, stable data attributes, and meaningful classes. The action generator can then target elements that actually exist instead of inventing selectors by convention. This is a small but important shift from “the model imagines an interaction” to “the model chooses from a discovered page surface.” The page can still contain errors or unsafe assumptions, but the action reference is tied to observed structure.
The PBL branch makes the same point through a different representation. A project is not just a long scene description. Its persisted shape can include roles, milestones, microtasks, scenario characters, documents, learner threads, submissions, and evaluations. The planner therefore has to produce a structure that the project runtime can understand. If a single-call planner fails for a recoverable parsing or schema reason, a caller may provide a loop fallback; provider failures and cancellation are not treated as invitations to retry blindly. The pipeline distinguishes a content-generation problem from a transport or cancellation problem because the recovery choice is different.
After content is generated, OpenMAIC performs a separate action-generation pass. For a slide, the model can receive an inventory of elements and choose where to focus, what to say, or whether to introduce another classroom action. For a quiz, it can produce an instructional lead-in. For interactive content, it can receive the widget's element inventory and generate widget highlights, state changes, annotations, or reveals. For a project, actions can introduce the project and its milestones. The action pass is not a second copy of the content pass; it answers a different question: how should this already-defined experience unfold in time?
Keeping these outputs separate makes several operations possible. A page can be regenerated while preserving its scene identity. Narration or actions can be regenerated after an edit without rewriting the page's visual content. Playback can consume the same action vocabulary whether the page was generated by the classic pipeline, imported, or edited later. The separation also limits damage: a failed action-generation response need not invalidate already-usable content, and a content failure can stop before any page is persisted.
Stable identity is especially important when a caller retries. A retry is not always a request for another page. It may be a second attempt to produce the same logical page after a transient provider error or an invalid response. If the retry receives a new identity every time, the course can accumulate duplicates while appearing to make progress. If it reuses the existing identity, the system can replace the page that the outline already assigned. The identity does not make the content correct; it keeps the history of the course aligned with the user's intent while content generation is repeated.
The action stage still has to validate references. A spotlight action needs an element that exists. A discussion action needs an agent that can participate. Unknown action names are filtered before persistence, and defaults provide a minimal behavior when the model produces no usable action set. Those defaults are not evidence that the page is pedagogically complete; they are a way to keep a structurally valid page playable when the richer model-generated choreography is unavailable.
Assembly is the point where the separate products become a complete scene. The builder supplies the common stage identity, scene identity, order, timestamps, content discriminant, and action list. A slide receives a canvas and theme; a quiz receives questions; interactive content receives HTML and widget information; a PBL scene receives its project. The result is still a data structure, not yet a running classroom. That distinction lets storage, validation, rendering, editing, and playback consume the same assembled object for different purposes.
Failure is a boundary, not an afterthought
The pipeline's fallbacks reveal its operating philosophy. If a prompt template cannot be prepared, or a non-PBL model response cannot be parsed, content generation can return a failure code and no scene is written. If an element is present but malformed, normalization can repair it or the element can be removed. If an interactive outline is incomplete, the system can downgrade it to a safer supported shape. If a page is retried, a caller can provide its existing identity so the retry replaces the logical page instead of creating a duplicate.
These choices do not make generation deterministic. They make failure legible. A provider may still return a shallow explanation. A source may be incomplete. A generated HTML widget may still be conceptually wrong. But the course store is less likely to contain a page that looks complete while violating the structural assumptions of its consumers. That is the difference between validating a pipeline boundary and validating the truth of what the model said.
For a reader inspecting the result, this distinction changes what a “successful” generation means. Success can mean that the outline was parsed, the selected scene branch produced a structurally usable payload, known actions were assembled, and the complete scene was persisted. It cannot, from these mechanics alone, mean that the page teaches the right idea or that its media is trustworthy. OpenMAIC's staged design is valuable because it exposes those different questions instead of allowing a model response to answer all of them by implication.
The staged pipeline also explains why OpenMAIC needs a shared course contract. The outline stage can decide that a page should be a slide, quiz, interactive experience, or project, but later components need a stable way to recognize that choice. The assembler can create a common scene shape, but the renderer and playback engine still need to know which content and actions are legal. The next design question is therefore not another prompt detail. It is what common structure lets these different learning experiences travel through the same platform without losing their meaning.