@qvac/sdk 0.22.0 → 0.23.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 (150) hide show
  1. package/NOTICE +123 -83
  2. package/README.md +22 -460
  3. package/dist/examples/asr/parakeet-transcribepsy-filesystem.d.ts +2 -0
  4. package/dist/examples/asr/parakeet-transcribepsy-filesystem.js +76 -0
  5. package/dist/examples/diffusion-img2vid-ltx.js +7 -14
  6. package/dist/examples/diffusion-qwen-image-21.d.ts +2 -0
  7. package/dist/examples/diffusion-qwen-image-21.js +104 -0
  8. package/dist/examples/diffusion-txt2vid-ltx.js +7 -14
  9. package/dist/examples/finetune/llamacpp-finetune.js +9 -4
  10. package/dist/examples/llamacpp-multimodal.js +3 -1
  11. package/dist/examples/mcp-websearch.js +1 -1
  12. package/dist/examples/plugins.js +1 -1
  13. package/dist/examples/rerank.d.ts +2 -0
  14. package/dist/examples/rerank.js +33 -0
  15. package/dist/examples/tools/llamacpp-deferred-tools.js +5 -5
  16. package/dist/examples/tools/llamacpp-tools-auto-dialect.js +4 -3
  17. package/dist/examples/tools/llamacpp-tools-gemma4.js +3 -3
  18. package/dist/examples/tools/llamacpp-tools-qwen35.js +4 -3
  19. package/dist/scripts/contract/build-contract.d.ts +1 -1
  20. package/dist/scripts/contract/constants-registry.d.ts +2 -0
  21. package/dist/scripts/contract/constants-registry.js +2 -1
  22. package/dist/scripts/contract/method-shapes.d.ts +1 -0
  23. package/dist/scripts/contract/method-shapes.js +1 -0
  24. package/dist/src/client/api/assess-model-fit.js +1 -1
  25. package/dist/src/client/api/audio-edit.js +2 -2
  26. package/dist/src/client/api/audio-gen-result.js +2 -2
  27. package/dist/src/client/api/audio-gen.js +2 -2
  28. package/dist/src/client/api/audio-understand.js +2 -2
  29. package/dist/src/client/api/batch-completion.js +2 -2
  30. package/dist/src/client/api/bci-transcribe.js +3 -3
  31. package/dist/src/client/api/cancel.js +1 -1
  32. package/dist/src/client/api/classify.js +1 -1
  33. package/dist/src/client/api/completion-stream.d.ts +2 -1
  34. package/dist/src/client/api/completion-stream.js +5 -3
  35. package/dist/src/client/api/decide.d.ts +1 -1
  36. package/dist/src/client/api/decide.js +3 -3
  37. package/dist/src/client/api/delete-cache.js +1 -1
  38. package/dist/src/client/api/diffusion.d.ts +18 -1
  39. package/dist/src/client/api/diffusion.js +19 -2
  40. package/dist/src/client/api/download-asset.js +3 -3
  41. package/dist/src/client/api/embed.js +2 -2
  42. package/dist/src/client/api/finetune.js +3 -3
  43. package/dist/src/client/api/get-loaded-model-info.js +1 -1
  44. package/dist/src/client/api/get-model-info.js +1 -1
  45. package/dist/src/client/api/get-system-resources.js +1 -1
  46. package/dist/src/client/api/heartbeat.js +1 -1
  47. package/dist/src/client/api/index.d.ts +4 -3
  48. package/dist/src/client/api/index.js +4 -3
  49. package/dist/src/client/api/invoke-plugin.js +1 -1
  50. package/dist/src/client/api/load-model.js +4 -4
  51. package/dist/src/client/api/logging-stream.d.ts +11 -2
  52. package/dist/src/client/api/logging-stream.js +12 -3
  53. package/dist/src/client/api/ocr.js +1 -1
  54. package/dist/src/client/api/rag.js +2 -2
  55. package/dist/src/client/api/registry.d.ts +2 -1
  56. package/dist/src/client/api/registry.js +6 -5
  57. package/dist/src/client/api/rerank.d.ts +22 -0
  58. package/dist/src/client/api/rerank.js +39 -0
  59. package/dist/src/client/api/resume.js +1 -1
  60. package/dist/src/client/api/rpc-server.js +2 -2
  61. package/dist/src/client/api/state.js +1 -1
  62. package/dist/src/client/api/subscribe-logs.js +3 -2
  63. package/dist/src/client/api/suspend.js +1 -1
  64. package/dist/src/client/api/text-to-speech.js +3 -3
  65. package/dist/src/client/api/transcribe.d.ts +1 -1
  66. package/dist/src/client/api/transcribe.js +2 -2
  67. package/dist/src/client/api/translate.js +2 -2
  68. package/dist/src/client/api/unload-model.js +2 -2
  69. package/dist/src/client/api/upscale.js +1 -1
  70. package/dist/src/client/api/vector-index.d.ts +1 -1
  71. package/dist/src/client/api/vector-index.js +1 -1
  72. package/dist/src/client/api/video.js +3 -3
  73. package/dist/src/client/api/world-result.js +2 -2
  74. package/dist/src/client/api/world.d.ts +1 -1
  75. package/dist/src/client/api/world.js +2 -2
  76. package/dist/src/client/logging-stream-registry.js +9 -6
  77. package/dist/src/client/plugins-factory.d.ts +1 -1
  78. package/dist/src/client/plugins-factory.js +1 -1
  79. package/dist/src/client/rpc/expo-rpc-client.js +3 -3
  80. package/dist/src/client/rpc/ipc-socket-path.d.ts +11 -0
  81. package/dist/src/client/rpc/ipc-socket-path.js +30 -0
  82. package/dist/src/client/rpc/node-rpc-client.js +14 -25
  83. package/dist/src/client/rpc/rpc-client.d.ts +3 -2
  84. package/dist/src/client/rpc/rpc-client.js +46 -12
  85. package/dist/src/client/rpc/rpc-error.js +4 -1
  86. package/dist/src/commands/bundle/constants.js +1 -0
  87. package/dist/src/commands/bundle/entry-gen.js +1 -1
  88. package/dist/src/commands/bundle/index.d.ts +1 -1
  89. package/dist/src/commands/bundle/index.js +11 -11
  90. package/dist/src/commands/bundle/plugins.js +1 -1
  91. package/dist/src/commands/host-prebuilds/index.d.ts +3 -3
  92. package/dist/src/commands/host-prebuilds/index.js +4 -4
  93. package/dist/src/commands/index.d.ts +12 -12
  94. package/dist/src/commands/index.js +7 -7
  95. package/dist/src/commands/verify/abi.d.ts +1 -1
  96. package/dist/src/commands/verify/abi.js +1 -1
  97. package/dist/src/commands/verify/bare-kit-runtime.d.ts +1 -1
  98. package/dist/src/commands/verify/bare-kit-runtime.js +1 -1
  99. package/dist/src/commands/verify/bundle-source.d.ts +1 -1
  100. package/dist/src/commands/verify/bundle-source.js +3 -3
  101. package/dist/src/commands/verify/engines-advice.d.ts +4 -4
  102. package/dist/src/commands/verify/engines-advice.js +4 -4
  103. package/dist/src/commands/verify/index.d.ts +5 -5
  104. package/dist/src/commands/verify/index.js +7 -7
  105. package/dist/src/commands/verify/node-modules-source.d.ts +1 -1
  106. package/dist/src/commands/verify/node-modules-source.js +1 -1
  107. package/dist/src/commands/verify/prebuilds.d.ts +1 -1
  108. package/dist/src/commands/verify/prebuilds.js +2 -2
  109. package/dist/src/commands/verify/resource-collectors.js +2 -2
  110. package/dist/src/expo/plugins/get-project-root.d.ts +1 -1
  111. package/dist/src/expo/plugins/link-addons.js +1 -1
  112. package/dist/src/expo/plugins/withAndroidArchitecture.d.ts +1 -1
  113. package/dist/src/expo/plugins/withAndroidNdkVersion.d.ts +1 -1
  114. package/dist/src/expo/plugins/withAndroidNdkVersion.js +16 -10
  115. package/dist/src/expo/plugins/withDeviceInfo.d.ts +1 -1
  116. package/dist/src/expo/plugins/withDeviceInfo.js +19 -5
  117. package/dist/src/expo/plugins/withMobileBundle.d.ts +4 -4
  118. package/dist/src/expo/plugins/withMobileBundle.js +6 -6
  119. package/dist/src/expo/plugins/withOpenCL.d.ts +1 -1
  120. package/dist/src/expo/plugins/withQvacSDK.d.ts +1 -1
  121. package/dist/src/index.d.ts +4 -4
  122. package/dist/src/index.js +3 -3
  123. package/dist/src/logging/addon.d.ts +1 -1
  124. package/dist/src/logging/base-logger.js +1 -1
  125. package/dist/src/logging/utils.js +1 -1
  126. package/dist/src/pear/pre.js +2 -0
  127. package/dist/src/plugin-ids.d.ts +2 -1
  128. package/dist/src/plugin-ids.js +2 -0
  129. package/dist/src/schemas/public.d.ts +1 -1
  130. package/dist/src/schemas/public.js +1 -1
  131. package/dist/src/schemas/sdk-errors-server.d.ts +1 -0
  132. package/dist/src/schemas/sdk-errors-server.js +6 -1
  133. package/dist/src/server/rpc/rpc-utils.d.ts +5 -0
  134. package/dist/src/server/rpc/rpc-utils.js +7 -0
  135. package/dist/src/server/utils/qvac-paths.js +1 -1
  136. package/dist/src/server/utils/worker-lock.js +1 -1
  137. package/dist/src/utils/aggregate-events.d.ts +1 -1
  138. package/dist/src/utils/aggregate-events.js +2 -2
  139. package/dist/src/utils/errors-server.d.ts +6 -0
  140. package/dist/src/utils/errors-server.js +12 -0
  141. package/dist/src/utils/mcp-adapter.d.ts +1 -1
  142. package/dist/src/utils/mcp-adapter.js +1 -1
  143. package/dist/src/utils/tool-helpers.js +1 -1
  144. package/dist/src/worker/handle-request.js +4 -2
  145. package/dist/src/worker/handler-utils.js +1 -1
  146. package/dist/src/worker/index.js +3 -1
  147. package/dist/src/worker/lifecycle.js +1 -1
  148. package/dist/src/worker/plugins/llamacpp-rerank.d.ts +2 -0
  149. package/dist/src/worker/plugins/llamacpp-rerank.js +1 -0
  150. package/package.json +46 -40
