Which Package Powers OpenMAIC's Generation Contracts and Pipeline?

OpenMAIC's generation contracts and pipeline are implemented entirely within the @openmaic/generation package, which provides the TypeScript typings, orchestration logic, and two-stage lesson generation flow.

The THU-MAIC/OpenMAIC repository is organized as a monorepo where the @openmaic/generation package serves as the central nervous system for automated lesson creation. This package contains the domain-specific language (DSL) definitions for outlines and scenes, the pipeline driver that coordinates generation stages, and the prompt loading mechanisms that interface with large language models (LLMs).

Core Architecture of the Generation Package

The @openmaic/generation package follows a clean architectural separation between contracts (data models), pipeline logic (orchestration), and generation engines (LLM interaction). Understanding this structure is essential for extending or debugging the lesson creation flow.

Generation Contracts and Type Definitions

The foundation of the system resides in the type definition files that establish strict contracts between pipeline stages. In packages/@openmaic/generation/src/outline-types.ts, the package defines the structure for lesson outlines, including metadata, learning objectives, and section hierarchies. Complementing this, packages/@openmaic/generation/src/scene-types.ts contains the media-rich scene definitions—covering slides, quizzes, simulations, and interactive actions.

These TypeScript interfaces enforce type safety across the monorepo, ensuring that the outline generator produces data structures the scene generator can consume without validation errors.

The Two-Stage Pipeline Driver

The pipeline orchestration logic lives in packages/@openmaic/generation/src/pipeline-types.ts and the main entry point at packages/@openmaic/generation/src/index.ts. This driver implements a sequential two-stage process:

1. Outline Generation – Converts raw text requirements into structured lesson blueprints
2. Scene Generation – Transforms each outline node into concrete educational content

The pipeline supports post-processors and middleware hooks, allowing developers to inject custom transformations between stages without modifying core generator logic.

Key Components and Source Files

Outline Generation Stage

The first stage of the pipeline is implemented in packages/@openmaic/generation/src/outline-generator.ts. This module accepts a natural language requirement (e.g., "Teach quantum computing basics in 20 minutes") and calls the configured LLM to produce a structured outline object.

Key features include:

• Template-based prompt construction
• Support for multiple model providers (OpenAI, Anthropic)
• Structured output parsing with validation against outline-types.ts contracts

Scene Generation Stage

Once an outline exists, packages/@openmaic/generation/src/scene-generator.ts executes the second stage. This file contains the logic for expanding outline items into media-specific scenes—generating slide content, quiz questions, and interactive simulations based on the pedagogical structure defined in the outline.

The scene generator respects the media constraints specified in the outline (e.g., "include a short video") and selects appropriate templates from the prompt library to ensure consistent output formatting.

Prompt Handling and Templates

Prompt management is centralized in packages/@openmaic/generation/src/prompts/loader.ts and the surrounding src/prompts/ directory. The loader handles:

• System prompt template resolution
• User message formatting with variable substitution
• Multi-provider prompt adaptation (different optimal formats for GPT vs. Claude)

This abstraction allows the generation pipeline to remain agnostic of specific LLM APIs while optimizing prompt engineering for each supported provider.

Using the @openmaic/generation Package

The package exposes a high-level SDK through its main entry point, while also providing low-level access to individual pipeline stages for advanced use cases.

Full Lesson Generation

For most applications, the generateLesson function provides the complete two-stage pipeline in a single call:

// Import the generation SDK
import { generateLesson } from '@openmaic/generation';

// Example: generate a lesson from a plain-text requirement
const requirement = `
  Teach me the basics of quantum computing in 20 minutes.
  Include a short video and an interactive quiz.
`;

async function run() {
  const lesson = await generateLesson({
    requirement,
    // optional: force a particular model/provider
    model: 'openai:gpt-5.5',
  });

  console.log('Outline:', lesson.outline);
  console.log('Scenes:', lesson.scenes);
}
run();

Stage-Specific Generation

For workflows requiring inspection or modification between stages, use the individual generators:

// Low-level usage – run the outline stage only
import { generateOutline } from '@openmaic/generation';

const outline = await generateOutline({
  requirement: 'Explain neural networks for beginners',
  model: 'anthropic:claude-sonnet-5',
});

// Modify outline here before scene generation
console.log('Generated outline structure:', outline);

Package Configuration

The package metadata is defined in packages/@openmaic/generation/package.json, which publishes the SDK as @openmaic/generation to the registry. Key configuration includes:

• Entry point: src/index.ts exports the public API
• Types: Full TypeScript declarations based on the contract files
• Dependencies: LLM client abstractions and template engines

Summary

• The @openmaic/generation package is the exclusive location for OpenMAIC's generation contracts and pipeline logic, hosted within the THU-MAIC/OpenMAIC monorepo.
• Type safety is enforced through outline-types.ts and scene-types.ts, creating strict DSL contracts between pipeline stages.
• Two-stage architecture separates outline creation (outline-generator.ts) from content generation (scene-generator.ts), enabling modular processing and custom post-processing.
• Prompt abstraction in prompts/loader.ts allows the same generation logic to work across multiple LLM providers without code changes.
• Public API exposes both high-level (generateLesson) and low-level (generateOutline) functions to accommodate different integration patterns.

Frequently Asked Questions

How do I install and import the OpenMAIC generation package?

The package is available as @openmaic/generation in the monorepo. Install it using your package manager (npm, yarn, or pnpm) within the OpenMAIC workspace, then import specific functions from the main entry point: import { generateLesson, generateOutline } from '@openmaic/generation'. The package requires TypeScript 4.7+ for proper type inference of the generation contracts.

What is the difference between outline generation and scene generation?

Outline generation (src/outline-generator.ts) is the first stage that produces a structured pedagogical blueprint from raw text requirements, defining learning objectives and section hierarchies. Scene generation (src/scene-generator.ts) is the second stage that converts each outline node into concrete educational content like slides, quizzes, or interactive media. The pipeline treats these as distinct contracts to allow human-in-the-loop review or automated modification between stages.

Can I use custom prompts with the OpenMAIC generation pipeline?

Yes. The prompt system in src/prompts/loader.ts supports custom template loading. You can override default system prompts or provide template directories when initializing the generator. The loader supports variable substitution and provider-specific formatting, allowing you to optimize prompts for different LLMs while maintaining the core generation contracts defined in the type system.

Which LLM providers are supported by the generation package?

The package supports multiple providers including OpenAI (GPT models) and Anthropic (Claude models), as evidenced by the model string formats like 'openai:gpt-5.5' and 'anthropic:claude-sonnet-5'. The abstraction layer in the generation pipeline allows new providers to be added by implementing the prompt formatting and response parsing interfaces without changing the core outline or scene generation logic.

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