Can OpenMAIC Generate Interactive Simulations? Technical Architecture and Implementation Guide

Yes, OpenMAIC can generate fully interactive simulations through a multi-layered widget pipeline that transforms text outlines into executable, physics-based learning components.

OpenMAIC is an open-source framework for AI-generated educational content. The platform supports interactive simulations as first-class widgets, enabling dynamic exploration of scientific concepts directly within lesson pages. This capability is implemented through a robust type system, validation layers, and generation engines that convert textual descriptions into functional simulation components.

How OpenMAIC Generates Interactive Simulations

The generation process follows a structured pipeline that begins with type definitions and ends with client-side rendering. When you request an interactive simulation, the system validates the widget type, applies default configurations if needed, and generates the specific simulation parameters through several coordinated modules.

Widget Type Definitions

At the foundation of the system, the simulation widget type is formally declared in lib/types/widgets.ts (line 24). This file establishes the contract that all simulation components must follow, including supported fields like concept and keyVariables.

API Validation and Routing

When submitting a generation request, the server validates the widgetType parameter against an allowed set of interactive components. In app/api/generate/scene-outlines-stream/route.ts (line 225), the system checks that the requested type matches one of the supported values: simulation, diagram, code, game, or visualization3d. If the request specifies simulation, the pipeline routes it to the appropriate generation handler.

Default Fallback Mechanisms

If an interactive page outline lacks an explicit widget type, OpenMAIC automatically defaults to the simulation widget. The logic in packages/@openmaic/generation/src/outline-type.ts (line 51) ensures that when no specific interaction mode is defined, the system supplies widgetType: 'simulation' as the fallback. This design choice prioritizes hands-on learning experiences as the default interactive modality.

Scene Generation Engine

The core transformation logic resides in packages/@openmaic/generation/src/scene-generator.ts. This module handles the creation of widget configurations, injecting the widgetType: 'simulation' identifier and processing any provided variables or concept fields (lines 135-139 and 262-267). The generator constructs a complete configuration object that specifies the simulation's behavior, initial state, and interactive controls.

DSL Integration

OpenMAIC provides a domain-specific language (DSL) for authoring interactive content. The packages/@openmaic/dsl/src/interactive.ts file (lines 5-14) declares simulation as a valid interactive widget type. This enables authors to write imperative actions such as SetState that modify simulation variables in real-time, creating dynamic learning experiences where learners can adjust parameters and observe immediate results.

Implementing Interactive Simulations

Developers can generate simulations through three primary interfaces: the REST API, the DSL, or direct React component integration.

Requesting Simulations via the API

To generate a simulation programmatically, send a POST request to the scene outlines endpoint with the widgetType explicitly set to simulation:

// POST /api/generate/scene-outlines-stream
await fetch('/api/generate/scene-outlines-stream', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Energy conservation simulation',
    type: 'interactive',
    widgetType: 'simulation',
    widgetConfig: {
      concept: 'conservation of energy',
      keyVariables: ['mass', 'velocity', 'height']
    }
  })
});

The server validates the widgetType against the allowed set and forwards the request to the scene generator, which returns a complete widget configuration ready for embedding in lesson pages.

Defining Simulations in the DSL

For content authors, the DSL provides a declarative syntax for creating simulations with associated actions:

import { interactive } from '@openmaic/dsl';

interactive({
  widgetType: 'simulation',
  widgetConfig: {
    concept: 'pendulum motion',
    keyVariables: ['length', 'mass', 'gravity']
  },
  actions: [
    // Adjust variables and observe the motion
    { type: 'SetState', payload: { length: 1.2 } },
    { type: 'Run' }
  ]
});

The DSL parser recognizes the simulation widget declaration, creates the appropriate client-side component, and wires the action handlers to the simulation engine.

Rendering in React Components

Once generated, simulations render as standard React components. Import the SimulationWidget from the widgets package and pass the generated configuration:

import { SimulationWidget } from '@openmaic/widgets';

function LessonPage() {
  const config = {
    concept: 'ideal gas law',
    keyVariables: ['pressure', 'volume', 'temperature']
  };
  return <SimulationWidget config={config} />;
}

The SimulationWidget component renders the interactive UI, allowing learners to manipulate variables and instantly visualize the resulting physical changes.

Testing and Validation

The simulation generation pipeline includes comprehensive test coverage to ensure reliability. Test suites in files such as tests/lib/agent/client/apply-regenerate.test.ts (lines 166-170) and tests/generation/widget-actions-direct-pipeline.test.ts (lines 14-70) verify that the system correctly produces simulation widgets and persists their configurations. These tests validate the end-to-end flow from outline processing through final widget generation, confirming that the widgetType: 'simulation' field is correctly maintained throughout the pipeline.

Summary

• OpenMAIC generates interactive simulations through a dedicated widget pipeline defined in the core type system.
• The system validates simulation requests in app/api/generate/scene-outlines-stream/route.ts, defaulting to simulation widgets when no type is specified in outline-type.ts.
• Scene generation logic in scene-generator.ts constructs widget configurations with physics variables and conceptual metadata.
• The DSL in interactive.ts supports imperative actions like SetState for real-time simulation manipulation.
• Simulations can be requested via REST API, authored declaratively in DSL files, or rendered directly as React components using SimulationWidget.

Frequently Asked Questions

What types of interactive simulations can OpenMAIC generate?

OpenMAIC supports physics-style simulations that allow parameter exploration and dynamic visualization. The system handles concepts ranging from energy conservation and pendulum motion to thermodynamic processes like the ideal gas law. Each simulation accepts configurable keyVariables that learners can manipulate to observe real-time changes in the system's behavior.

How does OpenMAIC handle generation requests without a specified widget type?

When an interactive outline omits an explicit widgetType, the system automatically defaults to simulation. This fallback logic is implemented in packages/@openmaic/generation/src/outline-type.ts (line 51), ensuring that hands-on, exploratory learning experiences remain the primary interactive mode unless specifically overridden by other widget types like diagram or code.

Can simulation states be modified programmatically after generation?

Yes. The DSL defined in packages/@openmaic/dsl/src/interactive.ts enables authors to declaratively specify actions that modify simulation state. Using the SetState action type, developers and content creators can programmatically update variables such as mass, velocity, or length, triggering immediate recalculation and visualization updates in the client-side simulation engine.

Is the simulation widget generation pipeline tested?

Yes. OpenMAIC includes comprehensive test suites that validate simulation generation end-to-end. Tests in tests/lib/agent/client/apply-regenerate.test.ts and tests/generation/widget-actions-direct-pipeline.test.ts specifically verify that the system correctly produces simulations with valid configurations and that these configurations persist correctly through the generation pipeline.

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