@qvac/sdk 0.23.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (239) hide show
  1. package/NOTICE +115 -58
  2. package/README.md +10 -13
  3. package/dist/examples/asr/parakeet-sortformer.js +24 -14
  4. package/dist/examples/asr/parakeet-transcribepsy-filesystem.js +40 -11
  5. package/dist/examples/asr/parakeet-unified-coreml.js +14 -9
  6. package/dist/examples/asr/whispercpp-prompt.js +9 -5
  7. package/dist/examples/assess-model-fit.d.ts +7 -9
  8. package/dist/examples/assess-model-fit.js +22 -43
  9. package/dist/examples/calc-tokens.d.ts +2 -0
  10. package/dist/examples/calc-tokens.js +21 -0
  11. package/dist/examples/classification/classify-image.js +11 -5
  12. package/dist/examples/completion-stop-reason.d.ts +3 -3
  13. package/dist/examples/completion-stop-reason.js +4 -4
  14. package/dist/examples/diffusion-flux3-klein.d.ts +2 -0
  15. package/dist/examples/diffusion-flux3-klein.js +102 -0
  16. package/dist/examples/diffusion-moss-image.d.ts +2 -0
  17. package/dist/examples/diffusion-moss-image.js +126 -0
  18. package/dist/examples/diffusion-qwen-image-21.js +15 -4
  19. package/dist/examples/embed-multimodal.d.ts +2 -0
  20. package/dist/examples/embed-multimodal.js +80 -0
  21. package/dist/examples/embed-p2p.js +2 -2
  22. package/dist/examples/image/megaloc.d.ts +2 -0
  23. package/dist/examples/image/megaloc.js +37 -0
  24. package/dist/examples/llamacpp-multimodal.js +18 -0
  25. package/dist/examples/rag/rag-hyperdb/pipeline.js +2 -2
  26. package/dist/examples/rag/rag-turbovec.js +2 -2
  27. package/dist/examples/sessions.d.ts +17 -0
  28. package/dist/examples/sessions.js +63 -0
  29. package/dist/examples/tools/llamacpp-deferred-tools.js +8 -4
  30. package/dist/scripts/check-resource-collectors-packaging.js +7 -6
  31. package/dist/scripts/contract/build-contract.d.ts +2 -1
  32. package/dist/scripts/contract/build-contract.js +13 -1
  33. package/dist/scripts/contract/constants-registry.d.ts +17 -0
  34. package/dist/scripts/contract/constants-registry.js +8 -2
  35. package/dist/scripts/contract/method-shapes.d.ts +4 -0
  36. package/dist/scripts/contract/method-shapes.js +4 -0
  37. package/dist/scripts/enforce-inference-versions.d.ts +1 -1
  38. package/dist/scripts/enforce-inference-versions.js +28 -18
  39. package/dist/scripts/generate-bare-kit-runtimes.js +101 -69
  40. package/dist/src/client/api/assess-model-fit.d.ts +17 -17
  41. package/dist/src/client/api/assess-model-fit.js +18 -31
  42. package/dist/src/client/api/audio-edit.d.ts +5 -3
  43. package/dist/src/client/api/audio-edit.js +5 -3
  44. package/dist/src/client/api/audio-gen-result.js +134 -45
  45. package/dist/src/client/api/audio-gen.d.ts +40 -3
  46. package/dist/src/client/api/audio-gen.js +40 -3
  47. package/dist/src/client/api/audio-understand.d.ts +2 -2
  48. package/dist/src/client/api/audio-understand.js +2 -2
  49. package/dist/src/client/api/batch-completion.js +2 -1
  50. package/dist/src/client/api/calc-tokens.d.ts +33 -0
  51. package/dist/src/client/api/calc-tokens.js +44 -0
  52. package/dist/src/client/api/cancel.d.ts +2 -2
  53. package/dist/src/client/api/cancel.js +2 -2
  54. package/dist/src/client/api/classify.d.ts +12 -5
  55. package/dist/src/client/api/classify.js +17 -5
  56. package/dist/src/client/api/client-request-id.d.ts +0 -15
  57. package/dist/src/client/api/client-request-id.js +15 -12
  58. package/dist/src/client/api/completion-stream.d.ts +8 -1
  59. package/dist/src/client/api/completion-stream.js +10 -1
  60. package/dist/src/client/api/delete-cache.d.ts +9 -2
  61. package/dist/src/client/api/delete-cache.js +13 -3
  62. package/dist/src/client/api/diffusion.d.ts +20 -4
  63. package/dist/src/client/api/diffusion.js +23 -5
  64. package/dist/src/client/api/embed.d.ts +82 -29
  65. package/dist/src/client/api/embed.js +64 -19
  66. package/dist/src/client/api/get-model-info.d.ts +2 -2
  67. package/dist/src/client/api/get-model-info.js +2 -2
  68. package/dist/src/client/api/get-system-resources.d.ts +2 -2
  69. package/dist/src/client/api/get-system-resources.js +2 -2
  70. package/dist/src/client/api/heartbeat.d.ts +3 -2
  71. package/dist/src/client/api/heartbeat.js +3 -2
  72. package/dist/src/client/api/index.d.ts +4 -3
  73. package/dist/src/client/api/index.js +2 -1
  74. package/dist/src/client/api/invoke-plugin.d.ts +8 -2
  75. package/dist/src/client/api/invoke-plugin.js +17 -2
  76. package/dist/src/client/api/load-model.js +5 -2
  77. package/dist/src/client/api/ocr.d.ts +5 -3
  78. package/dist/src/client/api/ocr.js +44 -21
  79. package/dist/src/client/api/rag.d.ts +1 -1
  80. package/dist/src/client/api/rag.js +1 -1
  81. package/dist/src/client/api/registry.d.ts +17 -7
  82. package/dist/src/client/api/registry.js +37 -12
  83. package/dist/src/client/api/resume.d.ts +2 -1
  84. package/dist/src/client/api/resume.js +2 -2
  85. package/dist/src/client/api/rpc-server.d.ts +4 -4
  86. package/dist/src/client/api/rpc-server.js +10 -10
  87. package/dist/src/client/api/state.d.ts +2 -2
  88. package/dist/src/client/api/state.js +2 -2
  89. package/dist/src/client/api/subscribe-logs.d.ts +2 -2
  90. package/dist/src/client/api/subscribe-logs.js +2 -2
  91. package/dist/src/client/api/suspend.d.ts +4 -2
  92. package/dist/src/client/api/suspend.js +4 -3
  93. package/dist/src/client/api/text-to-speech.d.ts +14 -5
  94. package/dist/src/client/api/text-to-speech.js +83 -29
  95. package/dist/src/client/api/transcribe.d.ts +6 -2
  96. package/dist/src/client/api/transcribe.js +7 -1
  97. package/dist/src/client/api/unload-model.d.ts +19 -7
  98. package/dist/src/client/api/unload-model.js +29 -11
  99. package/dist/src/client/api/upscale.d.ts +6 -3
  100. package/dist/src/client/api/upscale.js +9 -4
  101. package/dist/src/client/api/vector-index.d.ts +50 -16
  102. package/dist/src/client/api/vector-index.js +100 -48
  103. package/dist/src/client/api/video-request.d.ts +5 -5
  104. package/dist/src/client/api/video.d.ts +3 -2
  105. package/dist/src/client/api/video.js +3 -2
  106. package/dist/src/client/api/vla.d.ts +9 -5
  107. package/dist/src/client/api/vla.js +17 -8
  108. package/dist/src/client/api/world.d.ts +5 -5
  109. package/dist/src/client/api/world.js +4 -4
  110. package/dist/src/client/init-hooks.d.ts +6 -4
  111. package/dist/src/client/init-hooks.js +12 -15
  112. package/dist/src/client/logging-stream-registry.d.ts +6 -3
  113. package/dist/src/client/logging-stream-registry.js +31 -12
  114. package/dist/src/client/rpc/bundle-stamp.d.ts +29 -0
  115. package/dist/src/client/rpc/bundle-stamp.js +75 -0
  116. package/dist/src/client/rpc/expo-home-dir.d.ts +2 -0
  117. package/dist/src/client/rpc/expo-home-dir.js +4 -0
  118. package/dist/src/client/rpc/expo-rpc-client.js +189 -135
  119. package/dist/src/client/rpc/node-rpc-client.js +322 -413
  120. package/dist/src/client/rpc/pear-runtime.d.ts +12 -0
  121. package/dist/src/client/rpc/pear-runtime.js +12 -0
  122. package/dist/src/client/rpc/rpc-client.d.ts +5 -4
  123. package/dist/src/client/rpc/rpc-client.js +126 -23
  124. package/dist/src/client/rpc/rpc-error.js +21 -2
  125. package/dist/src/client/rpc/unbundled-harness.d.ts +16 -0
  126. package/dist/src/client/rpc/unbundled-harness.js +27 -0
  127. package/dist/src/client/rpc/worker-failure.d.ts +27 -0
  128. package/dist/src/client/rpc/worker-failure.js +61 -0
  129. package/dist/src/client/session-registry.d.ts +75 -0
  130. package/dist/src/client/session-registry.js +149 -0
  131. package/dist/src/client/session.d.ts +125 -0
  132. package/dist/src/client/session.js +148 -0
  133. package/dist/src/commands/bundle/addons.d.ts +14 -0
  134. package/dist/src/commands/bundle/addons.js +65 -0
  135. package/dist/src/commands/bundle/constants.js +1 -0
  136. package/dist/src/commands/bundle/entry-gen.d.ts +1 -5
  137. package/dist/src/commands/bundle/entry-gen.js +17 -50
  138. package/dist/src/commands/bundle/index.d.ts +59 -13
  139. package/dist/src/commands/bundle/index.js +345 -121
  140. package/dist/src/commands/bundle/link.d.ts +58 -0
  141. package/dist/src/commands/bundle/link.js +135 -0
  142. package/dist/src/commands/bundle/node-support.d.ts +13 -0
  143. package/dist/src/commands/bundle/node-support.js +23 -0
  144. package/dist/src/commands/bundle/read-bundle.d.ts +9 -0
  145. package/dist/src/commands/bundle/read-bundle.js +27 -0
  146. package/dist/src/commands/bundle/resolve-sdk-import.d.ts +6 -0
  147. package/dist/src/commands/bundle/resolve-sdk-import.js +24 -28
  148. package/dist/src/commands/bundle/scratch.d.ts +35 -0
  149. package/dist/src/commands/bundle/scratch.js +178 -0
  150. package/dist/src/commands/bundle/targets.d.ts +14 -0
  151. package/dist/src/commands/bundle/targets.js +37 -0
  152. package/dist/src/commands/host-prebuilds/index.d.ts +5 -4
  153. package/dist/src/commands/host-prebuilds/index.js +9 -7
  154. package/dist/src/commands/index.d.ts +4 -3
  155. package/dist/src/commands/verify/abi.d.ts +20 -14
  156. package/dist/src/commands/verify/abi.js +11 -79
  157. package/dist/src/commands/verify/bare-kit-runtime.d.ts +20 -22
  158. package/dist/src/commands/verify/bare-kit-runtime.js +102 -150
  159. package/dist/src/commands/verify/bare-kit-runtimes.d.ts +10 -9
  160. package/dist/src/commands/verify/bare-kit-runtimes.js +21 -21
  161. package/dist/src/commands/verify/bundle-source.js +25 -21
  162. package/dist/src/commands/verify/engines-advice.d.ts +2 -8
  163. package/dist/src/commands/verify/engines-advice.js +7 -54
  164. package/dist/src/commands/verify/index.d.ts +30 -29
  165. package/dist/src/commands/verify/index.js +92 -200
  166. package/dist/src/commands/verify/prebuilds.d.ts +3 -5
  167. package/dist/src/commands/verify/prebuilds.js +1 -2
  168. package/dist/src/commands/verify/resource-collectors.d.ts +0 -6
  169. package/dist/src/commands/verify/resource-collectors.js +1 -50
  170. package/dist/src/commands/verify/sidecar-runtime.d.ts +6 -0
  171. package/dist/src/commands/verify/sidecar-runtime.js +51 -0
  172. package/dist/src/expo/plugins/withBareKit.d.ts +59 -0
  173. package/dist/src/expo/plugins/withBareKit.js +204 -0
  174. package/dist/src/expo/plugins/withMobileBundle.d.ts +4 -11
  175. package/dist/src/expo/plugins/withMobileBundle.js +36 -57
  176. package/dist/src/expo/plugins/withQvacSDK.d.ts +1 -0
  177. package/dist/src/expo/plugins/withQvacSDK.js +3 -0
  178. package/dist/src/index.d.ts +6 -5
  179. package/dist/src/index.js +10 -14
  180. package/dist/src/logging/utils.js +10 -2
  181. package/dist/src/plugin-ids.d.ts +2 -1
  182. package/dist/src/plugin-ids.js +2 -0
  183. package/dist/src/schemas/public.d.ts +1 -1
  184. package/dist/src/schemas/public.js +1 -1
  185. package/dist/src/schemas/sdk-errors-client.d.ts +5 -6
  186. package/dist/src/schemas/sdk-errors-client.js +30 -36
  187. package/dist/src/schemas/sdk-errors-server.d.ts +11 -1
  188. package/dist/src/schemas/sdk-errors-server.js +60 -2
  189. package/dist/src/server/rpc/rpc-utils.d.ts +25 -4
  190. package/dist/src/server/rpc/rpc-utils.js +39 -5
  191. package/dist/src/utils/errors-client.d.ts +37 -29
  192. package/dist/src/utils/errors-client.js +50 -41
  193. package/dist/src/utils/errors-server.d.ts +59 -1
  194. package/dist/src/utils/errors-server.js +110 -1
  195. package/dist/src/utils/withTimeout.js +34 -17
  196. package/dist/src/worker/handle-request.js +25 -22
  197. package/dist/src/worker/handler-utils.d.ts +2 -6
  198. package/dist/src/worker/handler-utils.js +2 -20
  199. package/dist/src/worker/index.d.ts +2 -4
  200. package/dist/src/worker/index.js +23 -35
  201. package/dist/src/worker/plugins/ggml-image-embedding.d.ts +2 -0
  202. package/dist/src/worker/plugins/ggml-image-embedding.js +1 -0
  203. package/dist/src/worker/shim.d.ts +4 -0
  204. package/dist/src/worker/shim.js +7 -0
  205. package/dist/src/worker/start.d.ts +9 -0
  206. package/dist/src/worker/start.js +16 -0
  207. package/dist/src/worker/unbundled-shim.d.ts +2 -0
  208. package/dist/src/worker/unbundled-shim.js +4 -0
  209. package/docs/system-resources-support-matrix.md +27 -19
  210. package/package.json +62 -51
  211. package/src/electron-forge/index.cjs +65 -91
  212. package/dist/examples/model-fit-ui/server.d.ts +0 -24
  213. package/dist/examples/model-fit-ui/server.js +0 -221
  214. package/dist/src/client/rpc/ensure-worker-ready.d.ts +0 -9
  215. package/dist/src/client/rpc/ensure-worker-ready.js +0 -17
  216. package/dist/src/client/rpc/init-timeout.d.ts +0 -26
  217. package/dist/src/client/rpc/init-timeout.js +0 -25
  218. package/dist/src/client/rpc/ipc-socket-path.d.ts +0 -11
  219. package/dist/src/client/rpc/ipc-socket-path.js +0 -30
  220. package/dist/src/client/rpc/worker-startup-error.d.ts +0 -12
  221. package/dist/src/client/rpc/worker-startup-error.js +0 -13
  222. package/dist/src/commands/bundle/bare-pack.d.ts +0 -21
  223. package/dist/src/commands/bundle/bare-pack.js +0 -77
  224. package/dist/src/commands/bundle/manifest.d.ts +0 -25
  225. package/dist/src/commands/bundle/manifest.js +0 -192
  226. package/dist/src/expo/plugins/link-addons.d.ts +0 -18
  227. package/dist/src/expo/plugins/link-addons.js +0 -65
  228. package/dist/src/pear/pre.d.ts +0 -21
  229. package/dist/src/pear/pre.js +0 -450
  230. package/dist/src/server/env.d.ts +0 -22
  231. package/dist/src/server/env.js +0 -59
  232. package/dist/src/server/utils/qvac-paths.d.ts +0 -2
  233. package/dist/src/server/utils/qvac-paths.js +0 -5
  234. package/dist/src/server/utils/worker-lock.d.ts +0 -3
  235. package/dist/src/server/utils/worker-lock.js +0 -67
  236. package/dist/src/worker/create-server.d.ts +0 -8
  237. package/dist/src/worker/create-server.js +0 -51
  238. package/dist/src/worker/lifecycle.d.ts +0 -23
  239. package/dist/src/worker/lifecycle.js +0 -149
