@qvac/sdk 0.23.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (239) hide show
  1. package/NOTICE +115 -58
  2. package/README.md +10 -13
  3. package/dist/examples/asr/parakeet-sortformer.js +24 -14
  4. package/dist/examples/asr/parakeet-transcribepsy-filesystem.js +40 -11
  5. package/dist/examples/asr/parakeet-unified-coreml.js +14 -9
  6. package/dist/examples/asr/whispercpp-prompt.js +9 -5
  7. package/dist/examples/assess-model-fit.d.ts +7 -9
  8. package/dist/examples/assess-model-fit.js +22 -43
  9. package/dist/examples/calc-tokens.d.ts +2 -0
  10. package/dist/examples/calc-tokens.js +21 -0
  11. package/dist/examples/classification/classify-image.js +11 -5
  12. package/dist/examples/completion-stop-reason.d.ts +3 -3
  13. package/dist/examples/completion-stop-reason.js +4 -4
  14. package/dist/examples/diffusion-flux3-klein.d.ts +2 -0
  15. package/dist/examples/diffusion-flux3-klein.js +102 -0
  16. package/dist/examples/diffusion-moss-image.d.ts +2 -0
  17. package/dist/examples/diffusion-moss-image.js +126 -0
  18. package/dist/examples/diffusion-qwen-image-21.js +15 -4
  19. package/dist/examples/embed-multimodal.d.ts +2 -0
  20. package/dist/examples/embed-multimodal.js +80 -0
  21. package/dist/examples/embed-p2p.js +2 -2
  22. package/dist/examples/image/megaloc.d.ts +2 -0
  23. package/dist/examples/image/megaloc.js +37 -0
  24. package/dist/examples/llamacpp-multimodal.js +18 -0
  25. package/dist/examples/rag/rag-hyperdb/pipeline.js +2 -2
  26. package/dist/examples/rag/rag-turbovec.js +2 -2
  27. package/dist/examples/sessions.d.ts +17 -0
  28. package/dist/examples/sessions.js +63 -0
  29. package/dist/examples/tools/llamacpp-deferred-tools.js +8 -4
  30. package/dist/scripts/check-resource-collectors-packaging.js +7 -6
  31. package/dist/scripts/contract/build-contract.d.ts +2 -1
  32. package/dist/scripts/contract/build-contract.js +13 -1
  33. package/dist/scripts/contract/constants-registry.d.ts +17 -0
  34. package/dist/scripts/contract/constants-registry.js +8 -2
  35. package/dist/scripts/contract/method-shapes.d.ts +4 -0
  36. package/dist/scripts/contract/method-shapes.js +4 -0
  37. package/dist/scripts/enforce-inference-versions.d.ts +1 -1
  38. package/dist/scripts/enforce-inference-versions.js +28 -18
  39. package/dist/scripts/generate-bare-kit-runtimes.js +101 -69
  40. package/dist/src/client/api/assess-model-fit.d.ts +17 -17
  41. package/dist/src/client/api/assess-model-fit.js +18 -31
  42. package/dist/src/client/api/audio-edit.d.ts +5 -3
  43. package/dist/src/client/api/audio-edit.js +5 -3
  44. package/dist/src/client/api/audio-gen-result.js +134 -45
  45. package/dist/src/client/api/audio-gen.d.ts +40 -3
  46. package/dist/src/client/api/audio-gen.js +40 -3
  47. package/dist/src/client/api/audio-understand.d.ts +2 -2
  48. package/dist/src/client/api/audio-understand.js +2 -2
  49. package/dist/src/client/api/batch-completion.js +2 -1
  50. package/dist/src/client/api/calc-tokens.d.ts +33 -0
  51. package/dist/src/client/api/calc-tokens.js +44 -0
  52. package/dist/src/client/api/cancel.d.ts +2 -2
  53. package/dist/src/client/api/cancel.js +2 -2
  54. package/dist/src/client/api/classify.d.ts +12 -5
  55. package/dist/src/client/api/classify.js +17 -5
  56. package/dist/src/client/api/client-request-id.d.ts +0 -15
  57. package/dist/src/client/api/client-request-id.js +15 -12
  58. package/dist/src/client/api/completion-stream.d.ts +8 -1
  59. package/dist/src/client/api/completion-stream.js +10 -1
  60. package/dist/src/client/api/delete-cache.d.ts +9 -2
  61. package/dist/src/client/api/delete-cache.js +13 -3
  62. package/dist/src/client/api/diffusion.d.ts +20 -4
  63. package/dist/src/client/api/diffusion.js +23 -5
  64. package/dist/src/client/api/embed.d.ts +82 -29
  65. package/dist/src/client/api/embed.js +64 -19
  66. package/dist/src/client/api/get-model-info.d.ts +2 -2
  67. package/dist/src/client/api/get-model-info.js +2 -2
  68. package/dist/src/client/api/get-system-resources.d.ts +2 -2
  69. package/dist/src/client/api/get-system-resources.js +2 -2
  70. package/dist/src/client/api/heartbeat.d.ts +3 -2
  71. package/dist/src/client/api/heartbeat.js +3 -2
  72. package/dist/src/client/api/index.d.ts +4 -3
  73. package/dist/src/client/api/index.js +2 -1
  74. package/dist/src/client/api/invoke-plugin.d.ts +8 -2
  75. package/dist/src/client/api/invoke-plugin.js +17 -2
  76. package/dist/src/client/api/load-model.js +5 -2
  77. package/dist/src/client/api/ocr.d.ts +5 -3
  78. package/dist/src/client/api/ocr.js +44 -21
  79. package/dist/src/client/api/rag.d.ts +1 -1
  80. package/dist/src/client/api/rag.js +1 -1
  81. package/dist/src/client/api/registry.d.ts +17 -7
  82. package/dist/src/client/api/registry.js +37 -12
  83. package/dist/src/client/api/resume.d.ts +2 -1
  84. package/dist/src/client/api/resume.js +2 -2
  85. package/dist/src/client/api/rpc-server.d.ts +4 -4
  86. package/dist/src/client/api/rpc-server.js +10 -10
  87. package/dist/src/client/api/state.d.ts +2 -2
  88. package/dist/src/client/api/state.js +2 -2
  89. package/dist/src/client/api/subscribe-logs.d.ts +2 -2
  90. package/dist/src/client/api/subscribe-logs.js +2 -2
  91. package/dist/src/client/api/suspend.d.ts +4 -2
  92. package/dist/src/client/api/suspend.js +4 -3
  93. package/dist/src/client/api/text-to-speech.d.ts +14 -5
  94. package/dist/src/client/api/text-to-speech.js +83 -29
  95. package/dist/src/client/api/transcribe.d.ts +6 -2
  96. package/dist/src/client/api/transcribe.js +7 -1
  97. package/dist/src/client/api/unload-model.d.ts +19 -7
  98. package/dist/src/client/api/unload-model.js +29 -11
  99. package/dist/src/client/api/upscale.d.ts +6 -3
  100. package/dist/src/client/api/upscale.js +9 -4
  101. package/dist/src/client/api/vector-index.d.ts +50 -16
  102. package/dist/src/client/api/vector-index.js +100 -48
  103. package/dist/src/client/api/video-request.d.ts +5 -5
  104. package/dist/src/client/api/video.d.ts +3 -2
  105. package/dist/src/client/api/video.js +3 -2
  106. package/dist/src/client/api/vla.d.ts +9 -5
  107. package/dist/src/client/api/vla.js +17 -8
  108. package/dist/src/client/api/world.d.ts +5 -5
  109. package/dist/src/client/api/world.js +4 -4
  110. package/dist/src/client/init-hooks.d.ts +6 -4
  111. package/dist/src/client/init-hooks.js +12 -15
  112. package/dist/src/client/logging-stream-registry.d.ts +6 -3
  113. package/dist/src/client/logging-stream-registry.js +31 -12
  114. package/dist/src/client/rpc/bundle-stamp.d.ts +29 -0
  115. package/dist/src/client/rpc/bundle-stamp.js +75 -0
  116. package/dist/src/client/rpc/expo-home-dir.d.ts +2 -0
  117. package/dist/src/client/rpc/expo-home-dir.js +4 -0
  118. package/dist/src/client/rpc/expo-rpc-client.js +189 -135
  119. package/dist/src/client/rpc/node-rpc-client.js +322 -413
  120. package/dist/src/client/rpc/pear-runtime.d.ts +12 -0
  121. package/dist/src/client/rpc/pear-runtime.js +12 -0
  122. package/dist/src/client/rpc/rpc-client.d.ts +5 -4
  123. package/dist/src/client/rpc/rpc-client.js +126 -23
  124. package/dist/src/client/rpc/rpc-error.js +21 -2
  125. package/dist/src/client/rpc/unbundled-harness.d.ts +16 -0
  126. package/dist/src/client/rpc/unbundled-harness.js +27 -0
  127. package/dist/src/client/rpc/worker-failure.d.ts +27 -0
  128. package/dist/src/client/rpc/worker-failure.js +61 -0
  129. package/dist/src/client/session-registry.d.ts +75 -0
  130. package/dist/src/client/session-registry.js +149 -0
  131. package/dist/src/client/session.d.ts +125 -0
  132. package/dist/src/client/session.js +148 -0
  133. package/dist/src/commands/bundle/addons.d.ts +14 -0
  134. package/dist/src/commands/bundle/addons.js +65 -0
  135. package/dist/src/commands/bundle/constants.js +1 -0
  136. package/dist/src/commands/bundle/entry-gen.d.ts +1 -5
  137. package/dist/src/commands/bundle/entry-gen.js +17 -50
  138. package/dist/src/commands/bundle/index.d.ts +59 -13
  139. package/dist/src/commands/bundle/index.js +345 -121
  140. package/dist/src/commands/bundle/link.d.ts +58 -0
  141. package/dist/src/commands/bundle/link.js +135 -0
  142. package/dist/src/commands/bundle/node-support.d.ts +13 -0
  143. package/dist/src/commands/bundle/node-support.js +23 -0
  144. package/dist/src/commands/bundle/read-bundle.d.ts +9 -0
  145. package/dist/src/commands/bundle/read-bundle.js +27 -0
  146. package/dist/src/commands/bundle/resolve-sdk-import.d.ts +6 -0
  147. package/dist/src/commands/bundle/resolve-sdk-import.js +24 -28
  148. package/dist/src/commands/bundle/scratch.d.ts +35 -0
  149. package/dist/src/commands/bundle/scratch.js +178 -0
  150. package/dist/src/commands/bundle/targets.d.ts +14 -0
  151. package/dist/src/commands/bundle/targets.js +37 -0
  152. package/dist/src/commands/host-prebuilds/index.d.ts +5 -4
  153. package/dist/src/commands/host-prebuilds/index.js +9 -7
  154. package/dist/src/commands/index.d.ts +4 -3
  155. package/dist/src/commands/verify/abi.d.ts +20 -14
  156. package/dist/src/commands/verify/abi.js +11 -79
  157. package/dist/src/commands/verify/bare-kit-runtime.d.ts +20 -22
  158. package/dist/src/commands/verify/bare-kit-runtime.js +102 -150
  159. package/dist/src/commands/verify/bare-kit-runtimes.d.ts +10 -9
  160. package/dist/src/commands/verify/bare-kit-runtimes.js +21 -21
  161. package/dist/src/commands/verify/bundle-source.js +25 -21
  162. package/dist/src/commands/verify/engines-advice.d.ts +2 -8
  163. package/dist/src/commands/verify/engines-advice.js +7 -54
  164. package/dist/src/commands/verify/index.d.ts +30 -29
  165. package/dist/src/commands/verify/index.js +92 -200
  166. package/dist/src/commands/verify/prebuilds.d.ts +3 -5
  167. package/dist/src/commands/verify/prebuilds.js +1 -2
  168. package/dist/src/commands/verify/resource-collectors.d.ts +0 -6
  169. package/dist/src/commands/verify/resource-collectors.js +1 -50
  170. package/dist/src/commands/verify/sidecar-runtime.d.ts +6 -0
  171. package/dist/src/commands/verify/sidecar-runtime.js +51 -0
  172. package/dist/src/expo/plugins/withBareKit.d.ts +59 -0
  173. package/dist/src/expo/plugins/withBareKit.js +204 -0
  174. package/dist/src/expo/plugins/withMobileBundle.d.ts +4 -11
  175. package/dist/src/expo/plugins/withMobileBundle.js +36 -57
  176. package/dist/src/expo/plugins/withQvacSDK.d.ts +1 -0
  177. package/dist/src/expo/plugins/withQvacSDK.js +3 -0
  178. package/dist/src/index.d.ts +6 -5
  179. package/dist/src/index.js +10 -14
  180. package/dist/src/logging/utils.js +10 -2
  181. package/dist/src/plugin-ids.d.ts +2 -1
  182. package/dist/src/plugin-ids.js +2 -0
  183. package/dist/src/schemas/public.d.ts +1 -1
  184. package/dist/src/schemas/public.js +1 -1
  185. package/dist/src/schemas/sdk-errors-client.d.ts +5 -6
  186. package/dist/src/schemas/sdk-errors-client.js +30 -36
  187. package/dist/src/schemas/sdk-errors-server.d.ts +11 -1
  188. package/dist/src/schemas/sdk-errors-server.js +60 -2
  189. package/dist/src/server/rpc/rpc-utils.d.ts +25 -4
  190. package/dist/src/server/rpc/rpc-utils.js +39 -5
  191. package/dist/src/utils/errors-client.d.ts +37 -29
  192. package/dist/src/utils/errors-client.js +50 -41
  193. package/dist/src/utils/errors-server.d.ts +59 -1
  194. package/dist/src/utils/errors-server.js +110 -1
  195. package/dist/src/utils/withTimeout.js +34 -17
  196. package/dist/src/worker/handle-request.js +25 -22
  197. package/dist/src/worker/handler-utils.d.ts +2 -6
  198. package/dist/src/worker/handler-utils.js +2 -20
  199. package/dist/src/worker/index.d.ts +2 -4
  200. package/dist/src/worker/index.js +23 -35
  201. package/dist/src/worker/plugins/ggml-image-embedding.d.ts +2 -0
  202. package/dist/src/worker/plugins/ggml-image-embedding.js +1 -0
  203. package/dist/src/worker/shim.d.ts +4 -0
  204. package/dist/src/worker/shim.js +7 -0
  205. package/dist/src/worker/start.d.ts +9 -0
  206. package/dist/src/worker/start.js +16 -0
  207. package/dist/src/worker/unbundled-shim.d.ts +2 -0
  208. package/dist/src/worker/unbundled-shim.js +4 -0
  209. package/docs/system-resources-support-matrix.md +27 -19
  210. package/package.json +62 -51
  211. package/src/electron-forge/index.cjs +65 -91
  212. package/dist/examples/model-fit-ui/server.d.ts +0 -24
  213. package/dist/examples/model-fit-ui/server.js +0 -221
  214. package/dist/src/client/rpc/ensure-worker-ready.d.ts +0 -9
  215. package/dist/src/client/rpc/ensure-worker-ready.js +0 -17
  216. package/dist/src/client/rpc/init-timeout.d.ts +0 -26
  217. package/dist/src/client/rpc/init-timeout.js +0 -25
  218. package/dist/src/client/rpc/ipc-socket-path.d.ts +0 -11
  219. package/dist/src/client/rpc/ipc-socket-path.js +0 -30
  220. package/dist/src/client/rpc/worker-startup-error.d.ts +0 -12
  221. package/dist/src/client/rpc/worker-startup-error.js +0 -13
  222. package/dist/src/commands/bundle/bare-pack.d.ts +0 -21
  223. package/dist/src/commands/bundle/bare-pack.js +0 -77
  224. package/dist/src/commands/bundle/manifest.d.ts +0 -25
  225. package/dist/src/commands/bundle/manifest.js +0 -192
  226. package/dist/src/expo/plugins/link-addons.d.ts +0 -18
  227. package/dist/src/expo/plugins/link-addons.js +0 -65
  228. package/dist/src/pear/pre.d.ts +0 -21
  229. package/dist/src/pear/pre.js +0 -450
  230. package/dist/src/server/env.d.ts +0 -22
  231. package/dist/src/server/env.js +0 -59
  232. package/dist/src/server/utils/qvac-paths.d.ts +0 -2
  233. package/dist/src/server/utils/qvac-paths.js +0 -5
  234. package/dist/src/server/utils/worker-lock.d.ts +0 -3
  235. package/dist/src/server/utils/worker-lock.js +0 -67
  236. package/dist/src/worker/create-server.d.ts +0 -8
  237. package/dist/src/worker/create-server.js +0 -51
  238. package/dist/src/worker/lifecycle.d.ts +0 -23
  239. package/dist/src/worker/lifecycle.js +0 -149
