@qvac/sdk 0.21.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (167) hide show
  1. package/NOTICE +35 -1
  2. package/README.md +167 -24
  3. package/dist/examples/abot-world.js +1 -1
  4. package/dist/examples/advisory-model-fit.d.ts +0 -58
  5. package/dist/examples/advisory-model-fit.js +23 -150
  6. package/dist/examples/asr/moss-transcribe-filesystem.d.ts +2 -0
  7. package/dist/examples/asr/moss-transcribe-filesystem.js +84 -0
  8. package/dist/examples/asr/moss-transcribe-fit.d.ts +2 -0
  9. package/dist/examples/asr/moss-transcribe-fit.js +40 -0
  10. package/dist/examples/asr/nemotron-diarization-filesystem.d.ts +2 -0
  11. package/dist/examples/asr/nemotron-diarization-filesystem.js +64 -0
  12. package/dist/examples/asr/parakeet-ctc-filesystem.js +2 -2
  13. package/dist/examples/asr/parakeet-indic-conformer-filesystem.js +2 -2
  14. package/dist/examples/asr/parakeet-microphone-record.js +1 -1
  15. package/dist/examples/asr/parakeet-microphone-stream.js +1 -1
  16. package/dist/examples/asr/parakeet-nemotron-filesystem.js +3 -3
  17. package/dist/examples/asr/parakeet-sortformer-streaming.js +2 -2
  18. package/dist/examples/asr/parakeet-sortformer.js +1 -1
  19. package/dist/examples/asr/parakeet-tdt-filesystem-chunked.js +2 -2
  20. package/dist/examples/asr/parakeet-tdt-filesystem.js +2 -2
  21. package/dist/examples/asr/parakeet-unified-coreml.js +2 -2
  22. package/dist/examples/asr/parakeet-unified-filesystem.js +2 -2
  23. package/dist/examples/asr/whispercpp-filesystem-streaming.js +1 -1
  24. package/dist/examples/asr/whispercpp-filesystem.js +1 -1
  25. package/dist/examples/asr/whispercpp-microphone-record.js +1 -1
  26. package/dist/examples/asr/whispercpp-prompt.js +1 -1
  27. package/dist/examples/assess-model-fit.js +3 -6
  28. package/dist/examples/audiogen/edit-music.js +2 -2
  29. package/dist/examples/audiogen/generate-cover.js +2 -2
  30. package/dist/examples/audiogen/generate-music-minimax.js +1 -1
  31. package/dist/examples/audiogen/generate-music.js +1 -1
  32. package/dist/examples/audiogen/understand-music.js +2 -2
  33. package/dist/examples/batch-completion.d.ts +1 -1
  34. package/dist/examples/batch-completion.js +1 -1
  35. package/dist/examples/bci/bci-filesystem-streaming.js +2 -2
  36. package/dist/examples/bci/bci-filesystem.js +2 -2
  37. package/dist/examples/concurrent-completion-collision.js +1 -1
  38. package/dist/examples/config-reload.js +1 -1
  39. package/dist/examples/decisions.d.ts +2 -0
  40. package/dist/examples/decisions.js +38 -0
  41. package/dist/examples/diffusion-esrgan-upscale.js +1 -1
  42. package/dist/examples/diffusion-flux2-klein-img2img.js +1 -1
  43. package/dist/examples/diffusion-img2img.js +1 -1
  44. package/dist/examples/diffusion-img2vid-ltx.js +1 -1
  45. package/dist/examples/diffusion-img2vid-minimax-h3.d.ts +2 -0
  46. package/dist/examples/diffusion-img2vid-minimax-h3.js +72 -0
  47. package/dist/examples/diffusion-img2vid.js +1 -1
  48. package/dist/examples/llamacpp-filesystem.js +1 -1
  49. package/dist/examples/llamacpp-multi-gpu.js +2 -2
  50. package/dist/examples/llamacpp-structured-output.js +1 -1
  51. package/dist/examples/mcp-websearch.d.ts +2 -2
  52. package/dist/examples/mcp-websearch.js +3 -3
  53. package/dist/examples/model-fit-ui/server.d.ts +1 -1
  54. package/dist/examples/model-fit-ui/server.js +1 -1
  55. package/dist/examples/multi-job-completion.d.ts +1 -1
  56. package/dist/examples/multi-job-completion.js +1 -1
  57. package/dist/examples/ocr-fasttext.js +1 -1
  58. package/dist/examples/tools/llamacpp-tools-auto-dialect.js +1 -1
  59. package/dist/examples/tools/llamacpp-tools-gemma4.js +1 -1
  60. package/dist/examples/tools/llamacpp-tools-qwen35.js +1 -1
  61. package/dist/examples/tts/llm-to-tts-streaming.d.ts +2 -2
  62. package/dist/examples/tts/llm-to-tts-streaming.js +2 -2
  63. package/dist/examples/tts/moss-sound-effect-controls.d.ts +2 -0
  64. package/dist/examples/tts/moss-sound-effect-controls.js +88 -0
  65. package/dist/examples/tts/moss-sound-effect.d.ts +2 -0
  66. package/dist/examples/tts/moss-sound-effect.js +86 -0
  67. package/dist/examples/tts/moss-speech-audio.d.ts +2 -0
  68. package/dist/examples/tts/moss-speech-audio.js +159 -0
  69. package/dist/examples/tts/moss-speech.d.ts +2 -0
  70. package/dist/examples/tts/moss-speech.js +70 -0
  71. package/dist/examples/vla-groot.js +2 -2
  72. package/dist/examples/vla-pi05.js +2 -2
  73. package/dist/examples/vla-smolvla.js +2 -2
  74. package/dist/examples/voice-assistant/voice-assistant.js +1 -1
  75. package/dist/scripts/contract/build-contract.d.ts +3 -1
  76. package/dist/scripts/contract/build-contract.js +40 -2
  77. package/dist/scripts/contract/build-model-type-maps.d.ts +6 -1
  78. package/dist/scripts/contract/build-model-type-maps.js +3 -2
  79. package/dist/scripts/contract/constants-registry.d.ts +4 -0
  80. package/dist/scripts/contract/constants-registry.js +3 -1
  81. package/dist/scripts/contract/method-shapes.d.ts +1 -0
  82. package/dist/scripts/contract/method-shapes.js +1 -0
  83. package/dist/scripts/export-contract.js +20 -7
  84. package/dist/scripts/run-unit-tests.js +10 -5
  85. package/dist/src/client/api/assess-model-fit.d.ts +5 -5
  86. package/dist/src/client/api/assess-model-fit.js +5 -6
  87. package/dist/src/client/api/audio-edit.d.ts +14 -2
  88. package/dist/src/client/api/audio-edit.js +14 -2
  89. package/dist/src/client/api/audio-gen.d.ts +10 -2
  90. package/dist/src/client/api/audio-gen.js +10 -2
  91. package/dist/src/client/api/audio-understand.d.ts +1 -1
  92. package/dist/src/client/api/audio-understand.js +1 -1
  93. package/dist/src/client/api/batch-completion.js +1 -1
  94. package/dist/src/client/api/completion-stream.js +1 -1
  95. package/dist/src/client/api/decide.d.ts +31 -0
  96. package/dist/src/client/api/decide.js +29 -0
  97. package/dist/src/client/api/index.d.ts +1 -0
  98. package/dist/src/client/api/index.js +1 -0
  99. package/dist/src/client/api/load-model.d.ts +1 -0
  100. package/dist/src/client/api/text-to-speech.d.ts +1 -0
  101. package/dist/src/client/api/text-to-speech.js +15 -22
  102. package/dist/src/client/api/transcribe.js +5 -2
  103. package/dist/src/client/api/video-request.d.ts +5 -5
  104. package/dist/src/client/api/video.d.ts +23 -3
  105. package/dist/src/client/api/video.js +23 -3
  106. package/dist/src/commands/bundle/bare-pack.d.ts +8 -0
  107. package/dist/src/commands/bundle/bare-pack.js +28 -5
  108. package/dist/src/commands/bundle/constants.js +2 -0
  109. package/dist/src/commands/bundle/index.d.ts +7 -6
  110. package/dist/src/commands/bundle/index.js +126 -43
  111. package/dist/src/commands/bundle/manifest.d.ts +2 -0
  112. package/dist/src/commands/bundle/manifest.js +3 -2
  113. package/dist/src/commands/host-prebuilds/index.d.ts +15 -7
  114. package/dist/src/commands/host-prebuilds/index.js +35 -16
  115. package/dist/src/commands/index.d.ts +1 -1
  116. package/dist/src/commands/index.js +1 -1
  117. package/dist/src/commands/verify/addon-source.d.ts +12 -0
  118. package/dist/src/commands/verify/addon-source.js +36 -3
  119. package/dist/src/commands/verify/bare-kit-runtimes.js +2 -1
  120. package/dist/src/commands/verify/node-modules-source.js +10 -1
  121. package/dist/src/{expo/plugins/patches/qvac-platform-addons.d.ts → commands/verify/platform-addons.d.ts} +6 -10
  122. package/dist/src/{expo/plugins/patches/qvac-platform-addons.js → commands/verify/platform-addons.js} +2 -45
  123. package/dist/src/commands/verify/prebuilds.d.ts +7 -10
  124. package/dist/src/commands/verify/prebuilds.js +43 -34
  125. package/dist/src/expo/plugins/get-project-root.d.ts +1 -1
  126. package/dist/src/expo/plugins/link-addons.d.ts +18 -0
  127. package/dist/src/expo/plugins/link-addons.js +65 -0
  128. package/dist/src/expo/plugins/withAndroidArchitecture.d.ts +1 -1
  129. package/dist/src/expo/plugins/withAndroidNdkVersion.d.ts +1 -1
  130. package/dist/src/expo/plugins/withDeviceInfo.d.ts +1 -1
  131. package/dist/src/expo/plugins/withMobileBundle.d.ts +11 -21
  132. package/dist/src/expo/plugins/withMobileBundle.js +22 -112
  133. package/dist/src/expo/plugins/withOpenCL.d.ts +1 -1
  134. package/dist/src/expo/plugins/withQvacSDK.d.ts +1 -1
  135. package/dist/src/index.d.ts +3 -3
  136. package/dist/src/index.js +2 -2
  137. package/dist/src/logging/base-logger.js +1 -1
  138. package/dist/src/logging/utils.js +1 -1
  139. package/dist/src/pear/pre.js +2 -0
  140. package/dist/src/plugin-ids.d.ts +3 -1
  141. package/dist/src/plugin-ids.js +4 -0
  142. package/dist/src/schemas/public.d.ts +2 -1
  143. package/dist/src/schemas/public.js +2 -1
  144. package/dist/src/schemas/sdk-errors-client.d.ts +3 -0
  145. package/dist/src/schemas/sdk-errors-client.js +16 -0
  146. package/dist/src/schemas/sdk-errors-server.d.ts +1 -0
  147. package/dist/src/schemas/sdk-errors-server.js +5 -0
  148. package/dist/src/utils/errors-client.d.ts +10 -0
  149. package/dist/src/utils/errors-client.js +18 -0
  150. package/dist/src/utils/mcp-adapter.js +12 -8
  151. package/dist/src/utils/tool-helpers.d.ts +1 -1
  152. package/dist/src/utils/tool-helpers.js +20 -52
  153. package/dist/src/worker/create-server.d.ts +1 -0
  154. package/dist/src/worker/create-server.js +5 -0
  155. package/dist/src/worker/index.js +4 -0
  156. package/dist/src/worker/lifecycle.js +9 -1
  157. package/dist/src/worker/plugins/llamacpp-decision.d.ts +2 -0
  158. package/dist/src/worker/plugins/llamacpp-decision.js +1 -0
  159. package/dist/src/worker/plugins/moss-transcribe.d.ts +2 -0
  160. package/dist/src/worker/plugins/moss-transcribe.js +1 -0
  161. package/package.json +39 -35
  162. package/src/electron-forge/index.cjs +12 -71
  163. package/dist/scripts/link-workspace-inference.d.ts +0 -2
  164. package/dist/scripts/link-workspace-inference.js +0 -31
  165. package/src/expo/plugins/patches/android-link.mjs +0 -67
  166. package/src/expo/plugins/patches/ios-link.mjs +0 -67
  167. package/src/expo/plugins/patches/qvac-platform-addons.ts +0 -124
