@camstack/addon-embedding-encoder 0.1.1

package/dist/index.js

@@ -0,0 +1,959 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  EmbeddingEncoderAddon: () => EmbeddingEncoderAddon
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/addon/index.ts
+var import_types2 = require("@camstack/types");
+var import_core = require("@camstack/core");
+
+// src/catalogs/embedding-models.ts
+var CLIP_IMAGE_MODELS = [
+  {
+    id: "clip-vit-b32",
+    name: "CLIP ViT-B/32",
+    description: "OpenAI CLIP ViT-B/32 \u2014 fast, 512-dim, int8 quantized (85 MB)",
+    inputSize: { width: 224, height: 224 },
+    labels: [],
+    inputLayout: "nchw",
+    inputNormalization: "none",
+    formats: {
+      onnx: {
+        url: "https://huggingface.co/Xenova/clip-vit-base-patch32/resolve/main/onnx/vision_model_quantized.onnx",
+        sizeMB: 85
+      }
+    }
+  },
+  {
+    id: "clip-vit-b16",
+    name: "CLIP ViT-B/16",
+    description: "OpenAI CLIP ViT-B/16 \u2014 higher accuracy, 512-dim, int8 quantized (83 MB)",
+    inputSize: { width: 224, height: 224 },
+    labels: [],
+    inputLayout: "nchw",
+    inputNormalization: "none",
+    formats: {
+      onnx: {
+        url: "https://huggingface.co/Xenova/clip-vit-base-patch16/resolve/main/onnx/vision_model_quantized.onnx",
+        sizeMB: 83
+      }
+    }
+  },
+  {
+    id: "siglip2-b16-256",
+    name: "SigLIP2 Base/16 256",
+    description: "Google SigLIP2 \u2014 superior scene understanding, 768-dim, int8 quantized (90 MB)",
+    inputSize: { width: 256, height: 256 },
+    labels: [],
+    inputLayout: "nchw",
+    inputNormalization: "none",
+    formats: {
+      onnx: {
+        url: "https://huggingface.co/onnx-community/siglip2-base-patch16-256-ONNX/resolve/main/onnx/vision_model_quantized.onnx",
+        sizeMB: 90
+      }
+    }
+  }
+];
+var CLIP_TEXT_MODELS = [
+  {
+    id: "clip-vit-b32-text",
+    name: "CLIP ViT-B/32 Text Encoder",
+    description: "Text encoder for CLIP ViT-B/32, int8 quantized (62 MB)",
+    inputSize: { width: 0, height: 0 },
+    labels: [],
+    formats: {
+      onnx: {
+        url: "https://huggingface.co/Xenova/clip-vit-base-patch32/resolve/main/onnx/text_model_quantized.onnx",
+        sizeMB: 62
+      }
+    }
+  },
+  {
+    id: "clip-vit-b16-text",
+    name: "CLIP ViT-B/16 Text Encoder",
+    description: "Text encoder for CLIP ViT-B/16, int8 quantized (62 MB)",
+    inputSize: { width: 0, height: 0 },
+    labels: [],
+    formats: {
+      onnx: {
+        url: "https://huggingface.co/Xenova/clip-vit-base-patch16/resolve/main/onnx/text_model_quantized.onnx",
+        sizeMB: 62
+      }
+    }
+  },
+  {
+    id: "siglip2-b16-256-text",
+    name: "SigLIP2 Base/16 256 Text Encoder",
+    description: "Text encoder for SigLIP2, int8 quantized (270 MB)",
+    inputSize: { width: 0, height: 0 },
+    labels: [],
+    formats: {
+      onnx: {
+        url: "https://huggingface.co/onnx-community/siglip2-base-patch16-256-ONNX/resolve/main/onnx/text_model_quantized.onnx",
+        sizeMB: 270
+      }
+    }
+  }
+];
+
+// src/shared/noop-logger.ts
+var noop = () => {
+};
+function createNoopLogger() {
+  const logger = {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    child: () => logger,
+    withTags: (_tags) => logger
+  };
+  return logger;
+}
+
+// src/shared/node-raw-tensor-engine.ts
+var path = __toESM(require("path"));
+var BACKEND_TO_DEVICE = {
+  cpu: "cpu",
+  coreml: "gpu-mps",
+  cuda: "gpu-cuda",
+  tensorrt: "tensorrt"
+};
+var NodeRawTensorEngine = class {
+  constructor(modelPath, backend, logger) {
+    this.modelPath = modelPath;
+    this.backend = backend;
+    this.device = BACKEND_TO_DEVICE[backend] ?? "cpu";
+    this.log = logger ?? createNoopLogger();
+  }
+  modelPath;
+  backend;
+  runtime = "onnx";
+  device;
+  session = null;
+  log;
+  async initialize() {
+    const ort = await import("onnxruntime-node");
+    const provider = this.backend === "coreml" ? "coreml" : this.backend === "cuda" ? "cuda" : "cpu";
+    const absModelPath = path.isAbsolute(this.modelPath) ? this.modelPath : path.resolve(process.cwd(), this.modelPath);
+    this.session = await ort.InferenceSession.create(absModelPath, {
+      executionProviders: [provider]
+    });
+    this.log.info("ONNX session loaded", { meta: { modelPath: absModelPath, backend: this.backend, provider } });
+  }
+  async run(input, inputShape) {
+    if (!this.session) {
+      throw new Error("NodeRawTensorEngine: not initialized \u2014 call initialize() first");
+    }
+    const ort = await import("onnxruntime-node");
+    const sess = this.session;
+    const inputName = sess.inputNames[0];
+    const tensor = new ort.Tensor("float32", input, [...inputShape]);
+    const feeds = { [inputName]: tensor };
+    const start = Date.now();
+    let results;
+    try {
+      results = await sess.run(feeds);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.log.error("Inference failed", { meta: { error: error.message } });
+      throw error;
+    }
+    const outputName = sess.outputNames[0];
+    this.log.debug("Inference complete", { meta: { durationMs: Date.now() - start, outputKeys: [outputName], preprocessMode: "raw-tensor" } });
+    return results[outputName].data;
+  }
+  async dispose() {
+    this.session = null;
+    this.log.debug("Session disposed");
+  }
+};
+
+// src/shared/engine-resolver.ts
+var import_types = require("@camstack/types");
+var fs = __toESM(require("fs"));
+var path3 = __toESM(require("path"));
+
+// src/shared/image-utils.ts
+var import_sharp = __toESM(require("sharp"));
+async function letterbox(jpeg, targetSize) {
+  const meta = await (0, import_sharp.default)(jpeg).metadata();
+  const originalWidth = meta.width ?? 0;
+  const originalHeight = meta.height ?? 0;
+  const scale = Math.min(targetSize / originalWidth, targetSize / originalHeight);
+  const scaledWidth = Math.round(originalWidth * scale);
+  const scaledHeight = Math.round(originalHeight * scale);
+  const padX = Math.floor((targetSize - scaledWidth) / 2);
+  const padY = Math.floor((targetSize - scaledHeight) / 2);
+  const { data } = await (0, import_sharp.default)(jpeg).resize(scaledWidth, scaledHeight).extend({
+    top: padY,
+    bottom: targetSize - scaledHeight - padY,
+    left: padX,
+    right: targetSize - scaledWidth - padX,
+    background: { r: 114, g: 114, b: 114 }
+  }).removeAlpha().raw().toBuffer({ resolveWithObject: true });
+  const numPixels = targetSize * targetSize;
+  const float32 = new Float32Array(3 * numPixels);
+  for (let i = 0; i < numPixels; i++) {
+    const srcBase = i * 3;
+    float32[0 * numPixels + i] = data[srcBase] / 255;
+    float32[1 * numPixels + i] = data[srcBase + 1] / 255;
+    float32[2 * numPixels + i] = data[srcBase + 2] / 255;
+  }
+  return { data: float32, scale, padX, padY, originalWidth, originalHeight };
+}
+async function resizeAndNormalize(jpeg, targetWidth, targetHeight, normalization, layout) {
+  const { data } = await (0, import_sharp.default)(jpeg).resize(targetWidth, targetHeight, { fit: "fill" }).removeAlpha().raw().toBuffer({ resolveWithObject: true });
+  const numPixels = targetWidth * targetHeight;
+  const float32 = new Float32Array(3 * numPixels);
+  const mean = [0.485, 0.456, 0.406];
+  const std = [0.229, 0.224, 0.225];
+  if (layout === "nchw") {
+    for (let i = 0; i < numPixels; i++) {
+      const srcBase = i * 3;
+      for (let c = 0; c < 3; c++) {
+        const raw = data[srcBase + c] / 255;
+        let val;
+        if (normalization === "zero-one") {
+          val = raw;
+        } else if (normalization === "imagenet") {
+          val = (raw - mean[c]) / std[c];
+        } else {
+          val = data[srcBase + c];
+        }
+        float32[c * numPixels + i] = val;
+      }
+    }
+  } else {
+    for (let i = 0; i < numPixels; i++) {
+      const srcBase = i * 3;
+      for (let c = 0; c < 3; c++) {
+        const raw = data[srcBase + c] / 255;
+        let val;
+        if (normalization === "zero-one") {
+          val = raw;
+        } else if (normalization === "imagenet") {
+          val = (raw - mean[c]) / std[c];
+        } else {
+          val = data[srcBase + c];
+        }
+        float32[i * 3 + c] = val;
+      }
+    }
+  }
+  return float32;
+}
+
+// src/shared/node-engine.ts
+var path2 = __toESM(require("path"));
+var BACKEND_TO_PROVIDER = {
+  cpu: "cpu",
+  coreml: "coreml",
+  cuda: "cuda",
+  tensorrt: "tensorrt",
+  dml: "dml"
+};
+var BACKEND_TO_DEVICE2 = {
+  cpu: "cpu",
+  coreml: "gpu-mps",
+  cuda: "gpu-cuda",
+  tensorrt: "tensorrt"
+};
+var NodeInferenceEngine = class {
+  constructor(modelPath, backend, modelMeta, logger) {
+    this.modelPath = modelPath;
+    this.backend = backend;
+    this.modelMeta = modelMeta;
+    this.device = BACKEND_TO_DEVICE2[backend] ?? "cpu";
+    this.log = logger ?? createNoopLogger();
+  }
+  modelPath;
+  backend;
+  modelMeta;
+  runtime = "onnx";
+  device;
+  session = null;
+  log;
+  async initialize() {
+    const ort = await import("onnxruntime-node");
+    const provider = BACKEND_TO_PROVIDER[this.backend] ?? "cpu";
+    const absModelPath = path2.isAbsolute(this.modelPath) ? this.modelPath : path2.resolve(process.cwd(), this.modelPath);
+    const sessionOptions = {
+      executionProviders: [provider]
+    };
+    this.session = await ort.InferenceSession.create(absModelPath, sessionOptions);
+    this.log.info("ONNX session loaded", { meta: { modelPath: absModelPath, backend: this.backend, provider } });
+  }
+  async infer(input) {
+    const jpeg = input.kind === "jpeg" ? input.data : await this.encodeRawAsJpeg(input.data, input.width, input.height, input.format);
+    const { data, letterboxMeta } = await this.preprocess(jpeg);
+    const { inputSize } = this.modelMeta;
+    const inputShape = this.modelMeta.preprocessMode === "letterbox" ? [1, 3, inputSize.height, inputSize.width] : [1, 3, inputSize.height, inputSize.width];
+    const start = Date.now();
+    let result;
+    try {
+      result = await this.runSession(data, inputShape);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.log.error("Inference failed", { meta: { error: error.message } });
+      throw error;
+    }
+    const durationMs = Date.now() - start;
+    if ("tensor" in result) {
+      this.log.debug("Inference complete", { meta: { durationMs, outputKeys: ["tensor"], preprocessMode: this.modelMeta.preprocessMode } });
+      return { tensor: result.tensor, letterbox: letterboxMeta, inferenceMs: durationMs };
+    }
+    this.log.debug("Inference complete", { meta: { durationMs, outputKeys: Object.keys(result.tensors), preprocessMode: this.modelMeta.preprocessMode } });
+    return { tensors: result.tensors, letterbox: letterboxMeta, inferenceMs: durationMs };
+  }
+  /** Preprocess JPEG to Float32Array using the configured mode */
+  async preprocess(jpeg) {
+    const { inputSize, inputNormalization, inputLayout, preprocessMode } = this.modelMeta;
+    if (preprocessMode === "letterbox") {
+      const targetSize = Math.max(inputSize.width, inputSize.height);
+      const result = await letterbox(jpeg, targetSize);
+      const letterboxMeta = {
+        scale: result.scale,
+        padX: result.padX,
+        padY: result.padY,
+        originalWidth: result.originalWidth,
+        originalHeight: result.originalHeight
+      };
+      return { data: result.data, letterboxMeta };
+    }
+    const data = await resizeAndNormalize(
+      jpeg,
+      inputSize.width,
+      inputSize.height,
+      inputNormalization,
+      inputLayout
+    );
+    return { data };
+  }
+  async encodeRawAsJpeg(raw, width, height, format) {
+    const sharp2 = (await import("sharp")).default;
+    const channels = format === "gray" ? 1 : 3;
+    return sharp2(raw, { raw: { width, height, channels } }).jpeg({ quality: 80, mozjpeg: false }).toBuffer();
+  }
+  /** Run an ONNX session with a single input, handling both single and multi-output models */
+  async runSession(input, inputShape) {
+    if (!this.session) {
+      throw new Error("NodeInferenceEngine: not initialized \u2014 call initialize() first");
+    }
+    const ort = await import("onnxruntime-node");
+    const sess = this.session;
+    const inputName = sess.inputNames[0];
+    const tensor = new ort.Tensor("float32", input, [...inputShape]);
+    const feeds = { [inputName]: tensor };
+    const results = await sess.run(feeds);
+    const outputNames = sess.outputNames;
+    if (outputNames.length === 1) {
+      const outputName = outputNames[0];
+      return { tensor: results[outputName].data };
+    }
+    const tensors = {};
+    for (const name of outputNames) {
+      tensors[name] = results[name].data;
+    }
+    return { tensors };
+  }
+  async run(input, inputShape) {
+    const result = await this.runSession(input, inputShape);
+    if ("tensor" in result) return result.tensor;
+    const firstKey = Object.keys(result.tensors)[0];
+    return result.tensors[firstKey];
+  }
+  async dispose() {
+    this.session = null;
+    this.log.debug("Session disposed");
+  }
+};
+
+// src/shared/python-engine.ts
+var import_node_child_process = require("child_process");
+var PythonInferenceEngine = class {
+  constructor(pythonPath, scriptPath, runtime, modelPath, extraArgs = [], logger) {
+    this.pythonPath = pythonPath;
+    this.scriptPath = scriptPath;
+    this.modelPath = modelPath;
+    this.extraArgs = extraArgs;
+    this.runtime = runtime;
+    const runtimeDeviceMap = {
+      onnx: "cpu",
+      coreml: "gpu-mps",
+      pytorch: "cpu",
+      openvino: "cpu",
+      tflite: "cpu"
+    };
+    this.device = runtimeDeviceMap[runtime];
+    this.log = logger ?? createNoopLogger();
+  }
+  pythonPath;
+  scriptPath;
+  modelPath;
+  extraArgs;
+  runtime;
+  device;
+  process = null;
+  receiveBuffer = Buffer.alloc(0);
+  pendingResolve = null;
+  pendingReject = null;
+  log;
+  async initialize() {
+    const args = [this.scriptPath, this.modelPath, ...this.extraArgs];
+    this.process = (0, import_node_child_process.spawn)(this.pythonPath, args, {
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    if (!this.process.stdout || !this.process.stdin) {
+      throw new Error("PythonInferenceEngine: failed to create process pipes");
+    }
+    this.log.info("Python process started", { meta: { pythonPath: this.pythonPath, scriptPath: this.scriptPath, modelPath: this.modelPath } });
+    this.process.stderr?.on("data", (chunk) => {
+      const lines = chunk.toString().split("\n");
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed) {
+          this.log.warn(trimmed);
+        }
+      }
+    });
+    this.process.on("error", (err) => {
+      this.log.error("Process error", { meta: { error: err.message } });
+      this.pendingReject?.(err);
+      this.pendingReject = null;
+      this.pendingResolve = null;
+    });
+    this.process.on("exit", (code) => {
+      if (code !== 0) {
+        this.log.error("Process exited", { meta: { code } });
+        const err = new Error(`PythonInferenceEngine: process exited with code ${code}`);
+        this.pendingReject?.(err);
+        this.pendingReject = null;
+        this.pendingResolve = null;
+      }
+    });
+    this.process.stdout.on("data", (chunk) => {
+      this.receiveBuffer = Buffer.concat([this.receiveBuffer, chunk]);
+      this._tryReceive();
+    });
+    await new Promise((resolve3, reject) => {
+      const timeout = setTimeout(() => resolve3(), 2e3);
+      this.process?.on("error", (err) => {
+        clearTimeout(timeout);
+        reject(err);
+      });
+      this.process?.on("exit", (code) => {
+        clearTimeout(timeout);
+        if (code !== 0) {
+          reject(new Error(`PythonInferenceEngine: process exited early with code ${code}`));
+        }
+      });
+    });
+  }
+  _tryReceive() {
+    if (this.receiveBuffer.length < 4) return;
+    const length = this.receiveBuffer.readUInt32LE(0);
+    if (this.receiveBuffer.length < 4 + length) return;
+    const jsonBytes = this.receiveBuffer.subarray(4, 4 + length);
+    this.receiveBuffer = this.receiveBuffer.subarray(4 + length);
+    const resolve3 = this.pendingResolve;
+    const reject = this.pendingReject;
+    this.pendingResolve = null;
+    this.pendingReject = null;
+    if (!resolve3) return;
+    try {
+      const parsed = JSON.parse(jsonBytes.toString("utf8"));
+      resolve3(parsed);
+    } catch (err) {
+      reject?.(err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+  /** Run inference, returning structured detection results. Encodes raw input to JPEG when needed. */
+  async infer(input) {
+    const start = Date.now();
+    const jpeg = input.kind === "jpeg" ? input.data : await this.encodeRawAsJpeg(input.data, input.width, input.height, input.format);
+    const result = await this.sendJpeg(jpeg);
+    const durationMs = Date.now() - start;
+    this.log.debug("Inference complete", { meta: { durationMs } });
+    return { structured: result, inferenceMs: durationMs };
+  }
+  async encodeRawAsJpeg(raw, width, height, format) {
+    const sharp2 = (await import("sharp")).default;
+    const channels = format === "gray" ? 1 : 3;
+    return sharp2(raw, { raw: { width, height, channels } }).jpeg({ quality: 80, mozjpeg: false }).toBuffer();
+  }
+  /** Send JPEG buffer via binary IPC, receive JSON detection results */
+  async sendJpeg(jpeg) {
+    if (!this.process?.stdin) {
+      throw new Error("PythonInferenceEngine: process not initialized");
+    }
+    return new Promise((resolve3, reject) => {
+      this.pendingResolve = resolve3;
+      this.pendingReject = reject;
+      const lengthBuf = Buffer.allocUnsafe(4);
+      lengthBuf.writeUInt32LE(jpeg.length, 0);
+      this.process.stdin.write(Buffer.concat([lengthBuf, jpeg]));
+    });
+  }
+  async dispose() {
+    const proc = this.process;
+    if (!proc) return;
+    this.process = null;
+    proc.stdin?.end();
+    proc.kill("SIGTERM");
+    const exited = await new Promise((resolve3) => {
+      const timer = setTimeout(() => {
+        resolve3(false);
+      }, 5e3);
+      proc.once("exit", () => {
+        clearTimeout(timer);
+        resolve3(true);
+      });
+    });
+    if (!exited) {
+      try {
+        proc.kill("SIGKILL");
+      } catch {
+      }
+      this.log.warn("Python process did not exit gracefully \u2014 sent SIGKILL");
+    } else {
+      this.log.debug("Python process terminated");
+    }
+  }
+};
+
+// src/shared/engine-resolver.ts
+var AUTO_BACKEND_PRIORITY = ["coreml", "cuda", "tensorrt", "cpu"];
+var BACKEND_TO_FORMAT = import_types.BACKEND_TO_FORMAT;
+var RUNTIME_TO_FORMAT = import_types.RUNTIME_TO_FORMAT;
+function extractModelMeta(entry) {
+  return {
+    inputSize: entry.inputSize,
+    inputNormalization: entry.inputNormalization ?? "zero-one",
+    inputLayout: entry.inputLayout ?? "nchw",
+    preprocessMode: entry.preprocessMode ?? "letterbox"
+  };
+}
+function modelFilePath(modelsDir, modelEntry, format) {
+  const formatEntry = modelEntry.formats[format];
+  if (!formatEntry) {
+    throw new Error(`Model ${modelEntry.id} has no ${format} format`);
+  }
+  const urlParts = formatEntry.url.split("/");
+  const filename = urlParts[urlParts.length - 1] ?? `${modelEntry.id}.${format}`;
+  return path3.join(modelsDir, filename);
+}
+function modelExists(filePath) {
+  try {
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+async function resolveEngine(options) {
+  const { runtime, backend, modelEntry, modelsDir, models } = options;
+  const log = options.logger ?? createNoopLogger();
+  let selectedFormat;
+  let selectedBackend;
+  if (runtime === "auto") {
+    const available = await probeOnnxBackends();
+    let chosen = null;
+    for (const b of AUTO_BACKEND_PRIORITY) {
+      if (!available.includes(b)) continue;
+      const fmt = BACKEND_TO_FORMAT[b];
+      if (!fmt) continue;
+      if (!modelEntry.formats[fmt]) continue;
+      chosen = { backend: b, format: fmt };
+      break;
+    }
+    if (!chosen) {
+      throw new Error(
+        `resolveEngine: no compatible backend found for model ${modelEntry.id}. Available backends: ${available.join(", ")}`
+      );
+    }
+    selectedFormat = chosen.format;
+    selectedBackend = chosen.backend;
+  } else {
+    const fmt = RUNTIME_TO_FORMAT[runtime];
+    if (!fmt) {
+      throw new Error(`resolveEngine: unsupported runtime "${runtime}"`);
+    }
+    if (!modelEntry.formats[fmt]) {
+      if (fmt !== "onnx" && modelEntry.formats["onnx"]) {
+        selectedFormat = "onnx";
+        selectedBackend = backend || "cpu";
+      } else {
+        throw new Error(
+          `resolveEngine: model ${modelEntry.id} has no ${fmt} format for runtime ${runtime}`
+        );
+      }
+    } else {
+      selectedFormat = fmt;
+      selectedBackend = runtime === "onnx" ? backend || "cpu" : runtime;
+    }
+  }
+  let modelPath;
+  if (models) {
+    modelPath = await models.ensure(modelEntry.id, selectedFormat);
+  } else {
+    modelPath = modelFilePath(modelsDir, modelEntry, selectedFormat);
+    if (!modelExists(modelPath)) {
+      throw new Error(
+        `resolveEngine: model file not found at ${modelPath} and no model service provided`
+      );
+    }
+  }
+  log.info("Engine resolved", { meta: { format: selectedFormat, backend: selectedBackend, modelId: modelEntry.id } });
+  if (selectedFormat === "onnx") {
+    const engine = new NodeInferenceEngine(modelPath, selectedBackend, extractModelMeta(modelEntry), options.logger);
+    await engine.initialize();
+    return { engine, format: selectedFormat, modelPath };
+  }
+  const effectiveRuntime = runtime === "auto" ? selectedBackend : runtime;
+  let { pythonPath } = options;
+  if (!pythonPath) {
+    const { execFileSync: efs } = await import("child_process");
+    for (const cmd of ["python3", "python"]) {
+      try {
+        efs(cmd, ["--version"], { timeout: 3e3, stdio: "ignore" });
+        pythonPath = cmd;
+        break;
+      } catch {
+      }
+    }
+  }
+  const scriptName = import_types.PYTHON_SCRIPT[effectiveRuntime];
+  if (scriptName && pythonPath) {
+    const candidates = [
+      path3.join(__dirname, "../../python", scriptName),
+      path3.join(__dirname, "../python", scriptName),
+      path3.join(__dirname, "../../../python", scriptName)
+    ];
+    const scriptPath = candidates.find((p) => fs.existsSync(p));
+    if (!scriptPath) {
+      throw new Error(
+        `resolveEngine: Python script "${scriptName}" not found. Searched:
+${candidates.join("\n")}`
+      );
+    }
+    const inputSize = Math.max(modelEntry.inputSize.width, modelEntry.inputSize.height);
+    const engine = new PythonInferenceEngine(pythonPath, scriptPath, effectiveRuntime, modelPath, [
+      `--input-size=${inputSize}`,
+      `--confidence=0.25`
+    ], options.logger);
+    await engine.initialize();
+    return { engine, format: selectedFormat, modelPath };
+  }
+  const fallbackPath = modelFilePath(modelsDir, modelEntry, "onnx");
+  if (modelEntry.formats["onnx"] && modelExists(fallbackPath)) {
+    const engine = new NodeInferenceEngine(fallbackPath, "cpu", extractModelMeta(modelEntry), options.logger);
+    await engine.initialize();
+    return { engine, format: "onnx", modelPath: fallbackPath };
+  }
+  throw new Error(
+    `resolveEngine: format ${selectedFormat} is not yet supported by NodeInferenceEngine, no Python runtime is available, and no ONNX fallback exists`
+  );
+}
+async function probeOnnxBackends() {
+  const available = ["cpu"];
+  try {
+    const ort = await import("onnxruntime-node");
+    const providers = ort.env?.webgl?.disabled !== void 0 ? ort.InferenceSession.getAvailableProviders?.() ?? [] : [];
+    for (const p of providers) {
+      const normalized = p.toLowerCase().replace("executionprovider", "");
+      if (normalized === "coreml") available.push("coreml");
+      else if (normalized === "cuda") available.push("cuda");
+      else if (normalized === "tensorrt") available.push("tensorrt");
+    }
+  } catch {
+  }
+  if (process.platform === "darwin" && !available.includes("coreml")) {
+    available.push("coreml");
+  }
+  return [...new Set(available)];
+}
+
+// src/addon/clip-models.ts
+var CLIP_MODEL_META = {
+  "clip-vit-b32": {
+    imageModelId: "clip-vit-b32",
+    textModelId: "clip-vit-b32-text",
+    embeddingDim: 512,
+    inputSize: 224,
+    tokenizerType: "clip"
+  },
+  "clip-vit-b16": {
+    imageModelId: "clip-vit-b16",
+    textModelId: "clip-vit-b16-text",
+    embeddingDim: 512,
+    inputSize: 224,
+    tokenizerType: "clip"
+  },
+  "siglip2-b16-256": {
+    imageModelId: "siglip2-b16-256",
+    textModelId: "siglip2-b16-256-text",
+    embeddingDim: 768,
+    inputSize: 256,
+    tokenizerType: "siglip"
+  }
+};
+var DEFAULT_CLIP_MODEL = "clip-vit-b32";
+function getModelMeta(modelId) {
+  return CLIP_MODEL_META[modelId] ?? CLIP_MODEL_META[DEFAULT_CLIP_MODEL];
+}
+
+// src/addon/clip-preprocessing.ts
+var CLIP_MEAN = [0.48145466, 0.4578275, 0.40821073];
+var CLIP_STD = [0.26862954, 0.26130258, 0.27577711];
+function preprocessForClip(rgb, srcWidth, srcHeight, targetWidth, targetHeight) {
+  const pixels = targetWidth * targetHeight;
+  const result = new Float32Array(3 * pixels);
+  for (let y = 0; y < targetHeight; y++) {
+    for (let x = 0; x < targetWidth; x++) {
+      const srcX = Math.min(Math.floor(x / targetWidth * srcWidth), srcWidth - 1);
+      const srcY = Math.min(Math.floor(y / targetHeight * srcHeight), srcHeight - 1);
+      const srcIdx = (srcY * srcWidth + srcX) * 3;
+      const dstIdx = y * targetWidth + x;
+      for (let c = 0; c < 3; c++) {
+        const val = (rgb[srcIdx + c] ?? 0) / 255;
+        result[c * pixels + dstIdx] = (val - CLIP_MEAN[c]) / CLIP_STD[c];
+      }
+    }
+  }
+  return result;
+}
+function l2Normalize(vec) {
+  let norm = 0;
+  for (let i = 0; i < vec.length; i++) norm += vec[i] * vec[i];
+  norm = Math.sqrt(norm);
+  if (norm > 0) {
+    for (let i = 0; i < vec.length; i++) vec[i] /= norm;
+  }
+  return vec;
+}
+
+// src/addon/index.ts
+var EmbeddingEncoderAddon = class extends import_types2.BaseAddon {
+  imageRawEngine = null;
+  textRawEngine = null;
+  imagePythonEngine = null;
+  textPythonEngine = null;
+  models = null;
+  isPython = false;
+  constructor() {
+    super({ modelId: DEFAULT_CLIP_MODEL, runtime: "auto", backend: "cpu" });
+  }
+  async onInitialize() {
+    const modelsDir = await this.ctx.api.storage.resolve.query({ location: "models", relativePath: "" }).catch(() => "camstack-data/models");
+    this.models = new import_core.ModelDownloadService(modelsDir, []);
+    return [{ capability: import_types2.embeddingEncoderCapability, provider: this }];
+  }
+  async encode(crop, width, height) {
+    await this.ensureImageEngine();
+    const meta = getModelMeta(this.config.modelId);
+    const start = Date.now();
+    if (this.isPython && this.imagePythonEngine) {
+      const result = await this.imagePythonEngine.infer({ kind: "jpeg", data: crop });
+      const rawEmbedding = result.structured?.["embedding"];
+      const embedding = new Float32Array(rawEmbedding);
+      return {
+        embedding: l2Normalize(embedding),
+        inferenceMs: result.inferenceMs ?? Date.now() - start
+      };
+    }
+    const preprocessed = preprocessForClip(crop, width, height, meta.inputSize, meta.inputSize);
+    const output = await this.imageRawEngine.run(preprocessed, [1, 3, meta.inputSize, meta.inputSize]);
+    const sliced = output.length > meta.embeddingDim ? output.slice(0, meta.embeddingDim) : output;
+    return {
+      embedding: l2Normalize(new Float32Array(sliced)),
+      inferenceMs: Date.now() - start
+    };
+  }
+  async encodeText(text) {
+    await this.ensureTextEngine();
+    const meta = getModelMeta(this.config.modelId);
+    const start = Date.now();
+    if (this.isPython && this.textPythonEngine) {
+      const textBuffer = Buffer.from(JSON.stringify({ text }), "utf-8");
+      const result = await this.textPythonEngine.infer({ kind: "jpeg", data: textBuffer });
+      const rawEmbedding = result.structured?.["embedding"];
+      const embedding = new Float32Array(rawEmbedding);
+      return {
+        embedding: l2Normalize(embedding),
+        inferenceMs: result.inferenceMs ?? Date.now() - start
+      };
+    }
+    const tokenIds = clipTokenize(text);
+    const inputTensor = new Float32Array(tokenIds);
+    const output = await this.textRawEngine.run(inputTensor, [1, tokenIds.length]);
+    const sliced = output.length > meta.embeddingDim ? output.slice(0, meta.embeddingDim) : output;
+    return {
+      embedding: l2Normalize(new Float32Array(sliced)),
+      inferenceMs: Date.now() - start
+    };
+  }
+  getInfo() {
+    const meta = getModelMeta(this.config.modelId);
+    return {
+      modelId: this.config.modelId,
+      embeddingDim: meta.embeddingDim,
+      ready: this.imageRawEngine !== null || this.imagePythonEngine !== null
+    };
+  }
+  async ensureImageEngine() {
+    if (this.imageRawEngine || this.imagePythonEngine) return;
+    const meta = getModelMeta(this.config.modelId);
+    const imageEntry = CLIP_IMAGE_MODELS.find((m) => m.id === meta.imageModelId);
+    if (!imageEntry) {
+      throw new Error(`EmbeddingEncoderAddon: unknown image model "${meta.imageModelId}"`);
+    }
+    await this.resolveForEntry(imageEntry, "image");
+  }
+  async ensureTextEngine() {
+    if (this.textRawEngine || this.textPythonEngine) return;
+    const meta = getModelMeta(this.config.modelId);
+    const textEntry = CLIP_TEXT_MODELS.find((m) => m.id === meta.textModelId);
+    if (!textEntry) {
+      throw new Error(`EmbeddingEncoderAddon: unknown text model "${meta.textModelId}"`);
+    }
+    await this.resolveForEntry(textEntry, "text");
+  }
+  async resolveForEntry(entry, target) {
+    const runtime = this.config.runtime === "auto" ? "auto" : this.config.runtime === "node" ? "onnx" : this.config.runtime;
+    const modelsDir = this.models.getModelsDir();
+    const engineLogger = this.ctx.logger.withTags({
+      modelId: entry.id,
+      runtime: this.config.runtime,
+      backend: this.config.backend
+    });
+    await this.models.ensure(entry.id, "onnx");
+    const resolved = await resolveEngine({
+      runtime,
+      backend: this.config.backend,
+      modelEntry: entry,
+      modelsDir,
+      models: this.models ?? void 0,
+      logger: engineLogger
+    });
+    if (resolved.format !== "onnx") {
+      this.isPython = true;
+      if (target === "image") {
+        this.imagePythonEngine = resolved.engine;
+      } else {
+        this.textPythonEngine = resolved.engine;
+      }
+    } else {
+      const rawEngine = new NodeRawTensorEngine(resolved.modelPath, this.config.backend, engineLogger);
+      await rawEngine.initialize();
+      await resolved.engine.dispose();
+      if (target === "image") {
+        this.imageRawEngine = rawEngine;
+      } else {
+        this.textRawEngine = rawEngine;
+      }
+    }
+  }
+  async onShutdown() {
+    await this.imageRawEngine?.dispose();
+    await this.textRawEngine?.dispose();
+    await this.imagePythonEngine?.dispose();
+    await this.textPythonEngine?.dispose();
+  }
+  // ── Three-level settings API (Phase 3) ──────────────────────────────
+  globalSettingsSchema() {
+    return this.schema({
+      sections: [
+        {
+          id: "embedding-encoder-settings",
+          title: "Embedding Encoder",
+          columns: 2,
+          fields: [
+            {
+              type: "text",
+              key: "modelId",
+              label: "Model ID",
+              description: "CLIP model identifier to use for image/text embedding",
+              default: DEFAULT_CLIP_MODEL
+            },
+            {
+              type: "select",
+              key: "runtime",
+              label: "Runtime",
+              description: "Inference runtime (auto selects the best available)",
+              default: "auto",
+              options: [
+                { label: "Auto", value: "auto" },
+                { label: "Node (ONNX)", value: "node" },
+                { label: "Python", value: "python" }
+              ]
+            },
+            {
+              type: "select",
+              key: "backend",
+              label: "Backend",
+              description: "Hardware backend for inference acceleration",
+              default: "cpu",
+              options: [
+                { label: "CPU", value: "cpu" },
+                { label: "CUDA", value: "cuda" },
+                { label: "CoreML", value: "coreml" }
+              ]
+            }
+          ]
+        }
+      ]
+    });
+  }
+  async onConfigChanged() {
+  }
+};
+function clipTokenize(text, maxLength = 77) {
+  const SOT_TOKEN = 49406;
+  const EOT_TOKEN = 49407;
+  const tokens = [SOT_TOKEN];
+  for (let i = 0; i < text.length && tokens.length < maxLength - 1; i++) {
+    tokens.push(text.charCodeAt(i) + 256);
+  }
+  tokens.push(EOT_TOKEN);
+  while (tokens.length < maxLength) {
+    tokens.push(0);
+  }
+  return tokens;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EmbeddingEncoderAddon
+});
+//# sourceMappingURL=index.js.map