@@ -1,5 +1,6 @@
1
1
  import { ocrStreamResponseSchema } from '@qvac/inference/surface';
2
2
  import { stream as streamRpc } from '../../client/rpc/rpc-client.js';
3
+ import { generateClientRequestId } from '../../client/api/client-request-id.js';
3
4
  /**
4
5
  * Performs Optical Character Recognition (OCR) on an image to extract text.
5
6
  *
@@ -8,7 +9,8 @@ import { stream as streamRpc } from '../../client/rpc/rpc-client.js';
8
9
  * @param params.image - Image input as either a file path (string) or image buffer
9
10
  * @param params.options - Optional OCR options (e.g., paragraph mode)
10
11
  * @param params.stream - Whether to stream blocks as they're detected (true) or return all at once (false). Defaults to false
11
- * @returns Object with blockStream generator, blocks promise, and stats promise
12
+ * @param options - Optional RPC options (timeout, profiling, force new connection).
13
+ * @returns Object with `requestId` (pass to `cancel({ requestId })`), blockStream generator, blocks promise, and stats promise
12
14
  * @example
13
15
  * ```typescript
14
16
  * // Load an OCR model first. Registry GGUF models resolve their pipeline
@@ -33,9 +35,11 @@ import { stream as streamRpc } from '../../client/rpc/rpc-client.js';
33
35
  * }
34
36
  * ```
35
37
  */