package/README.md CHANGED
@@ -20,8 +20,6 @@ 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
-
25
23
  See https://docs.qvac.tether.io/sdk/getting-started/installation
26
24
 
27
25
  On Node.js, the SDK installs and launches its own Bare worker through `bare-runtime`.
@@ -31,52 +29,7 @@ package manager can replace an older, incompatible runtime. Remove any override
31
29
  or resolution that forces the worker below that requirement; installing a newer
32
30
  global `bare` executable does not change the SDK's worker dependency.
33
31
 
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.
32
+ 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.
80
33
 
81
34
  ## Quickstart
82
35
 
@@ -137,154 +90,29 @@ call fails with `RPC_INIT_TIMEOUT`. Re-running usually succeeds; to give every
137
90
  start more room, raise `rpcInitTimeoutMs` in `qvac.config.*` or set the
138
91
  `QVAC_RPC_INIT_TIMEOUT_MS` environment variable.
139
92
 
140
- ## System resource diagnostics
141
-
142
- Use `getSystemResources` to inspect locally observed CPU, system-memory, GPU, and
143
- driver capabilities. Pass `sample: true` only when you also need a fresh usage
144
- sample:
145
-
146
- ```ts
147
- import { getSystemResources } from '@qvac/sdk'
148
-
149
- const resources = await getSystemResources({ sample: true })
150
-
151
- if (resources.capabilities.memory.totalBytes.status === 'supported') {
152
- console.log('System memory:', resources.capabilities.memory.totalBytes.value)
153
- }
154
-
155
- if (resources.sample?.cpu.status === 'supported') {
156
- console.log('CPU utilization:', resources.sample.cpu.value)
157
- }
158
- ```
159
-
160
- See the [system resources support matrix](./docs/system-resources-support-matrix.md)
161
- for metric-level evidence and platform limitations.
162
-
163
- Every metric reports `supported`, `unavailable`, `unverified`, or `failed`.
164
- Supported values include provenance with a source and optional scope. These
165
- values are diagnostics; they do not reserve memory or guarantee that a model
166
- can be loaded.
167
-
168
- GPU capabilities expose observed driver names, versions, and graphics APIs.
169
- These observations do not prove that an inference backend is compatible.
170
-
171
- Profiled inference operation events may include `event.backend` with the
172
- selected backend and device, graphics API, driver, fallback reason, and probe
173
- result. Addons attach backend metadata with `attachBackendDiagnostics`; the SDK
174
- validates it before recording the operation event. `gpuId`, when present,
175
- identifies a GPU from the current worker resource collector and is stable only
176
- for that collector's lifetime. The SDK does not infer compatibility from driver
177
- inventory or log text.
178
-
179
- ### Profiler resource gauges
180
-
181
- Resource gauges are disabled by default. Enable them explicitly to attach one
182
- worker resource sample to each profiled operation:
183
-
184
- ```ts
185
- import { profiler } from '@qvac/sdk'
186
-
187
- profiler.enable({ mode: 'verbose', includeResourceGauges: true })
188
-
189
- // Run SDK operations, then inspect recentEvents[].resources.
190
- const profile = profiler.exportJSON()
191
- ```
192
-
193
- The sample uses the same status, provenance, and scope semantics as
194
- `getSystemResources({ sample: true })`. Its `sampledAt` uses the same monotonic
195
- clock as the profiling event's `ts`, so the two timestamps are comparable.
196
- `resources.origin` records that the sample was taken on the `local` worker.
197
- Samples are delivered to `profiler.onRecord`; they
198
- are retained in `exportJSON().recentEvents` only in `verbose` mode. Enabling
199
- gauges in `summary` mode still incurs the sampling cost without retaining them.
200
- Disabling profiling or omitting `includeResourceGauges` performs no resource
201
- sampling. Enabling gauges adds one CPU query and one query per GPU to each
202
- profiled operation's response path. If the worker resource collector is not
203
- initialized, the event omits the resource block.
204
-
205
- ## Pre-download model fit assessment
206
-
207
- Use `assessModelFit` to check, before downloading anything, whether models are
208
- likely to fit in this device's memory. Each candidate is described as `loadModel`
209
- takes it. It reads generated catalog metadata plus a fresh memory sample, and for
210
- a single candidate the registry's weightless description of the artifact, so the
211
- engine's own fitter can answer — no weights, no load:
212
-
213
- ```ts
214
- import { assessModelFit, QWEN3_8B_INST_Q4_K_M } from '@qvac/sdk'
215
-
216
- const result = await assessModelFit({
217
- models: [{ modelSrc: QWEN3_8B_INST_Q4_K_M, modelType: 'llm', modelConfig: { ctx_size: 8192 } }],
218
- execution: 'sequential',
219
- policy: 'interactive-v1'
220
- })
221
-
222
- console.log(result.verdict) // 'likely-fits' | 'likely-too-large' | 'unknown'
223
- ```
224
-
225
- The result is advisory: it does not block `loadModel`, reserve memory, or make a
226
- performance claim. `unknown` is a real answer meaning the evidence does not
227
- support a call either way — show it as "can't say", not as "no".
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
-
233
- See [pre-download model fit assessment](./docs/assess-model-fit.md) for the
234
- budget arithmetic, the reserve, and the supported engine and workload matrix.
235
-
236
- ## Streaming transcription statistics
237
-
238
- Whisper and Parakeet duplex transcription sessions expose terminal engine
239
- statistics after their event iterator completes:
93
+ ## Documentation
240
94
 
