@dbx-tools/appkit-mastra 0.1.25 → 0.1.27

package/dist/src/chart.d.ts

@@ -1,104 +1,156 @@
 /**
- * Chart-rendering primitives.
+ * Chart planner + chart cache.
  *
- * Two surfaces, one shared brain:
+ * Self-contained chart subsystem with two layers:
  *
- * - {@link runChartPlanner}: the chart-planner Agent + ECOption
- *   expansion as a plain async function. Takes a dataset and
- *   returns a promise that resolves to a full `EChartsOption`
- *   JSON plus the chosen `chartType`. No background work, no
- *   writer side-effects, no id allocation - callers stitch the
- *   result into whatever shape their producer needs.
+ *   1. Inner planner agent (private). Pure dataset-in /
+ *      `EChartsOption`-out brain. Driven by {@link prepareChart};
+ *      callers never instantiate it directly.
+ *   2. {@link prepareChart}: orchestration on top of the planner.
+ *      Mints a `chartId`, caches an empty `{ chartId }` record
+ *      synchronously, then resolves the dataset and runs the
+ *      planner in the background. The terminal entry settles with
+ *      either `result` (success) or `error` (failure). Both
+ *      undefined means the entry is still processing.
  *
- * - {@link buildRenderDataTool}: a Mastra tool the model calls
- *   ("here is a dataset, render it as a chart"). Mints a short
- *   `chartId`, `await`s {@link runChartPlanner} so the planner
- *   latency is attributed to this tool's trace span, emits one
- *   `type: "chart"` writer event carrying the dataset + resolved
- *   `option`, and returns `{ chartId }` to the model. The
- *   LLM-bound output stays flat regardless of dataset size.
+ * The cache surface ({@link fetchChart}) is the only state the
+ * HTTP route and the chart-producing tools share. `prepareChart`
+ * is dataset-agnostic - callers supply a `resolveData` callback
+ * that fetches the rows however they like (Genie statement, inline
+ * dataset, custom API). The module has no knowledge of Genie or
+ * statement ids; those concerns live in the tools that wrap it.
  *
- * The model wires the chart into its reply by emitting the marker
- * `[[chart:<chartId>]]` on its own line in markdown. The chat
- * client splits the assistant text on these markers and drops a
- * `<ChartSlot>` in at the position the model placed it. The slot
- * resolves directly to the rendered Echarts visualisation - no
- * skeleton state, because the option is in the same event as the
- * dataset.
+ * Wire-format schemas (`ChartSchema`, `ChartResultSchema`,
+ * {@link ChartTypeSchema}) live in
+ * `@dbx-tools/appkit-mastra-shared` so the demo client and any
+ * other UI consumer share the exact same shape this module reads
+ * and writes.
+ *
+ * Public surface (everything else is module-private):
+ *   - {@link chartPlannerRequestSchema} / {@link ChartPlannerRequest}
+ *   - {@link prepareChart} / {@link PrepareChartOptions}
+ *   - {@link fetchChart} / {@link FetchChartOptions}
+ *   - {@link buildRenderDataTool} (the `render_data` Mastra tool
+ *     auto-wired on every agent in `agents.ts`)
  */
+import { type Chart } from "@dbx-tools/appkit-mastra-shared";
 import type { RequestContext } from "@mastra/core/request-context";
 import { z } from "zod";
 import type { MastraPluginConfig } from "./config.js";
 /**
- * Compact, model-friendly representation of an Echarts spec. The
- * planner agent emits this; {@link planToEchartsOption} expands it
- * into a real `EChartsOption` JSON. Two layers because letting the
- * model fill in a fully-typed `EChartsOption` is brittle (hundreds
- * of optional fields, deep unions, version-dependent shapes). A
- * small "chart plan" schema is much more reliable for a fast model
- * and keeps animation / tooltip / styling defaults consistent
- * across charts.
+ * Canonical planner input shape. Tools that source rows from an
+ * inline dataset (`render_data`) use it as their `inputSchema`
+ * verbatim; tools that resolve rows from a remote (`prepare_chart`
+ * over a Genie statement) `omit({ data })` and `extend` with their
+ * own identifier field, so the field-level `.describe()` text
+ * stays a single source of truth. Server-only - the UI never
+ * sees a planner request, only the resolved {@link Chart}.
  */
-declare const chartPlanSchema: z.ZodObject<{
-    chartType: z.ZodEnum<{
-        bar: "bar";
-        line: "line";
-        area: "area";
-        scatter: "scatter";
-        pie: "pie";
-    }>;
-    title: z.ZodOptional<z.ZodString>;
-    xAxisLabel: z.ZodOptional<z.ZodString>;
-    yAxisLabel: z.ZodOptional<z.ZodString>;
-    categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    series: z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        data: z.ZodArray<z.ZodCatch<z.ZodPreprocess<z.ZodUnion<readonly [z.ZodNumber, z.ZodNull, z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodObject<{
-            name: z.ZodString;
-            value: z.ZodNumber;
-        }, z.core.$strip>]>>>>;
-    }, z.core.$strip>>;
+export declare const chartPlannerRequestSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    data: z.ZodReadonly<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
 }, z.core.$strip>;
