Skip to content

: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.

37.5 KB
Raw Blame
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."
    )