241
- ```ts
242
- const session = await transcribeStream({ modelId })
95
+ The [QVAC SDK documentation](https://docs.qvac.tether.io/sdk/) covers each
96
+ capability with its configuration and examples. See the
97
+ [API reference](https://docs.qvac.tether.io/sdk/reference/api/) for the full API
98
+ and the [release notes](https://docs.qvac.tether.io/sdk/reference/release-notes/)
99
+ for what changed in each release.
243
100
 
244
- for await (const text of session) {
245
- process.stdout.write(text)
246
- }
247
-
248
- const stats = await session.stats
249
- console.log(stats?.audioDuration, stats?.realTimeFactor)
250
- ```
251
-
252
- `session.stats` resolves to `undefined` when the engine does not report
253
- statistics.
254
-
255
- Batch `transcribe()` calls also expose terminal statistics:
256
-
257
- ```ts
258
- const call = transcribe({ modelId, audioChunk })
259
- const text = await call
260
- const stats = await call.stats
261
- console.log(text, stats?.encoderUsedCoreml)
262
- ```
263
-
264
- `call.stats` resolves to `undefined` when the engine reports no statistics and
265
- rejects if transcription fails.
266
-
267
- ## Parakeet Core ML encoders on Apple devices
268
-
269
- Load a supported Parakeet registry constant as usual. On macOS and iOS, the SDK
270
- downloads any complete, published Core ML encoder bundle with its GGUF and
271
- places the `.mlmodelc` directory where the native addon discovers it. This is
272
- available for TDT 0.6B v3, Unified English 0.6B, EOU 120M v1, and streaming
273
- Sortformer v2.1. The download includes the sidecar weights, so first load takes
274
- more time and disk space. Other platforms download only the GGUF. If the
275
- sidecar is unavailable or cannot load, inference uses the GGUF encoder.
276
- Sortformer v2.1 also needs a GGUF with the
277
- `parakeet.model_variant=sortformer-streaming-v2.1-aosc` metadata. Caching both
278
- sidecars alone does not activate Core ML. See
279
- [`examples/asr/parakeet-unified-coreml.ts`](examples/asr/parakeet-unified-coreml.ts)
280
- for a local check of a Unified GGUF and its encoder bundle.
101
+ TranscribePsy (`PARAKEET_TRANSCRIBEPSY_250M_Q8_0`, eight European
102
+ languages) has a separate Core ML distribution instead of a sidecar:
103
+ `PARAKEET_TRANSCRIBEPSY_250M_COREML_Q8_0` is an encoder-less GGUF whose
104
+ encoder and decoder bundles the SDK stages beside it, so both stages run on
105
+ the Neural Engine. It loads on macOS and iOS only; elsewhere the load is
106
+ refused up front with the ggml constant to use instead. See
107
+ [`examples/asr/parakeet-transcribepsy-filesystem.ts`](examples/asr/parakeet-transcribepsy-filesystem.ts),
108
+ which also shows the `longFormWindowFrames` / `longFormContextFrames` knobs
109
+ that bound the offline encoder window on long recordings.
281
110
 
