@qvac/sdk 0.21.0 → 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 +35 -1
  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
package/NOTICE CHANGED
@@ -135,6 +135,18 @@ Third-Party Model Licenses
135
135
  https://huggingface.co/jmb95/laser-dolphin-mixtral-2x7b-dpo-GGUF
136
136
  latin_g2
137
137
  https://www.jaided.ai/easyocr/modelhub/
138
+ laya-f16
139
+ https://huggingface.co/convaiinnovations/laya
140
+ laya-multilingual-f16
141
+ https://huggingface.co/convaiinnovations/laya-multilingual
142
+ laya-multilingual-Q8_0
143
+ https://huggingface.co/convaiinnovations/laya-multilingual
144
+ laya-Q8_0
145
+ https://huggingface.co/convaiinnovations/laya
146
+ laya-typed-decisions-f16
147
+ https://huggingface.co/convaiinnovations/laya-typed-decisions
148
+ laya-typed-decisions-Q8_0
149
+ https://huggingface.co/convaiinnovations/laya-typed-decisions
138
150
  LightOnOCR-2-1B-ocr-soup-GGUF
139
151
  https://huggingface.co/noctrex/LightOnOCR-2-1B-ocr-soup-GGUF
140
152
  Llama_3.2_1B_Intruct_Tool_Calling_V2-GGUF
@@ -153,8 +165,20 @@ Third-Party Model Licenses
153
165
  https://huggingface.co/OpenMOSS-Team/MOSS-TTS
154
166
  moss-codec-encoder-f16
155
167
  https://huggingface.co/OpenMOSS-Team/MOSS-TTS
168
+ moss-sfx-v2-f16
169
+ https://huggingface.co/OpenMOSS-Team/MOSS-SoundEffect-v2.0
170
+ moss-speech-bf16
171
+ https://huggingface.co/OpenMOSS-Team/MOSS-Speech
172
+ moss-speech-codec-f16
173
+ https://huggingface.co/OpenMOSS-Team/MOSS-Speech-Codec
174
+ moss-speech-q8_0
175
+ https://huggingface.co/OpenMOSS-Team/MOSS-Speech
176
+ moss-transcribe-diarize-f16
177
+ https://huggingface.co/OpenMOSS-Team/MOSS-Transcribe-Diarize
156
178
  moss-tts-delay-f16
157
179
  https://huggingface.co/OpenMOSS-Team/MOSS-TTS
180
+ moss-ttsd-f16
181
+ https://huggingface.co/OpenMOSS-Team/MOSS-TTSD-v1.0
158
182
  nb-tiny-ggml-model
159
183
  https://huggingface.co/NbAiLab/nb-whisper-tiny
160
184
  parler-indic-f16
@@ -707,6 +731,11 @@ Third-Party Model Licenses
707
731
  weight
708
732
  https://huggingface.co/nvidia/parakeet-unified-en-0.6b
709
733
 
734
+ --- openmdw-1.1 ---
735
+
736
+ Nemotron-3-Diarization.q8_0
737
+ https://huggingface.co/nvidia/Nemotron-3-Diarization
738
+
710
739
  --- openrail ---
711
740
 
712
741
  supertonic
@@ -748,7 +777,8 @@ the underlying models.
748
777
 
749
778
  Source URLs for original weights are recorded in each model's
750
779
  metadata entry within the registry.
751
- =========================================================================
780
+
781
+ ====
752
782
  JavaScript Dependencies
753
783
  =========================================================================
754
784
 
@@ -863,6 +893,10 @@ JavaScript Dependencies
863
893
  https://github.com/holepunchto/bare-inspect
864
894
  bare-inspector@6.1.0
865
895
  https://github.com/holepunchto/bare-inspector
896
+ bare-lief@0.2.10
897
+ https://github.com/holepunchto/bare-lief
898
+ bare-link@4.0.1
899
+ https://github.com/holepunchto/bare-link
866
900
  bare-mime@1.0.0
867
901
  https://github.com/holepunchto/bare-mime
868
902
  bare-module@6.4.0
