: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
from datetime import datetime
from typing import Any
from django.db import models
from drf_spectacular.utils import extend_schema_field
from rest_framework import serializers
from products.notebooks.backend.sql_v2_variables import RESERVED_VARIABLE_NAMES
@extend_schema_field(serializers.DictField(child=serializers.FloatField()))
class LenientTimingsField(serializers.JSONField):
"""`timings` documented as a str->float map but never validated as one.
The envelope is produced inside the sandbox, where user code can forge it, and the
callback is fire-and-forget — a 400 here is swallowed like a network error and the
run is stranded RUNNING forever. So a bad timings shape must never fail the envelope;
`sql_v2_metrics._sanitized_timings` is the sole validator and drops bad keys.
"""
class NotebookSQLV2RefKind(models.TextChoices):
HOGQL = "hogql", "hogql"
LOCAL = "local", "local"
class NotebookSQLV2RefSerializer(serializers.Serializer):
node_id = serializers.CharField(help_text="ProseMirror node id of the upstream node this name points at.")
# Named `kind` on purpose (matches the kernel input spec); avoids the `type`/`format`
# enum-collision trap.
kind = serializers.ChoiceField(
choices=NotebookSQLV2RefKind.choices,
required=False,
default="hogql",
help_text=(
"What the name resolves to: 'hogql' is a SQL node's query definition (resolved to its "
"last-run HogQL); 'local' is a dataframe a Python node bound in the kernel namespace."
),
)
# A notebook is authored by hand, so these sit just above real use: a person types a handful
# of named values, not a data set. Keeping them tight also bounds the abuse case — values ride
# a Temporal payload (~2 MiB hard limit) to the kernel, and one placeholder repeated across a
# query multiplies its value into the SQL the engine receives.
MAX_VARIABLES_PER_NOTEBOOK = 10
MAX_VARIABLE_NAME_CHARS = 200
MAX_VARIABLE_VALUE_CHARS = 1_000
def _is_absolute_date(value: Any) -> bool:
if not isinstance(value, str):
return False
try:
datetime.fromisoformat(value.strip())
except ValueError:
return False
return True
class NotebookVariableSerializer(serializers.Serializer):
"""One notebook-level variable. Shared by the notebook's own `variables` field and a run body."""
name = serializers.CharField(
max_length=MAX_VARIABLE_NAME_CHARS,
help_text="Identifier the cell reads: `{name}` in a SQL cell, a plain global in a Python cell.",
)
# CharField, not ChoiceField: a `type` enum collides with other generated enums under
# --fail-on-warn (same precedent as the status fields below).
type = serializers.CharField(
help_text="How to coerce the value: 'string', 'number', 'boolean', or 'date'. Unknown types read as 'string'."
)
value = serializers.JSONField(
required=False,
allow_null=True,
help_text=(
"The variable's current value. A 'date' is an absolute date or datetime in ISO 8601 form "
"('2025-01-31', '2025-01-31T09:00:00Z'); relative expressions such as '-7d' are rejected."
),
)
def validate_value(self, value: Any) -> Any:
if value is None:
return value
# Only scalars are ever bound. A dict or a list binds as its Python repr, which the
# state endpoint prints again for every cell that reads the name.
if not isinstance(value, str | int | float | bool):
raise serializers.ValidationError("Use a string, a number, a boolean, or null.")
# The printed form is what a run and a state read carry, so bound that rather than the
# string alone. A long number reaches the engine the same way a long string does.
if len(str(value)) > MAX_VARIABLE_VALUE_CHARS:
raise serializers.ValidationError(f"A variable value can be at most {MAX_VARIABLE_VALUE_CHARS} characters.")
return value
def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
# The editor's date picker only writes absolute dates, and a relative one would re-resolve
# against the clock on every read, so a cell reading it could never compare equal to the
# value its last run bound.
value = attrs.get("value")
if attrs.get("type") == "date" and value is not None and not _is_absolute_date(value):
raise serializers.ValidationError({"value": "Use an absolute date, like 2025-01-31."})
return attrs
def validate_name(self, value: str) -> str:
name = value.strip()
# A SQL cell reads the name as a `{name}` placeholder and a Python cell as a global, so
# only a plain identifier can ever resolve.
if not name.isidentifier():
raise serializers.ValidationError("Use letters, numbers, and underscores, and don't start with a number.")
if name in RESERVED_VARIABLE_NAMES:
raise serializers.ValidationError(f"'{name}' is reserved by PostHog. Pick another name.")
return name
class NotebookSQLV2NodeType(models.TextChoices):
HOGQL = "hogql", "hogql"
PYTHON = "python", "python"
class NotebookSQLV2RunRequestSerializer(serializers.Serializer):
reuse_results = serializers.BooleanField(
required=False,
default=False,
help_text="Reuse the requesting user's running or completed HogQL run with the same cell and resolved query from the last hour. Does not apply to token-only callers, kernel runs, or connection runs.",
)
node_id = serializers.CharField(help_text="ProseMirror node id of the SQLV2 node being run.")
node_type = serializers.ChoiceField(
choices=NotebookSQLV2NodeType.choices,
required=False,
default="hogql",
help_text=(
"Execution kind. 'hogql' is a SQL node — pushed to ClickHouse, or rerouted to the sandbox's "
"DuckDB when it references a local frame; 'python' runs the code in the sandbox kernel, "
"materializing referenced upstream nodes as pandas frames first."
),
)
code = serializers.CharField(
help_text="The node's source — SQL for a hogql node, Python for a python node. Must not be blank.",
)
output_name = serializers.CharField(
required=False,
default="",
allow_blank=True,
help_text=(
"Kernel nodes only: the dataframe variable to bind the result to in the kernel namespace "
"(a python node falls back to the last expression for its preview)."
),
)
refs = serializers.DictField(
child=NotebookSQLV2RefSerializer(),
required=False,
default=dict,
help_text=(
"Available upstream nodes, keyed by dataframe name. A SQL node inlines referenced hogql "
"refs as CTEs — unless it references a local ref, which reroutes the run to the sandbox's "
"DuckDB; a python node materializes the hogql refs its code reads as pandas frames."
),
)
variables = NotebookVariableSerializer(
many=True,
required=False,
default=list,
# DRF forwards this to the ListSerializer (LIST_SERIALIZER_KWARGS); the stubs only
# type Serializer.__init__, so mypy cannot see it.
max_length=MAX_VARIABLES_PER_NOTEBOOK, # type: ignore[call-arg]
help_text=(
"Notebook-level variables in scope for this run. A SQL node has each `{name}` bound to "
"its value before dispatch; a Python node gets them as globals in the kernel namespace. "
"A SQL node reading a `{name}` that is absent here fails the dispatch."
),
)
connection_id = serializers.UUIDField(
required=False,
allow_null=True,
default=None,
help_text=(
"SQL nodes only: id of a direct-query-capable external data source to run against "
"instead of PostHog's ClickHouse. Omit to query PostHog."
),
)
send_raw_query = serializers.BooleanField(
required=False,
default=False,
help_text=(
"Send the code to the selected connection verbatim instead of compiling it from HogQL "
"first. Ignored without connection_id, and incompatible with references to other cells."
),
)
class NotebookSQLV2PageRequestSerializer(serializers.Serializer):
offset = serializers.IntegerField(
required=False,
default=0,
min_value=0,
help_text="Number of rows to skip; pages re-query ClickHouse with LIMIT/OFFSET.",
)
limit = serializers.IntegerField(
required=False,
default=50,
min_value=1,
max_value=500,
help_text="Rows per page.",
)
class NotebookSQLV2DataPlaneRequestSerializer(serializers.Serializer):
query = serializers.CharField(help_text="HogQL SELECT to execute against the notebook team's data.")
limit = serializers.IntegerField(
required=False,
default=50,
min_value=1,
# Must admit the kernel executor's full-frame materialize cap (_MATERIALIZE_ROW_CAP);
# the HogQL printer clamps explicit LIMITs to MAX_SELECT_RETURNED_ROWS regardless.
max_value=2_000_000,
help_text="Maximum number of rows to return (applied as an outer LIMIT, clamped by HogQL's row ceiling).",
)
offset = serializers.IntegerField(
required=False,
default=0,
min_value=0,
help_text="Number of rows to skip (applied as an outer OFFSET), for paging.",
)
delivery = serializers.ChoiceField(
choices=["inline", "object"],
required=False,
default="inline",
help_text=(
"How the caller wants the result delivered. 'inline' (default) returns rows in the "
"poll response body as an Arrow IPC stream — right for pages and envelope fetches. "
"'object' streams the result to object storage and answers the poll with a 302 to a "
"short-lived presigned download URL — for whole-frame materializations; falls back "
"to 'inline' (clamped at the async row ceiling) when the frame store is unavailable."
),
)
class NotebookSQLV2MediaSerializer(serializers.Serializer):
mime_type = serializers.CharField(help_text="MIME type of the media, e.g. 'image/png' for a matplotlib figure.")
# The kernel sends this key as `data`; the field name collides with DRF's `.data` property at
# the type level only (fields live in a dict at runtime), so the ignore is safe.
data = serializers.CharField(help_text="Base64-encoded media bytes.") # type: ignore[assignment]
class NotebookSQLV2FrameSerializer(serializers.Serializer):
name = serializers.CharField(help_text="Name a SQL node can SELECT from.")
# CharField, not ChoiceField: a `kind` enum collides with other generated enums under
# --fail-on-warn, and `status` above sets the same precedent.
kind = serializers.CharField(
help_text=(
"Where the object came from: 'frame' (a dataframe a node produced), "
"or 'table'/'view' (created by SQL DDL in a DuckDB node)."
)
)
columns = serializers.ListField(
child=serializers.ListField(child=serializers.CharField(), help_text="A [column name, DuckDB type] pair."),
required=False,
default=list,
help_text="DuckDB type per column, as [name, type] pairs.",
)
row_count = serializers.IntegerField(
required=False,
allow_null=True,
help_text="Rows available, or null when counting would require a table scan (a DDL view).",
)
row_count_is_estimate = serializers.BooleanField(
required=False,
default=False,
help_text=(
"True when row_count is DuckDB's optimizer estimate rather than a count. The estimate "
"does not track deletes, so it must never be presented as exact."
),
)
class NotebookSQLV2EnvelopeSerializer(serializers.Serializer):
status = serializers.CharField(help_text="Run outcome: 'ok', 'error', or 'interrupted' (user-requested stop).")
frames = NotebookSQLV2FrameSerializer(
many=True,
required=False,
default=list,
help_text=(
"DuckDB objects a SQL node can SELECT from as of this run, for the schema browser. "
"Only kernel runs (python/duckdb) report these; a hogql run never enters the kernel."
),
)
stdout = serializers.CharField(
required=False,
default="",
allow_blank=True,
help_text="Captured stdout from a Python node run.",
)
stderr = serializers.CharField(
required=False,
default="",
allow_blank=True,
help_text="Captured stderr (including tracebacks) from a Python node run.",
)
media = NotebookSQLV2MediaSerializer(
many=True,
required=False,
default=list,
help_text="Rich outputs from a Python node run, e.g. matplotlib figures as PNGs.",
)
result_text = serializers.CharField(
required=False,
allow_blank=True,
help_text=(
"The plain-text form of a Python node's last expression, as Jupyter shows it under Out[n]. "
"Absent when the cell ends in a statement, a None value, a semicolon, or a dataframe."
),
)
columns = serializers.ListField(
child=serializers.CharField(),
required=False,
default=list,
help_text="Result column names.",
)
types = serializers.ListField(
child=serializers.ListField(child=serializers.CharField(), help_text="A [column name, ClickHouse type] pair."),
required=False,
default=list,
help_text="ClickHouse type per column, as [name, type] pairs; used by the visualization tab.",
)
row_count = serializers.IntegerField(required=False, default=0, help_text="Number of rows in the result.")
has_more = serializers.BooleanField(
required=False,
default=False,
help_text="Whether ClickHouse has more rows beyond first_page (detected by fetching limit+1).",
)
first_page = serializers.ListField(
child=serializers.ListField(help_text="A single result row as a list of cell values."),
required=False,
default=list,
help_text="First page of result rows for display; each row is a list of cell values.",
)
result_id = serializers.UUIDField(
required=False,
allow_null=True,
help_text="Identifier of the materialized result, used as the paging key.",
)
error = serializers.CharField(
required=False,
allow_null=True,
allow_blank=True,
help_text="Error message when status is 'error'.",
)
timings = LenientTimingsField(
required=False,
help_text=(
"Phase durations in seconds. From the sandbox: input_wait_s (waiting on the data "
"plane), download_s (presigned frame downloads), kernel_boot_s (ensuring the "
"ipykernel is up), exec_s (kernel cell execution), sandbox_total_s (the whole "
"sandbox-side run). From the direct lane: queued_s (enqueue to Celery pickup), "
"clickhouse_s (pickup to completion). Feeds the node-run metrics."
),
)
class NotebookSQLV2CallbackRequestSerializer(serializers.Serializer):
envelope = NotebookSQLV2EnvelopeSerializer(help_text="The result envelope produced by the sandbox run.")
class NotebookSQLV2RunResponseSerializer(serializers.Serializer):
run_id = serializers.UUIDField(
help_text="Identifier of the dispatched run. Poll the run result endpoint with it until the status is terminal."
)
starts_sandbox = serializers.BooleanField(
help_text=(
"True when this run has to provision a sandbox because none is live for the caller, checked here "
"rather than inferred from a client's cached kernel status. Tell the user what that costs."
)
)
sandbox_hourly_price = serializers.FloatField(
required=False,
allow_null=True,
help_text=(
"What the sandbox this run provisions costs per hour in USD. Null when the run needs no new "
"sandbox, or when the backend is not charged."
),
)
class NotebookSQLV2RunStatusResponseSerializer(serializers.Serializer):
# CharField, not ChoiceField: a `status` enum collides with other generated enums under
# --fail-on-warn (same precedent as the envelope's status field).
status = serializers.CharField(
help_text="Run state: 'running' (keep polling), or terminal — 'done', 'failed', or 'interrupted'."
)
result = NotebookSQLV2EnvelopeSerializer(
required=False,
allow_null=True,
help_text=(
"The result envelope once the run is 'done' or 'interrupted' (an interrupted run keeps the "
"stdout/stderr captured before the stop); null while running and for failed runs."
),
)
error = serializers.CharField(
required=False,
allow_null=True,
help_text=(
"Why the run failed when it never produced an envelope (dispatch or watchdog failure); "
"execution errors arrive inside the envelope's error field instead."
),
)
rows = serializers.ListField(
child=serializers.ListField(help_text="A single result row as a list of cell values."),
required=False,
help_text=(
"SQL (hogql) runs only: the full capped row set for client-side paging, present while the "
"query manager's transient result is alive (~20 minutes). Absent afterwards and for kernel "
"(python/duckdb) runs, which keep only the envelope's first_page preview."
),
)
class NotebookCellLastRunSerializer(serializers.Serializer):
run_id = serializers.UUIDField(help_text="Identifier of the cell's most recent run.")
# CharField, not ChoiceField: a `status` enum collides with other generated enums.
status = serializers.CharField(help_text="The run's own state: 'running', 'done', 'failed', or 'interrupted'.")
finished_at = serializers.DateTimeField(help_text="When the run last changed state.")
row_count = serializers.IntegerField(
required=False, allow_null=True, help_text="Rows in the result, when the run produced one."
)
columns = serializers.ListField(
child=serializers.CharField(), required=False, allow_null=True, help_text="Result column names."
)
error = serializers.CharField(required=False, allow_null=True, help_text="Error message when the run failed.")
class NotebookCellVisualizationSerializer(serializers.Serializer):
display = serializers.CharField(
help_text="Chart type the cell opens on, a chart display value such as 'ActionsBar' or 'ActionsLineGraph'."
)
x_axis = serializers.CharField(
allow_null=True,
help_text=(
"Column on the X axis. Null means the chart picks it: the first date column, or the first column the Y "
"series do not use when there is no date column."
),
)
y_axis = serializers.ListField(
child=serializers.CharField(),
allow_null=True,
help_text=(
"Columns plotted as Y series. Null means the chart picks them: every numeric column. An empty list "
"means the author removed every series, so the chart plots nothing."
),
)
series_breakdown = serializers.CharField(
allow_null=True,
help_text="Column that splits the Y series into one series per value, or null.",
)
class NotebookCellStateSerializer(serializers.Serializer):
node_id = serializers.CharField(help_text="Durable cell identity, used by the cell run and edit endpoints.")
cell_type = serializers.CharField(
help_text=(
"Cell kind: 'sql', 'python', 'saved_insight' (an insight with an optional prepared dataframe), or "
"'markdown' (prose, a heading, or a fenced block; never runs and joins no dependency graph)."
)
)
dataframe_name = serializers.CharField(
allow_blank=True,
help_text="Name other cells reference this cell's result by; blank means display-only.",
)
code = serializers.CharField(
allow_blank=True,
help_text=(
"The cell's source, truncated with a marker past 8KB. For a markdown cell this is the block's markdown."
),
)
start = serializers.IntegerField(
help_text=(
"Offset where the cell's source starts in the notebook's markdown, in UTF-16 code "
"units, the same unit the collaboration diffs use."
)
)
end = serializers.IntegerField(
help_text=(
"Offset just past the cell's source, in UTF-16 code units, excluding the blank lines "
"that separate it from the next cell."
)
)
status = serializers.CharField(
help_text=(
"Derived cell state: 'never_run', 'running', 'done', 'failed', 'interrupted', or 'stale' — "
"stale means re-running now would execute different code than the last completed run "
"(the cell or an upstream dependency changed)."
)
)
depends_on = serializers.ListField(
child=serializers.CharField(),
help_text="node_ids of cells whose dataframes this cell's code references.",
)
dependents = serializers.ListField(
child=serializers.CharField(),
help_text="node_ids of cells that reference this cell's dataframe.",
)
last_run = NotebookCellLastRunSerializer(
required=False, allow_null=True, help_text="Summary of the most recent run; null when never run."
)
visualization = NotebookCellVisualizationSerializer(
required=False,
allow_null=True,
help_text=(
"SQL cells only: the chart the cell opens on, set in the editor or with the visualization parameter of "
"notebooks-add-cell. Null when the cell opens on its results table."
),
)
class NotebookKernelStateSerializer(serializers.Serializer):
# CharField for the same enum-collision reason as run status fields.
status = serializers.CharField(
help_text="Kernel runtime state: 'starting', 'running', 'stopped', 'timed_out', 'discarded', or 'error'."
)
cpu_cores = serializers.FloatField(
required=False, allow_null=True, help_text="CPU cores the notebook's sandbox is configured with."
)
memory_gb = serializers.FloatField(
required=False, allow_null=True, help_text="Memory in GB the notebook's sandbox is configured with."
)
idle_timeout_seconds = serializers.IntegerField(
required=False,
allow_null=True,
help_text="Maximum lifetime of the sandbox in seconds. It shuts down this long after it starts, even while in use.",
)
class NotebookSQLV2StateResponseSerializer(serializers.Serializer):
notebook_id = serializers.CharField(help_text="The notebook's short id.")
title = serializers.CharField(allow_null=True, help_text="The notebook's title.")
version = serializers.IntegerField(
allow_null=True, help_text="Document version, the optimistic-concurrency baseline for edits."
)
markdown = serializers.CharField(
allow_null=True,
help_text=(
"The full markdown source — prose and cell tags. Null for legacy rich-text notebooks, "
"which carry their document in `content` instead."
),
)
content = serializers.JSONField(
required=False,
allow_null=True,
help_text=(
"Legacy rich-text notebooks only: the raw ProseMirror document. Omitted for markdown "
"notebooks — their document is the `markdown` field."
),
)
kernel = NotebookKernelStateSerializer(help_text="The notebook's kernel runtime state and compute config.")
variables = NotebookVariableSerializer(
many=True,
help_text=(
"The notebook's declared variables, in display order. A SQL cell reads one as a `{name}` "
"placeholder and a Python cell as a global; a cell that reads an undeclared name fails to run."
),
)
cells = NotebookCellStateSerializer(
many=True,
help_text="Every cell in document order, with its dependency edges and derived run state.",
)
class NotebookKernelStatusResponseSerializer(serializers.Serializer):
backend = serializers.CharField(
required=False, allow_null=True, help_text="Sandbox backend the kernel runs on: 'modal' or 'docker'."
)
# CharField for the enum-collision reason above.
status = serializers.CharField(
help_text="Live-checked kernel state: 'starting', 'running', 'stopped', 'timed_out', 'discarded', or 'error'."
)
last_used_at = serializers.DateTimeField(
required=False, allow_null=True, help_text="When the kernel last executed anything."
)
last_error = serializers.CharField(
required=False, allow_null=True, help_text="Most recent provisioning or runtime error, if any."
)
runtime_id = serializers.UUIDField(required=False, allow_null=True, help_text="Kernel runtime row identifier.")
kernel_id = serializers.CharField(required=False, allow_null=True, help_text="Jupyter kernel identifier.")
kernel_pid = serializers.IntegerField(
required=False, allow_null=True, help_text="Kernel process id inside the sandbox."
)
sandbox_id = serializers.CharField(required=False, allow_null=True, help_text="Sandbox container identifier.")
frames = NotebookSQLV2FrameSerializer(
many=True,
help_text=(
"Dataframes and DuckDB tables a cell can currently reference, with column names and types. "
"Empty unless the kernel is running and the caller has query access."
),
)
cpu_cores = serializers.FloatField(help_text="CPU cores the sandbox is configured with.")
memory_gb = serializers.FloatField(help_text="Memory in GB the sandbox is configured with.")
disk_size_gb = serializers.FloatField(
required=False, allow_null=True, help_text="Disk size in GB the sandbox is configured with."
)
idle_timeout_seconds = serializers.IntegerField(
required=False,
allow_null=True,
help_text="Maximum lifetime of the sandbox in seconds. It shuts down this long after it starts, even while in use.",
)
hourly_price = serializers.FloatField(
help_text=(
"What this sandbox shape costs per hour in USD while it is alive, at this region's rates. "
"Charged on the sandbox's lifetime, not on how much of it a cell uses. Resizing through the "
"kernel config endpoint restarts a live kernel, so this tracks the running sandbox."
)
)
preset_key = serializers.CharField(
required=False,
allow_null=True,
help_text=(
"Compute preset for the shape hourly_price describes: the running sandbox while a kernel is "
"live, otherwise the configured shape. Null when that shape was tuned by hand and matches no preset."
),
)
class NotebookComputePresetSerializer(serializers.Serializer):
key = serializers.CharField(help_text="Stable identifier for the preset, e.g. 'balanced'.")
name = serializers.CharField(help_text="Preset name as a person reads it, e.g. 'Balanced'.")
description = serializers.CharField(help_text="What this preset suits, in one sentence.")
cpu_cores = serializers.FloatField(help_text="CPU cores the preset provisions.")
memory_gb = serializers.FloatField(help_text="Memory in GB the preset provisions.")
hourly_price = serializers.FloatField(help_text="What this preset costs per hour in USD while it is alive.")
class NotebookComputeOptionsResponseSerializer(serializers.Serializer):
currency = serializers.CharField(help_text="Currency of every price in this response. Always 'USD'.")
cpu_rate_per_core_hour = serializers.FloatField(help_text="Price of one CPU core for one hour, in USD.")
memory_rate_per_gb_hour = serializers.FloatField(help_text="Price of one GB of memory for one hour, in USD.")
default_preset_key = serializers.CharField(
help_text="Preset a sandbox starts with when the notebook sets no compute config."
)
presets = NotebookComputePresetSerializer(many=True, help_text="Sandbox shapes offered as one-click options.")
allowed_cpu_cores = serializers.ListField(
child=serializers.FloatField(), help_text="CPU core counts the kernel config endpoint accepts."
)
allowed_memory_gb = serializers.ListField(
child=serializers.FloatField(), help_text="Memory sizes in GB the kernel config endpoint accepts."
)
allowed_idle_timeout_seconds = serializers.ListField(
child=serializers.IntegerField(),
help_text="Maximum sandbox lifetimes in seconds that the kernel config endpoint accepts.",
)
class NotebookKernelConfigResponseSerializer(serializers.Serializer):
cpu_cores = serializers.FloatField(
required=False, allow_null=True, help_text="Configured CPU cores; null means the default applies."
)
memory_gb = serializers.FloatField(
required=False, allow_null=True, help_text="Configured memory in GB; null means the default applies."
)
idle_timeout_seconds = serializers.IntegerField(
required=False,
allow_null=True,
help_text="Configured maximum sandbox lifetime in seconds; null means the default.",
)
restarted = serializers.BooleanField(
help_text=(
"True when this call restarted a live kernel to apply a new size. Restarting discards every "
"materialized dataframe, so cells that referenced one must run again."
)
)
restart_required = serializers.BooleanField(
help_text=(
"True when a kernel is live and this call did not restart it, so the running sandbox may not "
"match the saved config. A resize restarts the kernel and reports False on success, or True if "
"that restart fails. An idle-timeout change and a no-op on a live kernel also report True."
)
)
hourly_price = serializers.FloatField(
help_text=(
"What this sandbox shape costs per hour in USD while it is alive, at this region's rates. It "
"tracks the running sandbox while a kernel is live, otherwise the configured shape. After a "
"failed resize this stays the running sandbox's rate, not the size that failed to apply."
)
)
preset_key = serializers.CharField(
required=False,
allow_null=True,
help_text="Compute preset the configured shape matches, or null when it was tuned by hand.",
)
class NotebookSQLV2InterruptResponseSerializer(serializers.Serializer):
# CharField for the same enum-collision reason as above.
status = serializers.CharField(
help_text=(
"The run's status after the interrupt request. Already-terminal runs return their outcome "
"unchanged (idempotent noop); a stopped kernel run reports its terminal state through the "
"normal result poll."
)
)
detail = serializers.CharField(
required=False,
help_text="Present when the interrupt could not take effect yet, e.g. the run has not reached the kernel.",
)
class NotebookRunStartRequestSerializer(serializers.Serializer):
include_prepared_insights = serializers.BooleanField(
required=False,
default=False,
help_text="Include prepared embedded insights when refreshing a dashboard widget.",
)
variables = NotebookVariableSerializer(
many=True,
required=False,
# DRF forwards this to the ListSerializer (LIST_SERIALIZER_KWARGS); the stubs only
# type Serializer.__init__, so mypy cannot see it.
max_length=MAX_VARIABLES_PER_NOTEBOOK, # type: ignore[call-arg]
help_text=(
"Replace the notebook's variables with this list before the run starts, so the results "
"match what the document declares. Omit it to run with the variables already saved."
),
)
class NotebookRunStartResponseSerializer(serializers.Serializer):
run_id = serializers.UUIDField(
help_text="Identifier of the whole-notebook run. Poll the run status endpoint with it until the status is terminal."
)
cell_count = serializers.IntegerField(help_text="How many cells the run will execute, frozen when it started.")
starts_sandbox = serializers.BooleanField(
help_text=(
"True when this run has to provision a sandbox because it holds a Python cell and none is "
"live for the caller. Tell the user what that costs."
)
)
sandbox_hourly_price = serializers.FloatField(
required=False,
allow_null=True,
help_text=(
"What the sandbox this run provisions costs per hour in USD. Null when the run needs no new "
"sandbox, or when the backend is not charged."
),
)
class NotebookRunCellSerializer(serializers.Serializer):
node_id = serializers.CharField(help_text="Durable cell identity, the same id the cell run endpoints take.")
cell_type = serializers.CharField(help_text="Cell kind: 'sql' or 'python'.")
dataframe_name = serializers.CharField(
allow_blank=True, help_text="Name other cells reference this cell's result by; blank means display-only."
)
run_id = serializers.UUIDField(
required=False,
allow_null=True,
help_text="This cell's run in the whole-notebook run; null until the run reaches the cell.",
)
# CharField, not ChoiceField: a `status` enum collides with other generated enums.
status = serializers.CharField(
required=False,
allow_null=True,
help_text="The cell's own state: 'running', 'done', 'failed', or 'interrupted'; null before it starts.",
)
error = serializers.CharField(required=False, allow_null=True, help_text="Why this cell failed, when it did.")
class NotebookRunStatusResponseSerializer(serializers.Serializer):
run_id = serializers.UUIDField(help_text="Identifier of the whole-notebook run.")
status = serializers.CharField(
help_text="Run state: 'running' (keep polling), or terminal — 'done', 'failed', or 'interrupted'."
)
trigger = serializers.CharField(help_text="Which surface started the run: 'ui' or 'mcp'.")
variables = NotebookVariableSerializer(
many=True, help_text="The variable values this run bound, snapshotted when it started."
)
cell_count = serializers.IntegerField(help_text="How many cells the run executes.")
current_index = serializers.IntegerField(help_text="Position in the plan the run has reached, counting from 0.")
current_node_id = serializers.CharField(
required=False, allow_null=True, help_text="The cell the run is on; null once the plan is finished."
)
failed_node_id = serializers.CharField(
required=False, allow_null=True, help_text="The cell that stopped the run, when one did."
)
error = serializers.CharField(
required=False, allow_null=True, help_text="Why the run stopped, in one sentence a person can read."
)
cells = NotebookRunCellSerializer(
many=True, help_text="Every planned cell in run order, with the state of its run in this notebook run."
)
created_at = serializers.DateTimeField(help_text="When the run started.")
finished_at = serializers.DateTimeField(
required=False, allow_null=True, help_text="When the run reached a terminal state; null while running."
)
class NotebookRunInterruptResponseSerializer(serializers.Serializer):
interrupted = serializers.BooleanField(
help_text="True when this call stopped the run. False when it had already finished, which is not an error."
)
status = serializers.CharField(help_text="The run's state after the call: 'done', 'failed', or 'interrupted'.")
MAX_INTROSPECTION_CODE_LENGTH = 100_000
class NotebookKernelCompleteRequestSerializer(serializers.Serializer):
code = serializers.CharField(
allow_blank=True,
trim_whitespace=False,
max_length=MAX_INTROSPECTION_CODE_LENGTH,
help_text="The full source of the cell being edited.",
)
cursor_pos = serializers.IntegerField(
min_value=0, help_text="Character offset of the cursor in `code`, counting from 0."
)
class NotebookKernelCompletionSerializer(serializers.Serializer):
text = serializers.CharField(help_text="The text that replaces `code[cursor_start:cursor_end]`.")
type = serializers.CharField(
allow_blank=True,
help_text="What the match names, as the kernel reports it: 'function', 'module', 'instance', … or blank.",
)
class NotebookKernelCompleteResponseSerializer(serializers.Serializer):
matches = NotebookKernelCompletionSerializer(
many=True, help_text="Completions from the live kernel's namespace. Empty when no kernel is running."
)
cursor_start = serializers.IntegerField(help_text="Start offset of the text the completions replace.")
cursor_end = serializers.IntegerField(help_text="End offset of the text the completions replace.")
class NotebookKernelInspectRequestSerializer(NotebookKernelCompleteRequestSerializer):
detail_level = serializers.IntegerField(
min_value=0,
max_value=1,
default=0,
help_text="0 for the signature and docstring, 1 to add the source when the kernel can find it.",
)
class NotebookKernelInspectResponseSerializer(serializers.Serializer):
found = serializers.BooleanField(help_text="Whether the kernel found an object at the cursor.")
text = serializers.CharField(
allow_blank=True, help_text="The object's signature and docstring as plain text. Blank when not found."
)