OpenMAIC SDK Packages: A Complete Guide to the @openmaic Monorepo

The OpenMAIC repository provides four core SDK packages—@openmaic/dsl, @openmaic/generation, @openmaic/renderer, and @openmaic/storage—that enable type-safe contract definitions, multimodal AI generation, frontend rendering, and asset storage for educational content platforms.

The THU-MAIC/OpenMAIC codebase is structured as a TypeScript monorepo where functionality is partitioned into scoped npm packages under the @openmaic/* namespace. These OpenMAIC SDK packages are published independently as early-stage (0.x) releases, allowing selective adoption of the framework's DSL, generation pipeline, rendering engine, or storage layer.

Core OpenMAIC SDK Packages

The monorepo's packages directory contains the four primary SDK modules that constitute the OpenMAIC development kit.

@openmaic/dsl – The Contract Foundation

The @openmaic/dsl package serves as the pure, dependency-free "keystone" for the entire ecosystem. It defines the core type definitions and validation logic for MAIC's data model in packages/@openmaic/dsl/src/index.ts, ensuring type safety across consumer applications regardless of which other SDK features are implemented.

@openmaic/generation – Multimodal Prompt Engineering

The @openmaic/generation package implements the multimodal prompt generation pipeline. Key logic resides in packages/@openmaic/generation/src/prompt-formatters.ts, which formats user content and constructs prompts for underlying AI providers. Internally, this SDK interacts with the Vercel AI SDK through an adapter located at lib/orchestration/ai-sdk-adapter.ts, enabling support for OpenAI, Anthropic, Google, and other LLM providers while maintaining a unified interface.

@openmaic/renderer – Frontend Visualization Engine

The @openmaic/renderer package provides the client-side rendering engine for slides, classrooms, and interactive UI components. Critical rendering utilities are implemented in packages/@openmaic/renderer/src/snapshot/katex-fonts-embed.ts, which manages the embedding of KaTeX fonts for mathematical notation in rendered educational content.

@openmaic/storage – Unified Asset Persistence

The @openmaic/storage package offers a unified abstraction layer for asset storage, supporting local filesystem operations and cloud backends such as Amazon S3. The implementation in packages/@openmaic/storage/src/asset/s3-bytes.ts features lazy resolution of the optional AWS SDK v3, importing S3Client only when cloud storage is configured. This design keeps bundle sizes small for applications using only local storage while providing byte-store contracts defined in packages/@openmaic/storage/docs/asset-http-contract.md.

Installing and Using OpenMAIC SDK Packages

Consume these packages via npm or your preferred package manager. As early-stage releases, they follow semantic versioning in the 0.x range:

npm install @openmaic/dsl @openmaic/generation @openmaic/renderer @openmaic/storage

Using the DSL and Generation SDKs

Combine the contract definitions with the generation pipeline to produce AI-powered educational content:

import { createMAICModel } from '@openmaic/generation';
import { MAICContract } from '@openmaic/dsl';

// Define a slide deck contract using the DSL
const contract: MAICContract = {
  title: 'Intro to OpenMAIC',
  slides: [{ markdown: '# Welcome' }],

};

// Initialize the generation model with provider credentials
const model = createMAICModel({ 
  provider: 'openai', 
  apiKey: process.env.OPENAI_API_KEY 
});

// Generate the slide content
const result = await model.generate(contract);
console.log(result.slides[0].markdown);

Storing Assets with the Storage SDK

Store and retrieve binary assets using the lazy-loaded storage backend:

import { makeLazyStore } from '@openmaic/storage';
import { S3Client } from '@aws-sdk/client-s3';

const s3Store = makeLazyStore({
  client: new S3Client({ region: 'us-east-1' }),
  bucket: 'my-openmaic-assets',
});

// Upload an image buffer
await s3Store.put('logo.png', await fetch('/logo.png').then(r => r.arrayBuffer()));

// Generate a signed URL for retrieval
const url = await s3Store.getSignedUrl('logo.png');
console.log('Public URL:', url);

Rendering Content with the Renderer SDK

Convert MAIC data models into browser-ready HTML:

import { renderDeck } from '@openmaic/renderer';

// Fetch a slide deck definition
const deck = await fetch('https://example.com/deck.json').then(r => r.json());

// Render to HTML string
const html = await renderDeck(deck);
document.body.innerHTML = html;

Summary

• OpenMAIC SDK packages are distributed as four scoped npm modules: @openmaic/dsl, @openmaic/generation, @openmaic/renderer, and @openmaic/storage.
• The @openmaic/dsl package in packages/@openmaic/dsl/src/index.ts provides the type-safe contract foundation used by all other components.
• @openmaic/generation handles multimodal prompt formatting via packages/@openmaic/generation/src/prompt-formatters.ts and bridges to the Vercel AI SDK through lib/orchestration/ai-sdk-adapter.ts.
• @openmaic/renderer manages frontend visualization including KaTeX font embedding at packages/@openmaic/renderer/src/snapshot/katex-fonts-embed.ts.
• @openmaic/storage implements lazy-loaded S3 support in packages/@openmaic/storage/src/asset/s3-bytes.ts for efficient asset persistence.
• All packages are currently in early 0.x development status and available individually via npm.

Frequently Asked Questions

What is the relationship between @openmaic/dsl and the other OpenMAIC SDK packages?

The @openmaic/dsl package acts as the foundational contract layer that defines data types and validation schemas. The generation, renderer, and storage packages all depend on the DSL to ensure consistent data structures across the ecosystem, making it the "keystone" dependency-free module.

Does OpenMAIC require the AWS SDK for storage operations?

No. The @openmaic/storage package implements lazy resolution of the AWS SDK v3. If you only use local filesystem storage, the S3 client is never imported, keeping your bundle size minimal. The S3 functionality in packages/@openmaic/storage/src/asset/s3-bytes.ts only initializes the AWS client when cloud storage is explicitly configured.

How does the Generation SDK interact with LLM providers?

The @openmaic/generation package internally uses the Vercel AI SDK to communicate with providers like OpenAI, Anthropic, and Google. The translation between MAIC's internal message formats and the Vercel SDK occurs in lib/orchestration/ai-sdk-adapter.ts, allowing the generation pipeline to remain provider-agnostic.

Are the OpenMAIC SDK packages production-ready?

The packages are currently distributed as 0.x releases, indicating early-stage development. While the API surface is functional, breaking changes may occur between minor versions. Production use should include thorough testing and version pinning.

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