photon-grid-core 2.0.0 → 2.0.4

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":"AAaA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,kBAAkB;IAC7B,YACmB,GAAY,EACZ,QAAiC;QADjC,QAAG,GAAH,GAAG,CAAS;QACZ,aAAQ,GAAR,QAAQ,CAAyB;IACjD,CAAC;IAEJ,qEAAqE;IACrE,KAAK;QACH,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE;YAC5B,YAAY,EAAE,IAAI,CAAC,iBAAiB,EAAE;YACtC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE;SACzB,CAAC;IACJ,CAAC;IAEO,YAAY;QAClB,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1E,CAAC;IAEO,eAAe,CAAC,GAAc;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;QACxC,OAAO;YACL,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,0EAA0E;YAC1E,QAAQ,EAAE,GAAG,CAAC,QAAQ,KAAK,KAAK;YAChC,UAAU,EAAE,GAAG,CAAC,UAAU,KAAK,KAAK;YACpC,SAAS,EAAE,GAAG,CAAC,SAAS,KAAK,KAAK;YAClC,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI;YAC1B,OAAO,EAAE,GAAG,CAAC,OAAO,KAAK,KAAK;YAC9B,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChC,CAAC;IACJ,CAAC;IAED,kGAAkG;IAC1F,aAAa,CAAC,GAAc;QAClC,IAAI,GAAG,CAAC,eAAe,EAAE,MAAM;YAAE,OAAO,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAChF,IAAI,GAAG,CAAC,WAAW,EAAE,MAAM;YAAE,OAAO,GAAG,CAAC,WAAW,CAAC;QACpD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;OAIG;IACK,iBAAiB;QACvB,OAAO,IAAI,CAAC,QAAQ;aACjB,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC5F,CAAC;IAEO,UAAU;QAChB,OAAO;YACL,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,MAAM;YAC5E,eAAe,EAAE,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,MAAM;YAClF,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE;YAC3B,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE;YAChC,cAAc,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;YACnE,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE;SAC9C,CAAC;IACJ,CAAC;IAEO,cAAc;QACpB,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACnF,CAAC;IAEO,gBAAgB;QACtB,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC/D,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,OAAO,EAAE,eAAe,CAAC,MAAM,CAAC;SACjC,CAAC,CAAC,CAAC;IACN,CAAC;CACF;AAED,4EAA4E;AAC5E,SAAS,eAAe,CAAC,MAAoB;IAC3C,IAAI,MAAM,CAAC,WAAW,EAAE,MAAM;QAAE,OAAO,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IAC/E,MAAM,SAAS,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACvC,IAAI,CAAC,SAAS;QAAE,OAAO,QAAQ,CAAC;IAChC,IAAI,SAAS,CAAC,QAAQ,KAAK,OAAO,IAAI,SAAS,CAAC,QAAQ,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC,QAAQ,CAAC;IACnG,MAAM,EAAE,GAAG,SAAS,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACnF,OAAO,GAAG,SAAS,CAAC,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC;AACjE,CAAC"}

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"}

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

