@mvriu5/payload-ai 1.5.0 → 1.6.0

package/README.md

@@ -101,6 +101,8 @@ const options: PayloadAIPluginOptions = {
     },
   ],
   maxOutputTokens: 1200,
+  promptCaching: true,
+  translate: true,
   maxTokenUsage: {
     type: "user",
     perDay: 50_000,
@@ -135,6 +137,26 @@ payloadAiPlugin({
 
 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.
@@ -276,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/translate-document/TranslateDocumentButton.d.ts

@@ -0,0 +1,2 @@
+declare const TranslateDocumentButton: () => import("react").JSX.Element | null;
+export default TranslateDocumentButton;

package/dist/components/translate-document/TranslateDocumentButton.js

@@ -0,0 +1,111 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, useConfig, useDocumentForm, useDocumentInfo, useLocale } from "@payloadcms/ui";
+import { formatAdminURL } from "payload/shared";
+import { useEffect, useState } from "react";
+import styles from "./TranslateDocumentButton.module.css";
+const TranslateDocumentButton = ()=>{
+    const configContext = useConfig();
+    const documentForm = useDocumentForm();
+    const documentInfo = useDocumentInfo();
+    const locale = useLocale();
+    const [available, setAvailable] = useState(false);
+    const [error, setError] = useState("");
+    const [isChecking, setIsChecking] = useState(true);
+    const [isTranslating, setIsTranslating] = useState(false);
+    const scope = documentInfo.collectionSlug ? {
+        slug: documentInfo.collectionSlug,
+        type: "collection"
+    } : documentInfo.globalSlug ? {
+        slug: documentInfo.globalSlug,
+        type: "global"
+    } : null;
+    const apiRoute = configContext?.config?.routes?.api;
+    const request = async (action)=>{
+        if (!apiRoute || !scope) return null;
+        const response = await fetch(formatAdminURL({
+            apiRoute,
+            path: "/ai-translate-document"
+        }), {
+            body: JSON.stringify({
+                action,
+                id: documentInfo.id,
+                locale: locale.code,
+                scope
+            }),
+            headers: {
+                "Content-Type": "application/json"
+            },
+            method: "POST"
+        });
+        const result = await response.json().catch(()=>null);
+        if (!response.ok || !result) throw new Error(result?.error || "Could not translate this locale.");
+        return result;
+    };
+    useEffect(()=>{
+        let active = true;
+        setAvailable(false);
+        setError("");
+        setIsChecking(true);
+        void request("status").then((result)=>{
+            if (active) setAvailable(Boolean(result?.available));
+        }).catch(()=>{
+            if (active) setAvailable(false);
+        }).finally(()=>{
+            if (active) setIsChecking(false);
+        });
+        return ()=>{
+            active = false;
+        };
+    }, [
+        apiRoute,
+        documentInfo.id,
+        locale.code,
+        scope?.slug,
+        scope?.type
+    ]);
+    const translate = async ()=>{
+        if (isTranslating) return;
+        setError("");
+        setIsTranslating(true);
+        try {
+            const result = await request("translate");
+            for (const entry of result?.values || []){
+                documentForm.dispatchFields({
+                    ...entry.fieldType === "richText" ? {
+                        initialValue: entry.value
+                    } : {},
+                    path: entry.path,
+                    type: "UPDATE",
+                    value: entry.value
+                });
+            }
+            documentForm.setModified(true);
+            setAvailable(false);
+        } catch (translationError) {
+            setError(translationError instanceof Error ? translationError.message : "Could not translate this locale.");
+        } finally{
+            setIsTranslating(false);
+        }
+    };
+    if (isChecking || !available) return null;
+    return /*#__PURE__*/ _jsxs("div", {
+        className: styles.wrapper,
+        children: [
+            error && /*#__PURE__*/ _jsx("span", {
+                className: styles.error,
+                role: "alert",
+                children: error
+            }),
+            /*#__PURE__*/ _jsx(Button, {
+                buttonStyle: "subtle",
+                disabled: isTranslating,
+                margin: false,
+                onClick: ()=>void translate(),
+                size: "medium",
+                children: isTranslating ? "Translating..." : "Translate"
+            })
+        ]
+    });
+};
+export default TranslateDocumentButton;

package/dist/components/translate-document/TranslateDocumentButton.module.css

@@ -0,0 +1,11 @@
+.wrapper {
+    align-items: center;
+    display: flex;
+    gap: 8px;
+}
+
+.error {
+    color: var(--theme-error-500);
+    font-size: 12px;
+    max-width: 240px;
+}

package/dist/exports/client.d.ts

@@ -2,7 +2,9 @@ import Dashboard from "../components/dashboard/Dashboard.js";
 import APIKeyField from "../components/APIKeyField.js";
 import AIInput from "../components/ai-input/AIInput.js";
 import GenerateField from "../components/generate-field/GenerateField.js";
+import TranslateDocumentButton from "../components/translate-document/TranslateDocumentButton.js";
 export { Dashboard };
 export { APIKeyField as AIApiKeyField };
 export { AIInput };
 export { GenerateField };
+export { TranslateDocumentButton };

package/dist/exports/client.js

@@ -2,7 +2,9 @@ import Dashboard from "../components/dashboard/Dashboard.js";
 import APIKeyField from "../components/APIKeyField.js";
 import AIInput from "../components/ai-input/AIInput.js";
 import GenerateField from "../components/generate-field/GenerateField.js";
+import TranslateDocumentButton from "../components/translate-document/TranslateDocumentButton.js";
 export { Dashboard };
 export { APIKeyField as AIApiKeyField };
 export { AIInput };
 export { GenerateField };
+export { TranslateDocumentButton };

package/dist/handlers/chatHandler.d.ts

@@ -39,6 +39,7 @@ type ChatOptions = {
     maxOutputTokens?: number;
     maxTokenUsage?: ResolvedMaxTokenUsageOptions;
     models?: AIModelConfig;
+    promptCaching?: boolean;
     providers?: ResolvedAIProviderConfig[];
 };
 export declare const createChatHandler: (options?: ChatOptions) => PayloadHandler;