utilitas 2001.1.136 → 2001.1.139

package/lib/rag.mjs

@@ -1,4 +1,4 @@
-import { BASE64, convert } from './storage.mjs';
+import { BASE64, convert, formatDataURL } from './storage.mjs';
 import { countTokens, trimText } from './alan.mjs';
 import { ensureArray, ensureString, need } from './utilitas.mjs';
 
@@ -9,20 +9,16 @@ const rerankerClients = {};
 const [
     OPENAI, GOOGLE, OPENROUTER, JINA,
     GOOGLE_DEFAULT_LOCATION, GOOGLE_RERANK_CONFIG_ID,
-    OPENAI_MODEL_EMBED_SMALL,
-    OPENAI_MODEL_EMBED_LARGE,
-    GOOGLE_MODEL_GEMINI_EMBED,
-    JINA_MODEL_V_4,
+    OPENAI_EMBED,
+    GEMINI_EMBED,
     GOOGLE_MODEL_SEMANTIC_RANKER,
     JINA_MODEL_RERANKER_M0,
 ] = [
         'OPENAI', 'GOOGLE', 'OPENROUTER', 'JINA',
         'global', 'default_ranking_config',
         'text-embedding-3-small', // dim: 1536
-        'text-embedding-3-large', // dim: 3072
         // https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-embedding-2/
-        'gemini-embedding-001', // dim: 768(default), 1536, or 3072(google default)
-        'jina-embeddings-v4', // dim: 256‑2048
+        'gemini-embedding-2-preview', // dim: from 128 to 3072, default 768.
         'semantic-ranker-default@latest',
         'jina-reranker-m0',
     ];
