@qvac/inference 0.19.1 → 0.20.1

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 (152) hide show
  1. package/NOTICE +57 -17
  2. package/dist/api/assess-model-fit.d.ts +9 -4
  3. package/dist/api/assess-model-fit.js +9 -4
  4. package/dist/api/audio-gen.d.ts +42 -1
  5. package/dist/api/audio-gen.js +137 -51
  6. package/dist/api/index.d.ts +2 -1
  7. package/dist/api/index.js +2 -1
  8. package/dist/api/text-to-speech.d.ts +31 -4
  9. package/dist/api/text-to-speech.js +117 -21
  10. package/dist/api/vector-index.d.ts +142 -0
  11. package/dist/api/vector-index.js +168 -0
  12. package/dist/api/world.d.ts +2 -2
  13. package/dist/errors/index.d.ts +12 -0
  14. package/dist/errors/index.js +21 -0
  15. package/dist/handlers/assess-model-fit.d.ts +30 -6
  16. package/dist/handlers/assess-model-fit.js +68 -6
  17. package/dist/handlers/load-model/registry-download-utils.d.ts +1 -0
  18. package/dist/handlers/load-model/registry-download-utils.js +2 -1
  19. package/dist/handlers/vector-index.d.ts +2 -0
  20. package/dist/handlers/vector-index.js +40 -0
  21. package/dist/index.d.ts +1 -1
  22. package/dist/index.js +1 -1
  23. package/dist/models/registry/models.d.ts +351 -12
  24. package/dist/models/registry/models.js +2271 -1957
  25. package/dist/models/registry/resource-profiles.js +135 -0
  26. package/dist/plugins/builtin/audiogen-ggml/ops/audio-edit-stream.d.ts +2 -0
  27. package/dist/plugins/builtin/audiogen-ggml/ops/audio-edit-stream.js +65 -0
  28. package/dist/plugins/builtin/audiogen-ggml/ops/audio-gen-input.d.ts +9 -1
  29. package/dist/plugins/builtin/audiogen-ggml/ops/audio-gen-input.js +24 -7
  30. package/dist/plugins/builtin/audiogen-ggml/ops/audio-gen-run.d.ts +46 -0
  31. package/dist/plugins/builtin/audiogen-ggml/ops/audio-gen-run.js +218 -0
  32. package/dist/plugins/builtin/audiogen-ggml/ops/audio-gen-stream.d.ts +1 -1
  33. package/dist/plugins/builtin/audiogen-ggml/ops/audio-gen-stream.js +56 -225
  34. package/dist/plugins/builtin/audiogen-ggml/ops/audio-understand.d.ts +8 -0
  35. package/dist/plugins/builtin/audiogen-ggml/ops/audio-understand.js +28 -0
  36. package/dist/plugins/builtin/audiogen-ggml/plugin.d.ts +248 -0
  37. package/dist/plugins/builtin/audiogen-ggml/plugin.js +17 -1
  38. package/dist/plugins/builtin/bci-whispercpp-transcription/plugin.d.ts +5 -2
  39. package/dist/plugins/builtin/bci-whispercpp-transcription/plugin.js +1 -2
  40. package/dist/plugins/builtin/ggml-ocr/plugin.d.ts +1 -1
  41. package/dist/plugins/builtin/ggml-ocr/plugin.js +1 -2
  42. package/dist/plugins/builtin/llamacpp-completion/ops/batch-completion-stream.js +6 -4
  43. package/dist/plugins/builtin/llamacpp-completion/ops/cache-logger.d.ts +1 -2
  44. package/dist/plugins/builtin/llamacpp-completion/ops/cache-logger.js +0 -4
  45. package/dist/plugins/builtin/llamacpp-completion/ops/completion-stats.d.ts +1 -0
  46. package/dist/plugins/builtin/llamacpp-completion/ops/completion-stats.js +3 -0
  47. package/dist/plugins/builtin/llamacpp-completion/ops/completion-stream.d.ts +9 -0
  48. package/dist/plugins/builtin/llamacpp-completion/ops/completion-stream.js +96 -89
  49. package/dist/plugins/builtin/llamacpp-completion/ops/context-overflow.d.ts +0 -1
  50. package/dist/plugins/builtin/llamacpp-completion/ops/context-overflow.js +0 -31
  51. package/dist/plugins/builtin/llamacpp-completion/ops/kv-cache-session.d.ts +40 -24
  52. package/dist/plugins/builtin/llamacpp-completion/ops/kv-cache-session.js +187 -123
  53. package/dist/plugins/builtin/llamacpp-completion/ops/kv-cache-state.d.ts +11 -4
  54. package/dist/plugins/builtin/llamacpp-completion/ops/kv-cache-state.js +18 -16
  55. package/dist/plugins/builtin/llamacpp-completion/plugin.d.ts +69 -4
  56. package/dist/plugins/builtin/llamacpp-completion/plugin.js +1 -2
  57. package/dist/plugins/builtin/llamacpp-completion/transform.js +19 -0
  58. package/dist/plugins/builtin/llamacpp-embedding/plugin.d.ts +1 -2
  59. package/dist/plugins/builtin/llamacpp-embedding/plugin.js +2 -38
  60. package/dist/plugins/builtin/llamacpp-embedding/transform.d.ts +9 -0
  61. package/dist/plugins/builtin/llamacpp-embedding/transform.js +42 -0
  62. package/dist/plugins/builtin/nmtcpp-translation/plugin.d.ts +1 -1
  63. package/dist/plugins/builtin/nmtcpp-translation/plugin.js +1 -2
  64. package/dist/plugins/builtin/parakeet-transcription/plugin.d.ts +1 -1
  65. package/dist/plugins/builtin/parakeet-transcription/plugin.js +1 -2
  66. package/dist/plugins/builtin/sdcpp-generation/ops/video.d.ts +1 -0
  67. package/dist/plugins/builtin/sdcpp-generation/ops/video.js +8 -2
  68. package/dist/plugins/builtin/sdcpp-generation/plugin.d.ts +9 -4
  69. package/dist/plugins/builtin/sdcpp-generation/plugin.js +51 -19
  70. package/dist/plugins/builtin/tts-ggml/ops/cancel-binding.d.ts +29 -0
  71. package/dist/plugins/builtin/tts-ggml/ops/cancel-binding.js +66 -0
  72. package/dist/plugins/builtin/tts-ggml/ops/parler-options.js +10 -0
  73. package/dist/plugins/builtin/tts-ggml/ops/text-to-speech-stream.d.ts +3 -5
  74. package/dist/plugins/builtin/tts-ggml/ops/text-to-speech-stream.js +143 -28
  75. package/dist/plugins/builtin/tts-ggml/ops/text-to-speech.d.ts +5 -2
  76. package/dist/plugins/builtin/tts-ggml/ops/text-to-speech.js +182 -66
  77. package/dist/plugins/builtin/tts-ggml/plugin.d.ts +267 -22
  78. package/dist/plugins/builtin/tts-ggml/plugin.js +94 -35
  79. package/dist/plugins/builtin/whispercpp-transcription/plugin.d.ts +1 -1
  80. package/dist/plugins/builtin/whispercpp-transcription/plugin.js +1 -2
  81. package/dist/plugins/index.d.ts +1 -1
  82. package/dist/plugins/index.js +1 -1
  83. package/dist/plugins/ops/load-model.js +22 -2
  84. package/dist/plugins/ops/translate.js +58 -12
  85. package/dist/plugins/ops/translatepsy-utils.d.ts +17 -0
  86. package/dist/plugins/ops/translatepsy-utils.js +32 -0
  87. package/dist/plugins/registry.d.ts +15 -0
  88. package/dist/plugins/registry.js +133 -15
  89. package/dist/plugins/turbovec-backend.d.ts +17 -0
  90. package/dist/plugins/turbovec-backend.js +99 -0
  91. package/dist/registry.js +4 -0
  92. package/dist/resources/model-fit/assess.d.ts +10 -1
  93. package/dist/resources/model-fit/assess.js +43 -0
  94. package/dist/resources/model-fit/fit-stub/fetch-fit-stub.d.ts +83 -0
  95. package/dist/resources/model-fit/fit-stub/fetch-fit-stub.js +133 -0
  96. package/dist/resources/model-fit/fit-stub/index.d.ts +2 -0
  97. package/dist/resources/model-fit/fit-stub/index.js +2 -0
  98. package/dist/resources/model-fit/fit-stub/project-fit-from-stub.d.ts +31 -0
  99. package/dist/resources/model-fit/fit-stub/project-fit-from-stub.js +36 -0
  100. package/dist/resources/model-fit/native-probe/advisory-fit.d.ts +46 -0
  101. package/dist/resources/model-fit/native-probe/advisory-fit.js +214 -0
  102. package/dist/resources/model-fit/native-probe/create-llama-fit-request.d.ts +26 -0
  103. package/dist/resources/model-fit/native-probe/create-llama-fit-request.js +191 -0
  104. package/dist/resources/model-fit/native-probe/run-in-process-fit.d.ts +42 -0
  105. package/dist/resources/model-fit/native-probe/run-in-process-fit.js +192 -0
  106. package/dist/resources/model-fit/native-probe/run-isolated-fit.d.ts +70 -0
  107. package/dist/resources/model-fit/native-probe/run-isolated-fit.js +372 -0
  108. package/dist/runtime/env.d.ts +2 -0
  109. package/dist/runtime/env.js +9 -2
  110. package/dist/runtime/lifecycle.js +2 -0
  111. package/dist/runtime/model-registry.d.ts +3 -1
  112. package/dist/runtime/model-registry.js +2 -1
  113. package/dist/runtime/request-context.js +17 -0
  114. package/dist/runtime/vector-index-backend.d.ts +25 -0
  115. package/dist/runtime/vector-index-backend.js +1 -0
  116. package/dist/runtime/vector-index-registry.d.ts +76 -0
  117. package/dist/runtime/vector-index-registry.js +161 -0
  118. package/dist/schemas/assess-model-fit.d.ts +67 -0
  119. package/dist/schemas/assess-model-fit.js +56 -2
  120. package/dist/schemas/audio-gen.d.ts +479 -4
  121. package/dist/schemas/audio-gen.js +376 -17
  122. package/dist/schemas/batch-completion-stream.d.ts +7 -0
  123. package/dist/schemas/batch-completion-stream.js +5 -3
  124. package/dist/schemas/common.d.ts +816 -15
  125. package/dist/schemas/common.js +8 -1
  126. package/dist/schemas/completion-event.d.ts +11 -1
  127. package/dist/schemas/completion-event.js +3 -0
  128. package/dist/schemas/completion-stream.d.ts +20 -0
  129. package/dist/schemas/completion-stream.js +41 -4
  130. package/dist/schemas/config.d.ts +186 -30
  131. package/dist/schemas/errors.d.ts +4 -0
  132. package/dist/schemas/errors.js +22 -0
  133. package/dist/schemas/index.d.ts +1 -0
  134. package/dist/schemas/index.js +1 -0
  135. package/dist/schemas/llamacpp-config.d.ts +88 -8
  136. package/dist/schemas/llamacpp-config.js +108 -8
  137. package/dist/schemas/load-model.d.ts +2906 -206
  138. package/dist/schemas/model-config-schemas.d.ts +251 -5
  139. package/dist/schemas/plugin.d.ts +10 -0
  140. package/dist/schemas/sdcpp-config.d.ts +221 -4
  141. package/dist/schemas/sdcpp-config.js +128 -22
  142. package/dist/schemas/text-to-speech.d.ts +780 -19
  143. package/dist/schemas/text-to-speech.js +298 -44
  144. package/dist/schemas/transcription-config.js +7 -4
  145. package/dist/schemas/vector-index.d.ts +194 -0
  146. package/dist/schemas/vector-index.js +185 -0
  147. package/dist/utils/addon-responses.d.ts +29 -3
  148. package/dist/utils/aggregate-events.d.ts +3 -1
  149. package/dist/utils/aggregate-events.js +7 -1
  150. package/dist/utils/tts-stats.d.ts +15 -11
  151. package/dist/utils/tts-stats.js +33 -11
  152. package/package.json +29 -26
