Visually Engaging Study Material Generation and Validation using Multi‑Agent Orchestration

1. Summary

The whiz.coach platform turns an instructor-provided syllabus, anything from a national curriculum PDF to a one-page outline, into a complete, learner-ready study experience: structured topics, narrated audio with synchronised SVG storyboards, interactive visualisations, practice questions, flashcards, and a master index. This document describes the two production subsystems that make that transformation reliable at scale:

1. A cloud-resident multi-agent pipeline built on Firebase Cloud Functions and Cloud Tasks. Twelve specialised agents, each owning one slice of the content lifecycle, collaborate through Firestore state and asynchronous task queues. The pipeline uses Gemini (with thinking enabled) for every LLM call, Cloud TTS for narration, and Cloud STT for forced alignment.
2. A post-hoc local validation subsystem running entirely on an Apple Silicon MacBook Pro M5 Max via MLX. Two locally-served Qwen3 models (a coder for corrections and a 32B Thinking VL model for vision judgement) read every generated artefact and propose corrections, without uploading a single byte to a remote LLM provider.

Together they form a generate-cloud / validate-local architecture that combines the throughput of managed cloud services with the privacy, cost, and iteration speed of on-device inference.

2. The content problem

A single subject (say, Cambridge Primary Maths Stage 5) expands into roughly 60–120 topics. Each topic must yield:

• Age-adaptive structured prose (bullet-led for children, editorial for adults) with verbatim source grounding;
• One static image per ~150 words plus a small number of truly interactive SVGs (cap-enforced: 1–3 per topic, depending on age);
• A narration MP3 plus an SVG storyboard with cues synchronised to within ~80 ms using forced alignment;
• Flashcards (Leitner-ready), practice questions (with diagrams), and a quiz-game variant;
• A rendered, mobile-first HTML page hosted on Cloud Storage and tied into the React app's auth and progress system.

