videobook-engine 4.2.0 → 5.3.2

package/dist/similarity.js

@@ -1,28 +1,26 @@
+import { modelIdentity } from "./model-identity.js";
+import { guardSearchProvider } from "./search-provider-access.js";
 import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
 import { readFile } from "node:fs/promises";
-import { spawn } from "node:child_process";
 import { mkdtemp, mkdir, readdir, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
 import * as path from "node:path";
-import { AutoProcessor, ClapAudioModelWithProjection, pipeline, RawImage, } from "@huggingface/transformers";
-import sharp from "sharp";
-import { Index, MetricKind, ScalarKind, } from "usearch";
+import { decodeModelImage } from "./media-image.js";
+import { runMediaProcess, checkMediaCancellation } from "./media-process.js";
 import { err, } from "./engine-types.js";
 import { resultOf, syncResultOf, } from "./context.js";
 import { EngineFault } from "./store.js";
-const DEFAULT_MODEL_ID = "Xenova/clip-vit-base-patch32";
-const DEFAULT_MODEL_REVISION = "d15189d7028b43f1d3e65039190477f6af591c2a";
-const DEFAULT_EMBEDDING_SPACE = "clip-vit-b32-q8-d15189d7028b43f1d3e65039190477f6af591c2a-v1";
+import { isolatedModelCall } from "./isolated-models.js";
+function providerOperationOptions(options) {
+    return {
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    };
+}
 const DEFAULT_DIMENSIONS = 512;
-const DEFAULT_AUDIO_MODEL_ID = "Xenova/clap-htsat-unfused";
-const DEFAULT_AUDIO_MODEL_REVISION = "c28f2883575e590e04d3146ff0713c2448d691ba";
-const DEFAULT_AUDIO_EMBEDDING_SPACE = "clap-htsat-unfused-q8-c28f2883575e590e04d3146ff0713c2448d691ba-audio-v1";
 const DEFAULT_AUDIO_DIMENSIONS = 512;
 const DEFAULT_AUDIO_SAMPLE_RATE = 48_000;
 const DEFAULT_AUDIO_MAX_SAMPLES = 480_000;
-const DEFAULT_TEXT_MODEL_ID = "onnx-community/all-MiniLM-L6-v2-ONNX";
-const DEFAULT_TEXT_MODEL_REVISION = "aff7a1dc4e8a1ea593e6ea21e95c22ef0a25966f";
-const DEFAULT_TEXT_EMBEDDING_SPACE = "all-minilm-l6-v2-q4-aff7a1dc4e8a1ea593e6ea21e95c22ef0a25966f-text-v1";
 const DEFAULT_TEXT_DIMENSIONS = 384;
 const DEFAULT_TEXT_MAX_BYTES = 1024 * 1024;
 const DEFAULT_TEXT_MAX_CHUNKS = 256;
@@ -37,6 +35,16 @@ const TEXT_ARTIFACT_KINDS = new Set([
     "scene",
     "final",
 ]);
+let transformersModule;
+let usearchModule;
+function loadTransformers() {
+    transformersModule ??= import("./transformers-runtime.js");
+    return transformersModule;
+}
+function loadUsearch() {
+    usearchModule ??= createRequire(import.meta.url)("usearch");
+    return usearchModule;
+}
 export function createSimilarityApi(context) {
     if (!context.config.similarity)
         return disabledSimilarityApi();
@@ -50,17 +58,26 @@ class LocalSimilarityApi {
     indexes = new Map();
     constructor(context, config) {
         this.context = context;
-        this.provider = config.provider ?? new LocalClipProvider(context, config);
+        this.provider = config.provider
+            ? guardSearchProvider(config.provider, config.providerConsent).provider
+            : isolatedCompatibilityProvider("compat-clip", context, config);
         this.audioProvider = config.audio
-            ? config.audio.provider ??
-                new LocalClapAudioProvider(context, config, config.audio)
+            ? config.audio.provider
+                ? guardSearchProvider(config.audio.provider, config.audio.providerConsent).provider
+                : isolatedCompatibilityProvider("compat-clap", context, config)
             : null;
         this.textProvider = config.text
-            ? config.text.provider ?? new LocalTextProvider(context, config, config.text)
+            ? config.text.provider
+                ? guardSearchProvider(config.text.provider, config.text.providerConsent).provider
+                : isolatedCompatibilityProvider("compat-text", context, config)
             : null;
     }
+    localResult(operation) {
+        return this.context.withLocalMedia(() => resultOf(operation));
+    }
     async prepare(options = {}) {
-        return resultOf(async () => {
+        return this.localResult(async () => {
+            checkMediaCancellation(options);
             const kinds = options.kind
                 ? [options.kind]
                 : [
@@ -74,13 +91,13 @@ class LocalSimilarityApi {
             for (const kind of kinds) {
                 if (kind === "text") {
                     const provider = this.requireTextProvider();
-                    await provider.prepare();
+                    await provider.prepare(providerOperationOptions(options));
                     spaces.text = provider.embeddingSpace;
                 }
                 else {
                     const provider = this.providerFor(kind);
                     if (!preparedMedia.has(provider)) {
-                        await provider.prepare();
+                        await provider.prepare(providerOperationOptions(options));
                         preparedMedia.add(provider);
                     }
                     spaces[kind] = provider.embeddingSpace;
@@ -93,7 +110,8 @@ class LocalSimilarityApi {
         });
     }
     async index(artifactReference, options = {}) {
-        return resultOf(async () => {
+        return this.localResult(async () => {
+            checkMediaCancellation(options);
             const artifact = this.context.artifactRow(artifactReference);
             const kind = similarityKind(artifact);
             if (kind === "text") {
@@ -103,7 +121,8 @@ class LocalSimilarityApi {
         });
     }
     async rebuild(options = {}) {
-        return resultOf(async () => {
+        return this.localResult(async () => {
+            checkMediaCancellation(options);
             const allowedKinds = options.kind
                 ? [options.kind]
                 : [
@@ -114,7 +133,7 @@ class LocalSimilarityApi {
                 ];
             const artifactKinds = allowedKinds.flatMap((kind) => kind === "text" ? [...TEXT_ARTIFACT_KINDS] : [kind]);
             const artifactRows = this.context.store.db
-                .prepare(`SELECT artifact_id, slug, kind, created_at
+                .prepare(`SELECT artifact_id, label, kind, created_at
            FROM artifacts
            WHERE kind IN (${artifactKinds.map(() => "?").join(", ")})
            ORDER BY created_at, artifact_id`)
@@ -126,9 +145,7 @@ class LocalSimilarityApi {
                     continue;
                 if (kind === "text" && !this.hasTextSource(artifact.artifact_id))
                     continue;
-                const result = await this.index(artifact.artifact_id, {
-                    force: options.force,
-                });
+                const result = await this.index(artifact.artifact_id, options);
                 if (!result.ok)
                     throw new EngineFault(result.error);
                 indexed.push(result.value);
@@ -227,7 +244,8 @@ class LocalSimilarityApi {
         });
     }
     async findSimilar(artifactReference, options = {}) {
-        return resultOf(async () => {
+        return this.localResult(async () => {
+            checkMediaCancellation(options);
             const artifact = this.context.artifactRow(artifactReference);
             const kind = similarityKind(artifact);
             if (kind === "text") {
@@ -237,8 +255,9 @@ class LocalSimilarityApi {
         });
     }
     async findSimilarText(query, options = {}) {
-        return resultOf(async () => {
+        return this.localResult(async () => {
             const provider = this.requireTextProvider();
+            checkMediaCancellation(options);
             const normalizedQuery = normalizePlainText(query);
             if (normalizedQuery.text.length === 0) {
                 throw new EngineFault({
@@ -253,7 +272,7 @@ class LocalSimilarityApi {
                     message: `Text similarity queries cannot exceed ${maxBytes} bytes`,
                 });
             }
-            const chunks = await this.embedText(normalizedQuery.text);
+            const chunks = await this.embedText(normalizedQuery.text, options);
             return this.searchText(null, null, normalizedQuery.contentHash, chunks, options, provider);
         });
     }
@@ -277,7 +296,8 @@ class LocalSimilarityApi {
                 frameCount: reusable.frame_count,
                 reused: true,
             }
-            : await this.embedMediaSource(source);
+            : await this.embedMediaSource(source, options);
+        checkMediaCancellation(options);
         const row = this.context.store.runtime((now) => {
             if (existing) {
                 this.context.store.db
@@ -320,7 +340,7 @@ class LocalSimilarityApi {
                 endOffset: chunk.end_offset,
                 vector: vectorFromBlob(chunk),
             }))
-            : await this.embedText(normalizedSource.text);
+            : await this.embedText(normalizedSource.text, options);
         const maxChunks = checkedTextMaxChunks(this.context.config.similarity?.text);
         if (embeddedChunks.length > maxChunks) {
             throw new EngineFault({
@@ -330,6 +350,7 @@ class LocalSimilarityApi {
         }
         this.validateTextChunks(normalizedSource.text, embeddedChunks, provider.dimensions);
         this.indexes.delete(indexKey("text", provider.embeddingSpace));
+        checkMediaCancellation(options);
         const row = this.context.store.runtime((now) => {
             let documentId;
             if (existing) {
@@ -370,7 +391,7 @@ class LocalSimilarityApi {
         if (!query) {
             throw new EngineFault({
                 code: "NOT_READY",
-                message: `Artifact is not indexed for similarity: ${artifact.slug}`,
+                message: `Artifact is not indexed for similarity: ${artifact.artifact_id}`,
                 details: { artifactId: artifact.artifact_id },
             });
         }
@@ -389,7 +410,7 @@ class LocalSimilarityApi {
         if (!query) {
             throw new EngineFault({
                 code: "NOT_READY",
-                message: `Artifact is not indexed for similarity: ${artifact.slug}`,
+                message: `Artifact is not indexed for similarity: ${artifact.artifact_id}`,
                 details: { artifactId: artifact.artifact_id },
             });
         }
@@ -416,7 +437,7 @@ class LocalSimilarityApi {
                 : cosine(queryVector, vectorFromBlob(candidate));
             return {
                 artifactId: candidate.artifact_id,
-                slug: candidate.slug ?? candidate.artifact_id,
+                ...(candidate.label ? { label: candidate.label } : {}),
                 kind: candidate.kind,
                 score: global,
                 exactBytes,
@@ -513,7 +534,7 @@ class LocalSimilarityApi {
             const queryChunk = queryChunks[match.queryChunkIndex];
             return {
                 artifactId: match.chunk.artifact_id,
-                slug: match.chunk.slug ?? match.chunk.artifact_id,
+                ...(match.chunk.label ? { label: match.chunk.label } : {}),
                 kind: "text",
                 score: match.score,
                 exactBytes: match.exactBytes,
@@ -540,36 +561,37 @@ class LocalSimilarityApi {
             left.artifactId.localeCompare(right.artifactId))
             .slice(0, limit);
     }
-    async embedMediaSource(source) {
+    async embedMediaSource(source, options) {
         const localPath = await this.context.objects.ensureLocalPath(source.object_hash);
         if (source.kind === "audio") {
             const provider = this.requireAudioProvider();
-            await provider.prepare();
+            await provider.prepare(providerOperationOptions(options));
             return {
-                vector: normalized(await provider.embedAudio(localPath)),
+                vector: normalized(await provider.embedAudio(localPath, providerOperationOptions(options))),
                 frameCount: null,
                 reused: false,
             };
         }
-        await this.provider.prepare();
+        await this.provider.prepare(providerOperationOptions(options));
         if (source.kind === "image") {
             return {
-                vector: normalized(await this.provider.embedImage(localPath)),
+                vector: normalized(await this.provider.embedImage(localPath, providerOperationOptions(options))),
                 frameCount: null,
                 reused: false,
             };
         }
-        const video = await this.provider.embedVideo(localPath);
+        const video = await this.provider.embedVideo(localPath, providerOperationOptions(options));
         return {
             vector: normalized(video.vector),
             frameCount: video.frameCount,
             reused: false,
         };
     }
-    async embedText(text) {
+    async embedText(text, options) {
         const provider = this.requireTextProvider();
-        await provider.prepare();
-        const chunks = await provider.embedText(text);
+        await provider.prepare(providerOperationOptions(options));
+        const chunks = await provider.embedText(text, providerOperationOptions(options));
+        checkMediaCancellation(options);
         this.validateTextChunks(text, chunks, provider.dimensions);
         const maxChunks = checkedTextMaxChunks(this.context.config.similarity?.text);
         if (chunks.length > maxChunks) {
@@ -665,13 +687,13 @@ class LocalSimilarityApi {
         if (sources.length === 0) {
             throw new EngineFault({
                 code: "INVALID_INPUT",
-                message: `No supported original ${kind} file for ${artifact.slug}`,
+                message: `No supported original ${kind} file for ${artifact.artifact_id}`,
             });
         }
         if (kind === "text" && sources.length > 1) {
             throw new EngineFault({
                 code: "INVALID_INPUT",
-                message: `Multiple supported original ${kind} files for ${artifact.slug}`,
+                message: `Multiple supported original ${kind} files for ${artifact.artifact_id}`,
                 details: { paths: sources.map((source) => source.path) },
             });
         }
@@ -727,7 +749,7 @@ class LocalSimilarityApi {
         return this.context.store.db
             .prepare(`SELECT e.id, e.artifact_id, e.kind, e.source_path,
                 e.object_hash, e.embedding_space, e.dimensions, e.vector_blob,
-                e.frame_count, e.updated_at, a.slug
+                e.frame_count, e.updated_at, a.label AS label
          FROM runtime_similarity_embeddings e
          JOIN artifacts a ON a.artifact_id=e.artifact_id
          WHERE e.kind=? AND e.embedding_space=?
@@ -749,6 +771,7 @@ class LocalSimilarityApi {
         const current = this.indexes.get(key);
         if (current)
             return current;
+        const { Index, MetricKind, ScalarKind } = loadUsearch();
         const index = new Index({
             dimensions,
             metric: MetricKind.Cos,
@@ -781,6 +804,7 @@ class LocalSimilarityApi {
         const current = this.indexes.get(key);
         if (current)
             return current;
+        const { Index, MetricKind, ScalarKind } = loadUsearch();
         const index = new Index({
             dimensions,
             metric: MetricKind.Cos,
@@ -872,7 +896,7 @@ class LocalSimilarityApi {
                 c.embedding_space, c.chunk_index, c.start_offset,
                 c.end_offset, c.chunk_text, c.dimensions, c.vector_blob,
                 c.updated_at, d.source_path, d.object_hash, d.content_hash,
-                a.slug
+                a.label AS label
          FROM runtime_text_similarity_chunks c
          JOIN runtime_text_similarity_documents d ON d.id=c.document_id
          JOIN artifacts a ON a.artifact_id=c.artifact_id
@@ -921,36 +945,68 @@ class LocalSimilarityApi {
         return this.textProvider;
     }
 }
+function isolatedCompatibilityProvider(kind, context, config) {
+    const local = kind === "compat-clap" ? config.audio : kind === "compat-text" ? config.text : config;
+    const modelId = local.modelId?.startsWith(".") ? path.resolve(local.modelId) : local.modelId;
+    const modelCacheDir = local.modelCacheDir ?? config.modelCacheDir ?? path.join(context.config.dataDir, "similarity-models");
+    const configuration = { kind, modelCacheDir, modelId, modelRevision: local.modelRevision, allowModelDownload: local.allowModelDownload ?? config.allowModelDownload,
+        ffmpegPath: kind === "compat-clap" ? config.audio.ffmpegPath ?? config.ffmpegPath : config.ffmpegPath,
+        ffprobePath: config.ffprobePath };
+    return {
+        networkAccess: Object.freeze({ modelDownloads: configuration.allowModelDownload === true, inference: false }),
+        get embeddingSpace() { return modelIdentity(kind, configuration).embeddingSpace; },
+        dimensions: kind === "compat-text" ? DEFAULT_TEXT_DIMENSIONS : DEFAULT_DIMENSIONS,
+        async prepare(options = {}) { await isolatedModelCall(configuration, { method: "prepare" }, options); },
+        embedImage(sourcePath, options = {}) { return isolatedModelCall(configuration, { method: "embedImage", sourcePath }, options); },
+        embedAudio(sourcePath, options = {}) { return isolatedModelCall(configuration, { method: "embedAudio", sourcePath }, options); },
+        embedVideo(sourcePath, options = {}) { return isolatedModelCall(configuration, { method: "embedVideo", sourcePath }, options); },
+        embedText(text, options = {}) { return isolatedModelCall(configuration, { method: "embedText", text }, options); },
+    };
+}
+export function createInlineSimilarityProvider(configuration) {
+    const common = { modelCacheDir: configuration.modelCacheDir, allowModelDownload: configuration.allowModelDownload,
+        ffmpegPath: configuration.ffmpegPath, ffprobePath: configuration.ffprobePath };
+    const model = { ...common, modelId: configuration.modelId, modelRevision: configuration.modelRevision };
+    if (configuration.kind === "compat-clip")
+        return new LocalClipProvider(process.cwd(), model);
+    if (configuration.kind === "compat-clap")
+        return new LocalClapAudioProvider(process.cwd(), common, model);
+    return new LocalTextProvider(process.cwd(), common, model);
+}
 class LocalClipProvider {
-    context;
+    dataDir;
     config;
-    embeddingSpace = DEFAULT_EMBEDDING_SPACE;
+    get networkAccess() { return { modelDownloads: this.config.allowModelDownload === true, inference: false }; }
+    get embeddingSpace() { return modelIdentity("compat-clip", this.config).embeddingSpace; }
     dimensions = DEFAULT_DIMENSIONS;
     embedder = null;
-    constructor(context, config) {
-        this.context = context;
+    constructor(dataDir, config) {
+        this.dataDir = dataDir;
         this.config = config;
     }
-    async prepare() {
+    async prepare(options = {}) {
+        checkMediaCancellation(options);
         await this.loadEmbedder();
+        checkMediaCancellation(options);
     }
-    async embedImage(sourcePath) {
-        const vectors = await this.embedImages([sourcePath]);
+    async embedImage(sourcePath, options = {}) {
+        const vectors = await this.embedImages([sourcePath], options);
         const vector = vectors[0];
         if (!vector)
             throw new Error("Image embedder returned no vector");
         return vector;
     }
-    async embedVideo(sourcePath) {
-        const duration = await probeDuration(this.config.ffprobePath ?? "ffprobe", sourcePath);
+    async embedVideo(sourcePath, options = {}) {
+        const duration = await probeDuration(this.config.ffprobePath ?? "ffprobe", sourcePath, options);
         const frameCount = Math.min(120, Math.max(1, Math.ceil(duration / 2)));
-        const framesDir = await mkdtemp(path.join(tmpdir(), "videobook-sim-"));
+        const framesDir = await mkdtemp(path.join(process.cwd(), "videobook-sim-"));
         try {
             const fps = `${frameCount}/${Math.max(duration, 0.001)}`;
             await runCommand(this.config.ffmpegPath ?? "ffmpeg", [
                 "-hide_banner",
                 "-loglevel",
                 "error",
+                "-nostdin", "-protocol_whitelist", "file,pipe",
                 "-i",
                 sourcePath,
                 "-an",
@@ -959,7 +1015,7 @@ class LocalClipProvider {
                 "-frames:v",
                 String(frameCount),
                 path.join(framesDir, "frame-%04d.png"),
-            ]);
+            ], options);
             const frames = (await readdir(framesDir))
                 .filter((name) => name.endsWith(".png"))
                 .sort()
@@ -972,7 +1028,7 @@ class LocalClipProvider {
             }
             const vectors = [];
             for (let offset = 0; offset < frames.length; offset += 8) {
-                vectors.push(...(await this.embedImages(frames.slice(offset, offset + 8))));
+                vectors.push(...(await this.embedImages(frames.slice(offset, offset + 8), options)));
             }
             return { vector: normalizedCentroid(vectors), frameCount: vectors.length };
         }
@@ -983,34 +1039,35 @@ class LocalClipProvider {
     async loadEmbedder() {
         if (this.embedder)
             return this.embedder;
-        const dataDir = this.context.config.dataDir;
+        const dataDir = this.dataDir;
         if (!dataDir)
             throw new Error("Similarity requires a configured dataDir");
         const cacheDir = this.config.modelCacheDir ?? path.join(dataDir, "similarity-models");
         await mkdir(cacheDir, { recursive: true });
-        const modelId = this.config.modelId ?? DEFAULT_MODEL_ID;
+        const { modelId, modelRevision } = modelIdentity("compat-clip", this.config);
         try {
+            const { pipeline } = await loadTransformers();
             this.embedder = await pipeline("image-feature-extraction", modelId, {
                 dtype: "q8",
                 cache_dir: cacheDir,
-                local_files_only: this.config.allowModelDownload === false,
-                ...(modelId === DEFAULT_MODEL_ID
-                    ? { revision: DEFAULT_MODEL_REVISION }
-                    : {}),
+                local_files_only: this.config.allowModelDownload !== true,
+                ...(modelRevision ? { revision: modelRevision } : {}),
             });
             return this.embedder;
         }
         catch (error) {
             throw new EngineFault({
-                code: this.config.allowModelDownload === false ? "OFFLINE" : "FEATURE_UNAVAILABLE",
+                code: this.config.allowModelDownload !== true ? "OFFLINE" : "FEATURE_UNAVAILABLE",
                 message: `Unable to load local similarity model: ${errorMessage(error)}`,
             });
         }
     }
-    async embedImages(sourcePaths) {
+    async embedImages(sourcePaths, options) {
         const embedder = await this.loadEmbedder();
-        const images = await Promise.all(sourcePaths.map(readNormalizedImage));
+        checkMediaCancellation(options);
+        const images = await Promise.all(sourcePaths.map((source) => readNormalizedImage(source, options)));
         const output = await embedder(images);
+        checkMediaCancellation(options);
         const batch = output.dims[0];
         const dimensions = output.dims[1];
         if (batch !== sourcePaths.length || dimensions !== this.dimensions) {
@@ -1025,32 +1082,33 @@ class LocalClipProvider {
     }
 }
 class LocalClapAudioProvider {
-    context;
+    dataDir;
     sharedConfig;
     config;
-    embeddingSpace;
+    get networkAccess() { return { modelDownloads: (this.config.allowModelDownload ?? this.sharedConfig.allowModelDownload) === true, inference: false }; }
+    get embeddingSpace() { return modelIdentity("compat-clap", this.config).embeddingSpace; }
     dimensions = DEFAULT_AUDIO_DIMENSIONS;
     processor = null;
     model = null;
     sampleRate = DEFAULT_AUDIO_SAMPLE_RATE;
     maxSamples = DEFAULT_AUDIO_MAX_SAMPLES;
-    constructor(context, sharedConfig, config) {
-        this.context = context;
+    constructor(dataDir, sharedConfig, config) {
+        this.dataDir = dataDir;
         this.sharedConfig = sharedConfig;
         this.config = config;
-        this.embeddingSpace =
-            config.modelId && config.modelId !== DEFAULT_AUDIO_MODEL_ID
-                ? `audio-${config.modelId.replace(/[^a-zA-Z0-9]+/g, "-")}-v1`
-                : DEFAULT_AUDIO_EMBEDDING_SPACE;
     }
-    async prepare() {
+    async prepare(options = {}) {
+        checkMediaCancellation(options);
         await this.loadModel();
+        checkMediaCancellation(options);
     }
-    async embedAudio(sourcePath) {
+    async embedAudio(sourcePath, options = {}) {
+        checkMediaCancellation(options);
         const { processor, model } = await this.loadModel();
-        const audio = await decodeAudioToMono(this.config.ffmpegPath ?? this.sharedConfig.ffmpegPath ?? "ffmpeg", sourcePath, this.sampleRate, this.maxSamples);
+        const audio = await decodeAudioToMono(this.config.ffmpegPath ?? this.sharedConfig.ffmpegPath ?? "ffmpeg", sourcePath, this.sampleRate, this.maxSamples, options);
         const inputs = await processor(audio);
         const output = await model(inputs);
+        checkMediaCancellation(options);
         const dimensions = output.audio_embeds.dims;
         if (dimensions.length !== 2 ||
             dimensions[0] !== 1 ||
@@ -1064,29 +1122,28 @@ class LocalClapAudioProvider {
         if (this.processor && this.model) {
             return { processor: this.processor, model: this.model };
         }
-        const dataDir = this.context.config.dataDir;
+        const dataDir = this.dataDir;
         if (!dataDir)
             throw new Error("Audio similarity requires a configured dataDir");
         const cacheDir = this.config.modelCacheDir ??
             this.sharedConfig.modelCacheDir ??
             path.join(dataDir, "similarity-models");
         await mkdir(cacheDir, { recursive: true });
-        const modelId = this.config.modelId ?? DEFAULT_AUDIO_MODEL_ID;
+        const { modelId, modelRevision } = modelIdentity("compat-clap", this.config);
         const allowDownload = this.config.allowModelDownload ??
             this.sharedConfig.allowModelDownload;
-        const pinned = modelId === DEFAULT_AUDIO_MODEL_ID
-            ? { revision: DEFAULT_AUDIO_MODEL_REVISION }
-            : {};
+        const pinned = modelRevision ? { revision: modelRevision } : {};
         try {
+            const { AutoProcessor, ClapAudioModelWithProjection } = await loadTransformers();
             const processor = await AutoProcessor.from_pretrained(modelId, {
                 cache_dir: cacheDir,
-                local_files_only: allowDownload === false,
+                local_files_only: allowDownload !== true,
                 ...pinned,
             });
             const model = await ClapAudioModelWithProjection.from_pretrained(modelId, {
                 dtype: "q8",
                 cache_dir: cacheDir,
-                local_files_only: allowDownload === false,
+                local_files_only: allowDownload !== true,
                 ...pinned,
             });
             const featureConfig = processor.feature_extractor?.config;
@@ -1098,35 +1155,37 @@ class LocalClapAudioProvider {
         }
         catch (error) {
             throw new EngineFault({
-                code: allowDownload === false ? "OFFLINE" : "FEATURE_UNAVAILABLE",
+                code: allowDownload !== true ? "OFFLINE" : "FEATURE_UNAVAILABLE",
                 message: `Unable to load local audio similarity model: ${errorMessage(error)}`,
             });
         }
     }
 }
 class LocalTextProvider {
-    context;
+    dataDir;
     sharedConfig;
     config;
-    embeddingSpace;
+    get networkAccess() { return { modelDownloads: (this.config.allowModelDownload ?? this.sharedConfig.allowModelDownload) === true, inference: false }; }
+    get embeddingSpace() { return modelIdentity("compat-text", this.config).embeddingSpace; }
     dimensions = DEFAULT_TEXT_DIMENSIONS;
     embedder = null;
-    constructor(context, sharedConfig, config) {
-        this.context = context;
+    constructor(dataDir, sharedConfig, config) {
+        this.dataDir = dataDir;
         this.sharedConfig = sharedConfig;
         this.config = config;
-        this.embeddingSpace = config.modelId && config.modelId !== DEFAULT_TEXT_MODEL_ID
-            ? `text-${config.modelId.replace(/[^a-zA-Z0-9]+/g, "-")}-v1`
-            : DEFAULT_TEXT_EMBEDDING_SPACE;
     }
-    async prepare() {
+    async prepare(options = {}) {
+        checkMediaCancellation(options);
         await this.loadEmbedder();
+        checkMediaCancellation(options);
     }
-    async embedText(text) {
+    async embedText(text, options = {}) {
+        checkMediaCancellation(options);
         const embedder = await this.loadEmbedder();
         const ranges = makeTextRanges(text, embedder.tokenizer);
         const chunks = [];
         for (let offset = 0; offset < ranges.length; offset += 32) {
+            checkMediaCancellation(options);
             const batchRanges = ranges.slice(offset, offset + 32);
             const output = await embedder(batchRanges.map((range) => text.slice(range.startOffset, range.endOffset)), { pooling: "mean", normalize: true });
             const batch = output.dims[0];
@@ -1148,30 +1207,29 @@ class LocalTextProvider {
     async loadEmbedder() {
         if (this.embedder)
             return this.embedder;
-        const dataDir = this.context.config.dataDir;
+        const dataDir = this.dataDir;
         if (!dataDir)
             throw new Error("Text similarity requires a configured dataDir");
         const cacheDir = this.config.modelCacheDir ??
             this.sharedConfig.modelCacheDir ??
             path.join(dataDir, "similarity-models");
         await mkdir(cacheDir, { recursive: true });
-        const modelId = this.config.modelId ?? DEFAULT_TEXT_MODEL_ID;
+        const { modelId, modelRevision } = modelIdentity("compat-text", this.config);
         const allowDownload = this.config.allowModelDownload ??
             this.sharedConfig.allowModelDownload;
         try {
+            const { pipeline } = await loadTransformers();
             this.embedder = await pipeline("feature-extraction", modelId, {
                 dtype: "q4",
                 cache_dir: cacheDir,
-                local_files_only: allowDownload === false,
-                ...(modelId === DEFAULT_TEXT_MODEL_ID
-                    ? { revision: DEFAULT_TEXT_MODEL_REVISION }
-                    : {}),
+                local_files_only: allowDownload !== true,
+                ...(modelRevision ? { revision: modelRevision } : {}),
             });
             return this.embedder;
         }
         catch (error) {
             throw new EngineFault({
-                code: allowDownload === false ? "OFFLINE" : "FEATURE_UNAVAILABLE",
+                code: allowDownload !== true ? "OFFLINE" : "FEATURE_UNAVAILABLE",
                 message: `Unable to load local text similarity model: ${errorMessage(error)}`,
             });
         }
@@ -1205,22 +1263,11 @@ function similarityKind(artifact) {
         message: `Similarity supports image, video, audio, and text artifacts, not ${artifact.kind}`,
     });
 }
-async function readNormalizedImage(sourcePath) {
-    const decoded = await sharp(sourcePath, { animated: false })
-        .rotate()
-        .toColourspace("srgb")
-        .removeAlpha()
-        .raw()
-        .toBuffer({ resolveWithObject: true });
-    if (decoded.info.width <= 0 || decoded.info.height <= 0) {
-        throw new Error(`Invalid image dimensions: ${sourcePath}`);
-    }
-    if (decoded.info.channels !== 3) {
-        throw new Error(`Expected RGB image after conversion: ${sourcePath}`);
-    }
+async function readNormalizedImage(sourcePath, options = {}) {
+    const [{ RawImage }, decoded] = await Promise.all([loadTransformers(), decodeModelImage(sourcePath, options)]);
     return new RawImage(decoded.data, decoded.info.width, decoded.info.height, 3);
 }
-async function probeDuration(ffprobePath, sourcePath) {
+async function probeDuration(ffprobePath, sourcePath, options) {
     const result = await runCommand(ffprobePath, [
         "-v",
         "error",
@@ -1228,8 +1275,9 @@ async function probeDuration(ffprobePath, sourcePath) {
         "format=duration",
         "-of",
         "default=noprint_wrappers=1:nokey=1",
+        "-protocol_whitelist", "file,pipe",
         sourcePath,
-    ]);
+    ], { ...options, maxStdoutBytes: 64 * 1024 });
     const duration = Number.parseFloat(result.stdout.trim());
     if (!Number.isFinite(duration) || duration <= 0) {
         throw new EngineFault({
@@ -1239,12 +1287,13 @@ async function probeDuration(ffprobePath, sourcePath) {
     }
     return duration;
 }
-async function decodeAudioToMono(ffmpegPath, sourcePath, sampleRate, maxSamples) {
-    const output = await runBinaryCommand(ffmpegPath, [
+async function decodeAudioToMono(ffmpegPath, sourcePath, sampleRate, maxSamples, options) {
+    const output = await runMediaProcess(ffmpegPath, [
         "-hide_banner",
         "-loglevel",
         "error",
         "-nostdin",
+        "-protocol_whitelist", "file,pipe",
         "-i",
         sourcePath,
         "-map",
@@ -1261,7 +1310,7 @@ async function decodeAudioToMono(ffmpegPath, sourcePath, sampleRate, maxSamples)
         "-acodec",
         "pcm_f32le",
         "pipe:1",
-    ]);
+    ], { ...options, maxStdoutBytes: maxSamples * Float32Array.BYTES_PER_ELEMENT });
     if (output.stdout.byteLength === 0) {
         throw new EngineFault({
             code: "INVALID_INPUT",
@@ -1278,42 +1327,13 @@ async function decodeAudioToMono(ffmpegPath, sourcePath, sampleRate, maxSamples)
         ? decoded.slice(0, maxSamples)
         : decoded;
 }
-async function runCommand(command, args) {
-    const output = await runBinaryCommand(command, args);
+async function runCommand(command, args, options = {}) {
+    const output = await runMediaProcess(command, args, options);
     return {
         stdout: output.stdout.toString("utf8"),
         stderr: output.stderr,
     };
 }
-function runBinaryCommand(command, args) {
-    return new Promise((resolve, reject) => {
-        const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
-        const stdout = [];
-        const stderr = [];
-        child.stdout.on("data", (chunk) => stdout.push(chunk));
-        child.stderr.on("data", (chunk) => stderr.push(chunk));
-        child.once("error", (error) => {
-            reject(new EngineFault({
-                code: "FEATURE_UNAVAILABLE",
-                message: `Unable to start ${command}: ${errorMessage(error)}`,
-            }));
-        });
-        child.once("close", (code) => {
-            const output = {
-                stdout: Buffer.concat(stdout),
-                stderr: Buffer.concat(stderr).toString("utf8"),
-            };
-            if (code === 0) {
-                resolve(output);
-                return;
-            }
-            reject(new EngineFault({
-                code: "INVALID_INPUT",
-                message: `${command} exited with code ${code}: ${output.stderr.trim()}`,
-            }));
-        });
-    });
-}
 function normalizePlainText(raw) {
     const text = raw
         .replace(/^\uFEFF/, "")