@lightdash/cli 2.243.5 → 2.245.0

package/dist/vendor/template/.claude/skills/sdk-features/SKILL.md

@@ -21,6 +21,7 @@ Users describe features by what they see in the Lightdash editor. Translate:
 | thumbnails / screenshots / scheduled deliveries | `screenshot` | required — see below |
 | drill down, click into a chart | `drill-down` | app code opt-in |
 | drill into a viz data point (reusable visualization) | `viz-drill-down` | app code opt-in |
+| "ask the AI", one-line takeaway, explain this row | `ai-prompt` | app code opt-in |
 | "share this view", URL that restores state | `url-state` | app code opt-in |
 | Google Sheets export | `gsheet-export` | app code opt-in |
 | "delivery has all tabs", full data in scheduled deliveries | `delivery-render` | app code opt-in |
@@ -122,6 +123,12 @@ order, `sortBy` describes result ordering, `totalColumnCount` exposes truncation
   points can be marked, with `investigate(id)` / `continueInAskAi(id)` for the
   action menu. Render a summary block and markers; render nothing when
   `status === 'unavailable'`. Full contract in `/app/references/ai-analysis.md`.
+- `ai-prompt`: `useAiPrompt()` returns `{ available, ask, loading, text, error }`;
+  `ask({ prompt, sources: [{ result, label }], focus?: { row } })` sends an
+  author-written question over loaded `useLightdash` results and resolves to
+  plain text. `result` is the object `useLightdash` returns (keep a reference
+  to it even when destructuring), never a rebuilt `{ data, columns }`. Hide the control when `available` is false; trigger from a user
+  action. Full contract in `/app/references/ai-analysis.md`.
 - `delivery-render`: `useDeliveryRender()` is `true` during scheduled-delivery
   and delivery-preview capture renders. Gate tab/slide DATA mounting on it so
   every tab's queries execute during capture while only the active tab stays

package/dist/vendor/template/references/ai-analysis.md

@@ -201,9 +201,51 @@ Then render the investigation state wherever the anomaly is shown (a card under
 
 Never open a dialog for the investigation yourself; the app renders state, Lightdash owns the run.
 
+## Free-form prompts (`useAiPrompt`)
+
+`useInsights` is the host's analysis; `useAiPrompt` lets the app ask its own question about results it already loaded. Use it for an author-written takeaway under a chart, a "what stands out in this row" explanation, or a narrative tailored to the app's domain. Answers are short plain text, not Markdown.
+
+```tsx
+import { useAiPrompt, useLightdash } from '@lightdash/query-sdk';
+
+function RevenueTakeaway() {
+    // Keep the hook result itself: `sources` needs the object useLightdash
+    // returns, not a rebuilt { data, columns, ... }.
+    const revenue = useLightdash(revenueByMonth);
+    const { data, loading } = revenue;
+    const ai = useAiPrompt();
+
+    if (!ai.available || loading) return null;
+
+    return (
+        <div>
+            <button
+                disabled={ai.loading}
+                onClick={() =>
+                    ai.ask({
+                        prompt: 'In two sentences, what should a sales lead take away from the last six months of revenue?',
+                        sources: [{ result: revenue, label: 'Revenue by month' }],
+                    })
+                }
+            >
+                {ai.loading ? 'Thinking…' : 'Summarise'}
+            </button>
+            {ai.text && <p>{ai.text}</p>}
+            {ai.error && <p role="alert">{ai.error.message}</p>}
+        </div>
+    );
+}
+```
+
+- `sources` take the object `useLightdash` returns, as `{ result, label? }` (the `label` is the section title the model sees). If the component destructures the hook, keep a reference to the whole result (`const orders = useLightdash(q); const { data, loading } = orders;`) and pass `orders`; a rebuilt `{ data, columns }` object has no query uuid and `ask` throws. Only these rows reach the model; Lightdash reads them from the viewer's own query history, so the app sends no data.
+- `focus: { row }` narrows the question to one row of a source, for example from a clicked data point: `ai.ask({ prompt: 'Why is this month unusual?', sources: [{ result: revenue }], focus: { row } })`.
+- `available` is false outside a Lightdash host or when the organisation has not turned AI on for data apps. Hide the control; do not fall back to another provider.
+- Trigger `ask` from a user action, or at most once per loaded view. Never on a timer, never per row. Prompts are rate limited per viewer.
+- Prompts are capped at 2000 characters; write them as instructions to an analyst, and name the audience and the length you want.
+
 ## What the app must not do
 
-- Do not send prompts, rows or field values anywhere. The hook exposes results; Lightdash already has the data.
+- Do not send rows or field values anywhere. The hooks expose results; Lightdash already has the data.
 - Do not add an external connection to a model provider for summaries or explanations. Use this hook.
 - Do not fabricate insights when the status is `idle` or `unavailable`; render the state.
 - Do not render `explanation` as HTML. It is Markdown; render it as text or through a Markdown component.

package/dist/vendor/template/skill.md

@@ -693,7 +693,7 @@ For any external HTTP API call, read `/app/references/external-apis.md` and use
 
 ### AI analysis — executive summary and anomalies
 
-When the user asks for an executive summary, "what changed and why", anomaly callouts, or any AI-generated insight about the data on the page, read `/app/references/ai-analysis.md` and use `useInsights` from the SDK. Lightdash runs the analysis over the queries the app already loaded and pushes the result in; the app renders it (a summary block, markers on flagged points, an Investigate action) and never sends prompts, rows or keys. Render nothing when `status === 'unavailable'`.
+When the user asks for an executive summary, "what changed and why", anomaly callouts, or any AI-generated insight about the data on the page, read `/app/references/ai-analysis.md` and use `useInsights` from the SDK. Lightdash runs the analysis over the queries the app already loaded and pushes the result in; the app renders it (a summary block, markers on flagged points, an Investigate action) and never sends rows or keys. Render nothing when `status === 'unavailable'`. For an author-written question over loaded results (a takeaway under a chart, "explain this row"), use `useAiPrompt` from the same reference.
 
 ## Visual Design
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "2.243.5",
+  "version": "2.245.0",
   "description": "Lightdash CLI tool",
   "license": "MIT",
   "repository": {
@@ -22,8 +22,8 @@
     "@actions/core": "1.11.1",
     "@aws-sdk/credential-providers": "3.995.0",
     "@casl/ability": "6.8.0",
-    "@lightdash/common": "2.243.5",
-    "@lightdash/warehouses": "2.243.5",
+    "@lightdash/common": "2.245.0",
+    "@lightdash/warehouses": "2.245.0",
     "@sidvind/better-ajv-errors": "7.0.0",
     "@types/columnify": "1.5.1",
     "ajv": "8.18.0",