photon-grid-core 2.0.0 → 2.0.4

package/photon-ai/photon-ai-service.d.ts

@@ -1,5 +1,6 @@
 import type { GridApi } from '../core/grid-api';
 import { PhotonAICommandRegistry } from './photon-ai-registry';
+import { type PhotonAIProvider } from './provider/ai-provider.types';
 import type { PhotonCommandResult } from './photon-ai.types';
 /**
  * The only public entry point into Photon AI. Runs the full deterministic
@@ -36,11 +37,25 @@ export declare class PhotonAIService {
     private readonly resolver;
     private readonly builder;
     private readonly executor;
+    /**
+     * Generative back-end, when one was configured (e.g. Gemini). `null` keeps
+     * Photon AI in its default fully-deterministic mode — the two modes share
+     * the same registry, executor, and result contract, so nothing else changes.
+     */
+    private readonly provider;
+    /** Extra domain guidance appended to the base system instruction; only meaningful when {@link provider} is set. */
+    private readonly providerSystemInstruction?;
+    /** Builds a fresh grid-context snapshot per generative request. Lazily constructed alongside a provider. */
+    private readonly contextBuilder;
+    /** Reshapes model-generated actions into executable commands. Lazily constructed alongside a provider. */
+    private readonly commandNormalizer;
     /**
      * @param api - The grid's own `GridApi` — every command runs through it, never around it.
      * @param registry - Supply a custom registry to fully replace the built-ins, or omit to get sort/filter/pin/visibility/grouping/selection out of the box.
+     * @param provider - Optional generative back-end. When supplied, {@link submitAsync} routes prompts through it; when omitted, only the synchronous deterministic pipeline is available.
+     * @param providerSystemInstruction - Optional extra guidance appended to the base system instruction sent to {@link provider}.
      */
-    constructor(api: GridApi, registry?: PhotonAICommandRegistry);
+    constructor(api: GridApi, registry?: PhotonAICommandRegistry, provider?: PhotonAIProvider | null, providerSystemInstruction?: string);
     /** A registry pre-populated with every built-in intent — the default `PhotonAIService` uses when none is supplied. */
     static createDefaultRegistry(): PhotonAICommandRegistry;
     /** Registers additional custom intents at runtime (e.g. a third-party feature's own `registerAI()`). */
