@qvac/sdk 0.21.1 → 0.22.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 (167) hide show
  1. package/NOTICE +84 -55
  2. package/README.md +167 -24
  3. package/dist/examples/abot-world.js +1 -1
  4. package/dist/examples/advisory-model-fit.d.ts +0 -58
  5. package/dist/examples/advisory-model-fit.js +23 -150
  6. package/dist/examples/asr/moss-transcribe-filesystem.d.ts +2 -0
  7. package/dist/examples/asr/moss-transcribe-filesystem.js +84 -0
  8. package/dist/examples/asr/moss-transcribe-fit.d.ts +2 -0
  9. package/dist/examples/asr/moss-transcribe-fit.js +40 -0
  10. package/dist/examples/asr/nemotron-diarization-filesystem.d.ts +2 -0
  11. package/dist/examples/asr/nemotron-diarization-filesystem.js +64 -0
  12. package/dist/examples/asr/parakeet-ctc-filesystem.js +2 -2
  13. package/dist/examples/asr/parakeet-indic-conformer-filesystem.js +2 -2
  14. package/dist/examples/asr/parakeet-microphone-record.js +1 -1
  15. package/dist/examples/asr/parakeet-microphone-stream.js +1 -1
  16. package/dist/examples/asr/parakeet-nemotron-filesystem.js +3 -3
  17. package/dist/examples/asr/parakeet-sortformer-streaming.js +2 -2
  18. package/dist/examples/asr/parakeet-sortformer.js +1 -1
  19. package/dist/examples/asr/parakeet-tdt-filesystem-chunked.js +2 -2
  20. package/dist/examples/asr/parakeet-tdt-filesystem.js +2 -2
  21. package/dist/examples/asr/parakeet-unified-coreml.js +2 -2
  22. package/dist/examples/asr/parakeet-unified-filesystem.js +2 -2
  23. package/dist/examples/asr/whispercpp-filesystem-streaming.js +1 -1
  24. package/dist/examples/asr/whispercpp-filesystem.js +1 -1
  25. package/dist/examples/asr/whispercpp-microphone-record.js +1 -1
  26. package/dist/examples/asr/whispercpp-prompt.js +1 -1
  27. package/dist/examples/assess-model-fit.js +3 -6
  28. package/dist/examples/audiogen/edit-music.js +2 -2
  29. package/dist/examples/audiogen/generate-cover.js +2 -2
  30. package/dist/examples/audiogen/generate-music-minimax.js +1 -1
  31. package/dist/examples/audiogen/generate-music.js +1 -1
  32. package/dist/examples/audiogen/understand-music.js +2 -2
  33. package/dist/examples/batch-completion.d.ts +1 -1
  34. package/dist/examples/batch-completion.js +1 -1
  35. package/dist/examples/bci/bci-filesystem-streaming.js +2 -2
  36. package/dist/examples/bci/bci-filesystem.js +2 -2
  37. package/dist/examples/concurrent-completion-collision.js +1 -1
  38. package/dist/examples/config-reload.js +1 -1
  39. package/dist/examples/decisions.d.ts +2 -0
  40. package/dist/examples/decisions.js +38 -0
  41. package/dist/examples/diffusion-esrgan-upscale.js +1 -1
  42. package/dist/examples/diffusion-flux2-klein-img2img.js +1 -1
  43. package/dist/examples/diffusion-img2img.js +1 -1
  44. package/dist/examples/diffusion-img2vid-ltx.js +1 -1
  45. package/dist/examples/diffusion-img2vid-minimax-h3.d.ts +2 -0
  46. package/dist/examples/diffusion-img2vid-minimax-h3.js +72 -0
  47. package/dist/examples/diffusion-img2vid.js +1 -1
  48. package/dist/examples/llamacpp-filesystem.js +1 -1
  49. package/dist/examples/llamacpp-multi-gpu.js +2 -2
  50. package/dist/examples/llamacpp-structured-output.js +1 -1
  51. package/dist/examples/mcp-websearch.d.ts +2 -2
  52. package/dist/examples/mcp-websearch.js +3 -3
  53. package/dist/examples/model-fit-ui/server.d.ts +1 -1
  54. package/dist/examples/model-fit-ui/server.js +1 -1
  55. package/dist/examples/multi-job-completion.d.ts +1 -1
  56. package/dist/examples/multi-job-completion.js +1 -1
  57. package/dist/examples/ocr-fasttext.js +1 -1
  58. package/dist/examples/tools/llamacpp-tools-auto-dialect.js +1 -1
  59. package/dist/examples/tools/llamacpp-tools-gemma4.js +1 -1
  60. package/dist/examples/tools/llamacpp-tools-qwen35.js +1 -1
  61. package/dist/examples/tts/llm-to-tts-streaming.d.ts +2 -2
  62. package/dist/examples/tts/llm-to-tts-streaming.js +2 -2
  63. package/dist/examples/tts/moss-sound-effect-controls.d.ts +2 -0
  64. package/dist/examples/tts/moss-sound-effect-controls.js +88 -0
  65. package/dist/examples/tts/moss-sound-effect.d.ts +2 -0
  66. package/dist/examples/tts/moss-sound-effect.js +86 -0
  67. package/dist/examples/tts/moss-speech-audio.d.ts +2 -0
  68. package/dist/examples/tts/moss-speech-audio.js +159 -0
  69. package/dist/examples/tts/moss-speech.d.ts +2 -0
  70. package/dist/examples/tts/moss-speech.js +70 -0
  71. package/dist/examples/vla-groot.js +2 -2
  72. package/dist/examples/vla-pi05.js +2 -2
  73. package/dist/examples/vla-smolvla.js +2 -2
  74. package/dist/examples/voice-assistant/voice-assistant.js +1 -1
  75. package/dist/scripts/contract/build-contract.d.ts +3 -1
  76. package/dist/scripts/contract/build-contract.js +40 -2
  77. package/dist/scripts/contract/build-model-type-maps.d.ts +6 -1
  78. package/dist/scripts/contract/build-model-type-maps.js +3 -2
  79. package/dist/scripts/contract/constants-registry.d.ts +4 -0
  80. package/dist/scripts/contract/constants-registry.js +3 -1
  81. package/dist/scripts/contract/method-shapes.d.ts +1 -0
  82. package/dist/scripts/contract/method-shapes.js +1 -0
  83. package/dist/scripts/export-contract.js +20 -7
  84. package/dist/scripts/run-unit-tests.js +10 -5
  85. package/dist/src/client/api/assess-model-fit.d.ts +5 -5
  86. package/dist/src/client/api/assess-model-fit.js +5 -6
  87. package/dist/src/client/api/audio-edit.d.ts +14 -2
  88. package/dist/src/client/api/audio-edit.js +14 -2
  89. package/dist/src/client/api/audio-gen.d.ts +10 -2
  90. package/dist/src/client/api/audio-gen.js +10 -2
  91. package/dist/src/client/api/audio-understand.d.ts +1 -1
  92. package/dist/src/client/api/audio-understand.js +1 -1
  93. package/dist/src/client/api/batch-completion.js +1 -1
  94. package/dist/src/client/api/completion-stream.js +1 -1
  95. package/dist/src/client/api/decide.d.ts +31 -0
  96. package/dist/src/client/api/decide.js +29 -0
  97. package/dist/src/client/api/index.d.ts +1 -0
  98. package/dist/src/client/api/index.js +1 -0
  99. package/dist/src/client/api/load-model.d.ts +1 -0
  100. package/dist/src/client/api/text-to-speech.d.ts +1 -0
  101. package/dist/src/client/api/text-to-speech.js +15 -22
  102. package/dist/src/client/api/transcribe.js +5 -2
  103. package/dist/src/client/api/video-request.d.ts +5 -5
  104. package/dist/src/client/api/video.d.ts +23 -3
  105. package/dist/src/client/api/video.js +23 -3
  106. package/dist/src/commands/bundle/bare-pack.d.ts +8 -0
  107. package/dist/src/commands/bundle/bare-pack.js +28 -5
  108. package/dist/src/commands/bundle/constants.js +2 -0
  109. package/dist/src/commands/bundle/index.d.ts +7 -6
  110. package/dist/src/commands/bundle/index.js +126 -43
  111. package/dist/src/commands/bundle/manifest.d.ts +2 -0
  112. package/dist/src/commands/bundle/manifest.js +3 -2
  113. package/dist/src/commands/host-prebuilds/index.d.ts +15 -7
  114. package/dist/src/commands/host-prebuilds/index.js +35 -16
  115. package/dist/src/commands/index.d.ts +1 -1
  116. package/dist/src/commands/index.js +1 -1
  117. package/dist/src/commands/verify/addon-source.d.ts +12 -0
  118. package/dist/src/commands/verify/addon-source.js +36 -3
  119. package/dist/src/commands/verify/bare-kit-runtimes.js +2 -1
  120. package/dist/src/commands/verify/node-modules-source.js +10 -1
  121. package/dist/src/{expo/plugins/patches/qvac-platform-addons.d.ts → commands/verify/platform-addons.d.ts} +6 -10
  122. package/dist/src/{expo/plugins/patches/qvac-platform-addons.js → commands/verify/platform-addons.js} +2 -45
  123. package/dist/src/commands/verify/prebuilds.d.ts +7 -10
  124. package/dist/src/commands/verify/prebuilds.js +43 -34
  125. package/dist/src/expo/plugins/get-project-root.d.ts +1 -1
  126. package/dist/src/expo/plugins/link-addons.d.ts +18 -0
  127. package/dist/src/expo/plugins/link-addons.js +65 -0
  128. package/dist/src/expo/plugins/withAndroidArchitecture.d.ts +1 -1
  129. package/dist/src/expo/plugins/withAndroidNdkVersion.d.ts +1 -1
  130. package/dist/src/expo/plugins/withDeviceInfo.d.ts +1 -1
  131. package/dist/src/expo/plugins/withMobileBundle.d.ts +11 -21
  132. package/dist/src/expo/plugins/withMobileBundle.js +22 -112
  133. package/dist/src/expo/plugins/withOpenCL.d.ts +1 -1
  134. package/dist/src/expo/plugins/withQvacSDK.d.ts +1 -1
  135. package/dist/src/index.d.ts +3 -3
  136. package/dist/src/index.js +2 -2
  137. package/dist/src/logging/base-logger.js +1 -1
  138. package/dist/src/logging/utils.js +1 -1
  139. package/dist/src/pear/pre.js +2 -0
  140. package/dist/src/plugin-ids.d.ts +3 -1
  141. package/dist/src/plugin-ids.js +4 -0
  142. package/dist/src/schemas/public.d.ts +2 -1
  143. package/dist/src/schemas/public.js +2 -1
  144. package/dist/src/schemas/sdk-errors-client.d.ts +3 -0
  145. package/dist/src/schemas/sdk-errors-client.js +16 -0
  146. package/dist/src/schemas/sdk-errors-server.d.ts +1 -0
  147. package/dist/src/schemas/sdk-errors-server.js +5 -0
  148. package/dist/src/utils/errors-client.d.ts +10 -0
  149. package/dist/src/utils/errors-client.js +18 -0
  150. package/dist/src/utils/mcp-adapter.js +12 -8
  151. package/dist/src/utils/tool-helpers.d.ts +1 -1
  152. package/dist/src/utils/tool-helpers.js +20 -52
  153. package/dist/src/worker/create-server.d.ts +1 -0
  154. package/dist/src/worker/create-server.js +5 -0
  155. package/dist/src/worker/index.js +4 -0
  156. package/dist/src/worker/lifecycle.js +9 -1
  157. package/dist/src/worker/plugins/llamacpp-decision.d.ts +2 -0
  158. package/dist/src/worker/plugins/llamacpp-decision.js +1 -0
  159. package/dist/src/worker/plugins/moss-transcribe.d.ts +2 -0
  160. package/dist/src/worker/plugins/moss-transcribe.js +1 -0
  161. package/package.json +39 -35
  162. package/src/electron-forge/index.cjs +12 -71
  163. package/dist/scripts/link-workspace-inference.d.ts +0 -2
  164. package/dist/scripts/link-workspace-inference.js +0 -31
  165. package/src/expo/plugins/patches/android-link.mjs +0 -67
  166. package/src/expo/plugins/patches/ios-link.mjs +0 -67
  167. package/src/expo/plugins/patches/qvac-platform-addons.ts +0 -124
