@opencorestack/opengridx 3.3.0 → 3.5.0

package/lib/ai/index.ts

@@ -0,0 +1,33 @@
+// @opencorestack/opengridx/ai: schema, validator, prompt handler and agent tools for driving the grid
+// from a language model. No React, no dependencies and no AI SDK; the app calls its own model.
+export { getGridAiSchema } from './schema';
+export { validateGridAiState } from './validate';
+export { createGridAiPromptHandler } from './promptHandler';
+export { createGridAgentTools } from './agentTools';
+export type {
+  GridAgentApi,
+  GridAgentTool,
+  GridAgentToolResult,
+  GridAgentToolsOptions,
+  GridAiColumn,
+  GridAiHistoryEntry,
+  GridAiJsonSchema,
+  GridAiModelRequest,
+  GridAiPart,
+  GridAiPartOptions,
+  GridAiPromptContext,
+  GridAiPromptHandlerOptions,
+  GridAiPromptResult,
+  GridAiSchema,
+  GridAiSchemaOptions,
+  GridAiState,
+  GridAiValidateOptions,
+  GridAiValidationError,
+  GridAiValidationResult,
+} from './types';
+export type {
+  GridAiAssistantOptions,
+  GridAiAssistantPanelProps,
+  GridAiAssistantStatus,
+  GridAiChip,
+} from '../types';

package/lib/ai/promptHandler.ts

@@ -0,0 +1,109 @@
+// createGridAiPromptHandler: the `aiAssistant.onPrompt` function for an app's own model. It builds the
+// schema once, calls the app's `callModel`, reads the reply (an object, JSON text, or text with a fenced
+// JSON block) and returns the validated, branded result. The grid never sees the raw reply.
+import type { GridAiPromptContext, GridAiPromptResult } from '../types';
+import { brandGridAiValidated } from '../utils/aiBrand';
+import { hasOwn, isPlainObject } from './columns';
+import { getGridAiSchema } from './schema';
+import type { GridAiColumn, GridAiPartOptions, GridAiPromptHandlerOptions, GridAiValidationError } from './types';
+import { validateGridAiState } from './validate';
+
+const FENCE = '```';
+
+/** A DOMException named `AbortError`, as `fetch` rejects with. */
+export function abortError(): Error {
+  return typeof DOMException === 'function'
+    ? new DOMException('The operation was aborted.', 'AbortError')
+    : Object.assign(new Error('The operation was aborted.'), { name: 'AbortError' });
+}
+
+/**
+ * Splits a text reply into the JSON it holds and the text around it: the whole text when it starts
+ * with `{`, else the first fenced block (with no language or `json`). A plain loop, no regex.
+ */
+export function readModelText(text: string): { json: string | null; message: string } {
+  const trimmed = text.trim();
+  if (trimmed.startsWith('{')) return { json: trimmed, message: '' };
+  const open = text.indexOf(FENCE);
+  const lineEnd = open < 0 ? -1 : text.indexOf('\n', open + FENCE.length);
+  const close = lineEnd < 0 ? -1 : text.indexOf(FENCE, lineEnd + 1);
+  const lang = close < 0 ? '' : text.slice(open + FENCE.length, lineEnd).trim().toLowerCase();
+  if (close < 0 || (lang !== '' && lang !== 'json')) return { json: null, message: trimmed };
+  return {
+    json: text.slice(lineEnd + 1, close),
+    message: `${text.slice(0, open)}${text.slice(close + FENCE.length)}`.trim(),
+  };
+}
+
+function errorText(error: unknown): string {
+  if (error instanceof Error && error.message) return error.message;
+  return typeof error === 'string' && error ? error : 'Unknown error';
+}
+
+/** A branded result with an empty state: nothing to apply, the errors explain why. */
+function emptyResult(errors: GridAiValidationError[], message?: string): GridAiPromptResult {
+  const result: GridAiPromptResult = { state: brandGridAiValidated({}), errors };
+  if (message) result.message = message;
+  return brandGridAiValidated(result);
+}
+
+/** Validates a model reply into a branded result. Never throws. */
+export function readModelReply(reply: unknown, columns: readonly GridAiColumn[], parts: GridAiPartOptions): GridAiPromptResult {
+  let json: unknown = reply;
+  let message = '';
+  if (typeof reply === 'string') {
+    const text = readModelText(reply);
+    if (text.json === null) return emptyResult([], text.message || undefined);
+    json = text.json;
+    message = text.message;
+  } else if (isPlainObject(reply) && hasOwn(reply, 'message') && typeof reply.message === 'string') {
+    // A reply such as { filterModel, message: 'Showing paid orders' }: the message is not state.
+    const { message: text, ...rest } = reply;
+    json = rest;
+    message = text as string;
+  }
+  const result: GridAiPromptResult = validateGridAiState(json, columns, parts);
+  if (message) result.message = message;
+  return result;
+}
+
+/**
+ * Builds `aiAssistant.onPrompt` for your own model. On each prompt it calls
+ * `callModel({ prompt, schema, currentState, history }, { signal })`, reads the reply (a state object,
+ * a JSON string, or a fenced JSON block inside text), validates it with `validateGridAiState` and
+ * returns the branded result. A `callModel` throw or rejection becomes
+ * `{ state: {}, errors: [{ path: '', message }] }`; an abort rejects with an `AbortError`.
+ * @since v3.5
+ */
+export function createGridAiPromptHandler<C extends GridAiColumn>(
+  options: GridAiPromptHandlerOptions<C>,
+): (prompt: string, context: GridAiPromptContext) => Promise<GridAiPromptResult> {
+  const { columns, callModel, parts, schemaOptions = {} } = options;
+  const partOptions: GridAiPartOptions = { include: parts ?? schemaOptions.include, exclude: schemaOptions.exclude };
+  const schema = getGridAiSchema(columns, { ...schemaOptions, ...partOptions });
+
+  return async (prompt, context) => {
+    const signal = context?.signal ?? new AbortController().signal;
+    if (signal.aborted) throw abortError();
+    // Stop resolves the prompt at once, even when callModel ignores the signal.
+    const aborted = new Promise<never>((_, reject) => {
+      signal.addEventListener('abort', () => reject(abortError()), { once: true });
+    });
+    aborted.catch(() => undefined);
+    let reply: unknown;
+    try {
+      const request = {
+        prompt: String(prompt),
+        schema,
+        currentState: context?.currentState ?? {},
+        history: Array.isArray(context?.history) ? context.history : [],
+      };
+      reply = await Promise.race([callModel(request, { signal }), aborted]);
+    } catch (error) {
+      if (signal.aborted) throw abortError();
+      return emptyResult([{ path: '', message: `The model call failed: ${errorText(error)}` }]);
+    }
+    if (signal.aborted) throw abortError();
+    return readModelReply(reply, columns, partOptions);
+  };
+}

