@dbx-tools/appkit-mastra 0.3.44 → 0.4.0

package/lib/src/chart.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Chart planner + chart cache.
+ *
+ * Self-contained chart subsystem with two layers:
+ *
+ *   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.
+ *
+ * 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.
+ *
+ * Wire-format schemas live in `@dbx-tools/shared-mastra` so
+ * the demo client and any other UI consumer share the exact same
+ * shape this module reads and writes.
+ *
+ * @module
+ */
+import { type Chart } from "@dbx-tools/shared-mastra";
+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.
+ */
+export declare const chartPlanSchema: z.ZodObject<{
+    chartType: z.ZodUnion<readonly [z.ZodLiteral<"bar">, z.ZodLiteral<"line">, z.ZodLiteral<"area">, z.ZodLiteral<"scatter">, z.ZodLiteral<"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.ZodPipe<z.ZodTransform<number | number[] | {
+            name: string;
+            value: number;
+        } | null, unknown>, z.ZodUnion<readonly [z.ZodNumber, z.ZodNull, z.ZodArray<z.ZodNumber>, z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodNumber;
+        }, z.core.$strip>]>>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * 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}.
+ */
+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>;
+export type ChartPlannerRequest = z.infer<typeof chartPlannerRequestSchema>;
+/** Inputs to {@link prepareChart}. */
+export interface PrepareChartOptions {
+    /** Plugin config; resolves the planner agent's model. */
+    config: MastraPluginConfig;
+    /**
+     * Identity that owns the minted chart. Only a {@link fetchChart} call
+     * carrying the same key resolves it. Use {@link resolveUserKey}.
+     */
+    userKey: string;
+    /** Display title forwarded to the planner agent. */
+    title?: string;
+    /** Optional intent hint forwarded to the planner agent. */
+    description?: string;
+    /**
+     * 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;
+}
+/**
+ * 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 {
+    /**
+     * Identity the chart must belong to. A chart minted under a different key
+     * is indistinguishable from an unknown id. Use {@link resolveUserKey}.
+     */
+    userKey: string;
+    /**
+     * 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;
+}
+/**
+ * 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, expired, or owned by
+ *     another identity (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 fetchChart(chartId: string, options: FetchChartOptions): Promise<Chart | undefined>;
+/**
+ * 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.
+ *
+ * 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<{
+    title: string;
+    data: readonly Record<string, unknown>[];
+    description?: string | undefined;
+}, {
+    chartId: string;
+}, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, "render_data", unknown>;