@mvriu5/payload-ai 1.4.0 → 1.6.0

package/README.md

@@ -54,6 +54,7 @@ When `providers` is configured, provider selection and API keys are managed cent
 import type { PayloadAIPluginOptions } from "@mvriu5/payload-ai";
 
 const options: PayloadAIPluginOptions = {
+  aiInput: true,
   allowUserApiKeys: false,
   collections: {
     media: {
@@ -68,6 +69,7 @@ const options: PayloadAIPluginOptions = {
     },
     users: true,
   },
+  generateFields: true,
   media: {
     enabled: true,
     collectionSlug: "media",
@@ -99,6 +101,8 @@ const options: PayloadAIPluginOptions = {
     },
   ],
   maxOutputTokens: 1200,
+  promptCaching: true,
+  translate: true,
   maxTokenUsage: {
     type: "user",
     perDay: 50_000,
@@ -109,6 +113,50 @@ const options: PayloadAIPluginOptions = {
 
 `models` configures model choices for the user-selected provider mode. Use `providers` instead when provider selection, credentials, and endpoints should be managed centrally.
 
+### `aiInput`
+
+Controls whether the collapsible AI Assistant input is added to collection and global edit views. It defaults to `true`.
+
+```ts
+payloadAiPlugin({
+  aiInput: false,
+})
+```
+
+Disabling this option does not remove the AI dashboard or per-field Generate controls.
+
+### `generateFields`
+
+Controls whether supported fields receive a Generate control. It defaults to `true`.
+
+```ts
+payloadAiPlugin({
+  generateFields: false,
+})
+```
+
+Generate controls are added to `text`, `textarea`, `richText`, and `json` fields in collection and global edit views. When disabled, the plugin also omits the `/ai-generate-field` endpoint. The embedded AI Assistant and dashboard remain available.
+
+### `translate`
+
+Controls document translation for localized collections and globals. It defaults to `true`.
+
+```ts
+payloadAiPlugin({
+  translate: false,
+})
+```
+
+When enabled, the plugin adds a `Translate` action to the document header. It is shown only when:
+
+- a non-default locale is selected
+- at least one localized field is empty in that locale
+- the corresponding field in the default locale contains source content
+
+Translation fills only empty localized fields in the current Payload form and marks it as modified. Existing translated values are never overwritten. It does not save the document or global, so the generated values can be reviewed and validated before saving.
+
+When disabled, the plugin does not register the header control or the `/ai-translate-document` endpoint.
+
 ### `collections`
 
 Restricts AI read and write proposals to enabled collection slugs. If omitted, all non-internal Payload collections are available.
@@ -250,6 +298,18 @@ Use `type: "user"` to enforce separate budgets per authenticated user, or `type:
 
 Completed model usage is stored in the hidden `payload-ai-usage` collection. Requests made after a limit is reached return HTTP `429`. Because providers report token usage after completion, the request that crosses a limit is allowed to finish and subsequent requests are blocked.
 
+### `promptCaching`
+
+Enables provider prompt-caching hints and defaults to `true`. The chat endpoint keeps static instructions and Payload schemas in a stable prompt prefix, adds Anthropic cache-control breakpoints, and supplies a stable OpenAI prompt cache key. Gemini uses the same stable prefix with its implicit caching.
+
+```ts
+payloadAiPlugin({
+  promptCaching: false,
+})
+```
+
+Disable it when explicit provider-side caching is not desired. Dynamic document data and user prompts are never placed in the cacheable schema section. Managed providers with a custom `baseURL` receive the stable prefix but no provider-specific cache parameters, preserving compatibility with Ollama, vLLM, and other OpenAI-compatible endpoints.
+
 ### `allowUserApiKeys`
 
 Controls whether the plugin adds an `aiApiKey` field to the admin user collection.

package/dist/ai/promptCaching.d.ts

@@ -0,0 +1,23 @@
+import type { SystemModelMessage } from "ai";
+import type { AIProvider } from "./providerOptions.js";
+type PromptCacheContext = {
+    cacheable: Record<string, unknown>[];
+    dynamic: Record<string, unknown>[];
+};
+type PromptCacheProviderOptions = NonNullable<SystemModelMessage["providerOptions"]>;
+export declare const splitPromptCacheContext: (mentionContext: Record<string, unknown>[]) => PromptCacheContext;
+export declare const createCachedSystemMessages: ({ cacheableContext, cacheableInstructions, dynamicInstructions, enabled, provider, staticInstructions, }: {
+    cacheableContext: Record<string, unknown>[];
+    cacheableInstructions: string[];
+    dynamicInstructions: string[];
+    enabled: boolean;
+    provider: AIProvider;
+    staticInstructions: string[];
+}) => SystemModelMessage[];
+export declare const createPromptCacheProviderOptions: ({ cacheKeyParts, enabled, model, provider, }: {
+    cacheKeyParts: unknown[];
+    enabled: boolean;
+    model: string;
+    provider: AIProvider;
+}) => PromptCacheProviderOptions | undefined;
+export {};

package/dist/ai/promptCaching.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+const getContextKey = (context)=>{
+    return [
+        context.type,
+        context.parent,
+        context.collection,
+        context.slug
+    ].filter(Boolean).join(":") || JSON.stringify(context);
+};
+export const splitPromptCacheContext = (mentionContext)=>{
+    const cacheable = [];
+    const dynamic = [];
+    const cacheableKeys = new Set();
+    const addCacheable = (context)=>{
+        const key = getContextKey(context);
+        if (cacheableKeys.has(key)) return;
+        cacheableKeys.add(key);
+        cacheable.push(context);
+    };
+    for (const context of mentionContext){
+        if ([
+            "block",
+            "collection"
+        ].includes(String(context.type))) {
+            addCacheable(context);
+            continue;
+        }
+        if (context.type === "global" && "doc" in context) {
+            const { doc, ...schema } = context;
+            addCacheable(schema);
+            dynamic.push({
+                doc,
+                slug: context.slug,
+                type: "globalDocument"
+            });
+            continue;
+        }
+        if (context.type === "global") {
+            addCacheable(context);
+            continue;
+        }
+        if (context.type === "mediaAttachment" && context.schema && typeof context.schema === "object") {
+            addCacheable(context.schema);
+            const { schema: _schema, ...attachmentContext } = context;
+            dynamic.push(attachmentContext);
+            continue;
+        }
+        dynamic.push(context);
+    }
+    return {
+        cacheable,
+        dynamic
+    };
+};
+const withAnthropicCacheControl = (message, enabled, provider)=>{
+    if (!enabled || provider !== "claude") return message;
+    return {
+        ...message,
+        providerOptions: {
+            anthropic: {
+                cacheControl: {
+                    type: "ephemeral"
+                }
+            }
+        }
+    };
+};
+export const createCachedSystemMessages = ({ cacheableContext, cacheableInstructions, dynamicInstructions, enabled, provider, staticInstructions })=>{
+    const messages = [
+        withAnthropicCacheControl({
+            content: staticInstructions.join("\n"),
+            role: "system"
+        }, enabled, provider)
+    ];
+    const scopedContent = [
+        ...cacheableContext.length ? [
+            "Payload schema references JSON. Use exact field names and values:",
+            JSON.stringify(cacheableContext)
+        ] : [],
+        ...cacheableInstructions
+    ];
+    if (scopedContent.length > 0) {
+        messages.push(withAnthropicCacheControl({
+            content: scopedContent.join("\n"),
+            role: "system"
+        }, enabled, provider));
+    }
+    if (dynamicInstructions.length > 0) {
+        messages.push({
+            content: dynamicInstructions.join("\n"),
+            role: "system"
+        });
+    }
+    return messages;
+};
+export const createPromptCacheProviderOptions = ({ cacheKeyParts, enabled, model, provider })=>{
+    if (!enabled) return undefined;
+    if (provider === "openai") {
+        const digest = createHash("sha256").update(JSON.stringify([
+            "payload-ai-v1",
+            model,
+            ...cacheKeyParts
+        ])).digest("hex").slice(0, 32);
+        return {
+            openai: {
+                promptCacheKey: `payload-ai-${digest}`
+            }
+        };
+    }
+    if (provider === "openrouter" && model.toLowerCase().startsWith("anthropic/")) {
+        return {
+            openrouter: {
+                cache_control: {
+                    type: "ephemeral"
+                }
+            }
+        };
+    }
+    return undefined;
+};

package/dist/ai/proposalRepair.d.ts

@@ -0,0 +1,30 @@
+import type { ProposalValidationIssue } from "../payload/proposalData.js";
+export declare const maxProposalRepairAttempts = 1;
+export type CompactProposalRepairIssue = {
+    code: string;
+    hint: string;
+    path: string;
+};
+type ProposalRepairTarget = {
+    collection?: string;
+    id?: string;
+    slug?: string;
+    tool: string;
+};
+export declare const compactProposalRepairIssues: (issues: ProposalValidationIssue[]) => CompactProposalRepairIssue[];
+export declare const createProposalRepairKey: ({ collection, id, slug, tool }: ProposalRepairTarget) => string;
+export declare const createProposalRepairTracker: () => {
+    beginCall(target: ProposalRepairTarget): "initial" | "blocked" | "repair";
+    registerFailure(target: ProposalRepairTarget): {
+        attempt: number;
+        errorCode: "REPAIR_EXHAUSTED";
+        maxAttempts: number;
+        retryable: boolean;
+    } | {
+        attempt: number;
+        errorCode: "INVALID_PROPOSAL_DATA";
+        maxAttempts: number;
+        retryable: boolean;
+    };
+};
+export {};

package/dist/ai/proposalRepair.js

@@ -0,0 +1,76 @@
+export const maxProposalRepairAttempts = 1;
+const getIssueHint = (issue)=>{
+    switch(issue.code){
+        case "invalid_array":
+            return "Use an array of complete objects matching the child fields.";
+        case "invalid_block_type":
+            return "Use an exact blockType from the schema.";
+        case "invalid_blocks":
+            return "Use an array of block objects with blockType and exact field names.";
+        case "invalid_checkbox":
+            return "Use true or false.";
+        case "invalid_container":
+            return "Use an object matching the nested field schema.";
+        case "invalid_date":
+            return "Use a valid date string.";
+        case "invalid_option":
+            return issue.message;
+        case "invalid_relationship":
+            return "Use an existing document ID or { relationTo, value } for polymorphic relationships.";
+        case "missing_required_field":
+            return "Add the required field with a schema-compatible value.";
+        case "non_localized_field_in_secondary_locale":
+            return "Move this field to the primary locale data.";
+        case "unknown_field":
+            return "Remove it and use exact schema field names only.";
+        default:
+            return issue.message;
+    }
+};
+export const compactProposalRepairIssues = (issues)=>{
+    return issues.slice(0, 6).map((issue)=>({
+            code: issue.code,
+            hint: getIssueHint(issue).slice(0, 180),
+            path: issue.path
+        }));
+};
+export const createProposalRepairKey = ({ collection, id, slug, tool })=>{
+    return [
+        tool,
+        collection || slug || "",
+        id || ""
+    ].join(":");
+};
+export const createProposalRepairTracker = ()=>{
+    const statesByTarget = new Map();
+    return {
+        beginCall (target) {
+            const state = statesByTarget.get(createProposalRepairKey(target));
+            if (!state) return "initial";
+            if (state.repairCallConsumed) return "blocked";
+            state.repairCallConsumed = true;
+            return "repair";
+        },
+        registerFailure (target) {
+            const key = createProposalRepairKey(target);
+            const state = statesByTarget.get(key);
+            if (state) {
+                return {
+                    attempt: maxProposalRepairAttempts,
+                    errorCode: "REPAIR_EXHAUSTED",
+                    maxAttempts: maxProposalRepairAttempts,
+                    retryable: false
+                };
+            }
+            statesByTarget.set(key, {
+                repairCallConsumed: false
+            });
+            return {
+                attempt: 1,
+                errorCode: "INVALID_PROPOSAL_DATA",
+                maxAttempts: maxProposalRepairAttempts,
+                retryable: true
+            };
+        }
+    };
+};

package/dist/ai/sensitiveData.d.ts

@@ -1,2 +1,3 @@
+export declare const isSensitiveKey: (key: string) => boolean;
 export declare const containsSensitiveData: (value: unknown) => boolean;
 export declare const redactSensitiveData: (value: unknown) => unknown;

package/dist/ai/sensitiveData.js

@@ -5,10 +5,12 @@ const sensitiveKeyPatterns = [
     /^aiApiKey$/i,
     /^authorization$/i,
     /^accessToken$/i,
+    /^password$/i,
+    /^privateKey$/i,
     /^refreshToken$/i,
     /^secret$/i
 ];
-const isSensitiveKey = (key)=>sensitiveKeyPatterns.some((pattern)=>pattern.test(key));
+export const isSensitiveKey = (key)=>sensitiveKeyPatterns.some((pattern)=>pattern.test(key));
 export const containsSensitiveData = (value)=>{
     if (Array.isArray(value)) return value.some(containsSensitiveData);
     if (!isRecord(value)) return false;

package/dist/components/ai-input/AIInput.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Button, useConfig, useDocumentForm, useDocumentInfo, useLocale } from "@payloadcms/ui";
+import { Button, ChevronIcon, useConfig, useDocumentForm, useDocumentInfo, useLocale } from "@payloadcms/ui";
 import { formatAdminURL } from "payload/shared";
 import { useEffect, useRef, useState } from "react";
 import { mergeData } from "../../payload/shared.js";
@@ -281,7 +281,7 @@ const AIInputCore = ({ applyProposalLocally, documentScope, isDashboard })=>{
             children: /*#__PURE__*/ _jsxs("div", {
                 className: styles.chat,
                 children: [
-                    /*#__PURE__*/ _jsx("div", {
+                    isDashboard && /*#__PURE__*/ _jsx("div", {
                         className: styles.chatHeader,
                         children: /*#__PURE__*/ _jsx("h2", {
                             className: styles.chatTitle,
@@ -299,13 +299,13 @@ const AIInputCore = ({ applyProposalLocally, documentScope, isDashboard })=>{
     return /*#__PURE__*/ _jsx("div", {
         className: styles.chatLayout,
         style: {
-            marginBottom: isDashboard ? "0" : "20px",
+            marginBottom: "0",
             height: isDashboard ? "332px" : "220px"
         },
         children: /*#__PURE__*/ _jsxs("div", {
             className: styles.chat,
             children: [
-                /*#__PURE__*/ _jsx("div", {
+                isDashboard && /*#__PURE__*/ _jsx("div", {
                     className: styles.chatHeader,
                     children: /*#__PURE__*/ _jsx("h2", {
                         className: styles.chatTitle,
@@ -543,6 +543,36 @@ const AIInput = ({ isDashboard = false })=>{
     if (isDashboard) return /*#__PURE__*/ _jsx(AIInputCore, {
         isDashboard: true
     });
-    return /*#__PURE__*/ _jsx(DocumentAIInput, {});
+    return /*#__PURE__*/ _jsx(CollapsibleDocumentAIInput, {});
+};
+const CollapsibleDocumentAIInput = ()=>{
+    const [isExpanded, setIsExpanded] = useState(false);
+    return /*#__PURE__*/ _jsxs("div", {
+        className: styles.collapsible,
+        children: [
+            /*#__PURE__*/ _jsxs("button", {
+                "aria-controls": "payload-ai-input-content",
+                "aria-expanded": isExpanded,
+                className: styles.collapsibleToggle,
+                onClick: ()=>setIsExpanded((current)=>!current),
+                type: "button",
+                children: [
+                    /*#__PURE__*/ _jsx("span", {
+                        children: "AI Assistant"
+                    }),
+                    /*#__PURE__*/ _jsx(ChevronIcon, {
+                        ariaLabel: isExpanded ? "Collapse AI Assistant" : "Expand AI Assistant",
+                        className: styles.collapsibleChevron,
+                        direction: isExpanded ? "up" : "down"
+                    })
+                ]
+            }),
+            isExpanded && /*#__PURE__*/ _jsx("div", {
+                className: styles.collapsibleContent,
+                id: "payload-ai-input-content",
+                children: /*#__PURE__*/ _jsx(DocumentAIInput, {})
+            })
+        ]
+    });
 };
 export default AIInput;

package/dist/components/ai-input/AIInput.module.css

@@ -1,3 +1,52 @@
+.collapsible {
+    border: 1px solid var(--theme-elevation-150);
+    border-radius: 8px;
+    margin-bottom: 20px;
+    overflow: hidden;
+    width: 100%;
+}
+
+.collapsibleToggle {
+    align-items: center;
+    background: transparent;
+    border: 0;
+    color: var(--theme-text);
+    cursor: pointer;
+    display: flex;
+    font: inherit;
+    font-weight: 600;
+    justify-content: space-between;
+    min-height: 44px;
+    padding: 0 20px;
+    text-align: left;
+    width: 100%;
+}
+
+.collapsibleToggle:hover {
+    color: var(--theme-elevation-800);
+}
+
+.collapsibleToggle:focus-visible {
+    outline: 2px solid var(--theme-success-500);
+    outline-offset: 2px;
+}
+
+.collapsibleToggle .collapsibleChevron {
+    flex: 0 0 24px;
+    height: 24px;
+    width: 24px;
+}
+
+.collapsibleContent {
+    padding: 0;
+}
+
+.collapsibleContent .chat {
+    border: 0;
+    border-radius: 0;
+    padding-top: 0;
+}
+
 .chatLayout {
     width: 100%;
     max-width: none;

package/dist/components/generate-field/GenerateField.d.ts

@@ -0,0 +1,11 @@
+type GenerateFieldProps = {
+    field?: {
+        hasMany?: boolean;
+    };
+    generationFieldKey: string;
+    generationFieldType: "json" | "richText" | "text" | "textarea";
+    path: string;
+    readOnly?: boolean;
+};
+declare const GenerateField: ({ field, generationFieldKey, generationFieldType, path, readOnly }: GenerateFieldProps) => import("react").JSX.Element | null;
+export default GenerateField;

package/dist/components/generate-field/GenerateField.js

@@ -0,0 +1,109 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useConfig, useDocumentForm, useDocumentInfo, useField, useLocale } from "@payloadcms/ui";
+import { formatAdminURL } from "payload/shared";
+import { useState } from "react";
+import { createGeneratedRichTextValue } from "./richText.js";
+import styles from "./GenerateField.module.css";
+const pendingRequests = new Map();
+const requestGeneratedValue = ({ apiRoute, body, cacheKey })=>{
+    const pending = pendingRequests.get(cacheKey);
+    if (pending) return pending;
+    const request = fetch(formatAdminURL({
+        apiRoute,
+        path: "/ai-generate-field"
+    }), {
+        body: JSON.stringify(body),
+        headers: {
+            "Content-Type": "application/json"
+        },
+        method: "POST"
+    }).then(async (response)=>{
+        const result = await response.json().catch(()=>null);
+        if (!response.ok || result?.value === undefined) throw new Error(result?.error || "Could not generate field content.");
+        return result;
+    }).finally(()=>pendingRequests.delete(cacheKey));
+    pendingRequests.set(cacheKey, request);
+    return request;
+};
+const GenerateField = ({ field, generationFieldKey, generationFieldType, path, readOnly })=>{
+    const configContext = useConfig();
+    const documentForm = useDocumentForm();
+    const documentInfo = useDocumentInfo();
+    const locale = useLocale();
+    const { disabled, setValue } = useField({
+        path
+    });
+    const [error, setError] = useState("");
+    const [isGenerating, setIsGenerating] = useState(false);
+    const scope = documentInfo.collectionSlug ? {
+        slug: documentInfo.collectionSlug,
+        type: "collection"
+    } : documentInfo.globalSlug ? {
+        slug: documentInfo.globalSlug,
+        type: "global"
+    } : null;
+    const generate = async ()=>{
+        const apiRoute = configContext?.config?.routes?.api;
+        if (!apiRoute || !scope || isGenerating) return;
+        setError("");
+        setIsGenerating(true);
+        try {
+            const context = documentForm.getData();
+            const cacheKey = JSON.stringify([
+                scope.type,
+                scope.slug,
+                generationFieldKey,
+                locale.code,
+                context
+            ]);
+            const result = await requestGeneratedValue({
+                apiRoute,
+                body: {
+                    context,
+                    fieldKey: generationFieldKey,
+                    locale: locale.code,
+                    scope
+                },
+                cacheKey
+            });
+            if (generationFieldType === "richText") {
+                const value = createGeneratedRichTextValue(result.value);
+                documentForm.dispatchFields({
+                    initialValue: value,
+                    path,
+                    type: "UPDATE",
+                    value
+                });
+            } else {
+                setValue(field?.hasMany ? [
+                    result.value
+                ] : result.value);
+            }
+            documentForm.setModified(true);
+        } catch (err) {
+            setError(err instanceof Error ? err.message : "Could not generate field content.");
+        } finally{
+            setIsGenerating(false);
+        }
+    };
+    if (!scope) return null;
+    return /*#__PURE__*/ _jsxs("div", {
+        className: styles.generateField,
+        children: [
+            /*#__PURE__*/ _jsx("button", {
+                className: styles.generateButton,
+                disabled: Boolean(readOnly || disabled || isGenerating),
+                onClick: ()=>void generate(),
+                type: "button",
+                children: isGenerating ? "Generating..." : "Generate"
+            }),
+            error && /*#__PURE__*/ _jsx("span", {
+                className: styles.generateError,
+                role: "alert",
+                children: error
+            })
+        ]
+    });
+};
+export default GenerateField;

package/dist/components/generate-field/GenerateField.module.css

@@ -0,0 +1,39 @@
+.generateField {
+    align-items: center;
+    display: flex;
+    gap: 8px;
+    justify-content: flex-end;
+    margin-top: 6px;
+}
+
+.generateButton {
+    background: transparent;
+    border: 0;
+    color: var(--theme-elevation-600);
+    cursor: pointer;
+    font: inherit;
+    font-size: 12px;
+    line-height: 1.2;
+    padding: 2px 0;
+}
+
+.generateButton:hover,
+.generateButton:focus-visible {
+    color: var(--theme-text);
+}
+
+.generateButton:focus-visible {
+    outline: 1px solid currentColor;
+    outline-offset: 2px;
+}
+
+.generateButton:disabled {
+    cursor: not-allowed;
+    opacity: 0.45;
+}
+
+.generateError {
+    color: var(--theme-error-500);
+    font-size: 11px;
+    line-height: 1.2;
+}

package/dist/components/generate-field/richText.d.ts

@@ -0,0 +1,29 @@
+type LexicalTextNode = {
+    detail: number;
+    format: number;
+    mode: "normal";
+    style: string;
+    text: string;
+    type: "text";
+    version: 1;
+};
+type LexicalParagraphNode = {
+    children: LexicalTextNode[];
+    direction: "ltr";
+    format: "";
+    indent: number;
+    type: "paragraph";
+    version: 1;
+};
+export type GeneratedRichTextValue = {
+    root: {
+        children: LexicalParagraphNode[];
+        direction: "ltr";
+        format: "";
+        indent: number;
+        type: "root";
+        version: 1;
+    };
+};
+export declare const createGeneratedRichTextValue: (value: string) => GeneratedRichTextValue;
+export {};