The naive approach, a single monolithic prompt, fails on three axes: output budget (a 60-topic syllabus easily exceeds Gemini's 65 k output tokens), partial failure modes (TTS rate limits should not erase content work), and verifiability (a single artefact must be inspectable by domain-specific judges). The system therefore decomposes generation into specialised agents and validation into specialised tiers.

3. System architecture

The system is partitioned across three planes: a cloud generation plane, a local validation plane, and a cloud-side user-feedback correction plane that handles thumbs-down submissions from learners. All three share Firestore as the source of truth.

4. The agent cast

Each agent extends a common base class, receives its work via a Cloud Tasks message, transitions topic state in Firestore, and either chains to the next agent or fans out in parallel. Twelve agents are in production.

An optional thirteenth agent, PastPaperAnalysisAgent, runs on demand to surface exam-paper patterns into the syllabus document.

5. Multi-agent interactions

5.1 The happy-path pipeline

For a fresh syllabus, the pipeline cascades from a single Firestore onCreate trigger. Agents that share no dependency run in parallel, both across topics and within a single topic (most visibly the image + storyboard fan-out).

5.2 The parallel image + storyboard fan-out

The storyboard path is intentionally fire-and-forget: it never chains to another agent. The rendered HTML is emitted with pre-determined URLs for the MP3 and storyboard JSON, so the renderer does not need to wait for audio completion, it embeds an <audio> tag whose onloadedmetadata handler reveals the player only when the file becomes fetchable. This eliminates a synchronous dependency between two paths of very different latency (1–3 min vs 5–15 min).

5.3 The SVG auto-fix loop

HTML validation is the only loop in the system that actively rewrites artefacts. It is bounded by an SVG fix-attempt counter, a regeneration-triggered flag, and a fallback needs-review state that the cleanup scheduler picks up after two hours.

5.4 The user-feedback correction path

When a learner taps thumbs-down on an interactive SVG, the web app posts a feedback record to a dedicated Cloud Function, which enqueues SvgCorrectionAgent on its own Cloud Tasks queue. This is the one cloud-side correction path that remained on Gemini after the 2026-05-12 local-validator pivot.

6. Platform and external services

The pipeline composes a small number of Google Cloud primitives and a handful of external service providers, each chosen for a specific operational property.

6.1 Queue topology

Each agent owns its queue so that a backlog in one stage cannot stall another. Queue-level rate limits map onto provider quotas (Gemini RPM, Cloud TTS RPM, STT operation budget).

7. Engineering techniques

7.1 Loop prevention in three layers

• Permanent flags. Audio-URL set, permanent-failure markers, and regeneration-triggered flags all cause an idempotent early return on re-delivery.
• Status checks. Every action begins with an early return if the topic is already marked completed, so stale queued messages cannot overwrite finished work.
• Atomic transactions. Request-document completion is batched with the downstream write so a crash cannot leave both sides inconsistent.

7.2 Bounded iteration

7.3 Fire-and-forget for asymmetric latency

The image path takes 5–15 minutes; the storyboard path takes 1–3 minutes. Coupling them would either delay the page or block on the slower one. Instead, the renderer commits to a pre-determined URL pattern, content/{syllabusId}/audio/{topicId}.mp3, and emits HTML against that path. The <audio> element's onloadedmetadata handler reveals the player only when the browser successfully parses the metadata header; if the file never lands, the section silently remains hidden. No re-render is required when audio completes.

7.4 Topic-kind dispatch

A single topic-kind field, chosen by the planner from concept, lab, capstone, or reference, branches both the content prompt and the renderers section order.|

A single topic-kind field, chosen by the planner from concept, lab, capstone, or reference, branches both the content prompt and the renderers section order.|

A single topic-kind field, chosen by the planner from concept, lab, capstone, or reference, branches both the content prompt and the renderers section order.|

A single topic-kind field, chosen by the planner from concept, lab, capstone, or reference, branches both the content prompt and the renderers section order. A lab topic emits hands-on steps, pitfalls, and tools; a capstone emits a rubric; a reference emits a glossary. Adding a new kind is therefore a content-prompt change plus a renderer switch, not a new pipeline.

7.5 Age- and language-adaptive generation

Every agent that touches learner-facing text or visuals reads the syllabus average age and language fields and routes through shared configuration tables for age-tuned content, age-tuned imagery, and language registry. The same agent that produces a playful, emoji-rich cartoon storyboard for a 9-year-old produces a slate/sky-blue editorial schematic for an adult, by reading two scalar fields and a config map.

7.6 Thinking levels as a cost knob

7.7 Defensive SVG generation

SVG output is the system's highest-failure-rate artefact. The pipeline applies a layered defence:

• Prompt constraints: banned elements (<select>, <foreignObject> form controls, drag-and-drop), required patterns (1:1 viewBox, 44×44 px targets, slate slider tracks).
• Structural lint. A native renderer round-trip plus a deterministic geometry sweep (overflow, text-cut-by-line, endpoint-into-box).
• Defensive script wrapping. Every emitted interaction script is automatically wrapped with safe parsing and lookup helpers so NaN and null-reference errors never escape.
• Post-hoc visual judgement: deferred to the local Qwen3-VL validator (see §8).

8. Local validation subsystem

The local validator is a self-contained package that is the exclusive owner of every post-hoc validation, audit, and fix-proposal in the system. The 2026-05-12 pivot moved all visual judgement and validator-side correction off cloud Gemini and onto the operator's MacBook Pro M5 Max via MLX.

8.1 The MLX server pair

8.2 Activity inventory

The validator decomposes into 24 named activities. The headline is that none of them invoke a cloud LLM. A representative sample:

8.3 The local correction loop

8.4 Storage and observability

• Firestore. Dedicated collections hold each test run, its per-artefact results, individual issues, weekly feedback digests, prompt-improvement records, and an audit log of admin actions.
• Cloud Storage. A run-scoped prefix holds screenshots, run reports, and pre-correction backups.
• Admin console. An internal review page lists runs with signed-URL screenshot thumbnails and a one-click delete that removes both the Firestore documents and the matching Cloud Storage prefix.

9. Cloud / local boundary

The system enforces a strict separation between where content is generated and where it is judged. Crossing the boundary is a privacy concern (screenshots may include unreleased curriculum), a cost concern (vision tokens are expensive), and a latency concern (loopback is microseconds; remote APIs are seconds).

9.1 What lives on which side

10. Closing the loop

The validator does not merely flag bugs, it generates the data needed to prevent the same class of bug next time. Each issue document carries a remediation note written by the local coder model after the consensus vision pass. The string follows a strict shape:

1. What the bug is, in one sentence.
2. The proximate cause inferred from the screenshot.
3. The exact sentence the generation prompt should add to prevent the class.

A weekly Cloud Scheduler job reads the past seven days of notes, groups them by content kind and root cause, and sends each group to Gemini for synthesis into one prompt-edit suggestion. The output lands in a dedicated Firestore collection and surfaces in the admin review console for human acceptance and manual application to the generation prompts.

11. Operational characteristics

11.1 Recovery

A scheduled cleanup Cloud Function runs every 15 minutes. It scans for topics in every intermediate processing status and reapplies the appropriate enqueue. Quota-induced errors are retried after a 4-hour delay, up to 5 times.

11.2 Deployment isolation

Three independent guards prevent any validator code from entering production:

1. Package isolation. The validator package is referenced by neither the web app nor the cloud-function backend; production deploys ship only the latter two.
2. Sandbox route exclusion. Sandbox-only React routes use a development-only file-extension convention; the build configuration includes that extension only when an explicit sandbox flag is set at build time.
3. CI verification. A release-time script fails the build if any sandbox path leaks into the static export bundle.

11.3 Telemetry

12. Conclusion

The whiz.coach syllabus pipeline demonstrates a workable production pattern for AI-generated educational content: decompose generation into specialised, bounded, idempotent agents on managed cloud infrastructure; defer subjective visual judgement to a fully-local, privacy-preserving validation tier; and close the loop by feeding validator findings back into generation prompts. The same architecture that produces a 60-topic syllabus in hours also catches its own regressions overnight and proposes the fixes, without ever uploading a learner's unreleased curriculum to a third-party vision model.

The two design choices that did the most work were fire-and-forget for asymmetric latency (the image / storyboard fan-out) and cloud-generate / local-validate (the 2026-05-12 pivot). Both replaced synchronous coupling with a small amount of well-placed convention, a pre-determined URL pattern in one case, a six-rule local-only contract in the other.