photon-grid-core 2.0.1 → 2.0.4

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":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,GAGtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAwBhG,+FAA+F;AAC/F,SAAS,SAAS,CAAC,MAAc,EAAE,KAAa,EAAE,MAA0B;IAC1E,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;IACvE,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,SAAS,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IACtD,OAAO,GAAG,SAAS,GAAG,SAAS,OAAO,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;AACrE,CAAC;AAED,mIAAmI;AACnI,SAAS,QAAQ,CAAC,MAAe,EAAE,IAAkC;IACnE,IAAI,OAAO,GAAY,MAAM,CAAC;IAC9B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,OAAO,IAAI,IAAI;YAAE,OAAO,EAAE,CAAC;QAC/B,OAAO,GAAI,OAA4C,CAAC,GAAG,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AACpD,CAAC;AAED,MAAM,aAAa,GAAmB;IACpC,aAAa,EAAE,iFAAiF;IAChG,YAAY,EAAE,kBAAkB;IAChC,QAAQ,EAAE,SAAS;IACnB,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;IACxB,gBAAgB,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC9B,iBAAiB,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,iBAAiB,EAAE,CAAC,EAAE;QACnE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,mBAAmB,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;QAC7E,gBAAgB,EAAE;YAChB,0DAA0D;YAC1D,gBAAgB,EAAE,kBAAkB;YACpC,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC;KACF,CAAC;IACF,iBAAiB,EAAE,CAAC,QAAQ,EAAE,EAAE;QAC9B,MAAM,OAAO,GAAG,QAGf,CAAC;QACF,IAAI,OAAO,CAAC,cAAc,EAAE,WAAW,EAAE,CAAC;YACxC,MAAM,IAAI,qBAAqB,CAC7B,iBAAiB,CAAC,OAAO,EACzB,+BAA+B,OAAO,CAAC,cAAc,CAAC,WAAW,IAAI,CACtE,CAAC;QACJ,CAAC;QACD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC;QAC1C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,qBAAqB,CAAC,iBAAiB,CAAC,OAAO,EAAE,6CAA6C,CAAC,CAAC;QAC5G,CAAC;QACD,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QAC/E,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;CACF,CAAC;AAEF,MAAM,aAAa,GAAmB;IACpC,aAAa,EAAE,4CAA4C;IAC3D,YAAY,EAAE,aAAa;IAC3B,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM;IAC5B,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE;QACvB,MAAM,OAAO,GAA2B,EAAE,CAAC;QAC3C,IAAI,MAAM;YAAE,OAAO,CAAC,aAAa,GAAG,UAAU,MAAM,EAAE,CAAC;QACvD,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,gBAAgB,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC9B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,4FAA4F;QAC5F,eAAe,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE;QACxC,QAAQ,EAAE;YACR,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,iBAAiB,EAAE;YACtD,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,EAAE;SACxD;KACF,CAAC;IACF,iBAAiB,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,mBAAmB,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;CAC/G,CAAC;AAEF,MAAM,gBAAgB,GAAmB;IACvC,aAAa,EAAE,uCAAuC;IACtD,YAAY,EAAE,2BAA2B;IACzC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM;IAC5B,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE;QACvB,MAAM,OAAO,GAA2B;YACtC,mBAAmB,EAAE,YAAY;YACjC,kEAAkE;YAClE,2CAA2C,EAAE,MAAM;SACpD,CAAC;QACF,IAAI,MAAM;YAAE,OAAO,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC;QAC1C,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,gBAAgB,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC9B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,MAAM,EAAE,OAAO,CAAC,iBAAiB;QACjC,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,EAAE,CAAC;KACpE,CAAC;IACF,iBAAiB,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,mBAAmB,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;CACjG,CAAC;AAEF;;;GAGG;AACH,MAAM,OAAO,GAAkE;IAC7E,CAAC,oBAAoB,CAAC,MAAM,CAAC,EAAE,aAAa;IAC5C,CAAC,oBAAoB,CAAC,MAAM,CAAC,EAAE,aAAa;IAC5C,CAAC,oBAAoB,CAAC,SAAS,CAAC,EAAE,gBAAgB;IAClD,CAAC,oBAAoB,CAAC,MAAM,CAAC,EAAE,IAAI;CACpC,CAAC;AAEF,yFAAyF;AACzF,MAAM,UAAU,SAAS,CAAC,IAA0B;IAClD,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AAC/B,CAAC;AAED,uHAAuH;AACvH,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,CAAC"}

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

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

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