@@ -0,0 +1,125 @@
+import { PhotonAIProviderType } from '../../types/photon-ai.types';
+import { getPreset } from './presets';
+import { PhotonAIErrorKind, PhotonAIProviderError, } from './ai-provider.types';
+/** Default request deadline. */
+const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * 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 class HttpAIProvider {
+    constructor(config) {
+        this.type = config.type ?? PhotonAIProviderType.Gemini;
+        this.preset = getPreset(this.type);
+        // A Custom provider ships no defaults — it must be fully specified.
+        if (!this.preset) {
+            if (!config.apiUrl || !config.requestTransformer || !config.responseTransformer) {
+                throw new PhotonAIProviderError(PhotonAIErrorKind.Http, 'A custom Photon AI provider requires apiUrl, requestTransformer, and responseTransformer.');
+            }
+        }
+        this.apiKey = config.apiKey?.trim() || undefined;
+        this.apiUrl = config.apiUrl?.trim() || this.preset?.defaultApiUrl || '';
+        this.model = config.model?.trim() || this.preset?.defaultModel || '';
+        this.headers = { ...(config.headers ?? {}) };
+        this.temperature = config.temperature ?? 0;
+        this.timeoutMs = config.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+        // Consumer transformers win; otherwise fall back to the preset's. The
+        // Custom-provider guard above guarantees both exist when there's no preset.
+        this.transformRequest = config.requestTransformer ?? this.preset.transformRequest;
+        this.transformResponse = config.responseTransformer ?? this.preset.transformResponse;
+    }
+    async generate(request) {
+        const neutral = {
+            systemInstruction: request.systemInstruction,
+            userCommand: request.userCommand,
+            gridContext: request.gridContext,
+            model: this.model,
+            temperature: this.temperature,
+        };
+        const body = this.transformRequest(neutral);
+        const url = this.buildUrl();
+        const headers = this.buildHeaders();
+        const response = await this.fetchWithTimeout(url, headers, body, request.signal);
+        const payload = await this.parseHttpResponse(response);
+        return this.transformResponse(payload);
+    }
+    /** Resolves the final URL (auth-in-query for Gemini, plain otherwise). */
+    buildUrl() {
+        if (this.preset)
+            return this.preset.buildUrl(this.apiUrl, this.model, this.apiKey);
+        return this.apiUrl;
+    }
+    /** Merges Content-Type + provider auth headers + consumer headers (consumer wins). */
+    buildHeaders() {
+        const auth = this.preset ? this.preset.buildHeaders(this.apiKey) : {};
+        return { 'Content-Type': 'application/json', ...auth, ...this.headers };
+    }
+    /** POSTs the request as JSON, enforcing the configured timeout via `AbortController`. */
+    async fetchWithTimeout(url, headers, body, external) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        const onExternalAbort = () => controller.abort();
+        external?.addEventListener('abort', onExternalAbort, { once: true });
+        try {
+            return await fetch(url, { method: 'POST', headers, body: JSON.stringify(body), signal: controller.signal });
+        }
+        catch (err) {
+            if (external?.aborted) {
+                throw new PhotonAIProviderError(PhotonAIErrorKind.Network, 'Photon AI request was cancelled.');
+            }
+            if (controller.signal.aborted) {
+                throw new PhotonAIProviderError(PhotonAIErrorKind.Timeout, `The model did not respond within ${this.timeoutMs / 1000}s. Please try again.`);
+            }
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new PhotonAIProviderError(PhotonAIErrorKind.Network, `Couldn't reach the model provider: ${detail}`);
+        }
+        finally {
+            clearTimeout(timer);
+            external?.removeEventListener('abort', onExternalAbort);
+        }
+    }
+    /** Validates the HTTP status, mapping known failure statuses (auth, rate-limit) to categorized errors, and returns the parsed JSON body. */
+    async parseHttpResponse(response) {
+        if (response.ok) {
+            try {
+                return await response.json();
+            }
+            catch {
+                throw new PhotonAIProviderError(PhotonAIErrorKind.InvalidResponse, 'The model provider returned a response that was not valid JSON.');
+            }
+        }
+        const message = await this.readErrorMessage(response);
+        const suffix = message ? ` ${message}` : '';
+        if (response.status === 429) {
+            throw new PhotonAIProviderError(PhotonAIErrorKind.RateLimit, `Rate limit reached. Please wait a moment and try again.${suffix}`, 429);
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new PhotonAIProviderError(PhotonAIErrorKind.Auth, `The model provider rejected the API key (HTTP ${response.status}).${suffix}`, response.status);
+        }
+        throw new PhotonAIProviderError(PhotonAIErrorKind.Http, `The model provider request failed (HTTP ${response.status}).${suffix}`, response.status);
+    }
+    /** Best-effort extraction of a provider error message from a non-2xx body (`{ error: { message } }` or `{ error: "..." }`). */
+    async readErrorMessage(response) {
+        try {
+            const payload = (await response.json());
+            if (typeof payload.error === 'string')
+                return payload.error.trim();
+            return payload.error?.message?.trim() ?? '';
+        }
+        catch {
+            return '';
+        }
+    }
+}
+//# sourceMappingURL=http-ai-provider.js.map

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

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

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