@@ -1,60 +1,2 @@
1
- /**
2
- * Advisory model fit check.
3
- *
4
- * Before a load, the SDK runs the fitter belonging to the engine that would
5
- * run it and projects whether the exact configuration it is about to load will
6
- * fit in device memory. Desktop runs it in a disposable Bare child; mobile,
7
- * which cannot spawn one, runs it on a worker thread.
8
- *
9
- * The result is ADVISORY. It never blocks a load. `does-not-fit` is logged and
10
- * the ordinary load path runs unchanged. Crashes, timeouts, malformed
11
- * responses, unsupported configurations, and internal errors all resolve to
12
- * "no evidence" and are equally non-blocking. No verdict changes the load;
13
- * `getLoadedModelInfo` returns it as `fitProbe`.
14
- *
15
- * The verdict is emitted on the SDK server log stream, not to stdout, so this
16
- * example subscribes to `loggingStream({ id: SDK_LOG_ID })` and reprints the
17
- * `[advisory-fit:…]` lines.
18
- *
19
- * ---------------------------------------------------------------------------
20
- * What fits on this machine (Apple M4 Pro, 24 GiB unified memory)
21
- * ---------------------------------------------------------------------------
22
- *
23
- * Measured at the default 1024 MiB margin. The fitter budgets against what the
24
- * machine can actually keep resident
25
- * (total − wired − compressor: 17.4 GiB on this machine at idle), not the raw
26
- * RAM figure.
27
- *
28
- * PROJECTED TO FIT — all layers on GPU
29
- * Qwen3.5 0.8B Q4_K_M 0.5 GiB @ 4k ctx
30
- * gpt-oss-20B Q4_K_M 10.8 GiB @ 32k ctx
31
- * gte-large fp16 0.6 GiB (embedding, context pinned to 512)
32
- *
33
- * PROJECTED NOT TO FIT — with `gpu_layers: 99` pinned
34
- * gpt-oss-20B Q4_K_M 10.8 GiB @ 128k ctx with an f32 KV cache ← below
35
- *
36
- * These rows were measured with `gpu_layers` pinned at 99. Loads no longer pin
37
- * the layer count, and the `does-not-fit` row has not been re-measured
38
- * unpinned.
39
- *
40
- * gpt-oss-20B at 128k context FITS with the default KV cache and DOES NOT FIT
41
- * once `cache-type-k`/`cache-type-v` are set to `f32`. Same model, same
42
- * context, same machine — the verdict tracks the configuration, not the file
43
- * size.
44
- *
45
- * Two boundaries worth understanding when reading verdicts:
46
- *
47
- * 1. The verdict answers for a PLACEMENT, not a model. With `gpu_layers`
48
- * unset, the fitter may move layers to the CPU side; setting it pins the
49
- * layer count, and `does-not-fit` then means "not at this placement".
50
- * 2. A `does-not-fit` configuration can still RUN on macOS when the OS
51
- * compresses and pages hard enough — and a `fits` configuration right at
52
- * the boundary can still fail at first decode under memory pressure.
53
- * Prediction cannot separate those cases from a snapshot; the addon-side
54
- * probe decode (QVAC-24114) is the runtime check that catches the
55
- * remainder. The verdict here is the honest working-set budget, and the
56
- * measured failure modes punish over-committing, so treat `does-not-fit`
57
- * as "expect degradation or decode failure", not "the load will error".
58
- */
59
1
  export {};