@@ -3,17 +3,15 @@
3
3
  *
4
4
  * From packages/sdk:
5
5
  * npx tsx examples/asr/parakeet-unified-coreml.ts \
6
- * /path/to/parakeet-unified-en-0.6b.q4_0.gguf [16-kHz-wav-file]
6
+ * /path/to/parakeet-unified-en-0.6b.q4_0.gguf <16-kHz-wav-file>
7
7
  *
8
8
  * The GGUF must be a regenerated Unified artifact. The five compiled Core ML
9
9
  * files are downloaded through the SDK registry and staged beside the GGUF.
10
- * The default audio is examples/audio/sample-16khz.wav.
11
10
  */
12
11
  import { downloadAsset, getModelInfo, loadModel, transcribe, unloadModel } from '@qvac/sdk';
13
- import { link, mkdir, mkdtemp, open, rm, symlink } from 'node:fs/promises';
12
+ import { copyFile, link, mkdir, mkdtemp, open, rm, symlink } from 'node:fs/promises';
14
13
  import { tmpdir } from 'node:os';
15
14
  import { basename, join, resolve } from 'node:path';
16
- import { fileURLToPath } from 'node:url';
17
15
  const MODEL_STEM = 'parakeet-unified-en-0.6b';
18
16
  const COREML_FILES = [
19
17
  ['PARAKEET_UNIFIED_COREMLDATA', 'analytics/coremldata.bin'],
@@ -22,9 +20,8 @@ const COREML_FILES = [
22
20
  ['PARAKEET_UNIFIED_MODEL', 'model.mil'],
23
21
  ['PARAKEET_UNIFIED_WEIGHT', 'weights/weight.bin']
24
22
  ];
25
- const defaultAudioPath = fileURLToPath(new URL('../audio/sample-16khz.wav', import.meta.url));
26
23
  const modelPath = process.argv[2];
27
- const audioPath = process.argv[3] ?? defaultAudioPath;
24
+ const audioPath = process.argv[3];
28
25
  async function checkModel(path) {
29
26
  const name = basename(path);
30
27
  if (!/^parakeet-unified-en-0\.6b\.(?:f16|q4_0|q8_0)\.gguf$/.test(name)) {
@@ -66,7 +63,15 @@ async function stageModel(path) {
66
63
  throw new Error(`Core ML file is missing from the SDK cache: ${name}`);
67
64
  const targetPath = join(bundleDir, relativePath);
68
65
  await mkdir(join(targetPath, '..'), { recursive: true });
69
- await link(sourcePath, targetPath);
66
+ try {
67
+ await link(sourcePath, targetPath);
68
+ }
69
+ catch (error) {
70
+ // A hard link cannot cross filesystems, e.g. a QVAC_HOME_DIR on another drive.
71
+ if (error.code !== 'EXDEV')
72
+ throw error;
73
+ await copyFile(sourcePath, targetPath);
74
+ }
70
75
  }
71
76
  return { modelSrc, dir };
72
77
  }
@@ -76,9 +81,9 @@ async function stageModel(path) {
76
81
  }
77
82
  }
78
83
  async function main() {
79
- if (!modelPath) {
84
+ if (!modelPath || !audioPath) {
80
85
  throw new Error('Usage: npx tsx examples/asr/parakeet-unified-coreml.ts ' +
81
- '<regenerated-unified-gguf> [16-kHz-wav-file]');
86
+ '<regenerated-unified-gguf> <16-kHz-wav-file>');
82
87
  }
83
88
  let staged;
84
89
  let modelId;
@@ -2,14 +2,18 @@
2
2
  * Whisper transcription with prompt example.
3
3
  *
4
4
  * Usage:
5
- * npx tsx examples/asr/whispercpp-prompt.ts
5
+ * npx tsx examples/asr/whispercpp-prompt.ts <wav-file>
6
6
  *
7
- * This example requires a test audio file (default: examples/audio/sample-16khz.wav).
8
- * Sample audio files are available in the QVAC source repository, but not included in the published npm package.
9
- * Set audioChunk to a custom WAV, or download the default audio into examples/audio/:
7
+ * Pass the path of a 16 kHz mono WAV file. A sample is available in the QVAC
8
+ * source repository, but not included in the published npm package:
10
9
  * https://github.com/tetherto/qvac/blob/main/packages/sdk/examples/audio/sample-16khz.wav
11
10
  */
12
11
  import { loadModel, unloadModel, transcribe, WHISPER_TINY } from '@qvac/sdk';
12
+ const audioFilePath = process.argv[2];
13
+ if (!audioFilePath) {
14
+ console.error('Usage: npx tsx examples/asr/whispercpp-prompt.ts <wav-file>');
15
+ process.exit(1);
16
+ }
13
17
  try {
14
18
  console.log('▸ Starting Whisper transcription with prompt example...');
15
19
  // Load the Whisper model
@@ -64,7 +68,7 @@ try {
64
68
  console.log('▸ Transcribing audio...');
65
69
  const text = await transcribe({
66
70
  modelId,
67
- audioChunk: 'examples/audio/sample-16khz.wav',
71
+ audioChunk: audioFilePath,
68
72
  prompt: 'This is a test recording with clear speech and proper punctuation.'
69
73
  });
70
74
  console.log('▸ Transcription result:');
@@ -1,14 +1,12 @@
1
1
  /**
2
- * Which models is this machine likely to run — asked before downloading any
3
- * weights. Nothing is fetched, loaded or reserved.
2
+ * Which models fit this machine, asked before downloading any weights. Each
3
+ * engine's fitter reads the registry's weightless description of a model, so
4
+ * nothing is fetched beyond tens of KB, loaded or reserved.
4
5
  *
5
- * The header prints the evidence the answer rests on: `system-memory` on a
6
- * CPU-only or integrated-GPU host, `device-memory` on a discrete card,
7
- * `device-budget` for the per-process allowance Windows grants on one. Which
8
- * of those applies depends on where the engine would put the model.
9
- *
10
- * `unknown` is a real answer, not an error: the evidence does not support a
11
- * call either way. Show it as "can't say", never as "no".
6
+ * Each model gets its own verdict and the memory it takes on each device, and
7
+ * the set gets one verdict for all of them loaded together, with what it takes
8
+ * from each memory pool. `unknown` is a valid answer: show it as "can't say",
9
+ * never as "no".
12
10
  */
13
11
  export {};
14
12
  //# sourceMappingURL=assess-model-fit.d.ts.map
@@ -1,18 +1,15 @@
1
1
  /**
2
- * Which models is this machine likely to run — asked before downloading any
3
- * weights. Nothing is fetched, loaded or reserved.
2
+ * Which models fit this machine, asked before downloading any weights. Each
3
+ * engine's fitter reads the registry's weightless description of a model, so
4
+ * nothing is fetched beyond tens of KB, loaded or reserved.
4
5
  *
5
- * The header prints the evidence the answer rests on: `system-memory` on a
6
- * CPU-only or integrated-GPU host, `device-memory` on a discrete card,
7
- * `device-budget` for the per-process allowance Windows grants on one. Which
8
- * of those applies depends on where the engine would put the model.
9
- *
10
- * `unknown` is a real answer, not an error: the evidence does not support a
11
- * call either way. Show it as "can't say", never as "no".
6
+ * Each model gets its own verdict and the memory it takes on each device, and
7
+ * the set gets one verdict for all of them loaded together, with what it takes
8
+ * from each memory pool. `unknown` is a valid answer: show it as "can't say",
9
+ * never as "no".
12
10
  */
13
11
  import { assessModelFit, QWEN3_600M_INST_Q4, QWEN3_1_7B_INST_Q4, QWEN3_4B_INST_Q4_K_M, QWEN3_8B_INST_Q4_K_M, QWEN3_8_27B_MULTIMODAL_UD_Q8_K_XL } from '@qvac/sdk';
14
- // Sizes the assessment the way it sizes the load: the estimator reads the
15
- // context out of the config `loadModel` would be given.
12
+ // The fitter sizes the load as `loadModel` would run it, context included.
16
13
  const CONTEXT_TOKENS = 8192;
17
14
  // A ladder ending well past what a laptop has, so one screen shows every verdict.
18
15
  const CANDIDATES = [
@@ -23,8 +20,8 @@ const CANDIDATES = [
23
20
  QWEN3_8_27B_MULTIMODAL_UD_Q8_K_XL
24
21
  ];
25
22
  const VERDICT_MARK = {
26
- 'likely-fits': '✔',
27
- 'likely-too-large': '✖',
23
+ fits: '✔',
24
+ 'does-not-fit': '✖',
28
25
  unknown: '?'
29
26
  };
30
27
  function gib(bytes) {
@@ -36,40 +33,22 @@ try {
36
33
  modelSrc: model,
37
34
  modelType: 'llamacpp-completion',
38
35
  modelConfig: { ctx_size: CONTEXT_TOKENS }
39
- })),
40
- // Declared for aggregation only, not a scheduling instruction: 'sequential'
41
- // counts the largest operation peak, 'concurrent' counts one per model.
42
- execution: 'sequential',
43
- policy: 'interactive-v1'
36
+ }))
44
37
  });
