index.ts

import { AdminForthPlugin, Filters, ActionCheckSource, interpretResource } from "adminforth";
import type { IAdminForth, IHttpServer, AdminForthPageInjectionDeclarationFull, AdminForthResource, AdminUser, HttpExtra, AdminForthDataTypes, AdminForthResourceColumn } from "adminforth";
import { suggestIfTypo } from "adminforth";
import type { PluginOptions, AdapterForRecord, AdapterResolver } from './types.js';
import Handlebars from 'handlebars';
import { RateLimiter } from "adminforth";
import { randomUUID } from "crypto";
import { z } from "zod";

const getRecordsBodySchema = z.object({
  record: z.array(z.any()).nullish(),
}).strict();

const getImagesBodySchema = z.object({
  recordId: z.union([z.string(), z.number()]),
}).strict();

const getOldDataBodySchema = z.object({
  recordId: z.union([z.string(), z.number()]).nullish(),
}).strict();

const updateFieldsBodySchema = z.object({
  selectedIds: z.array(z.any()).nullish(),
  fields: z.any(),
}).strict();

const getImageGenerationPromptsBodySchema = z.object({
  recordId: z.union([z.string(), z.number()]),
  customPrompt: z.string().nullish(),
}).strict();

const createJobBodySchema = z.object({
  actionType: z.string().nullish(),
  recordId: z.union([z.string(), z.number()]).nullish(),
  customPrompt: z.string().nullish(),
  filterFilledFields: z.boolean().nullish(),
  sessionIds: z.array(z.string()).nullish(),
  prompt: z.string().nullish(),
  fieldName: z.string().nullish(),
  fieldToRegenerate: z.string().nullish(),
  action: z.string().nullish(),
}).strict();

const jobStatusBodySchema = z.object({
  jobId: z.string(),
}).strict();

const updateRateLimitsBodySchema = z.object({
  actionType: z.string().nullish(),
}).strict();

const getFilteredIdsBodySchema = z.object({
  filters: z.any(),
}).passthrough();

type AccessCheckContext = {
  adminUser: AdminUser;
  resource: AdminForthResource;
  meta: any;
  source: ActionCheckSource;
  adminforth: IAdminForth;
};

async function resolveBoolOrFn(val: any, ctx: AccessCheckContext): Promise<boolean> {
  if (typeof val === 'function') {
    return !!(await val(ctx));
  }
  return !!val;
}

function valueIsUnchanged(newValue: any, oldValue: any): boolean {
  if (newValue === oldValue) {
    return true;
  }
  if (newValue === null || newValue === undefined || oldValue === null || oldValue === undefined) {
    return false;
  }
  if (typeof newValue === 'object' || typeof oldValue === 'object') {
    try {
      return JSON.stringify(newValue) === JSON.stringify(oldValue);
    } catch {
      return false;
    }
  }
  return String(newValue) === String(oldValue);
}
const STUB_MODE = false;
const jobs = new Map(); 
export default class  BulkAiFlowPlugin extends AdminForthPlugin {
  options: PluginOptions;
  primaryKeyColumn!: AdminForthResourceColumn;
  totalCalls: number;
  totalDuration: number;
  rateLimiters: Record<string, RateLimiter> = {};
  sessionIds: Set<string> = new Set();

  constructor(options: PluginOptions) {
    super(options, import.meta.url);
    this.options = options;

    // for calculating average time
    this.totalCalls = 0;
    this.totalDuration = 0;

    // for rate limiting
    this.sessionIds = new Set();
  }

  /**
   * Compiles Handlebars templates from `source`.
   *
   * `record` is the raw row and is always what `provideAdditionalContextForRecord` sees, but the
   * templates themselves are rendered against `record` only when they come from `PluginOptions`:
   * those are written by the app author and may reference any column. Templates which arrived in
   * the request body are rendered against the record as the caller is allowed to read it, so a
   * hand-written `{{column}}` cannot pull a backendOnly column out of the row.
   */
  private async compileTemplates<T extends Record<string, any>>(
    source: T,
    { record, ctx, clientSupplied }: { record: any, ctx: AccessCheckContext, clientSupplied: boolean },
    valueSelector: (value: T[keyof T]) => string
  ): Promise<Record<string, string>> {
    let templateContext = clientSupplied ? await this.stripBackendOnlyColumns(record, ctx) : record;
    if (this.options.provideAdditionalContextForRecord) {
      const additionalFields = await this.options.provideAdditionalContextForRecord({ record, adminUser: ctx.adminUser, resource: this.resourceConfig });
      templateContext = { ...templateContext, ...additionalFields };
    }
    const compiled: Record<string, string> = {};
    for (const [key, value] of Object.entries(source)) {
      const templateStr = valueSelector(value);
      try {
        const tpl = Handlebars.compile(templateStr);
        compiled[key] = tpl(templateContext);
      } catch {
        compiled[key] = templateStr;
      }
    }
    return compiled;
  }

  private async compileOutputFieldsTemplates(record: any, ctx: AccessCheckContext, customPrompt? : string | null, clientSupplied: boolean = !!customPrompt) {
    return await this.compileTemplates(customPrompt ? JSON.parse(customPrompt) :this.options.fillFieldsFromImages, { record, ctx, clientSupplied }, v => String(v));
  }

  private async compileOutputFieldsTemplatesNoImage(record: any, ctx: AccessCheckContext, customPrompt? : string | null, clientSupplied: boolean = !!customPrompt) {
    return await this.compileTemplates(customPrompt ? JSON.parse(customPrompt) : this.options.fillPlainFields, { record, ctx, clientSupplied }, v => String(v));
  }

  private async compileGenerationFieldTemplates(record: any, ctx: AccessCheckContext, customPrompt? : string | null, clientSupplied: boolean = !!customPrompt) {
    return await this.compileTemplates(customPrompt ? JSON.parse(customPrompt) : this.options.generateImages, { record, ctx, clientSupplied }, v => String(customPrompt ? v : v.prompt));
  }

  private removeFromPromptFilledFields(compiledOutputFields: Record<string, string>, record: Record<string, any>): Record<string, string> {
    const newCompiledOutputFields: Record<string, string> = {};
    for (const [key, value] of Object.entries(record)) {
      if (compiledOutputFields[key]) {
        if (value !== null && value !== undefined && value !== '') {
          continue;
        }
        newCompiledOutputFields[key] = compiledOutputFields[key];
      }
    }
    return newCompiledOutputFields;
  }

  private async checkRateLimit(field: string, fieldNameRateLimit: string | undefined, headers: Record<string, string | string[] | undefined>): Promise<void | { error?: string; }> {
    if (fieldNameRateLimit) {
      // rate limit
      // const { error } = RateLimiter.checkRateLimit(
      //   field,
      //   fieldNameRateLimit,
      //   this.adminforth.auth.getClientIp(headers),
      // );
      if (!this.rateLimiters[field]) {
        this.rateLimiters[field] = new RateLimiter(fieldNameRateLimit);
      }
      if (!await this.rateLimiters[field].consume(`${field}-${this.adminforth.auth.getClientIp(headers)}`)) {
        return { error: "Rate limit exceeded" };
      }
    }
  }

