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

> Explore the @openmaic monorepo SDK packages: dsl, generation, renderer, and storage. Build type-safe educational content platforms with multimodal AI and frontend rendering.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: getting-started
- Published: 2026-08-30

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```bash
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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.