45
- console.log(`▸ Budget basis: ${result.basis}`);
46
- if (result.budget) {
47
- console.log(` ${gib(result.budget.availableAfterReserveBytes)} budget` +
48
- ` (${gib(result.budget.totalBytes)} total,` +
49
- ` ${gib(result.budget.usedBytes)} in use,` +
50
- ` ${gib(result.budget.availableBytes)} free,` +
51
- ` ${gib(result.budget.reservedBytes)} held back)`);
52
- }
53
- // Says which device the verdicts assume, when the model would run on a GPU.
54
- const placement = result.assumptions.find((line) => line.includes('assumed to execute on'));
55
- if (placement)
56
- console.log(`▸ ${placement}`);
57
- console.log(`\n▸ At ${CONTEXT_TOKENS} tokens of context`);
38
+ console.log(`▸ At ${CONTEXT_TOKENS} tokens of context, each model alone`);
58
39
  for (const [index, model] of result.models.entries()) {
59
- const mark = VERDICT_MARK[model.verdict];
60
- const size = gib(CANDIDATES[index].expectedSize).padStart(9);
61
- const needs = model.evidence === 'computed-only' && model.floorBytes
62
- ? `at least ${gib(model.floorBytes)}`
63
- : '';
64
- console.log(` ${mark} ${model.name.padEnd(46)} ${size} on disk ${needs}`);
65
- // Present on every `unknown`, and worth surfacing: it names what is missing.
66
- if (model.verdict === 'unknown') {
67
- for (const reason of model.reasons)
68
- console.log(` ${reason}`);
40
+ const candidate = CANDIDATES[index];
41
+ const size = gib(candidate.expectedSize).padStart(9);
42
+ console.log(` ${VERDICT_MARK[model.status]} ${candidate.name.padEnd(46)} ${size} on disk`);
43
+ for (const device of model.devices) {
44
+ console.log(` ${device.name.padEnd(10)} ${gib(device.usedBytes).padStart(10)}`);
69
45
  }
70
46
  }
71
- console.log(`\n▸ All five together, sequentially: ${result.verdict}`);
72
- console.log('▸ Advisory only — this does not gate loadModel or reserve anything.');
47
+ console.log(`\n▸ All five loaded together: ${result.verdict}`);
48
+ for (const pool of result.pools) {
49
+ const free = pool.freeBytes === undefined ? 'no free figure' : `of ${gib(pool.freeBytes)} free`;
50
+ console.log(` ${pool.id.padEnd(14)} ${gib(pool.usedBytes).padStart(10)} ${free}`);
51
+ }
73
52
  process.exit(0);
74
53
  }
