THU-MAIC/OpenMAIC v1.3.0-rc.1

v1.3.0-rc.1 — knowledge base (release candidate)

on GitHub

1.3.0-rc.1 is the first release candidate for 1.3.0. Its main theme is the knowledge base: every upload is kept in its owner's knowledge base until it is deleted, organized in folders and parsed once, with the result reused by every conversation. A new library page lists and organizes the materials, the composer offers them through @ and a picker, and the agent gets tools to read, search and organize them. Interactive scenes also load their libraries from the deployment instead of a public CDN, the editor marks pages that have current problems, and malformed slide shapes no longer hang the renderer. This release contains breaking changes and upgrade conditions: the built-in Veo provider is removed, and the knowledge base adds schema changes that cannot run beside older instances or be rolled back. Read Breaking Changes before upgrading from 1.2.x.

Breaking Changes

• The built-in Veo video provider (veo) is removed. Google shuts down all three Veo 3.1 preview models (veo-3.1-generate-preview, veo-3.1-fast-generate-preview, veo-3.1-lite-generate-preview) on October 22, 2026, and they were the provider's last models (Veo 3.0 and 2.0 were removed in #1939). Support for Google's replacement, gemini-omni-1.1-flash, is tracked in #1940.

  • Pick another video provider in Course Model Config → Video, or assign slots.video to one in openmaic.yml. Veo 3.1 stays available through OpenRouter Video (google/veo-3.1), which OpenRouter serves from Vertex AI and is not part of this shutdown.
  • Existing configurations keep loading. An openmaic.yml provider with preset: veo no longer stops the server: it resolves nothing, every slot that named it follows its parent again, and a startup notice asks to remove it. Workspace settings that chose a Veo provider fall back the same way. VIDEO_VEO_API_KEY, VIDEO_VEO_MODELS and VIDEO_VEO_BASE_URL are ignored, with a startup notice when set; a video.veo entry in server-providers.yml is not carried over.

• The knowledge base sets release conditions. This is the first release that writes material reference roots and keeps knowledge-base materials only in the asset pool, and processes of an earlier release can lose that data. #1896

  • Stop every old instance before this version accepts writes. Do not run a mixed-version rolling deployment: schema-version checks in recent builds refuse to start against a newer schema but do not stop a process that is already running.
  • Finish the rollout well within ASSET_COLLECTION_GRACE_MS (one hour by default). An older collector releases an entry that only a reference root keeps alive one grace period after stamping it.
  • Do not roll back below this release (the material-pool Phase 1a boundary): an older reader cannot read a material that exists only in the pool.
  • Set MATERIALS_POOL_BACKFILL=1 only after every old instance has stopped, then restart. Unset, older uploads stay where they are and are still read from there.
  • A host that provisions ASSET_PG_SCHEMA, AGENT_SESSION_PG_SCHEMA or AGENT_SESSION_MATERIAL_PG_SCHEMA through its own migrations must apply the schema additions listed under Material library upgrade reference below before upgrading; otherwise document writes, session reads and extraction fail on a missing table or column.
  • Without a registered byte store or ASSET_S3_BUCKET, knowledge-base originals are stored in PostgreSQL; plan database size and backups accordingly.

Highlights

• Knowledge base. Every successful upload, from the workbench or from classic generation, now belongs to its owner's knowledge base and stays there until it is deleted; existing undeleted uploads are included. Materials can be grouped into folders, each is parsed once and the result is shared by every conversation, and a library page shows usage and parsing status and lets owners rename, move and delete them. The composer's @ menu and @ button offer knowledge-base sources beside classrooms, and the agent can read, search and organize them (but not delete them). RFC: Discussion #1716, tracking: #1736. #1896 #1989
• Self-hosted interactive scene libraries. KaTeX, Three.js, Chart.js and the Tailwind browser runtime are served by the deployment, and public CDN URLs for them in new and stored scenes are mapped to the hosted copies, so interactive scenes no longer depend on a public CDN. #1972 #1971
• Course issue markers. The editor's page thumbnails now mark current problems in a course, such as missing narration, media that was never generated and cues that point at nothing, and a marker clears once its cause is fixed. This is the first phase of #1900. #1903 (by @Oliveryfaso)

Added

• Interactive scenes load KaTeX, Three.js, Chart.js and the Tailwind v4 browser runtime from the deployment (/vendor/interactive, configurable with the build-time INTERACTIVE_ASSET_BASE_URL) instead of a public CDN. KaTeX is injected only into pages that contain math, and loads ahead of the page's scripts as before. The interactive prompts list the hosted libraries, and public CDN URLs for them in generated or stored pages are rewritten to the hosted copies when a scene opens and before export; other URLs are left as written. @openmaic/generation 0.3.24. #1971

• Course generation passes each catalogue voice's gender into the voice list and asks the model to pick a voice whose gender matches the agent, keeping the agent's name and persona consistent with that gender. voiceDesign.gender (male or female) is part of the agent DSL, the export sanitizer, and set_roster, so a course-language identity can still drive the match. When the model's voice is missing or invalid, playback falls back by index within that gender. A catalogue with no male/female data, or an agent whose gender is unknown, keeps the previous full-list index pick. #1084 #1908 (by @Frank-zhu2000)

