Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aipoch/open-science/llms.txt

Use this file to discover all available pages before exploring further.

Open Science maintains a persistent Python kernel per session, enabling stateful multi-step analyses — variables, imports, and data all persist across agent turns. Each session runs its own isolated python3 interpreter process, launched on demand and kept alive as long as the session is active.

​
Kernel Lifecycle

1

Kernel starts on first use

The NotebookPythonExecutor spawns a python3 subprocess the first time a code cell is executed in the session. The subprocess hosts a lightweight stdin/stdout JSON bridge that keeps a single global namespace alive across all executions, so variables defined in one cell are available in later cells.
2

Agent streams code into a cell

The agent writes code using a three-step protocol: beginCodeCell acquires an exclusive write lock, appendCodeCell streams incremental code deltas into the cell, and finishCodeCell releases the lock. The notebook preview reflects each delta as it arrives.
3

runCell executes the code

runCell sends the completed cell code to the bridge over stdin as a newline-delimited JSON request. The bridge executes the code in the shared global namespace, capturing both file descriptors and subprocess writes, then returns stdout, stderr, and a traceback (if any) as a JSON response on stdout.
4

Results are written to run.json

The NotebookRunRecord produced by the execution is persisted in run.json for the session. The record includes the source code, status, timestamps, all outputs, and a list of any working files created during the run. The preview panel reloads the record to show live progress.
5

Artifacts are collected

Files written to the notebook session root or data root during execution are surfaced as artifacts in the conversation thread. Artifact tabs open in the preview panel when the agent or user clicks them.
6

Kernel can be restarted or shut down

restart shuts down the current interpreter process and creates a fresh one, clearing all in-memory state while preserving the persisted run history. shutdown terminates the process and removes the in-memory session routing entry.
The kernel is scoped per session. Restarting one session’s kernel does not affect any other session — each has its own subprocess and its own global namespace.

​
Kernel Status

The NotebookKernelMetadata.lastKnownStatus field reflects the current state of the interpreter:
StatusDescription
idleThe interpreter is ready and waiting for the next execution request
startingThe subprocess is being spawned for the first time
runningA cell is currently executing inside the bridge
errorThe interpreter encountered a fatal error or exited unexpectedly
shutdownThe interpreter has been explicitly shut down

​
NotebookRunRecord Fields

Every execution produces a NotebookRunRecord stored in run.json. The table below describes each field:
FieldTypeDescription
runIdstringUnique identifier for this run
cellIdstringThe ID of the cell that triggered this run
source'agent' | 'user'Whether the run was initiated by the agent or by the user terminal
inputKind'cell' | 'terminal'Distinguishes regular notebook cells from terminal submissions
scriptstringThe exact Python code that was executed
statusNotebookRunStatusThe terminal state of this run (see below)
startedAtnumberUnix timestamp (ms) when execution began
endedAtnumberUnix timestamp (ms) when execution completed
cwdBeforestringWorking directory at the start of execution
cwdAfterstringWorking directory after execution (may differ if the code called os.chdir)
executionCountnumberMonotonically increasing counter across all runs in the session
textNotebookTextOutputStructured capture of stdout, stderr, traceback, and a plain display array
outputsNotebookOutput[]Structured output objects (stream, error, text, json)
artifactsArtifactFile[]Files promoted to the artifact store during this run
workingFilesNotebookWorkingFile[]Intermediate files found in the working directory after execution
truncatedbooleanSet when the run record was trimmed due to output size

​
Run Status Values

NotebookRunStatus is one of: 
'queued' | 'running' | 'completed' | 'failed' | 'timeout' | 'interrupted'
When the kernel timeout is reached (default: 120 seconds), the interpreter process is killed and the run is marked timeout. Long-running computations — such as large model training loops — should be structured as multiple shorter cells or use an explicit timeoutMs override if needed.

​
run.json Structure

Each notebook session persists its full execution history in a run.json file at the path <storageRoot>/notebooks/<projectName>/<sessionId>/run.json. The document is a NotebookRunDocument with version: 1: 
type NotebookRunDocument = {
  version: 1
  projectName: string
  sessionId: string
  artifactSessionId?: string
  workspaceCwd: string
  notebookSessionRoot: string
  dataRoot: string
  kernel: NotebookKernelMetadata
  runs: NotebookRunRecord[]
  updatedAt: number
}
The kernel object stores interpreter metadata including the pythonPath, kernelName, runtimeRoot, and lastKnownStatus. The runs array is the ordered history of every execution in the session.

​
Working Files

Files created inside the notebook session workspace are tracked as NotebookWorkingFile entries. Each entry has a kind field from NotebookWorkingFileKind:
KindDescription
raw-dataOriginal input data files, not yet processed
processed-dataData that has been transformed or cleaned
cacheIntermediate computed results saved to speed up reruns
scriptHelper scripts written by the agent or user
intermediateTemporary computation outputs not intended as final results
otherAny file that doesn’t fit the above categories

​
NotebookOutput Types

Structured outputs returned by the interpreter bridge are typed as NotebookOutput:
TypeFieldsDescription
streamname: 'stdout' | 'stderr', textA line or block of standard output or error text
errorname?, message?, tracebackA Python exception with optional name, message, and full traceback
texttextPlain text output not associated with a specific stream
jsondataA rich structured object, such as a serialized DataFrame summary

​
Environment Variables

The bridge injects three environment variables into every execution so user code and helper scripts can locate workspace directories without hardcoding paths: 
OPEN_SCIENCE_NOTEBOOK_DIR        # notebookSessionRoot
OPEN_SCIENCE_NOTEBOOK_DATA_DIR   # dataRoot
OPEN_SCIENCE_RUNTIME_DIR         # runtimeRoot

Build docs developers (and LLMs) love

Get started for freeTalk to us