@mvriu5/payload-ai 1.2.0 → 1.4.0

package/README.md

@@ -39,21 +39,27 @@ export default buildConfig({
 });
 ```
 
-The plugin adds two fields to the configured Payload admin user collection:
+Without centrally configured providers, the plugin adds two fields to the configured Payload admin user collection:
 
 - `aiProvider`
 - `aiApiKey`
 
 Users can select their provider and optionally store their own API key in account settings. If no account-level key is set, the chat endpoint uses provider environment variables.
 
+When `providers` is configured, provider selection and API keys are managed centrally. The plugin does not add either field to the user collection. All configured provider models are grouped by provider in the AI input.
+
 ## Options
 
 ```ts
-import type { PayloadAiPluginOptions } from "@mvriu5/payload-ai";
+import type { PayloadAIPluginOptions } from "@mvriu5/payload-ai";
 
-const options: PayloadAiPluginOptions = {
+const options: PayloadAIPluginOptions = {
   allowUserApiKeys: false,
   collections: {
+    media: {
+      read: true,
+      update: true,
+    },
     posts: {
       read: true,
       create: true,
@@ -62,22 +68,47 @@ const options: PayloadAiPluginOptions = {
     },
     users: true,
   },
-  models: {
-    defaults: {
-      openai: "gpt-4.1-mini",
-      openrouter: "openai/gpt-oss-120b",
-    },
-    providers: {
-      openai: [
+  media: {
+    enabled: true,
+    collectionSlug: "media",
+    acceptedMimeTypes: ["image/*"],
+    maxFileSize: 10 * 1024 * 1024,
+  },
+  providers: [
+    {
+      id: "company-openai",
+      label: "Company OpenAI",
+      provider: "openai",
+      apiKey: process.env.COMPANY_OPENAI_API_KEY,
+      models: [
         { label: "GPT-4.1 Mini", value: "gpt-4.1-mini" },
         { label: "GPT-4.1", value: "gpt-4.1" },
       ],
+      defaultModel: "gpt-4.1-mini",
     },
-  },
+    {
+      id: "ollama",
+      label: "Local Ollama",
+      provider: "openai",
+      baseURL: "http://localhost:11434/v1",
+      apiKey: "ollama",
+      models: [
+        { label: "Llama 3.3", value: "llama3.3" },
+        { label: "Qwen 3", value: "qwen3" },
+      ],
+    },
+  ],
   maxOutputTokens: 1200,
+  maxTokenUsage: {
+    type: "user",
+    perDay: 50_000,
+    perWeek: 250_000,
+  },
 };
 ```
 
+`models` configures model choices for the user-selected provider mode. Use `providers` instead when provider selection, credentials, and endpoints should be managed centrally.
+
 ### `collections`
 
 Restricts AI read and write proposals to enabled collection slugs. If omitted, all non-internal Payload collections are available.
@@ -124,6 +155,38 @@ payloadAiPlugin({
 
 `read` controls schema/context access, document search, and mentions. `create`, `update`, and `delete` control AI action proposals and server-side apply permissions.
 
+### `media`
+
+Enables media uploads from the AI assistant. Uploaded files are created through the configured Payload upload collection and then passed to the chat endpoint as media attachments.
+
+```ts
+payloadAiPlugin({
+  collections: {
+    media: {
+      read: true,
+      update: true,
+    },
+    posts: true,
+  },
+  media: {
+    enabled: true,
+    collectionSlug: "media",
+    acceptedMimeTypes: ["image/*"],
+    maxFileSize: 10 * 1024 * 1024,
+  },
+})
+```
+
+`collectionSlug` defaults to `"media"`. The target collection must be configured with Payload `upload` support.
+
+`acceptedMimeTypes` accepts exact MIME types such as `"image/png"` and wildcard groups such as `"image/*"`. If omitted, all file types accepted by the upload collection can be sent to the endpoint.
+
+`maxFileSize` is checked before creating the upload document. The value is in bytes.
+
+If you want the AI to use uploaded files in other documents, enable `read` on the media collection so the chat endpoint can validate and inspect the uploaded media document. If the media collection has editable fields such as `alt`, `caption`, or `credit` and you want the AI to fill them, also enable `update` for that collection.
+
+Upload references in AI proposals are restricted to the uploaded attachments for the current request. This prevents the model from inventing arbitrary media IDs for upload fields.
+
 ### `models`
 
 Overrides the model list shown in the admin UI and the default model per provider.
@@ -138,6 +201,27 @@ OpenRouter includes these built-in model options:
 - `anthropic/claude-3.5-sonnet`
 - `google/gemini-2.0-flash-001`
 
+### `providers`
+
+Enables centrally managed provider profiles. Each profile supports:
+
+- `id`: unique provider profile identifier
+- `label`: provider group label shown in the model select
+- `provider`: SDK adapter (`openai`, `openrouter`, `claude`, `mistral`, or `google`)
+- `models`: allowed model list
+- `defaultModel`: optional default; otherwise the first configured model is used
+- `baseURL`: optional custom provider URL
+- `apiKey`: optional server-side API key
+
+When at least one profile is configured:
+
+- `aiProvider` and `aiApiKey` are not added to the admin user collection.
+- Models from every configured profile are displayed in provider groups.
+- The chat endpoint validates both provider IDs and model IDs against this configuration.
+- User-level provider and API key values are ignored.
+
+`apiKey` and `baseURL` remain server-side and are not included in Payload's public admin configuration. Custom endpoints must implement the protocol expected by their selected SDK adapter. For Ollama, vLLM, and similar APIs, use the `openai` adapter with an OpenAI-compatible `/v1` endpoint.
+
 ### `maxOutputTokens`
 
 Controls the maximum number of output tokens the chat endpoint may generate per request. If omitted, the plugin uses `700`.
@@ -148,6 +232,24 @@ payloadAiPlugin({
 })
 ```
 
+### `maxTokenUsage`
+
+Limits total AI tokens across rolling 24-hour and 7-day windows.
+
+```ts
+payloadAiPlugin({
+  maxTokenUsage: {
+    type: "user",
+    perDay: 50_000,
+    perWeek: 250_000,
+  },
+})
+```
+
+Use `type: "user"` to enforce separate budgets per authenticated user, or `type: "site"` to share one budget across the entire Payload installation. `perDay` and `perWeek` are optional individually, but at least one must be configured.
+
+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.
+
 ### `allowUserApiKeys`
 
 Controls whether the plugin adds an `aiApiKey` field to the admin user collection.
@@ -160,6 +262,8 @@ payloadAiPlugin({
 
 When disabled, users can still select an AI provider, but API keys must come from environment variables.
 
+This option only applies when `providers` is not configured. Managed provider mode never adds user-level AI settings.
+
 ### `disabled`
 
 Disables endpoint and UI registration while keeping the plugin call in your config.
@@ -171,8 +275,9 @@ The package lazy-loads provider SDKs at runtime. If a user selects `claude`, `go
 
 API key priority is:
 
-1. account-level API key, unless `allowUserApiKeys: false`
-2. provider environment variables
+1. managed provider `apiKey`, when `providers` is configured
+2. account-level API key, unless `allowUserApiKeys: false`
+3. provider environment variables
 
 - `OPENAI_API_KEY`, `OPENAI_MODEL`
 - `OPENROUTER_API_KEY`, `OPENROUTER_MODEL`

package/dist/ai/providerOptions.d.ts

@@ -1,4 +1,4 @@
-type AIProviderModelOption = {
+export type AIProviderModelOption = {
     label: string;
     value: string;
 };
@@ -71,6 +71,26 @@ declare const aiProviderModels: {
 };
 export type AIProvider = keyof typeof aiProviderModels;
 type AIProviderModels = Record<AIProvider, AIProviderModelOption[]>;
+export type AIProviderConfig = {
+    apiKey?: string;
+    baseURL?: string;
+    defaultModel?: string;
+    id: string;
+    label: string;
+    models: AIProviderModelOption[];
+    provider: AIProvider;
+};
+export type AIProviderProfile = {
+    defaultModel: string;
+    id: string;
+    label: string;
+    models: AIProviderModelOption[];
+    provider: AIProvider;
+};
+export type ResolvedAIProviderConfig = AIProviderProfile & {
+    apiKey?: string;
+    baseURL?: string;
+};
 export declare const aiProviders: {
     label: string;
     value: AIProvider;
@@ -85,4 +105,7 @@ export declare const getResolvedAIModelConfig: (modelConfig?: AIModelConfig) =>
     providers: AIProviderModels;
 };
 export declare const isAIProvider: (provider: string) => provider is AIProvider;
+export declare const getLegacyAIProviderProfiles: (modelConfig?: AIModelConfig) => AIProviderProfile[];
+export declare const resolveAIProviderConfigs: (providers?: AIProviderConfig[]) => ResolvedAIProviderConfig[];
+export declare const toClientAIProviderProfiles: (providers: ResolvedAIProviderConfig[]) => AIProviderProfile[];
 export {};

package/dist/ai/providerOptions.js

@@ -144,3 +144,84 @@ export const getResolvedAIModelConfig = (modelConfig)=>{
     };
 };
 export const isAIProvider = (provider)=>provider in aiProviderModels;
+export const getLegacyAIProviderProfiles = (modelConfig)=>{
+    const resolvedModels = getResolvedAIModelConfig(modelConfig);
+    return aiProviders.map(({ label, value })=>({
+            defaultModel: resolvedModels.defaults[value],
+            id: value,
+            label,
+            models: resolvedModels.providers[value],
+            provider: value
+        }));
+};
+export const resolveAIProviderConfigs = (providers)=>{
+    if (!providers?.length) return [];
+    const providerIDs = new Set();
+    return providers.map((providerConfig, index)=>{
+        const path = `providers[${index}]`;
+        const id = providerConfig.id.trim();
+        const label = providerConfig.label.trim();
+        if (!id || !/^[a-z0-9][a-z0-9_-]*$/i.test(id)) {
+            throw new Error(`${path}.id must contain only letters, numbers, hyphens, or underscores.`);
+        }
+        if (providerIDs.has(id)) throw new Error(`Duplicate AI provider id: ${id}`);
+        providerIDs.add(id);
+        if (!label) throw new Error(`${path}.label is required.`);
+        if (!isAIProvider(providerConfig.provider)) {
+            throw new Error(`${path}.provider is unsupported: ${String(providerConfig.provider)}`);
+        }
+        if (!providerConfig.models.length) throw new Error(`${path}.models must contain at least one model.`);
+        const modelValues = new Set();
+        const models = providerConfig.models.map((model, modelIndex)=>{
+            const modelPath = `${path}.models[${modelIndex}]`;
+            const modelLabel = model.label.trim();
+            const value = model.value.trim();
+            if (!modelLabel) throw new Error(`${modelPath}.label is required.`);
+            if (!value) throw new Error(`${modelPath}.value is required.`);
+            if (modelValues.has(value)) throw new Error(`Duplicate model value "${value}" in AI provider "${id}".`);
+            modelValues.add(value);
+            return {
+                label: modelLabel,
+                value
+            };
+        });
+        const defaultModel = providerConfig.defaultModel?.trim() || models[0].value;
+        if (!modelValues.has(defaultModel)) {
+            throw new Error(`${path}.defaultModel must match a configured model value.`);
+        }
+        if (providerConfig.baseURL) {
+            let parsedURL;
+            try {
+                parsedURL = new URL(providerConfig.baseURL);
+            } catch  {
+                throw new Error(`${path}.baseURL must be a valid URL.`);
+            }
+            if (![
+                "http:",
+                "https:"
+            ].includes(parsedURL.protocol)) {
+                throw new Error(`${path}.baseURL must use http or https.`);
+            }
+        }
+        return {
+            ...providerConfig.apiKey ? {
+                apiKey: providerConfig.apiKey
+            } : {},
+            ...providerConfig.baseURL ? {
+                baseURL: providerConfig.baseURL
+            } : {},
+            defaultModel,
+            id,
+            label,
+            models,
+            provider: providerConfig.provider
+        };
+    });
+};
+export const toClientAIProviderProfiles = (providers)=>providers.map(({ defaultModel, id, label, models, provider })=>({
+            defaultModel,
+            id,
+            label,
+            models,
+            provider
+        }));

package/dist/ai/providerRuntime.d.ts

@@ -8,6 +8,7 @@ type ProviderConfig = {
 };
 type ModelConfig = {
     apiKey: string;
+    baseURL?: string;
     model: string;
     provider: AIProvider;
 };
@@ -15,5 +16,5 @@ export declare const getProviderConfig: ({ apiKey, defaultModels, model, provide
     apiKey: string | undefined;
     modelID: string;
 };
-export declare const getModel: ({ apiKey, model, provider }: ModelConfig) => Promise<LanguageModel>;
+export declare const getModel: ({ apiKey, baseURL, model, provider }: ModelConfig) => Promise<LanguageModel>;
 export {};

package/dist/ai/providerRuntime.js

@@ -33,9 +33,12 @@ export const getProviderConfig = ({ apiKey, defaultModels, model, provider })=>{
 const getMissingProviderDependencyError = (packageName, provider)=>{
     return new Error(`Missing optional dependency ${packageName}. Install it to use the ${provider} provider.`);
 };
-export const getModel = async ({ apiKey, model, provider })=>{
+export const getModel = async ({ apiKey, baseURL, model, provider })=>{
     const providerOptions = {
-        apiKey
+        apiKey,
+        ...baseURL ? {
+            baseURL
+        } : {}
     };
     if (provider === "claude") {
         try {

package/dist/ai/tokenUsage.d.ts

@@ -0,0 +1,38 @@
+import type { PayloadHandler } from "payload";
+export type MaxTokenUsageOptions = {
+    perDay?: number;
+    perWeek?: number;
+    type: "site" | "user";
+};
+export type ResolvedMaxTokenUsageOptions = {
+    perDay?: number;
+    perWeek?: number;
+    type: "site" | "user";
+};
+export type TokenUsageData = {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+};
+type TokenUsageLimit = {
+    limit: number;
+    period: "day" | "week";
+    used: number;
+};
+export declare const tokenUsageCollectionSlug = "payload-ai-usage";
+export declare const resolveMaxTokenUsageOptions: (options?: MaxTokenUsageOptions) => ResolvedMaxTokenUsageOptions | undefined;
+export declare const getExceededTokenUsageLimit: ({ maxTokenUsage, now, req, userID, }: {
+    maxTokenUsage?: ResolvedMaxTokenUsageOptions;
+    now?: Date;
+    req: Parameters<PayloadHandler>[0];
+    userID: number | string;
+}) => Promise<TokenUsageLimit | null>;
+export declare const recordTokenUsage: ({ model, now, provider, req, usage, userID, }: {
+    model: string;
+    now?: Date;
+    provider: string;
+    req: Parameters<PayloadHandler>[0];
+    usage: TokenUsageData;
+    userID: number | string;
+}) => Promise<void>;
+export {};

package/dist/ai/tokenUsage.js

@@ -0,0 +1,106 @@
+export const tokenUsageCollectionSlug = "payload-ai-usage";
+const dayInMilliseconds = 24 * 60 * 60 * 1000;
+const weekInMilliseconds = 7 * dayInMilliseconds;
+const resolvePositiveInteger = (value, path)=>{
+    if (value === undefined) return undefined;
+    if (!Number.isFinite(value) || value <= 0) throw new Error(`${path} must be a positive number.`);
+    return Math.floor(value);
+};
+export const resolveMaxTokenUsageOptions = (options)=>{
+    if (!options) return undefined;
+    if (![
+        "site",
+        "user"
+    ].includes(options.type)) throw new Error('maxTokenUsage.type must be either "user" or "site".');
+    const perDay = resolvePositiveInteger(options.perDay, "maxTokenUsage.perDay");
+    const perWeek = resolvePositiveInteger(options.perWeek, "maxTokenUsage.perWeek");
+    if (!perDay && !perWeek) throw new Error("maxTokenUsage must configure perDay, perWeek, or both.");
+    return {
+        ...perDay ? {
+            perDay
+        } : {},
+        ...perWeek ? {
+            perWeek
+        } : {},
+        type: options.type
+    };
+};
+const normalizeTokenCount = (value)=>typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+const getTokenCount = (usage)=>typeof usage.totalTokens === "number" ? normalizeTokenCount(usage.totalTokens) : normalizeTokenCount(usage.inputTokens) + normalizeTokenCount(usage.outputTokens);
+export const getExceededTokenUsageLimit = async ({ maxTokenUsage, now = new Date(), req, userID })=>{
+    if (!maxTokenUsage) return null;
+    const dayStart = new Date(now.getTime() - dayInMilliseconds);
+    const weekStart = new Date(now.getTime() - weekInMilliseconds);
+    const queryStart = maxTokenUsage.perWeek ? weekStart : dayStart;
+    let page = 1;
+    let usagePerDay = 0;
+    let usagePerWeek = 0;
+    while(true){
+        const result = await req.payload.find({
+            collection: tokenUsageCollectionSlug,
+            depth: 0,
+            limit: 500,
+            overrideAccess: true,
+            page,
+            req,
+            where: {
+                and: [
+                    {
+                        recordedAt: {
+                            greater_than_equal: queryStart.toISOString()
+                        }
+                    },
+                    ...maxTokenUsage.type === "user" ? [
+                        {
+                            userID: {
+                                equals: String(userID)
+                            }
+                        }
+                    ] : []
+                ]
+            }
+        });
+        for (const document of result.docs || []){
+            const tokenCount = getTokenCount(document);
+            usagePerWeek += tokenCount;
+            if (document.recordedAt && new Date(document.recordedAt).getTime() >= dayStart.getTime()) {
+                usagePerDay += tokenCount;
+            }
+        }
+        if (!result.hasNextPage || !result.nextPage) break;
+        page = result.nextPage;
+    }
+    if (maxTokenUsage.perDay && usagePerDay >= maxTokenUsage.perDay) {
+        return {
+            limit: maxTokenUsage.perDay,
+            period: "day",
+            used: usagePerDay
+        };
+    }
+    if (maxTokenUsage.perWeek && usagePerWeek >= maxTokenUsage.perWeek) {
+        return {
+            limit: maxTokenUsage.perWeek,
+            period: "week",
+            used: usagePerWeek
+        };
+    }
+    return null;
+};
+export const recordTokenUsage = async ({ model, now = new Date(), provider, req, usage, userID })=>{
+    const totalTokens = getTokenCount(usage);
+    if (!totalTokens) return;
+    await req.payload.create({
+        collection: tokenUsageCollectionSlug,
+        data: {
+            inputTokens: typeof usage.inputTokens === "number" ? normalizeTokenCount(usage.inputTokens) : undefined,
+            model,
+            outputTokens: typeof usage.outputTokens === "number" ? normalizeTokenCount(usage.outputTokens) : undefined,
+            provider,
+            recordedAt: now.toISOString(),
+            totalTokens,
+            userID: String(userID)
+        },
+        overrideAccess: true,
+        req
+    });
+};

package/dist/components/Icons.d.ts

@@ -4,11 +4,4 @@ export declare function OpenaiIcon(props: SVGProps<SVGSVGElement>): import("reac
 export declare function ClaudeIcon(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
 export declare function GoogleGeminiIcon(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
 export declare function OpenrouterIcon(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
-export declare function FileDiff(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
-export declare function Send(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
-export declare function Apply(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
-export declare function Reject(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
-export declare function Collection(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
-export declare function Document(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
-export declare function Global(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
-export declare function Block(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
+export declare function PaperclipIcon(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;