• Course issues: @openmaic/dsl 0.12.0 adds CourseIssue and collectCourseIssues, which derive a course's current problems from the document (missing narration, generated-media placeholders, dangling cues and the existing action-content lint) without changing the serialized format. Editor thumbnails show their markers from this one list. Missing narration is reported only when the workspace can generate narration on the server, and every issue is a warning in this phase. Thumbnail markers no longer flash while a page whose narration lives only in the browser's cache is edited. #1903 #1953 (by @Oliveryfaso)

• Speech: a provider in openmaic.yml can declare its own voices list and options.defaultVoice, for OpenAI-compatible TTS endpoints whose voices differ from the built-in OpenAI catalogue. The list feeds the voice picker and the catalogue generated agents choose from, and the default is used for browser and server narration when no voice was selected; an explicitly selected voice is still used. Providers without these settings behave as before. #1969 (by @xuyuanwei678)

• Course cards: a course that is generating shows the page in progress ("Generating 2/5" while page 2 is generated) instead of the number of finished pages, capped at the total. #1926 (by @Cham1229)

Bug Fixes

• Interactive scenes that load KaTeX themselves now get the platform's KaTeX too. Previously any page that mentioned KaTeX was skipped, so its math stayed raw when the page's own copy did not render it, and a page that called renderMathInElement after its copy failed to load stopped with a ReferenceError and showed the runtime-error notice. The platform's KaTeX now loads ahead of the page's scripts, its observer typesets labels the page fills in on load, and when the CDN is unreachable the page's math calls do nothing instead of throwing. The interactive prompts ask pages to leave math typesetting to the platform. @openmaic/generation 0.3.23. #1538

• Slides: malformed SVG paths and invalid shape geometry could hang the renderer or leave part of a slide missing. The new @openmaic/geometry package validates shapes where they are generated, edited or written by the agent; shapes already stored with invalid geometry are drawn as their text label (or left out when they have none) in playback, the editor, the whiteboard and PPTX export, without rewriting saved courses. Authored and generated shape labels get the same 10px inset in every renderer, while imported PPTX labels keep their own. #1915 (by @cosarah)

• Renderer: slides with many heavy inline formulas no longer block the page in one long task when they first appear, including on cached visits, while ordinary slides with many formulas still finish before their first paint. Formulas still waiting to be typeset stay hidden instead of showing raw LaTeX. #1930 #1962 (by @YizukiAme)

• Charts: short bar, column, line, area and scatter charts no longer collapse to an empty plot. Margins scale with the chart, axis labels stay inside it and the legend gets its own row, in the app and in @openmaic/renderer; plot areas from imported files are kept. #1973 (by @cosarah)

• Whiteboard: text and code on the whiteboard can be selected and copied; the rest of the canvas stays non-selectable. #1952 (by @bhushan4work)

• Export: after moving from a classroom with failed outlines to a completed one without reloading, Export stayed disabled until the page was reloaded. #1934 (by @VictorMaxWang)

• Web fetch: DeepSeek returns response headers only after it has fetched the whole page, but its reader gave up after 10 s, so slow pages failed with Web fetch headers timed out although DeepSeek completed (and billed) them. The header wait now uses the request deadline (bodyTimeoutMs, 30 s by default). #1990

• Media: the OpenRouter Video and ComfyUI adapters read the files a provider returns with a 200 MB limit, checked against the declared length and while streaming, instead of buffering a response of any size. #1933 (by @AbelWangYaBo)

Packages

• @openmaic/storage 0.38.0 (was 0.37.3), @openmaic/dsl 0.12.0 (was 0.11.3), @openmaic/generation 0.3.24 (was 0.3.21), @openmaic/renderer 0.2.0 (was 0.1.14), @openmaic/editor 0.0.12 (was 0.0.11), and the new @openmaic/geometry 0.1.0. @openmaic/importer is unchanged at 0.3.1.
• @openmaic/renderer 0.2.0 requires the optional peer echarts >=5.5; SDK consumers on ECharts 5.0–5.4 must upgrade it. ECharts is still needed only for slides with charts. #1973

Known issues

• Qwen voice cloning still calls a retired model, so registering or synthesizing a cloned voice fails. The move to CosyVoice is in review in #1949. #1941
• Course issues ship their first phase only: thumbnail markers, all at warning level. An issues list and a single "Fix with agent" entry point are planned in #1900.
• On deployments protected by ACCESS_CODE, the composer's attach button, drag-and-drop and image paste can stay unavailable after the access code is entered on a fresh page load, until the page is reloaded. A fix is in review in #1974.
• Volcengine Ark Agent Plan models report no image input, so reference images are dropped for them. #1942

Material library upgrade reference

The full list of storage, schema and API changes behind the knowledge base, for self-hosters and embedders, is in the CHANGELOG.