diff --git a/ai_evals/cases/global.yaml b/ai_evals/cases/global.yaml index b258c3822a..8758eb2d36 100644 --- a/ai_evals/cases/global.yaml +++ b/ai_evals/cases/global.yaml @@ -4080,3 +4080,63 @@ skipJudge: true judgeChecklist: - explains the MCP setup from the docs: the MCP URL with a token, added to Claude + +# --- Charts and tables in replies (```wm-display blocks) --- +# The chat renders a ```wm-display block holding a chart or table value; anything the catalog +# rejects shows as code with an error. Pin that the model reaches for it when a chart is the +# answer, that what it writes validates, and that a plain question gets prose. + +- id: global-display-chart-in-reply + prompt: |- + Our deploys last week were Mon 4, Tue 7, Wed 3, Thu 9, Fri 6. Can you chart that for me? + runtime: + maxTurns: 6 + sessionChat: true + validate: + draftCountExactly: 0 + toolExpect: + forbiddenToolsUsed: + - deploy_workspace_item + - delete_workspace_item + assistantExpect: + displayBlocks: required + judgeAssistantText: true + judgeChecklist: + - the reply shows the five days' deploy counts as a chart rather than only as text + - the chart carries the values given (Mon 4, Tue 7, Wed 3, Thu 9, Fri 6) + - does not create a script or flow just to draw the chart + +- id: global-display-chart-in-artifact + prompt: |- + Write me a short doc I can share summarizing last month's support tickets by channel: + email 120, chat 85, phone 30, other 12. Include a chart. + runtime: + maxTurns: 8 + sessionChat: true + validate: + draftCountExactly: 0 + toolExpect: + requiredToolsUsed: + - create_artifact + toolCallArgs: + - tool: create_artifact + field: content + stringIncludesAnyOf: + - "```wm-display" + skipJudge: true + judgeChecklist: + - creates an artifact whose content includes a chart of the ticket counts by channel + +- id: global-display-not-for-prose + prompt: |- + What's the difference between a flow and a script in Windmill? + runtime: + maxTurns: 6 + sessionChat: true + validate: + draftCountExactly: 0 + assistantExpect: + displayBlocks: forbidden + skipJudge: true + judgeChecklist: + - answers in prose without a chart or table block diff --git a/ai_evals/core/types.ts b/ai_evals/core/types.ts index 2b667c3129..5e9fd0a362 100644 --- a/ai_evals/core/types.ts +++ b/ai_evals/core/types.ts @@ -311,6 +311,12 @@ export interface AssistantValidationSpec { * assistant say the right thing" expectations to the judge checklist. */ forbiddenMentions?: string[]; + /** + * `required`: the reply holds at least one ```wm-display block, and every one validates + * against the chat's display catalog (what the chat renders as a chart or table). + * `forbidden`: the reply holds none. + */ + displayBlocks?: "required" | "forbidden"; } export interface EvalCase { diff --git a/ai_evals/core/validators.test.ts b/ai_evals/core/validators.test.ts index 4668995a15..f0aa8f55a9 100644 --- a/ai_evals/core/validators.test.ts +++ b/ai_evals/core/validators.test.ts @@ -8,6 +8,7 @@ import { validateScriptState, validateAssistantExpectations, validateToolExpectations, + validateDisplayBlocks, } from "./validators"; describe("validateScriptState", () => { @@ -1373,3 +1374,19 @@ describe("validateCliWorkspace", () => { }); }); }); + +describe("validateDisplayBlocks", () => { + const fence = (value: unknown) => "```wm-display\n" + JSON.stringify(value) + "\n```"; + const chart = { chart: { type: "bar", data: [{ day: "Mon", n: 4 }], x: "day", y: "n" } }; + + it("requires every block to validate against the display catalog", () => { + const ok = validateDisplayBlocks(`Here:\n${fence(chart)}`, "required"); + expect(ok.every((c) => c.passed)).toBe(true); + const bad = validateDisplayBlocks( + `${fence(chart)}\n${fence({ chart: { ...chart.chart, y: "missing" } })}`, + "required" + ); + expect(bad.every((c) => c.passed)).toBe(false); + expect(validateDisplayBlocks("plain prose", "required").every((c) => c.passed)).toBe(false); + }); +}); diff --git a/ai_evals/core/validators.ts b/ai_evals/core/validators.ts index 6f596649df..0baf6f6f3a 100644 --- a/ai_evals/core/validators.ts +++ b/ai_evals/core/validators.ts @@ -1,5 +1,6 @@ import path from "node:path"; import ts from "typescript"; +import { parseFence } from "../../frontend/src/lib/components/display/displayCatalog"; import type { AppValidationSpec, AssistantValidationSpec, @@ -207,9 +208,38 @@ export function validateAssistantExpectations(input: { ); } + if (expect.displayBlocks) { + checks.push(...validateDisplayBlocks(text, expect.displayBlocks)); + } + return checks; } +const DISPLAY_BLOCK = /```wm-display[^\n]*\n([\s\S]*?)```/g; + +/** The ```wm-display blocks in `text`, checked with the parser the chat renders them with. */ +export function validateDisplayBlocks( + text: string, + mode: "required" | "forbidden" +): BenchmarkCheck[] { + const blocks = [...text.matchAll(DISPLAY_BLOCK)].map((m) => m[1]); + if (mode === "forbidden") { + return [check("reply holds no wm-display block", blocks.length === 0, truncateForDetails(text))]; + } + const failures = blocks + .map((source, i) => ({ i, parsed: parseFence(source) })) + .filter(({ parsed }) => !parsed.ok) + .map(({ i, parsed }) => `block ${i + 1}: ${parsed.ok ? "" : parsed.error}`); + return [ + check("reply holds a wm-display block", blocks.length > 0, truncateForDetails(text)), + check( + "every wm-display block validates against the display catalog", + blocks.length > 0 && failures.length === 0, + failures.join("\n") || undefined + ), + ]; +} + export function validateToolExpectations(input: { run: ModeRunOutput; toolExpect?: ToolValidationSpec; diff --git a/backend/ee-repo-ref.txt b/backend/ee-repo-ref.txt index f42fed2c59..aab30364b4 100644 --- a/backend/ee-repo-ref.txt +++ b/backend/ee-repo-ref.txt @@ -1 +1 @@ -bf04cefe64776cb7262f041105b6ceca2953d5f4 +a5d1e052df3e920d3f0b50bdb148c37bf8eec2c4 diff --git a/backend/windmill-api/src/ai_session_tools/gen/instructions.json b/backend/windmill-api/src/ai_session_tools/gen/instructions.json index f6de7178d2..493e6cd79a 100644 --- a/backend/windmill-api/src/ai_session_tools/gen/instructions.json +++ b/backend/windmill-api/src/ai_session_tools/gen/instructions.json @@ -223,6 +223,34 @@ "duckdb": "workspace_settings", "bunnative": "workspace_settings", "dbt": "workspace_settings" + }, + "display": { + "": "display", + "python3": "display", + "deno": "display", + "go": "display", + "bash": "display", + "powershell": "display", + "postgresql": "display", + "mysql": "display", + "bigquery": "display", + "snowflake": "display", + "mssql": "display", + "oracledb": "display", + "graphql": "display", + "nativets": "display", + "bun": "display", + "php": "display", + "rust": "display", + "ansible": "display", + "csharp": "display", + "nu": "display", + "java": "display", + "ruby": "display", + "rlang": "display", + "duckdb": "display", + "bunnative": "display", + "dbt": "display" } }, "texts": { @@ -261,6 +289,7 @@ "datatable.python3": "# Data tables: schema changes, migrations and permissions\n\nA data table is a PostgreSQL database managed by Windmill and shared by the whole workspace: scripts, flows and apps reach it by name, `main` being the default. It is configured in the workspace settings (Data Tables), never created by SQL.\n\n## Changing the schema\n\nA data table with migrations enabled keeps its schema as an ordered list of versioned SQL migrations, each an `up` and an optional `down`. That list is what git sync and a workspace merge carry, and what rebuilds the schema in another workspace. So first find out whether migrations are enabled on the data table:\n\n- **Enabled**: make every schema change (CREATE, ALTER, DROP, anything but row data) as a new migration. A change made with plain SQL exists in that one database only, and the history no longer describes it.\n- **Not enabled**: schema changes are plain SQL. Enabling migrations is a workspace admin's decision, made in the Data Tables settings, not a step to take on the way to something else.\n\nWriting a migration:\n\n- Wrap the statements in `BEGIN; ... END;` so it applies atomically. Leave the frame out only for a statement that cannot run in a transaction, such as `CREATE INDEX CONCURRENTLY`: such a migration can fail half applied.\n- Give it a `down` that undoes the `up` whenever the change is reversible. Without one it cannot be rolled back.\n- Declare the schemas it changes on a leading line of its `up`, `-- schemas sales, billing`, and qualify every name with its schema (`sales.orders`). A migration waits only on earlier migrations whose schemas overlap its own. One that declares none applies to the whole database and every later migration waits for it, so leave the line out only for a change that really spans the database, such as an extension.\n- Migrations apply oldest first. One that is applied is not edited: correct it with a new migration.\n- Row data is not schema. Insert, update and delete rows with plain SQL, migrations or not.\n\n## A migration is not a draft\n\nA migration is saved to the workspace and changes the database as soon as it is applied, for everything that reads those tables. To try a schema out without touching tables already in use:\n\n- put the new tables in a schema of their own, created by the same migration (`CREATE SCHEMA IF NOT EXISTS`), and point what you are building at it. A raw app names its schema in its `data` config, which is why a new app gets a new schema by default;\n- or work in a workspace fork whose data table was cloned when the fork was created (\"Clone schema only\" or \"Clone schema and data\"): migrations applied there change that copy alone, and reach the parent workspace when the fork is merged. A fork that kept the original data table points at the parent's database, so a migration applied in it changes the parent's tables at once.\n\nAltering or dropping a table other scripts or apps use is neither of those: say what depends on it before doing it.\n\n## Roles and permissions\n\nData table roles are a self-hosted Enterprise Edition feature, for data tables on managed Postgres (the instance database or the external managed instance). Without them, and always on a data table backed by a Postgres resource, everyone who can use the data table reaches all of it: there is no per-user, per-schema or per-row access to promise.\n\nA data table under roles is reached as a Postgres role, and Postgres enforces what that role was granted:\n\n- roles are assigned, per data table, to users, groups or folders. `admin` is the connection the data table had before roles: it owns the existing objects and ignores grants;\n- a connection either names a role (`wmill.datatable('main', { role: 'analyst' })`, `role='analyst'` in Python, `datatable://main?role=analyst`) and holds that role alone, or names none and is resolved from the data table's default role;\n- `permission denied` means the role in use lacks a grant. Say which role and which object: the grant is a data table admin's to give, in the roles drawer of the Database Manager. Do not switch to `admin` to get past it;\n- a migration runs as the role its SQL declares on its first line, `-- role `, the same one in its `down`. One that declares none runs as `admin`, which only those who may use `admin` can do.\n\nRead the Permissions section of https://www.windmill.dev/docs/core_concepts/persistent_storage/data_tables before designing who reaches what: it covers tenants, grants, the default role and the roles a connection that names none ends up holding, rows that differ per viewer through row-level security, and how forks and raw apps behave under roles.\n\n\n# Datatable SQL SDK reference\n\nDatatables are workspace-scoped managed PostgreSQL databases. In chat, explore and shape them with the datatable tools you were given. The reference below is for code you author inside runnables (inline app runnables, scripts, or flow rawscript modules) that reads or writes datatable data at runtime.\n\n- A runnable accesses a datatable via `wmill.datatable()` (the default \"main\") or `wmill.datatable('')`, referencing tables as `schema.table`.\n- Use parameterized queries (the tagged template in TypeScript, `$1`/`$2` placeholders in Python) — never interpolate untrusted values into SQL strings.\n\n## Python Datatable API (wmill)\n\nImport: `import wmill`\n\n# Get a DataTable client for SQL queries.\n# \n# Args:\n# name: Database name (default: \"main\")\n# role: Connect as this data table role instead of the data table's default one.\n# \n# Returns:\n# DataTableClient instance\ndef datatable(name: str = 'main', *, role: Optional[str] = None) -> DataTableClient\n\n# Client for executing SQL queries against Windmill DataTables.\nclass DataTableClient:\n # Initialize DataTableClient.\n # \n # Args:\n # client: Windmill client instance\n # name: DataTable name\n # role: Data table role to connect as, or None for the data table's default\n def __init__(client: Windmill, name: str, role: Optional[str] = None)\n\n # Execute a SQL query against the DataTable.\n # \n # Args:\n # sql: SQL query string with $1, $2, etc. placeholders\n # *args: Positional arguments to bind to query placeholders\n # \n # Returns:\n # SqlQuery instance for fetching results\n def query(sql: str, *args) -> SqlQuery\n\n\n# Query result handler for DataTable and DuckLake queries.\nclass SqlQuery:\n # Initialize SqlQuery.\n # \n # Args:\n # sql: SQL query string\n # fetch_fn: Function to execute the query\n def __init__(sql: str, fetch_fn)\n\n # Execute query and fetch results.\n # \n # Args:\n # result_collection: Optional result collection mode\n # \n # Returns:\n # Query results\n def fetch(result_collection: str | None = None)\n\n # Execute query and fetch first row of results.\n # \n # Returns:\n # First row of query results\n def fetch_one()\n\n # Execute query and fetch first row of results. Return result as a scalar value.\n # \n # Returns:\n # First row of query result as a scalar value\n def fetch_one_scalar()\n\n # Execute query and don't return any results.\n # \n def execute()\n\n\n", "datatable.go": "# Data tables: schema changes, migrations and permissions\n\nA data table is a PostgreSQL database managed by Windmill and shared by the whole workspace: scripts, flows and apps reach it by name, `main` being the default. It is configured in the workspace settings (Data Tables), never created by SQL.\n\n## Changing the schema\n\nA data table with migrations enabled keeps its schema as an ordered list of versioned SQL migrations, each an `up` and an optional `down`. That list is what git sync and a workspace merge carry, and what rebuilds the schema in another workspace. So first find out whether migrations are enabled on the data table:\n\n- **Enabled**: make every schema change (CREATE, ALTER, DROP, anything but row data) as a new migration. A change made with plain SQL exists in that one database only, and the history no longer describes it.\n- **Not enabled**: schema changes are plain SQL. Enabling migrations is a workspace admin's decision, made in the Data Tables settings, not a step to take on the way to something else.\n\nWriting a migration:\n\n- Wrap the statements in `BEGIN; ... END;` so it applies atomically. Leave the frame out only for a statement that cannot run in a transaction, such as `CREATE INDEX CONCURRENTLY`: such a migration can fail half applied.\n- Give it a `down` that undoes the `up` whenever the change is reversible. Without one it cannot be rolled back.\n- Declare the schemas it changes on a leading line of its `up`, `-- schemas sales, billing`, and qualify every name with its schema (`sales.orders`). A migration waits only on earlier migrations whose schemas overlap its own. One that declares none applies to the whole database and every later migration waits for it, so leave the line out only for a change that really spans the database, such as an extension.\n- Migrations apply oldest first. One that is applied is not edited: correct it with a new migration.\n- Row data is not schema. Insert, update and delete rows with plain SQL, migrations or not.\n\n## A migration is not a draft\n\nA migration is saved to the workspace and changes the database as soon as it is applied, for everything that reads those tables. To try a schema out without touching tables already in use:\n\n- put the new tables in a schema of their own, created by the same migration (`CREATE SCHEMA IF NOT EXISTS`), and point what you are building at it. A raw app names its schema in its `data` config, which is why a new app gets a new schema by default;\n- or work in a workspace fork whose data table was cloned when the fork was created (\"Clone schema only\" or \"Clone schema and data\"): migrations applied there change that copy alone, and reach the parent workspace when the fork is merged. A fork that kept the original data table points at the parent's database, so a migration applied in it changes the parent's tables at once.\n\nAltering or dropping a table other scripts or apps use is neither of those: say what depends on it before doing it.\n\n## Roles and permissions\n\nData table roles are a self-hosted Enterprise Edition feature, for data tables on managed Postgres (the instance database or the external managed instance). Without them, and always on a data table backed by a Postgres resource, everyone who can use the data table reaches all of it: there is no per-user, per-schema or per-row access to promise.\n\nA data table under roles is reached as a Postgres role, and Postgres enforces what that role was granted:\n\n- roles are assigned, per data table, to users, groups or folders. `admin` is the connection the data table had before roles: it owns the existing objects and ignores grants;\n- a connection either names a role (`wmill.datatable('main', { role: 'analyst' })`, `role='analyst'` in Python, `datatable://main?role=analyst`) and holds that role alone, or names none and is resolved from the data table's default role;\n- `permission denied` means the role in use lacks a grant. Say which role and which object: the grant is a data table admin's to give, in the roles drawer of the Database Manager. Do not switch to `admin` to get past it;\n- a migration runs as the role its SQL declares on its first line, `-- role `, the same one in its `down`. One that declares none runs as `admin`, which only those who may use `admin` can do.\n\nRead the Permissions section of https://www.windmill.dev/docs/core_concepts/persistent_storage/data_tables before designing who reaches what: it covers tenants, grants, the default role and the roles a connection that names none ends up holding, rows that differ per viewer through row-level security, and how forks and raw apps behave under roles.\n\n\n# Datatable SQL SDK reference\n\nDatatables are workspace-scoped managed PostgreSQL databases. In chat, explore and shape them with the datatable tools you were given. The reference below is for code you author inside runnables (inline app runnables, scripts, or flow rawscript modules) that reads or writes datatable data at runtime.\n\n- A runnable accesses a datatable via `wmill.datatable()` (the default \"main\") or `wmill.datatable('')`, referencing tables as `schema.table`.\n- Use parameterized queries (the tagged template in TypeScript, `$1`/`$2` placeholders in Python) — never interpolate untrusted values into SQL strings.\n\n## TypeScript Datatable API (windmill-client)\n\nImport: `import * as wmill from 'windmill-client'`\n\nSQL statement object with query content, arguments, and execution methods\n```typescript\ntype SqlStatement = {\n /** Raw SQL content with formatted arguments */\n content: string;\n\n /** Argument values keyed by parameter name */\n args: Record;\n\n /**\n * Execute the SQL query and return results\n * @param params - Optional parameters including result collection mode\n * @returns Query results based on the result collection mode\n */\n fetch(\n params?: FetchParams // The union is for auto-completion\n ): Promise>;\n\n /**\n * Execute the SQL query and return only the first row\n * @param params - Optional parameters\n * @returns First row of the query result\n */\n fetchOne(\n params?: Omit, \"resultCollection\">\n ): Promise>;\n\n /**\n * Execute the SQL query and return only the first row as a scalar value\n * @param params - Optional parameters\n * @returns First row of the query result\n */\n fetchOneScalar(\n params?: Omit<\n FetchParams<\"last_statement_first_row_scalar\">,\n \"resultCollection\"\n >\n ): Promise>;\n\n /**\n * Execute the SQL query without fetching rows\n * @param params - Optional parameters\n */\n execute(\n params?: Omit, \"resultCollection\">\n ): Promise;\n};\n```\n\n```typescript\n// Template tag function: sql`SELECT * FROM table WHERE id = ${id}`.fetch()\ninterface DatatableSqlTemplateFunction {\n // Tagged template usage:\n (strings: TemplateStringsArray, ...values: any[]): SqlStatement;\n query(sql: string, ...params: any[]): SqlStatement;\n};\n```\n\nCreate a SQL template function for PostgreSQL/datatable queries\n@param name - Database/datatable name (default: \"main\")\n@param opts.role - Connect as this data table role instead of the data table's default one.\n Only meaningful on a data table under roles, and only for a role you are a tenant of.\n@returns SQL template function for building parameterized queries\n@example\nlet sql = wmill.datatable()\nlet name = 'Robin'\nlet age = 21\nawait sql`\n SELECT * FROM friends\n WHERE name = ${name} AND age = ${age}::int\n`.fetch()\n@example\n// Read through a restricted role\nlet sql = wmill.datatable(\"main\", { role: \"analytics\" })\n```typescript\nfunction datatable(name: string = \"main\",\n opts?: DatatableOptions): DatatableSqlTemplateFunction\n```\n\n\n## Python Datatable API (wmill)\n\nImport: `import wmill`\n\n# Get a DataTable client for SQL queries.\n# \n# Args:\n# name: Database name (default: \"main\")\n# role: Connect as this data table role instead of the data table's default one.\n# \n# Returns:\n# DataTableClient instance\ndef datatable(name: str = 'main', *, role: Optional[str] = None) -> DataTableClient\n\n# Client for executing SQL queries against Windmill DataTables.\nclass DataTableClient:\n # Initialize DataTableClient.\n # \n # Args:\n # client: Windmill client instance\n # name: DataTable name\n # role: Data table role to connect as, or None for the data table's default\n def __init__(client: Windmill, name: str, role: Optional[str] = None)\n\n # Execute a SQL query against the DataTable.\n # \n # Args:\n # sql: SQL query string with $1, $2, etc. placeholders\n # *args: Positional arguments to bind to query placeholders\n # \n # Returns:\n # SqlQuery instance for fetching results\n def query(sql: str, *args) -> SqlQuery\n\n\n# Query result handler for DataTable and DuckLake queries.\nclass SqlQuery:\n # Initialize SqlQuery.\n # \n # Args:\n # sql: SQL query string\n # fetch_fn: Function to execute the query\n def __init__(sql: str, fetch_fn)\n\n # Execute query and fetch results.\n # \n # Args:\n # result_collection: Optional result collection mode\n # \n # Returns:\n # Query results\n def fetch(result_collection: str | None = None)\n\n # Execute query and fetch first row of results.\n # \n # Returns:\n # First row of query results\n def fetch_one()\n\n # Execute query and fetch first row of results. Return result as a scalar value.\n # \n # Returns:\n # First row of query result as a scalar value\n def fetch_one_scalar()\n\n # Execute query and don't return any results.\n # \n def execute()\n\n\n", "pipeline": "# Data pipeline authoring\n\nA **data pipeline** is NOT a flow. A flow is one runnable that orchestrates steps internally. A data pipeline is a set of **independent scripts**, each deployed on its own, that form a DAG by reading and writing shared **storage assets** (DuckLake tables, data tables, S3 objects, volumes, resources) and by declaring execution **triggers**. The pipeline is visualized and edited at `/pipeline/`; every node is a normal workspace script that happens to carry pipeline annotations. When the user asks for a \"data pipeline\" (or to \"ingest / transform / materialize\" data across steps), build pipeline-annotated scripts — do NOT build a flow.\n\n## Default to DuckDB + DuckLake\n\nA pipeline node that produces a table should almost always be a **`duckdb`** node that materializes its output into a **DuckLake** table with `-- materialize ducklake:///` (in a DuckDB node the annotation uses SQL `--` comment syntax; write the body as a bare `SELECT` and let the runtime do the write). DuckLake is the default lakehouse store for pipelines and is the shape the pipeline editor is built around, so prefer it unless the work specifically calls for something else:\n\n- `postgresql` / data tables — only for row-level, OLTP-style mutations against an existing Postgres data table (frequent single-row upserts/updates, transactional reads that an app queries live).\n- `bun` / `python3` — only for work that doesn't map to SQL: calling an external API, wrangling files, arbitrary glue. When such a node produces tabular data for downstream steps, write it **straight into DuckLake** (or a data table) from the same script — see \"Ingesting from Python / TypeScript\" below — rather than inventing a parallel store.\n\nDo not spread a pipeline across postgres, S3, and DuckLake when one DuckLake lake would do; a consistent DuckLake lakehouse is the goal.\n\n## Ingesting from Python / TypeScript\n\nA node that fetches data in code (an API, a SaaS export, a scraper) writes the rows **directly** into their DuckLake table with `wmill.ducklake()`, or into a data table with `wmill.datatable()`. DuckLake already stores every table as parquet files in the workspace object storage, so **never stage the raw payload first** — no intermediate JSON / CSV / parquet file in S3 and no second \"load the raw file\" node. One ingestion node, one table.\n\nPass the rows as a query argument (a list of dicts / array of objects is sent as JSON) and let SQL unnest them; declare the column types so the table gets a real schema:\n\n```python\n# pipeline\n# on schedule\nimport wmill\n\ndef main():\n rows = fetch_charges() # list[dict]\n lake = wmill.ducklake()\n lake.query(\"\"\"\n CREATE OR REPLACE TABLE stripe_charges AS\n SELECT unnest(from_json($rows, '[{\"id\":\"VARCHAR\",\"amount\":\"BIGINT\",\"created\":\"BIGINT\"}]'), recursive := true)\n \"\"\", rows=rows).fetch()\n```\n\n```ts\n// pipeline\n// on schedule\nimport * as wmill from \"windmill-client\"\n\nexport async function main() {\n const rows = await fetchCharges()\n const lake = wmill.ducklake()\n await lake`CREATE OR REPLACE TABLE stripe_charges AS\n SELECT unnest(from_json(${rows}, '[{\"id\":\"VARCHAR\",\"amount\":\"BIGINT\",\"created\":\"BIGINT\"}]'), recursive := true)`.fetch()\n}\n```\n\n- Use `INSERT INTO
SELECT ...` instead of `CREATE OR REPLACE` to append (an incremental pull), with a one-time `CREATE TABLE IF NOT EXISTS` first.\n- Assign the client to a variable (`lake = wmill.ducklake()`) and keep the SQL a **string literal** (Python) or a template without `sql.raw` (TS): that is what lets the graph record the node's write to `ducklake://main/
`. A chained `wmill.ducklake().query(...)` or SQL built in a variable records no output, so the downstream edge never forms.\n- `wmill.ducklake(\"\")` targets a non-default catalog; `wmill.datatable(\"\")` writes a Postgres data table the same way (Python `db.query(sql, *args)` with `$1` placeholders, TS the same template form) — use it only when the data belongs in Postgres (see above).\n- The downstream node triggers on the table itself: `-- on ducklake://main/stripe_charges`.\n\n## Storage prerequisites\n\nA DuckLake pipeline only runs once the workspace has **object storage** (S3 / Azure Blob / GCS) **and a DuckLake catalog** configured — DuckLake tables and `s3://` assets can't be materialized or read without it. Check which DuckLake catalogs the workspace has before you build.\nDrafting the annotated scripts does not require storage, but the pipeline can't ingest, materialize, or read its assets until it exists. So if there is none (or the user hits \"storage not configured\" errors), say so and give the right next step **by role**:\n\n- a workspace **admin** sets it up in Workspace settings → Object Storage (add an S3/Azure/GCS storage), then adds a DuckLake catalog on top of it;\n- anyone **without admin rights** should ask a workspace admin to configure object storage + a DuckLake catalog.\n\nNever hand back a DuckLake pipeline that cannot run without flagging the missing storage and pointing to who sets it up.\n\n## What makes a script a pipeline node\n\nA script joins the pipeline when its source begins with the `pipeline` annotation as a top-of-file comment, **written in the script's own comment syntax** — `//` for TS/JS (bun), `--` for SQL (DuckDB/Postgres), `#` for Python/Bash. So it's `-- pipeline` in a DuckDB node, `# pipeline` in a Python node, `// pipeline` in a bun node. Every annotation below uses that same prefix (the `//` shown is the TS form). All other wiring is expressed as annotation comments near the top of the file:\n\n- `// on ` — declares an execution-DAG **input** (what triggers/feeds this node). `` is either:\n - an **asset URI** (the node runs when that asset is produced upstream): `ducklake://main/orders`, `datatable://main/users`, `$res:f/folder/my_resource`, `volume://name/path`, or an S3 object (see the S3 storage-form rule below).\n - a **native trigger kind**: `schedule`, `webhook`, `email`, `kafka`, `mqtt`, `amqp`, `nats`, `postgres`, `sqs`, `gcp`, or `data_upload` (a user-uploaded S3 file). For these the actual trigger row (cron, topic, …) is created separately; the annotation only declares the binding. **`data_upload` is special**: there is no trigger row — the node instead declares an **`S3Object` input parameter** fed by the auto-generated upload picker; it never hard-codes a key. Any language can be the `data_upload` node:\n - Python (has `import wmill`): `def main(file: wmill.S3Object):` then `wmill.load_s3_file(file)`; TS (has `import * as wmill from \"windmill-client\"`): `export async function main(file: wmill.S3Object)`. Qualify the type as `wmill.S3Object` (or add `from wmill import S3Object` / `import { S3Object } from \"windmill-client\"`) — a bare `S3Object` is undefined.\n - **DuckDB** takes the s3object arg via a `-- $ (s3object)` declaration and reads it directly, so a single DuckDB node can ingest **and** materialize:\n ```\n -- pipeline\n -- on data_upload\n -- materialize ducklake://main/raw_uploads\n -- $file (s3object)\n SELECT * FROM read_csv($file)\n ```\n- **Outputs** are inferred from what the body writes — a `CREATE TABLE`, a `wmill.writeS3File(...)`, a DuckLake/datatable write. To declare a managed output explicitly, use `// materialize `.\n- Optional badges: `// partitioned `, `// freshness ` (e.g. `1h`), `// tag `, `// retry [delay]`, `// data_test ...` (managed DuckLake targets only — deploy rejects it beside a `dbt://` one), `// measure = [where ]` and `// dimension = ` (see \"Declared metrics\" below).\n\n## S3 object wiring (storage form matters)\n\nAn `s3://` URI's first slashes select the **storage**, not part of the key — get this wrong and the producer/consumer edge silently won't connect:\n\n- `s3:///` (**triple** slash, empty first segment) = the **default** workspace storage. A downstream node reading or triggering on that object uses `s3:///` — e.g. DuckDB `-- on s3:///orders/2024.parquet` and `read_parquet('s3:///orders/2024.parquet')`.\n- `s3:///` (**double** slash, non-empty first segment) = a **named secondary** storage called `` — so `s3://ingest/x` means storage `ingest`, key `x`, NOT key `ingest/x`. Only use this when the object genuinely lives in a configured secondary storage; never invent a bucket/storage name for a default-storage object (it breaks the edge).\n\nTo make the producer side visible to lineage, a Python/TS node MUST pass the **`S3Object` form**, not a bare key string: Python `wmill.write_s3_file(wmill.S3Object(s3=\"\"), data)` (or the import-free dict `{\"s3\": \"\"}`), TS `wmill.writeS3File({ s3: \"\" }, data)`. That records the default-storage asset `/`, which a downstream `s3:///` reader connects to (same key both sides). A bare `write_s3_file(\"\", ...)` records **no** asset and produces **no** edge. Add `storage=\"\"` only for a named secondary storage.\n\nThe key must be a **string literal** — the graph parser is static and cannot follow a variable, f-string, or computed path, so `write_s3_file(wmill.S3Object(s3=key_var), ...)` records no edge. Inline the literal (`s3=\"events/user_events.parquet\"`) on both the writing and reading node. The same rule applies to every asset URI in an annotation or SDK call (`ducklake://`, `datatable://`, `s3://`): write them literally, not via a variable.\n\n## Materialize (the managed output)\n\n> **A MANAGED `// materialize` is DuckDB-only**, and its target must be a DuckLake table (`ducklake:///
`). Deploy **rejects** a `ducklake://` `// materialize` on any other language (`python3`, `bun`, `postgresql`). For a non-DuckDB node writing the lake, do **not** use `// materialize` — write the table itself with `wmill.ducklake()` (see \"Ingesting from Python / TypeScript\") and let the output be inferred. Use `duckdb` when a node should materialize a DuckLake table.\n>\n> The one target ANY language may declare (except a dbt script, whose writes come from its manifest) is a **warehouse relation**: `// materialize manual dbt:////`, where `` is a warehouse the workspace configures under Settings → dbt. `manual` is the only mode it has — nothing generates warehouse DDL, so the node issues its own write (a postgresql `CREATE TABLE` / `INSERT`, an SDK load, …) and the annotation records the outcome. Use it on an ingestion node whose output a dbt project reads as a `source`: the declared relation and the dbt model land on ONE graph node, and a downstream `// on dbt:////` fires when the ingestion node completes.\n\nA managed `// materialize ducklake:///
` tells the runtime to write the node's output table **for you**: write the body as a single `SELECT` and the runtime wraps it in the create/replace — do **not** also write your own `CREATE TABLE` / `INSERT`. (The opposite holds for the `dbt://` target above: there the node writes its own DDL and the strategies below do not apply.)\n\nA target that names no table — `// materialize`, `// materialize ducklake://`, or options alone such as `// materialize key=id` — writes the table named after the script: node `f/shop/orders_daily` materializes `ducklake://main/orders_daily` (characters other than letters, digits and `_` become `_`, and a name starting with a digit gets a leading `_`). Name the node after the table it produces and the bare form is enough; write the full target when the table's name differs from the node's, and use that same name in every downstream `// on` and read.\n\nWrite strategy:\n\n- no option → **replace** the whole table each run (full refresh; the only mode whose output columns may change);\n- `// materialize append` → INSERT-append rows (incremental);\n- `// materialize key=` → merge/upsert on ``.\n\n`// materialize manual ` opts **out** of managed writes — the script writes its own DDL and the annotation only records the output asset for lineage.\n\n`materialize` pairs with partitioning for incremental pipelines: a `// partitioned ` node runs **once per partition** (append/merge into a fixed-schema table). The `{partition}` token, usable in any asset URI **and** in the body SQL, is replaced at run time by the current partition's **identity string**:\n\n- To filter the source to the active slice on a time grain, use the runtime-injected macro: `WHERE wm_partition() = {partition}`. `wm_partition(ts)` buckets a timestamp in exactly the identity format the runtime uses for daily/hourly/weekly/monthly, so it always matches; never hand-write a `strftime` format.\n- Do NOT write `= TIMESTAMP {partition}`: the identity string is not a valid timestamp literal for hourly/weekly/monthly and errors at run time.\n- For `dynamic` partitioning the identity is the caller-supplied key (not a timestamp, no macro), so filter on it directly: `WHERE = {partition}`.\n\n`materialize` is an output **declaration** on a node — not a command. There is no \"materialize run\".\n\n## Declared metrics (`measure` / `dimension`)\n\nOn a node that materializes a DuckLake table, `// measure = [where ]` names the canonical way to aggregate that table (e.g. `// measure revenue = sum(amount) where not is_refund`), and `// dimension = ` names a way to slice it (e.g. `// dimension region = region`, `// dimension month = date_trunc('month', ordered_at)`). They execute nothing: they are catalogued at deploy so the editor and other agents reuse the definition instead of re-deriving it and silently disagreeing.\n\n- Keep the predicate in the `where` clause rather than folding it into the aggregate: it is rendered as ` FILTER (WHERE )`, which is what lets two measures with different predicates share one GROUP BY.\n- DuckLake-only, and only meaningful next to `// materialize`.\n- Declare one when a number carries a judgement call someone else would get wrong (refunds excluded, test rows dropped, which column is the amount); do NOT blanket every table with measures — an obvious `count(*)` earns nothing.\n- To use a metric another node declares, read that node and reuse its exact expression rather than guessing it.\n\n## How to build one\n\n1. Put every node in the **same folder**: `f//`. The folder is the pipeline.\n2. Write each node as its own script. Default to `duckdb` materializing into DuckLake (see \"Default to DuckDB + DuckLake\" above); pick `postgresql`, `bun`, or `python3` only when that section says the work calls for it.\n3. Start each body with `// pipeline`, then the `// on` input declarations, then the transform that writes the output.\n4. **Chain nodes by asset URI**: read an upstream node's output asset, then `// on ` in the downstream node so the edge forms. Reuse exact asset paths from existing nodes rather than inventing parallel ones.\n5. Never guess the columns of a file or table you have not seen: read them first with a query that writes nothing, such as `DESCRIBE SELECT * FROM read_csv('s3:///raw/orders/*.csv')` or `ATTACH 'ducklake://main' AS lake; DESCRIBE lake.orders`, and use those exact column names. A test run of a node that materializes a table writes that table into the workspace's lake: test-run such a node only while its table does not exist yet, and ask before running one that would replace a table already there.\n6. Don't deploy nodes unless the user asks to. A pipeline only \"runs\" once its scripts are deployed and their triggers exist.\n\n## Example (DuckDB → DuckLake, scheduled ingest + downstream transform)\n\nNode `f/sales/orders_ingest` (runs on a schedule, materializes a DuckLake table):\n\n```sql\n-- pipeline\n-- on schedule\n-- materialize ducklake://main/orders\nSELECT * FROM read_csv('s3:///raw/orders/*.csv')\n```\n\nNode `f/sales/orders_daily` (runs when `orders` is produced, writes a rollup):\n\n```sql\n-- pipeline\n-- on ducklake://main/orders\n-- materialize ducklake://main/orders_daily\nATTACH 'ducklake://main' AS lake;\nSELECT date_trunc('day', ts) AS day, count(*) AS n\nFROM lake.orders GROUP BY 1\n```\n\nA node reads a DuckLake table only through a lake it attaches itself (`ATTACH 'ducklake://' AS lake;`, then `lake.
`); the materialize target is attached by the runtime under a name of its own, so `ducklake.main.
` does not resolve.\n", - "workspace_settings": "# Workspace settings\n\nEverything an admin sets on the Workspace settings page is one document: a mapping of top-level\nkeys, the same layout as the `settings.yaml` file `wmill sync` keeps. Only a workspace admin can\nread or change it.\n\n## Applying a document\n\n- A partial document changes only the keys it states; every key it omits is left as it is.\n- Each key is replaced whole, so read its current value and send it back edited: a nested object\n given with one field replaces the stored object with that one field.\n- A key set to `null` clears that setting; an on/off switch cleared this way reads as `false`.\n- Each setting is written through the same path the settings page uses, with the same validation\n and audit log. The writes are not one transaction: when one fails the apply stops, and the\n error says what was already written.\n- A dry run reports the changes, as `before` / `after` per key, without writing anything.\n- `name` is never applied: rename a workspace on the settings page. `color` is applied only when\n set to a value, so `null` does not clear it.\n- A key the server does not know is ignored and named in the warnings: check them, since a typo\n otherwise reads as \"nothing to change\".\n- A setting this edition does not offer (Enterprise only) is refused, by the dry run too.\n\n## Secrets\n\n`slack_oauth_client_secret` is the one secret. A read shows `__SENSITIVE_AND_UNCHANGED__` in place\nof a set secret; sending that placeholder back keeps the stored value. A value starting with\n`$encrypted:` is decrypted with the workspace key, and one encrypted with another workspace's key\nis left unchanged with a warning; any other value is taken as plaintext. Never\nwrite a secret you were not given: keep the placeholder.\n\n## Keys\n\n| Key | Value |\n|---|---|\n| `auto_invite` | `{ enabled, mode: invite \\| add, operator, instance_groups?, instance_groups_roles? }`. The instance groups are managed only when `instance_groups` is stated; clearing a group removes the members it added. |\n| `error_handler` / `success_handler` | `{ path, extra_args?, muted_on_cancel?, muted_on_user_path? }`, `path` being `script/` or `flow/`. |\n| `error_handler_fallback_to_instance_alerts` | Report failures to the instance critical alert channels when no error handler is set. |\n| `webhook` | URL POSTed a JSON event on every change to the workspace's items. |\n| `ai_config` | Providers, default and completion models, custom prompts, `copilot_disabled`. |\n| `large_file_storage` | Workspace object storage: `{ type, s3_resource_path \\| azure_blob_resource_path \\| gcs_resource_path, public_resource?, secondary_storage?, advanced_permissions? }`. |\n| `git_sync` | `{ repositories: [...] }`, each with `git_repo_resource_path`, `script_path` and `settings` (include/exclude paths and types). Server-owned fields (webhook secrets, sync state, credentials) are never read nor written. |\n| `datatable` | `{ datatables: { : { database: { resource_type, resource_path } } } }`, both required: `resource_type: postgresql` with `resource_path` a Postgres resource's path, or `instance`, or `external_instance` (Enterprise only), with `resource_path` the name of a database a superadmin set up. A fork's entry can instead be `{ reference: { workspace_id, datatable } }`, pointing at its parent's data table; keep it as is. `main` is the one scripts use by default. Role permissions are `datatable_permissions`. |\n| `datatable_permissions` | `{ : { default_role, roles: { : [tenants] } } }`: who may connect to each data table as which role. Tenants are `u/`, `g/`, `f/` or `*`; `admin` is always a role, and `default_role: null` means no default. A data table the value omits is no longer under roles. Only a data table on a cluster Windmill manages can be. |\n| `protection_rules` | `{ : { rules: [...], bypass_groups: [...], bypass_users: [...], fork_role_mapping?: { : } } }`, rules among `DisableDirectDeployment`, `DisableWorkspaceForking`, `RestrictDeployToDeployers`, `RestrictAnonymousAppDeployment`, `RestrictPublicRunSharing`, `RestrictGuestAppDeployment`, `RequireIsolatedForks`. A rule the value omits is deleted. The dev workspace lock is not listed and cannot be set here. |\n| `ducklake` | `{ ducklakes: { : { catalog, storage, ... } } }`. |\n| `dbt_warehouses` | dbt warehouse connections. |\n| `default_app` | Path of the app shown as the workspace home. |\n| `default_scripts` | `{ order?, hidden?, default_script_content? }` for the script language picker. |\n| `deploy_ui` | `{ include_path?, include_type? }`: what the deploy-to-workspace UI offers. |\n| `role_overrides` | `{ : { label?, capabilities, workspace_only? } }`: the workspace's overrides of the instance's roles, and with `workspace_only: true` a role of this workspace only (Enterprise). A role the value omits loses its override. Overriding a role the instance does not define is refused. Edit operator rights in `role_overrides.operator`. |\n| `operator_settings` | Legacy view of the `operator` role, kept for older servers: page visibility flags (`runs`, `schedules`, `resources`, `variables`, `assets`, `audit_logs`, `groups`, `folders`, `workers`, `triggers`) and write rights (`manage_schedules`, `manage_triggers`, `builder_flows`, `builder_apps`). Not applied when the document also states `role_overrides`. |\n| `mute_critical_alerts` | Mute the workspace's critical alerts. |\n| `slack_team_id`, `slack_name` | Read only: set by connecting Slack on the settings page. |\n| `slack_command_script` / `teams_command_script` | Script or flow handling the Slack / Teams command. |\n| `slack_oauth_client_id` / `slack_oauth_client_secret` | The workspace's own Slack OAuth app. Clearing either removes both. |\n| `public_app_execution_limit_per_minute` | Rate limit for public apps, `null` for none. |\n| `guest_jwt_public_key`, `guest_jwt_jwks_url` | The key that signs guest JWTs for apps set to Guests. |\n| `add_admins_and_developers_to_forks` | Add the workspace's admins and developers to each fork. |\n| `color` | Workspace color, `#rrggbb`. |\n" + "workspace_settings": "# Workspace settings\n\nEverything an admin sets on the Workspace settings page is one document: a mapping of top-level\nkeys, the same layout as the `settings.yaml` file `wmill sync` keeps. Only a workspace admin can\nread or change it.\n\n## Applying a document\n\n- A partial document changes only the keys it states; every key it omits is left as it is.\n- Each key is replaced whole, so read its current value and send it back edited: a nested object\n given with one field replaces the stored object with that one field.\n- A key set to `null` clears that setting; an on/off switch cleared this way reads as `false`.\n- Each setting is written through the same path the settings page uses, with the same validation\n and audit log. The writes are not one transaction: when one fails the apply stops, and the\n error says what was already written.\n- A dry run reports the changes, as `before` / `after` per key, without writing anything.\n- `name` is never applied: rename a workspace on the settings page. `color` is applied only when\n set to a value, so `null` does not clear it.\n- A key the server does not know is ignored and named in the warnings: check them, since a typo\n otherwise reads as \"nothing to change\".\n- A setting this edition does not offer (Enterprise only) is refused, by the dry run too.\n\n## Secrets\n\n`slack_oauth_client_secret` is the one secret. A read shows `__SENSITIVE_AND_UNCHANGED__` in place\nof a set secret; sending that placeholder back keeps the stored value. A value starting with\n`$encrypted:` is decrypted with the workspace key, and one encrypted with another workspace's key\nis left unchanged with a warning; any other value is taken as plaintext. Never\nwrite a secret you were not given: keep the placeholder.\n\n## Keys\n\n| Key | Value |\n|---|---|\n| `auto_invite` | `{ enabled, mode: invite \\| add, operator, instance_groups?, instance_groups_roles? }`. The instance groups are managed only when `instance_groups` is stated; clearing a group removes the members it added. |\n| `error_handler` / `success_handler` | `{ path, extra_args?, muted_on_cancel?, muted_on_user_path? }`, `path` being `script/` or `flow/`. |\n| `error_handler_fallback_to_instance_alerts` | Report failures to the instance critical alert channels when no error handler is set. |\n| `webhook` | URL POSTed a JSON event on every change to the workspace's items. |\n| `ai_config` | Providers, default and completion models, custom prompts, `copilot_disabled`. |\n| `large_file_storage` | Workspace object storage: `{ type, s3_resource_path \\| azure_blob_resource_path \\| gcs_resource_path, public_resource?, secondary_storage?, advanced_permissions? }`. |\n| `git_sync` | `{ repositories: [...] }`, each with `git_repo_resource_path`, `script_path` and `settings` (include/exclude paths and types). Server-owned fields (webhook secrets, sync state, credentials) are never read nor written. |\n| `datatable` | `{ datatables: { : { database: { resource_type, resource_path } } } }`, both required: `resource_type: postgresql` with `resource_path` a Postgres resource's path, or `instance`, or `external_instance` (Enterprise only), with `resource_path` the name of a database a superadmin set up. A fork's entry can instead be `{ reference: { workspace_id, datatable } }`, pointing at its parent's data table; keep it as is. `main` is the one scripts use by default. Role permissions are `datatable_permissions`. |\n| `datatable_permissions` | `{ : { default_role, roles: { : [tenants] } } }`: who may connect to each data table as which role. Tenants are `u/`, `g/`, `f/` or `*`; `admin` is always a role, and `default_role: null` means no default. A data table the value omits is no longer under roles. Only a data table on a cluster Windmill manages can be. |\n| `protection_rules` | `{ : { rules: [...], bypass_groups: [...], bypass_users: [...], fork_role_mapping?: { : } } }`, rules among `DisableDirectDeployment`, `DisableWorkspaceForking`, `RestrictDeployToDeployers`, `RestrictAnonymousAppDeployment`, `RestrictPublicRunSharing`, `RestrictGuestAppDeployment`, `RequireIsolatedForks`. A rule the value omits is deleted. The dev workspace lock is not listed and cannot be set here. |\n| `ducklake` | `{ ducklakes: { : { catalog, storage, ... } } }`. |\n| `dbt_warehouses` | dbt warehouse connections. |\n| `default_app` | Path of the app shown as the workspace home. |\n| `default_scripts` | `{ order?, hidden?, default_script_content? }` for the script language picker. |\n| `deploy_ui` | `{ include_path?, include_type? }`: what the deploy-to-workspace UI offers. |\n| `role_overrides` | `{ : { label?, capabilities, workspace_only? } }`: the workspace's overrides of the instance's roles, and with `workspace_only: true` a role of this workspace only (Enterprise). A role the value omits loses its override. Overriding a role the instance does not define is refused. Edit operator rights in `role_overrides.operator`. |\n| `operator_settings` | Legacy view of the `operator` role, kept for older servers: page visibility flags (`runs`, `schedules`, `resources`, `variables`, `assets`, `audit_logs`, `groups`, `folders`, `workers`, `triggers`) and write rights (`manage_schedules`, `manage_triggers`, `builder_flows`, `builder_apps`). Not applied when the document also states `role_overrides`. |\n| `mute_critical_alerts` | Mute the workspace's critical alerts. |\n| `slack_team_id`, `slack_name` | Read only: set by connecting Slack on the settings page. |\n| `slack_command_script` / `teams_command_script` | Script or flow handling the Slack / Teams command. |\n| `slack_oauth_client_id` / `slack_oauth_client_secret` | The workspace's own Slack OAuth app. Clearing either removes both. |\n| `public_app_execution_limit_per_minute` | Rate limit for public apps, `null` for none. |\n| `guest_jwt_public_key`, `guest_jwt_jwks_url` | The key that signs guest JWTs for apps set to Guests. |\n| `add_admins_and_developers_to_forks` | Add the workspace's admins and developers to each fork. |\n| `color` | Workspace color, `#rrggbb`. |\n", + "display": "# Rich results\n\nWindmill renders a script's or flow's return value according to its shape: on run pages, in the\nscript and flow editors, in app result displays and in AI chat run cards. Anything that matches none\nof the shapes below is shown as JSON.\n\n## Shapes\n\n- `{ \"table-row-object\": [{...}, ...] }`, or a bare array of objects: a table whose columns are the\n union of the objects' keys.\n- `{ \"table-col\": { \"col\": [...], ... } }`, or a bare object of equal-length arrays: a table built\n column by column.\n- `{ \"table-row\": [[\"col\", ...], [v, ...], ...] }`: a table whose first row holds the column names.\n- `{ \"chart\": {...} }`: a bar, line, pie or scatter chart drawn from rows (schema below). A `chart`\n value the schema rejects is shown as JSON, not as a broken chart.\n- `{ \"markdown\": \"...\" }` (or `md`): rendered markdown.\n- `{ \"html\": \"...\" }`: sanitized HTML.\n- `{ \"png\": \"\" }`, likewise `jpeg`, `gif`, `svg`: an image. `{ \"pdf\": \"\" }`: a PDF.\n- `{ \"file\": \"\", \"filename\": \"report.csv\" }`: a download.\n- `{ \"map\": { \"lat\": 0, \"lon\": 0, \"zoom\": 3, \"markers\": [{ \"lat\": 0, \"lon\": 0, \"title\": \"...\" }] } }`:\n a map.\n- `{ \"s3\": \"path/to/key\" }`: an object in the workspace storage, previewed by type.\n- `{ \"render_all\": [ ... ] }`: each item rendered in turn with the rules above.\n\nEach shape is an object with that one key (plus `filename` for a file, and an optional `storage` for\n`s3`). A result carrying any other key beside it is shown as JSON.\n\n## Choosing one\n\nA chart answers a question at a glance: a trend over time (line), a comparison across categories\n(bar), parts of a whole with few parts (pie), or a relation between two numbers (scatter). A table\nanswers lookups and holds the exact values. When both help, return both in a `render_all`: the chart\nfirst, then the table of the same rows.\n\nKeep a chart to what it shows well: at most 8 series. A pie with more than 8 slices keeps the 7\nlargest and folds the rest into \"Other\", so prefer a bar chart for many categories. Aggregate before\ncharting: a chart of thousands of raw points says less than one of the totals per day.\n\n\n### Chart and table schema\n\nA chart or table value, as JSON Schema. Beyond it: `x` and every `y` must be columns of `data`, `y` columns hold numbers, a scatter chart's `x` column holds numbers, and a pie chart takes exactly one `y`.\n\n```json\n{\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"anyOf\":[{\"anyOf\":[{\"type\":\"object\",\"properties\":{\"chart\":{\"type\":\"object\",\"properties\":{\"type\":{\"description\":\"bar or line for categories or time, pie for parts of a whole, scatter for two numeric columns\",\"type\":\"string\",\"enum\":[\"bar\",\"line\",\"pie\",\"scatter\"]},\"title\":{\"type\":\"string\"},\"data\":{\"description\":\"The rows to plot, the same shape as a table-row-object result\",\"minItems\":1,\"maxItems\":5000,\"type\":\"array\",\"items\":{\"description\":\"One row: column name to value (string, number, boolean or null)\",\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{\"anyOf\":[{\"type\":\"string\"},{\"type\":\"number\"},{\"type\":\"boolean\"},{\"type\":\"null\"}]}}},\"x\":{\"description\":\"Column holding the category, label or date of each row (bar, line, pie), or the numeric x value (scatter)\",\"type\":\"string\"},\"y\":{\"description\":\"Numeric column, or columns, to plot: one series each. A pie takes exactly one\",\"anyOf\":[{\"type\":\"string\"},{\"minItems\":1,\"maxItems\":8,\"type\":\"array\",\"items\":{\"type\":\"string\"}}]},\"stacked\":{\"description\":\"bar and line: stack the series\",\"type\":\"boolean\"},\"horizontal\":{\"description\":\"bar: draw the bars horizontally\",\"type\":\"boolean\"},\"x_label\":{\"type\":\"string\"},\"y_label\":{\"type\":\"string\"}},\"required\":[\"type\",\"data\",\"x\",\"y\"],\"additionalProperties\":false}},\"required\":[\"chart\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"table-row-object\":{\"description\":\"Rows as objects; the columns are the union of their keys\",\"minItems\":1,\"maxItems\":5000,\"type\":\"array\",\"items\":{\"description\":\"One row: column name to value (string, number, boolean or null)\",\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{\"anyOf\":[{\"type\":\"string\"},{\"type\":\"number\"},{\"type\":\"boolean\"},{\"type\":\"null\"}]}}}},\"required\":[\"table-row-object\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"table-col\":{\"description\":\"Columns: column name to its values, all the same length\",\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{\"maxItems\":5000,\"type\":\"array\",\"items\":{\"anyOf\":[{\"type\":\"string\"},{\"type\":\"number\"},{\"type\":\"boolean\"},{\"type\":\"null\"}]}}}},\"required\":[\"table-col\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"table-row\":{\"description\":\"Rows as arrays; the first row holds the column names\",\"minItems\":2,\"maxItems\":5000,\"type\":\"array\",\"items\":{\"type\":\"array\",\"items\":{\"anyOf\":[{\"type\":\"string\"},{\"type\":\"number\"},{\"type\":\"boolean\"},{\"type\":\"null\"}]}}}},\"required\":[\"table-row\"],\"additionalProperties\":false}]},{\"type\":\"object\",\"properties\":{\"render_all\":{\"description\":\"Several items shown one after another\",\"minItems\":1,\"maxItems\":10,\"type\":\"array\",\"items\":{\"anyOf\":[{\"type\":\"object\",\"properties\":{\"chart\":{\"type\":\"object\",\"properties\":{\"type\":{\"description\":\"bar or line for categories or time, pie for parts of a whole, scatter for two numeric columns\",\"type\":\"string\",\"enum\":[\"bar\",\"line\",\"pie\",\"scatter\"]},\"title\":{\"type\":\"string\"},\"data\":{\"description\":\"The rows to plot, the same shape as a table-row-object result\",\"minItems\":1,\"maxItems\":5000,\"type\":\"array\",\"items\":{\"description\":\"One row: column name to value (string, number, boolean or null)\",\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{\"anyOf\":[{\"type\":\"string\"},{\"type\":\"number\"},{\"type\":\"boolean\"},{\"type\":\"null\"}]}}},\"x\":{\"description\":\"Column holding the category, label or date of each row (bar, line, pie), or the numeric x value (scatter)\",\"type\":\"string\"},\"y\":{\"description\":\"Numeric column, or columns, to plot: one series each. A pie takes exactly one\",\"anyOf\":[{\"type\":\"string\"},{\"minItems\":1,\"maxItems\":8,\"type\":\"array\",\"items\":{\"type\":\"string\"}}]},\"stacked\":{\"description\":\"bar and line: stack the series\",\"type\":\"boolean\"},\"horizontal\":{\"description\":\"bar: draw the bars horizontally\",\"type\":\"boolean\"},\"x_label\":{\"type\":\"string\"},\"y_label\":{\"type\":\"string\"}},\"required\":[\"type\",\"data\",\"x\",\"y\"],\"additionalProperties\":false}},\"required\":[\"chart\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"table-row-object\":{\"description\":\"Rows as objects; the columns are the union of their keys\",\"minItems\":1,\"maxItems\":5000,\"type\":\"array\",\"items\":{\"description\":\"One row: column name to value (string, number, boolean or null)\",\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{\"anyOf\":[{\"type\":\"string\"},{\"type\":\"number\"},{\"type\":\"boolean\"},{\"type\":\"null\"}]}}}},\"required\":[\"table-row-object\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"table-col\":{\"description\":\"Columns: column name to its values, all the same length\",\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{\"maxItems\":5000,\"type\":\"array\",\"items\":{\"anyOf\":[{\"type\":\"string\"},{\"type\":\"number\"},{\"type\":\"boolean\"},{\"type\":\"null\"}]}}}},\"required\":[\"table-col\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"table-row\":{\"description\":\"Rows as arrays; the first row holds the column names\",\"minItems\":2,\"maxItems\":5000,\"type\":\"array\",\"items\":{\"type\":\"array\",\"items\":{\"anyOf\":[{\"type\":\"string\"},{\"type\":\"number\"},{\"type\":\"boolean\"},{\"type\":\"null\"}]}}}},\"required\":[\"table-row\"],\"additionalProperties\":false}]}}},\"required\":[\"render_all\"],\"additionalProperties\":false}]}\n```\n\nBar chart, one series per y column:\n\n```json\n{\n \"chart\": {\n \"type\": \"bar\",\n \"title\": \"Runs per day\",\n \"data\": [\n {\n \"day\": \"2026-11-10\",\n \"success\": 42,\n \"failure\": 3\n },\n {\n \"day\": \"2026-11-11\",\n \"success\": 51,\n \"failure\": 1\n }\n ],\n \"x\": \"day\",\n \"y\": [\n \"success\",\n \"failure\"\n ],\n \"stacked\": true\n }\n}\n```\n\nPie chart (exactly one y column):\n\n```json\n{\n \"chart\": {\n \"type\": \"pie\",\n \"data\": [\n {\n \"language\": \"python3\",\n \"scripts\": 18\n },\n {\n \"language\": \"bun\",\n \"scripts\": 25\n }\n ],\n \"x\": \"language\",\n \"y\": \"scripts\"\n }\n}\n```\n\nA chart and a table together:\n\n```json\n{\n \"render_all\": [\n {\n \"chart\": {\n \"type\": \"line\",\n \"data\": [\n {\n \"hour\": \"10:00\",\n \"p95_ms\": 120\n },\n {\n \"hour\": \"11:00\",\n \"p95_ms\": 180\n }\n ],\n \"x\": \"hour\",\n \"y\": \"p95_ms\",\n \"y_label\": \"ms\"\n }\n },\n {\n \"table-row-object\": [\n {\n \"hour\": \"10:00\",\n \"p95_ms\": 120,\n \"jobs\": 310\n },\n {\n \"hour\": \"11:00\",\n \"p95_ms\": 180,\n \"jobs\": 402\n }\n ]\n }\n ]\n}\n```\n" } } diff --git a/backend/windmill-api/src/ai_session_tools/gen/tools.json b/backend/windmill-api/src/ai_session_tools/gen/tools.json index 81b779088f..55ee6a8b01 100644 --- a/backend/windmill-api/src/ai_session_tools/gen/tools.json +++ b/backend/windmill-api/src/ai_session_tools/gen/tools.json @@ -216,7 +216,7 @@ "type": "object", "properties": { "subject": { - "description": "What to get authoring instructions for: a workspace item type (script, flow, resource, app), \"agent\" for a saved AI agent (an `ai_agent` resource, as the Agents page lists it), \"pipeline\" for building a data pipeline (a DAG of annotated scripts wired by storage assets — NOT a flow), or \"datatable\" for how data tables work (schema changes and migrations, roles and permissions) plus the wmill.datatable() SQL SDK used inside runnables, or \"workspace_settings\" for the keys and rules of the workspace settings (admins only). Schedules, triggers, and variables don't need instructions — their tool schemas describe everything.", + "description": "What to get authoring instructions for: a workspace item type (script, flow, resource, app), \"agent\" for a saved AI agent (an `ai_agent` resource, as the Agents page lists it), \"pipeline\" for building a data pipeline (a DAG of annotated scripts wired by storage assets — NOT a flow), or \"datatable\" for how data tables work (schema changes and migrations, roles and permissions) plus the wmill.datatable() SQL SDK used inside runnables, \"workspace_settings\" for the keys and rules of the workspace settings (admins only), or \"display\" for the tables and charts a return value renders as. Schedules, triggers, and variables don't need instructions — their tool schemas describe everything.", "type": "string", "enum": [ "script", @@ -226,7 +226,8 @@ "agent", "datatable", "pipeline", - "workspace_settings" + "workspace_settings", + "display" ] }, "language": { diff --git a/cli/src/guidance/skills.gen.ts b/cli/src/guidance/skills.gen.ts index 5f6be1e3ca..d9a12db577 100644 --- a/cli/src/guidance/skills.gen.ts +++ b/cli/src/guidance/skills.gen.ts @@ -37,6 +37,7 @@ export const SKILLS: SkillMetadata[] = [ { name: "write-pipeline", description: "MUST use when creating or modifying a data pipeline, a set of scripts marked `pipeline` and wired together by `on` / `materialize` annotations." }, { name: "datatables", description: "MUST use when changing a data table's schema, writing or running its migrations, or working with its roles and permissions." }, { name: "workspace-settings", description: "MUST use when reading or changing workspace settings, or the settings.yaml file `wmill sync` keeps." }, + { name: "rich-results", description: "MUST use when a script or flow should return a table, chart, markdown, image, file or map instead of plain JSON." }, { name: "cli-commands", description: "MUST use when using the CLI, including debugging job failures and inspecting run history via `wmill job`." }, { name: "preview", description: "MUST use when opening the Windmill dev page / visual preview of a flow, script, or app. Triggers on words like preview, open, navigate to, visualize, see the flow/app/script, and after writing a flow/script/app for visual verification." }, ]; @@ -8554,6 +8555,149 @@ instance groups, and the keys \`ducklake\`, \`dbt_warehouses\`, \`deploy_ui\`, \ \`datatable_permissions\` is pushed only with \`includeDatatablePermissions: true\` (or \`--include-datatable-permissions\`). A push ignores \`protection_rules\`: \`protection-rules.yaml\` and \`wmill protection-rules push\` sync them. +`, + "rich-results": `--- +name: rich-results +description: MUST use when a script or flow should return a table, chart, markdown, image, file or map instead of plain JSON. +--- + +# Rich results + +Windmill renders a script's or flow's return value according to its shape: on run pages, in the +script and flow editors, in app result displays and in AI chat run cards. Anything that matches none +of the shapes below is shown as JSON. + +## Shapes + +- \`{ "table-row-object": [{...}, ...] }\`, or a bare array of objects: a table whose columns are the + union of the objects' keys. +- \`{ "table-col": { "col": [...], ... } }\`, or a bare object of equal-length arrays: a table built + column by column. +- \`{ "table-row": [["col", ...], [v, ...], ...] }\`: a table whose first row holds the column names. +- \`{ "chart": {...} }\`: a bar, line, pie or scatter chart drawn from rows (schema below). A \`chart\` + value the schema rejects is shown as JSON, not as a broken chart. +- \`{ "markdown": "..." }\` (or \`md\`): rendered markdown. +- \`{ "html": "..." }\`: sanitized HTML. +- \`{ "png": "" }\`, likewise \`jpeg\`, \`gif\`, \`svg\`: an image. \`{ "pdf": "" }\`: a PDF. +- \`{ "file": "", "filename": "report.csv" }\`: a download. +- \`{ "map": { "lat": 0, "lon": 0, "zoom": 3, "markers": [{ "lat": 0, "lon": 0, "title": "..." }] } }\`: + a map. +- \`{ "s3": "path/to/key" }\`: an object in the workspace storage, previewed by type. +- \`{ "render_all": [ ... ] }\`: each item rendered in turn with the rules above. + +Each shape is an object with that one key (plus \`filename\` for a file, and an optional \`storage\` for +\`s3\`). A result carrying any other key beside it is shown as JSON. + +## Choosing one + +A chart answers a question at a glance: a trend over time (line), a comparison across categories +(bar), parts of a whole with few parts (pie), or a relation between two numbers (scatter). A table +answers lookups and holds the exact values. When both help, return both in a \`render_all\`: the chart +first, then the table of the same rows. + +Keep a chart to what it shows well: at most 8 series. A pie with more than 8 slices keeps the 7 +largest and folds the rest into "Other", so prefer a bar chart for many categories. Aggregate before +charting: a chart of thousands of raw points says less than one of the totals per day. + +### Chart and table schema + +A chart or table value, as JSON Schema. Beyond it: \`x\` and every \`y\` must be columns of \`data\`, \`y\` columns hold numbers, a scatter chart's \`x\` column holds numbers, and a pie chart takes exactly one \`y\`. + +\`\`\`json +{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"anyOf":[{"type":"object","properties":{"chart":{"type":"object","properties":{"type":{"description":"bar or line for categories or time, pie for parts of a whole, scatter for two numeric columns","type":"string","enum":["bar","line","pie","scatter"]},"title":{"type":"string"},"data":{"description":"The rows to plot, the same shape as a table-row-object result","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"x":{"description":"Column holding the category, label or date of each row (bar, line, pie), or the numeric x value (scatter)","type":"string"},"y":{"description":"Numeric column, or columns, to plot: one series each. A pie takes exactly one","anyOf":[{"type":"string"},{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string"}}]},"stacked":{"description":"bar and line: stack the series","type":"boolean"},"horizontal":{"description":"bar: draw the bars horizontally","type":"boolean"},"x_label":{"type":"string"},"y_label":{"type":"string"}},"required":["type","data","x","y"],"additionalProperties":false}},"required":["chart"],"additionalProperties":false},{"type":"object","properties":{"table-row-object":{"description":"Rows as objects; the columns are the union of their keys","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row-object"],"additionalProperties":false},{"type":"object","properties":{"table-col":{"description":"Columns: column name to its values, all the same length","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"maxItems":5000,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-col"],"additionalProperties":false},{"type":"object","properties":{"table-row":{"description":"Rows as arrays; the first row holds the column names","minItems":2,"maxItems":5000,"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row"],"additionalProperties":false}]},{"type":"object","properties":{"render_all":{"description":"Several items shown one after another","minItems":1,"maxItems":10,"type":"array","items":{"anyOf":[{"type":"object","properties":{"chart":{"type":"object","properties":{"type":{"description":"bar or line for categories or time, pie for parts of a whole, scatter for two numeric columns","type":"string","enum":["bar","line","pie","scatter"]},"title":{"type":"string"},"data":{"description":"The rows to plot, the same shape as a table-row-object result","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"x":{"description":"Column holding the category, label or date of each row (bar, line, pie), or the numeric x value (scatter)","type":"string"},"y":{"description":"Numeric column, or columns, to plot: one series each. A pie takes exactly one","anyOf":[{"type":"string"},{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string"}}]},"stacked":{"description":"bar and line: stack the series","type":"boolean"},"horizontal":{"description":"bar: draw the bars horizontally","type":"boolean"},"x_label":{"type":"string"},"y_label":{"type":"string"}},"required":["type","data","x","y"],"additionalProperties":false}},"required":["chart"],"additionalProperties":false},{"type":"object","properties":{"table-row-object":{"description":"Rows as objects; the columns are the union of their keys","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row-object"],"additionalProperties":false},{"type":"object","properties":{"table-col":{"description":"Columns: column name to its values, all the same length","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"maxItems":5000,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-col"],"additionalProperties":false},{"type":"object","properties":{"table-row":{"description":"Rows as arrays; the first row holds the column names","minItems":2,"maxItems":5000,"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row"],"additionalProperties":false}]}}},"required":["render_all"],"additionalProperties":false}]} +\`\`\` + +Bar chart, one series per y column: + +\`\`\`json +{ + "chart": { + "type": "bar", + "title": "Runs per day", + "data": [ + { + "day": "2026-11-10", + "success": 42, + "failure": 3 + }, + { + "day": "2026-11-11", + "success": 51, + "failure": 1 + } + ], + "x": "day", + "y": [ + "success", + "failure" + ], + "stacked": true + } +} +\`\`\` + +Pie chart (exactly one y column): + +\`\`\`json +{ + "chart": { + "type": "pie", + "data": [ + { + "language": "python3", + "scripts": 18 + }, + { + "language": "bun", + "scripts": 25 + } + ], + "x": "language", + "y": "scripts" + } +} +\`\`\` + +A chart and a table together: + +\`\`\`json +{ + "render_all": [ + { + "chart": { + "type": "line", + "data": [ + { + "hour": "10:00", + "p95_ms": 120 + }, + { + "hour": "11:00", + "p95_ms": 180 + } + ], + "x": "hour", + "y": "p95_ms", + "y_label": "ms" + } + }, + { + "table-row-object": [ + { + "hour": "10:00", + "p95_ms": 120, + "jobs": 310 + }, + { + "hour": "11:00", + "p95_ms": 180, + "jobs": 402 + } + ] + } + ] +} +\`\`\` `, "cli-commands": `--- name: cli-commands diff --git a/docs/feature-telemetry.md b/docs/feature-telemetry.md index 0589d79b16..773f489fda 100644 --- a/docs/feature-telemetry.md +++ b/docs/feature-telemetry.md @@ -4,7 +4,7 @@ anonymous usage-stats payload. It answers "does anyone use this, and which variant do they pick" without any identifying data leaving the instance. -It currently carries 100 registered actions across forty features (`access_view`, `ai_session`, `ai_chat`, +It currently carries 102 registered actions across forty features (`access_view`, `ai_session`, `ai_chat`, `ai_fix`, `ai_agent`, `ai_decision`, `ai_agent_eval`, `app_sandbox`, `datatable`, `db_manager`, `flow_editor`, `flow_run`, `flow_step`, `home`, `header_nav`, `run_form`, `sharing`, `debugger`, `trigger`, `command_script`, `mcp`, `mcp_workspace`, `mcp_external_client`, `hub_script`, `usage_meter`, `sso_groups_claim`, diff --git a/frontend/package.json b/frontend/package.json index 43f3ddcc33..eb967a8d47 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -17,6 +17,7 @@ "package": "svelte-package -o package && node scripts/package-system-prompts.js && node scripts/fix-svelte-module-imports.js", "generate-backend-client": "openapi-ts --input ../backend/windmill-api/openapi.yaml --output ./src/lib/gen --useOptions --enums javascript --format false", "generate-backend-client-mac": "openapi-ts --input ../backend/windmill-api/openapi.yaml --output ./src/lib/gen --useOptions --enums javascript", + "gen:display-catalog": "WM_GEN_DISPLAY_CATALOG=1 vitest run --project server src/lib/components/display/displayCatalogGen.test.ts", "gen:mcp-session": "WM_GEN_MCP_SESSION=1 vitest run --project server src/lib/components/copilot/chat/global/mcpSessionGen.test.ts", "pretest": "tsc --incremental -p tests/tsconfig.json", "filter-classes": "node filterTailwindClasses.js", diff --git a/frontend/src/lib/components/DisplayResult.svelte b/frontend/src/lib/components/DisplayResult.svelte index afadcb5741..f04c48faa0 100644 --- a/frontend/src/lib/components/DisplayResult.svelte +++ b/frontend/src/lib/components/DisplayResult.svelte @@ -38,6 +38,8 @@ import ToggleButtonGroup from './common/toggleButton-v2/ToggleButtonGroup.svelte' import ToggleButton from './common/toggleButton-v2/ToggleButton.svelte' import MapResult from './MapResult.svelte' + import ChartResult from './display/ChartResult.svelte' + import { isChartResult } from './display/displayCatalog' import DownloadCsv from './table/DownloadCsv.svelte' import { convertJsonToCsv } from './table/tableUtils' import Tooltip from './Tooltip.svelte' @@ -89,6 +91,7 @@ | 'nondisplayable' | 'pdf' | 'aiagent' + | 'chart' | undefined let resultKind: ResultKind = $state() /** Kinds whose renderer leaves the page: S3/ducklake previews fetch the file or @@ -378,7 +381,11 @@ } if (keys.length != 0) { - if ( + // Only a chart the catalog accepts: any other `{ chart }` result stays JSON. The + // catalog caps its rows, so it is exempt from the display size limit. + if (keys.length == 1 && keys[0] === 'chart' && isChartResult(result)) { + return 'chart' + } else if ( keys.length == 1 && [...IMG_KINDS, 'html', 'map', 'pdf', 'file', 'error'].includes(keys[0]) ) { @@ -907,6 +914,8 @@ {@html renderResultMarkup(result.html)} {/if} + {:else if !forceJson && resultKind === 'chart'} + {:else if !forceJson && resultKind === 'map'}
void applyButtonIcon?: typeof ClipboardCopy renderMermaid?: boolean lightMermaid?: boolean + renderDisplay?: boolean + staticDisplay?: boolean } = $props() const astNode = getAstNode() @@ -124,7 +131,10 @@ ) let language = $derived( - (astNode.current.children?.[0]?.properties?.class as string | undefined)?.split('-')[1] + (astNode.current.children?.[0]?.properties?.class as string | undefined) + ?.split(' ') + .find((c) => c.startsWith('language-')) + ?.slice('language-'.length) ) let smartLang = $derived(getSmartLang(language)) @@ -135,6 +145,14 @@
{#if renderMermaid && language === 'mermaid'} + {:else if renderDisplay && language === 'wm-display'} + + {#await import('./display/DisplayFence.svelte')} +
+ {:then { default: DisplayFence }} + + {/await} {:else} - - + + diff --git a/frontend/src/lib/components/copilot/chat/artifacts/DisplayCodeBlock.svelte b/frontend/src/lib/components/copilot/chat/artifacts/DisplayCodeBlock.svelte new file mode 100644 index 0000000000..d9a0fc6fa3 --- /dev/null +++ b/frontend/src/lib/components/copilot/chat/artifacts/DisplayCodeBlock.svelte @@ -0,0 +1,7 @@ + + + + diff --git a/frontend/src/lib/components/copilot/chat/artifacts/MermaidCodeBlock.svelte b/frontend/src/lib/components/copilot/chat/artifacts/MermaidCodeBlock.svelte index 76756ab5b0..c993831c80 100644 --- a/frontend/src/lib/components/copilot/chat/artifacts/MermaidCodeBlock.svelte +++ b/frontend/src/lib/components/copilot/chat/artifacts/MermaidCodeBlock.svelte @@ -2,5 +2,6 @@ import MarkdownCodeBlock from '$lib/components/MarkdownCodeBlock.svelte' - - + + diff --git a/frontend/src/lib/components/copilot/chat/artifacts/artifactExport.ts b/frontend/src/lib/components/copilot/chat/artifacts/artifactExport.ts index 9f588194a5..0c3f81425b 100644 --- a/frontend/src/lib/components/copilot/chat/artifacts/artifactExport.ts +++ b/frontend/src/lib/components/copilot/chat/artifacts/artifactExport.ts @@ -216,8 +216,19 @@ async function drawDiagrams(html: string): Promise { return template.innerHTML } +/** `html` with its ```wm-display fences drawn as images and tables. */ +async function drawDisplays(html: string): Promise { + if (!html.includes('language-wm-display')) return html + // Built in the template's inert document, like the diagrams. + const template = document.createElement('template') + template.innerHTML = html + const { drawDisplayFences } = await import('$lib/components/display/displayExport') + await drawDisplayFences(template.content) + return template.innerHTML +} + /** The page a download gets: `artifactHtmlDocument` with its diagrams drawn and fonts embedded. */ export async function artifactHtmlFile(name: string, content: string): Promise { - const html = await drawDiagrams(renderArtifactHtml(content)) + const html = await drawDisplays(await drawDiagrams(renderArtifactHtml(content))) return htmlPage(name, html, { fontCss: await artifactFontCss(html) }) } diff --git a/frontend/src/lib/components/copilot/chat/artifacts/printArtifact.ts b/frontend/src/lib/components/copilot/chat/artifacts/printArtifact.ts index a64b2b02f0..d315d9c1cc 100644 --- a/frontend/src/lib/components/copilot/chat/artifacts/printArtifact.ts +++ b/frontend/src/lib/components/copilot/chat/artifacts/printArtifact.ts @@ -120,12 +120,13 @@ async function imagesSettled(doc: Document): Promise { await Promise.race([Promise.all(pending), new Promise((resolve) => setTimeout(resolve, 10_000))]) } -/** Mermaid draws asynchronously; printing before it lands puts the diagram source in the PDF. - * A diagram that fails to parse settles too (as its source), so this waits only on renders - * still in flight; the cap covers one that never returns. */ +/** Mermaid draws asynchronously, and display blocks load their renderer on demand; printing + * before they land puts their source in the PDF. One that fails to parse settles too (as its + * source), so this waits only on renders still in flight; the cap covers one that never returns. */ async function diagramsSettled(doc: Document): Promise { const deadline = Date.now() + 10_000 - while (doc.querySelector('[data-mermaid-pending="true"]') && Date.now() < deadline) { + const pending = '[data-mermaid-pending="true"], [data-display-pending="true"]' + while (doc.querySelector(pending) && Date.now() < deadline) { await new Promise((resolve) => setTimeout(resolve, 100)) } } diff --git a/frontend/src/lib/components/copilot/chat/global/core.ts b/frontend/src/lib/components/copilot/chat/global/core.ts index ee849b890d..cd8dc25c87 100644 --- a/frontend/src/lib/components/copilot/chat/global/core.ts +++ b/frontend/src/lib/components/copilot/chat/global/core.ts @@ -94,7 +94,8 @@ import { getRawAppPrompt, getResourcePrompt, getAgentPrompt, - getScriptPrompt + getScriptPrompt, + getDisplayPrompt } from '$system_prompts' import type { ChatCompletionSystemMessageParam, @@ -283,7 +284,14 @@ const INSTRUCTION_SUBJECTS = [ // annotated scripts in a folder, so it gets authoring guidance, not a CRUD type. // `workspace_settings` is the settings document an admin reads and changes. // `agent` is a resource of type `ai_agent`, with authoring guidance of its own. -const INSTRUCTION_SUBJECTS_EXTRA = ['agent', 'datatable', 'pipeline', 'workspace_settings'] as const +// `display` is the rich-result format: tables and charts a return value renders as. +const INSTRUCTION_SUBJECTS_EXTRA = [ + 'agent', + 'datatable', + 'pipeline', + 'workspace_settings', + 'display' +] as const export const ALL_INSTRUCTION_SUBJECTS = [ ...INSTRUCTION_SUBJECTS, ...INSTRUCTION_SUBJECTS_EXTRA @@ -354,7 +362,7 @@ const scriptLangSchema = z.enum($ScriptLang.enum) const getInstructionsSchema = z.object({ subject: instructionSubjectSchema.describe( - 'What to get authoring instructions for: a workspace item type (script, flow, resource, app), "agent" for a saved AI agent (an `ai_agent` resource, as the Agents page lists it), "pipeline" for building a data pipeline (a DAG of annotated scripts wired by storage assets — NOT a flow), or "datatable" for how data tables work (schema changes and migrations, roles and permissions) plus the wmill.datatable() SQL SDK used inside runnables, or "workspace_settings" for the keys and rules of the workspace settings (admins only). Schedules, triggers, and variables don\'t need instructions — their tool schemas describe everything.' + 'What to get authoring instructions for: a workspace item type (script, flow, resource, app), "agent" for a saved AI agent (an `ai_agent` resource, as the Agents page lists it), "pipeline" for building a data pipeline (a DAG of annotated scripts wired by storage assets — NOT a flow), or "datatable" for how data tables work (schema changes and migrations, roles and permissions) plus the wmill.datatable() SQL SDK used inside runnables, "workspace_settings" for the keys and rules of the workspace settings (admins only), or "display" for the tables and charts a return value renders as. Schedules, triggers, and variables don\'t need instructions — their tool schemas describe everything.' ), language: scriptLangSchema .optional() @@ -1781,6 +1789,7 @@ ${ Rules:${draftsOnlyRule} ${findItemsRule} ${groupMembershipRule}- Listings and reads return only what this user can see: items in folders they cannot read are hidden from you both. When an item the user names is missing, say it is not among what they can see and may be in a folder they cannot read, where someone with access can run it — never state that it does not exist or is not deployed. +- To show a chart or a sortable table in a reply or an artifact, write a \`\`\`wm-display fenced block holding one JSON value in the chart or table format of get_instructions with subject "display" (read it first). Reach for it when a chart answers the question better than prose or a markdown table; keep small tables as markdown. - An agent, as the Agents page lists it, is a resource of type \`ai_agent\`: read it with read_workspace_item type "resource".${when( // An agent draft is a resource draft that the server checks under the flow builder right. canDraftResources && canWriteFlowDraft, @@ -2314,6 +2323,8 @@ export function getInstructions( return getPipelineInstructions() case 'workspace_settings': return getWorkspaceSettingsPrompt() + case 'display': + return getDisplayPrompt() } } diff --git a/frontend/src/lib/components/copilot/chat/script/CodeDisplay.svelte b/frontend/src/lib/components/copilot/chat/script/CodeDisplay.svelte index e83c163302..e3bcf42ead 100644 --- a/frontend/src/lib/components/copilot/chat/script/CodeDisplay.svelte +++ b/frontend/src/lib/components/copilot/chat/script/CodeDisplay.svelte @@ -37,4 +37,5 @@ onApplyCode={handleApplyCode} applyButtonIcon={aiChatManager.pendingNewCode ? Check : Play} renderMermaid={!chatHost.untrustedTranscript} + renderDisplay /> diff --git a/frontend/src/lib/components/display/ChartResult.svelte b/frontend/src/lib/components/display/ChartResult.svelte new file mode 100644 index 0000000000..93e5a762cf --- /dev/null +++ b/frontend/src/lib/components/display/ChartResult.svelte @@ -0,0 +1,41 @@ + + +
+ +
diff --git a/frontend/src/lib/components/display/DisplayFence.svelte b/frontend/src/lib/components/display/DisplayFence.svelte new file mode 100644 index 0000000000..ed0015a5db --- /dev/null +++ b/frontend/src/lib/components/display/DisplayFence.svelte @@ -0,0 +1,85 @@ + + +{#if parsed.ok && staticRender} +
+ {#each fenceItems(parsed.result) as item, i (i)} + {#if 'chart' in item} + + {:else} + {@const table = tableRows(item)} + +
+ + + {#each table.columns as column, c (c)}{/each} + + + + {#each table.rows as row, r (r)} + {#each row as cell, c (c)}{/each} + {/each} + +
{column}
{cell ?? ''}
+ {/if} + {/each} + +{:else if parsed.ok} +
+ +
+{:else if streaming} +
+ +
+{:else} +
+ +
{parsed.error}
+
+ +
+{/if} diff --git a/frontend/src/lib/components/display/chartConfig.ts b/frontend/src/lib/components/display/chartConfig.ts new file mode 100644 index 0000000000..f4147c480b --- /dev/null +++ b/frontend/src/lib/components/display/chartConfig.ts @@ -0,0 +1,176 @@ +import type { ChartConfiguration } from 'chart.js' +import type { ChartBody } from './displayCatalog' + +// Categorical slots in fixed order, stepped separately for each surface (validated for +// colour-vision deficiency). Never cycled: the catalog caps series and pie slices to their count. +const LIGHT = [ + '#2a78d6', + '#eb6834', + '#1baf7a', + '#eda100', + '#e87ba4', + '#008300', + '#6250d6', + '#e34948' +] +const DARK = [ + '#3987e5', + '#d95926', + '#199e70', + '#c98500', + '#d55181', + '#008300', + '#9085e9', + '#e66767' +] + +export interface ChartTheme { + dark: boolean + /** The colour behind the chart: gaps between adjacent fills are borders drawn in it. */ + surface: string +} + +function num(v: unknown): number | null { + return typeof v === 'number' ? v : null +} + +/** The chart.js configuration a catalog chart draws with, on screen and in exports alike. */ +export function chartConfig(chart: ChartBody, { dark, surface }: ChartTheme): ChartConfiguration { + const palette = dark ? DARK : LIGHT + const ink = dark ? '#c3c2b7' : '#55544f' + const grid = dark ? 'rgba(255,255,255,0.08)' : 'rgba(0,0,0,0.07)' + const ys = typeof chart.y === 'string' ? [chart.y] : chart.y + const stacked = !!chart.stacked + const labels = chart.data.map((r) => String(r[chart.x] ?? '')) + + const axis = (label: string | undefined, stack: boolean) => ({ + stacked: stack, + title: { display: !!label, text: label ?? '', color: ink }, + ticks: { color: ink }, + grid: { color: grid }, + border: { color: grid } + }) + const common = { + responsive: true, + maintainAspectRatio: false, + animation: false as const, + plugins: { + legend: { + display: chart.type === 'pie' || ys.length > 1, + position: 'bottom' as const, + labels: { color: ink, boxWidth: 10, boxHeight: 10 } + }, + title: { + display: !!chart.title, + text: chart.title ?? '', + color: ink, + align: 'start' as const, + font: { size: 13, weight: 600 as const } + } + } + } + + switch (chart.type) { + case 'bar': + return { + type: 'bar', + data: { + labels, + datasets: ys.map((y, i) => ({ + label: y, + data: chart.data.map((r) => num(r[y])), + backgroundColor: palette[i], + borderRadius: 4, + borderSkipped: stacked ? false : ('start' as const), + borderColor: surface, + borderWidth: stacked ? { top: 2 } : 0, + maxBarThickness: 48 + })) + }, + options: { + ...common, + indexAxis: chart.horizontal ? 'y' : 'x', + scales: chart.horizontal + ? { y: axis(chart.x_label, stacked), x: axis(chart.y_label, stacked) } + : { x: axis(chart.x_label, stacked), y: axis(chart.y_label, stacked) } + } + } + case 'line': + return { + type: 'line', + data: { + labels, + datasets: ys.map((y, i) => ({ + label: y, + data: chart.data.map((r) => num(r[y])), + borderColor: palette[i], + backgroundColor: palette[i], + borderWidth: 2, + pointRadius: chart.data.length > 60 ? 0 : 3, + pointHoverRadius: 5, + fill: stacked ? 'stack' : false, + tension: 0 + })) + }, + options: { + ...common, + interaction: { mode: 'index', intersect: false }, + scales: { x: axis(chart.x_label, false), y: axis(chart.y_label, stacked) } + } + } + case 'scatter': + return { + type: 'scatter', + data: { + datasets: ys.map((y, i) => ({ + label: y, + data: chart.data + .map((r) => ({ x: num(r[chart.x]), y: num(r[y]) })) + .filter((p): p is { x: number; y: number } => p.x !== null && p.y !== null), + backgroundColor: palette[i], + borderColor: surface, + borderWidth: 2, + pointRadius: 5, + pointHoverRadius: 7 + })) + }, + options: { + ...common, + scales: { x: axis(chart.x_label, false), y: axis(chart.y_label, false) } + } + } + case 'pie': { + // A pie keeps its largest slices and folds the rest into one, so no slice reuses a hue. + let slices: { label: string; value: number; other?: boolean }[] = chart.data.map((r) => ({ + label: String(r[chart.x] ?? ''), + value: num(r[ys[0]]) ?? 0 + })) + if (slices.length > palette.length) { + const sorted = [...slices].sort((a, b) => b.value - a.value) + const rest = sorted.slice(palette.length - 1).reduce((s, x) => s + x.value, 0) + slices = [ + ...sorted.slice(0, palette.length - 1), + { label: 'Other', value: rest, other: true } + ] + } + return { + type: 'pie', + data: { + labels: slices.map((s) => s.label), + datasets: [ + { + label: ys[0], + data: slices.map((s) => s.value), + backgroundColor: slices.map((s, i) => + s.other ? (dark ? '#6f6e68' : '#9b9a93') : palette[i] + ), + borderColor: surface, + borderWidth: 2 + } + ] + }, + options: common + } + } + } +} diff --git a/frontend/src/lib/components/display/displayCatalog.test.ts b/frontend/src/lib/components/display/displayCatalog.test.ts new file mode 100644 index 0000000000..057f4f776e --- /dev/null +++ b/frontend/src/lib/components/display/displayCatalog.test.ts @@ -0,0 +1,43 @@ +import { describe, expect, it } from 'vitest' +import { isChartResult, parseFence } from './displayCatalog' + +const rows = [ + { status: 'success', runs: 12 }, + { status: 'failure', runs: 3 } +] + +describe('display catalog', () => { + it('accepts a chart and reports a missing column by name', () => { + expect( + parseFence(JSON.stringify({ chart: { type: 'bar', data: rows, x: 'status', y: 'runs' } })).ok + ).toBe(true) + const bad = parseFence( + JSON.stringify({ chart: { type: 'bar', data: rows, x: 'status', y: 'count' } }) + ) + expect(bad.ok).toBe(false) + expect(!bad.ok && bad.error).toContain('column "count" is not in any row of data') + const pie = parseFence( + JSON.stringify({ chart: { type: 'pie', data: rows, x: 'status', y: ['runs', 'status'] } }) + ) + expect(!pie.ok && pie.error).toContain('a pie chart takes exactly one y column') + expect(!pie.ok && pie.error).toContain('y column "status" must hold numbers') + }) + + // The fence renders on the public shared-session page, which must issue no request. + it('rejects kinds that fetch or run markup, alone or inside render_all', () => { + for (const item of [ + { html: '' }, + { markdown: '![x](https://example.com/x.png)' }, + { s3: 'a/b.png' }, + { map: { lat: 0, lon: 0 } } + ]) { + expect(parseFence(JSON.stringify(item)).ok).toBe(false) + expect(parseFence(JSON.stringify({ render_all: [item] })).ok).toBe(false) + } + }) + + it('does not classify an arbitrary `chart` result as a chart', () => { + expect(isChartResult({ chart: 'https://example.com/chart.png' })).toBe(false) + expect(isChartResult({ chart: { type: 'bar', data: rows, x: 'status', y: 'runs' } })).toBe(true) + }) +}) diff --git a/frontend/src/lib/components/display/displayCatalog.ts b/frontend/src/lib/components/display/displayCatalog.ts new file mode 100644 index 0000000000..467ecda88e --- /dev/null +++ b/frontend/src/lib/components/display/displayCatalog.ts @@ -0,0 +1,208 @@ +import { z } from 'zod' + +/** + * The rich-result kinds a ```wm-display fence may hold, and the `chart` kind a script result may + * take. The schemas validate what the model writes, gate `chart` in `DisplayResult`, and are + * exported as JSON Schema into the model's guidance (`displayCatalog.gen.test.ts`). + * + * The fence only admits kinds that issue no request and run no markup: it renders on the public + * shared-session page, which promises to fetch nothing. Do not add `html`, `svg`, images, `map`, + * `markdown` (its images fetch), `file`, `s3object`, `approval` or `pdf` to `fenceSchema`. + */ + +export const MAX_CHART_ROWS = 5000 +/** One per categorical palette slot in `ChartResult`: a ninth series would need a cycled hue. */ +export const MAX_CHART_SERIES = 8 +export const MAX_TABLE_ROWS = 5000 + +const cell = z.union([z.string(), z.number(), z.boolean(), z.null()]) + +const row = z + .record(z.string(), cell) + .describe('One row: column name to value (string, number, boolean or null)') + +export const chartBodySchema = z + .strictObject({ + type: z + .enum(['bar', 'line', 'pie', 'scatter']) + .describe( + 'bar or line for categories or time, pie for parts of a whole, scatter for two numeric columns' + ), + title: z.string().optional(), + data: z + .array(row) + .min(1) + .max(MAX_CHART_ROWS) + .describe('The rows to plot, the same shape as a table-row-object result'), + x: z + .string() + .describe( + 'Column holding the category, label or date of each row (bar, line, pie), or the numeric x value (scatter)' + ), + y: z + .union([z.string(), z.array(z.string()).min(1).max(MAX_CHART_SERIES)]) + .describe('Numeric column, or columns, to plot: one series each. A pie takes exactly one'), + stacked: z.boolean().optional().describe('bar and line: stack the series'), + horizontal: z.boolean().optional().describe('bar: draw the bars horizontally'), + x_label: z.string().optional(), + y_label: z.string().optional() + }) + .superRefine((chart, ctx) => { + const ys = typeof chart.y === 'string' ? [chart.y] : chart.y + if (chart.type === 'pie' && ys.length !== 1) { + ctx.addIssue({ + code: 'custom', + path: ['y'], + message: 'a pie chart takes exactly one y column' + }) + } + const columns = new Set(chart.data.flatMap((r) => Object.keys(r))) + for (const [key, column] of [['x', chart.x], ...ys.map((c) => ['y', c] as const)] as const) { + if (!columns.has(column)) { + ctx.addIssue({ + code: 'custom', + path: [key], + message: `column "${column}" is not in any row of data` + }) + } + } + for (const column of ys) { + const bad = chart.data.findIndex( + (r) => r[column] !== undefined && r[column] !== null && typeof r[column] !== 'number' + ) + if (bad !== -1) { + ctx.addIssue({ + code: 'custom', + path: ['data', bad, column], + message: `y column "${column}" must hold numbers` + }) + } + } + if (chart.type === 'scatter') { + const bad = chart.data.findIndex((r) => typeof r[chart.x] !== 'number') + if (bad !== -1) { + ctx.addIssue({ + code: 'custom', + path: ['data', bad, chart.x], + message: `a scatter chart's x column "${chart.x}" must hold numbers` + }) + } + } + }) + +export type ChartBody = z.infer + +export const chartSchema = z.strictObject({ chart: chartBodySchema }) + +const tableRowObjectSchema = z.strictObject({ + 'table-row-object': z + .array(row) + .min(1) + .max(MAX_TABLE_ROWS) + .describe('Rows as objects; the columns are the union of their keys') +}) + +const tableColSchema = z.strictObject({ + 'table-col': z + .record(z.string(), z.array(cell).max(MAX_TABLE_ROWS)) + .describe('Columns: column name to its values, all the same length') +}) + +const tableRowSchema = z.strictObject({ + 'table-row': z + .array(z.array(cell)) + .min(2) + .max(MAX_TABLE_ROWS) + .describe('Rows as arrays; the first row holds the column names') +}) + +const fenceItemSchema = z.union([chartSchema, tableRowObjectSchema, tableColSchema, tableRowSchema]) + +export const fenceSchema = z.union([ + fenceItemSchema, + z.strictObject({ + render_all: z + .array(fenceItemSchema) + .min(1) + .max(10) + .describe('Several items shown one after another') + }) +]) + +export type FenceResult = z.infer +export type FenceItem = z.infer +export type FenceTable = Exclude + +/** The items a fence value renders, in order. */ +export function fenceItems(value: FenceResult): FenceItem[] { + return 'render_all' in value ? value.render_all : [value] +} + +type Cell = string | number | boolean | null + +/** The columns and rows of a catalog table value, in the order the table renders them. */ +export function tableRows(item: FenceTable): { columns: string[]; rows: Cell[][] } { + if ('table-row' in item) { + const [header, ...rows] = item['table-row'] + return { columns: header.map((c) => String(c ?? '')), rows } + } + if ('table-col' in item) { + const cols = item['table-col'] + const columns = Object.keys(cols) + const length = Math.max(0, ...columns.map((c) => cols[c].length)) + return { + columns, + rows: Array.from({ length }, (_, i) => columns.map((c) => cols[c][i] ?? null)) + } + } + const objects = item['table-row-object'] + const columns = [...new Set(objects.flatMap((o) => Object.keys(o)))] + return { columns, rows: objects.map((o) => columns.map((c) => o[c] ?? null)) } +} + +export function isChartResult(result: unknown): result is { chart: ChartBody } { + return chartSchema.safeParse(result).success +} + +/** The fence kinds, as `feature_usage` keys: a closed set. */ +export type FenceKind = 'chart' | 'table' | 'render_all' + +export function fenceKind(result: FenceResult): FenceKind { + if ('render_all' in result) return 'render_all' + if ('chart' in result) return 'chart' + return 'table' +} + +export type FenceParse = { ok: true; result: FenceResult } | { ok: false; error: string } + +export function parseFence(source: string): FenceParse { + let json: unknown + try { + json = JSON.parse(source) + } catch (e) { + return { ok: false, error: `Not valid JSON: ${(e as Error).message}` } + } + const parsed = fenceSchema.safeParse(json) + if (parsed.success) return { ok: true, result: parsed.data } + return { ok: false, error: describeFenceError(json, parsed.error) } +} + +const FENCE_KEYS = ['chart', 'table-row-object', 'table-col', 'table-row', 'render_all'] + +// A union's own error lists every branch's failure; report the branch the object's key names. +function describeFenceError(json: unknown, error: z.ZodError): string { + if (json && typeof json === 'object' && !Array.isArray(json)) { + const keys = Object.keys(json) + if (keys.length !== 1 || !FENCE_KEYS.includes(keys[0])) { + return `Expected an object with exactly one of the keys ${FENCE_KEYS.join(', ')}; got ${keys.length ? keys.join(', ') : 'no key'}` + } + const key = keys[0] + const branch = + key === 'render_all' + ? fenceSchema.options[1] + : fenceItemSchema.options.find((o) => key in o.shape) + const inner = branch?.safeParse(json) + if (inner && !inner.success) return z.prettifyError(inner.error) + } + return z.prettifyError(error) +} diff --git a/frontend/src/lib/components/display/displayCatalogGen.test.ts b/frontend/src/lib/components/display/displayCatalogGen.test.ts new file mode 100644 index 0000000000..8945ede688 --- /dev/null +++ b/frontend/src/lib/components/display/displayCatalogGen.test.ts @@ -0,0 +1,99 @@ +import { readFileSync, writeFileSync } from 'node:fs' +import { join } from 'node:path' +import { describe, expect, it } from 'vitest' +import { z } from 'zod' +import { fenceSchema } from './displayCatalog' + +// The model's guidance for charts and tables is generated from the catalog, so the schema it +// reads is the one its output is validated against. Regenerate with `npm run gen:display-catalog`. +const OUT = join(__dirname, '../../../../../system_prompts/base/display-catalog.gen.md') + +const EXAMPLES: { title: string; value: unknown }[] = [ + { + title: 'Bar chart, one series per y column', + value: { + chart: { + type: 'bar', + title: 'Runs per day', + data: [ + { day: '2026-11-10', success: 42, failure: 3 }, + { day: '2026-11-11', success: 51, failure: 1 } + ], + x: 'day', + y: ['success', 'failure'], + stacked: true + } + } + }, + { + title: 'Pie chart (exactly one y column)', + value: { + chart: { + type: 'pie', + data: [ + { language: 'python3', scripts: 18 }, + { language: 'bun', scripts: 25 } + ], + x: 'language', + y: 'scripts' + } + } + }, + { + title: 'A chart and a table together', + value: { + render_all: [ + { + chart: { + type: 'line', + data: [ + { hour: '10:00', p95_ms: 120 }, + { hour: '11:00', p95_ms: 180 } + ], + x: 'hour', + y: 'p95_ms', + y_label: 'ms' + } + }, + { + 'table-row-object': [ + { hour: '10:00', p95_ms: 120, jobs: 310 }, + { hour: '11:00', p95_ms: 180, jobs: 402 } + ] + } + ] + } + } +] + +function render(): string { + const schema = z.toJSONSchema(fenceSchema, { unrepresentable: 'any' }) + const parts = [ + '### Chart and table schema', + '', + "A chart or table value, as JSON Schema. Beyond it: `x` and every `y` must be columns of `data`, `y` columns hold numbers, a scatter chart's `x` column holds numbers, and a pie chart takes exactly one `y`.", + '', + '```json', + JSON.stringify(schema), + '```', + '' + ] + for (const { title, value } of EXAMPLES) { + parts.push(`${title}:`, '', '```json', JSON.stringify(value, null, 2), '```', '') + } + return parts.join('\n') +} + +describe('display catalog guidance', () => { + it('examples are valid fence values', () => { + for (const { title, value } of EXAMPLES) { + expect(fenceSchema.safeParse(value).success, title).toBe(true) + } + }) + + it('matches the catalog (npm run gen:display-catalog)', () => { + const content = render() + if (process.env.WM_GEN_DISPLAY_CATALOG) writeFileSync(OUT, content) + expect(readFileSync(OUT, 'utf8')).toBe(content) + }) +}) diff --git a/frontend/src/lib/components/display/displayExport.ts b/frontend/src/lib/components/display/displayExport.ts new file mode 100644 index 0000000000..23cf724af3 --- /dev/null +++ b/frontend/src/lib/components/display/displayExport.ts @@ -0,0 +1,60 @@ +import type { ChartBody, FenceResult, FenceTable } from './displayCatalog' +import { fenceItems, parseFence, tableRows } from './displayCatalog' +import { chartConfig } from './chartConfig' + +async function chartImage(doc: Document, chart: ChartBody): Promise { + const { Chart } = await import('chart.js/auto') + const canvas = document.createElement('canvas') + canvas.width = 800 + canvas.height = 400 + const config = chartConfig(chart, { dark: false, surface: '#ffffff' }) + const drawn = new Chart(canvas, { + ...config, + options: { ...config.options, responsive: false, devicePixelRatio: 2 } + }) + const src = drawn.toBase64Image() + drawn.destroy() + const figure = doc.createElement('figure') + figure.className = 'wm-diagram' + const img = doc.createElement('img') + img.src = src + img.alt = chart.title ?? `${chart.type} chart` + img.style.maxWidth = '100%' + figure.appendChild(img) + return figure +} + +function tableElement(doc: Document, item: FenceTable): HTMLElement { + const { columns, rows } = tableRows(item) + const table = doc.createElement('table') + const head = table.createTHead().insertRow() + for (const c of columns) head.appendChild(doc.createElement('th')).textContent = c + const body = table.createTBody() + for (const row of rows) { + const tr = body.insertRow() + for (const cell of row) tr.insertCell().textContent = cell === null ? '' : String(cell) + } + return table +} + +async function displayElements(doc: Document, value: FenceResult): Promise { + const out: HTMLElement[] = [] + for (const item of fenceItems(value)) { + out.push('chart' in item ? await chartImage(doc, item.chart) : tableElement(doc, item)) + } + return out +} + +/** + * Replaces each valid ```wm-display fence under `root` with what it renders as: a chart as a PNG, + * a table as a plain HTML table, so a downloaded document carries no script. An invalid fence + * stays as its source, as it does on screen. + */ +export async function drawDisplayFences(root: DocumentFragment | Element): Promise { + const doc = root.ownerDocument ?? document + for (const code of Array.from(root.querySelectorAll('pre > code.language-wm-display'))) { + const parsed = parseFence(code.textContent ?? '') + if (!parsed.ok) continue + code.parentElement!.replaceWith(...(await displayElements(doc, parsed.result))) + } +} diff --git a/frontend/src/lib/components/display/displayTelemetry.ts b/frontend/src/lib/components/display/displayTelemetry.ts new file mode 100644 index 0000000000..2cb2d91f32 --- /dev/null +++ b/frontend/src/lib/components/display/displayTelemetry.ts @@ -0,0 +1,14 @@ +import { logFeatureUsage } from '$lib/utils/featureUsage' +import { fenceKind, parseFence, type FenceKind } from './displayCatalog' + +const DISPLAY_BLOCK = /```wm-display[^\n]*\n([\s\S]*?)```/g + +/** Counts the ```wm-display blocks of a finished assistant reply, by kind or as `invalid`. */ +export function logDisplayBlocks(reply: string): void { + if (!reply.includes('```wm-display')) return + for (const [, source] of reply.matchAll(DISPLAY_BLOCK)) { + const parsed = parseFence(source) + const key: FenceKind | 'invalid' = parsed.ok ? fenceKind(parsed.result) : 'invalid' + logFeatureUsage('ai_chat', 'display_block', { key }) + } +} diff --git a/frontend/src/lib/components/sessions/SharedSessionTranscript.svelte b/frontend/src/lib/components/sessions/SharedSessionTranscript.svelte index 19239fe48c..d0f74f4b6b 100644 --- a/frontend/src/lib/components/sessions/SharedSessionTranscript.svelte +++ b/frontend/src/lib/components/sessions/SharedSessionTranscript.svelte @@ -4,6 +4,7 @@ import AIChatMessage from '$lib/components/copilot/chat/AIChatMessage.svelte' import ToolGroupDisplay from '$lib/components/copilot/chat/ToolGroupDisplay.svelte' import ArtifactBody from '$lib/components/copilot/chat/artifacts/ArtifactBody.svelte' + import DisplayCodeBlock from '$lib/components/copilot/chat/artifacts/DisplayCodeBlock.svelte' import { setChatViewHost } from '$lib/components/copilot/chat/chatViewHost' import { readOnlyChatViewHost } from '$lib/components/copilot/chat/readOnlyChatViewHost.svelte' import { chatItemKey, groupToolRuns } from '$lib/components/copilot/chat/toolGroups' @@ -113,7 +114,11 @@ drawer?.closeDrawer()}> {#if openArtifact} - + {:else} This artifact was not part of the share. {/if} diff --git a/system_prompts/README.md b/system_prompts/README.md index 14a940ea0f..9c6648acb0 100644 --- a/system_prompts/README.md +++ b/system_prompts/README.md @@ -52,6 +52,7 @@ a CLI-only workflow file (`flow-cli.md`, `script-cli.md`, `raw-app-cli.md`). | pipeline | `getPipelinePrompt()` | `write-pipeline` | `pipeline-base.md` | | data tables | `getDatatablePrompt()` | `datatables` | `datatable.md` | | workspace settings | `getWorkspaceSettingsPrompt()` | `workspace-settings` | `workspace-settings.md` | +| rich results | `getDisplayPrompt()` | `rich-results` | `display-results.md`, `display-catalog.gen.md` (written by `npm run gen:display-catalog` in `frontend/` from the zod catalog) | | triggers, schedules, preview, CLI commands | — | same names | CLI only | The app chat embeds `RAW_APP_BASE` directly (`chat/app/core.ts`). diff --git a/system_prompts/auto-generated/index.d.ts b/system_prompts/auto-generated/index.d.ts index c989610ebf..32775ef4ae 100644 --- a/system_prompts/auto-generated/index.d.ts +++ b/system_prompts/auto-generated/index.d.ts @@ -5,6 +5,7 @@ export declare function getResourcePrompt(): string; export declare function getAgentPrompt(): string; export declare function getRawAppPrompt(language?: string): string; export declare function getPipelinePrompt(): string; +export declare function getDisplayPrompt(): string; export declare function getDatatablePrompt(): string; export declare function getWorkspaceSettingsPrompt(): string; export declare function getDatatableSdkReference(language?: string): string; diff --git a/system_prompts/auto-generated/index.ts b/system_prompts/auto-generated/index.ts index f9e890ebcb..59281e2723 100644 --- a/system_prompts/auto-generated/index.ts +++ b/system_prompts/auto-generated/index.ts @@ -80,6 +80,14 @@ export function getPipelinePrompt(): string { ].filter(Boolean).join('\n\n'); } +// Helper for rich results: tables, charts and the other shapes a return value renders as +export function getDisplayPrompt(): string { + return [ + prompts.DISPLAY_RESULTS_BASE, + prompts.DISPLAY_CATALOG + ].filter(Boolean).join('\n\n'); +} + // Helper for data table schema changes, migrations and permissions (chat consumers) export function getDatatablePrompt(): string { return [ diff --git a/system_prompts/auto-generated/prompts.d.ts b/system_prompts/auto-generated/prompts.d.ts index 79921ddaa3..28f21c6791 100644 --- a/system_prompts/auto-generated/prompts.d.ts +++ b/system_prompts/auto-generated/prompts.d.ts @@ -10,6 +10,8 @@ export declare const DATATABLE_BASE: string; export declare const WORKSPACE_SETTINGS_BASE: string; export declare const WORKFLOW_AS_CODE_BASE: string; export declare const FLOW_CHAT_SPECIAL_MODULES: string; +export declare const DISPLAY_RESULTS_BASE: string; +export declare const DISPLAY_CATALOG: string; export declare const SDK_TYPESCRIPT: string; export declare const SDK_PYTHON: string; export declare const WAC_SDK_TYPESCRIPT: string; diff --git a/system_prompts/auto-generated/prompts.ts b/system_prompts/auto-generated/prompts.ts index 485e04700f..19245b75e0 100644 --- a/system_prompts/auto-generated/prompts.ts +++ b/system_prompts/auto-generated/prompts.ts @@ -1875,6 +1875,146 @@ set_failure_module({ \`\`\` `; +export const DISPLAY_RESULTS_BASE = `# Rich results + +Windmill renders a script's or flow's return value according to its shape: on run pages, in the +script and flow editors, in app result displays and in AI chat run cards. Anything that matches none +of the shapes below is shown as JSON. + +## Shapes + +- \`{ "table-row-object": [{...}, ...] }\`, or a bare array of objects: a table whose columns are the + union of the objects' keys. +- \`{ "table-col": { "col": [...], ... } }\`, or a bare object of equal-length arrays: a table built + column by column. +- \`{ "table-row": [["col", ...], [v, ...], ...] }\`: a table whose first row holds the column names. +- \`{ "chart": {...} }\`: a bar, line, pie or scatter chart drawn from rows (schema below). A \`chart\` + value the schema rejects is shown as JSON, not as a broken chart. +- \`{ "markdown": "..." }\` (or \`md\`): rendered markdown. +- \`{ "html": "..." }\`: sanitized HTML. +- \`{ "png": "" }\`, likewise \`jpeg\`, \`gif\`, \`svg\`: an image. \`{ "pdf": "" }\`: a PDF. +- \`{ "file": "", "filename": "report.csv" }\`: a download. +- \`{ "map": { "lat": 0, "lon": 0, "zoom": 3, "markers": [{ "lat": 0, "lon": 0, "title": "..." }] } }\`: + a map. +- \`{ "s3": "path/to/key" }\`: an object in the workspace storage, previewed by type. +- \`{ "render_all": [ ... ] }\`: each item rendered in turn with the rules above. + +Each shape is an object with that one key (plus \`filename\` for a file, and an optional \`storage\` for +\`s3\`). A result carrying any other key beside it is shown as JSON. + +## Choosing one + +A chart answers a question at a glance: a trend over time (line), a comparison across categories +(bar), parts of a whole with few parts (pie), or a relation between two numbers (scatter). A table +answers lookups and holds the exact values. When both help, return both in a \`render_all\`: the chart +first, then the table of the same rows. + +Keep a chart to what it shows well: at most 8 series. A pie with more than 8 slices keeps the 7 +largest and folds the rest into "Other", so prefer a bar chart for many categories. Aggregate before +charting: a chart of thousands of raw points says less than one of the totals per day. +`; + +export const DISPLAY_CATALOG = `### Chart and table schema + +A chart or table value, as JSON Schema. Beyond it: \`x\` and every \`y\` must be columns of \`data\`, \`y\` columns hold numbers, a scatter chart's \`x\` column holds numbers, and a pie chart takes exactly one \`y\`. + +\`\`\`json +{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"anyOf":[{"type":"object","properties":{"chart":{"type":"object","properties":{"type":{"description":"bar or line for categories or time, pie for parts of a whole, scatter for two numeric columns","type":"string","enum":["bar","line","pie","scatter"]},"title":{"type":"string"},"data":{"description":"The rows to plot, the same shape as a table-row-object result","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"x":{"description":"Column holding the category, label or date of each row (bar, line, pie), or the numeric x value (scatter)","type":"string"},"y":{"description":"Numeric column, or columns, to plot: one series each. A pie takes exactly one","anyOf":[{"type":"string"},{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string"}}]},"stacked":{"description":"bar and line: stack the series","type":"boolean"},"horizontal":{"description":"bar: draw the bars horizontally","type":"boolean"},"x_label":{"type":"string"},"y_label":{"type":"string"}},"required":["type","data","x","y"],"additionalProperties":false}},"required":["chart"],"additionalProperties":false},{"type":"object","properties":{"table-row-object":{"description":"Rows as objects; the columns are the union of their keys","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row-object"],"additionalProperties":false},{"type":"object","properties":{"table-col":{"description":"Columns: column name to its values, all the same length","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"maxItems":5000,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-col"],"additionalProperties":false},{"type":"object","properties":{"table-row":{"description":"Rows as arrays; the first row holds the column names","minItems":2,"maxItems":5000,"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row"],"additionalProperties":false}]},{"type":"object","properties":{"render_all":{"description":"Several items shown one after another","minItems":1,"maxItems":10,"type":"array","items":{"anyOf":[{"type":"object","properties":{"chart":{"type":"object","properties":{"type":{"description":"bar or line for categories or time, pie for parts of a whole, scatter for two numeric columns","type":"string","enum":["bar","line","pie","scatter"]},"title":{"type":"string"},"data":{"description":"The rows to plot, the same shape as a table-row-object result","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"x":{"description":"Column holding the category, label or date of each row (bar, line, pie), or the numeric x value (scatter)","type":"string"},"y":{"description":"Numeric column, or columns, to plot: one series each. A pie takes exactly one","anyOf":[{"type":"string"},{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string"}}]},"stacked":{"description":"bar and line: stack the series","type":"boolean"},"horizontal":{"description":"bar: draw the bars horizontally","type":"boolean"},"x_label":{"type":"string"},"y_label":{"type":"string"}},"required":["type","data","x","y"],"additionalProperties":false}},"required":["chart"],"additionalProperties":false},{"type":"object","properties":{"table-row-object":{"description":"Rows as objects; the columns are the union of their keys","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row-object"],"additionalProperties":false},{"type":"object","properties":{"table-col":{"description":"Columns: column name to its values, all the same length","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"maxItems":5000,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-col"],"additionalProperties":false},{"type":"object","properties":{"table-row":{"description":"Rows as arrays; the first row holds the column names","minItems":2,"maxItems":5000,"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row"],"additionalProperties":false}]}}},"required":["render_all"],"additionalProperties":false}]} +\`\`\` + +Bar chart, one series per y column: + +\`\`\`json +{ + "chart": { + "type": "bar", + "title": "Runs per day", + "data": [ + { + "day": "2026-11-10", + "success": 42, + "failure": 3 + }, + { + "day": "2026-11-11", + "success": 51, + "failure": 1 + } + ], + "x": "day", + "y": [ + "success", + "failure" + ], + "stacked": true + } +} +\`\`\` + +Pie chart (exactly one y column): + +\`\`\`json +{ + "chart": { + "type": "pie", + "data": [ + { + "language": "python3", + "scripts": 18 + }, + { + "language": "bun", + "scripts": 25 + } + ], + "x": "language", + "y": "scripts" + } +} +\`\`\` + +A chart and a table together: + +\`\`\`json +{ + "render_all": [ + { + "chart": { + "type": "line", + "data": [ + { + "hour": "10:00", + "p95_ms": 120 + }, + { + "hour": "11:00", + "p95_ms": 180 + } + ], + "x": "hour", + "y": "p95_ms", + "y_label": "ms" + } + }, + { + "table-row-object": [ + { + "hour": "10:00", + "p95_ms": 120, + "jobs": 310 + }, + { + "hour": "11:00", + "p95_ms": 180, + "jobs": 402 + } + ] + } + ] +} +\`\`\` +`; + export const SDK_TYPESCRIPT = `# TypeScript SDK (windmill-client) Import: import * as wmill from 'windmill-client' diff --git a/system_prompts/auto-generated/skills/rich-results/SKILL.md b/system_prompts/auto-generated/skills/rich-results/SKILL.md new file mode 100644 index 0000000000..ec49550773 --- /dev/null +++ b/system_prompts/auto-generated/skills/rich-results/SKILL.md @@ -0,0 +1,142 @@ +--- +name: rich-results +description: MUST use when a script or flow should return a table, chart, markdown, image, file or map instead of plain JSON. +--- + +# Rich results + +Windmill renders a script's or flow's return value according to its shape: on run pages, in the +script and flow editors, in app result displays and in AI chat run cards. Anything that matches none +of the shapes below is shown as JSON. + +## Shapes + +- `{ "table-row-object": [{...}, ...] }`, or a bare array of objects: a table whose columns are the + union of the objects' keys. +- `{ "table-col": { "col": [...], ... } }`, or a bare object of equal-length arrays: a table built + column by column. +- `{ "table-row": [["col", ...], [v, ...], ...] }`: a table whose first row holds the column names. +- `{ "chart": {...} }`: a bar, line, pie or scatter chart drawn from rows (schema below). A `chart` + value the schema rejects is shown as JSON, not as a broken chart. +- `{ "markdown": "..." }` (or `md`): rendered markdown. +- `{ "html": "..." }`: sanitized HTML. +- `{ "png": "" }`, likewise `jpeg`, `gif`, `svg`: an image. `{ "pdf": "" }`: a PDF. +- `{ "file": "", "filename": "report.csv" }`: a download. +- `{ "map": { "lat": 0, "lon": 0, "zoom": 3, "markers": [{ "lat": 0, "lon": 0, "title": "..." }] } }`: + a map. +- `{ "s3": "path/to/key" }`: an object in the workspace storage, previewed by type. +- `{ "render_all": [ ... ] }`: each item rendered in turn with the rules above. + +Each shape is an object with that one key (plus `filename` for a file, and an optional `storage` for +`s3`). A result carrying any other key beside it is shown as JSON. + +## Choosing one + +A chart answers a question at a glance: a trend over time (line), a comparison across categories +(bar), parts of a whole with few parts (pie), or a relation between two numbers (scatter). A table +answers lookups and holds the exact values. When both help, return both in a `render_all`: the chart +first, then the table of the same rows. + +Keep a chart to what it shows well: at most 8 series. A pie with more than 8 slices keeps the 7 +largest and folds the rest into "Other", so prefer a bar chart for many categories. Aggregate before +charting: a chart of thousands of raw points says less than one of the totals per day. + +### Chart and table schema + +A chart or table value, as JSON Schema. Beyond it: `x` and every `y` must be columns of `data`, `y` columns hold numbers, a scatter chart's `x` column holds numbers, and a pie chart takes exactly one `y`. + +```json +{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"anyOf":[{"type":"object","properties":{"chart":{"type":"object","properties":{"type":{"description":"bar or line for categories or time, pie for parts of a whole, scatter for two numeric columns","type":"string","enum":["bar","line","pie","scatter"]},"title":{"type":"string"},"data":{"description":"The rows to plot, the same shape as a table-row-object result","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"x":{"description":"Column holding the category, label or date of each row (bar, line, pie), or the numeric x value (scatter)","type":"string"},"y":{"description":"Numeric column, or columns, to plot: one series each. A pie takes exactly one","anyOf":[{"type":"string"},{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string"}}]},"stacked":{"description":"bar and line: stack the series","type":"boolean"},"horizontal":{"description":"bar: draw the bars horizontally","type":"boolean"},"x_label":{"type":"string"},"y_label":{"type":"string"}},"required":["type","data","x","y"],"additionalProperties":false}},"required":["chart"],"additionalProperties":false},{"type":"object","properties":{"table-row-object":{"description":"Rows as objects; the columns are the union of their keys","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row-object"],"additionalProperties":false},{"type":"object","properties":{"table-col":{"description":"Columns: column name to its values, all the same length","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"maxItems":5000,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-col"],"additionalProperties":false},{"type":"object","properties":{"table-row":{"description":"Rows as arrays; the first row holds the column names","minItems":2,"maxItems":5000,"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row"],"additionalProperties":false}]},{"type":"object","properties":{"render_all":{"description":"Several items shown one after another","minItems":1,"maxItems":10,"type":"array","items":{"anyOf":[{"type":"object","properties":{"chart":{"type":"object","properties":{"type":{"description":"bar or line for categories or time, pie for parts of a whole, scatter for two numeric columns","type":"string","enum":["bar","line","pie","scatter"]},"title":{"type":"string"},"data":{"description":"The rows to plot, the same shape as a table-row-object result","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"x":{"description":"Column holding the category, label or date of each row (bar, line, pie), or the numeric x value (scatter)","type":"string"},"y":{"description":"Numeric column, or columns, to plot: one series each. A pie takes exactly one","anyOf":[{"type":"string"},{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string"}}]},"stacked":{"description":"bar and line: stack the series","type":"boolean"},"horizontal":{"description":"bar: draw the bars horizontally","type":"boolean"},"x_label":{"type":"string"},"y_label":{"type":"string"}},"required":["type","data","x","y"],"additionalProperties":false}},"required":["chart"],"additionalProperties":false},{"type":"object","properties":{"table-row-object":{"description":"Rows as objects; the columns are the union of their keys","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row-object"],"additionalProperties":false},{"type":"object","properties":{"table-col":{"description":"Columns: column name to its values, all the same length","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"maxItems":5000,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-col"],"additionalProperties":false},{"type":"object","properties":{"table-row":{"description":"Rows as arrays; the first row holds the column names","minItems":2,"maxItems":5000,"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row"],"additionalProperties":false}]}}},"required":["render_all"],"additionalProperties":false}]} +``` + +Bar chart, one series per y column: + +```json +{ + "chart": { + "type": "bar", + "title": "Runs per day", + "data": [ + { + "day": "2026-11-10", + "success": 42, + "failure": 3 + }, + { + "day": "2026-11-11", + "success": 51, + "failure": 1 + } + ], + "x": "day", + "y": [ + "success", + "failure" + ], + "stacked": true + } +} +``` + +Pie chart (exactly one y column): + +```json +{ + "chart": { + "type": "pie", + "data": [ + { + "language": "python3", + "scripts": 18 + }, + { + "language": "bun", + "scripts": 25 + } + ], + "x": "language", + "y": "scripts" + } +} +``` + +A chart and a table together: + +```json +{ + "render_all": [ + { + "chart": { + "type": "line", + "data": [ + { + "hour": "10:00", + "p95_ms": 120 + }, + { + "hour": "11:00", + "p95_ms": 180 + } + ], + "x": "hour", + "y": "p95_ms", + "y_label": "ms" + } + }, + { + "table-row-object": [ + { + "hour": "10:00", + "p95_ms": 120, + "jobs": 310 + }, + { + "hour": "11:00", + "p95_ms": 180, + "jobs": 402 + } + ] + } + ] +} +``` diff --git a/system_prompts/base/display-catalog.gen.md b/system_prompts/base/display-catalog.gen.md new file mode 100644 index 0000000000..3824a46f95 --- /dev/null +++ b/system_prompts/base/display-catalog.gen.md @@ -0,0 +1,99 @@ +### Chart and table schema + +A chart or table value, as JSON Schema. Beyond it: `x` and every `y` must be columns of `data`, `y` columns hold numbers, a scatter chart's `x` column holds numbers, and a pie chart takes exactly one `y`. + +```json +{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"anyOf":[{"type":"object","properties":{"chart":{"type":"object","properties":{"type":{"description":"bar or line for categories or time, pie for parts of a whole, scatter for two numeric columns","type":"string","enum":["bar","line","pie","scatter"]},"title":{"type":"string"},"data":{"description":"The rows to plot, the same shape as a table-row-object result","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"x":{"description":"Column holding the category, label or date of each row (bar, line, pie), or the numeric x value (scatter)","type":"string"},"y":{"description":"Numeric column, or columns, to plot: one series each. A pie takes exactly one","anyOf":[{"type":"string"},{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string"}}]},"stacked":{"description":"bar and line: stack the series","type":"boolean"},"horizontal":{"description":"bar: draw the bars horizontally","type":"boolean"},"x_label":{"type":"string"},"y_label":{"type":"string"}},"required":["type","data","x","y"],"additionalProperties":false}},"required":["chart"],"additionalProperties":false},{"type":"object","properties":{"table-row-object":{"description":"Rows as objects; the columns are the union of their keys","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row-object"],"additionalProperties":false},{"type":"object","properties":{"table-col":{"description":"Columns: column name to its values, all the same length","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"maxItems":5000,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-col"],"additionalProperties":false},{"type":"object","properties":{"table-row":{"description":"Rows as arrays; the first row holds the column names","minItems":2,"maxItems":5000,"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row"],"additionalProperties":false}]},{"type":"object","properties":{"render_all":{"description":"Several items shown one after another","minItems":1,"maxItems":10,"type":"array","items":{"anyOf":[{"type":"object","properties":{"chart":{"type":"object","properties":{"type":{"description":"bar or line for categories or time, pie for parts of a whole, scatter for two numeric columns","type":"string","enum":["bar","line","pie","scatter"]},"title":{"type":"string"},"data":{"description":"The rows to plot, the same shape as a table-row-object result","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"x":{"description":"Column holding the category, label or date of each row (bar, line, pie), or the numeric x value (scatter)","type":"string"},"y":{"description":"Numeric column, or columns, to plot: one series each. A pie takes exactly one","anyOf":[{"type":"string"},{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string"}}]},"stacked":{"description":"bar and line: stack the series","type":"boolean"},"horizontal":{"description":"bar: draw the bars horizontally","type":"boolean"},"x_label":{"type":"string"},"y_label":{"type":"string"}},"required":["type","data","x","y"],"additionalProperties":false}},"required":["chart"],"additionalProperties":false},{"type":"object","properties":{"table-row-object":{"description":"Rows as objects; the columns are the union of their keys","minItems":1,"maxItems":5000,"type":"array","items":{"description":"One row: column name to value (string, number, boolean or null)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row-object"],"additionalProperties":false},{"type":"object","properties":{"table-col":{"description":"Columns: column name to its values, all the same length","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"maxItems":5000,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-col"],"additionalProperties":false},{"type":"object","properties":{"table-row":{"description":"Rows as arrays; the first row holds the column names","minItems":2,"maxItems":5000,"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}},"required":["table-row"],"additionalProperties":false}]}}},"required":["render_all"],"additionalProperties":false}]} +``` + +Bar chart, one series per y column: + +```json +{ + "chart": { + "type": "bar", + "title": "Runs per day", + "data": [ + { + "day": "2026-11-10", + "success": 42, + "failure": 3 + }, + { + "day": "2026-11-11", + "success": 51, + "failure": 1 + } + ], + "x": "day", + "y": [ + "success", + "failure" + ], + "stacked": true + } +} +``` + +Pie chart (exactly one y column): + +```json +{ + "chart": { + "type": "pie", + "data": [ + { + "language": "python3", + "scripts": 18 + }, + { + "language": "bun", + "scripts": 25 + } + ], + "x": "language", + "y": "scripts" + } +} +``` + +A chart and a table together: + +```json +{ + "render_all": [ + { + "chart": { + "type": "line", + "data": [ + { + "hour": "10:00", + "p95_ms": 120 + }, + { + "hour": "11:00", + "p95_ms": 180 + } + ], + "x": "hour", + "y": "p95_ms", + "y_label": "ms" + } + }, + { + "table-row-object": [ + { + "hour": "10:00", + "p95_ms": 120, + "jobs": 310 + }, + { + "hour": "11:00", + "p95_ms": 180, + "jobs": 402 + } + ] + } + ] +} +``` diff --git a/system_prompts/base/display-results.md b/system_prompts/base/display-results.md new file mode 100644 index 0000000000..17f0c5b864 --- /dev/null +++ b/system_prompts/base/display-results.md @@ -0,0 +1,37 @@ +# Rich results + +Windmill renders a script's or flow's return value according to its shape: on run pages, in the +script and flow editors, in app result displays and in AI chat run cards. Anything that matches none +of the shapes below is shown as JSON. + +## Shapes + +- `{ "table-row-object": [{...}, ...] }`, or a bare array of objects: a table whose columns are the + union of the objects' keys. +- `{ "table-col": { "col": [...], ... } }`, or a bare object of equal-length arrays: a table built + column by column. +- `{ "table-row": [["col", ...], [v, ...], ...] }`: a table whose first row holds the column names. +- `{ "chart": {...} }`: a bar, line, pie or scatter chart drawn from rows (schema below). A `chart` + value the schema rejects is shown as JSON, not as a broken chart. +- `{ "markdown": "..." }` (or `md`): rendered markdown. +- `{ "html": "..." }`: sanitized HTML. +- `{ "png": "" }`, likewise `jpeg`, `gif`, `svg`: an image. `{ "pdf": "" }`: a PDF. +- `{ "file": "", "filename": "report.csv" }`: a download. +- `{ "map": { "lat": 0, "lon": 0, "zoom": 3, "markers": [{ "lat": 0, "lon": 0, "title": "..." }] } }`: + a map. +- `{ "s3": "path/to/key" }`: an object in the workspace storage, previewed by type. +- `{ "render_all": [ ... ] }`: each item rendered in turn with the rules above. + +Each shape is an object with that one key (plus `filename` for a file, and an optional `storage` for +`s3`). A result carrying any other key beside it is shown as JSON. + +## Choosing one + +A chart answers a question at a glance: a trend over time (line), a comparison across categories +(bar), parts of a whole with few parts (pie), or a relation between two numbers (scatter). A table +answers lookups and holds the exact values. When both help, return both in a `render_all`: the chart +first, then the table of the same rows. + +Keep a chart to what it shows well: at most 8 series. A pie with more than 8 slices keeps the 7 +largest and folds the rest into "Other", so prefer a bar chart for many categories. Aggregate before +charting: a chart of thousands of raw points says less than one of the totals per day. diff --git a/system_prompts/generate.py b/system_prompts/generate.py index 0a76d6045d..a83834dc99 100644 --- a/system_prompts/generate.py +++ b/system_prompts/generate.py @@ -1714,6 +1714,14 @@ TOPICS: dict[str, dict] = { 'chat_helper': 'getWorkspaceSettingsPrompt', 'parts': ['workspace-settings.md'], }, + 'display': { + 'skill': 'rich-results', + 'description': 'MUST use when a script or flow should return a table, chart, markdown, image, file or map instead of plain JSON.', + 'chat_helper': 'getDisplayPrompt', + # display-catalog.gen.md is generated from the frontend's zod catalog by + # `npm run gen:display-catalog`; the chat validates charts against the same schema. + 'parts': ['display-results.md', 'display-catalog.gen.md'], + }, 'cli_commands': { 'skill': 'cli-commands', 'description': 'MUST use when using the CLI, including debugging job failures and inspecting run history via `wmill job`.', @@ -1738,6 +1746,8 @@ CHAT_CONSTANTS = { 'workspace-settings.md': 'WORKSPACE_SETTINGS_BASE', 'workflow-as-code.md': 'WORKFLOW_AS_CODE_BASE', 'flow-chat-special-modules.md': 'FLOW_CHAT_SPECIAL_MODULES', + 'display-results.md': 'DISPLAY_RESULTS_BASE', + 'display-catalog.gen.md': 'DISPLAY_CATALOG', } @@ -2676,6 +2686,11 @@ export function getPipelinePrompt(): string { __RETURN_pipeline__ } +// Helper for rich results: tables, charts and the other shapes a return value renders as +export function getDisplayPrompt(): string { + __RETURN_display__ +} + // Helper for data table schema changes, migrations and permissions (chat consumers) export function getDatatablePrompt(): string { __RETURN_datatable__ @@ -2748,6 +2763,7 @@ export declare function getResourcePrompt(): string; export declare function getAgentPrompt(): string; export declare function getRawAppPrompt(language?: string): string; export declare function getPipelinePrompt(): string; +export declare function getDisplayPrompt(): string; export declare function getDatatablePrompt(): string; export declare function getWorkspaceSettingsPrompt(): string; export declare function getDatatableSdkReference(language?: string): string;