Understanding the Generation Pipeline in OpenMAIC: A Two-Stage Architecture

OpenMAIC employs a two-stage generation pipeline that first creates a high-level lesson outline and then generates individual scenes with content, images, and audio to produce interactive educational material.

The generation pipeline in OpenMAIC transforms abstract lesson concepts into fully rendered interactive content through systematic orchestration. This article analyzes theTHU-MAIC/OpenMAIC repository to explain how the @openmaic/generation package and agent-runtime coordinate the construction of lessons from initial planning through final media assembly.

The Two-Stage Generation Pipeline Architecture

The generation pipeline in OpenMAIC follows a deterministic two-stage flow: outline planning followed by per-scene content generation. This architectural separation ensures structural coherence before the system invests computational resources in detailed media production.

Stage 1: Outline Generation

The pipeline initiates with outline generation, where the agent-runtime plans the lesson structure. According to lib/server/agent-runtime/curriculum-tools.ts, this planning step creates a set of "pages" (scenes) and establishes the high-level narrative flow.

Internally, the system uses the tool name generate_outline, though the actual implementation invokes the generateOutline contract exported by the @openmaic/generation package. This stage focuses exclusively on structure—defining the sequence and brief description of each page without generating actual content or media.

Stage 2: Scene Generation

For each page defined in the outline, the pipeline executes scene generation via the generate_scene tool mapping. As implemented in lib/server/agent-runtime/course-tools.ts, this stage produces:

• Textual content specific to the page
• Generated images via image generation tools
• Audio assets through TTS (text-to-speech) generation
• UI actions and metadata required for the workbench interface

The scene generation stage runs repeatedly—once per page—to populate the lesson with interactive elements.

Pipeline Implementation and Orchestration

The orchestration layer bridges legacy tool naming conventions with the modern pipeline architecture. The file lib/server/agent-runtime/course-tools.ts maps internal tool names (generate_outline, generate_scene) to the corresponding pipeline stages, ensuring backward compatibility while routing requests to the appropriate generation contracts.

The contracts and prompt assets that define the generation behavior reside in packages/@openmaic/generation/README.md. This package exports the type definitions and runtime functions that curriculum-tools.ts consumes to execute the actual generation logic.

Code Example: Invoking the Generation Pipeline

Developers interact with the pipeline programmatically through the @openmaic/generation package. The following TypeScript example demonstrates the complete workflow from outline creation to final lesson assembly:

import { generateOutline, generateScene } from '@openmaic/generation';

// 1️⃣  Generate the lesson outline
const outline = await generateOutline({
  topic: 'Photosynthesis',
  language: 'zh',           // language flows through the pipeline
  style: 'interactive',
});

// 2️⃣  Generate each scene (page) based on the outline
const scenes = await Promise.all(
  outline.pages.map((page, idx) =>
    generateScene({
      pageId: page.id,
      order: idx + 1,
      brief: page.brief,
      language: outline.language,
    })
  )
);

// 3️⃣  Assemble the final lesson document
const lesson = {
  title: outline.title,
  language: outline.language,
  scenes,
};

The generateOutline function establishes the planning rail, while generateScene executes iteratively to populate content, generate images, and produce TTS assets for each page.

Key Source Files and Contracts

The generation pipeline relies on specific files within the THU-MAIC/OpenMAIC repository to manage contracts, tool implementations, and orchestration:

• packages/@openmaic/generation/README.md – Defines the generation contracts, prompt assets, and documents the two-stage pipeline architecture.
• lib/server/agent-runtime/curriculum-tools.ts – Contains the server-side implementation that writes the outline and invokes per-scene generation logic.
• lib/server/agent-runtime/course-tools.ts – Maps legacy tool names to the modern pipeline implementation, translating generate_outline and generate_scene calls to the appropriate handlers.
• README.md (repository root) – Provides the high-level overview of the material pipeline and the classic two-stage lesson generation process.

Summary

• The generation pipeline in OpenMAIC uses a two-stage architecture: outline generation followed by scene generation.
• The agent-runtime orchestrates the process through curriculum-tools.ts and course-tools.ts, mapping tool names to pipeline stages.
• Media assets (images, audio) generate during the scene stage, not during outline planning.
• The @openmaic/generation package exports generateOutline and generateScene functions for programmatic access.
• Pipeline flow follows: high-level outline → per-scene content → media assets → final lesson document.

Frequently Asked Questions

What are the two stages of the OpenMAIC generation pipeline?

The first stage is outline generation, which creates the lesson structure and page sequence. The second stage is scene generation, which produces the detailed content, images, and audio for each individual page defined in the outline.

Where is the generation pipeline implemented in the OpenMAIC repository?

The core logic resides in packages/@openmaic/generation/ for contracts and prompts, while the orchestration implementation lives in lib/server/agent-runtime/curriculum-tools.ts and lib/server/agent-runtime/course-tools.ts within the THU-MAIC/OpenMAIC repository.

How does the pipeline handle media generation?

During the scene generation stage, the pipeline invokes specialized tools to create images through image generation APIs and audio through TTS (text-to-speech) services. These assets attach to the specific scene being generated rather than being produced during the outline stage.

Can developers call the generation pipeline directly?

Yes. Developers import generateOutline and generateScene from the @openmaic/generation package to programmatically execute the pipeline, passing parameters such as topic, language, and style to customize the output according to the contracts defined in the generation package.

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