@@ -3,6 +3,7 @@ import Buffer from 'bare-buffer';
3
3
  import { stream as streamRpc, duplex } from '../dispatch.js';
4
4
  import { getAppLogger } from '../logging/index.js';
5
5
  import { TextToSpeechStreamFailedError } from '../errors/index.js';
6
+ import { generateRequestId } from '../runtime/request-id.js';
6
7
  const logger = getAppLogger();
7
8
  /**
8
9
  * Fan-out queue that lets multiple consumers iterate the same TTS response
@@ -129,10 +130,11 @@ export class TtsMulticast {
129
130
  }
130
131
  }
131
132
  }
132
- function buildTtsRequest(params) {
133
+ function buildTtsRequest(params, requestId) {
133
134
  return {
134
135
  type: 'textToSpeech',
135
136
  modelId: params.modelId,
137
+ requestId,
136
138
  inputType: params.inputType ?? 'text',
137
139
  text: params.text,
138
140
  stream: params.stream ?? true,
@@ -155,10 +157,11 @@ function buildTtsRequest(params) {
155
157
  ...(params.quality !== undefined && { quality: params.quality })
156
158
  };
157
159
  }
158
- function buildTextToSpeechStreamRequest(params) {
160
+ function buildTextToSpeechStreamRequest(params, requestId) {
159
161
  return {
160
162
  type: 'textToSpeechStream',
161
163
  modelId: params.modelId,
164
+ requestId,
162
165
  inputType: params.inputType ?? 'text',
163
166
  ...(params.accumulateSentences !== undefined && {
164
167
  accumulateSentences: params.accumulateSentences
@@ -189,9 +192,9 @@ function buildTextToSpeechStreamRequest(params) {
189
192
  *
190
193
  * Three modes selected by `params.stream` and `params.sentenceStream`:
191
194
  *
192
- * - `stream: false` (default) — collect all PCM samples and resolve once via
195
+ * - `stream: false` — collect all PCM samples and resolve once via
193
196
  * `result.buffer` (`Promise<number[]>`). `bufferStream` is empty.
194
- * - `stream: true` — yield PCM samples through `result.bufferStream`
197
+ * - `stream: true` (default) — yield PCM samples through `result.bufferStream`
195
198
  * (`AsyncGenerator<number>`) as they arrive. `buffer` resolves to an empty
196
199
  * array.
197
200
  * - `stream: true, sentenceStream: true` — also exposes `result.chunkUpdates`
@@ -203,10 +206,21 @@ function buildTextToSpeechStreamRequest(params) {
203
206
  * if the consumer breaks out before the terminal frame, or rejects on a
204
207
  * pipeline error. Awaiting `done` is safe even when no stream is iterated.
205
208
  *
209
+ * `result.sampleRate` resolves from the first audio frame (so it can be awaited
210
+ * before draining the audio); `result.stats` and `result.stopReason` resolve
211
+ * from the terminal frame. All three resolve — with `undefined` when the run
212
+ * produced none — rather than reject. In `stream: true` mode (the default) the
213
+ * run starts lazily: nothing is sent until `bufferStream` is first iterated, so
214
+ * `done`, `sampleRate`, `stats` and `stopReason` stay pending until then. In
215
+ * `stream: false` and `sentenceStream: true` modes the run starts immediately.
216
+ * Read `sampleRate` rather than assuming the engine default: `outputSampleRate`
217
+ * and the LavaSR enhancer both change it.
218
+ *
206
219
  * @param params - TTS request parameters (see `TtsClientParamsInput`).
207
220
  * @param options - Optional RPC options (timeout, profiling, force new connection).
208
221
  * @returns A `TextToSpeechStreamResult` with `bufferStream`, `buffer`, `done`,
209
- * and (when `sentenceStream: true`) `chunkUpdates`.
222
+ * `sampleRate`, `stats`, and (when `sentenceStream: true`)
223
+ * `chunkUpdates`.
210
224
  * @throws {TextToSpeechStreamFailedError} When `sentenceStream: true` is paired
211
225
  * with `stream: false`, or when the underlying RPC stream errors.
212
226
  */