  /**
   * Calls the adapter function of the app for the record, its failure fails the job in `create-job`.
   */
  private async resolveAdapter<T>(option: AdapterForRecord<T>, record: any, adminUser: AdminUser): Promise<T> {
    if (typeof option !== 'function') {
      return option;
    }
    try {
      return await (option as AdapterResolver<T>)({ record, adminUser });
    } catch (e: any) {
      throw new Error(`Failed to select the AI adapter: ${e.message}`);
    }
  }

  private resolveVisionAdapter(record: any, adminUser: AdminUser) {
    return this.resolveAdapter(this.options.visionAdapter!, record, adminUser);
  }

  private resolveTextCompleteAdapter(record: any, adminUser: AdminUser) {
    return this.resolveAdapter(this.options.textCompleteAdapter!, record, adminUser);
  }

  private getImageFieldOptions(fieldName: string) {
    return this.options.generateImages![fieldName];
  }

  private resolveImageGenerationAdapter(fieldName: string, record: any, adminUser: AdminUser) {
    return this.resolveAdapter((this.getImageFieldOptions(fieldName).adapter ?? this.options.imageGenerationAdapter)!, record, adminUser);
  }

  private getAttachmentFiles(record: any) {
    return this.options.attachFiles!({ record });
  }

  private getPromptForImageAnalysis(compiledOutputFields: Record<string, string>) {
    const prompt = `Analyze the following image(s) and return a single JSON in format like: {'param1': 'value1', 'param2': 'value2'}. 
      Do NOT return array of objects. Do NOT include any Markdown, code blocks, explanations, or extra text. Only return valid JSON. 
      Only return valid JSON. Do NOT wrap in \`\`\` or \`\`\`json. Do not add any extra text. Do not return prompt in response 
      Each object must contain the following fields: ${JSON.stringify(compiledOutputFields)} Use the exact field names. If it's number field - return only number.
      Image URLs:`;
    return prompt;
  }

  private getPromptForPlainFields(compiledOutputFields: Record<string, string>){
    const prompt = `Generate the values of fields in object by using next prompts (key is field name, value is prompt): 
      ${JSON.stringify(compiledOutputFields)} In output object use the same field names (keys) as in input.
      Return a single valid passable JSON object in format like: {"meta_title": "generated_value"}.
      Do NOT include any Markdown, code blocks, explanations, or extra text. Only return valid JSON. 
      Do NOT wrap in \`\`\` or \`\`\`json. Do not add any extra text. Do not return prompt in response`;
    return prompt;
  }

  private async analyze_image(jobId: string, record: any, ctx: AccessCheckContext, headers: Record<string, string | string[] | undefined>, customPrompt? : string | null, filterFilledFields: boolean | null = true) {
    // TODO: need to do correct check of rate limit
    // if (this.options.rateLimits && this.options.rateLimits.fillFieldsFromImages && await this.checkRateLimit("fillFieldsFromImages" ,this.options.rateLimits.fillFieldsFromImages, headers)) {
    //   jobs.set(jobId, { status: 'failed', error: "Rate limit exceeded" });
    //   return { error: "Rate limit exceeded" };
    // }
    let isError = false;

    //recieve image URLs to analyze
    const attachmentFiles = await this.getAttachmentFiles(record);
    if (STUB_MODE) {
      await new Promise((resolve) => setTimeout(resolve, Math.floor(Math.random() * 8000) + 1000));
      const fakeError = Math.random() < 0.5; // 50% chance of error
      if (attachmentFiles.length === 0) {
        jobs.set(jobId, { status: 'failed', error: 'No source images found' });
      } else if (!fakeError) {
        jobs.set(jobId, { status: 'completed', result: {} });
      } else {
        jobs.set(jobId, { status: 'failed', error: 'AI provider refused to analyze images' });
      }
      return {};
    } else if (attachmentFiles.length !== 0) {
      try {
        for (const fileUrl of attachmentFiles) {
          new URL(fileUrl);
        }
      } catch (e) {
        jobs.set(jobId, { status: 'failed', error: 'One of the image URLs is not valid' });
        return { ok: false, error: 'One of the image URLs is not valid' };
      }
      //create prompt for OpenAI
      const compiledOutputFields = await this.compileOutputFieldsTemplates(record, ctx, customPrompt);
      const filteredCompiledOutputFields = filterFilledFields ? this.removeFromPromptFilledFields(compiledOutputFields, record) : compiledOutputFields;
      
      if (Object.keys(filteredCompiledOutputFields).length === 0) {
        jobs.set(jobId, { status: 'completed', result: {} });
        return { ok: true };
      }
        
      const prompt = this.getPromptForImageAnalysis(filteredCompiledOutputFields);

      const visionAdapter = await this.resolveVisionAdapter(record, ctx.adminUser);
      //send prompt to OpenAI and get response
      let chatResponse;
      try {
        chatResponse = await visionAdapter.generate({ prompt, inputFileUrls: attachmentFiles });
      } catch (e) {
        isError = true;
        jobs.set(jobId, { status: 'failed', error: 'AI provider refused to analyze images' });
        return { ok: false, error: 'AI provider refused to analyze images' };
      }
      if (!isError) {
        const { response: textOutput, error } = chatResponse;
        if (error) {
          jobs.set(jobId, { status: 'failed', error: `ERROR: ${error}` });
          return { ok: false, error: `ERROR: ${error}` };
        }

        //parse response and update record
        let resData;
        try {
          resData = JSON.parse(textOutput);
        } catch (e) {
          jobs.set(jobId, { status: 'failed', error: 'AI response is not valid JSON. Probably attached invalid image URL', aiResponse: textOutput });
          return { ok: false, error: 'AI response is not valid JSON. Probably attached invalid image URL', aiResponse: textOutput };
        }
        const result = resData;
        jobs.set(jobId, { status: 'completed', result });
        return { ok: true };
      }
    } else {
      jobs.set(jobId, { status: 'failed', error: "No source images found" });
      return { ok: false, error: "No source images found" };
    }

  }

