What Are the @openmaic SDKs? A Deep Dive into OpenMAIC's Modular Architecture

The @openmaic SDKs are a family of six specialized npm packages—@openmaic/dsl, @openmaic/renderer, @openmaic/editor, @openmaic/generation, @openmaic/storage, and @openmaic/importer—that together provide the type-safe building blocks for creating, rendering, editing, generating, persisting, and importing lesson content in the OpenMAIC platform.

Located under packages/@openmaic/* in the THU-MAIC/OpenMAIC monorepo, these packages follow a strict dependency graph and are published independently to npm as version-0 modules. Each SDK addresses a specific architectural concern, from defining data contracts to converting PowerPoint files into editable slide structures.

Core SDK Packages Overview

The OpenMAIC platform is composed of six distinct SDKs that form a unified pipeline for lesson content management.

@openmaic/dsl

The Data Structure Layer (DSL) serves as the foundational type system for the entire platform. In packages/@openmaic/dsl/src/index.ts, it exports the core Slide and PPTElement types along with JSON schema definitions (./schema/*). This package has zero runtime dependencies, yet all other SDKs depend on it for type-safe contracts.

@openmaic/renderer

The Renderer SDK provides read-only rendering of slide data to the DOM. Found in packages/@openmaic/renderer/src/elements/SlideCanvas.tsx, the main SlideCanvas component converts DSL slide objects into visual output. It requires React ≥18, react-dom ≥18, motion ≥11, and TailwindCSS ≥4. For correct typography, consuming applications must import the compiled styles: import '@openmaic/renderer/fonts.css'.

@openmaic/editor

Built directly atop the renderer, the Editor SDK adds interactive editing capabilities. The primary entry point is EditableSlideCanvasWithUI (located in packages/@openmaic/editor/ui/EditableSlideCanvasWithUI.tsx), which re-exports the renderer's read-only components and augments them with ProseMirror-based document editing tools and UI chrome.

@openmaic/generation

The Generation SDK handles LLM-driven content creation. Exposed through packages/@openmaic/generation/src/index.ts, the generateSceneContent function accepts a topic parameter and returns data structures that strictly conform to the DSL types. This package operates without external peer dependencies.

@openmaic/storage

The Storage SDK abstracts persistence across multiple backends. It organizes exports through barrel files for document, asset, and key-value stores, while runtime implementations use sub-paths like @openmaic/storage/runtime/http or @openmaic/storage/runtime/pg. In packages/@openmaic/storage/src/browser/BrowserKVStore.ts, the BrowserKVStore class provides an IndexedDB-backed implementation for browser environments. Optional S3 support requires @aws-sdk/client-s3 as a peer dependency.

@openmaic/importer

The Importer SDK converts external formats into OpenMAIC's native DSL. Defined in packages/@openmaic/importer/src/importPptx.ts, the importPptx function parses PowerPoint files and returns arrays of Slide objects. This enables end-to-end workflows such as pptx → @openmaic/importer → @openmaic/renderer.

Dependency Architecture and Build Order

The @openmaic SDKs follow a strict build dependency chain:

@openmaic/dsl → @openmaic/generation → @openmaic/storage → 
@openmaic/importer → @openmaic/renderer → @openmaic/editor

When modifying source code, you must rebuild the package (or run pnpm install to trigger post-install builds) so downstream packages consume updated dist/ bundles rather than stale source files. The renderer depends on the DSL definitions, while the editor peer-depends on the entire renderer stack.

Installation and Versioning Constraints

All @openmaic SDKs are published as 0.x releases. Under semantic versioning rules for pre-1.0 software, minor version bumps represent breaking changes. Therefore, you must pin exact versions in package.json:

{
  "dependencies": {
    "@openmaic/renderer": "0.1.0",
    "@openmaic/dsl": "0.1.0"
  }
}

Avoid caret (^) ranges to prevent accidental breaking changes.

Monorepo vs. External Consumption

• Inside the OpenMAIC monorepo: Use workspace links (workspace:*) that point directly to source under packages/@openmaic/*.
• External projects: Install published npm packages (npm i @openmaic/renderer). Your application imports from the compiled dist/ directory, not the src/ source files.

Practical Usage Examples

Below are minimal implementations demonstrating each SDK's public API surface.

Defining Content with the DSL

import type { Slide, PPTElement } from '@openmaic/dsl';

const slide: Slide = {
  id: 'slide-1',
  elements: [
    {
      id: 'elem-1',
      type: 'text',
      content: 'Hello OpenMAIC!',
    } as PPTElement,
  ],
};

Rendering a Slide

import { SlideCanvas } from '@openmaic/renderer';
import '@openmaic/renderer/fonts.css'; // Required for fonts and Tailwind v4

function RenderSlide({ slide }: { slide: Slide }) {
  return <SlideCanvas slide={slide} />;
}

Enabling Editing

import { EditableSlideCanvasWithUI } from '@openmaic/editor/ui';

function EditSlide({ slide }: { slide: Slide }) {
  return <EditableSlideCanvasWithUI slide={slide} />;
}

Generating Content via LLM

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

async function generateLesson(topic: string) {
  const content = await generateSceneContent({ topic });
  // Returns DSL-compatible structures
  return content;
}

Persisting Data

import { BrowserKVStore } from '@openmaic/storage';

const kv = new BrowserKVStore();
await kv.set('slide-1', slide);
const loaded = await kv.get('slide-1');

Importing External Files

import { importPptx } from '@openmaic/importer';

async function loadPptx(file: File) {
  const { slides } = await importPptx(file);
  return slides; // Array of Slide types
}

Key Source Files and Public APIs

Understanding the entry points helps when debugging or extending the platform:

• packages/@openmaic/dsl/src/index.ts: Declares Slide, PPTElement, and JSON schemas used across all packages.
• packages/@openmaic/renderer/src/elements/SlideCanvas.tsx: Implements the read-only canvas component for DOM rendering.
• packages/@openmaic/editor/ui/EditableSlideCanvasWithUI.tsx: Provides the full editable interface built on ProseMirror.
• packages/@openmaic/generation/src/index.ts: Exports generateSceneContent for AI-driven lesson generation.
• packages/@openmaic/storage/src/browser/BrowserKVStore.ts: Implements browser-side persistence using IndexedDB.
• packages/@openmaic/importer/src/importPptx.ts: Contains the PowerPoint parsing logic and OssUpload type definitions.

Summary

• The @openmaic SDKs comprise six scoped packages that handle specific concerns: data definitions, rendering, editing, AI generation, storage, and import conversion.
• Strict dependency ordering requires building dsl before generation, storage, importer, renderer, and finally editor.
• Version 0.x packages require exact version pinning in package.json to avoid breaking changes.
• The renderer requires importing fonts.css for correct visual output and depends on React ≥18, motion ≥11, and TailwindCSS ≥4.
• Storage uses barrel exports for document stores and sub-path imports for runtime-specific backends like runtime/http or runtime/pg.

Frequently Asked Questions

What is the difference between @openmaic/renderer and @openmaic/editor?

@openmaic/renderer provides read-only React components for displaying slide content, while @openmaic/editor imports and extends the renderer to add interactive editing capabilities, UI tools, and ProseMirror-based text editing. If you only need to display lessons, use the renderer; if users need to modify content, use the editor.

Why must I pin exact versions for @openmaic packages?

Because all SDKs are currently at version 0.x (pre-release), semantic versioning treats minor bumps as breaking changes. Using caret ranges (^0.1.0) could introduce incompatible type definitions or API changes. Pinning exact versions ensures deterministic builds and prevents runtime mismatches between tightly coupled packages.

How do I use the storage SDK with PostgreSQL instead of the browser?

Import the PostgreSQL runtime store from the sub-path @openmaic/storage/runtime/pg rather than the main barrel export. The PgRuntimeStore class (alongside HttpRuntimeStore) lives in these sub-paths, while the main export only contains browser-specific and generic storage interfaces.

Can I use @openmaic/importer without the rest of the OpenMAIC platform?

Yes. The importer converts PPTX or PDF files into standard Slide objects defined by @openmaic/dsl. You can use importPptx to generate DSL-compatible JSON and then process that data with your own rendering pipeline, or pass it directly to @openmaic/renderer if you want to display it within the OpenMAIC ecosystem.

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