@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/tools/ai-duplicate-resource-tool.js

@@ -0,0 +1,164 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { DUPLICABLE_HOST_RESOURCE_KINDS, DUPLICATE_NAME_MAX, isDuplicableHostResourceKind } from "@aglyn/aglyn/app-utils/duplicate-resource";
+import { hostRoleCanWrite } from "@aglyn/aglyn/app-utils/organizations";
+import { orgPermissionLabel } from "@aglyn/aglyn/app-utils/org-permissions";
+import { duplicateResource } from "@aglyn/tenant-data-admin/server/duplicate-resource";
+import { getOrgForUser, memberHasPermissionOnHost } from "@aglyn/tenant-data-admin/server/organizations";
+/**
+ * The `duplicate_resource` tool (AGL-2936, AGL-2984): a model that would
+ * rebuild something the site already has copies it instead, through core's
+ * `duplicateResource` — the same copy the row menus and the console door
+ * make, with the same uniqueness rules, the same band arithmetic and the same
+ * activity rows.
+ *
+ * It spends no tokens of its own, so it calls no provider: it runs inside a
+ * door or a job step that has already climbed `aiGateLadder`, and takes that
+ * ladder's context as its proof — the caller is signed in and verified, the
+ * release flag, entitlement and lockdown rungs admitted the request, and the
+ * workspace's band and caps admitted a reservation. On top of that it asks
+ * what a copy needs whichever door called it: `ai.generate`, because a copy
+ * is a generation's output, and a host role that may write the site, because
+ * the copy lands there.
+ *
+ * DRAFTS ONLY, by construction of the copy: a screen copy has no route, a
+ * workflow copy no trigger, and nothing places a component, layout or form
+ * copy until a person does.
+ */ export const AI_DUPLICATE_RESOURCE_TOOL_NAME = 'duplicate_resource';
+/** The structured-output tool a generation offers the model. */ export const AI_DUPLICATE_RESOURCE_TOOL = {
+    name: AI_DUPLICATE_RESOURCE_TOOL_NAME,
+    description: 'Copy a resource this site already has — a screen, an email design, a component, a layout, ' + 'a template, a form or a workflow — as a new draft to build from, instead of creating it again. ' + 'The copy is unpublished: it has no address, runs nothing and is placed nowhere until a person does.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            kind: {
+                type: 'string',
+                enum: [
+                    ...DUPLICABLE_HOST_RESOURCE_KINDS
+                ],
+                description: 'The kind of resource to copy.'
+            },
+            sourceId: {
+                type: 'string',
+                description: 'The id of the resource to copy, as the site inventory lists it.'
+            },
+            name: {
+                type: [
+                    'string',
+                    'null'
+                ],
+                description: `The copy's name, at most ${DUPLICATE_NAME_MAX} characters, or null for "Copy of" the source's name.`
+            }
+        },
+        required: [
+            'kind',
+            'sourceId',
+            'name'
+        ],
+        additionalProperties: false
+    },
+    strict: true
+};
+/** Reads a tool call's input; `null` when it is not one this tool accepts. */ export function parseAiDuplicateResourceInput(input) {
+    const kind = input['kind'];
+    const sourceId = typeof input['sourceId'] === 'string' ? input['sourceId'].trim() : '';
+    const name = input['name'];
+    if (!isDuplicableHostResourceKind(kind)) return null;
+    if (!sourceId || sourceId.length > 64 || sourceId.includes('/')) return null;
+    if (name !== null && typeof name !== 'string') return null;
+    const trimmed = typeof name === 'string' ? name.trim().slice(0, DUPLICATE_NAME_MAX) : '';
+    return {
+        kind,
+        sourceId,
+        name: trimmed || null
+    };
+}
+/**
+ * Makes the copy on `hostId` for the person the gate admitted. Refusals are
+ * outcomes, never throws: a model's call that names a missing source or a
+ * full band is an answer to relay, not a fault.
+ */ export async function runAiDuplicateResourceTool(context, input) {
+    var _context_hostId, _host_get;
+    var _gate_reservation;
+    const { gate } = context;
+    const hostId = String((_context_hostId = context.hostId) != null ? _context_hostId : '').trim();
+    const parsed = parseAiDuplicateResourceInput(input);
+    if (!parsed) return {
+        ok: false,
+        status: 400,
+        error: 'That is not a resource this site can copy'
+    };
+    if (!((_gate_reservation = gate.reservation) == null ? void 0 : _gate_reservation.allowed)) {
+        return {
+            ok: false,
+            status: 429,
+            error: 'This workspace cannot run AI requests right now'
+        };
+    }
+    if (!hostId) return {
+        ok: false,
+        status: 400,
+        error: 'Name the site to copy on'
+    };
+    const host = await gate.firestore.collection('hosts').doc(hostId).get();
+    // A site of another workspace is a site this request cannot see.
+    if (!host.exists || host.get('orgId') !== gate.orgId) {
+        return {
+            ok: false,
+            status: 404,
+            error: 'Unknown site'
+        };
+    }
+    if (!gate.staff) {
+        const membership = await getOrgForUser(gate.uid, gate.orgId);
+        const permitted = (membership == null ? void 0 : membership.orgId) === gate.orgId && await memberHasPermissionOnHost(gate.orgId, hostId, membership.member, 'ai.generate');
+        if (!permitted) {
+            return {
+                ok: false,
+                status: 403,
+                error: `Your role does not include "${orgPermissionLabel('ai.generate')}" — ask an organization admin`
+            };
+        }
+    }
+    const memberRole = ((_host_get = host.get('memberRoles')) != null ? _host_get : {})[gate.uid];
+    if (!hostRoleCanWrite(memberRole)) {
+        return {
+            ok: false,
+            status: 403,
+            error: 'Editing requires the editor role'
+        };
+    }
+    const result = await duplicateResource(parsed.kind, {
+        orgId: gate.orgId,
+        hostId,
+        sourceId: parsed.sourceId,
+        name: parsed.name,
+        uid: gate.uid,
+        email: gate.decoded.email ? String(gate.decoded.email) : null,
+        org: gate.org,
+        attemptKey: null
+    });
+    if (result.ok === false) return result;
+    return {
+        ok: true,
+        kind: parsed.kind,
+        id: result.id,
+        versionId: result.versionId,
+        name: result.name
+    };
+}
+
+//# sourceMappingURL=ai-duplicate-resource-tool.js.map

