:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { z } from 'zod'
import type { Schemas } from '@/api/generated'
import type { Context, ToolBase } from '@/tools/types'
import { wrapRunResultAsInformational } from './cellRuns'
import { notebookPathFor } from './markdownDoc'
import { NOTEBOOK_SHORT_ID_DESCRIPTION, notebookIdAliases } from './notebookId'
import { awaitNotebookRun, type NotebookRunOutcome } from './notebookRuns'
import { MAX_NOTEBOOK_VARIABLES, NotebookVariableSchema } from './notebookVariableSchema'
const RunNotebookInputSchema = z
.object({
notebook_id: z.string().describe(NOTEBOOK_SHORT_ID_DESCRIPTION),
variables: z
.array(NotebookVariableSchema)
.max(MAX_NOTEBOOK_VARIABLES)
.optional()
.describe(
`Set the notebook's variables before the run, in one call. This replaces the whole list, so include every variable you want to keep, and the notebook stores what you pass. Omit it to run with the variables already saved. At most ${MAX_NOTEBOOK_VARIABLES}.`
),
wait: z
.boolean()
.optional()
.default(true)
.describe(
'Wait for the run and write each result into the document as it lands. Set false to start the run and return immediately, then follow with notebooks-run-status.'
),
})
.strict()
export const NotebooksRunSchema = z.preprocess(notebookIdAliases('notebook_id'), RunNotebookInputSchema)
export const runNotebookHandler: ToolBase<typeof NotebooksRunSchema, NotebookRunOutcome>['handler'] = async (
context: Context,
params: z.infer<typeof NotebooksRunSchema>
) => {
const projectId = await context.stateManager.getProjectId()
const notebookPath = notebookPathFor(projectId, params.notebook_id)
const started = await context.api.request<Schemas.NotebookRunStartResponse>({
method: 'POST',
path: `${notebookPath}runs/`,
body: params.variables ? { variables: params.variables } : {},
})
const disclosure = {
starts_sandbox: started.starts_sandbox,
sandbox_hourly_price: started.sandbox_hourly_price ?? null,
}
if (params.wait === false) {
return wrapRunResultAsInformational({
run_id: started.run_id,
status: 'running',
cell_count: started.cell_count,
completed_count: 0,
cells: [],
...disclosure,
hint: 'The notebook is running. Call notebooks-run-status with this run_id to read the results and write them into the document.',
})
}
try {
const outcome = await awaitNotebookRun(context, params.notebook_id, notebookPath, started.run_id)
return wrapRunResultAsInformational({ ...outcome, ...disclosure })
} catch (error) {
// The run started, and the cells may well be executing. Only following it failed —
// a save that lost every attempt to an active editor, say. Raising bare would take
// the run id with it, and the caller needs that id: the status tool asks for it, and
// starting over either collides with this run or repeats it once it finishes.
return wrapRunResultAsInformational({
run_id: started.run_id,
status: 'running',
cell_count: started.cell_count,
completed_count: 0,
cells: [],
...disclosure,
hint: `The run started, but following it failed (${error instanceof Error ? error.message : String(error)}). Call notebooks-run-status with this run_id to read the results and write them into the document.`,
})
}
}
const tool = (): ToolBase<typeof NotebooksRunSchema, NotebookRunOutcome> => ({
name: 'notebooks-run',
schema: NotebooksRunSchema,
handler: runNotebookHandler,
})
export default tool