@@ -216,7 +230,10 @@ export function textToSpeech(params, options) {
216
230
  if (sentenceStream && !stream) {
217
231
  throw new TextToSpeechStreamFailedError('textToSpeech: `sentenceStream: true` requires `stream: true`');
218
232
  }
219
- const request = buildTtsRequest(params);
233
+ // Minted here and surfaced synchronously on the result so a caller can
234
+ // cancel a run it has only just started.
235
+ const requestId = params.requestId ?? generateRequestId();
236
+ const request = buildTtsRequest(params, requestId);
220
237
  if (stream && sentenceStream) {
221
238
  return sentenceStreamTts(request, options);
222
239
  }
@@ -225,18 +242,73 @@ export function textToSpeech(params, options) {
225
242
  }
226
243
  return collectTts(request, options);
227
244
  }
245
+ /** Exported for test use; not part of the public API surface. */
246
+ export function createTtsSideChannel() {
247
+ let resolveSampleRate;
248
+ let resolveStats;
249
+ let resolveStopReason;
250
+ const sampleRate = new Promise((resolve) => {
251
+ resolveSampleRate = resolve;
252
+ });
253
+ const stats = new Promise((resolve) => {
254
+ resolveStats = resolve;
255
+ });
256
+ const stopReason = new Promise((resolve) => {
257
+ resolveStopReason = resolve;
258
+ });
259
+ let seenSampleRate;
260
+ let latestStats;
261
+ let seenStopReason;
262
+ let settled = false;
263
+ return {
264
+ sampleRate,
265
+ stats,
266
+ stopReason,
267
+ observe(response) {
268
+ // Resolve on the FIRST frame that carries a rate, not at end of stream:
269
+ // a caller opening an audio device wants it before draining the audio.
270
+ // Promise resolution is idempotent, so settle() can still resolve the
271
+ // undefined fallback for a run that never reported one.
272
+ if (seenSampleRate === undefined && response.sampleRate !== undefined) {
273
+ seenSampleRate = response.sampleRate;
274
+ resolveSampleRate(seenSampleRate);
275
+ }
276
+ if (response.stats !== undefined)
277
+ latestStats = response.stats;
278
+ if (response.stopReason !== undefined)
279
+ seenStopReason = response.stopReason;
280
+ },
281
+ settle() {
282
+ if (settled)
283
+ return;
284
+ settled = true;
285
+ resolveSampleRate(seenSampleRate);
286
+ resolveStats(latestStats);
287
+ resolveStopReason(seenStopReason);
288
+ }
289
+ };
290
+ }
228
291
  // Adapts the raw RPC stream into the filtered `TtsResponse` source the