  private async analyzeNoImages(jobId: string, record: any, ctx: AccessCheckContext, headers: Record<string, string | string[] | undefined>, customPrompt? : string | null, filterFilledFields: boolean | null = true) {
    // TODO: need to do correct check of rate limit
    // if (this.options.rateLimits && this.options.rateLimits.fillPlainFields && await this.checkRateLimit("fillPlainFields" ,this.options.rateLimits.fillPlainFields, headers)) {
    //   jobs.set(jobId, { status: 'failed', error: "Rate limit exceeded" });
    //   return { error: "Rate limit exceeded" };
    // }
    let isError = false;
    if (STUB_MODE) {
      const fakeError = Math.random() < 0.005; // 0.05% chance of error
      // await new Promise((resolve) => setTimeout(resolve, Math.floor(Math.random() * 20000) + 1000));
      if (fakeError) {
        jobs.set(jobId, { status: 'failed', error: `ERROR: test error` });
        return { ok: false, error: 'test error' };
      } else {
        jobs.set(jobId, { status: 'completed', result: {description: 'test description', price: 99999999, engine_power: 999} });
        return { ok: true };
      }
    } else {
      const compiledOutputFields = await this.compileOutputFieldsTemplatesNoImage(record, ctx, customPrompt);

      const filteredCompiledOutputFields = filterFilledFields ? this.removeFromPromptFilledFields(compiledOutputFields, record) : compiledOutputFields;

      if (Object.keys(filteredCompiledOutputFields).length === 0) {
        jobs.set(jobId, { status: 'completed', result: {} });
        return { ok: true };
      }
      const prompt = this.getPromptForPlainFields(filteredCompiledOutputFields);
      //send prompt to OpenAI and get response
      const numberOfTokens = this.options.fillPlainFieldsMaxTokens ? this.options.fillPlainFieldsMaxTokens : 1000;
      const textCompleteAdapter = await this.resolveTextCompleteAdapter(record, ctx.adminUser);
      let resp: any;
      try {
        const { content: chatResponse, error: topLevelError } = await textCompleteAdapter.complete({
          content: prompt,
          maxTokens: numberOfTokens,
        });
        // resp = (chatResponse as any).response;
        if (topLevelError || resp?.error) {
          isError = true;
          jobs.set(jobId, { status: 'failed', error: `ERROR: ${JSON.stringify(topLevelError)}` });
          return { ok: false, error: `ERROR: ${JSON.stringify(topLevelError)}` };
        }
        resp = chatResponse
      } catch (e) {
        isError = true;
        jobs.set(jobId, { status: 'failed', error: `AI provider refused to fill fields: ${e}` });
        return { ok: false, error: `AI provider refused to fill fields: ${e}` };
      }
      let resData;
        try {
          resData = JSON.parse(resp);
        } catch (e) {
          jobs.set(jobId, { status: 'failed', error: 'AI response is not valid JSON', aiResponse: resp });
          return { ok: false, error: 'AI response is not valid JSON', aiResponse: resp };
        }
      const result = resData;
      jobs.set(jobId, { status: 'completed', result });
      return { ok: true };
    }
  }

  private async initialImageGenerate(jobId: string, record: any, ctx: AccessCheckContext, headers: Record<string, string | string[] | undefined>, customPrompt? : string | null, filterFilledFields: boolean | null = true) {
    // TODO: need to do correct check of rate limit
    // if (this.options.rateLimits && this.options.rateLimits.generateImages && await this.checkRateLimit("generateImages" ,this.options.rateLimits.generateImages, headers)) {
    //   jobs.set(jobId, { status: 'failed', error: "Rate limit exceeded" });
    //   return { error: "Rate limit exceeded" };
    // }
    let isError = false;
    const start = +new Date();
    let attachmentFiles: string[];
    if(!this.options.attachFiles){
      attachmentFiles = [];
    } else {
      attachmentFiles = await this.options.attachFiles({ record });
      try {
        for (const fileUrl of attachmentFiles) {
          new URL(fileUrl);
        }
      } catch (e) {
        jobs.set(jobId, { status: 'failed', error: 'One of the image URLs is not valid' });
        return { ok: false, error: 'One of the image URLs is not valid' };
      }
    }
    const fieldTasks = Object.keys(this.options?.generateImages || {}).map(async (key) => {
      if ( record[key] && filterFilledFields ) {
        const plugin = this.adminforth.activatedPlugins.find(p => 
          p.resourceConfig!.resourceId === this.resourceConfig.resourceId &&
          p.pluginOptions.pathColumnName === key
        );
        const image_url = await plugin!.pluginOptions.storageAdapter.getDownloadUrl(record[key]);
        return { 
          key,
          images: [image_url], 
          meta: {
            skippedToNotOverwrite: true,
            originalImage: image_url,
          } 
        };
      }
      const prompt = (await this.compileGenerationFieldTemplates(record, ctx, customPrompt))[key];
      let images;
        if (this.options.attachFiles && attachmentFiles.length === 0) {
          isError = true;
          jobs.set(jobId, { status: 'failed', error: "No source images found" });
          return { key, images: [] };
        } else {
          if (STUB_MODE) {
            await new Promise((resolve) => setTimeout(resolve, Math.floor(Math.random() * 20000) + 1000));
            const fakeError = Math.random() < 0.5; // 50% chance of error
            if (!fakeError) {
              images = `https://pic.re/image`;
            } else {
              isError = true;
              jobs.set(jobId, { status: 'failed', error: 'AI provider refused to generate image' });
            }
          } else {
            const generationAdapter = await this.resolveImageGenerationAdapter(key, record, ctx.adminUser);
            let resp;
            try {
              resp = await generationAdapter.generate(
                {
                  prompt,
                  inputFiles: attachmentFiles,
                  n: 1,
                  size: this.getImageFieldOptions(key).outputSize,
                }
              )
              if (resp.error) {
                isError = true;
                jobs.set(jobId, { status: 'failed', error: `AI provider refused to generate image: ${JSON.stringify(resp.error)}` });
                return { key, images: [] };
              }
            } catch (e) {
              jobs.set(jobId, { status: 'failed', error: "AI provider refused to generate image" });
              isError = true;
              return { key, images: [] };
            }
            images = resp.imageURLs![0];
          }
        return { key, images };
      }
    });

    const fieldResults = await Promise.all(fieldTasks);
    const recordResult: Record<string, any> = {};
    const recordMeta: Record<string, any> = {};

    fieldResults.forEach(({ key, images, meta }) => {
      recordResult[key] = images;
      if (meta) {
        recordMeta[`${key}_meta`] = meta;
      }
    });

    const result = recordResult;
    
    if (!isError) {
      this.totalCalls++;
      this.totalDuration += (+new Date() - start) / 1000;
      jobs.set(jobId, { status: 'completed', result, recordMeta });
      return { ok: true }
    } else {
      return { ok: false, error: 'Error during image generation' };
    }
  }
   
  private async regenerateImage(jobId: string, record: any, ctx: AccessCheckContext, fieldName: string, prompt: string, headers: Record<string, string | string[] | undefined>) {
    let isError = false;
    // TODO: need to do correct check of rate limit
    // if (await this.checkRateLimit(fieldName, this.options.generateImages[fieldName].rateLimit, headers)) {
    //   jobs.set(jobId, { status: 'failed', error: "Rate limit exceeded" });
    //   return { error: "Rate limit exceeded" };
    // }
    const start = +new Date();
    let attachmentFiles: string[];
      if(!this.options.attachFiles){
        attachmentFiles = [];
      } else {
        attachmentFiles = await this.options.attachFiles({ record });
      }
    const generationAdapter = await this.resolveImageGenerationAdapter(fieldName, record, ctx.adminUser);
    const images = await Promise.all(
      (new Array(this.getImageFieldOptions(fieldName).countToGenerate)).fill(0).map(async () => {
        if (this.options.attachFiles && attachmentFiles.length === 0) {
          isError = true;
          jobs.set(jobId, { status: 'failed', error: "No source images found" });
          return null;
        }
        if (STUB_MODE) {
          await new Promise((resolve) => setTimeout(resolve, 2000));
          jobs.set(jobId, { status: 'completed', result: {} });
          return `https://pic.re/image`;
        }

        let resp;
        try {
          resp = await generationAdapter.generate(
            {
              prompt,
              inputFiles: attachmentFiles,
              n: 1,
              size: this.getImageFieldOptions(fieldName).outputSize,
            }
          )
          if (resp.error) {
            isError = true;
            jobs.set(jobId, { status: 'failed', error: `AI provider refused to generate image: ${JSON.stringify(resp.error)}` });
            return [];
          }
        } catch (e) {
          jobs.set(jobId, { status: 'failed', error: "AI provider refused to generate image" });
          isError = true;
          return [];
        }
        return resp.imageURLs![0]
      })
    );

    if (!isError) {
      this.totalCalls++;
      this.totalDuration += (+new Date() - start) / 1000;
      jobs.set(jobId, { status: 'completed', result: { [fieldName]: images } });
      return { ok: true };
    } else {
      return { ok: false, error: 'Error during image generation' };
    }
  }

