@qvac/ocr-ggml 0.27.1 → 0.27.3

package/README.md

@@ -100,6 +100,32 @@ console.log(response.stats) // RuntimeStats (populated when opts.stats: true)
 await ocr.unload()
 ```
 
+### Check model weight fit
+
+`assessFit` reads the detector and recognizer GGUF tensor metadata without
+loading their weights. It checks a conservative weight-load estimate against
+the selected backend's currently free memory. It does **not** assess image
+decoding, detection or recognition graphs, or the number of text regions in a
+future image. A `fits` result therefore covers model weights only; `error`
+means the check could not reach a reliable capacity verdict.
+
+```js
+const { assessFit } = require('@qvac/ocr-ggml')
+
+const fit = assessFit({
+  pathDetector: '/abs/path/craft_mlt_25k.gguf',
+  pathRecognizer: '/abs/path/latin_g2.gguf',
+  backendDevice: 'cpu',
+  marginBytes: 1024 * 1024 * 1024
+})
+console.log(fit.status, fit.reason, fit.report)
+```
+
+Use the same `pipelineType`, `backendDevice`, `gpuDevice`, and `main-gpu`
+settings intended for the eventual `OcrGgml` load. DocTR configurations that
+place stages on different devices return `error` with `unsupported-config`
+until a multi-device weight estimate is available.
+
 The `doctr` pipeline is language-agnostic, so `langList` can be omitted
 entirely:
 

package/fit.d.ts

@@ -0,0 +1,23 @@
+import type { OcrGgmlParams } from "./index";
+/** Both OCR model files and the backend placement used by load(). */
+export interface OcrFitRequest extends OcrGgmlParams {
+    /** Bytes to leave free on the selected backend device. */
+    marginBytes?: number;
+}
+export interface OcrFitResult {
+    status: "fits" | "does-not-fit" | "error";
+    reason: string;
+    deviceName: string;
+    deviceBytes: number;
+    hostBytes: number;
+    weightsBytes: number;
+    deviceFreeBytes: number;
+    deviceTotalBytes: number;
+    report: string;
+}
+/**
+ * Assess loading the detector and recognizer weights from GGUF metadata.
+ * This does not load weights or account for image-dependent inference memory.
+ * `error` means no reliable capacity verdict was available.
+ */
+export declare function assessFit(request: OcrFitRequest): OcrFitResult;

package/fit.js

@@ -0,0 +1,31 @@
+'use strict'
+Object.defineProperty(exports, '__esModule', { value: true })
+exports.assessFit = assessFit
+/* eslint-disable @typescript-eslint/no-require-imports -- bare-path exposes a CommonJS export shape. */
+const path = require('bare-path')
+const backends_dir_1 = require('./lib/backends-dir')
+/**
+ * Assess loading the detector and recognizer weights from GGUF metadata.
+ * This does not load weights or account for image-dependent inference memory.
+ * `error` means no reliable capacity verdict was available.
+ */
+function assessFit(request) {
+  for (const key of ['pathDetector', 'pathRecognizer']) {
+    if (typeof request[key] !== 'string' || !path.isAbsolute(request[key])) {
+      throw new TypeError(`${key} must be an absolute path`)
+    }
+  }
+  if (
+    request.marginBytes !== undefined &&
+    (!Number.isSafeInteger(request.marginBytes) || request.marginBytes < 0)
+  ) {
+    throw new RangeError('marginBytes must be a non-negative safe integer')
+  }
+  // Resolve lazily so importing this package never loads the native binding.
+  // eslint-disable-next-line @typescript-eslint/no-require-imports -- native prebuild is resolved lazily.
+  const binding = require('./binding')
+  return binding.assessFit({
+    ...request,
+    backendsDir: request.backendsDir ?? (0, backends_dir_1.resolveBackendsDir)()
+  })
+}

package/index.d.ts

@@ -2,6 +2,8 @@ import QvacLogger = require("@qvac/logging");
 import { type QvacResponse } from "@qvac/infer-base";
 import { OcrGgmlInterface, type BackendInfo, type OcrGgmlRunOptions } from "./ocr-ggml";
 import { QvacErrorAddonOcrGgml, ERR_CODES } from "./lib/error";
+export type { OcrFitRequest, OcrFitResult } from "./fit";
+export { assessFit } from "./fit";
 /**
  * OCR pipeline backing the addon.
  *   - `easyocr` (default): CRAFT detector + CRNN gen-2 recognizer.

package/index.js

@@ -1,11 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ERR_CODES = exports.QvacErrorAddonOcrGgml = exports.OcrGgml = void 0;
+exports.ERR_CODES = exports.QvacErrorAddonOcrGgml = exports.OcrGgml = exports.assessFit = void 0;
 /* eslint-disable @typescript-eslint/no-require-imports -- Bare modules and @qvac/logging expose CommonJS export shapes. */
-const path = require("bare-path");
 const fs = require("bare-fs");
 const QvacLogger = require("@qvac/logging");
-const fabricBackends = require("@qvac/fabric/backends");
 /* eslint-enable @typescript-eslint/no-require-imports */
 const infer_base_1 = require("@qvac/infer-base");
 const ocr_ggml_1 = require("./ocr-ggml");
@@ -13,6 +11,10 @@ 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 backends_dir_1 = require("./lib/backends-dir");
+const fit_1 = require("./fit");
+var fit_2 = require("./fit");
+Object.defineProperty(exports, "assessFit", { enumerable: true, get: function () { return fit_2.assessFit; } });
 const DOCTR_INTERNAL_LANG_LIST = ["en"];
 /**
  * Native language-validation failure messages (see the EasyOCR pipeline's
@@ -21,22 +23,6 @@ const DOCTR_INTERNAL_LANG_LIST = ["en"];
  * create-time failures to ERR_CODES.UNSUPPORTED_LANGUAGE.
  */
 const NATIVE_LANGUAGE_ERROR = /unsupported languages|only compatible with english/i;
-// The ggml compute backends (GGML_BACKEND_DL modules) ship exactly once, next to
-// the @qvac/fabric runtime (<root>/<host>/qvac__fabric). We deliberately do not
-// copy them into this addon to avoid duplicating tens of MB per fabric
-// consumer. On desktop, @qvac/fabric/backends resolves that root in whichever
-// package holds the runtime. On mobile the package tree isn't resolvable at
-// runtime (the worklet runs from a packed bundle), so fall back to this addon's
-// own prebuilds, where the mobile packaging stages the backends. The native side
-// appends BACKENDS_SUBDIR ("<host>/qvac__fabric") to whichever root we return.
-function resolveBackendsDir() {
-    // fabric's resolver only checks that the platform package resolves, not that
-    // its prebuilds are on disk.
-    const fabricRoot = fabricBackends.resolveBackendsDir();
-    if (fabricRoot !== null && fs.existsSync(fabricRoot))
-        return fabricRoot;
-    return path.join(__dirname, "prebuilds");
-}
 /**
  * GGML-backed OCR implementation.
  *
@@ -180,7 +166,7 @@ class OcrGgml {
         configurationParams.backendsDir =
             this.params.backendsDir !== undefined
                 ? this.params.backendsDir
-                : resolveBackendsDir();
+                : (0, backends_dir_1.resolveBackendsDir)();
         this.logger.info("Creating ocr-ggml addon");
         try {
             this.addon = this._createAddon(configurationParams);
@@ -421,6 +407,7 @@ class OcrGgml {
 exports.OcrGgml = OcrGgml;
 module.exports = {
     OcrGgml,
+    assessFit: fit_1.assessFit,
     modelClass: OcrGgml,
     get modelFile() {
         return require.addon.resolve(".");

package/lib/backends-dir.d.ts

@@ -0,0 +1 @@
+export declare function resolveBackendsDir(): string;

package/lib/backends-dir.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBackendsDir = resolveBackendsDir;
+/* eslint-disable @typescript-eslint/no-require-imports -- Bare modules and fabric expose CommonJS export shapes. */
+const path = require("bare-path");
+const fs = require("bare-fs");
+const fabricBackends = require("@qvac/fabric/backends");
+/* eslint-enable @typescript-eslint/no-require-imports */
+// The ggml backends ship beside @qvac/fabric on desktop. Mobile bundles stage
+// them beside this addon because the package tree is not resolved at runtime.
+function resolveBackendsDir() {
+    const fabricRoot = fabricBackends.resolveBackendsDir();
+    if (fabricRoot !== null && fs.existsSync(fabricRoot))
+        return fabricRoot;
+    return path.join(__dirname, "..", "prebuilds");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/ocr-ggml",
-  "version": "0.27.1",
+  "version": "0.27.3",
   "description": "GGML-backed OCR addon for qvac (EasyOCR and DocTR pipelines on GGUF weights)",
   "addon": true,
   "engines": {
@@ -9,9 +9,9 @@
   "scripts": {
     "build": "npm run build:ts && npm run build:native",
     "build:native": "bare-make generate && bare-make build && bare-make install",
-    "build:ts": "tsc -p tsconfig.build.json",
+    "build:ts": "tsc -p tsconfig.build.json && prettier --write fit.js",
     "build:pack": "npm run build:ts && mkdir -p dist && npm pack --pack-destination dist",
-    "check:generated": "npm run build:ts && out=$(git status --porcelain --untracked-files=all -- index.js ocr-ggml.js addonLogging.js index.d.ts ocr-ggml.d.ts addonLogging.d.ts lib) && { [ -z \"$out\" ] || { echo \"$out\"; exit 1; }; }",
+    "check:generated": "npm run build:ts && out=$(git status --porcelain --untracked-files=all -- index.js ocr-ggml.js addonLogging.js fit.js index.d.ts ocr-ggml.d.ts addonLogging.d.ts fit.d.ts lib) && { [ -z \"$out\" ] || { echo \"$out\"; exit 1; }; }",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "mobile:copy-prebuilds": "node ./scripts/copy-mobile-test-assets.js",
     "mobile:generate-urls": "bash ./scripts/generate-ocr-ggml-presigned-urls.sh",
@@ -45,6 +45,8 @@
     "addonLogging.d.ts",
     "binding.js",
     "index.js",
+    "fit.js",
+    "fit.d.ts",
     "ocr-ggml.js",
     "ocr-ggml.d.ts",
     "prebuilds",
@@ -80,7 +82,7 @@
     "@qvac/registry-client": "^0.4.0",
     "@types/node": "^24.2.1",
     "bare-stream": "^2.7.0",
-    "bare-subprocess": "^5.2.1",
+    "bare-subprocess": "^6.2.1",
     "cmake-bare": "^1.7.5",
     "cmake-vcpkg": "^1.1.0",
     "eslint": "^9.39.4",

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

@@ -7,7 +7,7 @@
     ],
     "current_versions": [
       {
-        "version": "0.27.1"
+        "version": "0.27.3"
       }
     ],
     "exported_symbols": [
@@ -294,10 +294,10 @@
             "__ZN2cv3MatC1ERKNSt3__16vectorIiNS1_9allocatorIiEEEEi",
             "_jpeg_mem_term",
             "_LogLuv32toXYZ",
-            "_cvSetSeqBlockSize",
             "_TIFFFileno",
             "_cvFastArctan",
             "__ZN2cv8internal18WriteStructContextD1Ev",
+            "_cvSetSeqBlockSize",
             "_png_write_info_before_PLTE",
             "_jpeg_quality_scaling",
             "__ZN2cv11FileStorage4Impl19convertToCollectionEiRNS_8FileNodeE",
@@ -1011,8 +1011,8 @@
             "__ZN2cv6reduceERKNS_11_InputArrayERKNS_12_OutputArrayEiii",
             "__ZNK2cv5MatOp11elementWiseERKNS_7MatExprE",
             "__ZN2cv7sortIdxERKNS_11_InputArrayERKNS_12_OutputArrayEi",
-            "_jpeg_consume_input",
             "_cvSetNumThreads",
+            "_jpeg_consume_input",
             "_inflatePrime",
             "_cvInRangeS",
             "_png_convert_from_time_t",
@@ -1467,7 +1467,7 @@
             "__ZNK2cv5MatOp3addERKNS_7MatExprERKNS_7Scalar_IdEERS1_",
             "_png_set_PLTE",
             "__ZN2cv15ImageCollection4Impl7advanceEv",
-            "_png_chunk_report",
+            "__ZN23qvac_lib_infer_ocr_ggml7ocr_fit14inspectOcrGgufERKNSt3__112basic_stringIcNS1_11char_traitsIcEENS1_9allocatorIcEEEEPKc",
             "__ZN2cvltERKNS_3MatEd",
             "_png_read_png",
             "_png_destroy_info_struct",
@@ -1475,6 +1475,7 @@
             "_TIFFFieldWriteCount",
             "__ZN2cv7ellipseERKNS_17_InputOutputArrayENS_6Point_IiEENS_5Size_IiEEdddRKNS_7Scalar_IdEEiii",
             "_WebPAnimEncoderNewInternal",
+            "_png_chunk_report",
             "_j12init_1pass_quantizer",
             "__ZN2cv3hal6cmp32fEPKfmS2_mPhmiiPv",
             "__ZN2cv6repeatERKNS_11_InputArrayEiiRKNS_12_OutputArrayE",
@@ -2167,6 +2168,7 @@
             "__ZN2cvngERKNS_7MatExprE",
             "_lzma_mf_bt2_find",
             "__ZNK2cv8FileNodecviEv",
+            "__ZN23qvac_lib_infer_ocr_ggml7ocr_fit12assessOcrFitERKNSt3__112basic_stringIcNS1_11char_traitsIcEENS1_9allocatorIcEEEES9_RKNS_9OcrConfigEy",
             "__ZN5doctr4ggml8pipeline22StepDoctrDetectionGGMLC2ERKNSt3__112basic_stringIcNS3_11char_traitsIcEENS3_9allocatorIcEEEEiP19ggml_backend_device",
             "__ZN2cv3Mat5setToERKNS_11_InputArrayES3_",
             "_cvGetRealND",
@@ -2320,8 +2322,8 @@
             "_lzma_free",
             "_cvCreateData",
             "_adler32_combine",
-            "_lzma_lzma_decoder_create",
             "__ZNK2cv5MatOp17augAssignMultiplyERKNS_7MatExprERNS_3MatE",
+            "_lzma_lzma_decoder_create",
             "_jpeg_free_large",
             "_png_set_invalid",
             "_TIFFSwabArrayOfShort",
@@ -2370,8 +2372,8 @@
             "_png_calloc",
             "__ZN2cv8parallel14ParallelForAPID2Ev",
             "__ZN2cvmlERKNS_3MatES2_",
-            "_lzma_simple_armthumb_decoder_init",
             "_png_get_current_row_number",
+            "_lzma_simple_armthumb_decoder_init",
             "__ZN2cv11RNG_MT19937C2Ev",
             "__ZN2cvdvEdRKNS_3MatE",
             "_TIFFReadRGBAImage",
@@ -2797,9 +2799,9 @@
             "_jinit_lossless_compressor",
             "_lzma_next_filter_update",
             "_LogLuv24fromXYZ",
+            "__ZN2cv8SVDecompERKNS_11_InputArrayERKNS_12_OutputArrayES5_S5_i",
             "_WebPAnimEncoderAssemble",
             "__ZN2cv5utils5trace7details6Region4Impl14registerRegionERNS2_23TraceManagerThreadLocalE",
-            "__ZN2cv8SVDecompERKNS_11_InputArrayERKNS_12_OutputArrayES5_S5_i",
             "_cvExp",
             "_cvRawDataToScalar",
             "_png_destroy_read_struct",
@@ -3205,25 +3207,24 @@
           ],
           "weak": [
             "__ZZZN28qvac_lib_inference_addon_cpp16OutputCallBackJs26initializeProcessingThreadENSt3__110shared_ptrINS_11OutputQueueEEEENKUlvE_clEvENUlP11uv_handle_sE_8__invokeES7_",
+            "__ZZN28qvac_lib_inference_addon_cpp2js11JsAsyncTask5startINSt3__19monostateEEEP10js_value_sP8js_env_sNS1_12CallbackDataIT_E4WorkENSB_7MarshalEENUlP11uv_handle_sE_8__invokeESF_",
+            "__ZN28qvac_lib_inference_addon_cpp2js11JsAsyncTask13onCloseHandleINSt3__19monostateEEEvP11uv_handle_s",
             "__ZN28qvac_lib_inference_addon_cpp11JsInterface8activateEP8js_env_sP18js_callback_info_s",
+            "__ZN28qvac_lib_inference_addon_cpp2js11JsAsyncTask13onEnvTeardownINSt3__19monostateEEEvP22js_deferred_teardown_sPv",
             "__ZZN28qvac_lib_inference_addon_cpp6logger8JsLogger22closeAsyncHandleLockedEvENUlP11uv_handle_sE_8__invokeES3_",
             "__ZN23qvac_lib_infer_ocr_ggml14createInstanceEP8js_env_sP18js_callback_info_s",
-            "__ZZN28qvac_lib_inference_addon_cpp2js11JsAsyncTask3runEP8js_env_sNSt3__18functionIFvvEEEENUlP11uv_handle_sE_8__invokeES9_",
             "__ZN28qvac_lib_inference_addon_cpp6logger8JsLogger13asyncCallbackEP10uv_async_s",
-            "__ZN28qvac_lib_inference_addon_cpp2js11JsAsyncTask13onCloseHandleEP11uv_handle_s",
             "__ZN28qvac_lib_inference_addon_cpp11JsInterface9setLoggerEP8js_env_sP18js_callback_info_s",
+            "__ZN23qvac_lib_infer_ocr_ggml9assessFitEP8js_env_sP18js_callback_info_s",
             "__ZN28qvac_lib_inference_addon_cpp16OutputCallBackJs16jsOutputCallbackEP10uv_async_s",
             "__ZN23qvac_lib_infer_ocr_ggml6runJobEP8js_env_sP18js_callback_info_s",
-            "__ZNSt3__116__variant_detail12__visitation6__base12__dispatcherIJLm1EEE10__dispatchB8ne190102IONS1_9__variant15__value_visitorIZZN28qvac_lib_inference_addon_cpp9out_handl27JsRuntimeStatsOutputHandlerC1EvENKUlRKNS_6vectorINS_4pairINS_12basic_stringIcNS_11char_traitsIcEENS_9allocatorIcEEEENS_7variantIJdxEEEEENSG_ISL_EEEEE_clESP_EUlOT_E_EEJRKNS0_6__baseILNS0_6_TraitE0EJdxEEEEEEDcSR_DpT0_",
             "__ZN28qvac_lib_inference_addon_cpp11JsInterface6cancelEP8js_env_sP18js_callback_info_s",
             "__ZZN28qvac_lib_inference_addon_cpp16OutputCallBackJs16drainAndTeardownEPNS0_5StateEbbENUlP11uv_handle_sE_8__invokeES4_",
-            "__ZN28qvac_lib_inference_addon_cpp2js11JsAsyncTask10onCompleteEP10uv_async_s",
+            "__ZN28qvac_lib_inference_addon_cpp2js11JsAsyncTask10onCompleteINSt3__19monostateEEEvP10uv_async_s",
             "__ZN28qvac_lib_inference_addon_cpp11JsInterface15destroyInstanceEP8js_env_sP18js_callback_info_s",
-            "__ZNSt3__116__variant_detail12__visitation6__base12__dispatcherIJLm0EEE10__dispatchB8ne190102IONS1_9__variant15__value_visitorIZZN28qvac_lib_inference_addon_cpp9out_handl27JsRuntimeStatsOutputHandlerC1EvENKUlRKNS_6vectorINS_4pairINS_12basic_stringIcNS_11char_traitsIcEENS_9allocatorIcEEEENS_7variantIJdxEEEEENSG_ISL_EEEEE_clESP_EUlOT_E_EEJRKNS0_6__baseILNS0_6_TraitE0EJdxEEEEEEDcSR_DpT0_",
             "__ZN28qvac_lib_inference_addon_cpp6logger8JsLogger13onEnvTeardownEPv",
             "__ZN28qvac_lib_inference_addon_cpp11JsInterface11loadWeightsEP8js_env_sP18js_callback_info_s",
             "__ZN28qvac_lib_inference_addon_cpp16OutputCallBackJs13onEnvTeardownEPv",
-            "__ZN28qvac_lib_inference_addon_cpp2js11JsAsyncTask13onEnvTeardownEP22js_deferred_teardown_sPv",
             "__ZN28qvac_lib_inference_addon_cpp11JsInterface13releaseLoggerEP8js_env_sP18js_callback_info_s",
             "__ZN23qvac_lib_infer_ocr_ggml14getBackendInfoEP8js_env_sP18js_callback_info_s"
           ]