229
292
  // multicast expects. Kept here (not inlined) so the multicast can be
230
293
  // constructed in tests with a hand-rolled source instead.
231
- async function* ttsResponseSource(request, options) {
232
- for await (const response of streamRpc(request, options)) {
233
- if (response.type !== 'textToSpeech')
234
- continue;
235
- yield response;
294
+ async function* ttsResponseSource(request, options, side) {
295
+ try {
296
+ for await (const response of streamRpc(request, options)) {
297
+ if (response.type !== 'textToSpeech')
298
+ continue;
299
+ side.observe(response);
300
+ yield response;
301
+ }
302
+ }
303
+ finally {
304
+ // Reached on normal end, on error, and when the multicast's pump breaks
305
+ // out on the terminal frame.
306
+ side.settle();
236
307
  }
237
308
  }
238
309
  function sentenceStreamTts(request, options) {
239
- const multicast = new TtsMulticast(ttsResponseSource(request, options));
310
+ const side = createTtsSideChannel();
311
+ const multicast = new TtsMulticast(ttsResponseSource(request, options, side));
240
312
  // Subscribe eagerly, synchronously — before pump() can push its first
241
313
  // item — so both subscribers see the full queue from index 0. If we
242
314
  // deferred subscribing until the generators were iterated, the first
@@ -248,7 +320,11 @@ function sentenceStreamTts(request, options) {
248
320
  bufferStream: sentenceBufferStream(bufferSubscription),
249
321
  chunkUpdates: sentenceChunkUpdates(chunkSubscription),
250
322
  buffer: Promise.resolve([]),
251
- done: multicast.done
323
+ done: multicast.done,
324
+ requestId: request.requestId,
325
+ sampleRate: side.sampleRate,
326
+ stats: side.stats,
327
+ stopReason: side.stopReason
252
328
  };
253
329
  }
254
330
  async function* sentenceBufferStream(source) {
@@ -268,10 +344,12 @@ async function* sentenceChunkUpdates(source) {
268
344
  if (hasAudio || hasMeta) {
269
345
  yield {
270
346
  buffer: hasAudio ? [...m.buffer] : [],
347
+ ...(m.sampleRate !== undefined ? { sampleRate: m.sampleRate } : {}),
271
348
  ...(m.chunkIndex !== undefined ? { chunkIndex: m.chunkIndex } : {}),
272
349
  ...(typeof m.sentenceChunk === 'string' && m.sentenceChunk.length > 0
273
350
  ? { sentenceChunk: m.sentenceChunk }
274
- : {})
351
+ : {}),
352
+ ...(m.isLast !== undefined ? { isLast: m.isLast } : {})
275
353
  };
276
354
  }
277
355
  if (m.done)
@@ -286,13 +364,18 @@ function plainStreamTts(request, options) {
286
364
  rejectDone = reject;
287
365
  });
288
366
  done.catch(() => { });
367
+ const side = createTtsSideChannel();
289
368
  return {
290
- bufferStream: plainTtsBufferStream(request, options, resolveDone, rejectDone),
369
+ bufferStream: plainTtsBufferStream(request, options, resolveDone, rejectDone, side),
291
370
  buffer: Promise.resolve([]),
292
- done
371
+ done,
372
+ requestId: request.requestId,
373
+ sampleRate: side.sampleRate,
374
+ stats: side.stats,
375
+ stopReason: side.stopReason
293
376
  };
294
377
  }
295
- async function* plainTtsBufferStream(request, options, resolveDone, rejectDone) {
378
+ async function* plainTtsBufferStream(request, options, resolveDone, rejectDone, side) {
296
379
  let settled = false;
297
380
  try {
298
381
  for await (const response of streamRpc(request, options)) {
@@ -300,6 +383,7 @@ async function* plainTtsBufferStream(request, options, resolveDone, rejectDone)
300
383
  continue;
301
384
  // See TtsMulticast.pump — skip per-frame Zod validation; the engine is
302
385
  // the source of truth for this response shape.
386
+ side.observe(response);
303
387
  if (response.buffer.length > 0) {
304
388
  yield* response.buffer;
305
389
  }
@@ -321,6 +405,7 @@ async function* plainTtsBufferStream(request, options, resolveDone, rejectDone)
321
405
  // with `false` so `await result.done` never hangs.
322
406
  if (!settled)
323
407
  resolveDone(false);
408
+ side.settle();
324
409
  }
325
410
  }
326
411
  function collectTts(request, options) {
@@ -331,21 +416,27 @@ function collectTts(request, options) {
331
416
  rejectDone = reject;
332
417
  });
333
418
  done.catch(() => { });
419
+ const side = createTtsSideChannel();
334
420
  return {
335
421
  bufferStream: emptyBufferStream(),
336
- buffer: collectTtsBuffer(request, options, resolveDone, rejectDone),
337
- done
422
+ buffer: collectTtsBuffer(request, options, resolveDone, rejectDone, side),
423
+ done,
424
+ requestId: request.requestId,
425
+ sampleRate: side.sampleRate,
426
+ stats: side.stats,
427
+ stopReason: side.stopReason
338
428
  };
339
429
  }
340
430
  async function* emptyBufferStream() {
341
431
  // Non-streaming mode exposes no incremental buffer stream.
342
432
  }
343
- async function collectTtsBuffer(request, options, resolveDone, rejectDone) {
433
+ async function collectTtsBuffer(request, options, resolveDone, rejectDone, side) {
344
434
  let buffer = [];
345
435
  try {
346
436
  for await (const response of streamRpc(request, options)) {
347
437
  if (response.type !== 'textToSpeech')
348
438
  continue;
439
+ side.observe(response);
349
440
  buffer = buffer.concat(response.buffer);
350
441
  if (response.done) {
351
442
  resolveDone(true);
@@ -357,6 +448,9 @@ async function collectTtsBuffer(request, options, resolveDone, rejectDone) {
357
448
  rejectDone(e);
358
449
  throw e;
359
450
  }
451
+ finally {
452
+ side.settle();
453
+ }
360
454
  }
361
455
  /**
362
456
  * Duplex session: write UTF-8 text fragments (e.g. LLM token deltas) via `write`. Each string or
@@ -365,7 +459,8 @@ async function collectTtsBuffer(request, options, resolveDone, rejectDone) {
365
459
  * lines (PCM in `buffer`, optional `chunkIndex` / `sentenceChunk`) until `done`.
366
460
  */
367
461
  export async function textToSpeechStream(params, options) {
368
- const request = buildTextToSpeechStreamRequest(params);
462
+ const requestId = params.requestId ?? generateRequestId();
463
+ const request = buildTextToSpeechStreamRequest(params, requestId);
369
464
  const { requestStream, responseStream } = await duplex(request, options);
370
465
  const responses = parseTextToSpeechStreamLines(responseStream);
371
466
  let consumed = false;
@@ -375,6 +470,7 @@ export async function textToSpeechStream(params, options) {
375
470
  // surface predictable.
376
471
  let closed = false;
377
472
  return {
473
+ requestId,
378
474
  write(textFragment) {
379
475
  if (closed) {
380
476
  throw new TextToSpeechStreamFailedError('TextToSpeechStreamSession.write() called after end()/destroy()');
@@ -0,0 +1,142 @@
1
+ import { send } from '../dispatch.js';
2
+ import { type CreateVectorIndexParams, type LoadVectorIndexParams, type RPCOptions, type VectorIndexAddParams, type VectorIndexHit, type VectorIndexIdsParams, type VectorIndexStorage, type VectorIndexWriteParams } from '../schemas/index.js';
3
+ /**
4
+ * A handle to a vector index that lives in worker memory.
5
+ *
6
+ * Vectors are indexed under stable unsigned 64-bit ids and searched by
7
+ * dot-product similarity, so L2-normalize vectors before adding and queries
8
+ * before searching when cosine similarity is wanted. The index holds vectors
9
+ * only; keep the documents they describe wherever suits the app and map
10
+ * result ids back to them.
11
+ *
12
+ * The index is released by `dispose()` (or `await using`) and on worker
13
+ * shutdown. After a worker crash or restart every method rejects with
14
+ * `VECTOR_INDEX_NOT_FOUND`; recover by creating a new index or loading a
15
+ * snapshot written earlier with `write()`.
16
+ */
17
+ export interface VectorIndex {
18
+ /** Opaque id of the worker-side index; useful in logs, not needed for any call. */
19
+ readonly indexId: string;
20
+ /** Vector dimensionality every added vector and query must match. */
21
+ readonly dim: number;
22
+ /**
23
+ * Storage mode. Known after `createVectorIndex`. After `loadVectorIndex` it
24
+ * is derived from the snapshot's bit width, so 4-bit snapshots (`q4` or
25
+ * `turbovec-q4`) report `undefined`.
26
+ */
27
+ readonly storage: VectorIndexStorage | undefined;
28
+ /** Number of live entries as of the last call that changed or reported it. */
29
+ readonly length: number;
30
+ /**
31
+ * Adds vectors under the given ids in one atomic batch. Rejects duplicate
32
+ * ids, ids equal to 2^64 - 1, and rows whose length differs from `dim`.
33
+ * @returns The number of live entries after the add.
34
+ */
35
+ add(params: VectorIndexAddParams, options?: RPCOptions): Promise<{
36
+ length: number;
37
+ }>;
38
+ /**
39
+ * Finds the `k` nearest entries to one query. Hits are ordered by
40
+ * descending score, then ascending id, and fewer than `k` are returned
41
+ * when the index holds fewer entries.
42
+ * @overloadLabel "Single query"
43
+ */
44
+ search(params: {
45
+ query: number[];
46
+ k: number;
47
+ }, options?: RPCOptions): Promise<VectorIndexHit[]>;
48
+ /**
49
+ * Finds the `k` nearest entries to each query row; one hit list per row.
50
+ * @overloadLabel "Multiple queries"
51
+ */
52
+ search(params: {
53
+ queries: number[][];
54
+ k: number;
55
+ }, options?: RPCOptions): Promise<VectorIndexHit[][]>;
56
+ /**
57
+ * Removes ids; each boolean tells whether that id was present. Ids are
58
+ * applied in order, so a rejection leaves the ids before the failure
59
+ * removed and `length` reporting the last successful call.
60
+ */
61
+ remove(params: VectorIndexIdsParams, options?: RPCOptions): Promise<boolean[]>;
62
+ /** Reports, per id, whether the index holds it. */
63
+ contains(params: VectorIndexIdsParams, options?: RPCOptions): Promise<boolean[]>;
64
+ /**
65
+ * Writes a checksummed snapshot to `path`, replacing any existing file.
66
+ * An absolute path is used as given; a relative path resolves under the
67
+ * QVAC data directory. Load it later with `loadVectorIndex`.
68
+ * @returns The resolved absolute path.
69
+ */
70
+ write(params: VectorIndexWriteParams, options?: RPCOptions): Promise<{
71
+ path: string;
72
+ }>;
73
+ /** Releases worker memory. Safe to call more than once. */
74
+ dispose(options?: RPCOptions): Promise<void>;
75
+ [Symbol.asyncDispose](): Promise<void>;
76
+ }
77
+ /**
78
+ * Builds the two public functions over a transport. The default export pair
79
+ * below binds them to the engine dispatcher; tests bind a fake instead.
80
+ */
81
+ export declare function createVectorIndexClient(transport: typeof send): {
82
+ createVectorIndex(params: CreateVectorIndexParams, options?: RPCOptions): Promise<VectorIndex>;
83
+ loadVectorIndex(params: LoadVectorIndexParams, options?: RPCOptions): Promise<VectorIndex>;
84
+ };
85
+ /**
86
+ * Creates an empty vector index in worker memory and returns a handle to it.
87
+ *
88
+ * The index is backed by the native TurboVec engine of the registered
89
+ * embedding plugin (the built-in llama.cpp embedding plugin provides it).
90
+ * Pair it with `embed()` to build retrieval over documents kept in any store:
91
+ * add each document's embedding under an id of your choosing, then search
92
+ * with the embedding of a query and map the returned ids back to your
93
+ * documents.
94
+ *
95
+ * @param params - Index parameters
96
+ * @param params.dim - Vector dimensionality, for example 1024 for GTE Large. TurboVec storage needs a multiple of 8 no greater than 1024.
97
+ * @param params.storage - Storage mode from `VectorIndexStorage`; defaults to `TURBOVEC_Q4`. `TURBOVEC_Q2` halves memory again at lower recall; `F32`, `Q8`, and `Q4` are exact or generically quantised stores for dimensions TurboVec cannot hold.
98
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
99
+ * @returns A handle whose methods add, search, remove, snapshot, and dispose the index.
100
+ * @throws {VectorIndexProviderUnavailableError} When no registered plugin exposes a vector index provider
101
+ * @throws {VectorIndexFailedError} When the native index rejects the dimension or storage mode
102
+ *
103
+ * @example
104
+ * ```typescript
105
+ * const documents = new Map([
106
+ * ['1', 'Saturn moon Titan has lakes of liquid methane.'],
107
+ * ['2', 'Solar panels turn sunlight into electricity.']
108
+ * ])
109
+ * const { embedding } = await embed({ modelId, text: [...documents.values()] })
110
+ *
111
+ * await using index = await createVectorIndex({ dim: embedding[0].length })
112
+ * await index.add({ ids: [...documents.keys()], vectors: embedding })
113
+ *
114
+ * const { embedding: query } = await embed({ modelId, text: 'Which moon has methane lakes?' })
115
+ * const hits = await index.search({ query, k: 1 })
116
+ * console.log(documents.get(hits[0].id))
117
+ * ```
118
+ */
119
+ export declare function createVectorIndex(params: CreateVectorIndexParams, options?: RPCOptions): Promise<VectorIndex>;
120
+ /**
121
+ * Loads a vector index snapshot written by `VectorIndex.write()` into worker
122
+ * memory and returns a handle to it.
123
+ *
124
+ * The snapshot records its dimension, storage mode, and entries, so nothing
125
+ * else needs to be supplied. Loading copies the file into memory; later
126
+ * changes are not written back until `write()` is called again.
127
+ *
128
+ * @param params - Load parameters
129
+ * @param params.path - Snapshot path. An absolute path is used as given; a relative path resolves under the QVAC data directory, the same rule `write()` applies.
130
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
131
+ * @returns A handle to the loaded index.
132
+ * @throws {VectorIndexProviderUnavailableError} When no registered plugin exposes a vector index provider
133
+ * @throws {VectorIndexFailedError} When the file is missing, corrupt, or not a vector index snapshot
134
+ *
135
+ * @example
136
+ * ```typescript
137
+ * const index = await loadVectorIndex({ path: 'indexes/articles.qvi' })
138
+ * const hits = await index.search({ query, k: 5 })
139
+ * await index.dispose()
140
+ * ```
141
+ */
142
+ export declare function loadVectorIndex(params: LoadVectorIndexParams, options?: RPCOptions): Promise<VectorIndex>;
@@ -0,0 +1,168 @@
1
+ import { send } from '../dispatch.js';
2
+ import { DEFAULT_VECTOR_INDEX_STORAGE, findVectorRowLengthMismatch, toWireVectorIds } from '../schemas/index.js';
3
+ import { InvalidOperationError, InvalidResponseError, RequestValidationFailedError } from '../errors/index.js';
4
+ /**
5
+ * Builds the two public functions over a transport. The default export pair
6
+ * below binds them to the engine dispatcher; tests bind a fake instead.
7
+ */
8
+ export function createVectorIndexClient(transport) {
9
+ async function call(request, options) {
10
+ const response = await transport(request, options);
11
+ if (response.type !== 'vectorIndex') {
12
+ throw new InvalidResponseError('vectorIndex');
13
+ }
14
+ if (response.operation !== request.operation) {
15
+ throw new InvalidOperationError();
16
+ }
17
+ return response;
18
+ }
19
+ function createHandle(opened) {
20
+ const { indexId, dim, storage } = opened;
21
+ let length = opened.length;
22
+ let disposed = false;
23
+ // Row lengths are checked here so a mismatch fails before any request is
24
+ // sent and before the worker touches native memory.
25
+ function assertRows(rows, label) {
26
+ const mismatch = findVectorRowLengthMismatch(rows, dim);
27
+ if (mismatch === -1)
28
+ return;
29
+ throw new RequestValidationFailedError(`${label}[${mismatch}] has ${rows[mismatch]?.length ?? 0} components, expected ${dim}`);
30
+ }
31
+ // The flag is set only after the worker confirms, so a failed dispose
32
+ // can be retried instead of leaking the index until worker shutdown.
33
+ async function dispose(options) {
34
+ if (disposed)
35
+ return;
36
+ await call({ type: 'vectorIndex', operation: 'dispose', indexId }, options);
37
+ disposed = true;
38
+ }
39
+ async function search(params, options) {
40
+ const queries = 'queries' in params ? params.queries : [params.query];
41
+ assertRows(queries, 'queries');
42
+ const response = await call({ type: 'vectorIndex', operation: 'search', indexId, queries, k: params.k }, options);
43
+ return 'queries' in params ? response.results : (response.results[0] ?? []);
44
+ }
45
+ const handle = {
46
+ indexId,
47
+ dim,
48
+ storage,
49
+ get length() {
50
+ return length;
51
+ },
52
+ async add(params, options) {
53
+ assertRows(params.vectors, 'vectors');
54
+ const response = await call({
55
+ type: 'vectorIndex',
56
+ operation: 'add',
57
+ indexId,
58
+ ids: toWireVectorIds(params.ids),
59
+ vectors: params.vectors
60
+ }, options);
61
+ length = response.length;
62
+ return { length };
63
+ },
64
+ search,
65
+ async remove(params, options) {
66
+ const response = await call({ type: 'vectorIndex', operation: 'remove', indexId, ids: toWireVectorIds(params.ids) }, options);
67
+ length = response.length;
68
+ return response.removed;
69
+ },
70
+ async contains(params, options) {
71
+ const response = await call({ type: 'vectorIndex', operation: 'contains', indexId, ids: toWireVectorIds(params.ids) }, options);
72
+ return response.present;
73
+ },
74
+ async write(params, options) {
75
+ const response = await call({ type: 'vectorIndex', operation: 'write', indexId, path: params.path }, options);
76
+ return { path: response.path };
77
+ },
78
+ dispose
79
+ };
80
+ // Older runtimes without explicit resource management have no symbol to
81
+ // key the method on; `dispose()` remains available there.
82
+ if (typeof Symbol.asyncDispose === 'symbol') {
83
+ Object.defineProperty(handle, Symbol.asyncDispose, {
84
+ value: () => dispose(),
85
+ enumerable: false
86
+ });
87
+ }
88
+ return handle;
89
+ }
90
+ return {
91
+ async createVectorIndex(params, options) {
92
+ const response = await call({
93
+ type: 'vectorIndex',
94
+ operation: 'create',
95
+ dim: params.dim,
96
+ storage: params.storage ?? DEFAULT_VECTOR_INDEX_STORAGE
97
+ }, options);
98
+ return createHandle(response);
99
+ },
100
+ async loadVectorIndex(params, options) {
101
+ const response = await call({ type: 'vectorIndex', operation: 'load', path: params.path }, options);
102
+ return createHandle(response);
103
+ }
104
+ };
105
+ }
106
+ const client = createVectorIndexClient(send);
107
+ /**
108
+ * Creates an empty vector index in worker memory and returns a handle to it.
109
+ *
110
+ * The index is backed by the native TurboVec engine of the registered
111
+ * embedding plugin (the built-in llama.cpp embedding plugin provides it).
112
+ * Pair it with `embed()` to build retrieval over documents kept in any store:
113
+ * add each document's embedding under an id of your choosing, then search
114
+ * with the embedding of a query and map the returned ids back to your
115
+ * documents.
116
+ *
117
+ * @param params - Index parameters
118
+ * @param params.dim - Vector dimensionality, for example 1024 for GTE Large. TurboVec storage needs a multiple of 8 no greater than 1024.
119
+ * @param params.storage - Storage mode from `VectorIndexStorage`; defaults to `TURBOVEC_Q4`. `TURBOVEC_Q2` halves memory again at lower recall; `F32`, `Q8`, and `Q4` are exact or generically quantised stores for dimensions TurboVec cannot hold.
120
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
121
+ * @returns A handle whose methods add, search, remove, snapshot, and dispose the index.
122
+ * @throws {VectorIndexProviderUnavailableError} When no registered plugin exposes a vector index provider
123
+ * @throws {VectorIndexFailedError} When the native index rejects the dimension or storage mode
124
+ *
125
+ * @example
126
+ * ```typescript
127
+ * const documents = new Map([
128
+ * ['1', 'Saturn moon Titan has lakes of liquid methane.'],
129
+ * ['2', 'Solar panels turn sunlight into electricity.']
130
+ * ])
131
+ * const { embedding } = await embed({ modelId, text: [...documents.values()] })
132
+ *
133
+ * await using index = await createVectorIndex({ dim: embedding[0].length })
134
+ * await index.add({ ids: [...documents.keys()], vectors: embedding })
135
+ *
136
+ * const { embedding: query } = await embed({ modelId, text: 'Which moon has methane lakes?' })
137
+ * const hits = await index.search({ query, k: 1 })
138
+ * console.log(documents.get(hits[0].id))
139
+ * ```
140
+ */
141
+ export function createVectorIndex(params, options) {
142
+ return client.createVectorIndex(params, options);
143
+ }
144
+ /**
145
+ * Loads a vector index snapshot written by `VectorIndex.write()` into worker
146
+ * memory and returns a handle to it.
147
+ *
148
+ * The snapshot records its dimension, storage mode, and entries, so nothing
149
+ * else needs to be supplied. Loading copies the file into memory; later
150
+ * changes are not written back until `write()` is called again.
151
+ *
152
+ * @param params - Load parameters
153
+ * @param params.path - Snapshot path. An absolute path is used as given; a relative path resolves under the QVAC data directory, the same rule `write()` applies.
154
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
155
+ * @returns A handle to the loaded index.
156
+ * @throws {VectorIndexProviderUnavailableError} When no registered plugin exposes a vector index provider
157
+ * @throws {VectorIndexFailedError} When the file is missing, corrupt, or not a vector index snapshot
158
+ *
159
+ * @example
160
+ * ```typescript
161
+ * const index = await loadVectorIndex({ path: 'indexes/articles.qvi' })
162
+ * const hits = await index.search({ query, k: 5 })
163
+ * await index.dispose()
164
+ * ```
165
+ */
166
+ export function loadVectorIndex(params, options) {
167
+ return client.loadVectorIndex(params, options);
168
+ }
@@ -45,9 +45,9 @@ import { type WorldSceneResult, type WorldSceneResultWithPack, type WorldStepRes
45
45
  * modelSrc: ABOT_WORLD_0_5B_Q8_0,
46
46
  * modelConfig: {
47
47
  * mode: "world",
48
- * taehvModelSrc: ABOT_WORLD_0_5B_LF_VAE,
48
+ * taehvModelSrc: ABOT_WORLD_0_5B_LF_TAEHV_VAE,
49
49
  * t5XxlModelSrc: UMT5_XXL_ENC_Q8_0,
50
- * vaeModelSrc: ABOT_WORLD_0_5B_LF_VAE_F16,
50
+ * vaeModelSrc: ABOT_WORLD_0_5B_LF_WAN_VAE,
51
51
  * world: { seed: 42, kvCache: true },
52
52
  * },
53
53
  * });
@@ -293,6 +293,18 @@ export declare class RAGWorkspaceInUseError extends QvacErrorBase {
293
293
  export declare class RAGWorkspaceNotOpenError extends QvacErrorBase {
294
294
  constructor(workspace: string, cause?: unknown);
295
295
  }
296
+ export declare class VectorIndexProviderUnavailableError extends QvacErrorBase {
297
+ constructor(cause?: unknown);
298
+ }
299
+ export declare class VectorIndexNotFoundError extends QvacErrorBase {
300
+ constructor(indexId: string, cause?: unknown);
301
+ }
302
+ export declare class VectorIndexInvalidVectorsError extends QvacErrorBase {
303
+ constructor(details: string, cause?: unknown);
304
+ }
305
+ export declare class VectorIndexFailedError extends QvacErrorBase {
306
+ constructor(details: string, cause?: unknown);
307
+ }
296
308
  export declare class FileNotFoundError extends QvacErrorBase {
297
309
  constructor(path: string, cause?: unknown);
298
310
  }
@@ -472,6 +472,27 @@ export class RAGWorkspaceNotOpenError extends QvacErrorBase {
472
472
  super(createErrorOptions(ERROR_CODES.RAG_WORKSPACE_NOT_OPEN, [workspace], cause));
473
473
  }
474
474
  }
475
+ // ============== Vector index ==============
476
+ export class VectorIndexProviderUnavailableError extends QvacErrorBase {
477
+ constructor(cause) {
478
+ super(createErrorOptions(ERROR_CODES.VECTOR_INDEX_PROVIDER_UNAVAILABLE, undefined, cause));
479
+ }
480
+ }
481
+ export class VectorIndexNotFoundError extends QvacErrorBase {
482
+ constructor(indexId, cause) {
483
+ super(createErrorOptions(ERROR_CODES.VECTOR_INDEX_NOT_FOUND, [indexId], cause));
484
+ }
485
+ }
486
+ export class VectorIndexInvalidVectorsError extends QvacErrorBase {
487
+ constructor(details, cause) {
488
+ super(createErrorOptions(ERROR_CODES.VECTOR_INDEX_INVALID_VECTORS, [details], cause));
489
+ }
490
+ }
491
+ export class VectorIndexFailedError extends QvacErrorBase {
492
+ constructor(details, cause) {
493
+ super(createErrorOptions(ERROR_CODES.VECTOR_INDEX_FAILED, [details], cause));
494
+ }
495
+ }
475
496
  // ============== Download / resource ==============
476
497
  export class FileNotFoundError extends QvacErrorBase {
477
498
  constructor(path, cause) {