package/src/lib/tools/ai-duplicate-resource-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/tools/ai-duplicate-resource-tool.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  DUPLICABLE_HOST_RESOURCE_KINDS,\n  DUPLICATE_NAME_MAX,\n  isDuplicableHostResourceKind,\n  type DuplicableHostResourceKind,\n} from '@aglyn/aglyn/app-utils/duplicate-resource'\nimport { hostRoleCanWrite } from '@aglyn/aglyn/app-utils/organizations'\nimport { orgPermissionLabel } from '@aglyn/aglyn/app-utils/org-permissions'\nimport { duplicateResource } from '@aglyn/tenant-data-admin/server/duplicate-resource'\nimport {\n  getOrgForUser,\n  memberHasPermissionOnHost,\n} from '@aglyn/tenant-data-admin/server/organizations'\nimport type { AiTool } from '../providers/contract'\nimport type { AiGateContext } from '../runtime/ai-gate'\n\n/**\n * The `duplicate_resource` tool (AGL-2936, AGL-2984): a model that would\n * rebuild something the site already has copies it instead, through core's\n * `duplicateResource` — the same copy the row menus and the console door\n * make, with the same uniqueness rules, the same band arithmetic and the same\n * activity rows.\n *\n * It spends no tokens of its own, so it calls no provider: it runs inside a\n * door or a job step that has already climbed `aiGateLadder`, and takes that\n * ladder's context as its proof — the caller is signed in and verified, the\n * release flag, entitlement and lockdown rungs admitted the request, and the\n * workspace's band and caps admitted a reservation. On top of that it asks\n * what a copy needs whichever door called it: `ai.generate`, because a copy\n * is a generation's output, and a host role that may write the site, because\n * the copy lands there.\n *\n * DRAFTS ONLY, by construction of the copy: a screen copy has no route, a\n * workflow copy no trigger, and nothing places a component, layout or form\n * copy until a person does.\n */\n\nexport const AI_DUPLICATE_RESOURCE_TOOL_NAME = 'duplicate_resource'\n\n/** The structured-output tool a generation offers the model. */\nexport const AI_DUPLICATE_RESOURCE_TOOL: AiTool = {\n  name: AI_DUPLICATE_RESOURCE_TOOL_NAME,\n  description:\n    'Copy a resource this site already has — a screen, an email design, a component, a layout, ' +\n    'a template, a form or a workflow — as a new draft to build from, instead of creating it again. ' +\n    'The copy is unpublished: it has no address, runs nothing and is placed nowhere until a person does.',\n  inputSchema: {\n    type: 'object',\n    properties: {\n      kind: {\n        type: 'string',\n        enum: [...DUPLICABLE_HOST_RESOURCE_KINDS],\n        description: 'The kind of resource to copy.',\n      },\n      sourceId: {\n        type: 'string',\n        description: 'The id of the resource to copy, as the site inventory lists it.',\n      },\n      name: {\n        type: ['string', 'null'],\n        description: `The copy's name, at most ${DUPLICATE_NAME_MAX} characters, or null for \"Copy of\" the source's name.`,\n      },\n    },\n    required: ['kind', 'sourceId', 'name'],\n    additionalProperties: false,\n  },\n  strict: true,\n}\n\n/** A tool call's input, read. */\nexport type AiDuplicateResourceInput = {\n  kind: DuplicableHostResourceKind\n  sourceId: string\n  name: string | null\n}\n\n/** What the tool answers: the copy, or a refusal the caller can relay. */\nexport type AiDuplicateResourceOutcome =\n  | { ok: true; kind: DuplicableHostResourceKind; id: string; versionId: string | null; name: string }\n  | { ok: false; status: number; error: string }\n\n/** Reads a tool call's input; `null` when it is not one this tool accepts. */\nexport function parseAiDuplicateResourceInput(\n  input: Record<string, unknown>,\n): AiDuplicateResourceInput | null {\n  const kind = input['kind']\n  const sourceId = typeof input['sourceId'] === 'string' ? input['sourceId'].trim() : ''\n  const name = input['name']\n  if (!isDuplicableHostResourceKind(kind)) return null\n  if (!sourceId || sourceId.length > 64 || sourceId.includes('/')) return null\n  if (name !== null && typeof name !== 'string') return null\n  const trimmed = typeof name === 'string' ? name.trim().slice(0, DUPLICATE_NAME_MAX) : ''\n  return { kind, sourceId, name: trimmed || null }\n}\n\n/**\n * Makes the copy on `hostId` for the person the gate admitted. Refusals are\n * outcomes, never throws: a model's call that names a missing source or a\n * full band is an answer to relay, not a fault.\n */\nexport async function runAiDuplicateResourceTool(\n  context: { gate: AiGateContext; hostId: string },\n  input: Record<string, unknown>,\n): Promise<AiDuplicateResourceOutcome> {\n  const { gate } = context\n  const hostId = String(context.hostId ?? '').trim()\n  const parsed = parseAiDuplicateResourceInput(input)\n  if (!parsed) return { ok: false, status: 400, error: 'That is not a resource this site can copy' }\n  if (!gate.reservation?.allowed) {\n    return { ok: false, status: 429, error: 'This workspace cannot run AI requests right now' }\n  }\n  if (!hostId) return { ok: false, status: 400, error: 'Name the site to copy on' }\n\n  const host = await gate.firestore.collection('hosts').doc(hostId).get()\n  // A site of another workspace is a site this request cannot see.\n  if (!host.exists || host.get('orgId') !== gate.orgId) {\n    return { ok: false, status: 404, error: 'Unknown site' }\n  }\n  if (!gate.staff) {\n    const membership = await getOrgForUser(gate.uid, gate.orgId)\n    const permitted =\n      membership?.orgId === gate.orgId &&\n      (await memberHasPermissionOnHost(gate.orgId, hostId, membership.member, 'ai.generate'))\n    if (!permitted) {\n      return {\n        ok: false,\n        status: 403,\n        error: `Your role does not include \"${orgPermissionLabel('ai.generate')}\" — ask an organization admin`,\n      }\n    }\n  }\n  const memberRole = ((host.get('memberRoles') ?? {}) as Record<string, unknown>)[gate.uid]\n  if (!hostRoleCanWrite(memberRole)) {\n    return { ok: false, status: 403, error: 'Editing requires the editor role' }\n  }\n\n  const result = await duplicateResource(parsed.kind, {\n    orgId: gate.orgId,\n    hostId,\n    sourceId: parsed.sourceId,\n    name: parsed.name,\n    uid: gate.uid,\n    email: gate.decoded.email ? String(gate.decoded.email) : null,\n    org: gate.org as Record<string, unknown>,\n    attemptKey: null,\n  })\n  if (result.ok === false) return result\n  return {\n    ok: true,\n    kind: parsed.kind,\n    id: result.id,\n    versionId: result.versionId,\n    name: result.name,\n  }\n}\n"],"names":["DUPLICABLE_HOST_RESOURCE_KINDS","DUPLICATE_NAME_MAX","isDuplicableHostResourceKind","hostRoleCanWrite","orgPermissionLabel","duplicateResource","getOrgForUser","memberHasPermissionOnHost","AI_DUPLICATE_RESOURCE_TOOL_NAME","AI_DUPLICATE_RESOURCE_TOOL","name","description","inputSchema","type","properties","kind","enum","sourceId","required","additionalProperties","strict","parseAiDuplicateResourceInput","input","trim","length","includes","trimmed","slice","runAiDuplicateResourceTool","context","host","gate","hostId","String","parsed","ok","status","error","reservation","allowed","firestore","collection","doc","get","exists","orgId","staff","membership","uid","permitted","member","memberRole","result","email","decoded","org","attemptKey","id","versionId"],"mappings":"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"}

package/src/lib/tools/ai-experiment-tool.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type AiExperimentExplanationAnswer, type AiExperimentTarget, type AiExperimentVariantsProposal } from '../model/ai-experiment';
+import type { AiTool } from '../providers/contract';
+/**
+ * The two strict tools an `experiment` job answers through (AGL-2914).
+ *
+ * `propose_variants` writes copy for the thing under test and nothing else:
+ * no weights, no traffic split, no schedule, no winner — those are the A/B
+ * testing card's, and a model that could name them could start a test.
+ * `explain_result` writes the words for a verdict code already reached, and
+ * carries a `winner` field only so an answer that names one can be caught:
+ * `checkAiExperimentExplanation` decides what is kept, never this schema.
+ */
+export declare const AI_EXPERIMENT_VARIANTS_TOOL_NAME = "propose_variants";
+export declare const AI_EXPERIMENT_EXPLAIN_TOOL_NAME = "explain_result";
+export declare function aiExperimentVariantsTool(target: AiExperimentTarget): AiTool;
+export declare function aiExperimentExplainTool(): AiTool;
+/**
+ * A `propose_variants` call as the check reads it, or `null` when the call is
+ * not a proposal at all. Values keep the lengths the model wrote, so the
+ * check — not this reader — decides what is too long.
+ */
+export declare function parseAiExperimentVariants(input: unknown): AiExperimentVariantsProposal | null;
+/** An `explain_result` call as the check reads it, or `null` when it is not one. */
+export declare function parseAiExperimentExplanation(input: unknown): AiExperimentExplanationAnswer | null;