package/photon-ai/provider/system-prompt.d.ts

@@ -0,0 +1,26 @@
+import type { PhotonGridContext } from './ai-provider.types';
+/**
+ * Assembles the system instruction sent to a generative provider. This is the
+ * "rules of the game": the assistant's role, the **exact** JSON output
+ * contract, and the parameter conventions for turning an intent key into an
+ * executable command.
+ *
+ * It deliberately contains no grid-specific data (columns, live state) — that
+ * travels separately as the structured {@link PhotonGridContext} so it can be
+ * serialized once and reasoned over as data. Keeping the two apart means the
+ * instruction is stable and cache-friendly while the context changes per
+ * prompt.
+ *
+ * The output contract matches {@link import('./ai-provider.types').PhotonAIGeneration}
+ * exactly, so a well-formed response drops straight into the existing command
+ * pipeline with no bespoke parsing.
+ */
+export declare function buildSystemInstruction(extraInstruction?: string): string;
+/**
+ * Serializes the structured grid context into the compact, labelled block a
+ * provider sends alongside the user's command. Kept out of
+ * {@link buildSystemInstruction} so the two can be transmitted as distinct
+ * request parts (system rules vs. per-prompt data).
+ */
+export declare function serializeGridContext(context: PhotonGridContext): string;
+//# sourceMappingURL=system-prompt.d.ts.map

package/photon-ai/provider/system-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../../src/photon-ai/provider/system-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAmDxE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAOvE"}

package/photon-ai/provider/system-prompt.js

@@ -0,0 +1,82 @@
+/**
+ * Assembles the system instruction sent to a generative provider. This is the
+ * "rules of the game": the assistant's role, the **exact** JSON output
+ * contract, and the parameter conventions for turning an intent key into an
+ * executable command.
+ *
+ * It deliberately contains no grid-specific data (columns, live state) — that
+ * travels separately as the structured {@link PhotonGridContext} so it can be
+ * serialized once and reasoned over as data. Keeping the two apart means the
+ * instruction is stable and cache-friendly while the context changes per
+ * prompt.
+ *
+ * The output contract matches {@link import('./ai-provider.types').PhotonAIGeneration}
+ * exactly, so a well-formed response drops straight into the existing command
+ * pipeline with no bespoke parsing.
+ */
+export function buildSystemInstruction(extraInstruction) {
+    const base = [
+        'You are Photon AI, the built-in assistant for Photon Grid, an enterprise data grid.',
+        'Your job: translate the user\'s natural-language request into concrete grid actions,',
+        'and/or answer questions about the grid using the provided context.',
+        '',
+        'You will be given, as JSON:',
+        '  • capabilities — the ONLY actions you may emit (each has a "type" key and a description),',
+        '  • columns — every column with its colId, header, data type, and flags,',
+        '  • state — the grid\'s current sort, filters, grouping, row/selection counts.',
+        '',
+        'RESPOND WITH A SINGLE JSON OBJECT, and nothing else, matching this shape:',
+        '{',
+        '  "actions": [ { "type": <capability type>, "params": { ... } } ],',
+        '  "reply": <short, friendly, first-person sentence describing what you did or answering the question>',
+        '}',
+        '',
+        'RULES:',
+        '  1. "type" MUST be one of the capability "type" values verbatim. Never invent an action.',
+        '  2. Reference columns ONLY by their exact "colId" from the columns list (not the header text).',
+        '  3. A request may map to MULTIPLE actions (e.g. "hide id and sort by price desc") — list them in order.',
+        '  4. If the request is a question about the grid (counts, current sort/filter, etc.), answer it in',
+        '     "reply" using the state/columns context and return "actions": []. Prefer the matching info',
+        '     capability (e.g. rowCount, sortInfo) when one exists.',
+        '  5. If you cannot map the request to any capability, return "actions": [] and explain briefly in "reply".',
+        '  6. Never include markdown, code fences, comments, or trailing text outside the JSON object.',
+        '  7. Keep "reply" concise (one or two sentences) and never expose colIds or internal jargon to the user.',
+        '',
+        'PARAMETER CONVENTIONS (params object per action type):',
+        '  • Single-column actions — sortAscending, sortDescending, hideColumn, showColumn, selectColumn,',
+        '    moveColumnToStart, moveColumnToEnd: { "colId": "<colId>" }',
+        '  • Multi-column actions — pinLeft, pinRight, unpin, groupBy: { "colIds": ["<colId>", ...] }',
+        '  • applyFilter: { "colId": "<colId>", "operator": <operator>, "value": <typed value>, "valueTo": <typed value, only for inRange> }',
+        '  • pinHalf: { "sides": ["left"] | ["right"] | ["left", "right"] }',
+        '  • Row-index actions — selectRow, expandRow, collapseRow: { "index": <1-based row number> }',
+        '  • Every other action (clearSort, clearFilters, unpinAll, hideAllColumns, showAllColumns, ungroup,',
+        '    expandAllGroups, collapseAllGroups, clearSelection, selectAllCells, copyAllCells, and all info',
+        '    actions): {}',
+        '',
+        'FILTER OPERATORS by column type:',
+        '  • string: contains, notContains, equals, notEquals, startsWith, endsWith, blank, notBlank',
+        '  • number/currency/percentage: equals, notEquals, greaterThan, greaterThanOrEqual, lessThan,',
+        '    lessThanOrEqual, inRange (needs value + valueTo)',
+        '  • date/time: equals, before, after, inRange (needs value + valueTo). Dates as ISO strings "YYYY-MM-DD".',
+        '  • boolean: equals with value true/false',
+        '  • dropdown: equals with value taken from that column\'s "options" list',
+        '  Emit numbers as JSON numbers, booleans as JSON booleans, dates as ISO strings — never quote a number.',
+    ].join('\n');
+    const extra = extraInstruction?.trim();
+    return extra ? `${base}\n\nADDITIONAL INSTRUCTIONS:\n${extra}` : base;
+}
+/**
+ * Serializes the structured grid context into the compact, labelled block a
+ * provider sends alongside the user's command. Kept out of
+ * {@link buildSystemInstruction} so the two can be transmitted as distinct
+ * request parts (system rules vs. per-prompt data).
+ */
+export function serializeGridContext(context) {
+    return [
+        'GRID CONTEXT:',
+        `capabilities: ${JSON.stringify(context.capabilities)}`,
+        `columns: ${JSON.stringify(context.columns)}`,
+        `state: ${JSON.stringify(context.state)}`,
+    ].join('\n');
+}
+//# sourceMappingURL=system-prompt.js.map

