@qvac/ocr-ggml 0.24.2 → 0.25.0

package/README.md

@@ -149,6 +149,7 @@ bare examples/backend-device.js --backend metal
 | `params.nThreads` | `number` | | `0` (auto) | CPU thread count for GGML; `<0` leaves the GGML default |
 | `params.backendsDir` | `string` | | `<package>/prebuilds` | directory holding `libggml-*.so` backend shared libs |
 | `params.backendDevice` | `'cpu'` \| `'vulkan'` \| `'metal'` \| `'opencl'` | | `'cpu'` | ggml backend device. `'vulkan'` (Linux/Windows/Android), `'metal'` (Apple) and `'opencl'` (Android/Adreno) opt in to GPU inference with transparent CPU fallback — see [Backend device](#backend-device-cpu--vulkan--metal--opencl) |
+| `params.main-gpu` / `params.main_gpu` | `number` \| `string` | | _prefer dedicated_ | Raw ggml registry index or strict GPU class; requires GPU `backendDevice`. See below. |
 | `params.gpuDevice` | `number` | | _prefer discrete_ | 0-based index into the matching GPU/iGPU devices for `'vulkan'`/`'metal'`/`'opencl'`; out-of-range → CPU fallback — see [Selecting a specific GPU](#selecting-a-specific-gpu-gpudevice) |
 | `opts.stats` | `boolean` | | `false` | emit timing stats on `finish` |
 | `logger` | `Object` | | `null` | optional `{ info, warn, error, debug }` — receives C++ log lines |
@@ -278,6 +279,26 @@ Behaviour and expectations:
   with identical output. Other GPUs (Adreno OpenCL, Apple Metal, NVIDIA/Intel
   Vulkan) keep full-GPU detection.
 
+### Shared GPU selection (`main-gpu`)
+
+With a GPU `backendDevice`, set `'main-gpu': N` (or `main_gpu: N`) to select
+that **raw ggml registry index before backend filtering**. For example, with
+`[ROCm0, Vulkan0]`, `'main-gpu': 0` and `backendDevice: 'vulkan'` falls back to
+CPU; it never renumbers Vulkan0 to index 0. An in-range CPU, unsupported,
+or safety-excluded target also falls back to CPU. An out-of-range integer
+(including negative values) emits a warning and uses normal selection.
+
+`'dedicated'` selects only a dedicated GPU; `'integrated'` selects only an
+integrated GPU. If that class is unavailable, selection falls back to CPU.
+Without a selector, GPU selection prefers dedicated devices. Adreno Vulkan
+and required OCR-op safety checks apply to all `main-gpu` requests.
+`backendDevice: 'cpu'` (the default) remains CPU, regardless of this selector.
+
+Use only one of `main-gpu`, `main_gpu`, or legacy `gpuDevice`. The new selector
+accepts signed 32-bit integer numbers or integer strings, and case-insensitive
+class strings. Null, booleans, fractions, overflow, and other strings are rejected.
+`gpuDevice` retains its existing index into the filtered backend list.
+
 ### Selecting a specific GPU (`gpuDevice`)
 
 On a host with more than one GPU (e.g. a discrete GPU plus an integrated GPU,

package/index.d.ts

@@ -97,6 +97,16 @@ export interface OcrGgmlParams {
      * the README).
      */
     gpuDevice?: number;
+    /**
+     * Raw ggml registry index (integer number/string), or a GPU class (case-insensitive).
+     * An unavailable/excluded in-range device or absent class falls back to CPU.
+     * Out-of-range indices warn and use the default dedicated-first selection.
+     * Requires a GPU backendDevice; CPU remains the default. Cannot be combined
+     * with gpuDevice or main_gpu. Adreno Vulkan safety checks still apply.
+     */
+    "main-gpu"?: number | string;
+    /** Alias for main-gpu; provide only one spelling. */
+    main_gpu?: number | string;
 }
 export type { BackendInfo, OcrGgmlRunOptions };
 export interface OcrGgmlArgs {

package/index.js

@@ -11,6 +11,7 @@ const ocr_ggml_1 = require("./ocr-ggml");
 const error_1 = require("./lib/error");
 Object.defineProperty(exports, "QvacErrorAddonOcrGgml", { enumerable: true, get: function () { return error_1.QvacErrorAddonOcrGgml; } });
 Object.defineProperty(exports, "ERR_CODES", { enumerable: true, get: function () { return error_1.ERR_CODES; } });
+const main_gpu_1 = require("./lib/main-gpu");
 const DOCTR_INTERNAL_LANG_LIST = ["en"];
 /**
  * Native language-validation failure messages (see the EasyOCR pipeline's
@@ -139,6 +140,20 @@ class OcrGgml {
                 adds: "langList (non-empty array)",
             });
         }
+        const selectors = ["main-gpu", "main_gpu", "gpuDevice"];
+        if (selectors.filter((key) => this.params[key] !== undefined).length > 1) {
+            throw new TypeError("Use only one of main-gpu, main_gpu, or gpuDevice");
+        }
+        const rawMainGpu = this.params["main-gpu"] !== undefined
+            ? this.params["main-gpu"] : this.params.main_gpu;
+        const mainGpu = typeof rawMainGpu === "string"
+            ? (/^[+-]?\d+$/.test(rawMainGpu) ? Number(rawMainGpu) : rawMainGpu.toLowerCase())
+            : rawMainGpu;
+        if (mainGpu !== undefined && mainGpu !== "dedicated" && mainGpu !== "integrated" &&
+            !(typeof mainGpu === "number" && Number.isInteger(mainGpu) &&
+                mainGpu >= main_gpu_1.MIN_MAIN_GPU_INDEX && mainGpu <= main_gpu_1.MAX_MAIN_GPU_INDEX)) {
+            throw new TypeError("main-gpu must be a 32-bit integer registry index, 'dedicated', or 'integrated'");
+        }
         const configurationParams = {
             pathDetector: this.params.pathDetector,
             pathRecognizer: this.params.pathRecognizer,
@@ -157,6 +172,8 @@ class OcrGgml {
             "pipelineType",
             "backendDevice",
             "gpuDevice",
+            "main-gpu",
+            "main_gpu",
         ];
         for (const field of optionalFields) {
             if (this.params[field] !== undefined) {

package/lib/main-gpu.d.ts

@@ -0,0 +1,2 @@
+export declare const MIN_MAIN_GPU_INDEX = -2147483648;
+export declare const MAX_MAIN_GPU_INDEX = 2147483647;

package/lib/main-gpu.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_MAIN_GPU_INDEX = exports.MIN_MAIN_GPU_INDEX = void 0;
+exports.MIN_MAIN_GPU_INDEX = -2147483648;
+exports.MAX_MAIN_GPU_INDEX = 2147483647;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/ocr-ggml",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "GGML-backed OCR addon for qvac (EasyOCR and DocTR pipelines on GGUF weights)",
   "addon": true,
   "engines": {
@@ -95,7 +95,7 @@
   },
   "dependencies": {
     "@qvac/error": "^0.1.0",
-    "@qvac/fabric": "^0.16.0",
+    "@qvac/fabric": "^0.17.0",
     "@qvac/infer-base": "^0.6.2",
     "@qvac/logging": "^0.1.0",
     "bare-fetch": "^3.0.1",
@@ -116,7 +116,13 @@
       "types": "./addonLogging.d.ts",
       "default": "./addonLogging.js"
     },
-    "./addonLogging.js": "./addonLogging.js"
+    "./addonLogging.js": "./addonLogging.js",
+    "./lib/main-gpu": {
+      "types": "./lib/main-gpu.d.ts",
+      "default": "./lib/main-gpu.js"
+    },
+    "./binding": "./binding.js",
+    "./binding.js": "./binding.js"
   },
   "types": "index.d.ts"
 }

package/prebuilds/darwin-arm64/qvac__ocr-ggml.bare.exports

@@ -7,7 +7,7 @@
     ],
     "current_versions": [
       {
-        "version": "0.24.2"
+        "version": "0.25"
       }
     ],
     "exported_symbols": [
@@ -2543,7 +2543,6 @@
             "_png_write_bKGD",
             "_png_set_hIST",
             "__ZN2cv3MatC2ENS_5Size_IiEEi",
-            "__ZN23qvac_lib_infer_ocr_ggml21ocr_backend_selection19selectBackendDeviceENS_13BackendDeviceENSt3__18optionalIiEE",
             "__ZN2cv15ImageCollection4Impl3endEPS0_",
             "_png_get_copyright",
             "__Z6cvCeilRKN2cv9softfloatE",
@@ -2628,6 +2627,7 @@
             "__ZN2cv15ImageCollection8iteratorppEi",
             "_cvGetReal1D",
             "__ZN2cv3MatC1Ev",
+            "__ZN23qvac_lib_infer_ocr_ggml21ocr_backend_selection19selectBackendDeviceENS_13BackendDeviceENSt3__18optionalIiEENS3_INS2_7variantIJiNS_12MainGpuClassEEEEEE",
             "_png_check_fp_string",
             "__ZN2cv11linearPolarERKNS_11_InputArrayERKNS_12_OutputArrayENS_6Point_IfEEdi",
             "__ZN2cv3LDAC1ERKNS_11_InputArrayES3_i",

package/prebuilds/darwin-x64/qvac__ocr-ggml.bare.exports

@@ -7,7 +7,7 @@
     ],
     "current_versions": [
       {
-        "version": "0.24.2"
+        "version": "0.25"
       }
     ],
     "exported_symbols": [
@@ -2597,7 +2597,6 @@
             "_png_write_bKGD",
             "_png_set_hIST",
             "__ZN2cv3MatC2ENS_5Size_IiEEi",
-            "__ZN23qvac_lib_infer_ocr_ggml21ocr_backend_selection19selectBackendDeviceENS_13BackendDeviceENSt3__18optionalIiEE",
             "__ZN2cv15ImageCollection4Impl3endEPS0_",
             "_png_get_copyright",
             "__Z6cvCeilRKN2cv9softfloatE",
@@ -2680,6 +2679,7 @@
             "__ZN2cv15ImageCollection8iteratorppEi",
             "_cvGetReal1D",
             "__ZN2cv3MatC1Ev",
+            "__ZN23qvac_lib_infer_ocr_ggml21ocr_backend_selection19selectBackendDeviceENS_13BackendDeviceENSt3__18optionalIiEENS3_INS2_7variantIJiNS_12MainGpuClassEEEEEE",
             "_png_check_fp_string",
             "__ZN2cv11linearPolarERKNS_11_InputArrayERKNS_12_OutputArrayENS_6Point_IfEEdi",
             "__ZN2cv3LDAC1ERKNS_11_InputArrayES3_i",

package/prebuilds/ios-arm64/qvac__ocr-ggml.bare.exports

@@ -7,7 +7,7 @@
     ],
     "current_versions": [
       {
-        "version": "0.24.2"
+        "version": "0.25"
       }
     ],
     "exported_symbols": [
@@ -2533,7 +2533,6 @@
             "_png_write_bKGD",
             "_png_set_hIST",
             "__ZN2cv3MatC2ENS_5Size_IiEEi",
-            "__ZN23qvac_lib_infer_ocr_ggml21ocr_backend_selection19selectBackendDeviceENS_13BackendDeviceENSt3__18optionalIiEE",
             "__ZN2cv15ImageCollection4Impl3endEPS0_",
             "_png_get_copyright",
             "__Z6cvCeilRKN2cv9softfloatE",
@@ -2618,6 +2617,7 @@
             "__ZN2cv15ImageCollection8iteratorppEi",
             "_cvGetReal1D",
             "__ZN2cv3MatC1Ev",
+            "__ZN23qvac_lib_infer_ocr_ggml21ocr_backend_selection19selectBackendDeviceENS_13BackendDeviceENSt3__18optionalIiEENS3_INS2_7variantIJiNS_12MainGpuClassEEEEEE",
             "_png_check_fp_string",
             "__ZN2cv11linearPolarERKNS_11_InputArrayERKNS_12_OutputArrayENS_6Point_IfEEdi",
             "__ZN2cv3LDAC1ERKNS_11_InputArrayES3_i",

package/prebuilds/ios-arm64-simulator/qvac__ocr-ggml.bare.exports

@@ -7,7 +7,7 @@
     ],
     "current_versions": [
       {
-        "version": "0.24.2"
+        "version": "0.25"
       }
     ],
     "exported_symbols": [
@@ -2533,7 +2533,6 @@
             "_png_write_bKGD",
             "_png_set_hIST",
             "__ZN2cv3MatC2ENS_5Size_IiEEi",
-            "__ZN23qvac_lib_infer_ocr_ggml21ocr_backend_selection19selectBackendDeviceENS_13BackendDeviceENSt3__18optionalIiEE",
             "__ZN2cv15ImageCollection4Impl3endEPS0_",
             "_png_get_copyright",
             "__Z6cvCeilRKN2cv9softfloatE",
@@ -2618,6 +2617,7 @@
             "__ZN2cv15ImageCollection8iteratorppEi",
             "_cvGetReal1D",
             "__ZN2cv3MatC1Ev",
+            "__ZN23qvac_lib_infer_ocr_ggml21ocr_backend_selection19selectBackendDeviceENS_13BackendDeviceENSt3__18optionalIiEENS3_INS2_7variantIJiNS_12MainGpuClassEEEEEE",
             "_png_check_fp_string",
             "__ZN2cv11linearPolarERKNS_11_InputArrayERKNS_12_OutputArrayENS_6Point_IfEEdi",
             "__ZN2cv3LDAC1ERKNS_11_InputArrayES3_i",

package/prebuilds/ios-x64-simulator/qvac__ocr-ggml.bare.exports

@@ -7,7 +7,7 @@
     ],
     "current_versions": [
       {
-        "version": "0.24.2"
+        "version": "0.25"
       }
     ],
     "exported_symbols": [
@@ -2592,7 +2592,6 @@
             "_png_write_bKGD",
             "_png_set_hIST",
             "__ZN2cv3MatC2ENS_5Size_IiEEi",
-            "__ZN23qvac_lib_infer_ocr_ggml21ocr_backend_selection19selectBackendDeviceENS_13BackendDeviceENSt3__18optionalIiEE",
             "__ZN2cv15ImageCollection4Impl3endEPS0_",
             "_png_get_copyright",
             "__Z6cvCeilRKN2cv9softfloatE",
@@ -2674,6 +2673,7 @@
             "__ZN2cv15ImageCollection8iteratorppEi",
             "_cvGetReal1D",
             "__ZN2cv3MatC1Ev",
+            "__ZN23qvac_lib_infer_ocr_ggml21ocr_backend_selection19selectBackendDeviceENS_13BackendDeviceENSt3__18optionalIiEENS3_INS2_7variantIJiNS_12MainGpuClassEEEEEE",
             "_png_check_fp_string",
             "__ZN2cv11linearPolarERKNS_11_InputArrayERKNS_12_OutputArrayENS_6Point_IfEEdi",
             "__ZN2cv3LDAC1ERKNS_11_InputArrayES3_i",

package/test/integration/backend-device.test.js

@@ -2,6 +2,8 @@
 
 const { OcrGgml } = require('../..')
 const test = require('brittle')
+const path = require('bare-path')
+const { MIN_MAIN_GPU_INDEX, MAX_MAIN_GPU_INDEX } = require('@qvac/ocr-ggml/lib/main-gpu')
 const {
   isMobile,
   platform,
@@ -33,6 +35,101 @@ const vulkanBackendLib = findVulkanBackendLib(PREBUILDS_DIR)
 // host that did not ship a Vulkan backend lib.
 const shouldSkip = isMobile || !vulkanBackendLib
 
+function nativeBackendsDir() {
+  if (isMobile) return PREBUILDS_DIR
+  return path.join(path.dirname(require.resolve('@qvac/fabric/package')), 'prebuilds')
+}
+
+for (const key of ['main-gpu', 'main_gpu']) {
+  for (const value of [0, '+0', 'DEDICATED', 'Integrated']) {
+    test(
+      `native createInstance: ${key}=${value} resolves the requested device`,
+      { timeout: TEST_TIMEOUT },
+      async function (t) {
+        const binding = require('../../binding')
+        const pathDetector = await ensureModelPath('detector_craft')
+        const pathRecognizer = await ensureModelPath('recognizer_latin')
+        const backendDevice = platform === 'darwin' || platform === 'ios' ? 'metal' : 'vulkan'
+        const handle = binding.createInstance(
+          {},
+          {
+            pathDetector,
+            pathRecognizer,
+            langList: ['en'],
+            backendDevice,
+            backendsDir: nativeBackendsDir(),
+            [key]: value
+          },
+          () => {}
+        )
+        try {
+          const info = binding.getBackendInfo(handle)
+          t.is(info.requested, backendDevice, 'native backend request is preserved')
+          const numeric = value === 0 || value === '+0'
+          if (info.backendDevice === 'CPU') {
+            t.is(info.deviceIndex, -1, 'fallback selects CPU')
+            const selectorReason = numeric
+              ? 'main-gpu registry index 0 is not an eligible'
+              : 'main-gpu requested GPU class is unavailable'
+            t.ok(
+              info.fallbackReason.includes(selectorReason) ||
+                info.fallbackReason.includes('does not implement the OCR vision ops'),
+              'fallback identifies the parsed selector or the OCR safety check'
+            )
+          } else {
+            t.is(info.fallbackReason, '', 'selected GPU needs no fallback')
+            t.ok(info.deviceIndex >= 0, 'selected GPU has a registry index')
+            t.ok(
+              backendDevice === 'metal'
+                ? /metal|mtl/i.test(info.backendName)
+                : /vulkan/i.test(info.backendName),
+              'resolved device belongs to the requested backend'
+            )
+            if (numeric) {
+              t.is(info.deviceIndex, 0, 'numeric selector preserves raw registry identity')
+            } else {
+              t.is(
+                info.backendDevice,
+                value.toLowerCase() === 'integrated' ? 'IGPU' : 'GPU',
+                'class selector is parsed case-insensitively and applied strictly'
+              )
+            }
+          }
+        } finally {
+          binding.destroyInstance(handle)
+        }
+      }
+    )
+  }
+
+  test(`native createInstance: ${key} rejects invalid indices before model loading`, (t) => {
+    const binding = require('../../binding')
+    for (const value of [
+      0.5,
+      NaN,
+      Infinity,
+      MAX_MAIN_GPU_INDEX + 1,
+      MIN_MAIN_GPU_INDEX - 1,
+      String(MAX_MAIN_GPU_INDEX + 1),
+      String(MIN_MAIN_GPU_INDEX - 1),
+      '+-1',
+      '1junk',
+      ' 1'
+    ]) {
+      t.exception(
+        () =>
+          binding.createInstance(
+            {},
+            { pathDetector: 'unused', pathRecognizer: 'unused', langList: ['en'], [key]: value },
+            () => {}
+          ),
+        /main-gpu must be a 32-bit integer registry index/,
+        `${key}=${value} is rejected by native validation`
+      )
+    }
+  })
+}
+
 test(
   'backendDevice vulkan: selects Vulkan or reports an explicit CPU fallback',
   { timeout: TEST_TIMEOUT, skip: shouldSkip },