package/lib/ai/schema.ts

@@ -0,0 +1,214 @@
+// getGridAiSchema: a JSON Schema (draft 2020-12) of the grid state a model may produce. Built from
+// the column definitions only; no row data is read. Same columns and options, same schema.
+import {
+  MAX_FILTER_DEPTH,
+  NO_VALUE_OPS,
+  PART_KEYS,
+  PIVOT_FNS,
+  aggregationFnsOf,
+  isFilterable,
+  isGroupable,
+  isHideable,
+  isSortable,
+  operatorsOf,
+  optionValues,
+  selectedParts,
+  usableColumns,
+} from './columns';
+import type { GridAiColumn, GridAiJsonSchema, GridAiPart, GridAiSchema, GridAiSchemaOptions } from './types';
+
+/** Title of every schema. Also the marker `check-bundle` uses to keep this code out of the core bundle. */
+export const GRID_AI_SCHEMA_TITLE = 'OpenGridX grid state';
+
+const MAX_EXAMPLES = 10;
+
+interface Ctx {
+  descriptions: boolean;
+  examples: boolean;
+}
+
+function label(col: GridAiColumn): string {
+  const header = typeof col.headerName === 'string' && col.headerName !== '' ? col.headerName : col.field;
+  const desc = typeof col.description === 'string' && col.description !== '' ? ` (${col.description})` : '';
+  return `${header}${desc}`;
+}
+
+function describe(node: GridAiJsonSchema, text: string, ctx: Ctx): GridAiJsonSchema {
+  return ctx.descriptions ? { ...node, description: text } : node;
+}
+
+function examplesOf(col: GridAiColumn, ctx: Ctx): unknown[] {
+  if (!ctx.examples || !Array.isArray(col.aiExamples)) return [];
+  return col.aiExamples
+    .filter((v) => typeof v === 'string' || typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v)))
+    .slice(0, MAX_EXAMPLES);
+}
+
+/** Schema of one filter value for the column's type. */
+function valueSchema(col: GridAiColumn, ctx: Ctx): GridAiJsonSchema {
+  let node: GridAiJsonSchema;
+  switch (col.type) {
+    case 'number':
+      node = { type: 'number' };
+      break;
+    case 'date':
+      node = { type: 'string', format: 'date' };
+      break;
+    case 'boolean':
+      node = { type: 'boolean' };
+      break;
+    case 'singleSelect': {
+      const values = optionValues(col);
+      const one: GridAiJsonSchema = values.length > 0 ? { enum: values } : { type: 'string' };
+      node = { anyOf: [one, { type: 'array', items: one }] };
+      break;
+    }
+    default:
+      node = { type: 'string' };
+  }
+  const examples = examplesOf(col, ctx);
+  return examples.length > 0 ? { ...node, examples } : node;
+}
+
+function filterItemSchema(col: GridAiColumn, ctx: Ctx): GridAiJsonSchema {
+  const operators = operatorsOf(col);
+  const noValue = operators.filter((op) => NO_VALUE_OPS.includes(op));
+  const hint = col.type === 'singleSelect' ? '; isAnyOf takes an array' : '';
+  const ops = noValue.length > 0 ? `${noValue.join(' and ')} take no value${hint}` : hint.slice(2);
+  return describe(
+    {
+      type: 'object',
+      properties: {
+        field: { const: col.field },
+        operator: { enum: operators },
+        value: valueSchema(col, ctx),
+      },
+      required: ['field', 'operator'],
+      additionalProperties: false,
+    },
+    ops ? `${label(col)}: ${ops}` : label(col),
+    ctx,
+  );
+}
+
+function filterSchema(cols: GridAiColumn[], ctx: Ctx, defs: Record<string, GridAiJsonSchema>): GridAiJsonSchema | null {
+  const filterable = cols.filter(isFilterable);
+  const properties: Record<string, GridAiJsonSchema> = {};
+  const logic = { enum: ['and', 'or'] };
+  if (filterable.length > 0) {
+    defs.filterItem = { oneOf: filterable.map((col) => filterItemSchema(col, ctx)) };
+    // Groups are unrolled to MAX_FILTER_DEPTH levels: the deepest one holds items only.
+    for (let depth = MAX_FILTER_DEPTH; depth >= 1; depth--) {
+      const child = depth === MAX_FILTER_DEPTH ? { $ref: '#/$defs/filterItem' } : { anyOf: [{ $ref: '#/$defs/filterItem' }, { $ref: `#/$defs/filterGroup${depth + 1}` }] };
+      defs[`filterGroup${depth}`] = {
+        type: 'object',
+        properties: { logicOperator: logic, items: { type: 'array', items: child } },
+        required: ['logicOperator', 'items'],
+        additionalProperties: false,
+      };
+    }
+    properties.items = { type: 'array', items: { anyOf: [{ $ref: '#/$defs/filterItem' }, { $ref: '#/$defs/filterGroup1' }] } };
+    properties.logicOperator = logic;
+  }
+  properties.quickFilterValues = describe({ type: 'array', items: { type: 'string' } }, 'Words a row must contain, in any column', ctx);
+  return { type: 'object', properties, additionalProperties: false };
+}
+
+function fieldEnum(cols: GridAiColumn[]): GridAiJsonSchema {
+  return { enum: cols.map((c) => c.field) };
+}
+
+function partSchema(part: GridAiPart, cols: GridAiColumn[], ctx: Ctx, defs: Record<string, GridAiJsonSchema>): GridAiJsonSchema | null {
+  switch (part) {
+    case 'filter':
+      return filterSchema(cols, ctx, defs);
+    case 'sort': {
+      const sortable = cols.filter(isSortable);
+      if (sortable.length === 0) return null;
+      return describe(
+        {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: { field: fieldEnum(sortable), sort: { enum: ['asc', 'desc'] } },
+            required: ['field', 'sort'],
+            additionalProperties: false,
+          },
+        },
+        'Most significant first',
+        ctx,
+      );
+    }
+    case 'grouping': {
+      const groupable = cols.filter(isGroupable);
+      if (groupable.length === 0) return null;
+      return describe({ type: 'array', items: fieldEnum(groupable), uniqueItems: true }, 'Outermost first', ctx);
+    }
+    case 'aggregation': {
+      const properties: Record<string, GridAiJsonSchema> = {};
+      for (const col of cols) {
+        const fns = aggregationFnsOf(col);
+        if (fns.length > 0) properties[col.field] = describe({ enum: fns }, label(col), ctx);
+      }
+      if (Object.keys(properties).length === 0) return null;
+      return { type: 'object', properties, additionalProperties: false };
+    }
+    case 'pivot': {
+      const dims = cols.filter(isGroupable);
+      const values = cols
+        .map((col) => ({ col, fns: aggregationFnsOf(col, PIVOT_FNS) }))
+        .filter((v) => v.fns.length > 0)
+        .map(({ col, fns }) => describe({
+          type: 'object',
+          properties: { field: { const: col.field }, aggFn: { enum: fns } },
+          required: ['field', 'aggFn'],
+          additionalProperties: false,
+        }, label(col), ctx));
+      if (dims.length === 0 || values.length === 0) return null;
+      const dimArray = { type: 'array', items: fieldEnum(dims), uniqueItems: true };
+      return {
+        type: 'object',
+        properties: { rowFields: dimArray, columnFields: dimArray, valueFields: { type: 'array', items: { oneOf: values } } },
+        required: ['rowFields', 'columnFields', 'valueFields'],
+        additionalProperties: false,
+      };
+    }
+    case 'columnVisibility': {
+      const properties: Record<string, GridAiJsonSchema> = {};
+      for (const col of cols.filter(isHideable)) properties[col.field] = describe({ type: 'boolean' }, label(col), ctx);
+      if (Object.keys(properties).length === 0) return null;
+      return describe({ type: 'object', properties, additionalProperties: false }, 'false hides a column', ctx);
+    }
+  }
+}
+
+/**
+ * A JSON Schema (draft 2020-12) of the grid state a model may return for these columns: filter,
+ * sort, grouping, aggregation, pivot and column visibility, each limited to the fields, operators
+ * and functions the columns allow. Send it with the user's prompt to a model with structured
+ * output, then pass the reply to `validateGridAiState`. Reads column definitions only, never rows.
+ * @since v3.4
+ */
+export function getGridAiSchema<C extends GridAiColumn>(columns: readonly C[], options: GridAiSchemaOptions = {}): GridAiSchema {
+  const ctx: Ctx = { descriptions: options.descriptions !== false, examples: options.examples !== false };
+  const cols = usableColumns(columns);
+  const defs: Record<string, GridAiJsonSchema> = {};
+  const properties: Record<string, GridAiJsonSchema> = {};
+  for (const part of selectedParts(options)) {
+    const node = partSchema(part, cols, ctx, defs);
+    if (node) properties[PART_KEYS[part]] = node;
+  }
+  const schema: GridAiSchema = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    schemaVersion: 1,
+    title: GRID_AI_SCHEMA_TITLE,
+    type: 'object',
+    properties,
+    additionalProperties: false,
+  };
+  if (ctx.descriptions) {
+    schema.description = 'Grid state to apply. Include only the parts the user asked to change.';
+  }
+  if (Object.keys(defs).length > 0) schema.$defs = defs;
+  return schema;
+}