-type ChartPlan = z.infer<typeof chartPlanSchema>;
-/** Inputs to {@link runChartPlanner}. */
-export interface RunChartPlannerOptions {
+export type ChartPlannerRequest = z.infer<typeof chartPlannerRequestSchema>;
+/** Inputs to {@link prepareChart}. */
+export interface PrepareChartOptions {
+    /** Plugin config; resolves the planner agent's model. */
     config: MastraPluginConfig;
-    requestContext?: RequestContext;
-    title: string;
+    /** Display title forwarded to the planner agent. */
+    title?: string;
+    /** Optional intent hint forwarded to the planner agent. */
     description?: string;
-    data: ReadonlyArray<Record<string, unknown>>;
     /**
-     * Cooperative cancellation. Forwarded to the planner agent's
-     * `generate({ abortSignal })` call so concurrent renders can be
-     * aborted as a group when the parent Genie agent's signal fires.
+     * Resolves the rows to chart. Called once, in the background.
+     * Any thrown error lands in the cache as the entry's `error`
+     * field (never propagated to the caller of {@link prepareChart}).
+     * An empty `rows` array is rejected as `"dataset has no rows;
+     * nothing to chart"`.
+     */
+    resolveData: (signal?: AbortSignal) => Promise<{
+        rows: ReadonlyArray<Record<string, unknown>>;
+    }>;
+    /**
+     * Per-request `RequestContext`. Forwarded to the planner agent so
+     * user-scoped model resolution (OBO) stays in effect.
+     */
+    requestContext?: RequestContext;
+    /**
+     * Cooperative cancellation. Forwarded to `resolveData` and the
+     * planner agent. Note: the chart task continues running in the
+     * background after the parent request ends, so external abort
+     * signals are best-effort; typical use is to leave this unset
+     * and let the 1h TTL cap stale entries.
      */
     signal?: AbortSignal;
 }
-/** Output of {@link runChartPlanner}: a fully-formed Echarts spec. */
-export interface RunChartPlannerResult {
-    option: Record<string, unknown>;
-    chartType: ChartPlan["chartType"];
+/**
+ * Mint a `chartId`, cache an empty `{ chartId }` placeholder
+ * synchronously, and kick off a background task that resolves the
+ * dataset and runs the planner. Returns the `chartId` once the
+ * placeholder lands so the first {@link fetchChart} call always
+ * sees an entry (no spurious 404 race).
+ *
+ * The background task swallows its own failures and writes them
+ * as `error` entries, so callers never see a rejected promise.
+ * Cache state machine:
+ *
+ *   - just after this call returns: `{ chartId }` (processing)
+ *   - on planner success:           `{ chartId, result }`
+ *   - on data / planner failure:    `{ chartId, error }`
+ */
+export declare function prepareChart(opts: PrepareChartOptions): Promise<{
+    chartId: string;
+}>;
+/** Inputs to {@link fetchChart}. */
+export interface FetchChartOptions {
+    /**
+     * Server-side polling budget in ms. When the entry stays in
+     * the processing state past this window, the helper returns the
+     * last seen value (still processing) so the client can re-poll.
+     * Defaults to {@link DEFAULT_FETCH_TIMEOUT_MS} (60s).
+     */
+    timeoutMs?: number;
+    /**
+     * Poll interval in ms. Defaults to
+     * {@link DEFAULT_FETCH_INTERVAL_MS} (250ms).
+     */
+    intervalMs?: number;
+    /** External cancellation handle (e.g. request `req.signal`). */
+    signal?: AbortSignal;
 }
 /**
- * Run the chart planner against the given dataset and return a
- * full Echarts `EChartsOption` JSON. Pure async function: no
- * writer side-effects, no id minting, no background work.
- * Producers (the `render_data` tool, the Genie agent,
- * anything else that needs a chart) await this and stitch the
- * result into whatever shape their wire contract needs.
+ * Long-poll the chart cache until the entry settles (`result` or
+ * `error` set), the entry is missing, or the server-side timeout
+ * elapses.
+ *
+ * Returns:
+ *   - the resolved {@link Chart} when it settled, errored, or
+ *     stayed in processing past `timeoutMs` (so the client can
+ *     re-poll);
+ *   - `undefined` when the entry is missing or expired (the
+ *     consumer should treat as 404).
+ *
+ * `signal` lets the caller cancel ahead of timeout (e.g. the HTTP
+ * request closed). Cancellation propagates to the inter-poll sleep
+ * so the helper returns immediately.
  */
-export declare function runChartPlanner(opts: RunChartPlannerOptions): Promise<RunChartPlannerResult>;
+export declare function fetchChart(chartId: string, options?: FetchChartOptions): Promise<Chart | undefined>;
 /**
- * Build the `render_data` tool bound to the given plugin config.
+ * Build the `render_data` Mastra tool bound to the given plugin
+ * config. Auto-wired as a system tool on every agent (see
+ * `agents.ts`); per-agent tools can shadow it by registering a
+ * same-named entry.
+ *
+ * Thin wrapper over {@link prepareChart} for callers that already
+ * have a dataset in hand. Mints a `chartId` synchronously, caches
+ * an empty placeholder, and kicks off the chart-planner in the
+ * background. Returns just the `chartId`; the host UI resolves
+ * `[chart:<chartId>]` markers by hitting the plugin's
+ * `/embed/chart/:id` route.
  *
- * The tool awaits {@link runChartPlanner} so the planner's
- * latency is attributed to this tool's trace span, then emits
- * one `type: "chart"` writer event carrying the dataset and the
- * resolved `EChartsOption`. The LLM-bound output is just
- * `{ chartId }` so the model's context stays flat regardless of
- * dataset size. Planner failures are caught and surfaced as a
- * `type: "error"` writer event so the slot can fall back to
- * "couldn't render chart" without taking the parent agent down.
+ * For Genie statement results, prefer the Genie agent's
+ * `prepare_chart` tool, which accepts a `statement_id` and
+ * resolves the rows lazily.
  */
 export declare function buildRenderDataTool(config: MastraPluginConfig): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "render_data", unknown>;
-export {};