Monorch

Public API

The supported contract for @monorch/ai consumers. Anything not listed here is internal and may change without a major bump.

Entrypoints

@monorch/ai
Main control-plane API (agents, tools, graphs, events, MCP bridges, memory helpers). Full map: package reference.
@monorch/ai/openai
openai() and mock() providers. Also re-exported from the main entry for convenience.
@monorch/ai/postgres
ensureMonorchSchema, postgresCheckpointer, postgresThreads, postgresStore. Optional peer: pg.
@monorch/runtime
N-API binding. Install transitively via @monorch/ai. Do not call it from app code unless debugging.

Stable surface (pre-1.0 intent)

These symbols are the product. We will not rename or remove them casually before 1.0; after 1.0, removals require a major version.

Core

public-core.ts
import {
  agent, getAgent,
  tool, toolWithIr, callTool, listTools,
  graph, GRAPH_END,
  workflow,           // linear sugar — prefer graph()
  model,
  memorySaver,
  inMemoryStore, inMemoryThreads,
  createOtelListener, tapEvents, collectEvents,
  AiError,
  mock, openai,       // also from @monorch/ai/openai
} from "@monorch/ai";

MCP

public-mcp.ts
import {
  mcpStdio, mcpHttp, mcpTools, mockMcp, jsonSchemaToIr,
} from "@monorch/ai";

Postgres

public-postgres.ts
import {
  ensureMonorchSchema,
  postgresCheckpointer,
  postgresThreads,
  postgresStore,
} from "@monorch/ai/postgres";

Prefer graph()

workflow() is linear sugar over graph(). New code should use graph() for branching, cycles, interrupts, and checkpoints. See Workflows.

SemVer policy

Before 1.0 (0.x)
Minor versions may add APIs. Breaking changes to the public surface are allowed but will be called out in the changelog. Patch versions are fixes and docs.
At / after 1.0
Documented public exports keep backward compatibility within a major. Breaking changes require 2.0. Additive exports are fine in minors.
Types
Exported TypeScript types that appear in public function signatures are part of the contract. Narrowing types in a non-breaking way is allowed; removing fields is breaking.
AiError codes
String codes on AiError that are documented under Error codes are stable once listed. New codes may be added anytime.
Checkpoint blobs
On-disk / DB checkpoint shape is versioned (version field). Readers must tolerate documented versions; dropping a version is a major or an explicit migration guide.

Not public (do not depend on these)

getRuntime() / Engine methods
Escape hatch for the native addon. Shape follows Rust and may change without a major.
Module-private paths
Deep imports like @monorch/ai/dist/... or files not listed in package.json#exports are unsupported.
Undocumented helpers
Anything exported only for tests or examples without docs coverage is not a stability promise. Prefer the symbols on this page.
zodToIr
Exported for advanced IR use (for example MCP). Prefer tool() / toolWithIr() in app code. IR shape may evolve.
@monorch/runtime platform packages
@monorch/runtime-* packages are optional binaries. Depend on @monorch/ai / @monorch/runtime, not a single platform package, unless you know you need it.

Product lock (unchanged)

Monorch is a library, not an HTTP framework, ORM, Studio, or RAG product. The public API stays control-plane shaped: agents, tools, graphs, events, and thin adapters.

FAQ