  private async regenerateCell(jobId: string, fieldToRegenerate: string | null | undefined, record: any, ctx: AccessCheckContext, actionType: string | null | undefined, prompt: string | null | undefined) {
    if (!fieldToRegenerate || !actionType ) {
      jobs.set(jobId, { status: 'failed', error: 'Missing parameters' });
      return;
    }
    // a prompt which arrived in the request body is client-authored even though it is wrapped into
    // `promptToPass` below, while the PluginOptions fallback is written by the app author
    const clientSupplied = !!prompt;
    if ( !prompt ) {
      if (actionType === 'analyze') {
        prompt = this.options.fillFieldsFromImages ? (this.options.fillFieldsFromImages as any)[fieldToRegenerate] : null;
      } else if (actionType === 'analyze_no_images') {
        prompt = this.options.fillPlainFields ? (this.options.fillPlainFields as any)[fieldToRegenerate] : null;
      }
    }
    let promptToPass = JSON.stringify({[fieldToRegenerate]: prompt});
    if (STUB_MODE) {
      await new Promise((resolve) => setTimeout(resolve, Math.floor(Math.random() * 20000) + 1000));
      // return { ok: true, result: {[fieldToRegenerate]: "stub value"} };
      jobs.set(jobId, { status: 'completed', result: {[fieldToRegenerate]: "stub value"} });
    } else {
      if ( actionType === 'analyze') {
        const compiledPropmt = await this.compileOutputFieldsTemplates(record, ctx, promptToPass, clientSupplied);
        const finalPrompt = this.getPromptForImageAnalysis(compiledPropmt);
        const attachmentFiles = await this.getAttachmentFiles(record);
        if (attachmentFiles.length === 0) {
          jobs.set(jobId, { status: 'failed', error: "No source images found" });
          return;
        }
        const visionAdapter = await this.resolveVisionAdapter(record, ctx.adminUser);
        let visionAdapterResponse;
        try {
          visionAdapterResponse = await visionAdapter.generate({ prompt: finalPrompt, inputFileUrls: attachmentFiles });
        } catch (e) {
          jobs.set(jobId, { status: 'failed', error: 'AI provider refused to analyze images' });
          return;
        }
        const { response: textOutput, error } = visionAdapterResponse;
        if (error) {
          jobs.set(jobId, { status: 'failed', error: `ERROR: ${error}` });
          return;
        }

        let resData;
        try {
          resData = JSON.parse(textOutput);
        } catch (e) {
          jobs.set(jobId, { status: 'failed', error: 'AI response is not valid JSON. Probably attached invalid image URL', aiResponse: textOutput });
          return;
        }
        jobs.set(jobId, { status: 'completed', result: resData });

      } else if ( actionType === 'analyze_no_images') {
        const compiledPropmt = await this.compileOutputFieldsTemplatesNoImage(record, ctx, promptToPass, clientSupplied);
        const finalPrompt = this.getPromptForPlainFields(compiledPropmt);
        const numberOfTokens = this.options.fillPlainFieldsMaxTokens ? this.options.fillPlainFieldsMaxTokens : 1000;
        const textCompleteAdapter = await this.resolveTextCompleteAdapter(record, ctx.adminUser);
        let resp;
        try {
          const { content: chatResponse, error: topLevelError } = await textCompleteAdapter.complete({
            content: finalPrompt,
            maxTokens: numberOfTokens,
          });
          if (topLevelError) {
            jobs.set(jobId, { status: 'failed', error: `ERROR: ${JSON.stringify(topLevelError)}` });
            return;
          }
          resp = chatResponse;
        } catch (e) {
          jobs.set(jobId, { status: 'failed', error: 'AI provider refused to analyze plain fields' });
          return;
        }
        let resData;
        try {
          resData = JSON.parse(resp!);
        } catch (e) {
          jobs.set(jobId, { status: 'failed', error: 'AI response is not valid JSON', aiResponse: resp });
          return;
        }
        jobs.set(jobId, { status: 'completed', result: resData });
      }
    }
  }

  async modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
    super.modifyResourceConfig(adminforth, resourceConfig);
    this.primaryKeyColumn = resourceConfig.columns.find((col) => col.primaryKey)!;

    //check if options names are provided
    const columns = this.resourceConfig.columns;
    let columnEnums = [];
    if (this.options.fillFieldsFromImages) {
      for (const [key, value] of Object.entries((this.options.fillFieldsFromImages ))) {
        const column = columns.find(c => c.name.toLowerCase() === key.toLowerCase());
        if (column && column.enum) {
          (this.options.fillFieldsFromImages as any)[key] = `${value} Select ${key} from the list (USE ONLY VALUE FIELD. USE ONLY VALUES FROM THIS LIST): ${JSON.stringify(column.enum)}`;
          columnEnums.push({
            name: key,
            enum: column.enum,
          });
        }
      }
    }

    if (this.options.fillPlainFields) {
      for (const [key, value] of Object.entries((this.options.fillPlainFields))) {
        const column = columns.find(c => c.name.toLowerCase() === key.toLowerCase());
        if (column && column.enum) {
          (this.options.fillPlainFields as any)[key] = `${value} Select ${key} from the list (USE ONLY VALUE FIELD. USE ONLY VALUES FROM THIS LIST): ${JSON.stringify(column.enum)}`;
          columnEnums.push({
            name: key,
            enum: column.enum,
          });
        }
      }
    }  

    const outputImageFields = [];
    if (this.options.generateImages) {
      for (const [key, value] of Object.entries(this.options.generateImages)) {
        outputImageFields.push(key);
      }
    }
    const outputPlainFields = [];
    if (this.options.fillPlainFields) {
      for (const [key, value] of Object.entries(this.options.fillPlainFields)) {
        outputPlainFields.push(key);
      }
    }
    const outputFieldsForAnalizeFromImages = [];
    if (this.options.fillFieldsFromImages) {
      for (const [key, value] of Object.entries(this.options.fillFieldsFromImages)) {
        outputFieldsForAnalizeFromImages.push(key);
      }
    }