package/src/lib/tools/ai-experiment-tool.js

@@ -0,0 +1,155 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { AI_EXPERIMENT_BODY_MAX_CHARS, AI_EXPERIMENT_HEADLINE_MAX_CHARS, AI_EXPERIMENT_LINE_MAX_CHARS, AI_EXPERIMENT_MAX_POINTS, AI_EXPERIMENT_MAX_VARIANTS, AI_EXPERIMENT_MIN_VARIANTS, AI_EXPERIMENT_NAME_MAX_CHARS, AI_EXPERIMENT_NEXT_MAX_CHARS, AI_EXPERIMENT_POINT_MAX_CHARS, AI_EXPERIMENT_RATIONALE_MAX_CHARS, aiExperimentVariantFields } from "../model/ai-experiment.js";
+/**
+ * The two strict tools an `experiment` job answers through (AGL-2914).
+ *
+ * `propose_variants` writes copy for the thing under test and nothing else:
+ * no weights, no traffic split, no schedule, no winner — those are the A/B
+ * testing card's, and a model that could name them could start a test.
+ * `explain_result` writes the words for a verdict code already reached, and
+ * carries a `winner` field only so an answer that names one can be caught:
+ * `checkAiExperimentExplanation` decides what is kept, never this schema.
+ */ export const AI_EXPERIMENT_VARIANTS_TOOL_NAME = 'propose_variants';
+export const AI_EXPERIMENT_EXPLAIN_TOOL_NAME = 'explain_result';
+/** The copy fields a target's variants fill, as the tool describes them. */ const FIELD_HELP = {
+    headline: `The variant's main line of copy; at most ${AI_EXPERIMENT_LINE_MAX_CHARS} characters. Empty string when this variant does not change it.`,
+    body: `The variant's supporting copy; at most ${AI_EXPERIMENT_BODY_MAX_CHARS} characters. Empty string when this variant does not change it.`,
+    subject: `The variant's subject line; at most ${AI_EXPERIMENT_LINE_MAX_CHARS} characters. Empty string when this variant does not change it.`,
+    preheader: `The variant's preheader, the line shown beside the subject; at most ${AI_EXPERIMENT_LINE_MAX_CHARS} characters. Empty string when this variant does not change it.`
+};
+export function aiExperimentVariantsTool(target) {
+    const fields = aiExperimentVariantFields(target).filter((field)=>field !== 'name' && field !== 'rationale');
+    const properties = {
+        name: {
+            type: 'string',
+            description: `What to call this variant, in a few words; at most ${AI_EXPERIMENT_NAME_MAX_CHARS} characters.`
+        }
+    };
+    for (const field of fields){
+        properties[field] = {
+            type: 'string',
+            description: FIELD_HELP[field]
+        };
+    }
+    properties['rationale'] = {
+        type: 'string',
+        description: `One sentence: what this variant changes and what that is testing; at most ${AI_EXPERIMENT_RATIONALE_MAX_CHARS} characters.`
+    };
+    return {
+        name: AI_EXPERIMENT_VARIANTS_TOOL_NAME,
+        description: `Propose between ${AI_EXPERIMENT_MIN_VARIANTS} and ${AI_EXPERIMENT_MAX_VARIANTS} variants for the ` + 'A/B test, the first of them the copy already there. Every field is required.',
+        strict: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                goal: {
+                    type: 'string',
+                    description: `What these variants are trying to move, in one short phrase; at most ${AI_EXPERIMENT_RATIONALE_MAX_CHARS} characters.`
+                },
+                variants: {
+                    type: 'array',
+                    description: `The first is the copy under test as it stands; at most ${AI_EXPERIMENT_MAX_VARIANTS} in all. Each varies one idea, and no two say the same thing.`,
+                    items: {
+                        type: 'object',
+                        properties,
+                        required: [
+                            'name',
+                            ...fields,
+                            'rationale'
+                        ],
+                        additionalProperties: false
+                    }
+                }
+            },
+            required: [
+                'goal',
+                'variants'
+            ],
+            additionalProperties: false
+        }
+    };
+}
+export function aiExperimentExplainTool() {
+    return {
+        name: AI_EXPERIMENT_EXPLAIN_TOOL_NAME,
+        description: 'Explain what this result means, in the words of the verdict the request states. ' + 'Every field is required.',
+        strict: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                headline: {
+                    type: 'string',
+                    description: `One plain sentence saying what happened; at most ${AI_EXPERIMENT_HEADLINE_MAX_CHARS} characters.`
+                },
+                points: {
+                    type: 'array',
+                    description: `What the figures show, most useful first; at most ${AI_EXPERIMENT_MAX_POINTS}. Empty when the headline says it all.`,
+                    items: {
+                        type: 'string',
+                        description: `One plain sentence; at most ${AI_EXPERIMENT_POINT_MAX_CHARS} characters.`
+                    }
+                },
+                winner: {
+                    type: 'string',
+                    description: 'The variant the request states won, exactly as the figures name it. Empty string where the request states there is no winner yet.'
+                },
+                next: {
+                    type: 'string',
+                    description: `What to do next; at most ${AI_EXPERIMENT_NEXT_MAX_CHARS} characters. Empty string where the request states there is no winner yet.`
+                }
+            },
+            required: [
+                'headline',
+                'points',
+                'winner',
+                'next'
+            ],
+            additionalProperties: false
+        }
+    };
+}
+const isRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+const str = (value)=>typeof value === 'string' ? value : '';
+/**
+ * A `propose_variants` call as the check reads it, or `null` when the call is
+ * not a proposal at all. Values keep the lengths the model wrote, so the
+ * check — not this reader — decides what is too long.
+ */ export function parseAiExperimentVariants(input) {
+    if (!isRecord(input) || !Array.isArray(input['variants'])) return null;
+    return {
+        goal: str(input['goal']),
+        variants: input['variants'].filter(isRecord).map((raw)=>({
+                name: str(raw['name']),
+                headline: str(raw['headline']),
+                body: str(raw['body']),
+                subject: str(raw['subject']),
+                preheader: str(raw['preheader']),
+                rationale: str(raw['rationale'])
+            }))
+    };
+}
+/** An `explain_result` call as the check reads it, or `null` when it is not one. */ export function parseAiExperimentExplanation(input) {
+    if (!isRecord(input) || typeof input['headline'] !== 'string') return null;
+    return {
+        headline: input['headline'],
+        points: (Array.isArray(input['points']) ? input['points'] : []).map(str),
+        winner: str(input['winner']),
+        next: str(input['next'])
+    };
+}
+
+//# sourceMappingURL=ai-experiment-tool.js.map

