photon-grid-core 2.0.1 → 2.0.5

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"grid-context-builder.d.ts","sourceRoot":"","sources":["../../../src/photon-ai/provider/grid-context-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAMV,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;GAYG;AACH,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,uBAAuB;IAGpD,qEAAqE;IACrE,KAAK,IAAI,iBAAiB;IAQ1B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,eAAe;IAiBvB,kGAAkG;IAClG,OAAO,CAAC,aAAa;IAMrB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,gBAAgB;CAMzB"}

package/photon-ai/provider/grid-context-builder.js

@@ -0,0 +1,96 @@
+/**
+ * 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 class GridContextBuilder {
+    constructor(api, registry) {
+        this.api = api;
+        this.registry = registry;
+    }
+    /** Builds a fresh snapshot. Cheap enough to call once per prompt. */
+    build() {
+        return {
+            columns: this.buildColumns(),
+            capabilities: this.buildCapabilities(),
+            state: this.buildState(),
+        };
+    }
+    buildColumns() {
+        return this.api.getAllColumns().map((col) => this.toColumnContext(col));
+    }
+    toColumnContext(col) {
+        const options = this.columnOptions(col);
+        return {
+            colId: col.colId,
+            header: col.header,
+            field: col.field,
+            type: col.type,
+            // These flags default to enabled in the grid, so treat "unset" as `true`.
+            sortable: col.sortable !== false,
+            filterable: col.filterable !== false,
+            groupable: col.groupable !== false,
+            pinned: col.pinned ?? null,
+            visible: col.visible !== false,
+            ...(options ? { options } : {}),
+        };
+    }
+    /** Enumerated values a `dropdown`/`enum` column accepts, so the model filters by a real value. */
+    columnOptions(col) {
+        if (col.dropdownOptions?.length)
+            return col.dropdownOptions.map((o) => o.value);
+        if (col.enumOptions?.length)
+            return col.enumOptions;
+        return undefined;
+    }
+    /**
+     * 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.
+     */
+    buildCapabilities() {
+        return this.registry
+            .getAll()
+            .map((intent) => ({ type: intent.key, description: intent.description ?? intent.key }));
+    }
+    buildState() {
+        return {
+            totalRowCount: this.api.getAllRows().filter((r) => r.type === 'data').length,
+            visibleRowCount: this.api.getVisibleRows().filter((r) => r.type === 'data').length,
+            sort: this.buildSortState(),
+            filters: this.buildFilterState(),
+            groupedColumns: [...(this.api.getGridState().groupedColumns ?? [])],
+            selectedRowCount: this.api.getSelectedCount(),
+        };
+    }
+    buildSortState() {
+        return this.api.getSortConfig().map((s) => ({ colId: s.colId, order: s.order }));
+    }
+    buildFilterState() {
+        return Object.values(this.api.getFilterModel()).map((filter) => ({
+            colId: filter.colId,
+            summary: summarizeFilter(filter),
+        }));
+    }
+}
+/** Compresses a column filter into a single human/model-readable phrase. */
+function summarizeFilter(filter) {
+    if (filter.selectedIds?.length)
+        return `in [${filter.selectedIds.join(', ')}]`;
+    const condition = filter.conditions[0];
+    if (!condition)
+        return 'active';
+    if (condition.operator === 'blank' || condition.operator === 'notBlank')
+        return condition.operator;
+    const to = condition.valueTo !== undefined ? `..${String(condition.valueTo)}` : '';
+    return `${condition.operator} ${String(condition.value)}${to}`;
+}
+//# sourceMappingURL=grid-context-builder.js.map

package/photon-ai/provider/grid-context-builder.js.map

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

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

@@ -0,0 +1,42 @@
+import type { PhotonAIProviderConfig } from '../../types/photon-ai.types';
+import { type PhotonAIProvider, type PhotonAIProviderRequest, type PhotonAIResponse } from './ai-provider.types';
+/**
+ * The single, provider-agnostic {@link PhotonAIProvider}. It is driven entirely
+ * by a consumer-supplied {@link PhotonAIProviderConfig}: pick a hosted
+ * {@link PhotonAIProviderType} for out-of-the-box defaults (endpoint, model,
+ * auth, wire format), or override any field — up to and including the full
+ * request/response wire format via `requestTransformer`/`responseTransformer` —
+ * to talk to any JSON HTTP model endpoint.
+ *
+ * Uses the native `fetch` API only (no SDK), so it runs in every browser Photon
+ * Grid supports. The API key is read from config at request time and applied
+ * with the provider's auth scheme; it is never hard-coded, cached, or logged.
+ * Every failure mode — HTTP errors, rate limits, auth problems, safety blocks,
+ * timeouts, and malformed JSON — surfaces as a categorized
+ * {@link PhotonAIProviderError}.
+ */
+export declare class HttpAIProvider implements PhotonAIProvider {
+    private readonly type;
+    private readonly preset;
+    private readonly apiKey;
+    private readonly apiUrl;
+    private readonly model;
+    private readonly headers;
+    private readonly temperature;
+    private readonly timeoutMs;
+    private readonly transformRequest;
+    private readonly transformResponse;
+    constructor(config: PhotonAIProviderConfig);
+    generate(request: PhotonAIProviderRequest): Promise<PhotonAIResponse>;
+    /** Resolves the final URL (auth-in-query for Gemini, plain otherwise). */
+    private buildUrl;
+    /** Merges Content-Type + provider auth headers + consumer headers (consumer wins). */
+    private buildHeaders;
+    /** POSTs the request as JSON, enforcing the configured timeout via `AbortController`. */
+    private fetchWithTimeout;
+    /** Validates the HTTP status, mapping known failure statuses (auth, rate-limit) to categorized errors, and returns the parsed JSON body. */
+    private parseHttpResponse;
+    /** Best-effort extraction of a provider error message from a non-2xx body (`{ error: { message } }` or `{ error: "..." }`). */
+    private readErrorMessage;
+}
+//# sourceMappingURL=http-ai-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http-ai-provider.d.ts","sourceRoot":"","sources":["../../../src/photon-ai/provider/http-ai-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAG1E,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAE5B,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAK7B;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAe,YAAW,gBAAgB;IACrD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAwC;IACzE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0C;gBAEhE,MAAM,EAAE,sBAAsB;IA2BpC,QAAQ,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAkB3E,0EAA0E;IAC1E,OAAO,CAAC,QAAQ;IAKhB,sFAAsF;IACtF,OAAO,CAAC,YAAY;IAKpB,yFAAyF;YAC3E,gBAAgB;IA+B9B,4IAA4I;YAC9H,iBAAiB;IAoC/B,+HAA+H;YACjH,gBAAgB;CAS/B"}