@@ -0,0 +1,30 @@
+import type { PhotonAIProviderConfig } from '../../types/photon-ai.types';
+import type { PhotonAIProvider } from './ai-provider.types';
+export type { PhotonAIProvider, PhotonAIProviderRequest, PhotonAIRequest, PhotonAIResponse, PhotonAIGeneration, PhotonAIAction, PhotonGridContext, PhotonAIColumnContext, PhotonAICapability, PhotonAIGridState, PhotonAISortState, PhotonAIFilterState, } from './ai-provider.types';
+export { PhotonAIErrorKind, PhotonAIProviderError, describeProviderError } from './ai-provider.types';
+export { HttpAIProvider } from './http-ai-provider';
+export { GridContextBuilder } from './grid-context-builder';
+export { CommandNormalizer } from './command-normalizer';
+export { buildSystemInstruction, serializeGridContext } from './system-prompt';
+export { getPreset, coerceGeneration, parseGenerationText, type ProviderPreset } from './presets';
+export { buildUserPromptText, normalizeActions } from './response-parsing';
+/**
+ * Instantiates the {@link PhotonAIProvider} described by a
+ * {@link PhotonAIProviderConfig}. Returns `null` when no *usable* provider can
+ * be built — this is the signal for
+ * {@link import('../photon-ai-service').PhotonAIService} to stay in its default
+ * deterministic mode rather than fail. Configuring a provider is always
+ * strictly additive: a missing key or an incomplete custom setup silently
+ * keeps the offline pipeline.
+ *
+ * "Usable" means:
+ * - a hosted provider (Gemini/OpenAI/Anthropic) with an API key, or auth
+ *   supplied via `headers`; or
+ * - a {@link PhotonAIProviderType.Custom} provider with an endpoint and both
+ *   transformers.
+ *
+ * Every provider type routes through the single {@link HttpAIProvider}; adding a
+ * new hosted provider is just a new preset, not a new class.
+ */
+export declare function createAIProvider(config: PhotonAIProviderConfig | undefined): PhotonAIProvider | null;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/photon-ai/provider/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAG1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACtG,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAClG,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,SAAS,GAAG,gBAAgB,GAAG,IAAI,CAapG"}

package/photon-ai/provider/index.js