282
111
  ## Examples
283
112
 
284
- In the `./examples` subdirectory, you will find scripts demonstrating how to use all SDK functionalities. To try any of them:
285
-
286
- 1. Build the SDK from source (see [Build](#build) section).
287
- 2. Run with Node.js:
113
+ The [`examples`](./examples) directory has scripts covering every SDK capability.
114
+ To run one, set up the SDK from source as described in
115
+ [`CONTRIBUTING.md`](./CONTRIBUTING.md), then from `packages/sdk`:
288
116
 
289
117
  ```bash
290
118
  # Compiled output
@@ -294,274 +122,8 @@ node dist/examples/path/to/example.js
294
122
  npx tsx examples/path/to/example.ts
295
123
  ```
296
124
 
297
- `examples/abot-world.ts` has a companion guide covering the hardware
298
- requirements, scene-pack lifecycle, cancellation semantics and concurrency rules
299
- of an interactive world session: see
300
- [ABot-World interactive world sessions](./docs/abot-world.md).
301
-
302
- ## Build
303
-
304
- Node.js 22 and npm are the only tools needed. No lockfile is committed; `package-lock.json` is gitignored.
305
-
306
- Build and test against the in-repo engine at the same commit (this is what CI does):
307
-
308
- ```bash
309
- npm run sdk-source:workspace
310
- ```
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
-
314
- ```bash
315
- npm run build # or `watch` for hotreload
316
- ```
317
-
318
- ```bash
319
- npm run build:pack
320
- ```
321
-
322
- This outputs a tarball under `dist/qvac-sdk-{version}.tgz` that you can install in your project, e.g.:
323
-
324
- ```bash
325
- npm i path/to/qvac-sdk-0.21.0.tgz
326
- ```
327
-
328
- ## Testing
329
-
330
- The SDK test suite is organized into two buckets by runtime:
331
-
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) |
336
-
337
- See [`TESTING.md`](./TESTING.md) for the full decision tree on where new tests should land.
338
-
339
125
  ## Contributing
340
126
 
341
- ### Commit Message and PR Title Format
342
-
343
- This repository enforces structured commit messages and PR titles to maintain consistency and generate changelogs automatically.
344
-
345
- #### Format
346
-
347
- **Commit messages:**
348
-
349
- ```
350
- prefix[tags]?: subject
351
- ```
352
-
353
- **PR titles:**
354
-
355
- ```
356
- TICKET prefix[tags]: subject
357
- ```
358
-
359
- #### Allowed Prefixes
360
-
361
- - `feat` - New features or capabilities
362
- - `fix` - Bug fixes
363
- - `doc` - Documentation changes
364
- - `test` - Test additions or modifications
365
- - `mod` - Model-related changes
366
- - `chore` - Maintenance tasks
367
- - `infra` - CI/CD, tooling, infrastructure
368
-
369
- #### Allowed Tags
370
-
371
- Tags are optional:
372
-
373
- - `[api]` - API changes (non-breaking)
374
- - `[bc]` - Breaking changes (including breaking API changes)
375
-
376
- #### Examples
377
-
378
- **Valid commit messages:**
379
-
380
- ```bash
381
- feat: add RAG support for LanceDB
382
- fix[api]: fix completion stream error handling
383
- doc: update installation instructions
384
- feat[bc]: redesign loadModel signature
385
- chore: update dependencies
386
- ```
387
-
388
- **Valid PR titles:**
389
-
390
- ```bash
391
- QVAC-123 feat: add RAG support for LanceDB
392
- QVAC-456 fix[api]: fix completion stream error handling
393
- QVAC-789 doc: update installation instructions
394
- QVAC-101 feat[bc]: redesign loadModel signature
395
- ```
396
-
397
- #### Code Examples Requirements
398
-
399
- When creating PRs with specific tags, you must include code examples in the PR description:
400
-
401
- **`[bc]` tag requirements:**
402
-
403
- Must include BEFORE/AFTER code examples showing the migration path:
404
-
405
- ````markdown
406
- ## BC Changes
407
-
408
- **BEFORE:**
409
-
410
- ```typescript
411
- const model = await loadModel('model-path')
412
- ```
413
-
414
- **AFTER:**
415
-
416
- ```typescript
417
- const modelId = await loadModel('model-path', { modelType: 'llm' })
418
- ```
419
- ````
420
-
421
- Or using inline comments:
422
-
423
- ````markdown
424
- ```typescript
425
- // old
426
- const model = await loadModel('model-path')
427
-
428
- // new
429
- const modelId = await loadModel('model-path', { modelType: 'llm' })
430
- ```
431
- ````
432
-
433
- **`[api]` tag requirements (non-breaking):**
434
-
435
- Must include at least one fenced code block showing the new API usage:
436
-
437
- ````markdown
438
- ## New API
439
-
440
- ```typescript
441
- // New completion API with streaming support
442
- for await (const token of completion({
443
- modelId,
444
- history: [{ role: 'user', content: 'Hello!' }]
445
- }).tokenStream) {
446
- process.stdout.write(token)
447
- }
448
- ```
449
- ````
450
-
451
- #### Validation
452
-
453
- - **Commit messages** are validated automatically via Husky commit-msg hook
454
- - **PR titles and descriptions** are validated via GitHub Actions on PR creation/update
455
- - Invalid commits or PRs will be rejected with helpful error messages
456
- - **Auto-skipped commits:** The following Git-generated commits bypass validation:
457
- - Merge commits (e.g., `Merge pull request #123`)
458
- - Version bumps (e.g., `1.0.0`, `v1.0.0`)
459
- - Revert commits (e.g., `Revert "feat: add feature"`)
460
- - Squash commits (e.g., `squash! fix: bug fix`)
461
-
462
- #### Generating Changelogs
463
-
464
- Once your PRs are merged into `dev`, you can generate a changelog:
465
-
466
- ```bash
467
- npm run changelog:generate
468
- ```
469
-
470
- This will:
471
-
472
- 1. Compare versions between `dev` and `main` branches
473
- 2. Collect all merged PRs
474
- 3. Parse and classify each PR by prefix
475
- 4. Generate `changelog/<version>/CHANGELOG.md`
476
- 5. Generate `changelog/<version>/breaking.md` for BC changes (with code examples)
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
- ```
127
+ See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for building from source, commit and
128
+ PR title format, and changelog generation, and [`TESTING.md`](./TESTING.md) for
129
+ where new tests belong.
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=parakeet-transcribepsy-filesystem.d.ts.map
@@ -0,0 +1,76 @@
1
+ /**
2
+ * TranscribePsy transcription from an audio file.
3
+ *
4
+ * Usage:
5
+ * npx tsx examples/asr/parakeet-transcribepsy-filesystem.ts <audio-file> [--coreml] [--window-sec <seconds>]
6
+ *
7
+ * TranscribePsy-250M-EU-sub is a 254M Parakeet-TDT distilled for Dutch,
8
+ * English, French, German, Italian, Polish, Portuguese and Spanish; the engine
9
+ * detects the language, so there is nothing to set. The default constant
10
+ * (`PARAKEET_TRANSCRIBEPSY_250M_Q8_0`) runs on ggml everywhere. On
11
+ * macOS and iOS, `--coreml` loads the Core ML distribution instead
12
+ * (`PARAKEET_TRANSCRIBEPSY_250M_COREML_Q8_0`): the SDK downloads its
13
+ * encoder and decoder bundles with the GGUF, and both stages run on the Neural
14
+ * Engine. Anywhere else that constant is refused at load time.
15
+ *
16
+ * Long recordings are encoded in overlapping windows, so memory stays flat
17
+ * however long the file is. Without `--window-sec` the engine uses the 60 s
18
+ * windows with 25 % overlap the model recommends; an explicit window is sent
19
+ * as encoder frames (12.5 per second) with a quarter of it as context, which
20
+ * is how a phone with little memory can trade speed for a smaller footprint.
21
+ */
22
+ import { loadModel, unloadModel, transcribe, PARAKEET_TRANSCRIBEPSY_250M_Q8_0, PARAKEET_TRANSCRIBEPSY_250M_COREML_Q8_0 } from '@qvac/sdk';
23
+ const ENCODER_FRAMES_PER_SECOND = 12.5;
24
+ const RECOMMENDED_OVERLAP = 0.25;
25
+ const args = process.argv.slice(2);
26
+ const audioFilePath = args.find((arg) => !arg.startsWith('--'));
27
+ const useCoreml = args.includes('--coreml');
28
+ const windowIndex = args.indexOf('--window-sec');
29
+ const windowSeconds = windowIndex === -1 ? undefined : Number(args[windowIndex + 1]);
30
+ if (!audioFilePath || (windowSeconds !== undefined && !(windowSeconds > 0))) {
31
+ console.error('Usage: npx tsx examples/asr/parakeet-transcribepsy-filesystem.ts <audio-file> ' +
32
+ '[--coreml] [--window-sec <seconds>]');
33
+ process.exit(1);
34
+ }
35
+ // An explicit window becomes the engine's frame counts; the overlap is shared
36
+ // half and half with each neighbouring window.
37
+ const longForm = windowSeconds === undefined
38
+ ? {}
39
+ : {
40
+ longFormWindowFrames: Math.round(windowSeconds * ENCODER_FRAMES_PER_SECOND),
41
+ longFormContextFrames: Math.round((windowSeconds * ENCODER_FRAMES_PER_SECOND * RECOMMENDED_OVERLAP) / 2)
42
+ };
43
+ const modelSrc = useCoreml
44
+ ? PARAKEET_TRANSCRIBEPSY_250M_COREML_Q8_0
45
+ : PARAKEET_TRANSCRIBEPSY_250M_Q8_0;
46
+ try {
47
+ console.log(`▸ Loading TranscribePsy (${useCoreml ? 'Core ML distribution' : 'ggml'})...`);
48
+ const modelId = await loadModel({
49
+ modelSrc,
50
+ modelType: 'parakeet-transcription',
51
+ modelConfig: longForm,
52
+ onProgress: (p) => {
53
+ const mb = (n) => (n / 1e6).toFixed(1);
54
+ const line = `▸ Downloading ${p.percentage.toFixed(0)}% (${mb(p.downloaded)}/${mb(p.total)} MB)`;
55
+ process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
56
+ if (p.percentage >= 100)
57
+ process.stderr.write('\n');
58
+ }
59
+ });
60
+ console.log(windowSeconds === undefined
61
+ ? '▸ Transcribing with the windows the model recommends (60 s, 25 % overlap)...'
62
+ : `▸ Transcribing in ${windowSeconds} s windows...`);
63
+ const call = transcribe({ modelId, audioChunk: audioFilePath });
64
+ const text = await call;
65
+ const stats = await call.stats;
66
+ console.log(text);
67
+ if (stats) {
68
+ console.log(`▸ ${stats.audioDuration?.toFixed(1) ?? '?'} s of audio, real-time factor ${stats.realTimeFactor?.toFixed(3) ?? '?'}` +
69
+ (useCoreml ? `, encoder on Core ML: ${stats.encoderUsedCoreml === 1 ? 'yes' : 'no'}` : ''));
70
+ }
71
+ await unloadModel({ modelId });
72
+ }
73
+ catch (error) {
74
+ console.error('✖', error);
75
+ process.exit(1);
76
+ }
@@ -1,4 +1,4 @@
1
- import { loadModel, unloadModel, video } from '@qvac/sdk';
1
+ import { GEMMA_3_12B_Q4_K_XL, loadModel, LTX_2_3_22B_DISTILLED_EMBEDDINGS_CONNECTORS, LTX_2_3_22B_Q5_K_M, LTX_2_3_AUDIO_VAE, LTX_2_3_VIDEO_VAE, unloadModel, video } from '@qvac/sdk';
2
2
  import fs from 'fs';
3
3
  import path from 'path';
4
4
  // Image-to-video (+ synchronized audio) with LTX-2. Unlike Wan I2V, LTX-2
@@ -9,22 +9,15 @@ import path from 'path';
9
9
  // This example needs powerful hardware: LTX-2.3 is a ~21B model, budget at
10
10
  // least 20+ GB of video / unified memory.
11
11
  //
12
- // No LTX-2 model constants ship in the SDK registry, so the model sources
13
- // default to public HuggingFace URLs (the SDK downloads http(s) sources
14
- // directly). Pass your own paths / URLs via argv to override.
15
- const HF = 'https://huggingface.co';
12
+ // Pass your own paths / URLs via argv to override any of the five sources.
16
13
  const initImagePath = process.argv[2];
17
14
  const prompt = process.argv[3] || 'the subject slowly turns and smiles, soft natural lighting, cinematic';
18
15
  const outputDir = process.argv[4] || '.';
19
- const diffusionModelSrc = process.argv[5] ||
20
- `${HF}/QuantStack/LTX-2.3-GGUF/resolve/main/LTX-2.3-distilled-1.1/LTX-2.3-22B-distilled-1.1-Q5_K_M.gguf`;
21
- const llmModelSrc = process.argv[6] || `${HF}/unsloth/gemma-3-12b-it-GGUF/resolve/main/gemma-3-12b-it-UD-Q4_K_XL.gguf`;
22
- const vaeModelSrc = process.argv[7] ||
23
- `${HF}/unsloth/LTX-2.3-GGUF/resolve/main/vae/ltx-2.3-22b-distilled_video_vae.safetensors`;
24
- const audioVaeModelSrc = process.argv[8] ||
25
- `${HF}/unsloth/LTX-2.3-GGUF/resolve/main/vae/ltx-2.3-22b-distilled_audio_vae.safetensors`;
26
- const embeddingsConnectorsModelSrc = process.argv[9] ||
27
- `${HF}/unsloth/LTX-2.3-GGUF/resolve/main/text_encoders/ltx-2.3-22b-distilled_embeddings_connectors.safetensors`;
16
+ const diffusionModelSrc = process.argv[5] || LTX_2_3_22B_Q5_K_M;
17
+ const llmModelSrc = process.argv[6] || GEMMA_3_12B_Q4_K_XL;
18
+ const vaeModelSrc = process.argv[7] || LTX_2_3_VIDEO_VAE;
19
+ const audioVaeModelSrc = process.argv[8] || LTX_2_3_AUDIO_VAE;
20
+ const embeddingsConnectorsModelSrc = process.argv[9] || LTX_2_3_22B_DISTILLED_EMBEDDINGS_CONNECTORS;
28
21
  if (!initImagePath) {
29
22
  console.error('✖ init image path is required');
30
23
  console.error('Usage: node dist/examples/diffusion-img2vid-ltx.js ' +
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=diffusion-qwen-image-21.d.ts.map