package/src/lib/tools/ai-experiment-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/tools/ai-experiment-tool.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  AI_EXPERIMENT_BODY_MAX_CHARS,\n  AI_EXPERIMENT_HEADLINE_MAX_CHARS,\n  AI_EXPERIMENT_LINE_MAX_CHARS,\n  AI_EXPERIMENT_MAX_POINTS,\n  AI_EXPERIMENT_MAX_VARIANTS,\n  AI_EXPERIMENT_MIN_VARIANTS,\n  AI_EXPERIMENT_NAME_MAX_CHARS,\n  AI_EXPERIMENT_NEXT_MAX_CHARS,\n  AI_EXPERIMENT_POINT_MAX_CHARS,\n  AI_EXPERIMENT_RATIONALE_MAX_CHARS,\n  aiExperimentVariantFields,\n  type AiExperimentExplanationAnswer,\n  type AiExperimentTarget,\n  type AiExperimentVariantsProposal,\n} from '../model/ai-experiment'\nimport type { AiTool } from '../providers/contract'\n\n/**\n * The two strict tools an `experiment` job answers through (AGL-2914).\n *\n * `propose_variants` writes copy for the thing under test and nothing else:\n * no weights, no traffic split, no schedule, no winner — those are the A/B\n * testing card's, and a model that could name them could start a test.\n * `explain_result` writes the words for a verdict code already reached, and\n * carries a `winner` field only so an answer that names one can be caught:\n * `checkAiExperimentExplanation` decides what is kept, never this schema.\n */\n\nexport const AI_EXPERIMENT_VARIANTS_TOOL_NAME = 'propose_variants'\nexport const AI_EXPERIMENT_EXPLAIN_TOOL_NAME = 'explain_result'\n\n/** The copy fields a target's variants fill, as the tool describes them. */\nconst FIELD_HELP: Record<\n  'headline' | 'body' | 'subject' | 'preheader',\n  string\n> = {\n  headline: `The variant's main line of copy; at most ${AI_EXPERIMENT_LINE_MAX_CHARS} characters. Empty string when this variant does not change it.`,\n  body: `The variant's supporting copy; at most ${AI_EXPERIMENT_BODY_MAX_CHARS} characters. Empty string when this variant does not change it.`,\n  subject: `The variant's subject line; at most ${AI_EXPERIMENT_LINE_MAX_CHARS} characters. Empty string when this variant does not change it.`,\n  preheader: `The variant's preheader, the line shown beside the subject; at most ${AI_EXPERIMENT_LINE_MAX_CHARS} characters. Empty string when this variant does not change it.`,\n}\n\nexport function aiExperimentVariantsTool(target: AiExperimentTarget): AiTool {\n  const fields = aiExperimentVariantFields(target).filter(\n    (field): field is 'headline' | 'body' | 'subject' | 'preheader' =>\n      field !== 'name' && field !== 'rationale',\n  )\n  const properties: Record<string, unknown> = {\n    name: {\n      type: 'string',\n      description: `What to call this variant, in a few words; at most ${AI_EXPERIMENT_NAME_MAX_CHARS} characters.`,\n    },\n  }\n  for (const field of fields) {\n    properties[field] = { type: 'string', description: FIELD_HELP[field] }\n  }\n  properties['rationale'] = {\n    type: 'string',\n    description: `One sentence: what this variant changes and what that is testing; at most ${AI_EXPERIMENT_RATIONALE_MAX_CHARS} characters.`,\n  }\n  return {\n    name: AI_EXPERIMENT_VARIANTS_TOOL_NAME,\n    description:\n      `Propose between ${AI_EXPERIMENT_MIN_VARIANTS} and ${AI_EXPERIMENT_MAX_VARIANTS} variants for the ` +\n      'A/B test, the first of them the copy already there. Every field is required.',\n    strict: true,\n    inputSchema: {\n      type: 'object',\n      properties: {\n        goal: {\n          type: 'string',\n          description: `What these variants are trying to move, in one short phrase; at most ${AI_EXPERIMENT_RATIONALE_MAX_CHARS} characters.`,\n        },\n        variants: {\n          type: 'array',\n          description: `The first is the copy under test as it stands; at most ${AI_EXPERIMENT_MAX_VARIANTS} in all. Each varies one idea, and no two say the same thing.`,\n          items: {\n            type: 'object',\n            properties,\n            required: ['name', ...fields, 'rationale'],\n            additionalProperties: false,\n          },\n        },\n      },\n      required: ['goal', 'variants'],\n      additionalProperties: false,\n    },\n  }\n}\n\nexport function aiExperimentExplainTool(): AiTool {\n  return {\n    name: AI_EXPERIMENT_EXPLAIN_TOOL_NAME,\n    description:\n      'Explain what this result means, in the words of the verdict the request states. ' +\n      'Every field is required.',\n    strict: true,\n    inputSchema: {\n      type: 'object',\n      properties: {\n        headline: {\n          type: 'string',\n          description: `One plain sentence saying what happened; at most ${AI_EXPERIMENT_HEADLINE_MAX_CHARS} characters.`,\n        },\n        points: {\n          type: 'array',\n          description: `What the figures show, most useful first; at most ${AI_EXPERIMENT_MAX_POINTS}. Empty when the headline says it all.`,\n          items: {\n            type: 'string',\n            description: `One plain sentence; at most ${AI_EXPERIMENT_POINT_MAX_CHARS} characters.`,\n          },\n        },\n        winner: {\n          type: 'string',\n          description:\n            'The variant the request states won, exactly as the figures name it. Empty string where the request states there is no winner yet.',\n        },\n        next: {\n          type: 'string',\n          description: `What to do next; at most ${AI_EXPERIMENT_NEXT_MAX_CHARS} characters. Empty string where the request states there is no winner yet.`,\n        },\n      },\n      required: ['headline', 'points', 'winner', 'next'],\n      additionalProperties: false,\n    },\n  }\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\nconst str = (value: unknown): string => (typeof value === 'string' ? value : '')\n\n/**\n * A `propose_variants` call as the check reads it, or `null` when the call is\n * not a proposal at all. Values keep the lengths the model wrote, so the\n * check — not this reader — decides what is too long.\n */\nexport function parseAiExperimentVariants(\n  input: unknown,\n): AiExperimentVariantsProposal | null {\n  if (!isRecord(input) || !Array.isArray(input['variants'])) return null\n  return {\n    goal: str(input['goal']),\n    variants: input['variants'].filter(isRecord).map((raw) => ({\n      name: str(raw['name']),\n      headline: str(raw['headline']),\n      body: str(raw['body']),\n      subject: str(raw['subject']),\n      preheader: str(raw['preheader']),\n      rationale: str(raw['rationale']),\n    })),\n  }\n}\n\n/** An `explain_result` call as the check reads it, or `null` when it is not one. */\nexport function parseAiExperimentExplanation(\n  input: unknown,\n): AiExperimentExplanationAnswer | null {\n  if (!isRecord(input) || typeof input['headline'] !== 'string') return null\n  return {\n    headline: input['headline'],\n    points: (Array.isArray(input['points']) ? input['points'] : []).map(str),\n    winner: str(input['winner']),\n    next: str(input['next']),\n  }\n}\n"],"names":["AI_EXPERIMENT_BODY_MAX_CHARS","AI_EXPERIMENT_HEADLINE_MAX_CHARS","AI_EXPERIMENT_LINE_MAX_CHARS","AI_EXPERIMENT_MAX_POINTS","AI_EXPERIMENT_MAX_VARIANTS","AI_EXPERIMENT_MIN_VARIANTS","AI_EXPERIMENT_NAME_MAX_CHARS","AI_EXPERIMENT_NEXT_MAX_CHARS","AI_EXPERIMENT_POINT_MAX_CHARS","AI_EXPERIMENT_RATIONALE_MAX_CHARS","aiExperimentVariantFields","AI_EXPERIMENT_VARIANTS_TOOL_NAME","AI_EXPERIMENT_EXPLAIN_TOOL_NAME","FIELD_HELP","headline","body","subject","preheader","aiExperimentVariantsTool","target","fields","filter","field","properties","name","type","description","strict","inputSchema","goal","variants","items","required","additionalProperties","aiExperimentExplainTool","points","winner","next","isRecord","value","Array","isArray","str","parseAiExperimentVariants","input","map","raw","rationale","parseAiExperimentExplanation"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,4BAA4B,EAC5BC,gCAAgC,EAChCC,4BAA4B,EAC5BC,wBAAwB,EACxBC,0BAA0B,EAC1BC,0BAA0B,EAC1BC,4BAA4B,EAC5BC,4BAA4B,EAC5BC,6BAA6B,EAC7BC,iCAAiC,EACjCC,yBAAyB,QAIpB,4BAAwB;AAG/B;;;;;;;;;CASC,GAED,OAAO,MAAMC,mCAAmC,mBAAkB;AAClE,OAAO,MAAMC,kCAAkC,iBAAgB;AAE/D,0EAA0E,GAC1E,MAAMC,aAGF;IACFC,UAAU,CAAC,yCAAyC,EAAEZ,6BAA6B,+DAA+D,CAAC;IACnJa,MAAM,CAAC,uCAAuC,EAAEf,6BAA6B,+DAA+D,CAAC;IAC7IgB,SAAS,CAAC,oCAAoC,EAAEd,6BAA6B,+DAA+D,CAAC;IAC7Ie,WAAW,CAAC,oEAAoE,EAAEf,6BAA6B,+DAA+D,CAAC;AACjL;AAEA,OAAO,SAASgB,yBAAyBC,MAA0B;IACjE,MAAMC,SAASV,0BAA0BS,QAAQE,MAAM,CACrD,CAACC,QACCA,UAAU,UAAUA,UAAU;IAElC,MAAMC,aAAsC;QAC1CC,MAAM;YACJC,MAAM;YACNC,aAAa,CAAC,mDAAmD,EAAEpB,6BAA6B,YAAY,CAAC;QAC/G;IACF;IACA,KAAK,MAAMgB,SAASF,OAAQ;QAC1BG,UAAU,CAACD,MAAM,GAAG;YAAEG,MAAM;YAAUC,aAAab,UAAU,CAACS,MAAM;QAAC;IACvE;IACAC,UAAU,CAAC,YAAY,GAAG;QACxBE,MAAM;QACNC,aAAa,CAAC,0EAA0E,EAAEjB,kCAAkC,YAAY,CAAC;IAC3I;IACA,OAAO;QACLe,MAAMb;QACNe,aACE,CAAC,gBAAgB,EAAErB,2BAA2B,KAAK,EAAED,2BAA2B,kBAAkB,CAAC,GACnG;QACFuB,QAAQ;QACRC,aAAa;YACXH,MAAM;YACNF,YAAY;gBACVM,MAAM;oBACJJ,MAAM;oBACNC,aAAa,CAAC,qEAAqE,EAAEjB,kCAAkC,YAAY,CAAC;gBACtI;gBACAqB,UAAU;oBACRL,MAAM;oBACNC,aAAa,CAAC,uDAAuD,EAAEtB,2BAA2B,6DAA6D,CAAC;oBAChK2B,OAAO;wBACLN,MAAM;wBACNF;wBACAS,UAAU;4BAAC;+BAAWZ;4BAAQ;yBAAY;wBAC1Ca,sBAAsB;oBACxB;gBACF;YACF;YACAD,UAAU;gBAAC;gBAAQ;aAAW;YAC9BC,sBAAsB;QACxB;IACF;AACF;AAEA,OAAO,SAASC;IACd,OAAO;QACLV,MAAMZ;QACNc,aACE,qFACA;QACFC,QAAQ;QACRC,aAAa;YACXH,MAAM;YACNF,YAAY;gBACVT,UAAU;oBACRW,MAAM;oBACNC,aAAa,CAAC,iDAAiD,EAAEzB,iCAAiC,YAAY,CAAC;gBACjH;gBACAkC,QAAQ;oBACNV,MAAM;oBACNC,aAAa,CAAC,kDAAkD,EAAEvB,yBAAyB,sCAAsC,CAAC;oBAClI4B,OAAO;wBACLN,MAAM;wBACNC,aAAa,CAAC,4BAA4B,EAAElB,8BAA8B,YAAY,CAAC;oBACzF;gBACF;gBACA4B,QAAQ;oBACNX,MAAM;oBACNC,aACE;gBACJ;gBACAW,MAAM;oBACJZ,MAAM;oBACNC,aAAa,CAAC,yBAAyB,EAAEnB,6BAA6B,0EAA0E,CAAC;gBACnJ;YACF;YACAyB,UAAU;gBAAC;gBAAY;gBAAU;gBAAU;aAAO;YAClDC,sBAAsB;QACxB;IACF;AACF;AAEA,MAAMK,WAAW,CAACC,QAChB,OAAOA,UAAU,YAAYA,UAAU,QAAQ,CAACC,MAAMC,OAAO,CAACF;AAEhE,MAAMG,MAAM,CAACH,QAA4B,OAAOA,UAAU,WAAWA,QAAQ;AAE7E;;;;CAIC,GACD,OAAO,SAASI,0BACdC,KAAc;IAEd,IAAI,CAACN,SAASM,UAAU,CAACJ,MAAMC,OAAO,CAACG,KAAK,CAAC,WAAW,GAAG,OAAO;IAClE,OAAO;QACLf,MAAMa,IAAIE,KAAK,CAAC,OAAO;QACvBd,UAAUc,KAAK,CAAC,WAAW,CAACvB,MAAM,CAACiB,UAAUO,GAAG,CAAC,CAACC,MAAS,CAAA;gBACzDtB,MAAMkB,IAAII,GAAG,CAAC,OAAO;gBACrBhC,UAAU4B,IAAII,GAAG,CAAC,WAAW;gBAC7B/B,MAAM2B,IAAII,GAAG,CAAC,OAAO;gBACrB9B,SAAS0B,IAAII,GAAG,CAAC,UAAU;gBAC3B7B,WAAWyB,IAAII,GAAG,CAAC,YAAY;gBAC/BC,WAAWL,IAAII,GAAG,CAAC,YAAY;YACjC,CAAA;IACF;AACF;AAEA,kFAAkF,GAClF,OAAO,SAASE,6BACdJ,KAAc;IAEd,IAAI,CAACN,SAASM,UAAU,OAAOA,KAAK,CAAC,WAAW,KAAK,UAAU,OAAO;IACtE,OAAO;QACL9B,UAAU8B,KAAK,CAAC,WAAW;QAC3BT,QAAQ,AAACK,CAAAA,MAAMC,OAAO,CAACG,KAAK,CAAC,SAAS,IAAIA,KAAK,CAAC,SAAS,GAAG,EAAE,AAAD,EAAGC,GAAG,CAACH;QACpEN,QAAQM,IAAIE,KAAK,CAAC,SAAS;QAC3BP,MAAMK,IAAIE,KAAK,CAAC,OAAO;IACzB;AACF"}

