How the OpenMAIC Import Pipeline Processes PPTX Files and Legacy Whiteboard Formats

The OpenMAIC import pipeline handles PowerPoint files through a dedicated import_pptx tool that converts slides into internal stage objects, while legacy whiteboard data is automatically canonicalized from a flat whiteboard array to a modern whiteboards dictionary structure before merging into the runtime.

OpenMAIC (THU-MAIC/OpenMAIC) provides a unified stage model that must accommodate both modern PPTX presentations and older whiteboard backup formats. Understanding how the import pipeline transforms these distinct inputs into compatible stage objects is essential for developers extending the platform's material support.

PPTX Import Pipeline Architecture

The PPTX import flow follows a three-phase pattern: detection, conversion, and stage integration.

Material Detection and Validation

When a user attaches a presentation, the pipeline first validates the file type. In tests/agent-runtime/import-pptx.test.ts, the system checks for PPTX materials using the isPptxMaterial utility, which identifies files by MIME type or filename extension.

// Conceptual detection pattern from test suite
if (isPptxMaterial(material)) {
  // Trigger the import_pptx workflow
  await processPptxImport(material.blob);
}

This validation ensures that only compatible PowerPoint files enter the conversion stage, preventing invalid data from reaching the core runtime.

Slide Conversion via pptxgenjs

Upon validation, the pipeline dynamically imports the pptxgenjs library to parse the binary PPTX data. As implemented in tests/agent-runtime/import-pptx.test.ts (lines 706-721), the system reads the file buffer and extracts individual slides.

The conversion logic maps PPTX elements to OpenMAIC's internal slide format. The primary transformation occurs in lib/export/use-export-pptx.ts, where shapes, text boxes, and images are normalized into slide objects containing textual, image, and shape elements. This abstraction layer decouples the presentation source from the rendering engine.

Stage Integration Without Content Loss

The import_pptx tool appends converted slides to the current stage using the writePagesToStage action. Critically, the implementation in tests/agent-runtime/import-pptx.test.ts (lines 447-465) demonstrates that this operation never replaces existing content—it only appends new pages. This non-destructive approach ensures that pre-existing whiteboard data and annotations remain intact during the import process.

Legacy Whiteboard Format Migration

Older OpenMAIC backups store whiteboard data differently than the current architecture, requiring a canonicalization step during restoration.

Detecting Legacy whiteboard Arrays

Legacy stages stored whiteboard elements in a single whiteboard array property, while the modern schema uses a whiteboards dictionary where each whiteboard maintains a unique identifier. During stage loading, the system detects the legacy field presence in tests/runtime/database-chat-cutover.test.ts (lines 1616-1648).

Canonicalization to whiteboards Dictionary

The canonicalizer transforms legacy data by wrapping the flat array into the new dictionary structure and generating unique IDs. This logic appears in tests/runtime/database-chat-cutover.test.ts (lines 1941-1975) and is implemented within the stage-loading routine in lib/api/stage-api-whiteboard.ts.

// Legacy-to-modern conversion pattern
if (stage.whiteboard) {
  stage.whiteboards = [{ 
    id: generateId(), 
    elements: stage.whiteboard 
  }];
  delete stage.whiteboard;
}

This migration runs transparently during restoration, ensuring backward compatibility without requiring manual user intervention.

Merging Imported Content with Existing Stages

After PPTX conversion, the pipeline must reconcile new slide content with existing whiteboard state. The system injects whiteboard beats—timeline markers that signal whiteboard open/close events—to preserve interactivity.

According to tests/video-export/timeline.test.ts (line 142), the pipeline ensures that whiteboard actions existing before the import remain replayable by maintaining precise synchronization between slide transitions and whiteboard activation states. The final stage object contains both slide objects (from PPTX conversion) and whiteboard objects (either migrated from legacy data or newly created), providing a seamless, layout-preserving experience.

Practical Implementation Examples

The following patterns demonstrate the complete import workflow:

// PPTX detection and import
async function handleMaterialImport(material: Material) {
  if (isPptxMaterial(material)) {
    const pptx = await import('pptxgenjs');
    const buffer = await pptx.read(material.blob);
    const slides = convertPptxToSlides(buffer); // lib/export/use-export-pptx.ts
    await writePagesToStage(stageId, slides);
  }
}

// Legacy whiteboard handling during stage load
function canonicalizeStage(stage: StageData) {
  if (stage.whiteboard) {
    stage.whiteboards = [{ 
      id: crypto.randomUUID(), 
      elements: stage.whiteboard 
    }];
    delete stage.whiteboard;
  }
  return stage;
}

Summary

• PPTX processing relies on the import_pptx tool defined in skills/agent-runtime/pptx-import/SKILL.md, which uses pptxgenjs for parsing and lib/export/use-export-pptx.ts for element conversion.
• Legacy whiteboard arrays (single whiteboard property) are automatically detected and canonicalized to the modern whiteboards dictionary format during stage restoration.
• Non-destructive appending ensures existing stage content persists when importing PowerPoint slides.
• Whiteboard beats maintain timeline synchronization between imported slides and existing interactive elements.

Frequently Asked Questions

How does OpenMAIC detect PowerPoint files during import?

OpenMAIC uses the isPptxMaterial utility function, which validates MIME types and filename extensions within the import pipeline. This check occurs in tests/agent-runtime/import-pptx.test.ts before any conversion logic executes.

What happens to existing whiteboard content when I import a PPTX?

The import_pptx tool appends new slides to the current stage without replacing existing content. As verified in tests/agent-runtime/import-pptx.test.ts (lines 447-465), the pipeline preserves all pre-existing whiteboard data and annotations during the import operation.

Does OpenMAIC support old whiteboard backup formats?

Yes. The platform automatically canonicalizes legacy whiteboard arrays into the modern whiteboards dictionary structure. This migration occurs during stage loading in lib/api/stage-api-whiteboard.ts and is tested in tests/runtime/database-chat-cutover.test.ts, requiring no manual intervention.

Which library handles the actual PPTX parsing?

The pipeline dynamically imports pptxgenjs to read PowerPoint file buffers. This dependency is loaded at runtime in tests/agent-runtime/import-pptx.test.ts (lines 706-721) and processes the binary PPTX data before the conversion layer transforms it into OpenMAIC's internal slide format.

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