@@ -54,6 +69,28 @@ export declare class PhotonAIService {
      * aggregates their results.
      */
     submit(rawInput: string): PhotonCommandResult;
+    /** `true` when a generative back-end is configured — i.e. {@link submitAsync} will use the model rather than the deterministic pipeline. */
+    hasProvider(): boolean;
+    /**
+     * Async counterpart to {@link submit}. When a provider is configured, the
+     * prompt is interpreted by the model: the grid's current context (columns,
+     * capabilities, state) plus the user command are sent to the provider, and
+     * every returned action is executed through the *same* `CommandExecutor` the
+     * deterministic pipeline uses — so the two backends are interchangeable.
+     *
+     * With no provider configured, this simply awaits the synchronous
+     * deterministic pipeline, so callers can always use the async entry point
+     * regardless of mode. Like {@link submit}, it always resolves — provider and
+     * execution failures come back as `{ success: false }`, never a rejection.
+     */
+    submitAsync(rawInput: string, signal?: AbortSignal): Promise<PhotonCommandResult>;
+    /**
+     * Runs the model's actions in order and folds them into a single
+     * {@link PhotonCommandResult}. The model's natural-language `reply` is the
+     * user-facing message; per-command execution failures are appended so a
+     * partial success is never silently swallowed.
+     */
+    private executeGeneratedActions;
     private runClause;
     private runCommands;
     /**

package/photon-ai/photon-ai-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"photon-ai-service.d.ts","sourceRoot":"","sources":["../../src/photon-ai/photon-ai-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAOhD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,OAAO,KAAK,EAAiB,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAkB5E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,eAAe;IAYd,OAAO,CAAC,GAAG;IAXvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAE3C;;;OAGG;gBACiB,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,uBAAuB;IAOpE,sHAAsH;IACtH,MAAM,CAAC,qBAAqB,IAAI,uBAAuB;IAMvD,wGAAwG;IACxG,WAAW,IAAI,uBAAuB;IAItC,+IAA+I;IAC/I,mBAAmB,IAAI,IAAI;IAI3B;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB;IAe7C,OAAO,CAAC,SAAS;IAwBjB,OAAO,CAAC,WAAW;IAUnB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAgBxB,uJAAuJ;IACvJ,OAAO,CAAC,iBAAiB;IAKzB,mNAAmN;IACnN,OAAO,CAAC,WAAW;CASpB"}
+{"version":3,"file":"photon-ai-service.d.ts","sourceRoot":"","sources":["../../src/photon-ai/photon-ai-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAOhD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAM/D,OAAO,EAAyB,KAAK,gBAAgB,EAAuB,MAAM,8BAA8B,CAAC;AACjH,OAAO,KAAK,EAAiB,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAkB5E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,eAAe;IA4BxB,OAAO,CAAC,GAAG;IA3Bb,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAE3C;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IACnD,mHAAmH;IACnH,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAS;IACpD,4GAA4G;IAC5G,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA4B;IAC3D,0GAA0G;IAC1G,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA2B;IAE7D;;;;;OAKG;gBAEO,GAAG,EAAE,OAAO,EACpB,QAAQ,CAAC,EAAE,uBAAuB,EAClC,QAAQ,CAAC,EAAE,gBAAgB,GAAG,IAAI,EAClC,yBAAyB,CAAC,EAAE,MAAM;IAapC,sHAAsH;IACtH,MAAM,CAAC,qBAAqB,IAAI,uBAAuB;IAMvD,wGAAwG;IACxG,WAAW,IAAI,uBAAuB;IAItC,+IAA+I;IAC/I,mBAAmB,IAAI,IAAI;IAI3B;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB;IAe7C,4IAA4I;IAC5I,WAAW,IAAI,OAAO;IAItB;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAuBvF;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAwB/B,OAAO,CAAC,SAAS;IAwBjB,OAAO,CAAC,WAAW;IAUnB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAgBxB,uJAAuJ;IACvJ,OAAO,CAAC,iBAAiB;IAKzB,mNAAmN;IACnN,OAAO,CAAC,WAAW;CASpB"}

package/photon-ai/photon-ai-service.js

@@ -7,6 +7,10 @@ import { CommandExecutor } from './command-executor';
 import { PhotonAICommandRegistry } from './photon-ai-registry';
 import { PhotonAIMemoryStore, columnSignature } from './photon-ai-memory';
 import { registerBuiltinCommands } from './builtins';
+import { GridContextBuilder } from './provider/grid-context-builder';
+import { CommandNormalizer } from './provider/command-normalizer';
+import { buildSystemInstruction } from './provider/system-prompt';
+import { describeProviderError } from './provider/ai-provider.types';
 /**
  * Pure conversational openers — no command content, so `normalizeInput`
  * strips every word away (they're all in its filler list) and the clause
@@ -49,8 +53,10 @@ export class PhotonAIService {
     /**
      * @param api - The grid's own `GridApi` — every command runs through it, never around it.
      * @param registry - Supply a custom registry to fully replace the built-ins, or omit to get sort/filter/pin/visibility/grouping/selection out of the box.
+     * @param provider - Optional generative back-end. When supplied, {@link submitAsync} routes prompts through it; when omitted, only the synchronous deterministic pipeline is available.
+     * @param providerSystemInstruction - Optional extra guidance appended to the base system instruction sent to {@link provider}.
      */
-    constructor(api, registry) {
+    constructor(api, registry, provider, providerSystemInstruction) {
         this.api = api;
         this.parser = new IntentParser();
         this.builder = new CommandBuilder();
@@ -58,6 +64,10 @@ export class PhotonAIService {
         this.executor = new CommandExecutor(this.registry);
         this.memory = new PhotonAIMemoryStore(columnSignature(api.getAllColumns().map((c) => c.colId)));
         this.resolver = new EntityResolver(this.memory);
+        this.provider = provider ?? null;
+        this.providerSystemInstruction = providerSystemInstruction;
+        this.contextBuilder = this.provider ? new GridContextBuilder(this.api, this.registry) : null;
+        this.commandNormalizer = this.provider ? new CommandNormalizer(this.api) : null;
     }
     /** A registry pre-populated with every built-in intent — the default `PhotonAIService` uses when none is supplied. */
     static createDefaultRegistry() {
@@ -92,6 +102,67 @@ export class PhotonAIService {
             message: results.map((r, i) => `${i + 1}) ${r.message}`).join(' '),
         };
     }
+    /** `true` when a generative back-end is configured — i.e. {@link submitAsync} will use the model rather than the deterministic pipeline. */
+    hasProvider() {
+        return this.provider !== null;
+    }
+    /**
+     * Async counterpart to {@link submit}. When a provider is configured, the
+     * prompt is interpreted by the model: the grid's current context (columns,
+     * capabilities, state) plus the user command are sent to the provider, and
+     * every returned action is executed through the *same* `CommandExecutor` the
+     * deterministic pipeline uses — so the two backends are interchangeable.
+     *
+     * With no provider configured, this simply awaits the synchronous
+     * deterministic pipeline, so callers can always use the async entry point
+     * regardless of mode. Like {@link submit}, it always resolves — provider and
+     * execution failures come back as `{ success: false }`, never a rejection.
+     */
+    async submitAsync(rawInput, signal) {
+        const trimmed = rawInput.trim();
+        if (!trimmed)
+            return { success: false, message: 'Type a command first.' };
+        if (!this.provider || !this.contextBuilder || !this.commandNormalizer) {
+            return this.submit(trimmed);
+        }
+        try {
+            const gridContext = this.contextBuilder.build();
+            const generation = await this.provider.generate({
+                systemInstruction: buildSystemInstruction(this.providerSystemInstruction),
+                gridContext,
+                userCommand: trimmed,
+                signal,
+            });
+            return this.executeGeneratedActions(generation.actions, generation.reply);
+        }
+        catch (err) {
+            return { success: false, message: describeProviderError(err) };
+        }
+    }
+    /**
+     * Runs the model's actions in order and folds them into a single
+     * {@link PhotonCommandResult}. The model's natural-language `reply` is the
+     * user-facing message; per-command execution failures are appended so a
+     * partial success is never silently swallowed.
+     */
+    executeGeneratedActions(actions, reply) {
+        const normalizer = this.commandNormalizer;
+        const executionMessages = [];
+        const failures = [];
+        let lastCommand;
+        for (const action of actions) {
+            const command = normalizer.normalize(action);
+            const result = this.executor.execute(command, this.api);
+            executionMessages.push(result.message);
+            if (result.command)
+                lastCommand = result.command;
+            if (!result.success)
+                failures.push(result.message);
+        }
+        const message = reply || executionMessages.join(' ') || 'I understood your request but there was nothing to do.';
+        const combined = failures.length > 0 ? `${message} (${failures.join(' ')})` : message;
+        return { success: failures.length === 0, message: combined, command: lastCommand };
+    }
     runClause(clause) {
         const normalized = normalizeInput(clause);
         if (!normalized)

package/photon-ai/photon-ai-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"photon-ai-service.js","sourceRoot":"","sources":["../../src/photon-ai/photon-ai-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"photon-ai-service.js","sourceRoot":"","sources":["../../src/photon-ai/photon-ai-service.ts"],"names":[],"mappings":"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"}

package/photon-ai/provider/ai-provider.types.d.ts

@@ -0,0 +1,174 @@
+import type { ColumnDataType, ColumnPinPosition } from '../../types/column.types';
+/**
+ * The runtime contracts shared by every Photon AI generative provider. These
+ * types are intentionally provider-agnostic: {@link PhotonAIService} builds a
+ * {@link PhotonAIProviderRequest}, hands it to whichever {@link PhotonAIProvider}
+ * is configured, and executes the returned {@link PhotonAIGeneration} through
+ * the same command pipeline used by the deterministic interpreter — so a new
+ * back-end (Gemini today, another model tomorrow) only ever implements
+ * {@link PhotonAIProvider.generate}, never touches the grid.
+ */
+/**
+ * One column, distilled to exactly what a language model needs to choose a
+ * target and a valid value. Deliberately excludes render functions, widths,
+ * and other presentation-only fields — sending them would waste tokens and
+ * leak irrelevant internals into the prompt.
+ */
+export interface PhotonAIColumnContext {
+    /** Stable machine id — the value the model must echo back in a command's `colId`/`colIds`. */
+    readonly colId: string;
+    /** Human-facing column title (what the user is most likely to type). */
+    readonly header: string;
+    /** Underlying data field key. */
+    readonly field: string;
+    /** Data type — tells the model which filter operators and value formats make sense. */
+    readonly type: ColumnDataType;
+    readonly sortable: boolean;
+    readonly filterable: boolean;
+    readonly groupable: boolean;
+    /** Current pin side, or `null` when unpinned. */
+    readonly pinned: ColumnPinPosition;
+    readonly visible: boolean;
+    /**
+     * Allowed values for `dropdown`/`enum`-style columns, so the model filters
+     * by a value that actually exists rather than guessing. Omitted for
+     * free-form columns.
+     */
+    readonly options?: readonly (string | number)[];
+}
+/**
+ * A single grid action the model is allowed to emit, mirrored 1:1 from the
+ * live intent registry so the catalog can never drift from what the grid can
+ * actually execute. `type` is the intent key the model must reproduce in a
+ * command; `description` is the human blurb registered with that intent.
+ */
+export interface PhotonAICapability {
+    readonly type: string;
+    readonly description: string;
+}
+/** A concise, model-friendly snapshot of the grid's live state at prompt time. */
+export interface PhotonAIGridState {
+    readonly totalRowCount: number;
+    readonly visibleRowCount: number;
+    readonly sort: readonly PhotonAISortState[];
+    readonly filters: readonly PhotonAIFilterState[];
+    readonly groupedColumns: readonly string[];
+    readonly selectedRowCount: number;
+}
+export interface PhotonAISortState {
+    readonly colId: string;
+    readonly order: 'asc' | 'desc';
+}
+export interface PhotonAIFilterState {
+    readonly colId: string;
+    /** Short human summary of the active condition, e.g. `greaterThan 5000`. */
+    readonly summary: string;
+}
+/**
+ * Everything about the grid the model receives alongside the user's command:
+ * what columns exist, what actions are possible, and what state the grid is
+ * currently in. Built fresh per request by {@link PhotonAIService} so the
+ * model always reasons over the grid's *current* shape.
+ */
+export interface PhotonGridContext {
+    readonly columns: readonly PhotonAIColumnContext[];
+    readonly capabilities: readonly PhotonAICapability[];
+    readonly state: PhotonAIGridState;
+}
+/**
+ * One executable instruction returned by the model. Structurally identical to
+ * a {@link import('../photon-ai.types').PhotonCommand} — `type` is an intent
+ * key from the capability catalog and `params` carries that intent's inputs —
+ * so a generated action flows straight into the existing `CommandExecutor`
+ * after light normalization.
+ */
+export interface PhotonAIAction {
+    readonly type: string;
+    readonly params: Readonly<Record<string, unknown>>;
+}
+/** The parsed, validated result of one provider call. */
+export interface PhotonAIGeneration {
+    /** Zero or more grid actions to execute, in order. Empty for a pure conversational reply. */
+    readonly actions: readonly PhotonAIAction[];
+    /** Natural-language message to show the user (streamed into the panel). */
+    readonly reply: string;
+}
+/**
+ * The provider-neutral, transformer-facing view of one prompt. This is what a
+ * consumer's {@link import('../../types/photon-ai.types').PhotonAIProviderConfig.requestTransformer}
+ * receives — everything needed to build any provider's request body, with no
+ * transport concern (URL, headers, auth) leaking in.
+ */
+export interface PhotonAIRequest {
+    /** The assembled system instruction (role + output contract + any extra guidance). */
+    readonly systemInstruction: string;
+    /** The raw user command typed into the panel. */
+    readonly userCommand: string;
+    /** Structured grid context (columns, capabilities, live state). */
+    readonly gridContext: PhotonGridContext;
+    /** Resolved model id for this request. */
+    readonly model: string;
+    /** Resolved sampling temperature for this request. */
+    readonly temperature: number;
+}
+/**
+ * The provider-neutral, transformer-facing result. A consumer's
+ * {@link import('../../types/photon-ai.types').PhotonAIProviderConfig.responseTransformer}
+ * must return this shape from whatever the provider's raw JSON looked like.
+ * Identical in structure to {@link PhotonAIGeneration}.
+ */
+export type PhotonAIResponse = PhotonAIGeneration;
+/**
+ * What a provider receives. The service assembles the {@link systemInstruction}
+ * (role + output contract) and the structured {@link gridContext}; the provider
+ * decides how to serialize them into its own wire format and how to call its
+ * endpoint.
+ */
+export interface PhotonAIProviderRequest {
+    readonly systemInstruction: string;
+    readonly gridContext: PhotonGridContext;
+    readonly userCommand: string;
+    /** Optional cooperative cancellation (e.g. panel closed mid-flight). */
+    readonly signal?: AbortSignal;
+}
+/**
+ * The one method every generative back-end implements. Must resolve with a
+ * validated {@link PhotonAIResponse} or reject with a
+ * {@link PhotonAIProviderError} — never leak a raw transport error to the UI.
+ */
+export interface PhotonAIProvider {
+    generate(request: PhotonAIProviderRequest): Promise<PhotonAIResponse>;
+}
+/** Categorized failure reason, so the panel can show an actionable message rather than a stack trace. */
+export declare enum PhotonAIErrorKind {
+    /** The request never reached the provider (offline, DNS, CORS). */
+    Network = "network",
+    /** Provider returned a non-2xx status not covered by a more specific kind. */
+    Http = "http",
+    /** HTTP 429 / quota exhausted. */
+    RateLimit = "rate-limit",
+    /** HTTP 401/403 — missing, invalid, or unauthorized API key. */
+    Auth = "auth",
+    /** The model refused or its output was safety-blocked. */
+    Blocked = "blocked",
+    /** Response arrived but could not be parsed into a {@link PhotonAIGeneration}. */
+    InvalidResponse = "invalid-response",
+    /** The request exceeded {@link import('../../types/photon-ai.types').PhotonAIProviderConfig.requestTimeoutMs}. */
+    Timeout = "timeout"
+}
+/**
+ * The single error type providers throw. Carries a machine-readable
+ * {@link PhotonAIErrorKind} (for retry/telemetry decisions) plus a
+ * user-facing message the panel can display verbatim.
+ */
+export declare class PhotonAIProviderError extends Error {
+    readonly kind: PhotonAIErrorKind;
+    /** Upstream HTTP status, when the failure originated from an HTTP response. */
+    readonly status?: number | undefined;
+    constructor(kind: PhotonAIErrorKind, message: string, 
+    /** Upstream HTTP status, when the failure originated from an HTTP response. */
+    status?: number | undefined);
+}
+/** A short, friendly one-liner for each failure kind, used when a provider throws to the panel. */
+export declare function describeProviderError(error: unknown): string;
+//# sourceMappingURL=ai-provider.types.d.ts.map

package/photon-ai/provider/ai-provider.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-provider.types.d.ts","sourceRoot":"","sources":["../../../src/photon-ai/provider/ai-provider.types.ts"],"names":[],"mappings":"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"}

package/photon-ai/provider/ai-provider.types.js

@@ -0,0 +1,42 @@
+/** Categorized failure reason, so the panel can show an actionable message rather than a stack trace. */
+export var PhotonAIErrorKind;
+(function (PhotonAIErrorKind) {
+    /** The request never reached the provider (offline, DNS, CORS). */
+    PhotonAIErrorKind["Network"] = "network";
+    /** Provider returned a non-2xx status not covered by a more specific kind. */
+    PhotonAIErrorKind["Http"] = "http";
+    /** HTTP 429 / quota exhausted. */
+    PhotonAIErrorKind["RateLimit"] = "rate-limit";
+    /** HTTP 401/403 — missing, invalid, or unauthorized API key. */
+    PhotonAIErrorKind["Auth"] = "auth";
+    /** The model refused or its output was safety-blocked. */
+    PhotonAIErrorKind["Blocked"] = "blocked";
+    /** Response arrived but could not be parsed into a {@link PhotonAIGeneration}. */
+    PhotonAIErrorKind["InvalidResponse"] = "invalid-response";
+    /** The request exceeded {@link import('../../types/photon-ai.types').PhotonAIProviderConfig.requestTimeoutMs}. */
+    PhotonAIErrorKind["Timeout"] = "timeout";
+})(PhotonAIErrorKind || (PhotonAIErrorKind = {}));
+/**
+ * The single error type providers throw. Carries a machine-readable
+ * {@link PhotonAIErrorKind} (for retry/telemetry decisions) plus a
+ * user-facing message the panel can display verbatim.
+ */
+export class PhotonAIProviderError extends Error {
+    constructor(kind, message, 
+    /** Upstream HTTP status, when the failure originated from an HTTP response. */
+    status) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+        this.name = 'PhotonAIProviderError';
+    }
+}
+/** A short, friendly one-liner for each failure kind, used when a provider throws to the panel. */
+export function describeProviderError(error) {
+    if (error instanceof PhotonAIProviderError)
+        return error.message;
+    if (error instanceof Error)
+        return `Photon AI request failed: ${error.message}`;
+    return 'Photon AI request failed due to an unexpected error.';
+}
+//# sourceMappingURL=ai-provider.types.js.map

package/photon-ai/provider/ai-provider.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-provider.types.js","sourceRoot":"","sources":["../../../src/photon-ai/provider/ai-provider.types.ts"],"names":[],"mappings":"AA2JA,yGAAyG;AACzG,MAAM,CAAN,IAAY,iBAeX;AAfD,WAAY,iBAAiB;IAC3B,mEAAmE;IACnE,wCAAmB,CAAA;IACnB,8EAA8E;IAC9E,kCAAa,CAAA;IACb,kCAAkC;IAClC,6CAAwB,CAAA;IACxB,gEAAgE;IAChE,kCAAa,CAAA;IACb,0DAA0D;IAC1D,wCAAmB,CAAA;IACnB,kFAAkF;IAClF,yDAAoC,CAAA;IACpC,kHAAkH;IAClH,wCAAmB,CAAA;AACrB,CAAC,EAfW,iBAAiB,KAAjB,iBAAiB,QAe5B;AAED;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YACW,IAAuB,EAChC,OAAe;IACf,+EAA+E;IACtE,MAAe;QAExB,KAAK,CAAC,OAAO,CAAC,CAAC;QALN,SAAI,GAAJ,IAAI,CAAmB;QAGvB,WAAM,GAAN,MAAM,CAAS;QAGxB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,mGAAmG;AACnG,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,KAAK,YAAY,qBAAqB;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IACjE,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,6BAA6B,KAAK,CAAC,OAAO,EAAE,CAAC;IAChF,OAAO,sDAAsD,CAAC;AAChE,CAAC"}

package/photon-ai/provider/command-normalizer.d.ts

@@ -0,0 +1,36 @@
+import type { GridApi } from '../../core/grid-api';
+import type { PhotonCommand } from '../photon-ai.types';
+import type { PhotonAIAction } from './ai-provider.types';
+/**
+ * Bridges a model-generated {@link PhotonAIAction} to a fully-formed
+ * {@link PhotonCommand} the existing `CommandExecutor` can run unchanged.
+ *
+ * A language model reliably produces the *shape* of a command (an intent key
+ * plus the target column and value) but not the incidental details the
+ * deterministic builders add for free — the display `header`, `Date` objects
+ * for date filters, a default operator, numeric coercion. Rather than force
+ * the model to reproduce all of that (fragile, token-heavy), this normalizer
+ * backfills it deterministically from the live grid:
+ *
+ * - resolves `colId`/`colIds` against real columns (tolerating a header used
+ *   in place of an id, since models occasionally do that),
+ * - backfills the `header` param used by every intent's result message,
+ * - coerces `applyFilter` values to the column's type (ISO string → `Date`,
+ *   numeric string → `number`) and defaults a sensible operator.
+ *
+ * It is intentionally the *only* place provider output is reshaped, mirroring
+ * the role `CommandBuilder` plays for the deterministic pipeline.
+ */
+export declare class CommandNormalizer {
+    private readonly api;
+    constructor(api: GridApi);
+    /** Reshapes one action into an executable command. Never throws — worst case, the executor reports an unknown/invalid command. */
+    normalize(action: PhotonAIAction): PhotonCommand;
+    /** Resolves and canonicalizes `colId`/`colIds`, then backfills the human `header` label. */
+    private normalizeColumnTargets;
+    /** Coerces `applyFilter`'s value(s) to the target column's data type and supplies a default operator. */
+    private normalizeFilterParams;
+    /** Matches by exact colId first, then case-insensitively by header — models sometimes echo the visible header. */
+    private resolveColumn;
+}
+//# sourceMappingURL=command-normalizer.d.ts.map

package/photon-ai/provider/command-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-normalizer.d.ts","sourceRoot":"","sources":["../../../src/photon-ai/provider/command-normalizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,OAAO;IAEzC,kIAAkI;IAClI,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa;IAYhD,4FAA4F;IAC5F,OAAO,CAAC,sBAAsB;IAsB9B,yGAAyG;IACzG,OAAO,CAAC,qBAAqB;IAiB7B,kHAAkH;IAClH,OAAO,CAAC,aAAa;CAMtB"}

package/photon-ai/provider/command-normalizer.js

@@ -0,0 +1,120 @@
+/**
+ * Bridges a model-generated {@link PhotonAIAction} to a fully-formed
+ * {@link PhotonCommand} the existing `CommandExecutor` can run unchanged.
+ *
+ * A language model reliably produces the *shape* of a command (an intent key
+ * plus the target column and value) but not the incidental details the
+ * deterministic builders add for free — the display `header`, `Date` objects
+ * for date filters, a default operator, numeric coercion. Rather than force
+ * the model to reproduce all of that (fragile, token-heavy), this normalizer
+ * backfills it deterministically from the live grid:
+ *
+ * - resolves `colId`/`colIds` against real columns (tolerating a header used
+ *   in place of an id, since models occasionally do that),
+ * - backfills the `header` param used by every intent's result message,
+ * - coerces `applyFilter` values to the column's type (ISO string → `Date`,
+ *   numeric string → `number`) and defaults a sensible operator.
+ *
+ * It is intentionally the *only* place provider output is reshaped, mirroring
+ * the role `CommandBuilder` plays for the deterministic pipeline.
+ */
+export class CommandNormalizer {
+    constructor(api) {
+        this.api = api;
+    }
+    /** Reshapes one action into an executable command. Never throws — worst case, the executor reports an unknown/invalid command. */
+    normalize(action) {
+        const params = { ...action.params };
+        this.normalizeColumnTargets(params);
+        if (action.type === 'applyFilter') {
+            this.normalizeFilterParams(params);
+        }
+        return { type: action.type, params };
+    }
+    /** Resolves and canonicalizes `colId`/`colIds`, then backfills the human `header` label. */
+    normalizeColumnTargets(params) {
+        if (typeof params.colId === 'string') {
+            const column = this.resolveColumn(params.colId);
+            if (column) {
+                params.colId = column.colId;
+                if (typeof params.header !== 'string')
+                    params.header = column.header;
+            }
+        }
+        if (Array.isArray(params.colIds)) {
+            const columns = params.colIds
+                .map((id) => (typeof id === 'string' ? this.resolveColumn(id) : undefined))
+                .filter((c) => !!c);
+            if (columns.length > 0) {
+                params.colIds = columns.map((c) => c.colId);
+                if (typeof params.header !== 'string') {
+                    params.header = columns.map((c) => c.header).join('", "');
+                }
+            }
+        }
+    }
+    /** Coerces `applyFilter`'s value(s) to the target column's data type and supplies a default operator. */
+    normalizeFilterParams(params) {
+        const colId = typeof params.colId === 'string' ? params.colId : undefined;
+        const column = colId ? this.resolveColumn(colId) : undefined;
+        if (!column)
+            return;
+        params.colId = column.colId;
+        if (typeof params.operator !== 'string') {
+            params.operator = defaultOperatorFor(column.type);
+        }
+        params.value = coerceValue(params.value, column.type);
+        if (params.valueTo !== undefined) {
+            params.valueTo = coerceValue(params.valueTo, column.type);
+        }
+    }
+    /** Matches by exact colId first, then case-insensitively by header — models sometimes echo the visible header. */
+    resolveColumn(idOrHeader) {
+        const byId = this.api.getColumn(idOrHeader);
+        if (byId)
+            return byId;
+        const needle = idOrHeader.trim().toLowerCase();
+        return this.api.getAllColumns().find((c) => c.header.toLowerCase() === needle);
+    }
+}
+/** Default operator when the model omitted one — mirrors the deterministic filter builder. */
+function defaultOperatorFor(type) {
+    if (type === 'number' || type === 'currency' || type === 'percentage')
+        return 'equals';
+    if (type === 'date' || type === 'time')
+        return 'equals';
+    if (type === 'boolean')
+        return 'equals';
+    if (type === 'dropdown')
+        return 'equals';
+    return 'contains';
+}
+/** Coerces a JSON-safe primitive from the model into the runtime type the grid's filter engine expects. */
+function coerceValue(value, type) {
+    if (value === null || value === undefined)
+        return value;
+    if (type === 'date' || type === 'time') {
+        if (value instanceof Date)
+            return value;
+        const date = new Date(String(value));
+        return Number.isNaN(date.getTime()) ? value : date;
+    }
+    if (type === 'number' || type === 'currency' || type === 'percentage') {
+        if (typeof value === 'number')
+            return value;
+        const num = Number(String(value).replace(/,/g, '').trim());
+        return Number.isNaN(num) ? value : num;
+    }
+    if (type === 'boolean') {
+        if (typeof value === 'boolean')
+            return value;
+        const text = String(value).trim().toLowerCase();
+        if (['true', 'yes', 'active', 'enabled', 'on', '1'].includes(text))
+            return true;
+        if (['false', 'no', 'inactive', 'disabled', 'off', '0'].includes(text))
+            return false;
+        return value;
+    }
+    return value;
+}
+//# sourceMappingURL=command-normalizer.js.map

package/photon-ai/provider/command-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-normalizer.js","sourceRoot":"","sources":["../../../src/photon-ai/provider/command-normalizer.ts"],"names":[],"mappings":"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"}

package/photon-ai/provider/grid-context-builder.d.ts

@@ -0,0 +1,37 @@
+import type { GridApi } from '../../core/grid-api';
+import type { PhotonAICommandRegistry } from '../photon-ai-registry';
+import type { PhotonGridContext } from './ai-provider.types';
+/**
+ * Distills the live grid into the compact {@link PhotonGridContext} a language
+ * model needs to interpret a command: which columns exist, which actions are
+ * possible, and what the grid currently looks like.
+ *
+ * Every piece is read from the *live* {@link GridApi} and
+ * {@link PhotonAICommandRegistry} at build time, so the model always reasons
+ * over the grid's current shape — including any custom intents a host app
+ * registered at runtime (they appear in {@link buildCapabilities} automatically
+ * because it reads the registry, never a hard-coded list). This is what keeps
+ * the generative back-end in lock-step with the deterministic one: both are
+ * driven by the same registry.
+ */
+export declare class GridContextBuilder {
+    private readonly api;
+    private readonly registry;
+    constructor(api: GridApi, registry: PhotonAICommandRegistry);
+    /** Builds a fresh snapshot. Cheap enough to call once per prompt. */
+    build(): PhotonGridContext;
+    private buildColumns;
+    private toColumnContext;
+    /** Enumerated values a `dropdown`/`enum` column accepts, so the model filters by a real value. */
+    private columnOptions;
+    /**
+     * The catalog of actions the model may emit — one entry per registered
+     * intent. Sourced from the registry so it never drifts from what
+     * `CommandExecutor` can actually run.
+     */
+    private buildCapabilities;
+    private buildState;
+    private buildSortState;
+    private buildFilterState;
+}
+//# sourceMappingURL=grid-context-builder.d.ts.map