    const outputImagesPluginInstanceIds: Record<string, string> = {};
    //check if Upload plugin is installed on all attachment fields
    if (this.options.generateImages) {
      for (const [key, value] of Object.entries(this.options.generateImages)) {
        const plugin = adminforth.activatedPlugins.find(p => 
          p.resourceConfig!.resourceId === this.resourceConfig.resourceId &&
          p.pluginOptions.pathColumnName === key
        );
        if (!plugin) {
          throw new Error(`Plugin for attachment field '${key}' not found in resource '${this.resourceConfig.resourceId}', please check if Upload Plugin is installed on the field ${key}`);
        }
        if (!plugin.pluginOptions.storageAdapter.objectCanBeAccesedPublicly()) {
          throw new Error(`Upload Plugin for attachment field '${key}' in resource '${this.resourceConfig.resourceId}' 
            uses adapter which is not configured to store objects in public way, so it will produce only signed private URLs which can not be used in HTML text of blog posts.
            Please configure adapter in such way that it will store objects publicly (e.g.  for S3 use 'public-read' ACL).  
          `);
        }
          outputImagesPluginInstanceIds[key] = plugin.pluginInstanceId;
      }
    }

    const outputFields = [
      ...outputFieldsForAnalizeFromImages,
      ...outputPlainFields,
      ...outputImageFields,
    ];

    // Map of column technical names to their display labels from resource config
    const columnLabels: Record<string, string> = Object.fromEntries(
      (this.resourceConfig.columns || []).map((c: any) => [c.name, c.label || c.name])
    );
    // the review dialog picks an editor for a generated value by the type of its column
    const columnTypes: Record<string, AdminForthDataTypes | undefined> = Object.fromEntries(
      this.resourceConfig.columns.filter((c) => outputFields.includes(c.name)).map((c) => [c.name, c.type])
    );
    // only the prompts go to the browser: an entry of generateImages may hold an adapter with its API key
    const imageGenerationPrompts: Record<string, string> = Object.fromEntries(
      Object.entries(this.options.generateImages || {}).map(([key, value]) => [key, value.prompt])
    );

    const pageInjection: AdminForthPageInjectionDeclarationFull = {
      file: this.componentPath('VisionAction.vue'),
      isVisible: ({ adminUser }) => this.isAllowedToGenerate(adminUser, ActionCheckSource.DisplayButtons),
      meta: {
        pluginInstanceId: this.pluginInstanceId,
        outputFields: outputFields,
        actionName: this.options.actionName,
        columnEnums: columnEnums,
        columnLabels: columnLabels,
        columnTypes: columnTypes,
        outputImageFields: outputImageFields,
        outputFieldsForAnalizeFromImages: outputFieldsForAnalizeFromImages,
        outputPlainFields: outputPlainFields,
        primaryKey: this.primaryKeyColumn.name,
        outputImagesPluginInstanceIds: outputImagesPluginInstanceIds,
        isFieldsForAnalizeFromImages: this.options.fillFieldsFromImages ? Object.keys(this.options.fillFieldsFromImages).length > 0 : false,
        isFieldsForAnalizePlain: this.options.fillPlainFields ? Object.keys(this.options.fillPlainFields).length > 0 : false,
        isImageGeneration: this.options.generateImages ? Object.keys(this.options.generateImages).length > 0 : false,
        isAttachFiles: this.options.attachFiles ? true : false,
        disabledWhenNoCheckboxes: this.options.recordSelector === 'filtered' ? false : true,
        refreshRates: {
          fillFieldsFromImages: this.options.refreshRates?.fillFieldsFromImages || 2_000,
          fillPlainFields: this.options.refreshRates?.fillPlainFields || 1_000,
          generateImages: this.options.refreshRates?.generateImages || 5_000,
          regenerateImages: this.options.refreshRates?.regenerateImages || 5_000,
        },
        askConfirmationBeforeGenerating: this.options.askConfirmationBeforeGenerating || false,
        concurrencyLimit: this.options.concurrencyLimit || 10,
        recordSelector: this.options.recordSelector || 'checkbox',
        askConfirmation: this.options.askConfirmation || [],
        generationPrompts: {
          plainFieldsPrompts: this.options.fillPlainFields || {},
          imageFieldsPrompts: this.options.fillFieldsFromImages || {},
          imageGenerationPrompts: imageGenerationPrompts,
        },
        pageSize: this.options.pageSize
      }
    }
    
    if (!resourceConfig.options.pageInjections) {
      resourceConfig.options.pageInjections = {};
    }
    if (!resourceConfig.options.pageInjections.list) {
      resourceConfig.options.pageInjections.list = {};
    }
    if (!resourceConfig.options.pageInjections.list.threeDotsDropdownItems) {
      resourceConfig.options.pageInjections.list.threeDotsDropdownItems = [];
    }

