Understanding the UserRequirements Structure for Outline Generation in OpenMAIC

The UserRequirements interface in OpenMAIC defines a structured object with one required string field (requirement) and five optional fields (userNickname, userBio, webSearch, interactiveMode, taskEngineMode) that together capture user intent and generation preferences for AI-powered educational outlines.

OpenMAIC is an open-source educational content generation framework developed by THU-MAIC. When you request an outline—whether for a lesson, presentation, or interactive tutorial—the system relies on a well-defined UserRequirements object to understand what you need and how to personalize the output. This article breaks down every field, its purpose, and how to use it effectively in your own implementations.

---

Core Structure of UserRequirements

The UserRequirements interface is declared in packages/@openmaic/generation/src/outline-types.ts (lines 23-31). Here's the complete TypeScript definition:

export interface UserRequirements {
  requirement: string;
  userNickname?: string;
  userBio?: string;
  webSearch?: boolean;
  interactiveMode?: boolean;
  taskEngineMode?: boolean;
}

All fields marked with ? are optional. The generator ignores omitted fields rather than failing, giving you flexibility in how you construct requests.

---

Field-by-Field Breakdown for Outline Generation

requirement: The Core Teaching Request

Required. This string carries the fundamental content intent. Examples include "Teach photosynthesis," "Explain quantum entanglement to beginners," or "Create a coding tutorial on Python list comprehensions."

The requirement field drives the LLM prompt directly. Without it, generateSceneOutline will reject the request at the type level (TypeScript compilation) or runtime validation stage.

userNickname: Personal Reference

Optional short name (e.g., "Alex," "Dr. Chen") that the generator may weave into explanations or quiz feedback. Useful for building rapport in one-on-one tutoring scenarios.

userBio: Background Context

Optional background string that influences tone and depth. A value like "Biology teacher with 5 years of experience" signals professional sophistication, while "Complete beginner to programming" triggers more foundational explanations.

webSearch: Real-Time Fact Enrichment

When set to true, the generator may invoke an external web-search step before outline creation. This fetches current data—crucial for rapidly evolving topics like technology, scientific discoveries, or current events—then incorporates findings into the generated SceneOutline.

interactiveMode: Widget Generation

Enables embedding of interactive elements within the outline: quizzes, drag-and-drop exercises, simulations, or step-by-step problem solvers. In packages/@openmaic/generation/src/scene-generator.ts, this flag branches the generation logic toward specialized prompt templates that produce structured widget specifications alongside standard slide content.

taskEngineMode: Backend Switching

Routes the request to a task-oriented engine with different prompting strategies and response handling. Use this when the outline needs tight integration with external task systems or when the default generative mode produces suboptimal results for procedural, step-heavy content.

---

Practical Usage Examples

Minimal Request

Supply only what you need. Here's a bare-bones call to generateSceneOutline:

import { generateSceneOutline } from '@openmaic/generation';

const simpleReq: UserRequirements = {
  requirement: 'Explain the water cycle',
};

await generateSceneOutline(simpleReq);

This produces a standard educational outline without personalization, web augmentation, or interactive elements.

Rich, Personalized Request

Configure every option for maximum customization:

const detailedReq: UserRequirements = {
  requirement: 'Teach photosynthesis to high-school students',
  userNickname: 'Alex',
  userBio: 'Biology teacher with 5 years of experience',
  webSearch: true,
  interactiveMode: true,
  taskEngineMode: false,
};

await generateSceneOutline(detailedReq);

In this case, generateSceneOutline (implemented in packages/@openmaic/generation/src/scene-generator.ts) will:

1. Search the web for current photosynthesis research
2. Address the user as "Alex" where appropriate
3. Calibrate explanations to an experienced educator's level
4. Embed interactive quizzes or simulations within the resulting SceneOutline

---

Where UserRequirements Is Processed

File	Purpose
packages/@openmaic/generation/src/outline-types.ts	Source of truth for the UserRequirements interface definition
packages/@openmaic/generation/src/scene-generator.ts	Primary consumer; implements generateSceneOutline and handles field-dependent prompt construction
tests/generation/media-prompt-wiring.test.ts	Test coverage verifying correct propagation of all UserRequirements fields
lib/types/generation.ts	Internal re-export for broader library consumption

---

Summary

• UserRequirements structures all user input for OpenMAIC outline generation with one required field (requirement) and five optional modifiers
• Optional fields (userNickname, userBio, webSearch, interactiveMode, taskEngineMode) control personalization, fact-freshness, widget inclusion, and backend selection
• Omitted fields are silently ignored, so you pay only for the complexity you need
• Source locations: interface in outline-types.ts, implementation in scene-generator.ts

---

Frequently Asked Questions

What happens if I omit all optional fields in UserRequirements?

The generator proceeds with defaults. You'll receive a standard outline based solely on your requirement string—no personalization, no web search, no interactive elements. This is the recommended starting point for simple use cases.

Does OpenMAIC validate UserRequirements at runtime?

Yes. While TypeScript provides compile-time safety, the generation pipeline in scene-generator.ts performs runtime checks. Missing or malformed requirement values trigger errors before any LLM calls occur.

Can I update UserRequirements after initial outline generation?

The interface itself is immutable per call, but you can construct a new UserRequirements object with modified fields and invoke generateSceneOutline again. This pattern supports iterative refinement workflows where user context evolves.

When should I enable taskEngineMode over the default mode?

Enable taskEngineMode when your content is procedural or goal-oriented—software tutorials, lab protocols, or certification exam prep—where the task engine's structured response handling outperforms the default generative approach.

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