36
- export function ocr(params) {
38
+ export function ocr(params, options) {
39
+ const requestId = generateClientRequestId();
37
40
  const request = {
38
41
  type: 'ocrStream',
42
+ requestId,
39
43
  modelId: params.modelId,
40
44
  image: typeof params.image === 'string'
41
45
  ? { type: 'filePath', value: params.image }
@@ -44,25 +48,37 @@ export function ocr(params) {
44
48
  };
45
49
  let ocrStats;
46
50
  let statsResolver = () => { };
47
- const statsPromise = new Promise((resolve) => {
51
+ let statsRejecter = () => { };
52
+ const statsPromise = new Promise((resolve, reject) => {
48
53
  statsResolver = resolve;
54
+ statsRejecter = reject;
49
55
  });
56
+ // A failed stream (a cancel, a timeout, a worker error) sends no `done`
57
+ // frame, so it rejects `stats` too instead of leaving it pending.
58
+ statsPromise.catch(() => { });
50
59
  if (params.stream) {
51
60
  const blockStream = (async function* () {
52
- for await (const response of streamRpc(request)) {
53
- if (response.type === 'ocrStream') {
54
- const streamResponse = ocrStreamResponseSchema.parse(response);
55
- if (streamResponse.blocks && streamResponse.blocks.length > 0) {
56
- yield streamResponse.blocks;
57
- }
58
- if (streamResponse.done) {
59
- ocrStats = streamResponse.stats;
60
- statsResolver(ocrStats);
61
+ try {
62
+ for await (const response of streamRpc(request, options)) {
63
+ if (response.type === 'ocrStream') {
64
+ const streamResponse = ocrStreamResponseSchema.parse(response);
65
+ if (streamResponse.blocks && streamResponse.blocks.length > 0) {
66
+ yield streamResponse.blocks;
67
+ }
68
+ if (streamResponse.done) {
69
+ ocrStats = streamResponse.stats;
70
+ statsResolver(ocrStats);
71
+ }
61
72
  }
62
73
  }
63
74
  }
75
+ catch (error) {
76
+ statsRejecter(error);
77
+ throw error;
78
+ }
64
79
  })();
65
80
  return {
81
+ requestId,
66
82
  blockStream,
67
83
  blocks: Promise.resolve([]),
68
84
  stats: statsPromise
@@ -74,21 +90,28 @@ export function ocr(params) {
74
90
  })();
75
91
  const blocksPromise = (async () => {
76
92
  let allBlocks = [];
77
- for await (const response of streamRpc(request)) {
78
- if (response.type === 'ocrStream') {
79
- const streamResponse = ocrStreamResponseSchema.parse(response);
80
- if (streamResponse.blocks) {
81
- allBlocks = allBlocks.concat(streamResponse.blocks);
82
- }
83
- if (streamResponse.done) {
84
- ocrStats = streamResponse.stats;
85
- statsResolver(ocrStats);
93
+ try {
94
+ for await (const response of streamRpc(request, options)) {
95
+ if (response.type === 'ocrStream') {
96
+ const streamResponse = ocrStreamResponseSchema.parse(response);
97
+ if (streamResponse.blocks) {
98
+ allBlocks = allBlocks.concat(streamResponse.blocks);
99
+ }
100
+ if (streamResponse.done) {
101
+ ocrStats = streamResponse.stats;
102
+ statsResolver(ocrStats);
103
+ }
86
104
  }
87
105
  }
88
106
  }
107
+ catch (error) {
108
+ statsRejecter(error);
109
+ throw error;
110
+ }
89
111
  return allBlocks;
90
112
  })();
91
113
  return {
114
+ requestId,
92
115
  blockStream,
93
116
  blocks: blocksPromise,
94
117
  stats: statsPromise
@@ -84,7 +84,7 @@ export declare function ragIngest(params: RagIngestParams, options?: RPCOptions)
84
84
  * ```typescript
85
85
  * // Segregated flow
86
86
  * const chunks = await ragChunk({ documents: ["text1", "text2"] });
87
- * const { embedding: embeddings } = await embed({ modelId, text: chunks.map(c => c.content) });
87
+ * const { embedding: embeddings } = await embedBatch({ modelId, inputs: chunks.map(c => c.content) });
88
88
  * const embeddedDocs = chunks.map((chunk, i) => ({
89
89
  * ...chunk,
90
90
  * embedding: embeddings[i],
@@ -151,7 +151,7 @@ async function runRagIngest(params, requestId, options) {
151
151
  * ```typescript
152
152
  * // Segregated flow
153
153
  * const chunks = await ragChunk({ documents: ["text1", "text2"] });
154
- * const { embedding: embeddings } = await embed({ modelId, text: chunks.map(c => c.content) });
154
+ * const { embedding: embeddings } = await embedBatch({ modelId, inputs: chunks.map(c => c.content) });
155
155
  * const embeddedDocs = chunks.map((chunk, i) => ({
156
156
  * ...chunk,
157
157
  * embedding: embeddings[i],
@@ -1,4 +1,4 @@
1
- import type { ModelRegistryEntry, ModelRegistryEntryAddon } from '@qvac/inference/surface';
1
+ import type { ModelRegistryEntry, ModelRegistryEntryAddon, RPCOptions } from '@qvac/inference/surface';
2
2
  export type { ModelRegistryEntry, ModelRegistryEntryAddon };
3
3
  export interface ModelRegistrySearchParams {
4
4
  filter?: string;
@@ -7,13 +7,19 @@ export interface ModelRegistrySearchParams {
7
7
  modelType?: ModelRegistryEntryAddon;
8
8
  addon?: ModelRegistryEntryAddon;
9
9
  }
10
+ /** A registry query's result, with the id that `cancel({ requestId })` takes. */
11
+ export type RegistryQuery<T> = Promise<T> & {
12
+ requestId: string;
13
+ };
10
14
  /**
11
15
  * Returns all available models from the QVAC distributed model registry.
12
16
  *
13
- * @returns A promise resolving to an array of `ModelRegistryEntry` describing every model the SDK's connected registry knows about.
17
+ * @returns A promise resolving to an array of `ModelRegistryEntry` describing every model the SDK's connected registry knows about,
18
+ * decorated with a synchronous `requestId` for `cancel({ requestId })` while the query waits for the registry.
19
+ * @throws {ModelRegistryBusyError} When another QVAC process kept the registry for longer than the query waits.
14
20
  * @throws {ModelRegistryQueryFailedError} When the registry query fails.
15
21
  */
16
- declare function modelRegistryList(): Promise<ModelRegistryEntry[]>;
22
+ declare function modelRegistryList(options?: RPCOptions): RegistryQuery<ModelRegistryEntry[]>;
17
23
  /**
18
24
  * Searches the model registry with optional filters for model type, engine, and quantization.
19
25
  *
@@ -23,19 +29,23 @@ declare function modelRegistryList(): Promise<ModelRegistryEntry[]>;
23
29
  * @param params.quantization - Quantization identifier (e.g., `"Q4_K_M"`).
24
30
  * @param params.modelType - Alias for `addon`; kept for backward compatibility.
25
31
  * @param params.addon - Model addon / category to restrict results to.
26
- * @returns A promise resolving to the matching `ModelRegistryEntry` entries.
32
+ * @returns A promise resolving to the matching `ModelRegistryEntry` entries, decorated with a
33
+ * synchronous `requestId` for `cancel({ requestId })` while the query waits for the registry.
34
+ * @throws {ModelRegistryBusyError} When another QVAC process kept the registry for longer than the query waits.
27
35
  * @throws {ModelRegistryQueryFailedError} When the registry query fails.
28
36
  */
29
- declare function modelRegistrySearch(params?: ModelRegistrySearchParams): Promise<ModelRegistryEntry[]>;
37
+ declare function modelRegistrySearch(params?: ModelRegistrySearchParams, options?: RPCOptions): RegistryQuery<ModelRegistryEntry[]>;
30
38
  /**
31
39
  * Fetches a single model entry from the registry by its path and source.
32
40
  *
33
41
  * @param registryPath - Registry-relative path of the model to fetch.
34
42
  * @param registrySource - Registry source identifier (e.g., `"huggingface"`, `"local"`).
35
- * @returns A promise resolving to the matching `ModelRegistryEntry`.
43
+ * @returns A promise resolving to the matching `ModelRegistryEntry`, decorated with a
44
+ * synchronous `requestId` for `cancel({ requestId })` while the query waits for the registry.
36
45
  * @throws {ModelRegistryModelNotFoundError} When the registry has no model at this source and path.
46
+ * @throws {ModelRegistryBusyError} When another QVAC process kept the registry for longer than the query waits.
37
47
  * @throws {ModelRegistryQueryFailedError} When the registry query fails.
38
48
  */
39
- declare function modelRegistryGetModel(registryPath: string, registrySource: string): Promise<ModelRegistryEntry>;
49
+ declare function modelRegistryGetModel(registryPath: string, registrySource: string, options?: RPCOptions): RegistryQuery<ModelRegistryEntry>;
40
50
  export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel };
41
51
  //# sourceMappingURL=registry.d.ts.map
@@ -1,5 +1,7 @@
1
1
  import { send } from '../../client/rpc/rpc-client.js';
2
2
  import { ModelRegistryQueryFailedError } from '../../utils/errors-client.js';
3
+ import { generateClientRequestId } from '../../client/api/client-request-id.js';
4
+ import { decoratePromise } from '../../utils/decorate-promise.js';
3
5
  function validateRegistryResponse(response) {
4
6
  if (!response.success) {
5
7
  throw new ModelRegistryQueryFailedError(response.error ?? 'Unknown registry error');
@@ -8,14 +10,21 @@ function validateRegistryResponse(response) {
8
10
  /**
9
11
  * Returns all available models from the QVAC distributed model registry.
10
12
  *
11
- * @returns A promise resolving to an array of `ModelRegistryEntry` describing every model the SDK's connected registry knows about.
13
+ * @returns A promise resolving to an array of `ModelRegistryEntry` describing every model the SDK's connected registry knows about,
14
+ * decorated with a synchronous `requestId` for `cancel({ requestId })` while the query waits for the registry.
15
+ * @throws {ModelRegistryBusyError} When another QVAC process kept the registry for longer than the query waits.
12
16
  * @throws {ModelRegistryQueryFailedError} When the registry query fails.
13
17
  */
14
- async function modelRegistryList() {
18
+ function modelRegistryList(options) {
19
+ const requestId = generateClientRequestId();
20
+ return decoratePromise(runList(requestId, options), { requestId });
21
+ }
22
+ async function runList(requestId, options) {
15
23
  const request = {
16
- type: 'modelRegistryList'
24
+ type: 'modelRegistryList',
25
+ requestId
17
26
  };
18
- const response = (await send(request));
27
+ const response = (await send(request, options));
19
28
  validateRegistryResponse(response);
20
29
  return response.models;
21
30
  }
@@ -28,17 +37,24 @@ async function modelRegistryList() {
28
37
  * @param params.quantization - Quantization identifier (e.g., `"Q4_K_M"`).
29
38
  * @param params.modelType - Alias for `addon`; kept for backward compatibility.
30
39
  * @param params.addon - Model addon / category to restrict results to.
31
- * @returns A promise resolving to the matching `ModelRegistryEntry` entries.
40
+ * @returns A promise resolving to the matching `ModelRegistryEntry` entries, decorated with a
41
+ * synchronous `requestId` for `cancel({ requestId })` while the query waits for the registry.
42
+ * @throws {ModelRegistryBusyError} When another QVAC process kept the registry for longer than the query waits.
32
43
  * @throws {ModelRegistryQueryFailedError} When the registry query fails.
33
44
  */
34
- async function modelRegistrySearch(params = {}) {
45
+ function modelRegistrySearch(params = {}, options) {
46
+ const requestId = generateClientRequestId();
47
+ return decoratePromise(runSearch(params, requestId, options), { requestId });
48
+ }
49
+ async function runSearch(params, requestId, options) {
35
50
  const { modelType, ...rest } = params;
36
51
  const request = {
37
52
  type: 'modelRegistrySearch',
38
53
  ...rest,
39
- addon: modelType ?? rest.addon
54
+ addon: modelType ?? rest.addon,
55
+ requestId
40
56
  };
41
- const response = (await send(request));
57
+ const response = (await send(request, options));
42
58
  validateRegistryResponse(response);
43
59
  return response.models;
44
60
  }
@@ -47,17 +63,26 @@ async function modelRegistrySearch(params = {}) {
47
63
  *
48
64
  * @param registryPath - Registry-relative path of the model to fetch.
49
65
  * @param registrySource - Registry source identifier (e.g., `"huggingface"`, `"local"`).
50
- * @returns A promise resolving to the matching `ModelRegistryEntry`.
66
+ * @returns A promise resolving to the matching `ModelRegistryEntry`, decorated with a
67
+ * synchronous `requestId` for `cancel({ requestId })` while the query waits for the registry.
51
68
  * @throws {ModelRegistryModelNotFoundError} When the registry has no model at this source and path.
69
+ * @throws {ModelRegistryBusyError} When another QVAC process kept the registry for longer than the query waits.
52
70
  * @throws {ModelRegistryQueryFailedError} When the registry query fails.
53
71
  */
54
- async function modelRegistryGetModel(registryPath, registrySource) {
72
+ function modelRegistryGetModel(registryPath, registrySource, options) {
73
+ const requestId = generateClientRequestId();
74
+ return decoratePromise(runGetModel(registryPath, registrySource, requestId, options), {
75
+ requestId
76
+ });
77
+ }
78
+ async function runGetModel(registryPath, registrySource, requestId, options) {
55
79
  const request = {
56
80
  type: 'modelRegistryGetModel',
57
81
  registryPath,
58
- registrySource
82
+ registrySource,
83
+ requestId
59
84
  };
60
- const response = (await send(request));
85
+ const response = (await send(request, options));
61
86
  validateRegistryResponse(response);
62
87
  return response.model;
63
88
  }
@@ -1,3 +1,4 @@
1
+ import type { RPCOptions } from '@qvac/inference/surface';
1
2
  /**
2
3
  * Resumes the SDK runtime: restores all suspended Hyperswarm and Corestore
3
4
  * resources and releases the lifecycle gate so all SDK operations are allowed
@@ -23,5 +24,5 @@
23
24
  * await resume();
24
25
  * console.log(await state()); // "active"
25
26
  */
26
- export declare function resume(): Promise<void>;
27
+ export declare function resume(options?: RPCOptions): Promise<void>;
27
28
  //# sourceMappingURL=resume.d.ts.map
@@ -25,8 +25,8 @@ import { InvalidResponseError } from '../../utils/errors-client.js';
25
25
  * await resume();
26
26
  * console.log(await state()); // "active"
27
27
  */
28
- export async function resume() {
29
- const response = await send({ type: 'resume' });
28
+ export async function resume(options) {
29
+ const response = await send({ type: 'resume' }, options);
30
30
  if (response.type !== 'resume') {
31
31
  throw new InvalidResponseError('resume');
32
32
  }
@@ -1,20 +1,20 @@
1
- import { type StartRpcServerOptions, type StopRpcServerOptions, type DiscoverRpcServersOptions, type RpcServerInfo, type RpcServerCandidate } from '@qvac/inference/surface';
1
+ import { type StartRpcServerOptions, type StopRpcServerOptions, type DiscoverRpcServersOptions, type RpcServerInfo, type RpcServerCandidate, type RPCOptions } from '@qvac/inference/surface';
2
2
  /**
3
3
  * Start a worker-owned native RPC server. Non-loopback binding and advertising require explicit opt-in.
4
4
  * Cancel a pending start with its promise.requestId.
5
5
  */
6
- export declare function startRpcServer(options?: StartRpcServerOptions): Promise<RpcServerInfo> & {
6
+ export declare function startRpcServer(options?: StartRpcServerOptions, rpcOptions?: RPCOptions): Promise<RpcServerInfo> & {
7
7
  requestId: string;
8
8
  };
9
9
  /** Withdraw the announcement and await native stop. Bare stop has no deadline. */
10
- export declare function stopRpcServer(options: StopRpcServerOptions): Promise<void>;
10
+ export declare function stopRpcServer(options: StopRpcServerOptions, rpcOptions?: RPCOptions): Promise<void>;
11
11
  /**
12
12
  * Find private-network candidates with device inventories and server RDMA availability.
13
13
  * RDMA availability is a server-side offer, not a guarantee of the negotiated transport.
14
14
  * Use getRpcDeviceMap with the chosen endpoint registration order before loadModel.
15
15
  * Cancel a pending search with its promise.requestId.
16
16
  */
17
- export declare function discoverRpcServers(options: DiscoverRpcServersOptions): Promise<RpcServerCandidate[]> & {
17
+ export declare function discoverRpcServers(options: DiscoverRpcServersOptions, rpcOptions?: RPCOptions): Promise<RpcServerCandidate[]> & {
18
18
  requestId: string;
19
19
  };
20
20
  //# sourceMappingURL=rpc-server.d.ts.map
@@ -7,12 +7,12 @@ import { generateClientRequestId } from '../../client/api/client-request-id.js';
7
7
  * Start a worker-owned native RPC server. Non-loopback binding and advertising require explicit opt-in.
8
8
  * Cancel a pending start with its promise.requestId.
9
9
  */
10
- export function startRpcServer(options = {}) {
10
+ export function startRpcServer(options = {}, rpcOptions) {
11
11
  const requestId = generateClientRequestId();
12
- return decoratePromise(runStartRpcServer(options, requestId), { requestId });
12
+ return decoratePromise(runStartRpcServer(options, requestId, rpcOptions), { requestId });
13
13
  }
14
- async function runStartRpcServer(options, requestId) {
15
- const response = await send({ ...options, type: 'startRpcServer', requestId });
14
+ async function runStartRpcServer(options, requestId, rpcOptions) {
15
+ const response = await send({ ...options, type: 'startRpcServer', requestId }, rpcOptions);
16
16
  if (response.type !== 'startRpcServer')
17
17
  throw new InvalidResponseError('startRpcServer');
18
18
  return {
@@ -22,8 +22,8 @@ async function runStartRpcServer(options, requestId) {
22
22
  };
23
23
  }
24
24
  /** Withdraw the announcement and await native stop. Bare stop has no deadline. */
25
- export async function stopRpcServer(options) {
26
- const response = await send({ ...options, type: 'stopRpcServer' });
25
+ export async function stopRpcServer(options, rpcOptions) {
26
+ const response = await send({ ...options, type: 'stopRpcServer' }, rpcOptions);
27
27
  if (response.type !== 'stopRpcServer')
28
28
  throw new InvalidResponseError('stopRpcServer');
29
29
  }
@@ -33,12 +33,12 @@ export async function stopRpcServer(options) {
33
33
  * Use getRpcDeviceMap with the chosen endpoint registration order before loadModel.
34
34
  * Cancel a pending search with its promise.requestId.
35
35
  */
36
- export function discoverRpcServers(options) {
36
+ export function discoverRpcServers(options, rpcOptions) {
37
37
  const requestId = generateClientRequestId();
38
- return decoratePromise(runDiscoverRpcServers(options, requestId), { requestId });
38
+ return decoratePromise(runDiscoverRpcServers(options, requestId, rpcOptions), { requestId });
39
39
  }
40
- async function runDiscoverRpcServers(options, requestId) {
41
- const response = await send({ ...options, type: 'discoverRpcServers', requestId });
40
+ async function runDiscoverRpcServers(options, requestId, rpcOptions) {
41
+ const response = await send({ ...options, type: 'discoverRpcServers', requestId }, rpcOptions);
42
42
  if (response.type !== 'discoverRpcServers')
43
43
  throw new InvalidResponseError('discoverRpcServers');
44
44
  return response.servers;
@@ -1,4 +1,4 @@
1
- import type { LifecycleState } from '@qvac/inference/surface';
1
+ import type { LifecycleState, RPCOptions } from '@qvac/inference/surface';
2
2
  /**
3
3
  * Returns the current runtime lifecycle state.
4
4
  *
@@ -19,5 +19,5 @@ import type { LifecycleState } from '@qvac/inference/surface';
19
19
  * await resume();
20
20
  * }
21
21
  */
22
- export declare function state(): Promise<LifecycleState>;
22
+ export declare function state(options?: RPCOptions): Promise<LifecycleState>;
23
23
  //# sourceMappingURL=state.d.ts.map
@@ -20,8 +20,8 @@ import { InvalidResponseError } from '../../utils/errors-client.js';
20
20
  * await resume();
21
21
  * }
22
22
  */
23
- export async function state() {
24
- const response = await send({ type: 'state' });
23
+ export async function state(options) {
24
+ const response = await send({ type: 'state' }, options);
25
25
  if (response.type !== 'state') {
26
26
  throw new InvalidResponseError('state');
27
27
  }
@@ -1,4 +1,4 @@
1
- import type { LoggingStreamResponse } from '@qvac/inference/surface';
1
+ import type { LoggingStreamResponse, RPCOptions } from '@qvac/inference/surface';
2
2
  export type ServerLogHandler = (log: LoggingStreamResponse) => void;
3
3
  /**
4
4
  * Subscribes to every server-side log through a single stream: SDK server logs,
@@ -24,5 +24,5 @@ export type ServerLogHandler = (log: LoggingStreamResponse) => void;
24
24
  * unsubscribe();
25
25
  * ```
26
26
  */
27
- export declare function subscribeServerLogs(handler: ServerLogHandler): () => void;
27
+ export declare function subscribeServerLogs(handler: ServerLogHandler, options?: RPCOptions): () => void;
28
28
  //# sourceMappingURL=subscribe-logs.d.ts.map
@@ -25,9 +25,9 @@ const logger = getClientLogger();
25
25
  * unsubscribe();
26
26
  * ```
27
27
  */
28
- export function subscribeServerLogs(handler) {
28
+ export function subscribeServerLogs(handler, options) {
29
29
  const controller = new AbortController();
30
- const streamIterator = loggingStream({ id: SDK_ALL_LOG_ID }, { signal: controller.signal });
30
+ const streamIterator = loggingStream({ id: SDK_ALL_LOG_ID }, { ...options, signal: controller.signal });
31
31
  void (async () => {
32
32
  try {
33
33
  for await (const log of streamIterator) {
@@ -1,3 +1,4 @@
1
+ import type { RPCOptions } from '@qvac/inference/surface';
1
2
  /**
2
3
  * Suspends the SDK runtime: pauses all registered Hyperswarm and Corestore
3
4
  * resources and engages the lifecycle gate so non-lifecycle operations are
@@ -8,7 +9,8 @@
8
9
  *
9
10
  * After `suspend()` resolves, runtime state is `"suspended"` and any non-
10
11
  * lifecycle SDK operation throws `LifecycleOperationBlockedError` until
11
- * `resume()` is called.
12
+ * `resume()` is called. `session.close()` is the exception: a session can
13
+ * still end and release its leases while the runtime is suspended.
12
14
  *
13
15
  * In-flight operations started before suspend:
14
16
  * - P2P / Hyperdrive downloads: stall cleanly, continue after `resume()`
@@ -23,5 +25,5 @@
23
25
  * await suspend();
24
26
  * console.log(await state()); // "suspended"
25
27
  */
26
- export declare function suspend(): Promise<void>;
28
+ export declare function suspend(options?: RPCOptions): Promise<void>;
27
29
  //# sourceMappingURL=suspend.d.ts.map
@@ -10,7 +10,8 @@ import { InvalidResponseError } from '../../utils/errors-client.js';
10
10
  *
11
11
  * After `suspend()` resolves, runtime state is `"suspended"` and any non-
12
12
  * lifecycle SDK operation throws `LifecycleOperationBlockedError` until
13
- * `resume()` is called.
13
+ * `resume()` is called. `session.close()` is the exception: a session can
14
+ * still end and release its leases while the runtime is suspended.
14
15
  *
15
16
  * In-flight operations started before suspend:
16
17
  * - P2P / Hyperdrive downloads: stall cleanly, continue after `resume()`
@@ -25,8 +26,8 @@ import { InvalidResponseError } from '../../utils/errors-client.js';
25
26
  * await suspend();
26
27
  * console.log(await state()); // "suspended"
27
28
  */
28
- export async function suspend() {
29
- const response = await send({ type: 'suspend' });
29
+ export async function suspend(options) {
30
+ const response = await send({ type: 'suspend' }, options);
30
31
  if (response.type !== 'suspend') {
31
32
  throw new InvalidResponseError('suspend');
32
33
  }
@@ -35,9 +35,10 @@ export declare class TtsMulticast {
35
35
  *
36
36
  * - `stream: false` — collect all PCM samples and resolve once via
37
37
  * `result.buffer` (`Promise<number[]>`). `bufferStream` is empty.
38
- * - `stream: true` (default) — yield PCM samples through `result.bufferStream`
39
- * (`AsyncGenerator<number>`) as they arrive. `buffer` resolves to an empty
40
- * array.
38
+ * - `stream: true` (default) — yield PCM through `result.chunkStream`
39
+ * (`AsyncGenerator<Int16Array>`, one chunk per frame) or
40
+ * `result.bufferStream` (`AsyncGenerator<number>`, one sample at a time).
41
+ * `buffer` resolves to an empty array.
41
42
  * - `stream: true, sentenceStream: true` — also exposes `result.chunkUpdates`
42
43
  * (`AsyncGenerator<TtsSentenceChunkUpdate>`) so callers can mux per-sentence
43
44
  * metadata with the audio. Multiple consumers can iterate the response
@@ -60,7 +61,8 @@ export declare class TtsMulticast {
60
61
  * before draining the audio); `result.stats` and `result.stopReason` resolve
61
62
  * from the terminal frame. All three resolve — with `undefined` when the run
62
63
  * produced none — rather than reject. In `stream: true` mode (the default) the
63
- * run starts lazily: nothing is sent until `bufferStream` is first iterated, so
64
+ * run starts lazily: nothing is sent until `chunkStream` or `bufferStream` is
65
+ * first iterated, so
64
66
  * `done`, `sampleRate`, `stats` and `stopReason` stay pending until then. In
65
67
  * `stream: false` and `sentenceStream: true` modes the run starts immediately.
66
68
  * Read `sampleRate` rather than assuming the engine default: `outputSampleRate`
@@ -68,7 +70,7 @@ export declare class TtsMulticast {
68
70
  *
69
71
  * @param params - TTS request parameters (see `TtsClientParamsInput`).
70
72
  * @param options - Optional RPC options (timeout, profiling, force new connection).
71
- * @returns A `TextToSpeechStreamResult` with `bufferStream`, `buffer`, `done`,
73
+ * @returns A `TextToSpeechStreamResult` with `chunkStream`, `bufferStream`, `buffer`, `done`,
72
74
  * `sampleRate`, `stats`, and (when `sentenceStream: true`)
73
75
  * `chunkUpdates`.
74
76
  * @throws {TextToSpeechStreamFailedError} When `sentenceStream: true` is paired
@@ -87,11 +89,18 @@ export type TtsSideChannel = {
87
89
  sampleRate: Promise<number | undefined>;
88
90
  stats: Promise<TtsStats | undefined>;
89
91
  stopReason: Promise<'completed' | 'cancelled' | undefined>;
92
+ speechTokenIds: Promise<number[] | undefined>;
90
93
  observe(response: TtsResponse): void;
91
94
  settle(): void;
92
95
  };
93
96
  /** Exported for test use; not part of the public SDK surface. */
94
97
  export declare function createTtsSideChannel(): TtsSideChannel;
98
+ export declare function sentenceAudioViews(subscription: AsyncGenerator<TtsResponse>): {
99
+ bufferStream: AsyncGenerator<number>;
100
+ chunkStream: AsyncGenerator<Int16Array>;
101
+ };
102
+ export declare function pcmChunksOf(source: AsyncIterable<TtsResponse>): AsyncGenerator<Int16Array>;
103
+ export declare function samplesOf(chunks: AsyncIterable<Int16Array>): AsyncGenerator<number>;
95
104
  export declare function encodeTextToSpeechFragment(textFragment: string | Uint8Array): Uint8Array<ArrayBufferLike>;
96
105
  /**
97
106
  * Duplex session: write UTF-8 text fragments (e.g. LLM token deltas) via `write`. Each string or