package/src/lib/tools/ai-insight-tool.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type AiInsightAnswer } from '../model/ai-insight';
+import type { AiTool } from '../providers/contract';
+/**
+ * The two strict tools an insight job answers through (AGL-2915).
+ *
+ * `read_figures` names readers — an id, a window and the reader's own
+ * parameters — and nothing else: the model never writes a query, a field
+ * path or a filter of its own, only a choice among the readers the request
+ * lists. `submit_insights` is the answer, each insight citing the table rows
+ * its figures come from. Lengths and counts are stated in the descriptions,
+ * as the platform's other strict tools state them; the step holds every one.
+ */
+export declare const AI_INSIGHT_READ_TOOL_NAME = "read_figures";
+export declare const AI_INSIGHT_ANSWER_TOOL_NAME = "submit_insights";
+export declare function aiInsightReadTool(): AiTool;
+export declare function aiInsightAnswerTool(): AiTool;
+/** One reader the model asked for, as it asked. */
+export interface AiInsightReadRequest {
+    reader: string;
+    days: number;
+    params: Record<string, string>;
+}
+/** The reads a `read_figures` call names, shape-checked and bounded; the step decides which are real. */
+export declare function parseAiInsightReads(input: unknown): AiInsightReadRequest[];
+/**
+ * A `submit_insights` call as the trace reads it, or `null` when the call is
+ * not an answer at all. Values keep the types the model wrote, so the trace
+ * — not this reader — decides what an unreadable citation costs.
+ */
+export declare function parseAiInsightAnswer(input: unknown): AiInsightAnswer | null;