@@ -33,9 +29,8 @@ const PROVIDER_BASE_URL = {
 };
 
 const DEFAULT_EMBEDDING_MODELS = {
-    [OPENAI]: OPENAI_MODEL_EMBED_SMALL,
-    [OPENROUTER]: GOOGLE_MODEL_GEMINI_EMBED,
-    [JINA]: JINA_MODEL_V_4,
+    [OPENAI]: OPENAI_EMBED,
+    [OPENROUTER]: GEMINI_EMBED,
 };
 
 const DEFAULT_RERANKER_MODELS = {
@@ -44,27 +39,12 @@ const DEFAULT_RERANKER_MODELS = {
 };
 
 const MODEL_CONFIG = {
-    [OPENAI_MODEL_EMBED_SMALL]: {
+    [OPENAI_EMBED]: {
         source: 'openai', image: false, maxTokens: 8192,
     },
-    [OPENAI_MODEL_EMBED_LARGE]: {
-        source: 'openai', image: false, maxTokens: 8192,
-    },
-    [GOOGLE_MODEL_GEMINI_EMBED]: {
-        source: 'google', image: false, maxTokens: 2048,
-        options: { dimensions: 768 },
-    },
-    // Token calculation may be incorrect because its limitation applies to the
-    // entire request rather than individual entries.
-    // https://jina.ai/embeddings
-    [JINA_MODEL_V_4]: {
-        source: 'jina', image: true, maxTokens: 8192, recordsLimit: 512,
-        options: {
-            task: 'text-matching', // 'retrieval.query', 'retrieval.passage'
-            dimensions: 768, // normalized: true, by default DONT submit
-            truncate: true, // late_chunking: true, by default DONT submit
-            embedding_type: 'float',
-        },
+    [GEMINI_EMBED]: {
+        source: 'google', image: true, maxTokens: 8192,
+        options: { dimensions: 768, encoding_format: 'float' },
     },
     [GOOGLE_MODEL_SEMANTIC_RANKER]: {
         source: 'google', image: false, maxTokens: 1024, recordsLimit: 200,
@@ -136,6 +116,70 @@ const initEmbedding = async (options = {}) => {
     return getEmbeddingClient(provider);
 };
 
+const parseDataUrl = (value) => {
+    const match = ensureString(value).match(/^data:([^;]+);base64,(.*)$/i);
+    return match ? { mime: match[1], data: match[2], url: value } : null;
+};
+
+const normalizeEmbedImage = async (value, options) => {
+    const dataUrl = parseDataUrl(value);
+    if (dataUrl) { return dataUrl; }
+    if (!options?.input && /^https?:\/\//i.test(ensureString(value))) {
+        return { url: value, mime: options?.mime };
+    }
+    if (!options?.input && String.isString(value)) {
+        assert(options?.mime, 'Image MIME type is required.', 400);
+        return { data: value, mime: options.mime };
+    }
+    const { content, mime } = await convert(value, {
+        ...options, expected: BASE64, meta: true,
+    });
+    assert(
+        (options?.mime || mime)?.startsWith('image/'),
+        `Invalid image MIME type: ${options?.mime || mime}.`, 400
+    );
+    return { data: content, mime: options?.mime || mime };
+};
+
+const formatOpenRouterInput = (items) => items.map((x) => {
+    if (x.text !== undefined) {
+        return { content: [{ type: 'text', text: x.text }] };
+    }
+    if (x.image) {
+        return {
+            content: [{
+                type: 'image_url',
+                image_url: {
+                    url: x.image.url || formatDataURL(
+                        x.image.mime, x.image.data
+                    ),
+                },
+            }],
+        };
+    }
+    assert(false, 'Unsupported embedding input type.', 400);
+});
+
+/**
+ * Generate embeddings for text or image input.
+ *
+ * Usage:
+ *   await initEmbedding({ provider: 'OPENROUTER', apiKey });
+ *   await embed('hello world', { provider: 'OPENROUTER' });
+ *   await embed({ image: '/path/to/image.jpg' }, {
+ *       provider: 'OPENROUTER',
+ *       input: 'FILE',
+ *   });
+ *   await embed([
+ *       'hello world',
+ *       { image: 'https://example.com/image.jpg' },
+ *   ], { provider: 'OPENROUTER' });
+ *
+ * Input accepts a string, { text }, { image }, or an array of those values.
+ * Local image files should pass { input: 'FILE' }. Raw base64 image strings
+ * need { mime: 'image/...' }. OpenRouter image embeddings are sent through
+ * its multimodal `image_url` embeddings format.
+ */
 const embed = async (input, options = {}) => {
     let [{ client, model: selectedModel, provider, source }, resp]
         = [getEmbeddingClient(options?.provider), null];
@@ -147,35 +191,33 @@ const embed = async (input, options = {}) => {
             Object.keys(x).length == 1,
             'Only one type of input is allowed at a time.', 400
         );
-        if (x.text) {
-            x.text = await trimText(x.text, MODEL_CONFIG[model]?.maxTokens);
-        } else if (x.image) {
+        if (x.text !== undefined) {
+            x.text = trimText(x.text, MODEL_CONFIG[model]?.maxTokens);
+        } else if (x.image !== undefined) {
             assert(
                 MODEL_CONFIG[model]?.image,
                 `Model ${model} does not support image embeddings.`, 400
             );
-            if (options?.input) {
-                x.image = await convert(
-                    x.image, { ...options, expected: BASE64 }
-                );
-            }
+            x.image = await normalizeEmbedImage(x.image, options);
+        } else {
+            assert(false, 'Unsupported embedding input type.', 400);
         }
         return x;
     }));
-    MODEL_CONFIG[model]?.image || (input = input.map(x => x.text));
     assert(input.length, 'Input is required.', 400);
     const body = {
-        model, input, ...MODEL_CONFIG[model]?.options || {},
+        model,
+        input: input.map(x => x.text),
+        ...MODEL_CONFIG[model]?.options || {},
         ...options?.requestOptions || {},
     };
     switch (provider) {
-        case JINA:
-            resp = await client.post('/embeddings', { body });
-            break;
         case OPENROUTER:
             source = options?.source || source
                 || MODEL_CONFIG[body.model]?.source;
             body.model = `${source ? `${source}/` : ''}${body.model}`;
+            input.some(x => x.image)
+                && (body.input = formatOpenRouterInput(input));
         case OPENAI:
             resp = await client.embeddings.create(body);
             break;

package/lib/storage.mjs

@@ -31,7 +31,7 @@ const [
     MIME_JPEG, MIME_MOV, MIME_MPEG, MIME_MP4, MIME_MPG, MIME_AVI, MIME_WMV,
     MIME_MPEGPS, MIME_FLV, MIME_GIF, MIME_WEBP, MIME_PDF, MIME_AAC, MIME_FLAC,
     MIME_MP3, MIME_MPEGA, MIME_M4A, MIME_MPGA, MIME_OPUS, MIME_PCM, MIME_WAV,
-    MIME_WEBM, MIME_TGPP, MIME_PCM16, MIME_OGG,
+    MIME_WAVE, MIME_WEBM, MIME_TGPP, MIME_PCM16, MIME_OGG,
 ] = [
         'NULL', 'BASE64', 'BUFFER', 'FILE', 'STREAM', 'TEXT', 'JSON', 'utf8',
         'binary', 'BLOB', 'DATAURL', '0644', '0755', 'text/plain',
@@ -40,7 +40,8 @@ const [
         'video/avi', 'video/wmv', 'video/mpegps', 'video/x-flv', 'image/gif',
         'image/webp', 'application/pdf', 'audio/aac', 'audio/flac', 'audio/mp3',
         'audio/mpeg', 'audio/m4a', 'audio/mpga', 'audio/opus', 'audio/pcm',
-        'audio/wav', 'audio/webm', 'video/3gpp', 'audio/x-wav', 'audio/ogg',
+        'audio/wav', 'audio/wave', 'audio/webm', 'video/3gpp', 'audio/x-wav',
+        'audio/ogg',
     ];
 
 const [encodeBase64, encodeBinary, encodeNull]
@@ -551,6 +552,7 @@ export {
     MIME_TEXT,
     MIME_TGPP,
     MIME_WAV,
+    MIME_WAVE,
     MIME_WEBM,
     MIME_WEBP,
     MIME_WMV,

package/package.json

@@ -1,13 +1,13 @@
 {
     "name": "utilitas",
     "description": "Just another common utility for JavaScript.",
-    "version": "2001.1.136",
+    "version": "2001.1.139",
     "private": false,
     "homepage": "https://github.com/Leask/utilitas",
     "main": "index.mjs",
     "type": "module",
     "engines": {
-        "node": ">=20.x"
+        "node": ">=22.5.0"
     },
     "scripts": {
         "start": "node index.mjs",
@@ -30,19 +30,19 @@
         "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.1/xlsx-0.20.1.tgz"
     },
     "dependencies": {
-        "file-type": "^21.3.3",
-        "mathjs": "^15.1.1",
-        "uuid": "^13.0.0"
+        "file-type": "^22.0.1",
+        "mathjs": "^15.2.0",
+        "uuid": "^14.0.0"
     },
     "devDependencies": {
         "@ffmpeg-installer/ffmpeg": "^1.1.0",
         "@ffprobe-installer/ffprobe": "^2.1.2",
-        "@google-cloud/discoveryengine": "^2.5.3",
+        "@google-cloud/discoveryengine": "^2.6.0",
         "@google-cloud/storage": "^7.19.0",
-        "@google/genai": "^1.46.0",
+        "@google/genai": "^1.51.0",
         "@mozilla/readability": "github:mozilla/readability",
-        "@sentry/node": "^10.44.0",
-        "@sentry/profiling-node": "^10.44.0",
+        "@sentry/node": "^10.51.0",
+        "@sentry/profiling-node": "^10.51.0",
         "acme-client": "^5.4.0",
         "browserify-fs": "^1.0.0",
         "buffer": "^6.0.3",
@@ -51,34 +51,34 @@
         "fluent-ffmpeg": "^2.1.3",
         "form-data": "^4.0.5",
         "google-gax": "^5.0.6",
-        "ioredis": "^5.10.0",
-        "jsdom": "^29.0.0",
+        "ioredis": "^5.10.1",
+        "jsdom": "^29.1.0",
         "lorem-ipsum": "^2.0.8",
-        "mailgun.js": "^12.7.1",
-        "mailparser": "^3.9.4",
+        "mailgun.js": "^13.0.0",
+        "mailparser": "^3.9.8",
         "mime": "^4.1.0",
-        "mysql2": "^3.20.0",
+        "mysql2": "^3.22.3",
         "node-mailjet": "^6.0.11",
         "node-polyfill-webpack-plugin": "^4.1.0",
         "office-text-extractor": "^4.0.0",
-        "openai": "^6.32.0",
+        "openai": "^6.35.0",
         "pdf-lib": "^1.17.1",
-        "pdfjs-dist": "^5.5.207",
+        "pdfjs-dist": "^5.7.284",
         "pg": "^8.20.0",
         "pgvector": "^0.2.1",
         "ping": "^1.0.0",
         "process": "^0.11.10",
-        "puppeteer": "^24.39.1",
+        "puppeteer": "^24.42.0",
         "say": "^0.16.0",
         "telegraf": "^4.16.3",
         "telesignsdk": "^5.0.0",
         "tesseract.js": "^7.0.0",
-        "twilio": "^5.13.0",
+        "twilio": "^6.0.0",
         "url": "github:Leask/node-url",
         "webpack-cli": "^7.0.2",
         "whisper-node": "^1.1.1",
-        "wrangler": "^4.75.0",
+        "wrangler": "^4.86.0",
         "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.1/xlsx-0.20.1.tgz",
-        "youtube-transcript": "^1.3.0"
+        "youtube-transcript": "^1.3.1"
     }
 }