    (resourceConfig.options.pageInjections.list.threeDotsDropdownItems as AdminForthPageInjectionDeclarationFull[]).push(pageInjection);
  }

  /**
   * `allowedActions.generate` when set, otherwise the `edit` permission of the resource:
   * the generated values can only be saved by users who can edit.
   */
  private async isAllowedToGenerate(adminUser: AdminUser, source: ActionCheckSource): Promise<boolean> {
    const generate = this.options.allowedActions?.generate;
    if (generate === undefined) {
      const { allowedActions } = await interpretResource(adminUser, this.resourceConfig, {}, source, this.adminforth);
      return allowedActions.edit === true;
    }
    return typeof generate === 'function'
      ? await generate({ adminUser, resource: this.resourceConfig })
      : generate;
  }
  
  validateConfigAfterDiscover(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
    const columns = this.resourceConfig.columns;
    if (this.options.fillFieldsFromImages) {
      if (!this.options.attachFiles) {
        throw new Error('⚠️ attachFiles function must be provided when fillFieldsFromImages is used');
      }
      if (!this.options.visionAdapter) {
        throw new Error('⚠️ visionAdapter must be provided when fillFieldsFromImages is used');
      }
      for (const key of Object.keys(this.options.fillFieldsFromImages)) {
        const column = columns.find(c => c.name.toLowerCase() === key.toLowerCase());
        if (!column) {
          throw new Error(`⚠️ No column found for key "${key}"`);
        }
      }
    }
    if (this.options.fillPlainFields) {
      if (!this.options.textCompleteAdapter) {
        throw new Error('⚠️ textCompleteAdapter must be provided when fillPlainFields is used');
      }
      for (const key of Object.keys(this.options.fillPlainFields)) {
        const column = columns.find(c => c.name.toLowerCase() === key.toLowerCase());
        if (!column) {
          throw new Error(`⚠️ No column found for key "${key}"`);
        }
      }
    }
    if (this.options.generateImages) {
      for (const key of Object.keys(this.options.generateImages)) {
        const column = columns.find(c => c.name.toLowerCase() === key.toLowerCase());
        if (!column) {
          throw new Error(`⚠️ No column found for key "${key}"`);
        }
        const perKeyAdapter = this.options.generateImages[key].adapter;
        if (!perKeyAdapter && !this.options.imageGenerationAdapter) {
          throw new Error(`⚠️ No image generation adapter provided for key "${key}"`);
        }

        const plugin = adminforth.activatedPlugins.find(p => 
          p.resourceConfig!.resourceId === this.resourceConfig.resourceId &&
          p.pluginOptions.pathColumnName === key
        );
        if (!plugin) {
          throw new Error(`Plugin for attachment field '${key}' not found in resource '${this.resourceConfig.resourceId}', please check if Upload Plugin is installed on the field ${key}`);
        }
        if (!plugin.pluginOptions || !plugin.pluginOptions.storageAdapter) {
          throw new Error(`Upload Plugin for attachment field '${key}' in resource '${this.resourceConfig.resourceId}' is missing a storageAdapter configuration.`);
        }
        if (typeof plugin.pluginOptions.storageAdapter.objectCanBeAccesedPublicly !== 'function') {
          throw new Error(`Upload Plugin for attachment field '${key}' in resource '${this.resourceConfig.resourceId}' uses a storage adapter without 'objectCanBeAccesedPublicly' method.`);
        }
        if (!plugin.pluginOptions.storageAdapter.objectCanBeAccesedPublicly()) {
          throw new Error(`Upload Plugin for attachment field '${key}' in resource '${this.resourceConfig.resourceId}' 
            uses adapter which is not configured to store objects in public way, so it will produce only signed private URLs which can not be used in HTML text of blog posts.
            Please configure adapter in such way that it will store objects publicly (e.g.  for S3 use 'public-read' ACL).  
          `);
        }
      }
    }
    if ((this.options.fillFieldsFromImages || this.options.fillPlainFields || this.options.generateImages) && !this.options.provideAdditionalContextForRecord) {
      let matches: string[] = [];
      const regex = /{{(.*?)}}/g;

      if (this.options.fillFieldsFromImages) {
        for (const [key, value] of Object.entries((this.options.fillFieldsFromImages ))) {
          const template = value;
          const templateMatches = template.match(regex);
          if (templateMatches) {
            matches.push(...templateMatches);
          }
        }
      }
      if (this.options.fillPlainFields) {
        for (const [key, value] of Object.entries((this.options.fillPlainFields))) {
          const template = value;
          const templateMatches = template.match(regex);
          if (templateMatches) {
            matches.push(...templateMatches);
          }
        }
      }
      if (this.options.generateImages) {
        for (const [key, value] of Object.entries((this.options.generateImages ))) {
          const template = value.prompt;
          const templateMatches = template.match(regex);
          if (templateMatches) {
            matches.push(...templateMatches);
          }
        }
      }

      if (matches) {
        matches.forEach((match) => {
          const field = match.replace(/{{|}}/g, '').trim();
          const column = resourceConfig.columns.find((column: any) => column.name === field);
          if (!column) {
            const similar = suggestIfTypo(resourceConfig.columns.map((column: any) => column.name), field);
            throw new Error(`Field "${field}" specified in generationPrompt not found in resource "${resourceConfig.label}". ${similar ? `Did you mean "${similar}"?` : ''}`);
          } else {
            if (column.backendOnly === true) {
              throw new Error(`Field "${field}" specified in generationPrompt is marked as backendOnly in resource "${resourceConfig.label}". Please remove backendOnly or choose another field.`);
            }
          }
        });
      }
    }
  }

  instanceUniqueRepresentation(pluginOptions: any) : string {
    return `${this.pluginOptions.actionName}`;
  }

  pluginManagedFields(): Set<string> {
    return new Set([
      ...Object.keys(this.options.fillFieldsFromImages || {}),
      ...Object.keys(this.options.fillPlainFields || {}),
      ...Object.keys(this.options.generateImages || {}),
    ]);
  }


  /**
   * The rules of this plugin on top of the core edit checks: only the fields the action generates
   * may change, never the primary key, and `isAllowedToSave` has the last word. The resource ACL and
   * the column rules are enforced by `asUser().update()`.
   */
  async checkUpdateAllowed({ adminUser, oldRecord, fields }: {
    adminUser: AdminUser,
    oldRecord: any,
    fields: Record<string, any>,
  }): Promise<string | null | undefined> {
    const managedFields = this.pluginManagedFields();

    for (const [fieldName, value] of Object.entries(fields)) {
      if (valueIsUnchanged(value, oldRecord[fieldName])) {
        continue;
      }
      const column = this.resourceConfig.columns.find((col) => col.name === fieldName);
      if (!column) {
        return `Field "${fieldName}" does not exist in resource "${this.resourceConfig.resourceId}"`;
      }
      if (!managedFields.has(fieldName)) {
        return `Field "${fieldName}" cannot be modified, it is not generated by the "${this.options.actionName}" action`;
      }
      if (column.primaryKey) {
        return `Field "${fieldName}" cannot be modified as it is a primary key`;
      }
    }

    if (this.options.isAllowedToSave) {
      const isAllowedToSave = await this.options.isAllowedToSave({
        record: oldRecord,
        adminUser: adminUser,
        resource: this.resourceConfig,
      });
      if (isAllowedToSave?.ok === false) {
        return isAllowedToSave.error;
      }
    }

    return null;
  }

  /**
   * Reads one record for the user: `asUser().get()` enforces the `show` permission and the row
   * scope of the resource. Prompt templates and `attachFiles` are server-side and may use backendOnly
   * columns, so the full row is read afterwards; callers which send it to the browser must pass it
   * through `scopeRecordForFrontend` first.
   */
  private async getRecordForShow({ adminUser, recordId, extra }: {
    adminUser: AdminUser,
    recordId: any,
    extra: HttpExtra,
  }): Promise<{ record?: any, ctx: AccessCheckContext, error?: string }> {
    const meta = { requestBody: extra.body, pk: recordId };
    const ctx: AccessCheckContext = {
      adminUser,
      resource: this.resourceConfig,
      meta,
      source: ActionCheckSource.ShowRequest,
      adminforth: this.adminforth,
    };

    const resource = this.adminforth.resource(this.resourceConfig.resourceId);
    const filter = Filters.EQ(this.primaryKeyColumn.name, recordId);
    try {
      if (!await resource.asUser(adminUser, { meta, extra }).get(filter)) {
        return { error: 'Record not found', ctx };
      }
    } catch (e) {
      return { error: (e as Error).message, ctx };
    }
    return { record: await resource.get(filter), ctx };
  }

  /**
   * The action dialog only ever renders the fields this plugin generates, so only those leave the
   * backend, next to the primary key and the record label. backendOnly columns are dropped the same
   * way the core show route drops them.
   */
  private async scopeRecordForFrontend(record: any, ctx: AccessCheckContext): Promise<Record<string, any>> {
    const managedFields = this.pluginManagedFields();
    const scoped: Record<string, any> = {
      [this.primaryKeyColumn.name]: record[this.primaryKeyColumn.name],
      _label: this.resourceConfig.recordLabel(record),
    };
    for (const column of this.resourceConfig.columns.filter((col) => managedFields.has(col.name))) {
      if (await resolveBoolOrFn(column.backendOnly, ctx)) {
        continue;
      }
      scoped[column.name] = record[column.name];
    }
    return scoped;
  }

  /**
   * Links to the stored images of the generated image columns, built by the Upload plugin of each
   * column the same way its own previews are, so the dialog shows the current image next to the new one.
   */
  private async imagePreviewUrls(record: any): Promise<Record<string, string | null>> {
    const previews: Record<string, string | null> = {};
    for (const key of Object.keys(this.options.generateImages || {})) {
      const uploadPlugin = this.adminforth.activatedPlugins.find(p =>
        p.resourceConfig!.resourceId === this.resourceConfig.resourceId &&
        p.pluginOptions.pathColumnName === key
      ) as any;
      const holder = { [key]: record[key] };
      await uploadPlugin.genPreviewUrl(holder);
      previews[key] = holder[`previewUrl_${uploadPlugin.pluginInstanceId}`] ?? null;
    }
    return previews;
  }

  /**
   * The row as the caller is allowed to read it: columns which are not declared on the resource and
   * columns whose `backendOnly` resolves true for this request are dropped, exactly the way the
   * core show route drops them before a row reaches the browser.
   */
  private async stripBackendOnlyColumns(record: any, ctx: AccessCheckContext): Promise<Record<string, any>> {
    const visible: Record<string, any> = {};
    for (const column of this.resourceConfig.columns) {
      if (await resolveBoolOrFn(column.backendOnly, ctx)) {
        continue;
      }
      visible[column.name] = record[column.name];
    }
    return visible;
  }

  setupEndpoints(server: IHttpServer) {
    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/get_old_data`,
      agent: { hiddenFromAgents: true },
      request_schema: getOldDataBodySchema,
      handler: async ({ body, adminUser, headers, query, cookies, requestUrl, response }) => {
        const data = body as z.infer<typeof getOldDataBodySchema>;
        const recordId = data.recordId;
        if (recordId === undefined || recordId === null) {
          return { ok: false, error: "Missing recordId" };
        }
        const { record, ctx, error } = await this.getRecordForShow({
          adminUser,
          recordId,
          extra: { body, query, headers, cookies, requestUrl, response },
        });
        if (error) {
          return { ok: false, error };
        }
        return {
          ok: true,
          record: await this.scopeRecordForFrontend(record, ctx),
          imagePreviews: await this.imagePreviewUrls(record),
        };
      }
    });


    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/get_images`,
      agent: { hiddenFromAgents: true },
      request_schema: getImagesBodySchema,
      handler: async ({ body, adminUser, headers, query, cookies, requestUrl, response }) => {
        const data = body as z.infer<typeof getImagesBodySchema>;
        // attachFiles runs with server privileges and usually mints download URLs, so it is only
        // ever given a record loaded here after the show check, never one supplied by the client
        const { record, error } = await this.getRecordForShow({
          adminUser,
          recordId: data.recordId,
          extra: { body, query, headers, cookies, requestUrl, response },
        });
        if (error) {
          return { ok: false, error };
        }
        const images = this.options.attachFiles ? await this.options.attachFiles({ record }) : [];
        return { ok: true, images };
      }
    });


    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/update_fields`,
      agent: { hiddenFromAgents: true },
      request_schema: updateFieldsBodySchema,
      handler: async ({ body, adminUser, headers, query, cookies, requestUrl, response }) => {
        const data = body as z.infer<typeof updateFieldsBodySchema>;
        const selectedIds = data.selectedIds || [];
        const fieldsToUpdate = data.fields || {};

        const decimalFieldsArray = this.resourceConfig.columns.filter(c => c.type === 'decimal').map(c => c.name);
        const integerFieldsArray = this.resourceConfig.columns.filter(c => c.type === 'integer').map(c => c.name);
        const floatFieldsArray = this.resourceConfig.columns.filter(c => c.type === 'float').map(c => c.name);

        // the plugin rules are checked for every record before anything is written,
        // the permissions of the core edit route are enforced by asUser().update() below
        const managedFields = this.pluginManagedFields();
        const oldRecords: any[] = [];
        const sanitizedFields: Record<string, any>[] = [];
        for (const [idx, ID] of selectedIds.entries()) {
          const oldRecord = await this.adminforth.resource(this.resourceConfig.resourceId).get( [Filters.EQ(this.primaryKeyColumn.name, ID)] );
          if (!oldRecord) {
            return { ok: false, error: `Record with ${this.primaryKeyColumn.name} ${ID} not found` };
          }
          const fields = fieldsToUpdate[idx];
          if (!fields || typeof fields !== 'object' || Array.isArray(fields)) {
            return { ok: false, error: `No fields to update passed for record ${ID}` };
          }
          const accessError = await this.checkUpdateAllowed({
            adminUser,
            oldRecord,
            fields,
          });
          if (accessError) {
            return { ok: false, error: accessError };
          }
          oldRecords.push(oldRecord);
          // everything else (e.g. the primary key which frontend echoes back) is never written
          sanitizedFields.push(Object.fromEntries(
            Object.entries(fields).filter(([fieldName]) => managedFields.has(fieldName))
          ));
        }

        const updates = selectedIds.map(async (ID, idx) => {
          const oldRecord = oldRecords[idx];
          const recordFields = sanitizedFields[idx];
          // the stored images of the generated image columns are tagged for cleanup by the
          // edit.afterSave hook of the Upload plugin, once the update has been saved

          // Convert decimal fields to numbers
          if (decimalFieldsArray.length > 0) {
            for (const fieldName of decimalFieldsArray) {
              if (recordFields.hasOwnProperty(fieldName)) {
                recordFields[fieldName] = `${recordFields[fieldName]}`;
              }
            }
          }
          if (integerFieldsArray.length > 0) {
            for (const fieldName of integerFieldsArray) {
              if (recordFields.hasOwnProperty(fieldName)) {
                recordFields[fieldName] = parseInt(recordFields[fieldName], 10);
              }
            }
          }
          if (floatFieldsArray.length > 0) {
            for (const fieldName of floatFieldsArray) {
              if (recordFields.hasOwnProperty(fieldName)) {
                recordFields[fieldName] = parseFloat(recordFields[fieldName]);
              }
            }
          }

          return this.adminforth.resource(this.resourceConfig.resourceId)
            .asUser(adminUser, {
              meta: { requestBody: body },
              oldRecord,
              extra: { body, query, headers, cookies, requestUrl, response },
            })
            .update(ID, recordFields);
        });
        let results;
        try {
          results = await Promise.all(updates);
        } catch (error) {
          return { ok: false, error: `Error updating records, because of unprocesseble data for record ID ${selectedIds}` };
        }
        const updateErrors = results
          .map(({ error }, idx) => error && `Record ${selectedIds[idx]}: ${error}`)
          .filter(Boolean);
        if (updateErrors.length > 0) {
          return { ok: false, error: updateErrors.join('; ') };
        }
        return { ok: true };
      }
    });


    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/get_image_generation_prompts`,
      agent: { hiddenFromAgents: true },
      request_schema: getImageGenerationPromptsBodySchema,
      handler: async ({ body, adminUser, headers, query, cookies, requestUrl, response }) => {
        const data = body as z.infer<typeof getImageGenerationPromptsBodySchema>;
        const customPrompt = data.customPrompt || null;
        const { record, ctx, error } = await this.getRecordForShow({
          adminUser,
          recordId: data.recordId,
          extra: { body, query, headers, cookies, requestUrl, response },
        });
        if (error) {
          return { ok: false, error };
        }
        const compiledGenerationOptions = await this.compileGenerationFieldTemplates(record, ctx, JSON.stringify({"prompt": customPrompt}));
        return compiledGenerationOptions;
      }
    });


    server.endpoint({
      method: 'GET',
      path: `/plugin/${this.pluginInstanceId}/averageDuration`,
      handler: async () => {
        return {
          totalCalls: this.totalCalls,
          totalDuration: this.totalDuration,
          averageDuration: this.totalCalls ? this.totalDuration / this.totalCalls : null,
        };
      }
    });


    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/create-job`,
      agent: { hiddenFromAgents: true },
      request_schema: createJobBodySchema,
      handler: async ({ body, adminUser, headers, query, cookies, requestUrl, response }) => {
        const data = body as z.infer<typeof createJobBodySchema>;
        const { actionType, recordId, customPrompt, filterFilledFields, sessionIds } = data;
        if (!await this.isAllowedToGenerate(adminUser, ActionCheckSource.EditRequest)) {
          return { ok: false, error: "You are not allowed to run AI generation" };
        }
        if (this.options.rateLimits) {
          if (sessionIds && sessionIds.length > 0) {
            for (const sessionId of sessionIds) {
              if (!this.sessionIds.has(sessionId)) {
                return { ok: false, error: "Invalid session id" };
              }
              this.sessionIds.delete(sessionId);
            }
          } else {
            return { ok: false, error: "Missing session ids" };
          }
        }
        if (!actionType) {
          return { ok: false, error: "Missing action type" };
        }
        if (!recordId && typeof recordId !== 'number') {
          return { ok: false, error: "Missing record id" };
        }
        // every worker below compiles this record into an AI prompt whose answer is handed back
        // through get-job-status, so the record is read here, behind the same show check and
        // row-level scoping the other read endpoints use, and the row itself is what gets dispatched
        const { record, ctx, error } = await this.getRecordForShow({
          adminUser,
          recordId,
          extra: { body, query, headers, cookies, requestUrl, response },
        });
        if (error) {
          return { ok: false, error };
        }
        const jobId = randomUUID();
        jobs.set(jobId, { status: "in_progress" });
        // the workers run in background, a failure they do not handle themselves (e.g. of an adapter function) fails the job
        const run = (job: Promise<unknown>) => job.catch((e) => jobs.set(jobId, { status: 'failed', error: e.message }));
        switch(actionType) {
          case 'generate_images':
            run(this.initialImageGenerate(jobId, record, ctx, headers, customPrompt, filterFilledFields));
          break;
          case 'analyze_no_images':
            run(this.analyzeNoImages(jobId, record, ctx, headers, customPrompt, filterFilledFields));
          break;
          case 'analyze':
            run(this.analyze_image(jobId, record, ctx, headers, customPrompt, filterFilledFields));
          break;
          case 'regenerate_images':
            if (!data.prompt || !data.fieldName) {
              jobs.set(jobId, { status: "failed", error: "Missing prompt or field name" });
              break;
            }
            run(this.regenerateImage(jobId, record, ctx, data.fieldName, data.prompt, headers));
          break;
          case 'regenerate_cell':
            run(this.regenerateCell(jobId, data.fieldToRegenerate, record, ctx, data.action, data.prompt));
          break;
          default:
            jobs.set(jobId, { status: "failed", error: "Unknown action type" });
        }
        setTimeout(() => jobs.delete(jobId), 1_800_000);
        setTimeout(() => jobs.set(jobId, { status: "failed", error: "Job timed out" }), 180_000);
        return { ok: true, jobId };
      }
    });


    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/get-job-status`,
      agent: { hiddenFromAgents: true },
      request_schema: jobStatusBodySchema,
      handler: async ({ body, adminUser, headers, response }) => {
        const data = body as z.infer<typeof jobStatusBodySchema>;
        const jobId = data.jobId;
        if (!jobId) {
          response.setStatus(400);

          return {
            ok: false,
            error: "Can't find job id",
          };
        }
        const job = jobs.get(jobId);
        if (!job) {
          response.setStatus(404);

          return {
            ok: false,
            error: "Job not found",
          };
        }
        if (job.status === 'failed') {
          response.setStatus(500);

          return {
            ok: false,
            error: job.error
          };
        }
        return {
          ok: true,
          job,
        };
      }
    });


    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/update-rate-limits`,
      agent: { hiddenFromAgents: true },
      request_schema: updateRateLimitsBodySchema,
      handler: async ({ body, adminUser, headers, response }) => {
        const data = body as z.infer<typeof updateRateLimitsBodySchema>;
        const actionType = data.actionType;
        const sessionId = randomUUID();
        this.sessionIds.add(sessionId);
        if (actionType === 'analyze' && this.options.rateLimits?.fillFieldsFromImages) {
          if (await this.checkRateLimit("fillFieldsFromImages" ,this.options.rateLimits.fillFieldsFromImages, headers)) {
            return {ok: false, error: "Rate limit exceeded for image analyze" };
          }
        }
        if (actionType === 'analyze_no_images' && this.options.rateLimits?.fillPlainFields) {
          if (await this.checkRateLimit("fillPlainFields" ,this.options.rateLimits.fillPlainFields, headers)) {
            return {ok: false, error: "Rate limit exceeded for plain field analyze" };
          }
        }
        if (actionType === 'generate_images' && this.options.rateLimits?.generateImages) {
          if (await this.checkRateLimit("generateImages" ,this.options.rateLimits.generateImages, headers)) {
            return {ok: false, error: "Rate limit exceeded for image generation" };
          }
        }
        setTimeout(() => this.sessionIds.delete(sessionId), 300_000);
        return { ok: true, sessionId };
      }
    });


    server.endpoint({
      method: 'POST',
      path: `/plugin/${this.pluginInstanceId}/get_filtered_ids`,
      agent: { hiddenFromAgents: true },
      request_schema: getFilteredIdsBodySchema,
      handler: async ({ body, adminUser, headers, query, cookies, requestUrl, response }) => {
        let records;
        try {
          // only the primary key is read, so response hooks have nothing heavy to post-process
          records = await this.adminforth.resource(this.resourceConfig.resourceId)
            .asUser(adminUser, {
              meta: { requestBody: body },
              extra: { body, query, headers, cookies, requestUrl, response },
            })
            .list(body.filters ?? [], undefined, undefined, [], [this.primaryKeyColumn.name]);
        } catch (e) {
          return { ok: false, error: (e as Error).message };
        }
        return { ok: true, recordIds: records.map((record) => record[this.primaryKeyColumn.name]) };
      }
    });
  }
}