@@ -0,0 +1,70 @@
1
+ import { loadModel, textToSpeech, unloadModel, close, TTS_MOSS_SPEECH_Q8_0, TTS_CODEC_MOSS_SPEECH_F16 } from '@qvac/sdk';
2
+ // Desktop MOSS-Speech: answer a typed question with textReply: true.
3
+ // This mode skips audio decoding and returns text with an empty PCM buffer.
4
+ // Run from packages/sdk: node --import tsx examples/tts/moss-speech.ts
5
+ // Use a GPU with enough memory. Registry sources download automatically.
6
+ // Optional local paths: QVAC_MOSS_SPEECH_MODEL and QVAC_MOSS_SPEECH_CODEC.
7
+ // Both engines run a batch job; stream: false collects the complete reply.
8
+ let lastPercentage = -1;
9
+ function progress(p) {
10
+ const percentage = Math.floor(p.percentage);
11
+ if (percentage === lastPercentage)
12
+ return;
13
+ lastPercentage = percentage;
14
+ const line = `▸ Downloading ${p.percentage.toFixed(0)}% (${(p.downloaded / 1e6).toFixed(1)}/${(p.total / 1e6).toFixed(1)} MB)`;
15
+ process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
16
+ if (p.percentage >= 100)
17
+ process.stderr.write('\n');
18
+ }
19
+ async function main() {
20
+ const modelId = await loadModel({
21
+ modelSrc: process.env['QVAC_MOSS_SPEECH_MODEL'] ?? TTS_MOSS_SPEECH_Q8_0,
22
+ modelType: 'tts-ggml',
23
+ modelConfig: {
24
+ ttsEngine: 'moss-speech',
25
+ mossSpeechCodecModelSrc: process.env['QVAC_MOSS_SPEECH_CODEC'] ?? TTS_CODEC_MOSS_SPEECH_F16,
26
+ useGPU: true,
27
+ seed: 42
28
+ },
29
+ onProgress: progress
30
+ });
31
+ try {
32
+ console.error('▸ Generating a text-only reply...');
33
+ const result = textToSpeech({
34
+ modelId,
35
+ text: 'What is two plus two? Answer in one short sentence.',
36
+ stream: false,
37
+ textReply: true,
38
+ greedy: true,
39
+ maxNewTokens: 128,
40
+ maxReplySeconds: 5,
41
+ systemPrompt: 'You are a helpful assistant. Give short, direct answers.'
42
+ });
43
+ const samples = await result.buffer;
44
+ const reply = await result.text;
45
+ if (!(await result.done) || !reply?.trim())
46
+ throw new Error('The model returned no reply text.');
47
+ console.log(reply);
48
+ if (samples.length !== 0)
49
+ throw new Error('A text-only reply must not contain PCM audio.');
50
+ }
51
+ finally {
52
+ await unloadModel({ modelId });
53
+ }
54
+ }
55
+ try {
56
+ await main();
57
+ }
58
+ catch (error) {
59
+ console.error('✖', error);
60
+ process.exitCode = 1;
61
+ }
62
+ finally {
63
+ try {
64
+ await close();
65
+ }
66
+ catch (error) {
67
+ console.error('✖ Cleanup failed:', error);
68
+ process.exitCode = 1;
69
+ }
70
+ }
@@ -22,7 +22,7 @@
22
22
  * image tokens; we lay it out by hand for the smoke.