@@ -0,0 +1,42 @@
+import { PhotonAIProviderType } from '../../types/photon-ai.types';
+import { HttpAIProvider } from './http-ai-provider';
+export { PhotonAIErrorKind, PhotonAIProviderError, describeProviderError } from './ai-provider.types';
+export { HttpAIProvider } from './http-ai-provider';
+export { GridContextBuilder } from './grid-context-builder';
+export { CommandNormalizer } from './command-normalizer';
+export { buildSystemInstruction, serializeGridContext } from './system-prompt';
+export { getPreset, coerceGeneration, parseGenerationText } from './presets';
+export { buildUserPromptText, normalizeActions } from './response-parsing';
+/**
+ * Instantiates the {@link PhotonAIProvider} described by a
+ * {@link PhotonAIProviderConfig}. Returns `null` when no *usable* provider can
+ * be built — this is the signal for
+ * {@link import('../photon-ai-service').PhotonAIService} to stay in its default
+ * deterministic mode rather than fail. Configuring a provider is always
+ * strictly additive: a missing key or an incomplete custom setup silently
+ * keeps the offline pipeline.
+ *
+ * "Usable" means:
+ * - a hosted provider (Gemini/OpenAI/Anthropic) with an API key, or auth
+ *   supplied via `headers`; or
+ * - a {@link PhotonAIProviderType.Custom} provider with an endpoint and both
+ *   transformers.
+ *
+ * Every provider type routes through the single {@link HttpAIProvider}; adding a
+ * new hosted provider is just a new preset, not a new class.
+ */
+export function createAIProvider(config) {
+    if (!config)
+        return null;
+    const type = config.type ?? PhotonAIProviderType.Gemini;
+    if (type === PhotonAIProviderType.Custom) {
+        if (!config.apiUrl || !config.requestTransformer || !config.responseTransformer)
+            return null;
+    }
+    else if (!config.apiKey?.trim() && !config.headers) {
+        // A hosted provider with no way to authenticate — fall back to deterministic.
+        return null;
+    }
+    return new HttpAIProvider(config);
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/photon-ai/provider/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAiBpD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACtG,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,mBAAmB,EAAuB,MAAM,WAAW,CAAC;AAClG,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA0C;IACzE,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAEzB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,oBAAoB,CAAC,MAAM,CAAC;IAExD,IAAI,IAAI,KAAK,oBAAoB,CAAC,MAAM,EAAE,CAAC;QACzC,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,kBAAkB,IAAI,CAAC,MAAM,CAAC,mBAAmB;YAAE,OAAO,IAAI,CAAC;IAC/F,CAAC;SAAM,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACrD,8EAA8E;QAC9E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC"}

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

@@ -0,0 +1,29 @@
+import { PhotonAIProviderType } from '../../types/photon-ai.types';
+import { type PhotonAIRequest, type PhotonAIResponse } from './ai-provider.types';
+import { coerceGeneration, parseGenerationText } from './response-parsing';
+/**
+ * A built-in provider preset: everything Photon AI needs to talk to a hosted
+ * LLM out of the box — default endpoint + model, how to place auth, and the
+ * request/response wire transformers. A consumer overrides any of these
+ * through {@link import('../../types/photon-ai.types').PhotonAIProviderConfig},
+ * so a preset is only the *default* wiring, never a hard requirement.
+ */
+export interface ProviderPreset {
+    /** Default REST endpoint. May contain a `{model}` placeholder (Gemini). */
+    readonly defaultApiUrl: string;
+    /** Default model id for this provider. */
+    readonly defaultModel: string;
+    /** Builds the final request URL from the resolved endpoint, model, and key. */
+    buildUrl(apiUrl: string, model: string, apiKey: string | undefined): string;
+    /** Builds provider auth/headers from the key. Merged *under* consumer `headers`. */
+    buildHeaders(apiKey: string | undefined): Record<string, string>;
+    /** Default request-body transformer (overridable via config). */
+    transformRequest(request: PhotonAIRequest): unknown;
+    /** Default response parser (overridable via config). */
+    transformResponse(response: unknown): PhotonAIResponse;
+}
+/** The preset for a provider type, or `null` for {@link PhotonAIProviderType.Custom}. */
+export declare function getPreset(type: PhotonAIProviderType): ProviderPreset | null;
+/** Re-exported so a consumer's custom `responseTransformer` can reuse Photon AI's validated JSON→response coercion. */
+export { coerceGeneration, parseGenerationText };
+//# sourceMappingURL=presets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../../src/photon-ai/provider/presets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAuB,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEhG;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;IAC5E,oFAAoF;IACpF,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjE,iEAAiE;IACjE,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC;IACpD,wDAAwD;IACxD,iBAAiB,CAAC,QAAQ,EAAE,OAAO,GAAG,gBAAgB,CAAC;CACxD;AA8GD,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,IAAI,EAAE,oBAAoB,GAAG,cAAc,GAAG,IAAI,CAE3E;AAED,uHAAuH;AACvH,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,CAAC"}

package/photon-ai/provider/presets.js

@@ -0,0 +1,110 @@
+import { PhotonAIProviderType } from '../../types/photon-ai.types';
+import { PhotonAIErrorKind, PhotonAIProviderError, } from './ai-provider.types';
+import { buildUserPromptText, coerceGeneration, parseGenerationText } from './response-parsing';
+/** Substitutes `{model}` and appends `key=` to a URL, respecting any existing query string. */
+function geminiUrl(apiUrl, model, apiKey) {
+    const withModel = apiUrl.replace('{model}', encodeURIComponent(model));
+    if (!apiKey)
+        return withModel;
+    const separator = withModel.includes('?') ? '&' : '?';
+    return `${withModel}${separator}key=${encodeURIComponent(apiKey)}`;
+}
+/** Reads a nested text field out of an arbitrary parsed JSON body via a path of keys/indices. Returns '' if any hop is missing. */
+function readText(source, path) {
+    let current = source;
+    for (const key of path) {
+        if (current == null)
+            return '';
+        current = current[key];
+    }
+    return typeof current === 'string' ? current : '';
+}
+const GEMINI_PRESET = {
+    defaultApiUrl: 'https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent',
+    defaultModel: 'gemini-2.5-flash',
+    buildUrl: geminiUrl,
+    buildHeaders: () => ({}),
+    transformRequest: (request) => ({
+        systemInstruction: { parts: [{ text: request.systemInstruction }] },
+        contents: [{ role: 'user', parts: [{ text: buildUserPromptText(request) }] }],
+        generationConfig: {
+            // Forces Gemini to always return a parseable JSON object.
+            responseMimeType: 'application/json',
+            temperature: request.temperature,
+        },
+    }),
+    transformResponse: (response) => {
+        const payload = response;
+        if (payload.promptFeedback?.blockReason) {
+            throw new PhotonAIProviderError(PhotonAIErrorKind.Blocked, `Gemini blocked the request (${payload.promptFeedback.blockReason}).`);
+        }
+        const candidate = payload.candidates?.[0];
+        if (!candidate) {
+            throw new PhotonAIProviderError(PhotonAIErrorKind.Blocked, 'Gemini returned no answer for that request.');
+        }
+        const text = candidate.content?.parts?.map((p) => p.text ?? '').join('') ?? '';
+        return parseGenerationText(text);
+    },
+};
+const OPENAI_PRESET = {
+    defaultApiUrl: 'https://api.openai.com/v1/chat/completions',
+    defaultModel: 'gpt-4o-mini',
+    buildUrl: (apiUrl) => apiUrl,
+    buildHeaders: (apiKey) => {
+        const headers = {};
+        if (apiKey)
+            headers.Authorization = `Bearer ${apiKey}`;
+        return headers;
+    },
+    transformRequest: (request) => ({
+        model: request.model,
+        temperature: request.temperature,
+        // Forces a JSON object back (system instruction already mentions JSON, as OpenAI requires).
+        response_format: { type: 'json_object' },
+        messages: [
+            { role: 'system', content: request.systemInstruction },
+            { role: 'user', content: buildUserPromptText(request) },
+        ],
+    }),
+    transformResponse: (response) => parseGenerationText(readText(response, ['choices', 0, 'message', 'content'])),
+};
+const ANTHROPIC_PRESET = {
+    defaultApiUrl: 'https://api.anthropic.com/v1/messages',
+    defaultModel: 'claude-haiku-4-5-20251001',
+    buildUrl: (apiUrl) => apiUrl,
+    buildHeaders: (apiKey) => {
+        const headers = {
+            'anthropic-version': '2023-06-01',
+            // Required for calling the Anthropic API directly from a browser.
+            'anthropic-dangerous-direct-browser-access': 'true',
+        };
+        if (apiKey)
+            headers['x-api-key'] = apiKey;
+        return headers;
+    },
+    transformRequest: (request) => ({
+        model: request.model,
+        max_tokens: 1024,
+        temperature: request.temperature,
+        system: request.systemInstruction,
+        messages: [{ role: 'user', content: buildUserPromptText(request) }],
+    }),
+    transformResponse: (response) => parseGenerationText(readText(response, ['content', 0, 'text'])),
+};
+/**
+ * Built-in presets by provider type. {@link PhotonAIProviderType.Custom} has no
+ * preset — a custom setup must supply its endpoint and both transformers.
+ */
+const PRESETS = {
+    [PhotonAIProviderType.Gemini]: GEMINI_PRESET,
+    [PhotonAIProviderType.OpenAI]: OPENAI_PRESET,
+    [PhotonAIProviderType.Anthropic]: ANTHROPIC_PRESET,
+    [PhotonAIProviderType.Custom]: null,
+};
+/** The preset for a provider type, or `null` for {@link PhotonAIProviderType.Custom}. */
+export function getPreset(type) {
+    return PRESETS[type] ?? null;
+}
+/** Re-exported so a consumer's custom `responseTransformer` can reuse Photon AI's validated JSON→response coercion. */
+export { coerceGeneration, parseGenerationText };
+//# sourceMappingURL=presets.js.map

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

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

package/photon-ai/provider/response-parsing.d.ts

@@ -0,0 +1,22 @@
+import { type PhotonAIAction, type PhotonAIRequest, type PhotonAIResponse } from './ai-provider.types';
+/**
+ * Provider-agnostic helpers for turning a model's raw text/JSON into a
+ * validated {@link PhotonAIResponse}, and for composing the user turn. Shared
+ * by every built-in provider preset so the JSON-recovery and validation logic
+ * lives in exactly one place regardless of which API produced the text.
+ */
+/** The prompt text for the user turn: serialized grid context followed by the command. Reused by every preset. */
+export declare function buildUserPromptText(request: PhotonAIRequest): string;
+/**
+ * Parses the model's JSON *text* into a {@link PhotonAIResponse}. Tolerant of
+ * stray characters around the JSON object (some models wrap it), and validates
+ * that the result carries at least an action or a reply.
+ */
+export declare function parseGenerationText(text: string): PhotonAIResponse;
+/** Validates and normalizes an already-parsed JSON value into a {@link PhotonAIResponse}. Used by response transformers that receive an object. */
+export declare function coerceGeneration(parsed: unknown): PhotonAIResponse;
+/** Coerces the raw `actions` field into a validated, well-typed array — dropping any malformed entries. */
+export declare function normalizeActions(raw: unknown): readonly PhotonAIAction[];
+/** Last-ditch recovery: extract the first balanced `{...}` object from noisy model text. Returns `undefined` when none parses. */
+export declare function tryRecoverJsonObject(text: string): unknown;
+//# sourceMappingURL=response-parsing.d.ts.map

package/photon-ai/provider/response-parsing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-parsing.d.ts","sourceRoot":"","sources":["../../../src/photon-ai/provider/response-parsing.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAE7B;;;;;GAKG;AAEH,kHAAkH;AAClH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAoBlE;AAED,mJAAmJ;AACnJ,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAiBlE;AAED,2GAA2G;AAC3G,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,cAAc,EAAE,CAcxE;AAED,kIAAkI;AAClI,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAS1D"}

package/photon-ai/provider/response-parsing.js

@@ -0,0 +1,79 @@
+import { serializeGridContext } from './system-prompt';
+import { PhotonAIErrorKind, PhotonAIProviderError, } from './ai-provider.types';
+/**
+ * Provider-agnostic helpers for turning a model's raw text/JSON into a
+ * validated {@link PhotonAIResponse}, and for composing the user turn. Shared
+ * by every built-in provider preset so the JSON-recovery and validation logic
+ * lives in exactly one place regardless of which API produced the text.
+ */
+/** The prompt text for the user turn: serialized grid context followed by the command. Reused by every preset. */
+export function buildUserPromptText(request) {
+    return `${serializeGridContext(request.gridContext)}\n\nUSER COMMAND:\n${request.userCommand}`;
+}
+/**
+ * Parses the model's JSON *text* into a {@link PhotonAIResponse}. Tolerant of
+ * stray characters around the JSON object (some models wrap it), and validates
+ * that the result carries at least an action or a reply.
+ */
+export function parseGenerationText(text) {
+    const trimmed = text.trim();
+    if (!trimmed) {
+        throw new PhotonAIProviderError(PhotonAIErrorKind.InvalidResponse, 'The model returned an empty response.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        parsed = tryRecoverJsonObject(trimmed);
+        if (parsed === undefined) {
+            throw new PhotonAIProviderError(PhotonAIErrorKind.InvalidResponse, 'The model returned malformed JSON that could not be parsed.');
+        }
+    }
+    return coerceGeneration(parsed);
+}
+/** Validates and normalizes an already-parsed JSON value into a {@link PhotonAIResponse}. Used by response transformers that receive an object. */
+export function coerceGeneration(parsed) {
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new PhotonAIProviderError(PhotonAIErrorKind.InvalidResponse, 'The model response was not a JSON object.');
+    }
+    const record = parsed;
+    const actions = normalizeActions(record.actions);
+    const reply = typeof record.reply === 'string' ? record.reply.trim() : '';
+    if (actions.length === 0 && !reply) {
+        throw new PhotonAIProviderError(PhotonAIErrorKind.InvalidResponse, 'The model response contained neither an action nor a reply.');
+    }
+    return { actions, reply };
+}
+/** Coerces the raw `actions` field into a validated, well-typed array — dropping any malformed entries. */
+export function normalizeActions(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const actions = [];
+    for (const entry of raw) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const record = entry;
+        if (typeof record.type !== 'string' || !record.type)
+            continue;
+        const params = typeof record.params === 'object' && record.params !== null
+            ? record.params
+            : {};
+        actions.push({ type: record.type, params });
+    }
+    return actions;
+}
+/** Last-ditch recovery: extract the first balanced `{...}` object from noisy model text. Returns `undefined` when none parses. */
+export function tryRecoverJsonObject(text) {
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start < 0 || end <= start)
+        return undefined;
+    try {
+        return JSON.parse(text.slice(start, end + 1));
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=response-parsing.js.map