A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
/* Copyright 2026 Marimo. All rights reserved. */
/** What a backend's stream has confirmed about a notebook, kept in atoms. */
import { Logger } from "@/utils/Logger";
import {
createNotebookReducer,
type NotebookEvent,
NotebookEvents,
StreamStopped,
} from "@marimo-team/client";
import type { Attachment, NotebookOutput } from "@marimo-team/client/protocol";
import { type Atom, atom, type createStore } from "jotai/vanilla";
import { z } from "zod";
import type { NotebookBackend } from "./backend";
import {
ConnectionClosedReason,
ConnectionState,
type ConnectionStatus,
} from "./connection";
import { attachments } from "./resources/attachments";
import { type Document, document } from "./resources/document";
/** The kinds the editor reads, with marimo's own notifications. */
const TYPES = ["notebook", "cell", "document", "attachment", "marimo"] as const;
type EditorEvent = NotebookEvent<(typeof TYPES)[number]>;
/** A native marimo notification, passed through without interpretation. */
const MarimoMessage = z.object({ marimo: z.unknown() });
/** A notebook as its backend's stream reports it, kept current while connected. */
export interface NotebookReplica {
/** Connection status, independent of application session readiness. */
readonly connectionAtom: Atom<ConnectionStatus>;
/** Identity and capabilities, available while the stream is connected and ready. */
readonly notebookAtom: Atom<NotebookOutput | null>;
/**
* The most recently confirmed document.
*
* Null until a snapshot is complete, after reset or removal, and on
* connections without host document events. A temporary disconnection
* retains the last document. Partial updates are not exposed.
*/
readonly documentAtom: Atom<Document | null>;
/**
* The backend this replica follows, or null while not connected.
*
* Its commands reach the host that confirmed `documentAtom`. A temporary
* disconnection keeps it. Connecting again or disconnecting replaces it.
*/
readonly backendAtom: Atom<NotebookBackend | null>;
/** Live attachments, empty until the stream is ready or while disconnected. */
readonly attachmentsAtom: Atom<readonly Attachment[]>;
/**
* Follow a backend, replacing any current connection.
*
* The returned function ends this connection and clears the replica.
* It does nothing once another connection has replaced this one.
*/
connect(
backend: NotebookBackend,
options: {
/** Handle a native marimo notification. Its payload has not been validated. */
onNotification: (notification: unknown) => void;
},
): () => void;
/** Restore the current connection after its stream closed, if the host is healthy. */
reconnect(): Promise<void>;
}
const disconnected = {
state: ConnectionState.CLOSED,
code: ConnectionClosedReason.KERNEL_DISCONNECTED,
reason: "kernel not found",
} satisfies ConnectionStatus;
const malformed = {
...disconnected,
reason: "Failed to decode notebook message",
} satisfies ConnectionStatus;
function isStatus(value: unknown): value is ConnectionStatus {
return typeof value === "object" && value !== null && "state" in value;
}
/**
* The status to show after the stream stopped.
*
* A transport says which status its stop means. An event the protocol
* rejects is malformed. Anything else means the host was not reached.
*/
function statusAfter(error: unknown): ConnectionStatus {
if (error instanceof StreamStopped && isStatus(error.cause)) {
return error.cause;
}
if (error instanceof StreamStopped && error.cause instanceof z.ZodError) {
return malformed;
}
return disconnected;
}
/** Create a replica without connecting it. */
export function createNotebookReplica(
store: ReturnType<typeof createStore>,
): NotebookReplica {
// `useNotebookSession` copies this into the editor's shared `connectionAtom`,
// which gates features until MO-8051 derives availability separately.
const connectionAtom = atom<ConnectionStatus>({
state: ConnectionState.NOT_STARTED,
});
// One atom holds the whole stream, which resource atoms derive from.
const reducer = createNotebookReducer({ document, attachments });
const streamAtom = atom(reducer.initial);
// A resumed stream is live, but presence waits for this connection's ready.
const readyAtom = atom(false);
const presentAtom = atom(
(get) =>
get(readyAtom) && get(connectionAtom).state === ConnectionState.OPEN,
);
const notebookAtom = atom((get) =>
get(presentAtom) ? get(streamAtom).notebook : null,
);
const documentAtom = atom(
(get) => get(streamAtom).resources.document.current,
);
const attachmentsAtom = atom((get) =>
get(presentAtom)
? get(streamAtom).resources.attachments
: attachments.initial,
);
const backendAtom = atom<NotebookBackend | null>(null);
/** The connection this replica follows. Connecting again ends it. */
let current: { end(): void; reconnect(): Promise<void> } | undefined;
function setStatus(status: ConnectionStatus) {
store.set(readyAtom, false);
store.set(connectionAtom, status);
}
/** Drop what the stream reported and show `status`. */
function clear(status: ConnectionStatus) {
store.set(streamAtom, reducer.initial);
setStatus(status);
}
return {
connectionAtom,
notebookAtom,
documentAtom,
backendAtom,
attachmentsAtom,
connect,
reconnect: async () => current?.reconnect(),
};
function connect(
connected: NotebookBackend,
{ onNotification }: { onNotification: (notification: unknown) => void },
) {
current?.end();
const lifetime = new AbortController();
const { signal } = lifetime;
const checkHealth = connected.checkHealth ?? (async () => true);
store.set(backendAtom, connected);
const { transport } = connected;
let events: NotebookEvents<(typeof TYPES)[number]> | undefined;
let checkingHealth = false;
// Whether the replica still holds the state the last cursor describes.
let resumable = true;
/** Mirror one stream into the atoms until it closes. */
function follow(cursor?: string) {
if (cursor === undefined) {
store.set(streamAtom, reducer.initial);
}
resumable = true;
const current = new NotebookEvents(transport, {
types: TYPES,
cursor,
signal,
// TODO(MO-8051): Gate editing and running on the notebook's operations
// and request results instead. The stream's status would then only
// mark the view as stale.
onStatus: (status) => {
if (status === "connecting") {
setStatus({ state: ConnectionState.CONNECTING });
} else if (status === "connected") {
setStatus({ state: ConnectionState.OPEN });
}
},
});
current.subscribe(
(event) => apply(current, event),
(error) => {
if (!signal.aborted && current === events) {
Logger.warn("Notebook stream stopped", error);
const status = statusAfter(error);
if (status === malformed) {
stopMalformed(current);
} else {
setStatus(status);
}
}
},
);
events = current;
}
function stopMalformed(source: NotebookEvents<string>) {
source.close();
// The cursor can already include an event the replica rejected.
resumable = false;
clear(malformed);
}
function apply(source: NotebookEvents<string>, event: EditorEvent) {
if (event.event === "marimo") {
const message = MarimoMessage.safeParse(event.data);
if (message.success) {
onNotification(message.data.marimo);
} else {
Logger.error("Failed to decode notebook message", event);
stopMalformed(source);
}
return;
}
try {
store.set(streamAtom, reducer.reduce(store.get(streamAtom), event));
} catch (error) {
// An event the replica cannot apply, such as another notebook's.
Logger.error("Failed to apply notebook event", error);
stopMalformed(source);
return;
}
if (event.event === "ready" || event.event === "reset") {
store.set(readyAtom, event.event === "ready");
}
}
const reconnect = async () => {
if (signal.aborted || checkingHealth || events?.status !== "closed") {
return;
}
checkingHealth = true;
setStatus({ state: ConnectionState.CONNECTING });
try {
const healthy = await checkHealth();
if (signal.aborted) {
return;
}
if (!healthy) {
setStatus(disconnected);
return;
}
follow(resumable ? (events.cursor ?? undefined) : undefined);
} catch (error) {
if (!signal.aborted) {
Logger.error("Notebook health check failed", error);
setStatus(disconnected);
}
} finally {
checkingHealth = false;
}
};
const connection = {
end: () => {
if (signal.aborted) {
return;
}
lifetime.abort();
if (current === connection) {
current = undefined;
store.set(backendAtom, null);
}
clear({ state: ConnectionState.NOT_STARTED });
},
reconnect,
};
current = connection;
setStatus({ state: ConnectionState.CONNECTING });
follow();
return connection.end;
}
}