23
23
  *
24
24
  * Usage:
25
- * bun examples/vla-groot.ts [path-to-groot.gguf]
25
+ * npx tsx examples/vla-groot.ts [path-to-groot.gguf]
26
26
  *
27
27
  * By default the example pulls the registry-baked GR00T-LIBERO GGUF (~3.76 GB)
28
28
  * on first run and caches it locally. Pass an absolute path on the command line
@@ -68,7 +68,7 @@ try {
68
68
  const modelId = await loadModel({
69
69
  modelSrc,
70
70
  modelType: 'ggml-vla',
71
- modelConfig: { backend: 'cpu', ...(embodiment !== undefined && { embodiment }) },
71
+ modelConfig: { backend: ['cpu'], ...(embodiment !== undefined && { embodiment }) },
72
72
  onProgress: (p) => {
73
73
  const mb = (n) => (n / 1e6).toFixed(1);
74
74
  const line = `▸ Downloading ${p.percentage.toFixed(0)}% (${mb(p.downloaded)}/${mb(p.total)} MB)`;
@@ -12,7 +12,7 @@
12
12
  * `Float32Array(0)`. π₀.₅ also requires the `noise` prior.
13
13
  *
14
14
  * Usage:
15
- * bun examples/vla-pi05.ts [path-to-pi05.gguf]
15
+ * npx tsx examples/vla-pi05.ts [path-to-pi05.gguf]
16
16
  *
17
17
  * By default the example pulls the registry-baked π₀.₅ GGUF (~3.9 GB) on
18
18
  * first run and caches it locally. Pass an absolute path on the command line
@@ -26,7 +26,7 @@ try {
26
26
  const modelId = await loadModel({
27
27
  modelSrc,
28
28
  modelType: 'ggml-vla',
29
- modelConfig: { backend: 'cpu' },
29
+ modelConfig: { backend: ['cpu'] },
30
30
  onProgress: (p) => {
31
31
  const mb = (n) => (n / 1e6).toFixed(1);
32
32
  const line = `▸ Downloading ${p.percentage.toFixed(0)}% (${mb(p.downloaded)}/${mb(p.total)} MB)`;
@@ -6,7 +6,7 @@
6
6
  * zero noise), and prints the produced action chunk + per-stage timings.
7
7
  *
8
8
  * Usage:
9
- * bun examples/vla-smolvla.ts [path-to-smolvla.gguf]
9
+ * npx tsx examples/vla-smolvla.ts [path-to-smolvla.gguf]
10
10
  *
11
11
  * By default the example pulls the registry-baked SmolVLA-LIBERO GGUF
12
12
  * (~1.9 GB) on first run and caches it locally. Pass an absolute path on
@@ -20,7 +20,7 @@ try {
20
20
  const modelId = await loadModel({
21
21
  modelSrc,
22
22
  modelType: 'ggml-vla',
23
- modelConfig: { backend: 'cpu' },
23
+ modelConfig: { backend: ['cpu'] },
24
24
  onProgress: (p) => {
25
25
  const mb = (n) => (n / 1e6).toFixed(1);
26
26
  const line = `▸ Downloading ${p.percentage.toFixed(0)}% (${mb(p.downloaded)}/${mb(p.total)} MB)`;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Real-time Voice Assistant: mic → Whisper (with Silero VAD) → Llama → Supertonic TTS.
3
3
  *
4
- * Usage: bun run examples/voice-assistant/voice-assistant.ts
4
+ * Usage: npx tsx examples/voice-assistant/voice-assistant.ts
5
5
  *
6
6
  * Speak a question; the VAD detects when you pause, the utterance is
7
7
  * transcribed, sent to the LLM, and the response is spoken back. The loop
@@ -1,5 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  export declare const contractDir: URL;
3
+ export declare const registryEngineManifestFile: URL;
3
4
  export declare const callShapeByHandlerType: {
4
5
  readonly reply: "request-reply";
5
6
  readonly stream: "server-stream";
@@ -20,7 +21,7 @@ export declare function buildContract(): {
20
21
  condition: string;
21
22
  responseSchema: string;
22
23
  };
23
- name: "audioGenStream" | "audioEditStream" | "audioUnderstand" | "startRpcServer" | "stopRpcServer" | "discoverRpcServers" | "heartbeat" | "loadModel" | "downloadAsset" | "completionStream" | "completionOrchestrate" | "batchCompletionStream" | "unloadModel" | "transcribe" | "transcribeStream" | "bciTranscribe" | "bciTranscribeStream" | "loggingStream" | "embed" | "translate" | "textToSpeech" | "textToSpeechStream" | "cancel" | "finetune" | "rag" | "vectorIndex" | "deleteCache" | "getModelInfo" | "getLoadedModelInfo" | "getSystemResources" | "assessModelFit" | "ocrStream" | "diffusionStream" | "videoStream" | "upscaleStream" | "worldSceneStream" | "worldStepStream" | "resume" | "pluginInvoke" | "pluginInvokeStream" | "modelRegistryList" | "modelRegistrySearch" | "modelRegistryGetModel" | "suspend" | "state" | "classify";
24
+ name: "audioGenStream" | "audioEditStream" | "audioUnderstand" | "startRpcServer" | "stopRpcServer" | "discoverRpcServers" | "heartbeat" | "loadModel" | "downloadAsset" | "completionStream" | "completionOrchestrate" | "batchCompletionStream" | "unloadModel" | "transcribe" | "transcribeStream" | "bciTranscribe" | "bciTranscribeStream" | "loggingStream" | "embed" | "translate" | "textToSpeech" | "textToSpeechStream" | "cancel" | "finetune" | "rag" | "vectorIndex" | "deleteCache" | "getModelInfo" | "getLoadedModelInfo" | "getSystemResources" | "assessModelFit" | "ocrStream" | "diffusionStream" | "videoStream" | "upscaleStream" | "worldSceneStream" | "worldStepStream" | "resume" | "pluginInvoke" | "pluginInvokeStream" | "modelRegistryList" | "modelRegistrySearch" | "modelRegistryGetModel" | "suspend" | "state" | "classify" | "decide";
24
25
  callShape: "duplex" | "request-reply" | "server-stream";
25
26
  requestSchema: string;
26
27
  responseSchema: string;
@@ -35,5 +36,6 @@ export declare function renderContractFiles(): Promise<{
35
36
  'error-codes.json': string;
36
37
  'numeric-constants.json': string;
37
38
  }>;
39
+ export declare function renderRegistryEngineManifest(): Promise<string>;
38
40
  export {};
39
41
  //# sourceMappingURL=build-contract.d.ts.map
@@ -9,6 +9,7 @@ import { buildModelTypeMaps } from './build-model-type-maps.js';
9
9
  import { buildErrorCodes } from './build-error-codes.js';
10
10
  import { buildNumericConstants } from './build-numeric-constants.js';
11
11
  export const contractDir = new URL('../../contract/', import.meta.url);
12
+ export const registryEngineManifestFile = new URL('../../../registry-server/lib/generated/engine-manifest.json', import.meta.url);
12
13
  export const callShapeByHandlerType = {
13
14
  reply: 'request-reply',
14
15
  stream: 'server-stream',
@@ -139,6 +140,37 @@ function flattenAllOfWithUnion(json, defName) {
139
140
  function isSchemaObject(node) {
140
141
  return node !== null && typeof node === 'object' && !Array.isArray(node);
141
142
  }
143
+ /**
144
+ * Zod 4.6 emits primitive unions as `type: [...]`. That is valid JSON Schema,
145
+ * but the Kotlin generator represents that form as an untyped JsonElement.
146
+ * Keep the equivalent `anyOf` form used by earlier Zod releases so generated
147
+ * clients retain their typed union wrappers.
148
+ */
149
+ function expandPrimitiveTypeArrays(node) {
150
+ if (Array.isArray(node))
151
+ return node.map(expandPrimitiveTypeArrays);
152
+ if (!isSchemaObject(node))
153
+ return node;
154
+ const expanded = Object.fromEntries(Object.entries(node).map(function ([key, value]) {
155
+ return [key, expandPrimitiveTypeArrays(value)];
156
+ }));
157
+ const types = expanded['type'];
158
+ if (!Array.isArray(types))
159
+ return expanded;
160
+ if (!types.every(function (type) {
161
+ return typeof type === 'string';
162
+ })) {
163
+ throw new Error('JSON Schema type arrays must contain only strings');
164
+ }
165
+ if (expanded['anyOf'] !== undefined || expanded['oneOf'] !== undefined) {
166
+ throw new Error('Cannot expand a JSON Schema type array beside an existing union');
167
+ }
168
+ delete expanded['type'];
169
+ expanded['anyOf'] = types.map(function (type) {
170
+ return { type };
171
+ });
172
+ return expanded;
173
+ }
142
174
  function unionArmsOf(node) {
143
175
  if (Array.isArray(node['oneOf']))
144
176
  return node['oneOf'];
@@ -429,7 +461,8 @@ export function toWireJsonSchema(schema, io, defName) {
429
461
  unrepresentable: 'any'
430
462
  });
431
463
  delete json['$schema'];
432
- const flattened = flattenAllOfWithUnion(json, defName);
464
+ const expanded = expandPrimitiveTypeArrays(json);
465
+ const flattened = flattenAllOfWithUnion(expanded, defName);
433
466
  const collapsed = collapseSingleMemberUnions(flattened);
434
467
  assertNoRefs(collapsed, defName);
435
468
  return collapsed;
@@ -591,7 +624,7 @@ export function buildContract() {
591
624
  const schemaDocument = {
592
625
  $schema: 'https://json-schema.org/draft/2020-12/schema',
593
626
  title: '@qvac/sdk wire contract',
594
- description: 'Generated from the SDK Zod schemas by `bun run contract:export`. Do not edit by hand. ' +
627
+ description: 'Generated from the SDK Zod schemas by `npm run contract:export`. Do not edit by hand. ' +
595
628
  'Requests use the schema input shape, responses the output shape; runtime-only ' +
596
629
  'refinements and transforms stay server-side.',
597
630
  $defs: defs
@@ -621,3 +654,8 @@ export async function renderContractFiles() {
621
654
  'numeric-constants.json': await formatJson(numericConstants, 'numeric-constants.json')
622
655
  };
623
656
  }
657
+ // Build-time export only: registry validation reads its own packaged artifact.
658
+ export async function renderRegistryEngineManifest() {
659
+ const { engineToAddon, legacyEngineToCanonical, legacyRegistryEngineRules } = buildModelTypeMaps();
660
+ return formatJson({ engineToAddon, legacyEngineToCanonical, legacyRegistryEngineRules }, 'engine-manifest.json');
661
+ }
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * JSON export of the model-type resolution maps that `loadModel`'s
3
3
  * client-side type-inference reads: alias → canonical model type, canonical
4
- * engine → addon, and legacy engine string → canonical engine.
4
+ * engine → addon, legacy engine string → canonical engine, and tagged rules
5
+ * for shared legacy registry packages.
5
6
  *
6
7
  * Inference itself stays in each client (a plain string `modelSrc` carries no
7
8
  * engine to infer from, so it can't move server-side), but the *data* it reads
@@ -17,6 +18,10 @@ export interface ModelTypeMaps {
17
18
  aliasToCanonical: Record<string, string>;
18
19
  engineToAddon: Record<string, string>;
19
20
  legacyEngineToCanonical: Record<string, string>;
21
+ legacyRegistryEngineRules: Record<string, readonly {
22
+ tag: string;
23
+ engine: string;
24
+ }[]>;
20
25
  }
21
26
  export declare function buildModelTypeMaps(): ModelTypeMaps;
22
27
  //# sourceMappingURL=build-model-type-maps.d.ts.map
@@ -1,4 +1,4 @@
1
- import { ModelTypeAliases, ENGINE_TO_ADDON, LEGACY_ENGINE_TO_CANONICAL } from '@qvac/inference/surface';
1
+ import { ModelTypeAliases, ENGINE_TO_ADDON, LEGACY_ENGINE_TO_CANONICAL, LEGACY_REGISTRY_ENGINE_RULES } from '@qvac/inference/surface';
2
2
  function sortedEntries(record) {
3
3
  const entries = Object.entries(record);
4
4
  entries.sort(function (a, b) {
@@ -10,6 +10,7 @@ export function buildModelTypeMaps() {
10
10
  return {
11
11
  aliasToCanonical: sortedEntries(ModelTypeAliases),
12
12
  engineToAddon: sortedEntries(ENGINE_TO_ADDON),
13
- legacyEngineToCanonical: sortedEntries(LEGACY_ENGINE_TO_CANONICAL)
13
+ legacyEngineToCanonical: sortedEntries(LEGACY_ENGINE_TO_CANONICAL),
14
+ legacyRegistryEngineRules: sortedEntries(LEGACY_REGISTRY_ENGINE_RULES)
14
15
  };
15
16
  }
@@ -29,10 +29,12 @@ export declare const constantsRegistry: {
29
29
  readonly whispercppTranscription: "whispercpp-transcription";
30
30
  readonly bciWhispercppTranscription: "bci-whispercpp-transcription";
31
31
  readonly llamacppEmbedding: "llamacpp-embedding";
32
+ readonly llamacppDecision: "llamacpp-decision";
32
33
  readonly nmtcppTranslation: "nmtcpp-translation";
33
34
  readonly onnxTts: "onnx-tts";
34
35
  readonly ttsGgml: "tts-ggml";
35
36
  readonly parakeetTranscription: "parakeet-transcription";
37
+ readonly mossTranscribe: "moss-transcribe";
36
38
  readonly ggmlOcr: "ggml-ocr";
37
39
  readonly sdcppGeneration: "sdcpp-generation";
38
40
  readonly audiogenGgml: "audiogen-ggml";
@@ -48,8 +50,10 @@ export declare const constantsRegistry: {
48
50
  readonly PluginId: z.ZodEnum<{
49
51
  readonly LLM: "@qvac/sdk/llamacpp-completion/plugin";
50
52
  readonly EMBEDDING: "@qvac/sdk/llamacpp-embedding/plugin";
53
+ readonly DECISION: "@qvac/sdk/llamacpp-decision/plugin";
51
54
  readonly WHISPER: "@qvac/sdk/whispercpp-transcription/plugin";
52
55
  readonly BCI: "@qvac/sdk/bci-whispercpp-transcription/plugin";
56
+ readonly MOSS_TRANSCRIBE: "@qvac/sdk/moss-transcribe/plugin";
53
57
  readonly NMT: "@qvac/sdk/nmtcpp-translation/plugin";
54
58
  readonly TTS: "@qvac/sdk/tts-ggml/plugin";
55
59
  readonly OCR: "@qvac/sdk/ggml-ocr/plugin";
@@ -1,6 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  import { ModelType, VERBOSITY, SUPPORTED_AUDIO_FORMATS, AUDIOGEN_ENGINES, AUDIOGEN_TASK_TYPES, AUDIOGEN_EDIT_OPERATIONS, AUDIOGEN_REPAINT_MODES, AUDIOGEN_TRACKS, TTS_ENGINES, TTS_PACES, TTS_PARLER_EMOTIONS, TTS_SENTENCE_DELIMITER_PRESETS, TTS_CHATTERBOX_LANGUAGES, TTS_SUPERTONIC_LANGUAGES, TTS_COSYVOICE3_EMOTIONS, TTS_COSYVOICE3_INSTRUCT_DIALECTS, TTS_COSYVOICE3_INSTRUCT_VOLUMES, TTS_COSYVOICE3_INSTRUCT_STYLES, VectorIndexStorage } from '@qvac/inference/surface';
3
- import { PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_WHISPER, PLUGIN_BCI, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, PLUGIN_AUDIOGEN, PLUGIN_VLA, PLUGIN_CLASSIFICATION } from '../../src/plugin-ids.js';
3
+ import { PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_DECISION, PLUGIN_WHISPER, PLUGIN_BCI, PLUGIN_MOSS_TRANSCRIBE, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, PLUGIN_AUDIOGEN, PLUGIN_VLA, PLUGIN_CLASSIFICATION } from '../../src/plugin-ids.js';
4
4
  // Uppercases each vocabulary value into an identifier-safe varname (e.g.
5
5
  // 'slow' -> 'SLOW', 'cover-nofsq' -> 'COVER_NOFSQ'), mirroring the
6
6
  // SupportedAudioFormat derivation so names can't drift from the single
@@ -38,8 +38,10 @@ export const constantsRegistry = {
38
38
  PluginId: z.enum({
39
39
  LLM: PLUGIN_LLM,
40
40
  EMBEDDING: PLUGIN_EMBEDDING,
41
+ DECISION: PLUGIN_DECISION,
41
42
  WHISPER: PLUGIN_WHISPER,
42
43
  BCI: PLUGIN_BCI,
44
+ MOSS_TRANSCRIBE: PLUGIN_MOSS_TRANSCRIBE,
43
45
  NMT: PLUGIN_NMT,
44
46
  TTS: PLUGIN_TTS,
45
47
  OCR: PLUGIN_OCR,
@@ -25,6 +25,7 @@ export declare const methodShapes: {
25
25
  readonly diffusionStream: "stream";
26
26
  readonly downloadAsset: "reply";
27
27
  readonly embed: "reply";
28
+ readonly decide: "reply";
28
29
  readonly finetune: "reply";
29
30
  readonly getLoadedModelInfo: "reply";
30
31
  readonly getModelInfo: "reply";
@@ -25,6 +25,7 @@ export const methodShapes = {
25
25
  diffusionStream: 'stream',
26
26
  downloadAsset: 'reply',
27
27
  embed: 'reply',
28
+ decide: 'reply',
28
29
  finetune: 'reply',
29
30
  getLoadedModelInfo: 'reply',
30
31
  getModelInfo: 'reply',
@@ -1,27 +1,40 @@
1
1
  import { mkdir, readFile, writeFile } from 'node:fs/promises';
2
+ import { dirname } from 'node:path';
2
3
  import { fileURLToPath } from 'node:url';
3
- import { contractDir, renderContractFiles } from './contract/build-contract.js';
4
+ import { contractDir, registryEngineManifestFile, renderContractFiles, renderRegistryEngineManifest } from './contract/build-contract.js';
4
5
  const checkOnly = process.argv.includes('--check');
5
6
  const files = await renderContractFiles();
6
- await mkdir(contractDir, { recursive: true });
7
+ const artifacts = [
8
+ ...Object.entries(files).map(([name, content]) => ({
9
+ label: `contract/${name}`,
10
+ file: new URL(name, contractDir),
11
+ content
12
+ })),
13
+ {
14
+ label: 'registry-server/lib/generated/engine-manifest.json',
15
+ file: registryEngineManifestFile,
16
+ content: await renderRegistryEngineManifest()
17
+ }
18
+ ];
7
19
  let stale = false;
8
- for (const [name, content] of Object.entries(files)) {
9
- const filePath = fileURLToPath(new URL(name, contractDir));
20
+ for (const { label, file, content } of artifacts) {
21
+ const filePath = fileURLToPath(file);
10
22
  if (checkOnly) {
11
23
  const existing = await readFile(filePath, 'utf8').catch(function () {
12
24
  return null;
13
25
  });
14
26
  if (existing !== content) {
15
- console.error(`contract/${name} is ${existing === null ? 'missing' : 'out of date'}`);
27
+ console.error(`${label} is ${existing === null ? 'missing' : 'out of date'}`);
16
28
  stale = true;
17
29
  }
18
30
  }
19
31
  else {
32
+ await mkdir(dirname(filePath), { recursive: true });
20
33
  await writeFile(filePath, content);
21
- console.log(`wrote contract/${name}`);
34
+ console.log(`wrote ${label}`);
22
35
  }
23
36
  }
24
37
  if (stale) {
25
- console.error("Contract artifacts are stale. Run 'bun run contract:export' and commit the result.");
38
+ console.error("Generated contract artifacts are stale. Run 'npm run contract:export' and commit the result.");
26
39
  process.exit(1);
27
40
  }
@@ -4,9 +4,8 @@ import { spawnSync } from 'child_process';
4
4
  import { fileURLToPath } from 'url';
5
5
  const __dirname = dirname(fileURLToPath(import.meta.url));
6
6
  const testDir = join(__dirname, '..', 'test');
7
- // The Bare suite (test/bare) and its build output (test/dist) run via
8
- // `test:bare`, so the Bun/Node unit runner skips them.
9
- const SKIP_DIRS = new Set(['bare', 'dist']);
7
+ // test/dist is a build output, not a test source tree.
8
+ const SKIP_DIRS = new Set(['dist']);
10
9
  function collectTestFiles(dir) {
11
10
  const files = [];
12
11
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -28,9 +27,15 @@ function usesNodeTestRunner(filePath) {
28
27
  const source = readFileSync(filePath, 'utf8');
29
28
  return source.includes("from 'node:test'") || source.includes('from "node:test"');
30
29
  }
30
+ // Each file runs in its own Node process with tsx loaded, so TypeScript sources
31
+ // and the tsconfig path aliases resolve without a build step. brittle files run
32
+ // as plain scripts; node:test files go through Node's test runner, with
33
+ // `mock.module` enabled for tests that replace a module before importing it.
31
34
  for (const file of testFiles) {
32
- const args = usesNodeTestRunner(file) ? ['test', file] : ['run', file];
33
- const result = spawnSync('bun', args, {
35
+ const args = usesNodeTestRunner(file)
36
+ ? ['--experimental-test-module-mocks', '--import', 'tsx', '--test', file]
37
+ : ['--import', 'tsx', file];
38
+ const result = spawnSync(process.execPath, args, {
34
39
  stdio: 'inherit'
35
40
  });
36
41
  if (result.status !== 0) {
@@ -8,11 +8,11 @@ import { type AssessModelFitInput, type AssessModelFitResult } from '@qvac/infer
8
8
  * the available evidence does not support a verdict either way, and callers
9
9
  * should treat it as "cannot say", not "no".
10
10
  *
11
- * For a single candidate it fetches the registry's weightless description of
12
- * every source that load names — tens of KB each, never the weights — and runs
13
- * the engine's own fitter against them, reported as `native-fit` evidence.
14
- * Where that is unavailable, and for a set of candidates, the calibrated
15
- * estimate stands.
11
+ * For each candidate it fetches the registry's weightless description of every
12
+ * source that load names — tens of KB each, never the weights — and runs the
13
+ * engine's own fitter against them, reported as `native-fit` evidence. Where
14
+ * that is unavailable the computed floor stands, which can refuse a model but
15
+ * never confirm one.
16
16
  *
17
17
  * @param input - Loads to assess in `loadModel`'s own parameters, the declared
18
18
  * execution mode, and the headroom policy.
@@ -23,11 +23,11 @@ function withModelType(candidate) {
23
23
  * the available evidence does not support a verdict either way, and callers
24
24
  * should treat it as "cannot say", not "no".
25
25
  *
26
- * For a single candidate it fetches the registry's weightless description of
27
- * every source that load names — tens of KB each, never the weights — and runs
28
- * the engine's own fitter against them, reported as `native-fit` evidence.
29
- * Where that is unavailable, and for a set of candidates, the calibrated
30
- * estimate stands.
26
+ * For each candidate it fetches the registry's weightless description of every
27
+ * source that load names — tens of KB each, never the weights — and runs the
28
+ * engine's own fitter against them, reported as `native-fit` evidence. Where
29
+ * that is unavailable the computed floor stands, which can refuse a model but
30
+ * never confirm one.
31
31
  *
32
32
  * @param input - Loads to assess in `loadModel`'s own parameters, the declared
33
33
  * execution mode, and the headroom policy.
@@ -53,7 +53,6 @@ export async function assessModelFit(input) {
53
53
  execution: response.execution,
54
54
  ...(response.evidence && { evidence: response.evidence }),
55
55
  ...(response.budget && { budget: response.budget }),
56
- ...(response.estimate && { estimate: response.estimate }),
57
56
  ...(response.floorBytes !== undefined && { floorBytes: response.floorBytes }),
58
57
  models: response.models,
59
58
  reasons: response.reasons,
@@ -3,15 +3,24 @@ import type { AudioEditClientParams, AudioGenResult } from '@qvac/inference/surf
3
3
  * Edits a source recording with a loaded ACE-Step AudioGen model: an ordered
4
4
  * pipeline of `flow-edit` and `repaint` operations, executed in array order.
5
5
  *
6
- * @param params - Loaded model ID, the source audio, the ordered `operations`, and an optional `seed`.
6
+ * @param params - Loaded model ID, the source audio, the ordered `operations`, and optional
7
+ * run controls that apply to every operation.
7
8
  * @param params.sourceAudio - The recording to edit: a file path (decoded server-side) or raw
8
9
  * interleaved stereo 48 kHz Float32 LE PCM bytes in `[-1, 1]`.
10
+ * @param params.referenceAudio - Optional timbre reference for every operation, in the same forms
11
+ * as `sourceAudio` (samples need only be finite).
12
+ * @param params.vocalLanguage - Prompt metadata for every operation, as on a generation; so are
13
+ * `bpm`, `keyscale`, `timesignature` and `augmentCaptionWithMetadata`.
14
+ * @param params.dcwEnabled - Repaint only: the Haar DCW sampler correction, tuned by `dcwScaler` and
15
+ * `dcwHighScaler`.
16
+ * @param params.inferenceSteps - DiT steps for every operation (0..1000); omit to keep the load-time
17
+ * value. `shift` overrides the load-time timestep shift the same way.
9
18
  * @param params.operations - `flow-edit` re-conditions the whole clip from a `from` prompt to a
10
19
  * `to` prompt over an optional `nMin`/`nMax` diffusion window (turbo DiT variants only);
11
20
  * `repaint` regenerates the `start`..`end` range (seconds) against a new `caption`, keeping the
12
21
  * rest of the clip. Operations may repeat or mix.
13
22
  * @param params.seed - Seeds the first operation; each following operation uses `seed + index`.
14
- * @returns The same run shape as `audioGen()`: a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise.
23
+ * @returns The same run shape as `audioGen()`: a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise. `stats.metadata.seed` reports the base seed the edit used.
15
24
  *
16
25
  * @example
17
26
  * ```typescript
@@ -27,6 +36,9 @@ import type { AudioEditClientParams, AudioGenResult } from '@qvac/inference/surf
27
36
  * { type: "repaint", caption: "analog synth solo", start: 10, end: 20, mode: "balanced" },
28
37
  * ],
29
38
  * seed: 22883,
39
+ * referenceAudio: "/path/to/reference.wav",
40
+ * bpm: 120,
41
+ * keyscale: "C minor",
30
42
  * });
31
43
  * stopButton.onclick = () => cancel({ requestId: run.requestId });
32
44
  * const { pcm, sampleRate, channels, bitsPerSample } = await run.audio;
@@ -4,15 +4,24 @@ import { createAudioEditResult } from './audio-gen-result.js';
4
4
  * Edits a source recording with a loaded ACE-Step AudioGen model: an ordered
5
5
  * pipeline of `flow-edit` and `repaint` operations, executed in array order.
6
6
  *
7
- * @param params - Loaded model ID, the source audio, the ordered `operations`, and an optional `seed`.
7
+ * @param params - Loaded model ID, the source audio, the ordered `operations`, and optional
8
+ * run controls that apply to every operation.
8
9
  * @param params.sourceAudio - The recording to edit: a file path (decoded server-side) or raw
9
10
  * interleaved stereo 48 kHz Float32 LE PCM bytes in `[-1, 1]`.
11
+ * @param params.referenceAudio - Optional timbre reference for every operation, in the same forms
12
+ * as `sourceAudio` (samples need only be finite).
13
+ * @param params.vocalLanguage - Prompt metadata for every operation, as on a generation; so are
14
+ * `bpm`, `keyscale`, `timesignature` and `augmentCaptionWithMetadata`.
15
+ * @param params.dcwEnabled - Repaint only: the Haar DCW sampler correction, tuned by `dcwScaler` and
16
+ * `dcwHighScaler`.
17
+ * @param params.inferenceSteps - DiT steps for every operation (0..1000); omit to keep the load-time
18
+ * value. `shift` overrides the load-time timestep shift the same way.
10
19
  * @param params.operations - `flow-edit` re-conditions the whole clip from a `from` prompt to a
11
20
  * `to` prompt over an optional `nMin`/`nMax` diffusion window (turbo DiT variants only);
12
21
  * `repaint` regenerates the `start`..`end` range (seconds) against a new `caption`, keeping the
13
22
  * rest of the clip. Operations may repeat or mix.
14
23
  * @param params.seed - Seeds the first operation; each following operation uses `seed + index`.
15
- * @returns The same run shape as `audioGen()`: a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise.
24
+ * @returns The same run shape as `audioGen()`: a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise. `stats.metadata.seed` reports the base seed the edit used.
16
25
  *
17
26
  * @example
18
27
  * ```typescript
@@ -28,6 +37,9 @@ import { createAudioEditResult } from './audio-gen-result.js';
28
37
  * { type: "repaint", caption: "analog synth solo", start: 10, end: 20, mode: "balanced" },
29
38
  * ],
30
39
  * seed: 22883,
40
+ * referenceAudio: "/path/to/reference.wav",
41
+ * bpm: 120,
42
+ * keyscale: "C minor",
31
43
  * });
32
44
  * stopButton.onclick = () => cancel({ requestId: run.requestId });
33
45
  * const { pcm, sampleRate, channels, bitsPerSample } = await run.audio;
@@ -22,7 +22,10 @@ import type { AudioGenClientParams, AudioGenResult } from '@qvac/inference/surfa
22
22
  * @param params.track - ACE-Step only: the instrument layer the `"lego"` task regenerates.
23
23
  * Required when `taskType` is `"lego"` and rejected otherwise.
24
24
  * @param params.maxFrames - MiniMax semantic-frame cap; mutually exclusive with `duration`.
25
- * @param params.inferenceSteps - MiniMax flow steps for this run.
25
+ * @param params.inferenceSteps - Diffusion steps for this run (0..1000), on either engine; omit to
26
+ * keep the load-time value.
27
+ * @param params.shift - ACE-Step only: DiT timestep shift for this run; omit to keep the load-time
28
+ * value.
26
29
  * @param params.cfgScale - MiniMax flow classifier-free guidance scale for this run.
27
30
  * @param params.referenceAudio - Optional timbre reference: a file path (decoded server-side)
28
31
  * or raw interleaved stereo 48 kHz Float32 LE PCM bytes.
@@ -31,7 +34,7 @@ import type { AudioGenClientParams, AudioGenResult } from '@qvac/inference/surfa
31
34
  * @param params.taskType - `"text2music"` (default), `"cover-nofsq"`, or `"lego"`.
32
35
  * @param params.audioCoverStrength - Source-context strength for cover tasks (0..1).
33
36
  * @param params.coverNoiseStrength - Initial source/noise blend for cover tasks (0..1).
34
- * @returns A run with a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise describing the backend the run resolved to.
37
+ * @returns A run with a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise describing the backend the run resolved to. An ACE-Step run's stats carry `metadata`: the caption, lyrics and musical metadata it rendered and the seed it used. A MiniMax run's stats carry its stage timings and `emittedFrames`.
35
38
  *
36
39
  * @example
37
40
  * ```typescript
@@ -59,6 +62,7 @@ import type { AudioGenClientParams, AudioGenResult } from '@qvac/inference/surfa
59
62
  * engine: "minimax",
60
63
  * lmModelSrc: "/models/mm3-lm-q8.gguf",
61
64
  * synthModelSrc: "/models/mm3-synth-q8.gguf",
65
+ * device: "gpu", // fail the load instead of falling back to the CPU
62
66
  * },
63
67
  * });
64
68
  * const minimaxRun = audioGen({
@@ -89,6 +93,10 @@ import type { AudioGenClientParams, AudioGenResult } from '@qvac/inference/surfa
89
93
  * });
90
94
  * const { lrc, lyricsScore, qualityScore } = (await assisted.stats) ?? {};
91
95
  *
96
+ * // What the LM composed, and the seed that replays the take:
97
+ * const rendered = (await assisted.stats)?.metadata;
98
+ * console.log(rendered?.caption, rendered?.lyrics, rendered?.bpm, rendered?.seed);
99
+ *
92
100
  * // Rebuild one layer of an existing song:
93
101
  * const newDrums = audioGen({
94
102
  * modelId,
@@ -23,7 +23,10 @@ import { createAudioGenResult } from './audio-gen-result.js';
23
23
  * @param params.track - ACE-Step only: the instrument layer the `"lego"` task regenerates.
24
24
  * Required when `taskType` is `"lego"` and rejected otherwise.
25
25
  * @param params.maxFrames - MiniMax semantic-frame cap; mutually exclusive with `duration`.
26
- * @param params.inferenceSteps - MiniMax flow steps for this run.
26
+ * @param params.inferenceSteps - Diffusion steps for this run (0..1000), on either engine; omit to
27
+ * keep the load-time value.
28
+ * @param params.shift - ACE-Step only: DiT timestep shift for this run; omit to keep the load-time
29
+ * value.
27
30
  * @param params.cfgScale - MiniMax flow classifier-free guidance scale for this run.
28
31
  * @param params.referenceAudio - Optional timbre reference: a file path (decoded server-side)
29
32
  * or raw interleaved stereo 48 kHz Float32 LE PCM bytes.
@@ -32,7 +35,7 @@ import { createAudioGenResult } from './audio-gen-result.js';
32
35
  * @param params.taskType - `"text2music"` (default), `"cover-nofsq"`, or `"lego"`.
33
36
  * @param params.audioCoverStrength - Source-context strength for cover tasks (0..1).
34
37
  * @param params.coverNoiseStrength - Initial source/noise blend for cover tasks (0..1).
35
- * @returns A run with a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise describing the backend the run resolved to.
38
+ * @returns A run with a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise describing the backend the run resolved to. An ACE-Step run's stats carry `metadata`: the caption, lyrics and musical metadata it rendered and the seed it used. A MiniMax run's stats carry its stage timings and `emittedFrames`.
36
39
  *
37
40
  * @example
38
41
  * ```typescript
@@ -60,6 +63,7 @@ import { createAudioGenResult } from './audio-gen-result.js';
60
63
  * engine: "minimax",
61
64
  * lmModelSrc: "/models/mm3-lm-q8.gguf",
62
65
  * synthModelSrc: "/models/mm3-synth-q8.gguf",
66
+ * device: "gpu", // fail the load instead of falling back to the CPU
63
67
  * },
64
68
  * });
65
69
  * const minimaxRun = audioGen({
@@ -90,6 +94,10 @@ import { createAudioGenResult } from './audio-gen-result.js';
90
94
  * });
91
95
  * const { lrc, lyricsScore, qualityScore } = (await assisted.stats) ?? {};
92
96
  *
97
+ * // What the LM composed, and the seed that replays the take:
98
+ * const rendered = (await assisted.stats)?.metadata;
99
+ * console.log(rendered?.caption, rendered?.lyrics, rendered?.bpm, rendered?.seed);
100
+ *
93
101
  * // Rebuild one layer of an existing song:
94
102
  * const newDrums = audioGen({
95
103
  * modelId,
@@ -9,7 +9,7 @@ import type { AudioUnderstandClientParams, AudioUnderstandResult } from '@qvac/i
9
9
  * interleaved stereo 48 kHz Float32 LE PCM bytes in `[-1, 1]`.
10
10
  * @param params.vocalLanguage - Language hint forced into the result instead of the LM's guess.
11
11
  * @param params.seed - Seeds the LM decode; omit for a random seed.
12
- * @returns A synchronous request ID, a progress stream, the `description` promise, and the stats and diagnostics promises.
12
+ * @returns A synchronous request ID, a progress stream, the `description` promise, and the stats and diagnostics promises. `description.seed` is the seed the decode used, so an unseeded description can be reproduced.
13
13
  *
14
14
  * @example
15
15
  * ```typescript
@@ -10,7 +10,7 @@ import { createAudioUnderstandResult } from './audio-gen-result.js';
10
10
  * interleaved stereo 48 kHz Float32 LE PCM bytes in `[-1, 1]`.
11
11
  * @param params.vocalLanguage - Language hint forced into the result instead of the LM's guess.
12
12
  * @param params.seed - Seeds the LM decode; omit for a random seed.
13
- * @returns A synchronous request ID, a progress stream, the `description` promise, and the stats and diagnostics promises.
13
+ * @returns A synchronous request ID, a progress stream, the `description` promise, and the stats and diagnostics promises. `description.seed` is the seed the decode used, so an unseeded description can be reproduced.
14
14
  *
15
15
  * @example
16
16
  * ```typescript