75
54
  catch (error) {
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=calc-tokens.d.ts.map
@@ -0,0 +1,21 @@
1
+ import { QWEN3_600M_INST_Q4, calcTokens, close, loadModel, unloadModel } from '@qvac/sdk';
2
+ let modelId;
3
+ try {
4
+ modelId = await loadModel({ modelSrc: QWEN3_600M_INST_Q4 });
5
+ const raw = await calcTokens({ modelId, text: 'Summarize this conversation.' });
6
+ const rendered = await calcTokens({
7
+ modelId,
8
+ history: [{ role: 'system', content: 'You are a helpful assistant.' }],
9
+ text: 'Summarize this conversation.'
10
+ });
11
+ console.log({ raw, rendered });
12
+ }
13
+ catch (error) {
14
+ console.error('✖', error);
15
+ process.exitCode = 1;
16
+ }
17
+ finally {
18
+ if (modelId)
19
+ await unloadModel({ modelId });
20
+ await close();
21
+ }
@@ -1,16 +1,22 @@
1
1
  import fs from 'fs';
2
- import { loadModel, classify, unloadModel } from '@qvac/sdk';
2
+ import { loadModel, classify, unloadModel, MOBILENETV3_3CLASS_V3_FP16 } from '@qvac/sdk';
3
3
  /**
4
- * Classify an image using the bundled MobileNetV3-Small model.
4
+ * Classify an image with MobileNetV3-Small, which produces three classes:
5
+ * "food", "report", "other".
5
6
  *
6
- * The bundled model produces three classes: "food", "report", "other".
7
- * No modelSrc is needed — the model ships inside @qvac/classification-ggml.
7
+ * Usage: npx tsx examples/classification/classify-image.ts <image-path>
8
8
  */
9
9
  async function main() {
10
+ const imagePath = process.argv[2];
11
+ if (!imagePath) {
12
+ console.error('Usage: npx tsx examples/classification/classify-image.ts <image-path>');
13
+ process.exit(1);
14
+ }
10
15
  const modelId = await loadModel({
16
+ modelSrc: MOBILENETV3_3CLASS_V3_FP16,
11
17
  modelType: 'ggml-classification'
12
18
  });
13
- const image = fs.readFileSync('image.jpg');
19
+ const image = fs.readFileSync(imagePath);
14
20
  const results = await classify({ modelId, image });
15
21
  console.log('Classification results:');
16
22
  for (const { label, confidence } of results) {
@@ -4,9 +4,9 @@
4
4
  * `completion()` sets `stopReason` on the aggregated `final` promise to
5
5
  * indicate why the model stopped generating:
6
6
  *
7
- * - `undefined` — natural end-of-sequence (EOS). The model finished on
8
- * its own. This is the common case and the backwards-
9
- * compatible default.
7
+ * - `"eos"` — natural end-of-sequence. The model finished on its own.
8
+ * - `"stopSequence"` — a configured stop sequence ended generation.
9
+ * - `undefined` — the backend did not report a specific stop reason.
10
10
  * - `"length"` — the `predict` token budget was exhausted. Output is
11
11
  * truncated; the model did not reach a natural stopping
12
12
  * point.
@@ -4,9 +4,9 @@
4
4
  * `completion()` sets `stopReason` on the aggregated `final` promise to
5
5
  * indicate why the model stopped generating:
6
6
  *
7
- * - `undefined` — natural end-of-sequence (EOS). The model finished on
8
- * its own. This is the common case and the backwards-
9
- * compatible default.
7
+ * - `"eos"` — natural end-of-sequence. The model finished on its own.
8
+ * - `"stopSequence"` — a configured stop sequence ended generation.
9
+ * - `undefined` — the backend did not report a specific stop reason.
10
10
  * - `"length"` — the `predict` token budget was exhausted. Output is
11
11
  * truncated; the model did not reach a natural stopping
12
12
  * point.
@@ -47,7 +47,7 @@ try {
47
47
  process.stdout.write(event.text);
48
48
  }
49
49
  const final1 = await run1.final;
50
- console.log(`\n▸ stopReason: ${final1.stopReason ?? '(undefined — natural EOS)'}`);
50
+ console.log(`\n▸ stopReason: ${final1.stopReason ?? '(not reported)'}`);
51
51
  // --- Case 2: predict budget exhausted → stopReason = "length" ---
52
52
  console.log('\n▸ Case 2: predict budget hit (predict: 10)');
53
53
  const run2 = completion({
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=diffusion-flux3-klein.d.ts.map
@@ -0,0 +1,102 @@
1
+ import { close, diffusion, loadModel, unloadModel } from '@qvac/sdk';
2
+ import fs from 'fs';
3
+ import path from 'path';
4
+ // FLUX.3 Image Klein text-to-image, or reference editing when reference images are passed.
5
+ // FLUX.3 pairs its diffusion model with a Qwen3-VL 4B text encoder and the FLUX.2 VAE.
6
+ // Defaults download pinned Hugging Face weights; overrides accept paths or URLs.
7
+ // FLUX.3 model terms: https://huggingface.co/black-forest-labs/flux-3-image-klein/blob/09561231f44e41381c461caf53d5452005a60ac9/LICENSE.md
8
+ const HF = 'https://huggingface.co';
9
+ const prompt = process.argv[2] || "A lovely cat holding a sign that says 'FLUX3'";
10
+ const outputDir = process.argv[3] || '.';
11
+ const diffusionModelSrc = process.argv[4] ||
12
+ `${HF}/leejet/flux-3-image-klein-GGUF/resolve/1c2ad2f9b9247ccca6506a23bdb033fdb0873321/flux3-image-klein-Q8_0.gguf`;
13
+ const llmModelSrc = process.argv[5] ||
14
+ `${HF}/Qwen/Qwen3-VL-4B-Instruct-GGUF/resolve/1cd86afb9a95c410a6038ab3b40d8b578c892266/Qwen3VL-4B-Instruct-Q4_K_M.gguf`;
15
+ const vaeModelSrc = process.argv[6] ||
16
+ `${HF}/Comfy-Org/Flux-2-Klein-4B/resolve/5b3abca5c0dc1ecd4eaf3340868d09063fc1c965/split_files/vae/flux2-vae.safetensors`;
17
+ const referencePaths = process.argv.slice(7);
18
+ const usage = 'Usage: node --import tsx examples/diffusion-flux3-klein.ts [prompt] [outputDir] [model] [llm] [vae] [...references]';
19
+ if (process.argv.includes('--help')) {
20
+ console.log(usage);
21
+ console.log('▸ Defaults download pinned Hugging Face weights. Model overrides accept paths or URLs.');
22
+ console.log('▸ Pass up to 10 reference image paths to edit them instead of generating from text.');
23
+ process.exit(0);
24
+ }
25
+ if (referencePaths.length > 10) {
26
+ console.error('✖ FLUX.3 accepts at most 10 reference images');
27
+ console.error(usage);
28
+ process.exit(1);
29
+ }
30
+ function modelSource(source) {
31
+ return /^https?:\/\//.test(source) ? source : path.resolve(source);
32
+ }
33
+ let modelId;
34
+ try {
35
+ const init_images = referencePaths.map((file) => new Uint8Array(fs.readFileSync(file)));
36
+ console.log('▸ Loading FLUX.3 Image Klein split-layout model...');
37
+ modelId = await loadModel({
38
+ modelSrc: modelSource(diffusionModelSrc),
39
+ modelType: 'sdcpp-generation',
40
+ modelConfig: {
41
+ llmModelSrc: modelSource(llmModelSrc),
42
+ vaeModelSrc: modelSource(vaeModelSrc),
43
+ flash_attn: true
44
+ },
45
+ onProgress: (progress) => {
46
+ const mb = (bytes) => (bytes / 1e6).toFixed(1);
47
+ const line = `▸ Downloading ${progress.percentage.toFixed(0)}% (${mb(progress.downloaded)}/${mb(progress.total)} MB)`;
48
+ process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
49
+ if (progress.percentage >= 100)
50
+ process.stderr.write('\n');
51
+ }
52
+ });
53
+ console.log(`▸ Model loaded: ${modelId}`);
54
+ console.log(`▸ Generating: "${prompt}"`);
55
+ // Recommended settings for the distilled model: 16 Euler steps at CFG 1.
56
+ const { progressStream, outputs, stats } = diffusion({
57
+ modelId,
58
+ prompt,
59
+ ...(init_images.length > 0 && { init_images }),
60
+ width: 512,
61
+ height: 512,
62
+ steps: 16,
63
+ cfg_scale: 1,
64
+ sampling_method: 'euler',
65
+ seed: 42
66
+ });
67
+ for await (const { step, totalSteps } of progressStream) {
68
+ console.log(`▸ step ${step}/${totalSteps}`);
69
+ }
70
+ const buffers = await outputs;
71
+ if (buffers.length === 0)
72
+ throw new Error('FLUX.3 returned no image.');
73
+ for (let i = 0; i < buffers.length; i++) {
74
+ const outputPath = path.join(outputDir, `flux3_${i}.png`);
75
+ fs.writeFileSync(outputPath, buffers[i]);
76
+ console.log(`▸ Saved ${outputPath}`);
77
+ }
78
+ console.log('▸ Stats:', await stats);
79
+ }
80
+ catch (error) {
81
+ console.error('✖', error);
82
+ process.exitCode = 1;
83
+ }
84
+ finally {
85
+ try {
86
+ if (modelId)
87
+ await unloadModel({ modelId, clearStorage: false });
88
+ }
89
+ catch (error) {
90
+ console.error('✖ Unload failed:', error);
91
+ process.exitCode = 1;
92
+ }
93
+ try {
94
+ await close();
95
+ }
96
+ catch (error) {
97
+ console.error('✖ Cleanup failed:', error);
98
+ process.exitCode = 1;
99
+ }
100
+ }
101
+ if (!process.exitCode)
102
+ console.log('▸ Done');
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=diffusion-moss-image.d.ts.map
@@ -0,0 +1,126 @@
1
+ import { close, diffusion, loadModel, unloadModel } from '@qvac/sdk';
2
+ import fs from 'fs';
3
+ import path from 'path';
4
+ // Generate a poster from a MOSS-Image JSON layout prompt.
5
+ // Use the pinned model revisions from the diffusion addon's MOSS-Image downloader.
6
+ // Model terms (Apache-2.0): https://huggingface.co/OpenMOSS-Team/MOSS-Image-SFT
7
+ const HF = 'https://huggingface.co';
8
+ const mossRepo = `${HF}/Comfy-Org/MOSS-Image/resolve/530a4c94f92c35ef6818b1b035a983fe9dcf5f54`;
9
+ const outputDir = process.argv[2] || '.';
10
+ const diffusionModelSrc = process.argv[3] || `${mossRepo}/diffusion_models/moss_image_sft_bf16.safetensors`;
11
+ const llmModelSrc = process.argv[4] ||
12
+ `${HF}/unsloth/Qwen3.5-9B-GGUF/resolve/3885219b6810b007914f3a7950a8d1b469d598a5/Qwen3.5-9B-Q4_K_M.gguf`;
13
+ const vaeModelSrc = process.argv[5] || `${mossRepo}/vae/flux2-vae_small.safetensors`;
14
+ const tokenizerSrc = process.argv[6] ||
15
+ `${HF}/OpenMOSS-Team/MOSS-Image-SFT/resolve/f972bd4b4b9e3852133cc5da954d87bc32cd8fb9/tokenizer/tokenizer.json`;
16
+ const usage = 'Usage: node --import tsx examples/diffusion-moss-image.ts [outputDir] [model] [llm] [vae] [tokenizer]';
17
+ if (process.argv.includes('--help')) {
18
+ console.log(usage);
19
+ console.log('▸ Defaults download pinned Hugging Face weights. Model overrides accept paths or URLs.');
20
+ process.exit(0);
21
+ }
22
+ const width = 1024;
23
+ const height = 1024;
24
+ // Boxes are [y_min, x_min, y_max, x_max] in absolute pixels with the canvas
25
+ // centre as the origin, so a 1024×1024 canvas spans -512..512 on both axes.
26
+ // Keep them consistent with width and height.
27
+ const layout = {
28
+ summary: {
29
+ meta: ['poster'],
30
+ canvas: 'single',
31
+ caption: 'A minimalist travel poster of a snowy mountain at sunrise, flat illustration style.'
32
+ },
33
+ items: [
34
+ {
35
+ label: 'text',
36
+ caption: 'Bold white sans-serif title across the top of the poster.',
37
+ text: 'SUMMIT',
38
+ bbox: [-448, -352, -320, 352]
39
+ },
40
+ {
41
+ label: 'object',
42
+ caption: 'A snowy mountain peak lit by an orange sunrise.',
43
+ bbox: [-224, -320, 384, 320]
44
+ }
45
+ ],
46
+ bbox_coord_space: 'abs_centralized',
47
+ bbox_format: 'yxyx'
48
+ };
49
+ function modelSource(source) {
50
+ return /^https?:\/\//.test(source) ? source : path.resolve(source);
51
+ }
52
+ let modelId;
53
+ // Progress fires many times per percent on a multi-GB download; write once per whole percent
54
+ // of each file.
55
+ const lastPercent = new Map();
56
+ try {
57
+ console.log('▸ Loading MOSS-Image...');
58
+ modelId = await loadModel({
59
+ modelSrc: modelSource(diffusionModelSrc),
60
+ modelType: 'sdcpp-generation',
61
+ modelConfig: {
62
+ llmModelSrc: modelSource(llmModelSrc),
63
+ vaeModelSrc: modelSource(vaeModelSrc),
64
+ tokenizerSrc: modelSource(tokenizerSrc),
65
+ flash_attn: true
66
+ },
67
+ onProgress: (progress) => {
68
+ const percent = Math.floor(progress.percentage);
69
+ if (lastPercent.get(progress.downloadKey) === percent)
70
+ return;
71
+ lastPercent.set(progress.downloadKey, percent);
72
+ const mb = (bytes) => (bytes / 1e6).toFixed(1);
73
+ const line = `▸ Downloading ${progress.percentage.toFixed(0)}% (${mb(progress.downloaded)}/${mb(progress.total)} MB)`;
74
+ process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
75
+ if (progress.percentage >= 100)
76
+ process.stderr.write('\n');
77
+ }
78
+ });
79
+ console.log(`▸ Model loaded: ${modelId}`);
80
+ const { progressStream, outputs, stats } = diffusion({
81
+ modelId,
82
+ prompt: JSON.stringify(layout),
83
+ width,
84
+ height,
85
+ steps: 50,
86
+ cfg_scale: 3,
87
+ sampling_method: 'euler',
88
+ scheduler: 'discrete',
89
+ seed: 42
90
+ });
91
+ for await (const { step, totalSteps } of progressStream) {
92
+ console.log(`▸ step ${step}/${totalSteps}`);
93
+ }
94
+ const buffers = await outputs;
95
+ if (buffers.length === 0)
96
+ throw new Error('MOSS-Image returned no image.');
97
+ for (let i = 0; i < buffers.length; i++) {
98
+ const outputPath = path.join(outputDir, `moss_image_${i}.png`);
99
+ fs.writeFileSync(outputPath, buffers[i]);
100
+ console.log(`▸ Saved ${outputPath}`);
101
+ }
102
+ console.log('▸ Stats:', await stats);
103
+ }
104
+ catch (error) {
105
+ console.error('✖', error);
106
+ process.exitCode = 1;
107
+ }
108
+ finally {
109
+ try {
110
+ if (modelId)
111
+ await unloadModel({ modelId, clearStorage: false });
112
+ }
113
+ catch (error) {
114
+ console.error('✖ Unload failed:', error);
115
+ process.exitCode = 1;
116
+ }
117
+ try {
118
+ await close();
119
+ }
120
+ catch (error) {
121
+ console.error('✖ Cleanup failed:', error);
122
+ process.exitCode = 1;
123
+ }
124
+ }
125
+ if (!process.exitCode)
126
+ console.log('▸ Done');
@@ -1,9 +1,11 @@
1
1
  import { close, diffusion, loadModel, unloadModel } from '@qvac/sdk';
2
2
  import fs from 'fs';
3
3
  import path from 'path';
4
- // Combine two reference images into an RGBA image with a transparent background.
4
+ // Combine two references into an RGBA image, with optional Qwen-Image-2.1-Turbo sampling.
5
+ // Set QWEN_TURBO=1 and pass Turbo weights as the model argument, as a path or URL.
5
6
  // Use the pinned model revisions from the diffusion addon's Qwen-Image-2.1 downloader.
6
7
  // Model terms: https://huggingface.co/Qwen/Qwen-Image-2.1/blob/d26bb61231c349cf6b7896fa83353113880e1ba3/LICENSE
8
+ const turbo = process.env['QWEN_TURBO'] === '1';
7
9
  const HF = 'https://huggingface.co';
8
10
  const encoderRepo = `${HF}/Qwen/Qwen3-VL-8B-Instruct-GGUF/resolve/f982a07559d4a2f6c8744d840bf6fccab30eea96`;
9
11
  const referencePathA = process.argv[2];
@@ -21,6 +23,7 @@ const usage = 'Usage: node --import tsx examples/diffusion-qwen-image-21.ts <ref
21
23
  if (process.argv.includes('--help')) {
22
24
  console.log(usage);
23
25
  console.log('▸ Defaults download pinned Hugging Face weights. Model overrides accept paths or URLs.');
26
+ console.log('▸ Turbo: set QWEN_TURBO=1 and pass your Turbo weights as the model argument.');
24
27
  console.log('▸ The default prompt combines both subjects on a transparent background.');
25
28
  process.exit(0);
26
29
  }
@@ -29,6 +32,10 @@ if (!referencePathA || !referencePathB) {
29
32
  console.error(usage);
30
33
  process.exit(1);
31
34
  }
35
+ if (turbo && !process.argv[6]) {
36
+ console.error('✖ Pass the Turbo diffusion weights as the model argument, as a path or URL');
37
+ process.exit(1);
38
+ }
32
39
  function modelSource(source) {
33
40
  return /^https?:\/\//.test(source) ? source : path.resolve(source);
34
41
  }
@@ -61,8 +68,12 @@ try {
61
68
  init_images,
62
69
  width: 512,
63
70
  height: 512,
64
- steps: 30,
65
- cfg_scale: 6,
71
+ ...(!turbo && { steps: 30 }),
72
+ cfg_scale: turbo ? 1 : 6,
73
+ ...(turbo && {
74
+ // Official Turbo sample_sigmas plus the native terminal zero.
75
+ custom_sigmas: [1, 0.978453, 0.95418, 0.926626, 0.89508, 0.845148, 0.704534, 0.414568, 0]
76
+ }),
66
77
  sampling_method: 'euler',
67
78
  seed: 42
68
79
  });
@@ -73,7 +84,7 @@ try {
73
84
  if (buffers.length === 0)
74
85
  throw new Error('Qwen-Image-2.1 returned no image.');
75
86
  for (let i = 0; i < buffers.length; i++) {
76
- const outputPath = path.join(outputDir, `qwen_image_21_${i}.png`);
87
+ const outputPath = path.join(outputDir, `qwen_image_21${turbo ? '_turbo' : ''}_${i}.png`);
77
88
  fs.writeFileSync(outputPath, buffers[i]);
78
89
  console.log(`▸ Saved ${outputPath}`);
79
90
  }
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=embed-multimodal.d.ts.map