unrag 0.2.2 → 0.2.3

package/registry/embedding/ai.ts

@@ -1,27 +1,68 @@
-import { embed } from "ai";
-import type { EmbeddingProvider } from "../core/types";
+import { embed, embedMany } from "ai";
+import type { EmbeddingProvider, ImageEmbeddingInput } from "../core/types";
 
-export type AiEmbeddingConfig = {
+type BaseConfig = {
   /**
-   * AI Gateway model id, e.g. "openai/text-embedding-3-small"
+   * AI Gateway model id, e.g. "openai/text-embedding-3-small" or "google/gemini-...".
    */
   model?: string;
   timeoutMs?: number;
 };
 
-const DEFAULT_MODEL = "openai/text-embedding-3-small";
+export type AiEmbeddingConfig =
+  | (BaseConfig & {
+      /**
+       * Defaults to "text" for backwards compatibility.
+       * - "text": only supports embedding strings
+       * - "multimodal": additionally enables `embedImage()` for image assets (when the model supports it)
+       */
+      type?: "text";
+    })
+  | (BaseConfig & {
+      type: "multimodal";
+      /**
+       * Controls how images are translated into AI SDK `embed()` values.
+       * Different providers use different shapes; this is the escape hatch.
+       */
+      image?: {
+        value?: (input: ImageEmbeddingInput) => unknown;
+      };
+    });
+
+const DEFAULT_TEXT_MODEL = "openai/text-embedding-3-small";
+const DEFAULT_MULTIMODAL_MODEL = "cohere/embed-v4.0";
+
+const bytesToDataUrl = (bytes: Uint8Array, mediaType: string) => {
+  const base64 = Buffer.from(bytes).toString("base64");
+  return `data:${mediaType};base64,${base64}`;
+};
+
+const defaultImageValue = (input: ImageEmbeddingInput) => {
+  const v =
+    typeof input.data === "string"
+      ? input.data
+      : bytesToDataUrl(input.data, input.mediaType ?? "image/jpeg");
+  // This matches common AI Gateway multimodal embedding inputs where
+  // the embedding value is an object containing one or more images.
+  return { image: [v] };
+};
 
 export const createAiEmbeddingProvider = (
   config: AiEmbeddingConfig = {}
 ): EmbeddingProvider => {
-  const model = config.model ?? process.env.AI_GATEWAY_MODEL ?? DEFAULT_MODEL;
+  const type = (config as any).type ?? "text";
+  const model =
+    config.model ??
+    process.env.AI_GATEWAY_MODEL ??
+    (type === "multimodal" ? DEFAULT_MULTIMODAL_MODEL : DEFAULT_TEXT_MODEL);
+  const timeoutMs = config.timeoutMs;
 
   return {
     name: `ai-sdk:${model}`,
     dimensions: undefined,
     embed: async ({ text }) => {
-      const abortSignal = config.timeoutMs
-        ? AbortSignal.timeout(config.timeoutMs)
+      const abortSignal = timeoutMs
+        ? AbortSignal.timeout(timeoutMs)
         : undefined;
 
       const result = await embed({
@@ -36,6 +77,46 @@ export const createAiEmbeddingProvider = (
 
       return result.embedding;
     },
+    embedMany: async (inputs) => {
+      const values = inputs.map((i) => i.text);
+      const abortSignal = timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined;
+
+      const result = await embedMany({
+        model,
+        values,
+        ...(abortSignal ? { abortSignal } : {}),
+      });
+
+      const embeddings = (result as any)?.embeddings as number[][] | undefined;
+      if (!embeddings) {
+        throw new Error("Embeddings missing from AI SDK embedMany response");
+      }
+      return embeddings;
+    },
+    ...(type === "multimodal"
+      ? {
+          embedImage: async (input: ImageEmbeddingInput) => {
+            const abortSignal = timeoutMs
+              ? AbortSignal.timeout(timeoutMs)
+              : undefined;
+
+            const imageValue =
+              (config as any)?.image?.value?.(input) ?? defaultImageValue(input);
+
+            const result = await embed({
+              model,
+              value: imageValue,
+              ...(abortSignal ? { abortSignal } : {}),
+            });
+
+            if (!result.embedding) {
+              throw new Error("Embedding missing from AI SDK response");
+            }
+
+            return result.embedding;
+          },
+        }
+      : {}),
   };
 };
 

package/registry/extractors/_shared/fetch.ts

@@ -0,0 +1,113 @@
+import type { AssetData, AssetFetchConfig } from "../../core/types";
+
+const DEFAULT_UA = "unrag/asset-fetch";
+
+const isProbablyIpLiteral = (host: string) =>
+  /^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(":");
+
+const isDisallowedHost = (host: string) => {
+  const h = host.toLowerCase();
+  if (h === "localhost" || h.endsWith(".localhost")) return true;
+  if (h === "0.0.0.0") return true;
+  if (h === "127.0.0.1" || h.startsWith("127.")) return true;
+  if (h === "::1") return true;
+
+  // If host is an IP literal, block common private ranges.
+  if (isProbablyIpLiteral(h)) {
+    if (h.startsWith("10.")) return true;
+    if (h.startsWith("192.168.")) return true;
+    if (/^172\.(1[6-9]|2\d|3[0-1])\./.test(h)) return true;
+  }
+
+  return false;
+};
+
+export async function fetchBytesFromUrl(args: {
+  url: string;
+  fetchConfig: AssetFetchConfig;
+  headers?: Record<string, string>;
+  maxBytes: number;
+}): Promise<{ bytes: Uint8Array; mediaType?: string }> {
+  if (!args.fetchConfig.enabled) {
+    throw new Error("Asset fetch disabled (assetProcessing.fetch.enabled=false)");
+  }
+
+  const u = new URL(args.url);
+  if (u.protocol !== "https:") {
+    throw new Error("Only https:// URLs are allowed for asset fetching");
+  }
+
+  if (isDisallowedHost(u.hostname)) {
+    throw new Error(`Disallowed host for asset fetch: ${u.hostname}`);
+  }
+
+  const allow = args.fetchConfig.allowedHosts;
+  if (Array.isArray(allow) && allow.length > 0) {
+    const ok = allow.some((h) => h.toLowerCase() === u.hostname.toLowerCase());
+    if (!ok) {
+      throw new Error(`Host not allowlisted for asset fetch: ${u.hostname}`);
+    }
+  }
+
+  const abortSignal = AbortSignal.timeout(args.fetchConfig.timeoutMs);
+  const headers = {
+    "user-agent": DEFAULT_UA,
+    ...(args.fetchConfig.headers ?? {}),
+    ...(args.headers ?? {}),
+  };
+
+  const res = await fetch(args.url, { headers, signal: abortSignal });
+  if (!res.ok) {
+    throw new Error(`Asset fetch failed (${res.status} ${res.statusText})`);
+  }
+
+  const contentLength = Number(res.headers.get("content-length") ?? NaN);
+  if (Number.isFinite(contentLength) && contentLength > args.maxBytes) {
+    throw new Error(
+      `Asset too large (content-length ${contentLength} > ${args.maxBytes})`
+    );
+  }
+
+  const buf = new Uint8Array(await res.arrayBuffer());
+  if (buf.byteLength > args.maxBytes) {
+    throw new Error(`Asset too large (${buf.byteLength} > ${args.maxBytes})`);
+  }
+
+  const mediaType = res.headers.get("content-type")?.split(";")[0]?.trim();
+  return { bytes: buf, mediaType: mediaType || undefined };
+}
+
+export async function getAssetBytes(args: {
+  data: AssetData;
+  fetchConfig: AssetFetchConfig;
+  maxBytes: number;
+  /** Optional fallback when data does not provide a mediaType and the response lacks one. */
+  defaultMediaType?: string;
+}): Promise<{ bytes: Uint8Array; mediaType: string; filename?: string }> {
+  if (args.data.kind === "bytes") {
+    return {
+      bytes: args.data.bytes,
+      mediaType: args.data.mediaType,
+      ...(args.data.filename ? { filename: args.data.filename } : {}),
+    };
+  }
+
+  const fetched = await fetchBytesFromUrl({
+    url: args.data.url,
+    fetchConfig: args.fetchConfig,
+    headers: args.data.headers,
+    maxBytes: args.maxBytes,
+  });
+
+  return {
+    bytes: fetched.bytes,
+    mediaType:
+      args.data.mediaType ??
+      fetched.mediaType ??
+      args.defaultMediaType ??
+      "application/octet-stream",
+    ...(args.data.filename ? { filename: args.data.filename } : {}),
+  };
+}
+
+

package/registry/extractors/_shared/media.ts

@@ -0,0 +1,14 @@
+export function normalizeMediaType(mediaType: string | undefined): string | undefined {
+  if (!mediaType) return undefined;
+  return mediaType.split(";")[0]?.trim().toLowerCase() || undefined;
+}
+
+export function extFromFilename(filename: string | undefined): string | undefined {
+  if (!filename) return undefined;
+  const idx = filename.lastIndexOf(".");
+  if (idx < 0) return undefined;
+  const ext = filename.slice(idx + 1).trim().toLowerCase();
+  return ext || undefined;
+}
+
+

package/registry/extractors/_shared/text.ts

@@ -0,0 +1,11 @@
+export function capText(text: string, maxChars: number): string {
+  const t = String(text ?? "");
+  if (!Number.isFinite(maxChars) || maxChars <= 0) return t;
+  return t.length <= maxChars ? t : t.slice(0, maxChars).trimEnd();
+}
+
+export function toUtf8String(bytes: Uint8Array): string {
+  return new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+}
+
+

package/registry/extractors/audio-transcribe/index.ts

@@ -0,0 +1,75 @@
+import { experimental_transcribe as transcribe } from "ai";
+import type { AssetExtractor } from "../../core/types";
+import { getAssetBytes } from "../_shared/fetch";
+
+/**
+ * Audio transcription via the AI SDK `transcribe()` API.
+ */
+export function createAudioTranscribeExtractor(): AssetExtractor {
+  return {
+    name: "audio:transcribe",
+    supports: ({ asset, ctx }) =>
+      asset.kind === "audio" && ctx.assetProcessing.audio.transcription.enabled,
+    extract: async ({ asset, ctx }) => {
+      const cfg = ctx.assetProcessing.audio.transcription;
+      const fetchConfig = ctx.assetProcessing.fetch;
+
+      const maxBytes = Math.min(cfg.maxBytes, fetchConfig.maxBytes);
+      const { bytes } = await getAssetBytes({
+        data: asset.data,
+        fetchConfig,
+        maxBytes,
+        defaultMediaType: "audio/mpeg",
+      });
+
+      const abortSignal = AbortSignal.timeout(cfg.timeoutMs);
+
+      const result = await transcribe({
+        model: cfg.model as any,
+        audio: bytes,
+        abortSignal,
+      });
+
+      const segments: any[] = Array.isArray((result as any)?.segments)
+        ? (result as any).segments
+        : [];
+
+      if (segments.length > 0) {
+        return {
+          texts: segments
+            .map((s, i) => {
+              const t = String(s?.text ?? "").trim();
+              if (!t) return null;
+              const start = Number(s?.startSecond ?? NaN);
+              const end = Number(s?.endSecond ?? NaN);
+              return {
+                label: `segment-${i + 1}`,
+                content: t,
+                ...(Number.isFinite(start) && Number.isFinite(end)
+                  ? { timeRangeSec: [start, end] as [number, number] }
+                  : {}),
+              };
+            })
+            .filter(Boolean) as any,
+          diagnostics: {
+            model: cfg.model,
+            seconds:
+              typeof (result as any)?.durationInSeconds === "number"
+                ? (result as any).durationInSeconds
+                : undefined,
+          },
+        };
+      }
+
+      const text = String((result as any)?.text ?? "").trim();
+      if (!text) return { texts: [], diagnostics: { model: cfg.model } };
+
+      return {
+        texts: [{ label: "transcript", content: text }],
+        diagnostics: { model: cfg.model },
+      };
+    },
+  };
+}
+
+

package/registry/extractors/file-docx/index.ts

@@ -0,0 +1,53 @@
+import type { AssetExtractor } from "../../core/types";
+import { getAssetBytes } from "../_shared/fetch";
+import { extFromFilename, normalizeMediaType } from "../_shared/media";
+import { capText } from "../_shared/text";
+
+const DOCX_MEDIA =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+
+export function createFileDocxExtractor(): AssetExtractor {
+  return {
+    name: "file:docx",
+    supports: ({ asset, ctx }) => {
+      if (asset.kind !== "file") return false;
+      if (!ctx.assetProcessing.file.docx.enabled) return false;
+      const filename = asset.data.kind === "bytes" ? asset.data.filename : asset.data.filename;
+      const ext = extFromFilename(filename);
+      const mt =
+        asset.data.kind === "bytes"
+          ? normalizeMediaType(asset.data.mediaType)
+          : normalizeMediaType(asset.data.mediaType);
+      return ext === "docx" || mt === DOCX_MEDIA;
+    },
+    extract: async ({ asset, ctx }) => {
+      const cfg = ctx.assetProcessing.file.docx;
+      const fetchConfig = ctx.assetProcessing.fetch;
+
+      const maxBytes = Math.min(cfg.maxBytes, fetchConfig.maxBytes);
+      const { bytes } = await getAssetBytes({
+        data: asset.data,
+        fetchConfig,
+        maxBytes,
+        defaultMediaType: DOCX_MEDIA,
+      });
+
+      // Dynamic import so the core package can be used without mammoth unless this extractor is installed.
+      const mammoth: any = await import("mammoth");
+      const arrayBuffer = bytes.buffer.slice(
+        bytes.byteOffset,
+        bytes.byteOffset + bytes.byteLength
+      );
+      const res = await mammoth.extractRawText({ arrayBuffer });
+
+      const text = String(res?.value ?? "").trim();
+      if (text.length < cfg.minChars) return { texts: [] };
+
+      return {
+        texts: [{ label: "docx", content: capText(text, cfg.maxOutputChars) }],
+      };
+    },
+  };
+}
+
+

package/registry/extractors/file-pptx/index.ts

@@ -0,0 +1,92 @@
+import type { AssetExtractor } from "../../core/types";
+import { getAssetBytes } from "../_shared/fetch";
+import { extFromFilename, normalizeMediaType } from "../_shared/media";
+import { capText } from "../_shared/text";
+
+const PPTX_MEDIA =
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+
+const decodeXmlEntities = (s: string) =>
+  s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+
+export function createFilePptxExtractor(): AssetExtractor {
+  return {
+    name: "file:pptx",
+    supports: ({ asset, ctx }) => {
+      if (asset.kind !== "file") return false;
+      if (!ctx.assetProcessing.file.pptx.enabled) return false;
+      const filename = asset.data.kind === "bytes" ? asset.data.filename : asset.data.filename;
+      const ext = extFromFilename(filename);
+      const mt =
+        asset.data.kind === "bytes"
+          ? normalizeMediaType(asset.data.mediaType)
+          : normalizeMediaType(asset.data.mediaType);
+      return ext === "pptx" || mt === PPTX_MEDIA;
+    },
+    extract: async ({ asset, ctx }) => {
+      const cfg = ctx.assetProcessing.file.pptx;
+      const fetchConfig = ctx.assetProcessing.fetch;
+
+      const maxBytes = Math.min(cfg.maxBytes, fetchConfig.maxBytes);
+      const { bytes } = await getAssetBytes({
+        data: asset.data,
+        fetchConfig,
+        maxBytes,
+        defaultMediaType: PPTX_MEDIA,
+      });
+
+      // Dynamic import to avoid hard dependency unless installed.
+      const JSZip: any = (await import("jszip")).default;
+      const zip = await JSZip.loadAsync(bytes);
+
+      const slidePaths = Object.keys(zip.files).filter((p) =>
+        /^ppt\/slides\/slide\d+\.xml$/.test(p)
+      );
+      slidePaths.sort((a, b) => {
+        const na = Number(a.match(/slide(\d+)\.xml$/)?.[1] ?? 0);
+        const nb = Number(b.match(/slide(\d+)\.xml$/)?.[1] ?? 0);
+        return na - nb;
+      });
+
+      const texts: Array<{ label: string; content: string }> = [];
+      let totalChars = 0;
+
+      for (const slidePath of slidePaths) {
+        if (totalChars >= cfg.maxOutputChars) break;
+
+        const xml = await zip.files[slidePath]!.async("string");
+        const parts: string[] = [];
+        const re = /<a:t[^>]*>([\s\S]*?)<\/a:t>/g;
+        let m: RegExpExecArray | null;
+        while ((m = re.exec(xml))) {
+          const t = decodeXmlEntities(String(m[1] ?? "")).replace(/\s+/g, " ").trim();
+          if (t) parts.push(t);
+        }
+
+        const slideText = parts.join(" ").trim();
+        if (!slideText) continue;
+
+        const slideNum = Number(slidePath.match(/slide(\d+)\.xml$/)?.[1] ?? 0);
+        const capped = capText(slideText, cfg.maxOutputChars - totalChars);
+        if (!capped) continue;
+
+        texts.push({ label: `slide-${slideNum || texts.length + 1}`, content: capped });
+        totalChars += capped.length;
+      }
+
+      const joinedChars = texts.reduce((n, t) => n + t.content.length, 0);
+      if (joinedChars < cfg.minChars) return { texts: [] };
+
+      return {
+        texts: texts.map((t) => ({ label: t.label, content: t.content })),
+      };
+    },
+  };
+}
+
+

package/registry/extractors/file-text/index.ts

@@ -0,0 +1,85 @@
+import type { AssetExtractor } from "../../core/types";
+import { getAssetBytes } from "../_shared/fetch";
+import { extFromFilename, normalizeMediaType } from "../_shared/media";
+import { capText, toUtf8String } from "../_shared/text";
+
+const stripHtml = (html: string) => {
+  const withoutScripts = html
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ");
+  const withBreaks = withoutScripts
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/p>/gi, "\n")
+    .replace(/<\/div>/gi, "\n");
+  const withoutTags = withBreaks.replace(/<[^>]+>/g, " ");
+  return withoutTags.replace(/\s+\n/g, "\n").replace(/[ \t]{2,}/g, " ").trim();
+};
+
+const isTextish = (mediaType: string | undefined, filename: string | undefined) => {
+  const mt = normalizeMediaType(mediaType);
+  if (mt?.startsWith("text/")) return true;
+  if (mt === "application/json") return true;
+  if (mt === "application/xml") return true;
+  if (mt === "application/xhtml+xml") return true;
+
+  const ext = extFromFilename(filename);
+  if (!ext) return false;
+  return (
+    ext === "txt" ||
+    ext === "md" ||
+    ext === "markdown" ||
+    ext === "html" ||
+    ext === "htm" ||
+    ext === "json" ||
+    ext === "csv" ||
+    ext === "log" ||
+    ext === "xml"
+  );
+};
+
+export function createFileTextExtractor(): AssetExtractor {
+  return {
+    name: "file:text",
+    supports: ({ asset, ctx }) => {
+      if (asset.kind !== "file") return false;
+      if (!ctx.assetProcessing.file.text.enabled) return false;
+      const filename = asset.data.kind === "bytes" ? asset.data.filename : asset.data.filename;
+      const mediaType = asset.data.kind === "bytes" ? asset.data.mediaType : asset.data.mediaType;
+      return isTextish(mediaType, filename);
+    },
+    extract: async ({ asset, ctx }) => {
+      const cfg = ctx.assetProcessing.file.text;
+      const fetchConfig = ctx.assetProcessing.fetch;
+
+      const maxBytes = Math.min(cfg.maxBytes, fetchConfig.maxBytes);
+      const { bytes, mediaType, filename } = await getAssetBytes({
+        data: asset.data,
+        fetchConfig,
+        maxBytes,
+        defaultMediaType: "text/plain",
+      });
+
+      const ext = extFromFilename(filename);
+      const mt = normalizeMediaType(mediaType);
+
+      let text = toUtf8String(bytes);
+
+      if (mt === "text/html" || mt === "application/xhtml+xml" || ext === "html" || ext === "htm") {
+        text = stripHtml(text);
+      }
+
+      text = text.trim();
+      if (text.length < cfg.minChars) return { texts: [] };
+
+      return {
+        texts: [{ label: "text", content: capText(text, cfg.maxOutputChars) }],
+        metadata: {
+          ...(mt ? { mediaType: mt } : {}),
+          ...(ext ? { ext } : {}),
+        },
+      };
+    },
+  };
+}
+
+

package/registry/extractors/file-xlsx/index.ts

@@ -0,0 +1,58 @@
+import type { AssetExtractor } from "../../core/types";
+import { getAssetBytes } from "../_shared/fetch";
+import { extFromFilename, normalizeMediaType } from "../_shared/media";
+import { capText } from "../_shared/text";
+
+const XLSX_MEDIA =
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+
+export function createFileXlsxExtractor(): AssetExtractor {
+  return {
+    name: "file:xlsx",
+    supports: ({ asset, ctx }) => {
+      if (asset.kind !== "file") return false;
+      if (!ctx.assetProcessing.file.xlsx.enabled) return false;
+      const filename = asset.data.kind === "bytes" ? asset.data.filename : asset.data.filename;
+      const ext = extFromFilename(filename);
+      const mt =
+        asset.data.kind === "bytes"
+          ? normalizeMediaType(asset.data.mediaType)
+          : normalizeMediaType(asset.data.mediaType);
+      return ext === "xlsx" || mt === XLSX_MEDIA;
+    },
+    extract: async ({ asset, ctx }) => {
+      const cfg = ctx.assetProcessing.file.xlsx;
+      const fetchConfig = ctx.assetProcessing.fetch;
+
+      const maxBytes = Math.min(cfg.maxBytes, fetchConfig.maxBytes);
+      const { bytes } = await getAssetBytes({
+        data: asset.data,
+        fetchConfig,
+        maxBytes,
+        defaultMediaType: XLSX_MEDIA,
+      });
+
+      const xlsx: any = await import("xlsx");
+      const wb = xlsx.read(Buffer.from(bytes), { type: "buffer" });
+
+      const parts: string[] = [];
+      for (const sheetName of wb.SheetNames ?? []) {
+        if (parts.join("\n\n").length >= cfg.maxOutputChars) break;
+        const sheet = wb.Sheets?.[sheetName];
+        if (!sheet) continue;
+        const csv = String(xlsx.utils.sheet_to_csv(sheet) ?? "").trim();
+        if (!csv) continue;
+        parts.push(`# Sheet: ${sheetName}\n\n${csv}`);
+      }
+
+      const text = capText(parts.join("\n\n"), cfg.maxOutputChars).trim();
+      if (text.length < cfg.minChars) return { texts: [] };
+
+      return {
+        texts: [{ label: "xlsx", content: text }],
+      };
+    },
+  };
+}
+
+

package/registry/extractors/image-caption-llm/index.ts

@@ -0,0 +1,60 @@
+import { generateText } from "ai";
+import type { AssetExtractor } from "../../core/types";
+import { getAssetBytes } from "../_shared/fetch";
+import { normalizeMediaType } from "../_shared/media";
+import { capText } from "../_shared/text";
+
+/**
+ * Caption generation for images via a vision-capable LLM.
+ *
+ * Useful when you want text-based retrieval for images but the source system does not provide captions/alt text.
+ */
+export function createImageCaptionLlmExtractor(): AssetExtractor {
+  return {
+    name: "image:caption-llm",
+    supports: ({ asset, ctx }) =>
+      asset.kind === "image" && ctx.assetProcessing.image.captionLlm.enabled,
+    extract: async ({ asset, ctx }) => {
+      const cfg = ctx.assetProcessing.image.captionLlm;
+      const fetchConfig = ctx.assetProcessing.fetch;
+
+      const maxBytes = Math.min(cfg.maxBytes, fetchConfig.maxBytes);
+      const { bytes, mediaType } = await getAssetBytes({
+        data: asset.data,
+        fetchConfig,
+        maxBytes,
+        defaultMediaType: "image/jpeg",
+      });
+
+      const abortSignal = AbortSignal.timeout(cfg.timeoutMs);
+
+      const result = await generateText({
+        model: cfg.model as any,
+        abortSignal,
+        messages: [
+          {
+            role: "user",
+            content: [
+              { type: "text", text: cfg.prompt },
+              {
+                type: "image",
+                image: bytes,
+                mediaType: normalizeMediaType(mediaType),
+              },
+            ],
+          },
+        ],
+      });
+
+      const caption = String((result as any)?.text ?? "").trim();
+      if (!caption) return { texts: [], diagnostics: { model: cfg.model } };
+
+      return {
+        texts: [{ label: "caption", content: capText(caption, cfg.maxOutputChars) }],
+        diagnostics: { model: cfg.model },
+      };
+    },
+  };
+}
+
+