package/README.md CHANGED
@@ -20,6 +20,8 @@ For AI/LLM tools, use [https://docs.qvac.tether.io/llms-full.txt](https://docs.q
20
20
 
21
21
  ## Supported environments and installation
22
22
 
23
+ For mobile apps that use only raw PCM streaming transcription, list the required audio plugins and set `"includeAudioDecoder": false` in `qvac.config.*` before bundling or running Expo prebuild. You can also use `qvac bundle sdk --defer bare-ffmpeg`. Both options leave `bare-ffmpeg` out of the native addon manifest. Bundle FFmpeg when the app decodes compressed audio files or asks `audiogen-ggml` for a compressed output format; PCM and WAV output need no FFmpeg.
24
+
23
25
  See https://docs.qvac.tether.io/sdk/getting-started/installation
24
26
 
25
27
  On Node.js, the SDK installs and launches its own Bare worker through `bare-runtime`.
@@ -29,6 +31,53 @@ package manager can replace an older, incompatible runtime. Remove any override
29
31
  or resolution that forces the worker below that requirement; installing a newer
30
32
  global `bare` executable does not change the SDK's worker dependency.
31
33
 
34
+ ## TTS 0.11 engines and memory fit
35
+
36
+ `@qvac/tts-ggml` 0.11 adds two desktop batch engines to `textToSpeech`.
37
+ Load MOSS-SoundEffect with `modelType: 'tts-ggml'` and
38
+ `modelConfig: { ttsEngine: 'moss-sfx' }`; the primary source is its single
39
+ GGUF. With an `AUDIOGEN_MOSS_SFX_V2_*` constant, pass its `.src` URL as
40
+ `modelSrc`, because the full descriptor selects the audiogen plugin. This also applies to fit assessment: use explicit `modelType` and `ttsEngine`, and a downloaded local file for metadata-only TTS fit. The bare `.src` URL lacks checksum/registry coordinates for a weightless stub; the audiogen descriptor/resource profile does not identify the TTS engine. Use
41
+ a text description, with optional `seconds`
42
+ (up to 30), `negativePrompt`, `steps`, `guidance` and `shift`. These controls
43
+ can also be load defaults. The output is 48 kHz.
44
+
45
+ Load MOSS-Speech with `modelConfig: { ttsEngine: 'moss-speech',
46
+ mossSpeechCodecModelSrc: <codec source> }` and the language-model GGUF as
47
+ `modelSrc`. Use either `text`, or `audio` plus
48
+ `sampleRate`. Audio is a JSON array of normalized mono samples in [-1, 1].
49
+ Earlier turns go in `messages`; each turn has a `role` and either `text` or
50
+ `audio` plus `sampleRate`. Per-call controls include `systemPrompt`,
51
+ `replyVoice` plus `replyVoiceSampleRate`, `maxReplySeconds`, `maxNewTokens`,
52
+ `textReply`, `greedy`, `temperature`, `topP` and `topK`. Consume `bufferStream` in the default streaming mode, or await `buffer` with
53
+ `stream: false`, then await `result.text` for any reply text.
54
+ Spoken mode can return an audio-only reply; use `textReply: true` when text is required.
55
+ Spoken replies are 24 kHz; `textReply: true` returns text with an empty audio
56
+ buffer. Omitting `maxNewTokens` preserves the addon's remaining-context budget.
57
+ Both engines run one native batch job. The default `stream: true` emits the completed audio as one chunk; `stream: false` collects it in `buffer`. Neither supports sentence streaming or duplex text input.
58
+
59
+ Standalone examples: [basic sound effects](examples/tts/moss-sound-effect.ts),
60
+ [sound-effect controls](examples/tts/moss-sound-effect-controls.ts),
61
+ [typed question to text reply](examples/tts/moss-speech.ts), and
62
+ [spoken question to spoken reply](examples/tts/moss-speech-audio.ts).
63
+ Run them from this package with `node --import tsx examples/tts/<file>.ts`;
64
+ the spoken-question example also takes a WAV file path. Each example downloads
65
+ its model, returns text or writes a WAV reply, unloads the model, and closes the SDK worker.
66
+
67
+ `assessModelFit` supports metadata-only MOSS-TTS/TTSD and MOSS-SoundEffect
68
+ projections. Add `ttsWorkload` beside `modelConfig` on the assessment candidate:
69
+ `{ promptRows, referenceSamples, streaming }` for MOSS, or
70
+ `{ prompt, seconds }` for sound effects. MOSS needs its backbone and codec
71
+ decoder; reference encoding also needs the codec encoder. Prompt rows must
72
+ cover the complete native prompt, including dialogue and reference rows.
73
+ Missing workloads return an unknown assessment rather than guessing.
74
+ MOSS-Speech has no native fitter in this release and remains unknown. Workloads are fit-only; loading a MOSS model does not accept them and its automatic fit preflight remains unknown.
75
+
76
+ The CLI configuration picker includes both engines. Their conversation and
77
+ sound-effect request controls are library-only because the OpenAI speech
78
+ endpoint cannot represent those requests. Native performance and backend fixes
79
+ in the addon release are inherited without additional SDK controls.
80
+
32
81
  ## Quickstart
33
82
 
34
83
  1. Create the examples workspace:
@@ -82,6 +131,12 @@ try {
82
131
  node quickstart.js
83
132
  ```
84
133
 
134
+ A first `loadModel()` call also starts the SDK's worker. If that startup ever
135
+ exceeds its budget (cold disk cache, antivirus scanning the native addon), the
136
+ call fails with `RPC_INIT_TIMEOUT`. Re-running usually succeeds; to give every
137
+ start more room, raise `rpcInitTimeoutMs` in `qvac.config.*` or set the
138
+ `QVAC_RPC_INIT_TIMEOUT_MS` environment variable.
139
+
85
140
  ## System resource diagnostics
86
141
 
87
142
  Use `getSystemResources` to inspect locally observed CPU, system-memory, GPU, and
@@ -171,9 +226,12 @@ The result is advisory: it does not block `loadModel`, reserve memory, or make a
171
226
  performance claim. `unknown` is a real answer meaning the evidence does not
172
227
  support a call either way — show it as "can't say", not as "no".
173
228
 
229
+ The assessment holds back a reserve of its own, beyond the headroom the engine's
230
+ fitter leaves, so a model the engine calls a fit can still come back
231
+ `likely-too-large` on a host with little room.
232
+
174
233
  See [pre-download model fit assessment](./docs/assess-model-fit.md) for the
175
- budget arithmetic, why estimates are ranges, the supported engine and workload
176
- matrix, and the current calibration status.
234
+ budget arithmetic, the reserve, and the supported engine and workload matrix.
177
235
 
178
236
  ## Streaming transcription statistics
179
237
 
@@ -226,17 +284,14 @@ for a local check of a Unified GGUF and its encoder bundle.
226
284
  In the `./examples` subdirectory, you will find scripts demonstrating how to use all SDK functionalities. To try any of them:
227
285
 
228
286
  1. Build the SDK from source (see [Build](#build) section).
229
- 2. Run using Bare, Node.js, or Bun as the runtime:
287
+ 2. Run with Node.js:
230
288
 
231
289
  ```bash
232
- # With Bare
233
- bun run bare:example dist/examples/path/to/example.js
234
-
235
- # With Node
290
+ # Compiled output
236
291
  node dist/examples/path/to/example.js
237
292
 
238
- # With bun, straight from source
239
- bun run examples/path/to/example.ts
293
+ # Straight from source, with the tsx dev dependency
294
+ npx tsx examples/path/to/example.ts
240
295
  ```
241
296
 
242
297
  `examples/abot-world.ts` has a companion guide covering the hardware
@@ -246,40 +301,38 @@ of an interactive world session: see
246
301
 
247
302
  ## Build
248
303
 
249
- Use the [Bun](https://bun.sh/) package manager:
304
+ Node.js 22 and npm are the only tools needed. No lockfile is committed; `package-lock.json` is gitignored.
250
305
 
251
- ```bash
252
- bun i
253
- ```
254
-
255
- `@qvac/inference` resolves to its published release by default. To build and test against the in-repo engine at the same commit, link it first:
306
+ Build and test against the in-repo engine at the same commit (this is what CI does):
256
307
 
257
308
  ```bash
258
- bun run sdk-source:workspace
309
+ npm run sdk-source:workspace
259
310
  ```
260
311
 
312
+ This installs and builds `../inference`, points `@qvac/inference` at it, and installs the SDK's dependencies. A plain `npm install` resolves `@qvac/inference` to its published release instead, which fails with `ERESOLVE` whenever the SDK on `main` already depends on addon versions the published engine has not been released against.
313
+
261
314
  ```bash
262
- bun run build # or `watch` for hotreload
315
+ npm run build # or `watch` for hotreload
263
316
  ```
264
317
 
265
318
  ```bash
266
- bun run build:pack
319
+ npm run build:pack
267
320
  ```
268
321
 
269
- This outputs a tarball under `dist/sdk-{version}.tgz` that you can install in your project, e.g.:
322
+ This outputs a tarball under `dist/qvac-sdk-{version}.tgz` that you can install in your project, e.g.:
270
323
 
271
324
  ```bash
272
- npm i path/to/sdk-0.3.0.tgz
325
+ npm i path/to/qvac-sdk-0.21.0.tgz
273
326
  ```
274
327
 
275
328
  ## Testing
276
329
 
277
330
  The SDK test suite is organized into two buckets by runtime:
278
331
 
279
- | Bucket | Runtime | Location | Command |
280
- | ----------------- | ---------- | -------- | -------------------------------------- |
281
- | Unit | Bun / Node | `test/` | `bun run test:unit` |
282
- | Client (consumer) | Node / RN | `e2e/` | See [`e2e/README.md`](./e2e/README.md) |
332
+ | Bucket | Runtime | Location | Command |
333
+ | ----------------- | --------- | -------- | -------------------------------------- |
334
+ | Unit | Node | `test/` | `npm run test:unit` |
335
+ | Client (consumer) | Node / RN | `e2e/` | See [`e2e/README.md`](./e2e/README.md) |
283
336
 
284
337
  See [`TESTING.md`](./TESTING.md) for the full decision tree on where new tests should land.
285
338
 
@@ -422,3 +475,93 @@ This will:
422
475
  4. Generate `changelog/<version>/CHANGELOG.md`
423
476
  5. Generate `changelog/<version>/breaking.md` for BC changes (with code examples)
424
477
  6. Generate `changelog/<version>/api.md` for API changes (with code examples)
478
+
479
+ ## Speaker-aware transcription
480
+
481
+ ASR 0.8 adds `MODEL_TYPES.mossTranscribe` and the
482
+ `@qvac/sdk/moss-transcribe/plugin` entry point. MOSS processes a whole recording;
483
+ use `transcribe`, since it has no duplex streaming or configuration reload.
484
+
485
+ ```ts
486
+ import { loadModel, transcribe, MOSS_TRANSCRIBE_DIARIZE_Q8_0 } from '@qvac/sdk'
487
+
488
+ const modelId = await loadModel({
489
+ modelSrc: MOSS_TRANSCRIBE_DIARIZE_Q8_0,
490
+ modelConfig: { useGPU: true, maxThreads: 4 }
491
+ })
492
+ const segments = await transcribe({
493
+ modelId,
494
+ audioChunk: '/recordings/meeting.wav',
495
+ metadata: true,
496
+ hotwords: ['QVAC'],
497
+ maxNewTokens: 2048
498
+ })
499
+ ```
500
+
501
+ For a runnable example with download progress and resource cleanup, see
502
+ [the MOSS file transcription example](examples/asr/moss-transcribe-filesystem.ts).
503
+ From `packages/sdk`, run:
504
+
505
+ ```bash
506
+ npx tsx examples/asr/moss-transcribe-filesystem.ts examples/audio/diarization-sample-16k.wav
507
+ # Use local weights and per-request hotwords:
508
+ npx tsx examples/asr/moss-transcribe-filesystem.ts meeting.wav ./moss.gguf QVAC OpenMOSS
509
+ ```
510
+
511
+ Segments retain `speaker` labels such as `S01`, zero-based `speakerId`, and
512
+ `startMs`/`endMs`. Hotwords apply to each request: at most 64 nonempty terms of
513
+ 64 UTF-8 bytes each. A MOSS `prompt` replaces the default instruction and cannot
514
+ be combined with hotwords. `maxNewTokens: 0` uses the model default. These two
515
+ MOSS-specific options are rejected for Whisper and Parakeet models.
516
+
517
+ The published addon contains Whisper v1.9.4, so existing Whisper calls keep
518
+ their API and use the updated backend. MOSS memory-fit assessment projects the
519
+ declared recording and decoding options without loading weights:
520
+
521
+ ```typescript
522
+ const fit = await assessModelFit({
523
+ models: [
524
+ {
525
+ modelSrc: MOSS_TRANSCRIBE_DIARIZE_Q8_0,
526
+ modelConfig: { useGPU: false },
527
+ transcriptionWorkload: { audioSeconds: 300, hotwords: ['Erin'], maxNewTokens: 0 }
528
+ }
529
+ ]
530
+ })
531
+ ```
532
+
533
+ Import `assessModelFit` from `@qvac/sdk`. Use the longest recording you intend
534
+ to transcribe, with the same prompt/hotwords and token limit as the request.
535
+ Without `transcriptionWorkload`, MOSS has no native fit evidence, its recording
536
+ window is omitted, and the result can remain `unknown`. Assessment uses a registry description when available,
537
+ or a local model path; it downloads no full weights. MOSS CoreML requires an
538
+ addon revision newer than the published 0.8.0 release.
539
+
540
+ The SDK and inference use the published `@qvac/asr-ggml` package at `^0.8.0`.
541
+
542
+ ## Nemotron 3 Diarization
543
+
544
+ Load a local Nemotron 3 Diarization GGUF with `modelType: 'parakeet-transcription'`.
545
+ The addon detects the variant from the GGUF and supports up to eight speakers,
546
+ including overlapping activity. This model reports speaker turns rather than words.
547
+
548
+ Use `transcribe({ modelId, audioChunk, metadata: true })` for offline diarization.
549
+ Each result can include `speakerSegments` with zero-based `speakerId`, `startMs`,
550
+ and `endMs`. Load with `modelConfig.streaming: true` before using `transcribeStream`.
551
+ Streaming metadata carries `speakerId` on each diarization segment.
552
+ For streaming speaker-activity events, enable `streamingSpeakerVad` at load or
553
+ `emitSpeakerVad` under `parakeetStreamingConfig` per `transcribeStream` call;
554
+ conversation VAD events retain their dominant `speakerId`.
555
+
556
+ `diarizationThreshold` (0–1) and `diarizationMinSegmentMs` (nonnegative integer)
557
+ are supported in `modelConfig` and per-call `parakeetStreamingConfig`. Omit them
558
+ to preserve model defaults. Nemotron defaults to a 0.5 threshold and 200 ms minimum
559
+ turn; its default left context is 0 ms, while an explicitly configured 80 ms is
560
+ preserved. CLI `verbose_json` exposes offline turns as `speaker_segments` with
561
+ `speaker_id` and start/end timestamps in seconds.
562
+
563
+ See [the local Nemotron diarization example](examples/asr/nemotron-diarization-filesystem.ts):
564
+
565
+ ```bash
566
+ npx tsx examples/asr/nemotron-diarization-filesystem.ts ./nemotron-diarization.gguf meeting.wav
567
+ ```
@@ -17,7 +17,7 @@ const width = Number(process.argv[6] || 832);
17
17
  const height = Number(process.argv[7] || 480);
18
18
  if (!firstFramePath) {
19
19
  console.error('✖ first frame image path is required');
20
- console.error('Usage: bun run bare:example dist/examples/abot-world.js ' +
20
+ console.error('Usage: node dist/examples/abot-world.js ' +
21
21
  '<firstFrameImage> [prompt] [outputDir] [blocks] [width] [height]');
22
22
  process.exit(1);
23
23
  }
@@ -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