@humaan/payload-plugin-ai-assistant 0.0.0-stage → 0.1.1

package/dist/chat/tools.js

@@ -0,0 +1,596 @@
+import { jsonSchema, tool } from 'ai';
+import { z } from 'zod';
+import { aiAssistantPlanSlug, maxReadCharacters } from '../constants.js';
+import { notAllowed } from '../plan/allowed.js';
+import { canChangeTarget, collectionFields, describeTarget, globalFields, planTargets, searchWhere, titleFieldOf } from '../plan/catalogue.js';
+import { fieldChanges } from '../plan/diff.js';
+import { parsePlan } from '../plan/parsePlan.js';
+import { valueAtPath } from '../plan/tokens.js';
+import { planView } from '../plan/view.js';
+import { outline, valueAtReadablePath } from '../read/outline.js';
+import { readableTarget } from '../read/readTarget.js';
+import { compiledFieldAtPath, followedSlug, unknownFieldPaths } from '../schema/fields.js';
+import { missingListingCreatePaths } from '../schema/listingFields.js';
+import { userIdOf } from '../settings.js';
+/**
+ * The full plan shape, so the model gets it right first time. parsePlan still checks every value,
+ * since a schema only describes what the model should send.
+ */ const planInput = jsonSchema({
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'summary',
+        'blocked',
+        'operations'
+    ],
+    properties: {
+        summary: {
+            type: 'string',
+            description: 'What the plan changes, in one or two sentences.'
+        },
+        blocked: {
+            type: 'boolean',
+            description: 'True when the editor must choose first. Then operations is empty.'
+        },
+        questions: {
+            type: 'array',
+            items: {
+                type: 'string'
+            }
+        },
+        candidates: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: [
+                    'kind',
+                    'slug',
+                    'label'
+                ],
+                properties: {
+                    kind: {
+                        type: 'string',
+                        enum: [
+                            'collection',
+                            'global'
+                        ]
+                    },
+                    slug: {
+                        type: 'string'
+                    },
+                    id: {
+                        type: 'string'
+                    },
+                    label: {
+                        type: 'string'
+                    }
+                }
+            }
+        },
+        operations: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: [
+                    'action',
+                    'kind',
+                    'slug',
+                    'label',
+                    'summary'
+                ],
+                properties: {
+                    action: {
+                        type: 'string',
+                        enum: [
+                            'create',
+                            'update'
+                        ]
+                    },
+                    kind: {
+                        type: 'string',
+                        enum: [
+                            'collection',
+                            'global'
+                        ]
+                    },
+                    slug: {
+                        type: 'string',
+                        description: 'Collection or global slug.'
+                    },
+                    id: {
+                        type: 'string',
+                        description: 'Required to update a collection document.'
+                    },
+                    label: {
+                        type: 'string',
+                        description: "The document's title, for the plan card."
+                    },
+                    summary: {
+                        type: 'string',
+                        description: 'What this operation changes, and whether it saves as a draft.'
+                    },
+                    set: {
+                        type: 'object',
+                        description: 'Field values, nested as in the field guide.'
+                    },
+                    append: {
+                        type: 'array',
+                        description: 'Blocks to add to the end of a blocks field.',
+                        items: {
+                            type: 'object',
+                            required: [
+                                'path',
+                                'blocks'
+                            ],
+                            properties: {
+                                path: {
+                                    type: 'string',
+                                    description: 'Dotted path to the blocks field, such as content.content.'
+                                },
+                                blocks: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'object'
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        files: {
+            type: 'array',
+            description: 'Attachments this plan saves. Only listed files are saved.',
+            items: {
+                type: 'object',
+                required: [
+                    'index'
+                ],
+                properties: {
+                    index: {
+                        type: 'integer'
+                    },
+                    alt: {
+                        type: 'string',
+                        description: 'Required for images.'
+                    },
+                    title: {
+                        type: 'string'
+                    },
+                    note: {
+                        type: 'string'
+                    }
+                }
+            }
+        }
+    }
+});
+/**
+ * Every tool reads with the editor's access. Only submitPlan writes, and it writes a plan, not the documents.
+ */ export function assistantTools({ req, chatId, collectionRules, files, onPlan, openDocument }) {
+    const targets = planTargets(req.payload.config);
+    return {
+        listTargets: tool({
+            description: 'List the collections and globals. canChange says whether a plan may change it; the others can still be read.',
+            inputSchema: z.object({}),
+            execute: ()=>({
+                    targets: targets.map((target)=>({
+                            slug: target.slug,
+                            kind: target.kind,
+                            label: target.label,
+                            drafts: target.drafts,
+                            upload: target.upload,
+                            canChange: canChangeTarget(req.payload.config, target.kind, target.slug)
+                        }))
+                })
+        }),
+        describeTarget: tool({
+            description: 'Return the field guide for one collection or global. Call this before writing its fields. Blocks are listed by name; pass blocks to get the fields of the ones you will write.',
+            inputSchema: z.object({
+                kind: z.enum([
+                    'collection',
+                    'global'
+                ]),
+                slug: z.string(),
+                blocks: z.array(z.string()).max(12).optional().describe('Block slugs to describe in full.')
+            }),
+            execute: ({ kind, slug, blocks })=>describeTarget(req.payload.config, kind, slug, collectionRules, blocks)
+        }),
+        searchDocuments: tool({
+            description: "Search one collection by its title or name, and filter by any field from its field guide, such as a category or relationship id. An empty query lists recent documents. If more than one result could be the editor's target, do not pick one.",
+            inputSchema: z.object({
+                collection: z.string(),
+                query: z.string(),
+                filters: z.array(z.object({
+                    field: z.string().regex(/^[\w.]+$/).describe('Field path from the field guide, such as category.'),
+                    operator: z.enum([
+                        'equals',
+                        'not_equals',
+                        'in',
+                        'like',
+                        'exists'
+                    ]),
+                    value: z.union([
+                        z.string(),
+                        z.number(),
+                        z.boolean(),
+                        z.array(z.union([
+                            z.string(),
+                            z.number()
+                        ]))
+                    ])
+                })).max(5).optional(),
+                limit: z.number().int().min(1).max(25).optional()
+            }),
+            execute: (input)=>searchDocuments(req, input.collection, input.query, input.filters, input.limit)
+        }),
+        readDocument: tool({
+            description: 'Read one document, or a global, with rich text as markdown. A long document comes back as an outline; pass a path, such as content.content.3, to read one part in full.',
+            inputSchema: z.object({
+                kind: z.enum([
+                    'collection',
+                    'global'
+                ]),
+                slug: z.string(),
+                id: z.string().optional(),
+                path: z.string().optional().describe('Dotted path to one part of the document. List items are numbered from 0.')
+            }),
+            execute: (input)=>readForModel(req, input, openDocument)
+        }),
+        submitPlan: tool({
+            description: 'Submit a plan for the editor to review. This does not save the changes. If this returns an error, correct the plan and call it again.',
+            inputSchema: planInput,
+            execute: async (input)=>{
+                const parsed = parsePlan(input, targets, files);
+                if (!parsed.ok) {
+                    return {
+                        ok: false,
+                        error: parsed.errors.join(' ')
+                    };
+                }
+                const problem = notAllowed(parsed.plan, req.payload.config) ?? unknownFields(req, parsed.plan) ?? missingListingFields(req, parsed.plan) ?? await missingDocuments(req, parsed.plan);
+                if (problem) {
+                    return {
+                        ok: false,
+                        error: problem
+                    };
+                }
+                const status = parsed.plan.blocked ? 'blocked' : 'proposed';
+                // Plans are written only here and by the apply endpoints, so a plan always comes from the model and its checks.
+                const saved = await req.payload.create({
+                    collection: aiAssistantPlanSlug,
+                    data: {
+                        owner: userIdOf(req.user),
+                        thread: chatId,
+                        status,
+                        summary: parsed.plan.summary,
+                        plan: parsed.plan
+                    },
+                    req
+                });
+                onPlan();
+                const adminRoute = req.payload.config.routes?.admin ?? '/admin';
+                const changes = await planFieldChanges(req, parsed.plan);
+                return {
+                    ok: true,
+                    status,
+                    plan: planView(String(saved.id), parsed.plan, adminRoute, changes)
+                };
+            },
+            // The editor sees each value beside the current one. The model wrote those values, so it gets the plan without them.
+            toModelOutput: ({ output })=>({
+                    type: 'json',
+                    value: withoutFieldChanges(output)
+                })
+        })
+    };
+}
+async function planFieldChanges(req, plan) {
+    return Promise.all(plan.operations.map(async (operation)=>{
+        const read = operation.action === 'update' ? await readDocument(req, operation.kind, operation.slug, operation.id) : undefined;
+        const current = read && 'document' in read ? read.document : undefined;
+        const changes = fieldChanges({
+            operation,
+            current,
+            files: plan.files,
+            operations: plan.operations
+        });
+        const slug = slugChange(req, operation, current);
+        return Promise.all([
+            ...changes,
+            ...slug ? [
+                slug
+            ] : []
+        ].map((change)=>withMedia(req, operation, change, current, plan.files)));
+    }));
+}
+/** A rename moves the URL when the slug follows the title, so the card shows it before Proceed. */ function slugChange(req, operation, current) {
+    if (operation.action !== 'update' || current === undefined) {
+        return undefined;
+    }
+    const fields = (operation.kind === 'collection' ? collectionFields(req.payload.config, operation.slug) : globalFields(req.payload.config, operation.slug)) ?? [];
+    const slug = followedSlug(fields, current, valueAtPath(operation.set, 'title'));
+    if (!slug) {
+        return undefined;
+    }
+    const before = valueAtPath(current, 'slug');
+    return {
+        path: 'slug',
+        ...typeof before === 'string' && before ? {
+            before
+        } : {},
+        after: `${slug} (follows the new title; the URL changes)`
+    };
+}
+/** Upload fields show the file on each side, read with the editor's access. */ async function withMedia(req, operation, change, current, files) {
+    if (change.added) {
+        return change;
+    }
+    const fields = (operation.kind === 'collection' ? collectionFields(req.payload.config, operation.slug) : globalFields(req.payload.config, operation.slug)) ?? [];
+    const field = compiledFieldAtPath(fields, change.path);
+    if (field?.kind !== 'upload' || field.hasMany) {
+        return change;
+    }
+    const [before, after] = await Promise.all([
+        mediaView(req, field.relationTo, current === undefined ? undefined : valueAtPath(current, change.path), files),
+        mediaView(req, field.relationTo, valueAtPath(operation.set, change.path), files)
+    ]);
+    if (!before && !after) {
+        return change;
+    }
+    return {
+        ...change,
+        media: {
+            ...before ? {
+                before
+            } : {},
+            ...after ? {
+                after
+            } : {}
+        }
+    };
+}
+async function mediaView(req, relationTo, value, files) {
+    if (value && typeof value === 'object' && '$file' in value) {
+        const file = files.find((item)=>item.index === value.$file);
+        return file ? {
+            label: file.title || file.name,
+            pending: true
+        } : undefined;
+    }
+    const reference = value && typeof value === 'object' && 'relationTo' in value && 'value' in value ? {
+        collection: String(value.relationTo),
+        id: value.value
+    } : {
+        collection: relationTo[0],
+        id: value
+    };
+    if (!reference.collection || typeof reference.id !== 'string' && typeof reference.id !== 'number') {
+        return undefined;
+    }
+    try {
+        const doc = await req.payload.findByID({
+            collection: reference.collection,
+            id: reference.id,
+            depth: 0,
+            overrideAccess: false,
+            req,
+            user: req.user
+        });
+        const text = (key)=>typeof doc[key] === 'string' && doc[key] ? doc[key] : undefined;
+        const isImage = text('mimeType')?.startsWith('image/');
+        return {
+            label: text('alt') ?? text('title') ?? text('filename') ?? String(reference.id),
+            ...isImage && (text('thumbnailURL') ?? text('url')) ? {
+                thumbnail: text('thumbnailURL') ?? text('url')
+            } : {}
+        };
+    } catch  {
+        return undefined;
+    }
+}
+function withoutFieldChanges(output) {
+    if (!output.ok) {
+        return output;
+    }
+    const operations = output.plan.operations.map(({ fieldChanges: _shown, ...operation })=>operation);
+    return {
+        ...output,
+        plan: {
+            ...output.plan,
+            operations
+        }
+    };
+}
+async function searchDocuments(req, collection, query, filters = [], limit = 8) {
+    const target = planTargets(req.payload.config).find((item)=>item.kind === 'collection' && item.slug === collection);
+    if (!target) {
+        return {
+            error: `Unknown collection "${collection}".`
+        };
+    }
+    const titleKey = titleFieldOf(req.payload.config, collection);
+    try {
+        const found = await req.payload.find({
+            collection: collection,
+            where: searchWhere(req.payload.config, collection, query, filters),
+            sort: '-updatedAt',
+            limit,
+            depth: 0,
+            draft: true,
+            overrideAccess: false,
+            req,
+            user: req.user,
+            select: {
+                [titleKey]: true
+            }
+        });
+        return {
+            count: found.docs.length,
+            multiple: found.docs.length > 1,
+            documents: found.docs.map((doc)=>{
+                const record = doc;
+                const label = typeof record[titleKey] === 'string' ? record[titleKey] : String(record.id);
+                return {
+                    id: String(record.id),
+                    label
+                };
+            })
+        };
+    } catch (error) {
+        return {
+            error: error instanceof Error ? error.message : 'The search failed.'
+        };
+    }
+}
+/**
+ * What readDocument returns to the model. The open document is read from its form, so it includes unsaved changes.
+ * Long documents come back as an outline, and one part can be read in full by path.
+ */ async function readForModel(req, input, open) {
+    const isOpen = open?.context.kind === input.kind && open.context.slug === input.slug && (input.kind === 'global' || open.context.id === input.id);
+    const read = isOpen && open ? {
+        label: open.context.label,
+        document: open.document
+    } : await readDocument(req, input.kind, input.slug, input.id);
+    if ('error' in read) {
+        return read;
+    }
+    const path = input.path?.trim();
+    if (path) {
+        const value = valueAtReadablePath(read.document, path);
+        if (value === undefined) {
+            return {
+                error: `Nothing at ${path}. Read the document without a path to see its outline.`
+            };
+        }
+        const json = JSON.stringify(value) ?? '';
+        return json.length > maxReadCharacters ? {
+            label: read.label,
+            path,
+            outline: outline(value),
+            note: 'This part is long, so this is an outline. Read a deeper path for full values.'
+        } : {
+            label: read.label,
+            path,
+            value
+        };
+    }
+    if ((JSON.stringify(read.document) ?? '').length <= maxReadCharacters) {
+        return read;
+    }
+    return {
+        label: read.label,
+        outline: outline(read.document),
+        note: 'This document is long, so this is an outline. Call readDocument again with a path for full values.'
+    };
+}
+/** Reads with the editor's access, so the assistant sees only what the editor can see. */ export async function readDocument(req, kind, slug, id) {
+    const target = planTargets(req.payload.config).find((item)=>item.kind === kind && item.slug === slug);
+    if (!target) {
+        return {
+            error: `Unknown ${kind} "${slug}".`
+        };
+    }
+    try {
+        if (kind === 'global') {
+            const doc = await req.payload.findGlobal({
+                slug: slug,
+                depth: 0,
+                draft: true,
+                overrideAccess: false,
+                req,
+                user: req.user
+            });
+            return {
+                label: target.label,
+                document: await readableTarget(req.payload.config, kind, slug, doc)
+            };
+        }
+        if (!id) {
+            return {
+                error: 'An id is required to read a collection document.'
+            };
+        }
+        const doc = await req.payload.findByID({
+            collection: slug,
+            id,
+            depth: 0,
+            draft: true,
+            overrideAccess: false,
+            req,
+            user: req.user
+        });
+        const title = doc[titleFieldOf(req.payload.config, slug)];
+        return {
+            label: typeof title === 'string' && title ? title : id,
+            document: await readableTarget(req.payload.config, kind, slug, doc)
+        };
+    } catch (error) {
+        return {
+            error: error instanceof Error ? error.message : 'The document could not be read.'
+        };
+    }
+}
+function unknownFields(req, plan) {
+    for (const operation of plan.operations){
+        const fields = operation.kind === 'collection' ? collectionFields(req.payload.config, operation.slug) : globalFields(req.payload.config, operation.slug);
+        if (!fields) {
+            continue;
+        }
+        const unknown = unknownFieldPaths(fields, operation.set);
+        if (unknown.length > 0) {
+            return `${operation.label} (${operation.slug}) has no field ${unknown.join(', ')}. Use the names in the field guide, nested as objects.`;
+        }
+    }
+    return undefined;
+}
+function missingListingFields(req, plan) {
+    for (const operation of plan.operations){
+        if (operation.action !== 'create') {
+            continue;
+        }
+        const fields = operation.kind === 'collection' ? collectionFields(req.payload.config, operation.slug) : globalFields(req.payload.config, operation.slug);
+        if (!fields) {
+            continue;
+        }
+        const missing = missingListingCreatePaths(fields, operation.set);
+        if (missing.length === 0) {
+            continue;
+        }
+        return `When creating ${operation.label} (${operation.slug}), fill: ${missing.join(', ')}.`;
+    }
+    return undefined;
+}
+async function missingDocuments(req, plan) {
+    const checks = [
+        ...plan.operations.filter((operation)=>operation.action === 'update' && operation.kind === 'collection' && operation.id).map((operation)=>({
+                slug: operation.slug,
+                id: operation.id,
+                message: `No ${operation.slug} document has id ${operation.id}. Search again and use an id from the result.`
+            })),
+        ...plan.candidates.filter((candidate)=>candidate.kind === 'collection' && candidate.id).map((candidate)=>({
+                slug: candidate.slug,
+                id: candidate.id,
+                message: `Candidate ${candidate.label} was not found in ${candidate.slug}.`
+            }))
+    ];
+    for (const check of checks){
+        try {
+            await req.payload.findByID({
+                collection: check.slug,
+                id: check.id,
+                depth: 0,
+                draft: true,
+                overrideAccess: false,
+                req,
+                user: req.user
+            });
+        } catch  {
+            return check.message;
+        }
+    }
+    return undefined;
+}
+
+//# sourceMappingURL=tools.js.map