60
2
  //# sourceMappingURL=advisory-model-fit.d.ts.map
@@ -1,156 +1,29 @@
1
- /**
2
- * Advisory model fit check.
3
- *
4
- * Before a load, the SDK runs the fitter belonging to the engine that would
5
- * run it and projects whether the exact configuration it is about to load will
6
- * fit in device memory. Desktop runs it in a disposable Bare child; mobile,
7
- * which cannot spawn one, runs it on a worker thread.
8
- *
9
- * The result is ADVISORY. It never blocks a load. `does-not-fit` is logged and
10
- * the ordinary load path runs unchanged. Crashes, timeouts, malformed
11
- * responses, unsupported configurations, and internal errors all resolve to
12
- * "no evidence" and are equally non-blocking. No verdict changes the load;
13
- * `getLoadedModelInfo` returns it as `fitProbe`.
14
- *
15
- * The verdict is emitted on the SDK server log stream, not to stdout, so this
16
- * example subscribes to `loggingStream({ id: SDK_LOG_ID })` and reprints the
17
- * `[advisory-fit:…]` lines.
18
- *
19
- * ---------------------------------------------------------------------------
20
- * What fits on this machine (Apple M4 Pro, 24 GiB unified memory)
21
- * ---------------------------------------------------------------------------
22
- *
23
- * Measured at the default 1024 MiB margin. The fitter budgets against what the
24
- * machine can actually keep resident
25
- * (total − wired − compressor: 17.4 GiB on this machine at idle), not the raw
26
- * RAM figure.
27
- *
28
- * PROJECTED TO FIT — all layers on GPU
29
- * Qwen3.5 0.8B Q4_K_M 0.5 GiB @ 4k ctx
30
- * gpt-oss-20B Q4_K_M 10.8 GiB @ 32k ctx
31
- * gte-large fp16 0.6 GiB (embedding, context pinned to 512)
32
- *
33
- * PROJECTED NOT TO FIT — with `gpu_layers: 99` pinned
34
- * gpt-oss-20B Q4_K_M 10.8 GiB @ 128k ctx with an f32 KV cache ← below
35
- *
36
- * These rows were measured with `gpu_layers` pinned at 99. Loads no longer pin
37
- * the layer count, and the `does-not-fit` row has not been re-measured
38
- * unpinned.
39
- *
40
- * gpt-oss-20B at 128k context FITS with the default KV cache and DOES NOT FIT
41
- * once `cache-type-k`/`cache-type-v` are set to `f32`. Same model, same
42
- * context, same machine — the verdict tracks the configuration, not the file
43
- * size.
44
- *
45
- * Two boundaries worth understanding when reading verdicts:
46
- *
47
- * 1. The verdict answers for a PLACEMENT, not a model. With `gpu_layers`
48
- * unset, the fitter may move layers to the CPU side; setting it pins the
49
- * layer count, and `does-not-fit` then means "not at this placement".
50
- * 2. A `does-not-fit` configuration can still RUN on macOS when the OS
51
- * compresses and pages hard enough — and a `fits` configuration right at
52
- * the boundary can still fail at first decode under memory pressure.
53
- * Prediction cannot separate those cases from a snapshot; the addon-side
54
- * probe decode (QVAC-24114) is the runtime check that catches the
55
- * remainder. The verdict here is the honest working-set budget, and the
56
- * measured failure modes punish over-committing, so treat `does-not-fit`
57
- * as "expect degradation or decode failure", not "the load will error".
58
- */
59
- import { completion, loadModel, unloadModel, loggingStream, SDK_LOG_ID, QWEN3_5_0_8B_MULTIMODAL_Q4_K_M, GPT_OSS_20B_INST_Q4_K_M } from '@qvac/sdk';
60
- // The oversized load below is expected to be reported as `does-not-fit` and
61
- // then attempted anyway, because the check is advisory. It really does try to
62
- // allocate ~11 GiB, so it stays opt-in.
63
- const ATTEMPT_OVERSIZED = process.env['QVAC_FIT_DEMO_ATTEMPT_OVERSIZED'] === '1';
64
- // Reprint the worker's advisory verdicts. They arrive on the SDK server log
65
- // stream; everything else on that stream is filtered out to keep this readable.
66
- //
67
- // Called once per phase rather than once for the process: a subscription
68
- // currently stops delivering after any `unloadModel`, so a single one would go
69
- // silent before the second verdict. Resubscribing after the unload works.
70
- function watchVerdicts() {
71
- void (async () => {
72
- for await (const log of loggingStream({ id: SDK_LOG_ID })) {
73
- if (log.message.includes('[advisory-fit:')) {
74
- console.log(`▸ [${log.level.toUpperCase()}] ${log.message}`);
75
- }
76
- }
77
- })().catch(() => {
78
- // Stream terminated — normal on shutdown.
79
- });
80
- }
81
- watchVerdicts();
1
+ // `modelFitPolicy` decides what the engine fitter's verdict does to a load:
2
+ // `log` (the default) reports it and loads anyway, `refuse` rejects a load the
3
+ // fitter projects will not fit, `off` skips the check.
4
+ import { loadModel, loggingStream, SDK_LOG_ID, GPT_OSS_20B_INST_Q4_K_M } from '@qvac/sdk';
5
+ // Verdicts go to the SDK server log stream, not stdout.
6
+ void (async () => {
7
+ for await (const log of loggingStream({ id: SDK_LOG_ID })) {
8
+ if (log.message.includes('[advisory-fit:'))
9
+ console.log(`▸ ${log.message}`);
10
+ }
11
+ })().catch(() => { });
82
12
  try {
83
- // 1. A load the fitter projects to fit. The verdict carries the plan it
84
- // projected: resolved context, offloaded layers, and GPU device count.
85
- console.log('▸ Loading Qwen3.5 0.8B @ 4k — expected verdict: projected to fit');
86
- const smallModelId = await loadModel({
87
- modelSrc: QWEN3_5_0_8B_MULTIMODAL_Q4_K_M,
88
- modelConfig: { ctx_size: 4096 }
13
+ // gpt-oss-20B fits here at the default KV cache type and does not at f32.
14
+ await loadModel({
15
+ modelSrc: GPT_OSS_20B_INST_Q4_K_M,
16
+ modelConfig: {
17
+ ctx_size: 131072,
18
+ 'cache-type-k': 'f32',
19
+ 'cache-type-v': 'f32'
20
+ },
21
+ modelFitPolicy: 'refuse'
89
22
  });
90
- console.log(`▸ Loaded ${smallModelId}\n`);
91
- const result = completion({
92
- modelId: smallModelId,
93
- history: [{ role: 'user', content: 'Say hello in five words.' }],
94
- stream: false,
95
- generationParams: { predict: 48 }
96
- });
97
- const final = await result.final;
98
- console.log(`▸ Completion still works normally: ${final.contentText.trim().slice(0, 120)}\n`);
99
- // Unloaded before the next phase, so the second verdict is measured on an
100
- // idle machine and stays comparable to the fixture tables above. Leaving it
101
- // loaded would shift the verdict: the check reserves resident weight bytes
102
- // through the fit margin, and the fitter also sees system-wide wired memory.
103
- await unloadModel({ modelId: smallModelId, clearStorage: false });
104
- watchVerdicts();
105
- // 2. A load the fitter projects NOT to fit. The point of this example is that
106
- // the SDK reports the verdict and then loads anyway — the check is
107
- // evidence, not admission control.
108
- if (!ATTEMPT_OVERSIZED) {
109
- console.log('▸ Skipping the oversized gpt-oss-20B load.');
110
- console.log('▸ Set QVAC_FIT_DEMO_ATTEMPT_OVERSIZED=1 to let it run and watch the');
111
- console.log(' load proceed past a `does-not-fit` verdict (allocates ~11 GiB).');
112
- }
113
- else {
114
- console.log('▸ Loading gpt-oss-20B @ 128k with an f32 KV cache');
115
- console.log('▸ Expected verdict: projected NOT to fit');
116
- console.log('▸ The load is attempted regardless. That is the fail-open contract:');
117
- console.log(' the verdict is evidence, not admission control.\n');
118
- const bigModelId = await loadModel({
119
- modelSrc: GPT_OSS_20B_INST_Q4_K_M,
120
- modelConfig: {
121
- ctx_size: 131072,
122
- 'cache-type-k': 'f32',
123
- 'cache-type-v': 'f32'
124
- }
125
- });
126
- console.log(`▸ Load returned ${bigModelId} — the advisory verdict did not block it`);
127
- // Loading is not the same as being usable: a model can load and then fail
128
- // at decode time. Gemma 4 31B does exactly that on this machine. So run a
129
- // real completion and report throughput rather than trusting the load.
130
- try {
131
- const check = completion({
132
- modelId: bigModelId,
133
- history: [{ role: 'user', content: 'Name three colours. Answer briefly.' }],
134
- stream: false,
135
- generationParams: { predict: 40 }
136
- });
137
- const checkFinal = await check.final;
138
- console.log(`▸ ...and it actually runs: ${checkFinal.stats?.tokensPerSecond?.toFixed(1) ?? '?'} tok/s ` +
139
- `— the OS compressed and paged its way past the working-set budget`);
140
- }
141
- catch (inferenceError) {
142
- console.log(`▸ ...but it cannot run: ${inferenceError instanceof Error ? inferenceError.message : String(inferenceError)}`);
143
- console.log('▸ The verdict was right, and `loadModel` succeeding did not mean usable.');
144
- }
145
- await unloadModel({ modelId: bigModelId, clearStorage: false });
146
- }
23
+ console.log('▸ Loaded — the fitter projected this one to fit here');
24
+ process.exit(0);
147
25
  }
148
26
  catch (error) {
149
- // A failing load here is the native loader's own error, not the fit check.
150
- // The check never throws and never converts a verdict into a load failure.
151
27
  console.error('✖', error instanceof Error ? error.message : error);
152
- process.exitCode = 1;
28
+ process.exit(1);
153
29
  }
154
- // The log subscription is an open stream and would otherwise keep the process
155
- // alive after the work is done.
156
- process.exit(process.exitCode ?? 0);
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=moss-transcribe-filesystem.d.ts.map
@@ -0,0 +1,84 @@
1
+ /**
2
+ * MOSS-Transcribe-Diarize: one model produces text, timestamps, and speaker labels.
3
+ *
4
+ * Run from packages/sdk:
5
+ * npx tsx examples/asr/moss-transcribe-filesystem.ts <audio.wav> [moss.gguf] [hotword ...]
6
+ * npx tsx examples/asr/moss-transcribe-filesystem.ts examples/audio/diarization-sample-16k.wav
7
+ * npx tsx examples/asr/moss-transcribe-filesystem.ts meeting.wav ./moss.gguf QVAC OpenMOSS
8
+ *
9
+ * Omit the GGUF path to download MOSS_TRANSCRIBE_DIARIZE_Q8_0 from the registry.
10
+ * Use a 16 kHz mono PCM WAV recording. Hotwords are optional names/domain terms
11
+ * for this request, with at most 64 terms of 64 UTF-8 bytes each.
12
+ * This is batch transcription; MOSS streaming and CoreML are not exposed.
13
+ */
14
+ import { access, constants } from 'node:fs/promises';
15
+ import { loadModel, unloadModel, transcribe, close, MOSS_TRANSCRIBE_DIARIZE_Q8_0 } from '@qvac/sdk';
16
+ const [audioFilePath, modelPath, ...hotwords] = process.argv.slice(2);
17
+ if (!audioFilePath || audioFilePath === '--help') {
18
+ console.error('Usage: npx tsx examples/asr/moss-transcribe-filesystem.ts <audio.wav> [moss.gguf] [hotword ...]');
19
+ process.exit(audioFilePath === '--help' ? 0 : 1);
20
+ }
21
+ let modelId;
22
+ try {
23
+ // Check the recording before starting a model download.
24
+ await access(audioFilePath, constants.R_OK);
25
+ console.error('▸ Loading MOSS-Transcribe-Diarize...');
26
+ modelId = await loadModel({
27
+ modelType: 'moss-transcribe',
28
+ modelSrc: modelPath ?? MOSS_TRANSCRIBE_DIARIZE_Q8_0,
29
+ modelConfig: {
30
+ maxThreads: 4,
31
+ useGPU: false // Set true to opt into Metal on a supported Mac.
32
+ },
33
+ onProgress: (progress) => {
34
+ const mb = (bytes) => (bytes / 1e6).toFixed(1);
35
+ const line = `▸ Downloading ${progress.percentage.toFixed(0)}% (${mb(progress.downloaded)}/${mb(progress.total)} MB)`;
36
+ process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
37
+ if (process.stderr.isTTY && progress.percentage >= 100)
38
+ process.stderr.write('\n');
39
+ }
40
+ });
41
+ console.error(`▸ Transcribing ${audioFilePath}...`);
42
+ const segments = await transcribe({
43
+ modelId,
44
+ audioChunk: audioFilePath,
45
+ metadata: true,
46
+ hotwords,
47
+ maxNewTokens: 0 // Use the model's default decoding limit.
48
+ // For a custom instruction, replace hotwords with prompt; do not supply both.
49
+ });
50
+ for (const segment of segments) {
51
+ const start = (segment.startMs / 1000).toFixed(2);
52
+ const end = (segment.endMs / 1000).toFixed(2);
53
+ const speaker = segment.speaker ??
54
+ (segment.speakerId !== undefined ? `Speaker ${segment.speakerId}` : 'Unknown speaker');
55
+ console.log(`[${start}s → ${end}s] ${speaker}: ${segment.text.trim()}`);
56
+ }
57
+ if (segments.length === 0)
58
+ console.error('▸ No speech segments returned.');
59
+ }
60
+ catch (error) {
61
+ console.error('✖ MOSS transcription failed:', error);
62
+ process.exitCode = 1;
63
+ }
64
+ finally {
65
+ try {
66
+ if (modelId !== undefined) {
67
+ console.error('▸ Unloading MOSS model...');
68
+ await unloadModel({ modelId });
69
+ }
70
+ }
71
+ catch (error) {
72
+ console.error('✖ Could not unload the MOSS model:', error);
73
+ process.exitCode = 1;
74
+ }
75
+ finally {
76
+ try {
77
+ await close();
78
+ }
79
+ catch (error) {
80
+ console.error('✖ Could not close the SDK:', error);
81
+ process.exitCode = 1;
82
+ }
83
+ }
84
+ }
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=moss-transcribe-fit.d.ts.map
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Assess MOSS memory before downloading weights or loading a model.
3
+ * Run from packages/sdk:
4
+ * node --import tsx examples/asr/moss-transcribe-fit.ts <audio-seconds> [moss.gguf] [hotword ...]
5
+ * Without a local path, uses the Q8_0 registry model's weightless description.
6
+ */
7
+ import { assessModelFit, close, MOSS_TRANSCRIBE_DIARIZE_Q8_0 } from '@qvac/sdk';
8
+ const [seconds, modelPath, ...hotwords] = process.argv.slice(2);
9
+ const audioSeconds = Number(seconds);
10
+ if (seconds === '--help' || !Number.isFinite(audioSeconds) || audioSeconds <= 0) {
11
+ console.error('Usage: node --import tsx examples/asr/moss-transcribe-fit.ts <audio-seconds> [moss.gguf] [hotword ...]');
12
+ process.exit(seconds === '--help' ? 0 : 1);
13
+ }
14
+ try {
15
+ console.error('▸ Assessing MOSS memory for the declared recording...');
16
+ const result = await assessModelFit({
17
+ models: [
18
+ {
19
+ modelType: 'moss-transcribe',
20
+ modelSrc: modelPath ?? MOSS_TRANSCRIBE_DIARIZE_Q8_0,
21
+ modelConfig: { useGPU: false, maxThreads: 4 },
22
+ transcriptionWorkload: { audioSeconds, hotwords, maxNewTokens: 0 }
23
+ }
24
+ ]
25
+ });
26
+ console.log(JSON.stringify(result, null, 2));
27
+ }
28
+ catch (error) {
29
+ console.error('✖ MOSS memory assessment failed:', error);
30
+ process.exitCode = 1;
31
+ }
32
+ finally {
33
+ try {
34
+ await close();
35
+ }
36
+ catch (error) {
37
+ console.error('✖ Could not close the SDK:', error);
38
+ process.exitCode = 1;
39
+ }
40
+ }
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=nemotron-diarization-filesystem.d.ts.map
@@ -0,0 +1,64 @@
1
+ /**
2
+ * Nemotron 3 Diarization detects up to eight speakers, including overlapping turns.
3
+ * It reports speaker activity, not recognized words.
4
+ *
5
+ * Run from packages/sdk with a local Nemotron 3 Diarization GGUF:
6
+ * npx tsx examples/asr/nemotron-diarization-filesystem.ts <nemotron-diarization.gguf> [audio.wav]
7
+ *
8
+ * Defaults to examples/audio/diarization-sample-16k.wav in the source repository.
9
+ * Supply a 16 kHz mono PCM WAV when copying this example elsewhere.
10
+ */
11
+ import { access, constants } from 'node:fs/promises';
12
+ import { loadModel, unloadModel, transcribe, close } from '@qvac/sdk';
13
+ const [modelPath, audioPath = 'examples/audio/diarization-sample-16k.wav'] = process.argv.slice(2);
14
+ if (!modelPath || modelPath === '--help') {
15
+ console.error('Usage: npx tsx examples/asr/nemotron-diarization-filesystem.ts <nemotron-diarization.gguf> [audio.wav]');
16
+ process.exit(modelPath === '--help' ? 0 : 1);
17
+ }
18
+ let modelId;
19
+ try {
20
+ await access(modelPath, constants.R_OK);
21
+ await access(audioPath, constants.R_OK);
22
+ console.error('▸ Loading Nemotron 3 Diarization through the Parakeet engine...');
23
+ modelId = await loadModel({
24
+ modelSrc: modelPath,
25
+ modelType: 'parakeet-transcription',
26
+ modelConfig: {
27
+ maxThreads: 4,
28
+ useGPU: false
29
+ // Optional: diarizationThreshold and diarizationMinSegmentMs.
30
+ // Omit them to use the loaded model's defaults.
31
+ }
32
+ });
33
+ console.error(`▸ Diarizing ${audioPath}...`);
34
+ const segments = await transcribe({ modelId, audioChunk: audioPath, metadata: true });
35
+ const turns = segments.flatMap((segment) => segment.speakerSegments ?? []);
36
+ for (const turn of turns) {
37
+ console.log(`[${(turn.startMs / 1000).toFixed(2)}s → ${(turn.endMs / 1000).toFixed(2)}s] Speaker ${turn.speakerId + 1}`);
38
+ }
39
+ if (turns.length === 0)
40
+ console.error('▸ No speaker turns returned.');
41
+ }
42
+ catch (error) {
43
+ console.error('✖ Nemotron diarization failed:', error);
44
+ process.exitCode = 1;
45
+ }
46
+ finally {
47
+ try {
48
+ if (modelId !== undefined)
49
+ await unloadModel({ modelId });
50
+ }
51
+ catch (error) {
52
+ console.error('✖ Could not unload the diarization model:', error);
53
+ process.exitCode = 1;
54
+ }
55
+ finally {
56
+ try {
57
+ await close();
58
+ }
59
+ catch (error) {
60
+ console.error('✖ Could not close the SDK:', error);
61
+ process.exitCode = 1;
62
+ }
63
+ }
64
+ }
@@ -2,7 +2,7 @@
2
2
  * Parakeet CTC transcription from a WAV file.
3
3
  *
4
4
  * Usage:
5
- * bun run examples/asr/parakeet-ctc-filesystem.ts <wav-file> [parakeet-ctc-gguf]
5
+ * npx tsx examples/asr/parakeet-ctc-filesystem.ts <wav-file> [parakeet-ctc-gguf]
6
6
  *
7
7
  * Loads a single GGUF checkpoint (`PARAKEET_CTC_0_6B_Q8_0` by default) and
8
8
  * transcribes the file with the batch `transcribe` API. Omit the model
@@ -13,7 +13,7 @@
13
13
  import { loadModel, unloadModel, transcribe, PARAKEET_CTC_0_6B_Q8_0 } from '@qvac/sdk';
14
14
  const args = process.argv.slice(2);
15
15
  if (!args[0]) {
16
- console.error('Usage: bun run examples/asr/parakeet-ctc-filesystem.ts <wav-file> ' + '[parakeet-ctc-gguf]');
16
+ console.error('Usage: npx tsx examples/asr/parakeet-ctc-filesystem.ts <wav-file> ' + '[parakeet-ctc-gguf]');
17
17
  console.error('\nIf the model path is omitted, defaults to the registry model.');
18
18
  process.exit(1);
19
19
  }
@@ -2,7 +2,7 @@
2
2
  * Indic Conformer CTC transcription from a WAV file.
3
3
  *
4
4
  * Usage:
5
- * bun run examples/asr/parakeet-indic-conformer-filesystem.ts <wav-file> <language> [gguf]
5
+ * npx tsx examples/asr/parakeet-indic-conformer-filesystem.ts <wav-file> <language> [gguf]
6
6
  *
7
7
  * Loads a single GGUF checkpoint (`PARAKEET_INDIC_CONFORMER_600M_Q8_0` by
8
8
  * default) and transcribes with the batch `transcribe` API. `language` is
@@ -14,7 +14,7 @@
14
14
  import { loadModel, unloadModel, transcribe, PARAKEET_INDIC_CONFORMER_600M_Q8_0 } from '@qvac/sdk';
15
15
  const args = process.argv.slice(2);
16
16
  if (!args[0] || !args[1]) {
17
- console.error('Usage: bun run examples/asr/parakeet-indic-conformer-filesystem.ts ' +
17
+ console.error('Usage: npx tsx examples/asr/parakeet-indic-conformer-filesystem.ts ' +
18
18
  '<wav-file> <language> [indic-conformer-gguf]');
19
19
  console.error('\nExample: ... filesystem.ts speech.wav hi');
20
20
  console.error('If the model path is omitted, defaults to the registry model.');
@@ -2,7 +2,7 @@
2
2
  * Microphone → Parakeet batch transcription (chunked `transcribe`).
3
3
  *
4
4
  * Usage:
5
- * bun run examples/asr/parakeet-microphone-record.ts
5
+ * npx tsx examples/asr/parakeet-microphone-record.ts
6
6
  *
7
7
  * Captures 3 s s16le chunks from the microphone and sends each to `transcribe`
8
8
  * with the TDT model. Press Ctrl+C to stop.
@@ -2,7 +2,7 @@
2
2
  * Microphone → Parakeet duplex streaming (`transcribeStream`).
3
3
  *
4
4
  * Usage:
5
- * bun run examples/asr/parakeet-microphone-stream.ts
5
+ * npx tsx examples/asr/parakeet-microphone-stream.ts
6
6
  *
7
7
  * Streams microphone audio through `transcribeStream` with
8
8
  * `parakeetStreamingConfig`. Uses the EOU checkpoint so you may see
@@ -2,9 +2,9 @@
2
2
  * Parakeet Nemotron transcription from an audio file.
3
3
  *
4
4
  * Usage:
5
- * bun run examples/asr/parakeet-nemotron-filesystem.ts \
5
+ * npx tsx examples/asr/parakeet-nemotron-filesystem.ts \
6
6
  * <audio-file> [locale] [nemotron-gguf] [--streaming]
7
- * bun run examples/asr/parakeet-nemotron-filesystem.ts \
7
+ * npx tsx examples/asr/parakeet-nemotron-filesystem.ts \
8
8
  * <audio-file> [nemotron-gguf] [--streaming]
9
9
  *
10
10
  * Uses `PARAKEET_NEMOTRON_0_6B_Q4_0` when the model is omitted and `auto` when
@@ -22,7 +22,7 @@ const DEFAULT_LOCALE = 'auto';
22
22
  const FFMPEG_PROTOCOLS = 'file,pipe';
23
23
  const STREAMING_FLAG = '--streaming';
24
24
  const EARLY_OUTPUT_END_MESSAGE = 'The transcription stream ended before the decoder input completed';
25
- const USAGE = 'Usage: bun run examples/asr/parakeet-nemotron-filesystem.ts ' +
25
+ const USAGE = 'Usage: npx tsx examples/asr/parakeet-nemotron-filesystem.ts ' +
26
26
  '<audio-file> [locale] [nemotron-gguf] [--streaming]';
27
27
  function parseArguments(args) {
28
28
  const streaming = args.includes(STREAMING_FLAG);
@@ -2,7 +2,7 @@
2
2
  * Sortformer v2.1 streaming diarization via duplex `transcribeStream` + AOSC.
3
3
  *
4
4
  * Usage:
5
- * bun run examples/asr/parakeet-sortformer-streaming.ts <wav-file> [sortformer-gguf]
5
+ * npx tsx examples/asr/parakeet-sortformer-streaming.ts <wav-file> [sortformer-gguf]
6
6
  *
7
7
  * Streams 16 kHz mono s16le audio in real-time-paced chunks (required for parakeet
8
8
  * duplex streaming). Loads v2.1 with AOSC knobs in `modelConfig`. Omit the model
@@ -28,7 +28,7 @@ const SORTFORMER_V21_AOSC_LOAD_CONFIG = {
28
28
  };
29
29
  const args = process.argv.slice(2);
30
30
  if (!args[0]) {
31
- console.error('Usage: bun run examples/asr/parakeet-sortformer-streaming.ts <wav-file-path> [sortformer-gguf]');
31
+ console.error('Usage: npx tsx examples/asr/parakeet-sortformer-streaming.ts <wav-file-path> [sortformer-gguf]');
32
32
  console.error('\nDefaults to the v2.1 q8_0 registry model (PARAKEET_SORTFORMER_4SPK_V2_1_Q8_0).');
33
33
  process.exit(1);
34
34
  }
@@ -2,7 +2,7 @@
2
2
  * Parakeet Sortformer diarization + TDT transcription pipeline.
3
3
  *
4
4
  * Usage:
5
- * bun run examples/asr/parakeet-sortformer.ts [sortformer-gguf] [wav-file]
5
+ * npx tsx examples/asr/parakeet-sortformer.ts [sortformer-gguf] [wav-file]
6
6
  *
7
7
  * Two-step flow: Sortformer v2.1 diarizes the audio, then TDT transcribes each
8
8
  * speaker segment. Defaults to registry GGUFs and
@@ -2,7 +2,7 @@
2
2
  * Parakeet TDT transcription for long audio files.
3
3
  *
4
4
  * Usage:
5
- * bun run examples/asr/parakeet-tdt-filesystem-chunked.ts <audio-file> [parakeet-tdt-gguf]
5
+ * npx tsx examples/asr/parakeet-tdt-filesystem-chunked.ts <audio-file> [parakeet-tdt-gguf]
6
6
  *
7
7
  * FFmpeg first detects silence, then this example selects boundaries near
8
8
  * 45 seconds and transcribes one segment at a time. Segments never exceed
@@ -143,7 +143,7 @@ function formatTimestamp(seconds) {
143
143
  }
144
144
  const args = process.argv.slice(2);
145
145
  if (!args[0]) {
146
- console.error('Usage: bun run examples/asr/parakeet-tdt-filesystem-chunked.ts ' +
146
+ console.error('Usage: npx tsx examples/asr/parakeet-tdt-filesystem-chunked.ts ' +
147
147
  '<audio-file> [parakeet-tdt-gguf]');
148
148
  process.exit(1);
149
149
  }
@@ -2,7 +2,7 @@
2
2
  * Parakeet TDT transcription from a WAV file.
3
3
  *
4
4
  * Usage:
5
- * bun run examples/asr/parakeet-tdt-filesystem.ts <wav-file> [parakeet-tdt-gguf]
5
+ * npx tsx examples/asr/parakeet-tdt-filesystem.ts <wav-file> [parakeet-tdt-gguf]
6
6
  *
7
7
  * Loads a single GGUF checkpoint (`PARAKEET_TDT_0_6B_V3_Q8_0` by default) and
8
8
  * transcribes the file with the batch `transcribe` API. Omit the model
@@ -13,7 +13,7 @@
13
13
  import { loadModel, unloadModel, transcribe, PARAKEET_TDT_0_6B_V3_Q8_0 } from '@qvac/sdk';
14
14
  const args = process.argv.slice(2);
15
15
  if (!args[0]) {
16
- console.error('Usage: bun run examples/asr/parakeet-tdt-filesystem.ts <wav-file-path> ' +
16
+ console.error('Usage: npx tsx examples/asr/parakeet-tdt-filesystem.ts <wav-file-path> ' +
17
17
  '[parakeet-tdt-gguf]');
18
18
  console.error('\nIf the model path is omitted, defaults to the registry model.');
19
19
  process.exit(1);
@@ -2,7 +2,7 @@
2
2
  * Transcribe a WAV file with Parakeet Unified and its Core ML encoder sidecar.
3
3
  *
4
4
  * From packages/sdk:
5
- * bun run examples/asr/parakeet-unified-coreml.ts \
5
+ * npx tsx examples/asr/parakeet-unified-coreml.ts \
6
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
@@ -77,7 +77,7 @@ async function stageModel(path) {
77
77
  }
78
78
  async function main() {
79
79
  if (!modelPath) {
80
- throw new Error('Usage: bun run examples/asr/parakeet-unified-coreml.ts ' +
80
+ throw new Error('Usage: npx tsx examples/asr/parakeet-unified-coreml.ts ' +
81
81
  '<regenerated-unified-gguf> [16-kHz-wav-file]');
82
82
  }
83
83
  let staged;
@@ -2,7 +2,7 @@
2
2
  * Parakeet Unified transcription from a WAV file.
3
3
  *
4
4
  * Usage:
5
- * bun run examples/asr/parakeet-unified-filesystem.ts <wav-file> [parakeet-unified-gguf]
5
+ * npx tsx examples/asr/parakeet-unified-filesystem.ts <wav-file> [parakeet-unified-gguf]
6
6
  *
7
7
  * Loads a single GGUF checkpoint (`PARAKEET_UNIFIED_0_6B_Q8_0` by default) and
8
8
  * transcribes the file with the batch `transcribe` API. The Unified RNN-T
@@ -15,7 +15,7 @@
15
15
  import { loadModel, unloadModel, transcribe, PARAKEET_UNIFIED_0_6B_Q8_0 } from '@qvac/sdk';
16
16
  const args = process.argv.slice(2);
17
17
  if (!args[0]) {
18
- console.error('Usage: bun run examples/asr/parakeet-unified-filesystem.ts <wav-file-path> ' +
18
+ console.error('Usage: npx tsx examples/asr/parakeet-unified-filesystem.ts <wav-file-path> ' +
19
19
  '[parakeet-unified-gguf]');
20
20
  console.error('\nIf the model path is omitted, defaults to the registry model.');
21
21
  process.exit(1);
@@ -2,7 +2,7 @@
2
2
  * Test script: pipes a WAV file through transcribeStream to verify
3
3
  * the bidirectional streaming + addon processing works end-to-end.
4
4
  *
5
- * Usage: bun run examples/asr/whispercpp-filesystem-streaming.ts
5
+ * Usage: npx tsx examples/asr/whispercpp-filesystem-streaming.ts
6
6
  *
7
7
  * Uses FFmpeg to convert the WAV to raw f32le and streams chunks
8
8
  * through the duplex RPC session to the whisper addon.
@@ -2,7 +2,7 @@ import { loadModel, unloadModel, transcribe, WHISPER_TINY } from '@qvac/sdk';
2
2
  // Parse command line arguments
3
3
  const args = process.argv.slice(2);
4
4
  if (!args[0]) {
5
- console.error('Usage: bun run examples/asr/whispercpp-filesystem.ts <wav-file-path>');
5
+ console.error('Usage: npx tsx examples/asr/whispercpp-filesystem.ts <wav-file-path>');
6
6
  process.exit(1);
7
7
  }
8
8
  const audioFilePath = args[0];