package/lib/ai/types.ts

@@ -0,0 +1,152 @@
+import type { GridAiPart, GridAiState, GridAiValidationError } from '../types';
+
+// The state types live with the grid's own types (lib/types), so the grid's `aiAssistant` prop can
+// use them without importing this entry point. They are type-only and re-exported from here.
+export type {
+  GridAiHistoryEntry,
+  GridAiPart,
+  GridAiPromptContext,
+  GridAiPromptResult,
+  GridAiState,
+  GridAiValidationError,
+} from '../types';
+
+/**
+ * The column properties the AI toolkit reads. A `GridColDef` (typed or untyped) is accepted as is;
+ * renderers, getters and formatters are never called, and no row data is read.
+ * @since v3.4
+ */
+export interface GridAiColumn {
+  field: string;
+  headerName?: string;
+  description?: string;
+  type?: string;
+  filterable?: boolean;
+  sortable?: boolean;
+  groupable?: boolean;
+  hideable?: boolean;
+  aggregable?: boolean;
+  availableAggregationFunctions?: readonly string[];
+  valueOptions?: readonly (string | number | { value: unknown; label: string })[];
+  /** Example values sent to the model. Real data: see `GridColDef.aiExamples`. */
+  aiExamples?: readonly unknown[];
+  /** Internal spacer columns are skipped. */
+  isSpacer?: boolean;
+}
+
+/** Chooses the parts of the state; `exclude` wins over `include`. Default: every part. */
+export interface GridAiPartOptions {
+  include?: readonly GridAiPart[];
+  exclude?: readonly GridAiPart[];
+}
+
+export interface GridAiSchemaOptions extends GridAiPartOptions {
+  /**
+   * Put each column's `headerName` and `description` into the schema, so the model can map the
+   * user's words ("revenue") to a field (`amt_usd`).
+   * @default true
+   */
+  descriptions?: boolean;
+  /**
+   * Include the columns' `aiExamples`. Columns without `aiExamples` never send example values.
+   * @default true
+   */
+  examples?: boolean;
+}
+
+export type GridAiValidateOptions = GridAiPartOptions;
+
+/** A JSON Schema (draft 2020-12) node. */
+export type GridAiJsonSchema = { [keyword: string]: unknown };
+
+/** The schema returned by `getGridAiSchema`. `schemaVersion` changes when its shape changes. */
+export interface GridAiSchema extends GridAiJsonSchema {
+  $schema: 'https://json-schema.org/draft/2020-12/schema';
+  schemaVersion: 1;
+  type: 'object';
+  properties: Record<string, GridAiJsonSchema>;
+}
+
+/**
+ * The validated state and what was dropped. Since v3.5 the result and its `state` carry the brand
+ * `Symbol.for('opengridx.ai.validated')` (not enumerable), which the grid's `aiAssistant` checks.
+ */
+export interface GridAiValidationResult {
+  state: GridAiState;
+  errors: GridAiValidationError[];
+}
+
+/** What `callModel` receives: send it to your model. @since v3.5 */
+export interface GridAiModelRequest {
+  prompt: string;
+  /** `getGridAiSchema(columns, …)`: use it as the structured-output format. */
+  schema: GridAiSchema;
+  currentState: GridAiState;
+  history: { prompt: string; applied: GridAiState }[];
+}
+
+/** Options of `createGridAiPromptHandler`. @since v3.5 */
+export interface GridAiPromptHandlerOptions<C extends GridAiColumn = GridAiColumn> {
+  columns: readonly C[];
+  /**
+   * Calls your model. Resolve with its reply: a state object, a JSON string, or text with a fenced JSON
+   * block. A string `message` key next to the state, or the text around the JSON, is shown as the reply.
+   */
+  callModel: (request: GridAiModelRequest, options: { signal: AbortSignal }) => Promise<unknown>;
+  /** The parts the model may change (schema and validation). Default: every part. */
+  parts?: readonly GridAiPart[];
+  /** Options for the schema; its `include` / `exclude` also limit validation. */
+  schemaOptions?: GridAiSchemaOptions;
+}
+
+/**
+ * The part of `GridApi` the agent tools use. A grid's `apiRef.current` fits it.
+ * @since v3.5
+ */
+export interface GridAgentApi {
+  getGridAiState: () => GridAiState;
+  setFilterModel: (model: NonNullable<GridAiState['filterModel']>) => void;
+  setSortModel: (model: NonNullable<GridAiState['sortModel']>) => void;
+  setRowGroupingModel: (model: NonNullable<GridAiState['rowGroupingModel']>) => void;
+  setAggregationModel: (model: NonNullable<GridAiState['aggregationModel']>) => void;
+  setColumnVisibilityModel: (model: NonNullable<GridAiState['columnVisibilityModel']>) => void;
+  getAllFilteredRows: () => object[];
+}
+
+/** Options of `createGridAgentTools`. @since v3.5 */
+export interface GridAgentToolsOptions {
+  /** Adds `get_row_summary`, the one tool that sends row values to the model. Default: false. */
+  allowRowAccess?: boolean;
+  /** Fields `get_row_summary` returns. Default: every column the tools were given. */
+  fields?: readonly string[];
+  /** Most rows `get_row_summary` returns. Default: 20. */
+  maxRows?: number;
+}
+
+/** What every tool's `execute` resolves with. It never throws or rejects. @since v3.5 */
+export interface GridAgentToolResult {
+  ok: boolean;
+  /** The state the tool applied. */
+  applied?: GridAiState;
+  /** Why nothing was applied. */
+  errors?: GridAiValidationError[];
+  /** `get_grid_state`: the current models. */
+  state?: GridAiState;
+  /** `get_grid_state`: the columns the tools know. */
+  columns?: { field: string; headerName: string; type: string }[];
+  /** `get_row_summary`: the number of rows that pass the filter. */
+  rowCount?: number;
+  /** `get_row_summary`: the first rows, limited to the allowed fields. */
+  rows?: Record<string, unknown>[];
+}
+
+/**
+ * A tool in the shape most tool-calling APIs take: `name`, `description`, a JSON Schema for the input
+ * and `execute`. No SDK is involved. @since v3.5
+ */
+export interface GridAgentTool {
+  name: string;
+  description: string;
+  inputSchema: GridAiJsonSchema;
+  execute: (input: unknown) => Promise<GridAgentToolResult>;
+}