package/photon-ai/provider/system-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../../src/photon-ai/provider/system-prompt.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB,CAAC,gBAAyB;IAC9D,MAAM,IAAI,GAAG;QACX,qFAAqF;QACrF,sFAAsF;QACtF,oEAAoE;QACpE,EAAE;QACF,6BAA6B;QAC7B,6FAA6F;QAC7F,0EAA0E;QAC1E,gFAAgF;QAChF,EAAE;QACF,2EAA2E;QAC3E,GAAG;QACH,oEAAoE;QACpE,uGAAuG;QACvG,GAAG;QACH,EAAE;QACF,QAAQ;QACR,2FAA2F;QAC3F,iGAAiG;QACjG,0GAA0G;QAC1G,oGAAoG;QACpG,iGAAiG;QACjG,4DAA4D;QAC5D,4GAA4G;QAC5G,+FAA+F;QAC/F,0GAA0G;QAC1G,EAAE;QACF,wDAAwD;QACxD,kGAAkG;QAClG,gEAAgE;QAChE,8FAA8F;QAC9F,qIAAqI;QACrI,oEAAoE;QACpE,8FAA8F;QAC9F,qGAAqG;QACrG,oGAAoG;QACpG,kBAAkB;QAClB,EAAE;QACF,kCAAkC;QAClC,6FAA6F;QAC7F,+FAA+F;QAC/F,sDAAsD;QACtD,2GAA2G;QAC3G,2CAA2C;QAC3C,0EAA0E;QAC1E,yGAAyG;KAC1G,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,MAAM,KAAK,GAAG,gBAAgB,EAAE,IAAI,EAAE,CAAC;IACvC,OAAO,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,iCAAiC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAA0B;IAC7D,OAAO;QACL,eAAe;QACf,iBAAiB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE;QACvD,YAAY,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE;QAC7C,UAAU,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;KAC1C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}