package/src/lib/tools/ai-insight-tool.js

@@ -0,0 +1,200 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { AI_INSIGHT_GAP_MAX_CHARS, AI_INSIGHT_MAX_CHARS, AI_INSIGHT_MAX_CITED_ROWS, AI_INSIGHT_MAX_CITES, AI_INSIGHT_MAX_INSIGHTS, AI_INSIGHT_MAX_READS } from "../model/ai-insight.js";
+/**
+ * The two strict tools an insight job answers through (AGL-2915).
+ *
+ * `read_figures` names readers — an id, a window and the reader's own
+ * parameters — and nothing else: the model never writes a query, a field
+ * path or a filter of its own, only a choice among the readers the request
+ * lists. `submit_insights` is the answer, each insight citing the table rows
+ * its figures come from. Lengths and counts are stated in the descriptions,
+ * as the platform's other strict tools state them; the step holds every one.
+ */ export const AI_INSIGHT_READ_TOOL_NAME = 'read_figures';
+export const AI_INSIGHT_ANSWER_TOOL_NAME = 'submit_insights';
+export function aiInsightReadTool() {
+    return {
+        name: AI_INSIGHT_READ_TOOL_NAME,
+        description: `Choose the readers whose tables answer the question: at most ${AI_INSIGHT_MAX_READS}, ` + 'each from the list the request gives. Every field is required.',
+        strict: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                reads: {
+                    type: 'array',
+                    description: `The readers to read, most useful first; at most ${AI_INSIGHT_MAX_READS}.`,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            reader: {
+                                type: 'string',
+                                description: 'A reader id from the list, exactly as written.'
+                            },
+                            days: {
+                                type: 'integer',
+                                description: 'One of the windows that reader lists, in days; 0 for a reader that lists none.'
+                            },
+                            params: {
+                                type: 'array',
+                                description: 'The parameters that reader lists, by name; empty when it lists none.',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        name: {
+                                            type: 'string'
+                                        },
+                                        value: {
+                                            type: 'string'
+                                        }
+                                    },
+                                    required: [
+                                        'name',
+                                        'value'
+                                    ],
+                                    additionalProperties: false
+                                }
+                            }
+                        },
+                        required: [
+                            'reader',
+                            'days',
+                            'params'
+                        ],
+                        additionalProperties: false
+                    }
+                }
+            },
+            required: [
+                'reads'
+            ],
+            additionalProperties: false
+        }
+    };
+}
+export function aiInsightAnswerTool() {
+    return {
+        name: AI_INSIGHT_ANSWER_TOOL_NAME,
+        description: `Answer with at most ${AI_INSIGHT_MAX_INSIGHTS} insights, each citing the table rows its figures come from. ` + 'Every field is required.',
+        strict: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                insights: {
+                    type: 'array',
+                    description: `Most useful first; at most ${AI_INSIGHT_MAX_INSIGHTS}.`,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            text: {
+                                type: 'string',
+                                description: `One or two plain sentences; at most ${AI_INSIGHT_MAX_CHARS} characters.`
+                            },
+                            cites: {
+                                type: 'array',
+                                description: `The tables and rows its figures come from; at most ${AI_INSIGHT_MAX_CITES} tables.`,
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        table: {
+                                            type: 'string',
+                                            description: 'The table handle: t1, t2, …'
+                                        },
+                                        rows: {
+                                            type: 'array',
+                                            description: `Row numbers as the table numbers them, from 0; at most ${AI_INSIGHT_MAX_CITED_ROWS}.`,
+                                            items: {
+                                                type: 'integer'
+                                            }
+                                        }
+                                    },
+                                    required: [
+                                        'table',
+                                        'rows'
+                                    ],
+                                    additionalProperties: false
+                                }
+                            }
+                        },
+                        required: [
+                            'text',
+                            'cites'
+                        ],
+                        additionalProperties: false
+                    }
+                },
+                gap: {
+                    anyOf: [
+                        {
+                            type: 'string'
+                        },
+                        {
+                            type: 'null'
+                        }
+                    ],
+                    description: `What the tables cannot answer, in one sentence without numbers; at most ${AI_INSIGHT_GAP_MAX_CHARS} characters. null when nothing.`
+                }
+            },
+            required: [
+                'insights',
+                'gap'
+            ],
+            additionalProperties: false
+        }
+    };
+}
+const isRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+/** The reads a `read_figures` call names, shape-checked and bounded; the step decides which are real. */ export function parseAiInsightReads(input) {
+    const reads = isRecord(input) && Array.isArray(input['reads']) ? input['reads'] : [];
+    const parsed = [];
+    for (const raw of reads){
+        if (parsed.length === AI_INSIGHT_MAX_READS) break;
+        if (!isRecord(raw) || typeof raw['reader'] !== 'string') continue;
+        const params = {};
+        for (const pair of Array.isArray(raw['params']) ? raw['params'] : []){
+            if (isRecord(pair) && typeof pair['name'] === 'string' && typeof pair['value'] === 'string') {
+                params[pair['name']] = pair['value'];
+            }
+        }
+        const days = Number(raw['days']);
+        parsed.push({
+            reader: raw['reader'].trim(),
+            days: Number.isInteger(days) && days >= 0 ? days : 0,
+            params
+        });
+    }
+    return parsed;
+}
+/**
+ * A `submit_insights` call as the trace reads it, or `null` when the call is
+ * not an answer at all. Values keep the types the model wrote, so the trace
+ * — not this reader — decides what an unreadable citation costs.
+ */ export function parseAiInsightAnswer(input) {
+    if (!isRecord(input) || !Array.isArray(input['insights'])) return null;
+    const insights = input['insights'].filter(isRecord).map((raw)=>({
+            text: typeof raw['text'] === 'string' ? raw['text'] : '',
+            cites: (Array.isArray(raw['cites']) ? raw['cites'] : []).filter(isRecord).map((cite)=>({
+                    table: typeof cite['table'] === 'string' ? cite['table'] : '',
+                    rows: Array.isArray(cite['rows']) ? cite['rows'] : []
+                }))
+        }));
+    const gap = typeof input['gap'] === 'string' ? input['gap'] : null;
+    return {
+        insights,
+        gap
+    };
+}
+
+//# sourceMappingURL=ai-insight-tool.js.map