diff --git a/plugins/deepnote/.claude-plugin/plugin.json b/plugins/deepnote/.claude-plugin/plugin.json index 0077af9..dcae1f7 100644 --- a/plugins/deepnote/.claude-plugin/plugin.json +++ b/plugins/deepnote/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "deepnote", "displayName": "Deepnote", - "version": "0.9.2", + "version": "0.10.0", "description": "Search Deepnote workspaces, inspect and edit projects and notebooks, manage integrations and project machines, build data apps and Streamlit apps, generate links, read docs, and run notebooks from Claude.", "author": { "name": "Deepnote", diff --git a/plugins/deepnote/.codex-plugin/plugin.json b/plugins/deepnote/.codex-plugin/plugin.json index 6536296..d1af2ca 100644 --- a/plugins/deepnote/.codex-plugin/plugin.json +++ b/plugins/deepnote/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "deepnote", - "version": "0.9.2", + "version": "0.10.0", "description": "Search Deepnote workspaces, inspect and edit projects and notebooks, manage integrations and project machines, build data apps and Streamlit apps, generate links, read docs, and run notebooks from ChatGPT and Codex.", "author": { "name": "Deepnote", diff --git a/plugins/deepnote/skills/deepnote-data-apps/SKILL.md b/plugins/deepnote/skills/deepnote-data-apps/SKILL.md index b8bd5dc..d64e2b2 100644 --- a/plugins/deepnote/skills/deepnote-data-apps/SKILL.md +++ b/plugins/deepnote/skills/deepnote-data-apps/SKILL.md @@ -25,10 +25,16 @@ A data app project has two parts: the page, a responsive HTML page in `_deepnote display({'application/json': app_data}, raw=True) ``` +- Store a DataFrame instead when it is too large for the JSON output, or when the page should show it without waiting for a run. End a block of its own with `store_dataframe(df, '')`, after `from deepnote_toolkit.artifacts import store_dataframe`. The name matches `[A-Za-z0-9_-]{1,128}`, and storing replaces the frame stored before under it. + - Store it with `create_run` without `detachedRunStorageMode`, which can write to the project, then read that block's output with `get_run` and `snapshotDelivery: "blocks"` and check that it shows the returned reference ID. Read-only runs, viewers' runs included, return `None` and store nothing. + - Keep the block in the notebook: running it again, in the editor or with a writable `create_run`, is what refreshes the frame. + - Every viewer sees the frame stored last, whatever their inputs, so keep input-dependent data in the JSON output, and leave stored frames out of it. When the page shows only stored frames, the notebook needs no JSON-output block and no read-only check run. + - Store a SQL result from a SQL block in DataFrame output mode, which holds the whole result. A query preview holds at most 100 rows: create a SQL block with the same query and integration with `create_block`, without `deepnote_return_variable_type` in its `metadata`, and store that block's variable. Never store `pd.DataFrame(df)` of a query preview, as its `TypeError` suggests; that stores only the preview's rows. + - Queries, heavy computation, credentials, and authenticated calls stay in the notebook. The page only filters, sorts, and charts. - The app's controls are the notebook's input blocks. Reuse them by name and add only the missing ones. - For AI-written text, such as a summary of the data, keep an agent block as the last block and ask for that text in its prompt. The page reads it as `agentBlockSummary`. -- The page shows each viewer's own newest successful detached run, or, when the app lets everyone with access see results without running it, the editors' newest one until the viewer runs it, so running blocks in the editor changes nothing. That setting is always on for public and scheduled apps and never with private outputs. After changing the notebook, start a run with `create_run` and `detachedRunStorageMode: "readonly"`, wait until `get_run` with `snapshotDelivery: "blocks"` reports success, and check the JSON output's keys, types, and first rows before wiring the page to it. Changes to the page alone need no new run. +- The page shows each viewer's own newest successful detached run, or, when the app lets everyone with access see results without running it, the editors' newest one until the viewer runs it, so running blocks in the editor does not change its JSON output. That setting is always on for public and scheduled apps and never with private outputs. After changing the notebook, start a run with `create_run` and `detachedRunStorageMode: "readonly"`, wait until `get_run` with `snapshotDelivery: "blocks"` reports success, and check the JSON output's keys, types, and first rows before wiring the page to it. Changes to the page alone need no new run. ## The Page @@ -65,10 +71,14 @@ A data app project has two parts: the page, a responsive HTML page in `_deepnote ``` - By default, make it calm and compact like Deepnote without copying Deepnote's UI: neutral surfaces with one blue accent, 1px borders, `rounded-lg` controls and `rounded-xl` cards, sentence case, solid backgrounds without gradients, no emoji or decorative icons, shadows only on floating elements, and at most one primary button per view. When the user asks for another look or their brand, change the theme and classes freely. -- Connect with `const notebook = Deepnote.connect().notebook('')`, using the notebook ID from `get_project`. +- Connect once with `const deepnote = Deepnote.connect()`, then `const notebook = deepnote.notebook('')`, using the notebook ID from `get_project`. - On load, render `const {appData, agentBlockSummary, runCreatedAt} = await notebook.appData()` and show `runCreatedAt` as the time of the last update. When the app lets everyone with access see results without running it, a viewer with no run of their own gets the latest results of the app's editors. It throws when the viewer has no run yet, their results expired, or the run has no JSON output: show the message in an empty state with a button that runs the notebook with `{}`. - `const {run} = await notebook.run(values, {onProgress})` runs the whole notebook for this viewer. When `run.status === 'success'`, render `await notebook.appData()` again. Run it on submission, or with `{}` from a refresh button when the app has no inputs. Public visitors with **View** access can't run the app, so the call rejects: show its message. - Build the form from `await notebook.inputs()`, which returns each input's label, value, min, max, step, and options, so input changes in the notebook reach the app. Never overwrite input variables with hardcoded values. Values are keyed by input name and are strings (sliders too), booleans, or string arrays. + - `await deepnote.dataframe('', {pageIndex, pageSize})` reads one page of a stored frame and starts no run. It rejects in a project with private outputs, so keep the data in the JSON output there. `pageIndex` defaults to 0 and `pageSize` to 10, at most 1000. It returns `{referenceId, rowCount, columnCount, pageIndex, pageSize, pageCount, columns, rows}`, where `columns` is `[{name, type, timezone}]` and each row is an array of values in the order of `columns`. + - `int64` (pandas' default integers) and `decimal` values arrive as strings, dates and timestamps as ISO strings, and missing values as `null` in every type. Convert non-null `int64` and `decimal` values with `Number()` before summing, sorting, or charting, and keep `null` as missing, since `Number(null)` is 0. Keep ID columns as strings, since `Number()` rounds integers beyond `Number.MAX_SAFE_INTEGER`. + - Page through it in a table, or load only the pages a view needs. When `referenceId` changes between pages, a new frame replaced the stored one: start again from page 0. When a page after page 0 rejects, read page 0 again: a different `referenceId` means a new frame, possibly with fewer pages, replaced it, so start again from there; otherwise show the error. + - Load it on page load without waiting for `notebook.appData()`, which rejects for a viewer who has no run yet. A page that shows only stored frames calls neither `notebook.appData()` nor `notebook.run()`, so every viewer sees the table. - Show loading, empty, and error states, prevent duplicate submissions, and handle rejected calls, missing results, and `run.error`. When a failed run has no error text, show its status and point to run history. - Lay out dashboards as a title with one line of context, filters, a row of key numbers, one to three main charts, then a detail table. Format numbers and dates for reading, and label units. - To show another app's data, connect to that app's notebook instead of copying its queries. Find its ID with `search`, check its JSON output with a read-only run, and do not change that notebook. Its keys can change, so show an error state when they are missing. @@ -81,7 +91,7 @@ Test a changed-input submission with `create_run`, its `inputs`, and `detachedRu Preview the page locally before pushing it, against the same API and data it gets in Deepnote: 1. Mint a viewer token with `create_data_app_token` for the project. Pass it only on the command line; never write it into files or answers. -2. Run `node scripts/app-dev.mjs --token --api-origin ` in the background, with the script from this skill's directory. Have the same background command kill it after 15 minutes, for example after `sleep 900`, so previews do not pile up; the token expires then anyway. It needs Node 18 or later. It serves the page embedded the way Deepnote does, prints the preview URL, and logs files the page asks for that do not exist. +2. Run `node scripts/app-dev.mjs --token --api-origin --project-id ` in the background, with the script from this skill's directory, where `` is the project ID passed to `create_data_app_token` in step 1. Have the same background command kill it after 15 minutes, for example after `sleep 900`, so previews do not pile up; the token expires then anyway. It needs Node 18 or later. It serves the page embedded the way Deepnote does, prints the preview URL, and logs files the page asks for that do not exist. 3. With a browser tool, open the preview URL. The bar above the page says whether the app connected to Deepnote and lists its errors. Look at the page and try the inputs; runs started there are real runs. Fix the files and reload until the bar shows no errors. When it stops, mint a new token and start it again. 4. Without a browser tool, give the user the preview URL, ask them to open it, and say that you did not check the page yourself. 5. Push the new and changed files, after asking the user first when the app existed before this conversation, and leave the preview running so the user can open it until it is killed after 15 minutes. Stop it sooner when the user asks, or before starting another preview on the same port. When the user still wants it after it stops, mint a new token and start it again. diff --git a/plugins/deepnote/skills/deepnote-data-apps/scripts/app-dev.mjs b/plugins/deepnote/skills/deepnote-data-apps/scripts/app-dev.mjs index 8320a58..ae7ce1c 100755 --- a/plugins/deepnote/skills/deepnote-data-apps/scripts/app-dev.mjs +++ b/plugins/deepnote/skills/deepnote-data-apps/scripts/app-dev.mjs @@ -10,10 +10,11 @@ import http from 'node:http' import path from 'node:path' import { parseArgs } from 'node:util' -const USAGE = `Usage: node app-dev.mjs --token --api-origin [--port ] +const USAGE = `Usage: node app-dev.mjs --token --api-origin --project-id [--port ] --token Viewer token from the create_data_app_token MCP tool. It is never printed. --api-origin apiOrigin from the same create_data_app_token result. + --project-id ID of the data app project, the one passed to create_data_app_token. --port Port of the preview page; the app is served on the next one. Default 4747.` // The common web types from the table Deepnote's server looks content types up in. @@ -91,7 +92,7 @@ function createAppServer(root, origins, apiOrigin) { }) } -function renderDeepnotePage({ appOrigin, apiOrigin, token }) { +function renderDeepnotePage({ appOrigin, apiOrigin, token, projectId }) { return ` @@ -111,7 +112,7 @@ iframe { flex: 1; width: 100%; border: 0; color-scheme: light dark; }
Waiting for the app to connect to Deepnote.