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

> Explore the OpenMAIC generation pipeline, a two-stage architecture that crafts interactive educational content, from lesson outlines to detailed scenes with text, images, and audio.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: deep-dive
- Published: 2026-08-30

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```typescript
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/curriculum-tools.ts) and [`course-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/curriculum-tools.ts) and [`lib/server/agent-runtime/course-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.