@qvac/sdk 0.20.0 → 0.21.0

package/dist/examples/advisory-model-fit.js

@@ -1,15 +1,16 @@
 /**
- * Advisory llama.cpp fit check (QVAC-22629).
+ * Advisory model fit check.
  *
- * Before a completion or embedding load, the SDK runs `@qvac/model-fit` in one
- * disposable Bare child and projects whether the exact configuration it is
- * about to load will fit in device memory.
+ * Before a load, the SDK runs the fitter belonging to the engine that would
+ * run it and projects whether the exact configuration it is about to load will
+ * fit in device memory. Desktop runs it in a disposable Bare child; mobile,
+ * which cannot spawn one, runs it on a worker thread.
  *
  * The result is ADVISORY. It never blocks a load. `does-not-fit` is logged and
  * the ordinary load path runs unchanged. Crashes, timeouts, malformed
  * responses, unsupported configurations, and internal errors all resolve to
- * "no evidence" and are equally non-blocking. Nothing consumes the verdict
- * yet — this PR only produces it.
+ * "no evidence" and are equally non-blocking. No verdict changes the load;
+ * `getLoadedModelInfo` returns it as `fitProbe`.
  *
  * The verdict is emitted on the SDK server log stream, not to stdout, so this
  * example subscribes to `loggingStream({ id: SDK_LOG_ID })` and reprints the
@@ -19,9 +20,8 @@
  * What fits on this machine (Apple M4 Pro, 24 GiB unified memory)
  * ---------------------------------------------------------------------------
  *
- * Measured with `@qvac/model-fit@0.8.0` (the first release carrying the
- * qvac-fabric#214 memory-reporting fix) at the default 1024 MiB margin. The
- * fitter budgets against what the machine can actually keep resident
+ * Measured at the default 1024 MiB margin. The fitter budgets against what the
+ * machine can actually keep resident
  * (total − wired − compressor: 17.4 GiB on this machine at idle), not the raw
  * RAM figure.
  *
@@ -30,10 +30,12 @@
  *     gpt-oss-20B   Q4_K_M  10.8 GiB  @  32k ctx
  *     gte-large     fp16     0.6 GiB  (embedding, context pinned to 512)
  *
- *   PROJECTED NOT TO FIT — try any of these to see a `does-not-fit` verdict
+ *   PROJECTED NOT TO FIT — with `gpu_layers: 99` pinned
  *     gpt-oss-20B   Q4_K_M  10.8 GiB  @ 128k ctx with an f32 KV cache ← below
- *     Gemma 4 31B   Q4_K_M  18.3 GiB  @   1k ctx   ← the weights alone do not
- *                                                    fit with gpu_layers: 99
+ *
+ * These rows were measured with `gpu_layers` pinned at 99. Loads no longer pin
+ * the layer count, and the `does-not-fit` row has not been re-measured
+ * unpinned.
  *
  * gpt-oss-20B at 128k context FITS with the default KV cache and DOES NOT FIT
  * once `cache-type-k`/`cache-type-v` are set to `f32`. Same model, same
@@ -42,10 +44,9 @@
  *
  * Two boundaries worth understanding when reading verdicts:
  *
- * 1. The verdict answers for a PLACEMENT, not a model. The SDK's schema
- *    default is `gpu_layers: 99` ("everything on the GPU"), so `does-not-fit`
- *    means "not at this placement". Omit `gpu_layers` and the fitter is free
- *    to move layers to the CPU side instead.
+ * 1. The verdict answers for a PLACEMENT, not a model. With `gpu_layers`
+ *    unset, the fitter may move layers to the CPU side; setting it pins the
+ *    layer count, and `does-not-fit` then means "not at this placement".
  * 2. A `does-not-fit` configuration can still RUN on macOS when the OS
  *    compresses and pages hard enough — and a `fits` configuration right at
  *    the boundary can still fail at first decode under memory pressure.
@@ -98,8 +99,7 @@ try {
     // Unloaded before the next phase, so the second verdict is measured on an
     // idle machine and stays comparable to the fixture tables above. Leaving it
     // loaded would shift the verdict: the check reserves resident weight bytes
-    // through the fit margin, and since model-fit 0.8.0 the fit child also sees
-    // system-wide wired memory.
+    // through the fit margin, and the fitter also sees system-wide wired memory.
     await unloadModel({ modelId: smallModelId, clearStorage: false });
     watchVerdicts();
     // 2. A load the fitter projects NOT to fit. The point of this example is that

package/dist/examples/asr/parakeet-indic-conformer-filesystem.js

@@ -4,14 +4,14 @@
  * Usage:
  *   bun run examples/asr/parakeet-indic-conformer-filesystem.ts <wav-file> <language> [gguf]
  *
- * Loads a single GGUF checkpoint (`PARAKEET_INDIC_CONFORMER_CTC_Q8_0` by
+ * Loads a single GGUF checkpoint (`PARAKEET_INDIC_CONFORMER_600M_Q8_0` by
  * default) and transcribes with the batch `transcribe` API. `language` is
  * required (e.g. `hi`, `ta`) because Indic Conformer CTC masks the vocab
  * with `parakeet.ctc.lang_*` ranges. English Parakeet CTC ignores this field.
  *
  * Audio should be 16 kHz mono PCM in a WAV container.
  */
-import { loadModel, unloadModel, transcribe, PARAKEET_INDIC_CONFORMER_CTC_Q8_0 } from '@qvac/sdk';
+import { loadModel, unloadModel, transcribe, PARAKEET_INDIC_CONFORMER_600M_Q8_0 } from '@qvac/sdk';
 const args = process.argv.slice(2);
 if (!args[0] || !args[1]) {
     console.error('Usage: bun run examples/asr/parakeet-indic-conformer-filesystem.ts ' +
@@ -22,7 +22,7 @@ if (!args[0] || !args[1]) {
 }
 const audioFilePath = args[0];
 const language = args[1];
-const parakeetModelSrc = args[2] ?? PARAKEET_INDIC_CONFORMER_CTC_Q8_0;
+const parakeetModelSrc = args[2] ?? PARAKEET_INDIC_CONFORMER_600M_Q8_0;
 try {
     console.log('▸ Loading Indic Conformer CTC model...');
     const modelId = await loadModel({

package/dist/examples/asr/parakeet-unified-coreml.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=parakeet-unified-coreml.d.ts.map

package/dist/examples/asr/parakeet-unified-coreml.js

@@ -0,0 +1,113 @@
+/**
+ * Transcribe a WAV file with Parakeet Unified and its Core ML encoder sidecar.
+ *
+ * From packages/sdk:
+ *   bun run examples/asr/parakeet-unified-coreml.ts \
+ *     /path/to/parakeet-unified-en-0.6b.q4_0.gguf [16-kHz-wav-file]
+ *
+ * The GGUF must be a regenerated Unified artifact. The five compiled Core ML
+ * files are downloaded through the SDK registry and staged beside the GGUF.
+ * The default audio is examples/audio/sample-16khz.wav.
+ */
+import { downloadAsset, getModelInfo, loadModel, transcribe, unloadModel } from '@qvac/sdk';
+import { link, mkdir, mkdtemp, open, rm, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const MODEL_STEM = 'parakeet-unified-en-0.6b';
+const COREML_FILES = [
+    ['PARAKEET_UNIFIED_COREMLDATA', 'analytics/coremldata.bin'],
+    ['PARAKEET_UNIFIED_COREMLDATA_1', 'coremldata.bin'],
+    ['PARAKEET_UNIFIED_METADATA', 'metadata.json'],
+    ['PARAKEET_UNIFIED_MODEL', 'model.mil'],
+    ['PARAKEET_UNIFIED_WEIGHT', 'weights/weight.bin']
+];
+const defaultAudioPath = fileURLToPath(new URL('../audio/sample-16khz.wav', import.meta.url));
+const modelPath = process.argv[2];
+const audioPath = process.argv[3] ?? defaultAudioPath;
+async function checkModel(path) {
+    const name = basename(path);
+    if (!/^parakeet-unified-en-0\.6b\.(?:f16|q4_0|q8_0)\.gguf$/.test(name)) {
+        throw new Error(`Expected a regenerated Unified GGUF, got: ${name}`);
+    }
+    const file = await open(path, 'r');
+    try {
+        const header = Buffer.alloc(1024 * 1024);
+        const { bytesRead } = await file.read(header, 0, header.length, 0);
+        if (!header.subarray(0, bytesRead).includes('parakeet.unified.left_context_frames')) {
+            throw new Error(`Unified GGUF lacks the new streaming metadata: ${path}`);
+        }
+    }
+    finally {
+        await file.close();
+    }
+}
+async function stageModel(path) {
+    if (process.platform !== 'darwin')
+        throw new Error('Core ML requires macOS');
+    await checkModel(path);
+    const dir = await mkdtemp(join(tmpdir(), 'qvac-unified-coreml-'));
+    try {
+        const modelSrc = join(dir, basename(path));
+        await symlink(resolve(path), modelSrc);
+        const bundleDir = join(dir, `${MODEL_STEM}-encoder.mlmodelc`);
+        for (const [name, relativePath] of COREML_FILES) {
+            const info = await getModelInfo({ name });
+            if (!info.isCached) {
+                if (!info.registrySource || !info.registryPath) {
+                    throw new Error(`Registry location missing for ${name}`);
+                }
+                console.log(`▸ Downloading Core ML ${relativePath}...`);
+                await downloadAsset({ assetSrc: `registry://${info.registrySource}/${info.registryPath}` });
+            }
+            const cached = await getModelInfo({ name });
+            const sourcePath = cached.cacheFiles.find((file) => file.isCached)?.path;
+            if (!sourcePath)
+                throw new Error(`Core ML file is missing from the SDK cache: ${name}`);
+            const targetPath = join(bundleDir, relativePath);
+            await mkdir(join(targetPath, '..'), { recursive: true });
+            await link(sourcePath, targetPath);
+        }
+        return { modelSrc, dir };
+    }
+    catch (error) {
+        await rm(dir, { recursive: true, force: true });
+        throw error;
+    }
+}
+async function main() {
+    if (!modelPath) {
+        throw new Error('Usage: bun run examples/asr/parakeet-unified-coreml.ts ' +
+            '<regenerated-unified-gguf> [16-kHz-wav-file]');
+    }
+    let staged;
+    let modelId;
+    try {
+        staged = await stageModel(modelPath);
+        console.log('▸ Loading Parakeet Unified with its Core ML encoder sidecar...');
+        modelId = await loadModel({
+            modelSrc: staged.modelSrc,
+            modelType: 'parakeet-transcription',
+            modelConfig: { useGPU: true }
+        });
+        console.log('▸ Transcribing audio...');
+        const text = await transcribe({ modelId, audioChunk: audioPath });
+        if (!text.trim())
+            throw new Error('Parakeet Unified returned an empty transcription');
+        console.log(text);
+    }
+    finally {
+        try {
+            if (modelId)
+                await unloadModel({ modelId });
+        }
+        finally {
+            if (staged)
+                await rm(staged.dir, { recursive: true, force: true });
+        }
+    }
+}
+main().catch((error) => {
+    console.error('✖', error);
+    process.exitCode = 1;
+});

package/dist/examples/assess-model-fit.js

@@ -11,8 +11,9 @@
  * call either way. Show it as "can't say", never as "no".
  */
 import { assessModelFit, QWEN3_600M_INST_Q4, QWEN3_1_7B_INST_Q4, QWEN3_4B_INST_Q4_K_M, QWEN3_8B_INST_Q4_K_M, QWEN3_8_27B_MULTIMODAL_UD_Q8_K_XL } from '@qvac/sdk';
-// `as const` so `kind` stays the `'llm'` literal the input type asks for.
-const WORKLOAD = { kind: 'llm', contextTokens: 8192 };
+// Sizes the assessment the way it sizes the load: the estimator reads the
+// context out of the config `loadModel` would be given.
+const CONTEXT_TOKENS = 8192;
 // A ladder ending well past what a laptop has, so one screen shows every verdict.
 const CANDIDATES = [
     QWEN3_600M_INST_Q4,
@@ -31,7 +32,11 @@ function gib(bytes) {
 }
 try {
     const result = await assessModelFit({
-        models: CANDIDATES.map((model) => ({ model, workload: WORKLOAD })),
+        models: CANDIDATES.map((model) => ({
+            modelSrc: model,
+            modelType: 'llamacpp-completion',
+            modelConfig: { ctx_size: CONTEXT_TOKENS }
+        })),
         // Declared for aggregation only, not a scheduling instruction: 'sequential'
         // counts the largest operation peak, 'concurrent' counts one per model.
         execution: 'sequential',
@@ -49,7 +54,7 @@ try {
     const placement = result.assumptions.find((line) => line.includes('assumed to execute on'));
     if (placement)
         console.log(`▸ ${placement}`);
-    console.log(`\n▸ At ${WORKLOAD.contextTokens} tokens of context`);
+    console.log(`\n▸ At ${CONTEXT_TOKENS} tokens of context`);
     for (const [index, model] of result.models.entries()) {
         const mark = VERDICT_MARK[model.verdict];
         const size = gib(CANDIDATES[index].expectedSize).padStart(9);

package/dist/examples/model-fit-ui/server.js

@@ -102,9 +102,12 @@ function sendJson(response, status, payload) {
 async function estimate(body) {
     const names = Array.isArray(body['names']) ? body['names'] : [];
     const contextTokens = Number(body['contextTokens'] ?? 8192);
-    const workload = { kind: 'llm', contextTokens };
     return assessModelFit({
-        models: names.map((name) => ({ model: byName(name), workload })),
+        models: names.map((name) => ({
+            modelSrc: byName(name),
+            modelType: 'llamacpp-completion',
+            modelConfig: { ctx_size: contextTokens }
+        })),
         // Declared for aggregation only. 'sequential' counts the largest operation
         // peak; 'concurrent' counts one per model.
         execution: 'sequential',

package/dist/examples/rpc-inference.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rpc-inference.d.ts.map

package/dist/examples/rpc-inference.js

@@ -0,0 +1,51 @@
+// npx tsx rpc-inference.ts my-private-rpc-group
+import { discoverRpcServers, getRpcDeviceMap, loadModel, completion, unloadModel, close, LLAMA_3_2_1B_INST_Q4_0 } from '@qvac/sdk';
+try {
+    const topic = process.argv[2];
+    if (!topic)
+        throw new Error('Usage: rpc-inference.ts <topic>');
+    // Prefer server RDMA offers before assigning aliases. Transport is negotiated at load time.
+    const selected = (await discoverRpcServers({ topic, timeoutMs: 5000 }))
+        .sort((a, b) => Number(b.rdmaAvailable) - Number(a.rdmaAvailable) || a.url.localeCompare(b.url))
+        .slice(0, 2);
+    if (selected.length !== 2)
+        throw new Error('Two idle RPC servers are required');
+    const devices = getRpcDeviceMap(selected);
+    if (!devices.length)
+        throw new Error('The selected servers expose no devices');
+    console.error(`▸ Using ${devices.length} devices across ${selected.length} servers`);
+    const modelId = await loadModel({
+        modelSrc: LLAMA_3_2_1B_INST_Q4_0,
+        modelConfig: {
+            device: 'gpu',
+            'rpc-servers': selected.map((server) => server.url).join(','),
+            devices: devices.map((device) => device.alias).join(','),
+            'split-mode': 'layer',
+            'tensor-split': devices.map(() => '1').join(',')
+        },
+        onProgress: (progress) => {
+            process.stderr.write(`\r▸ Downloading ${progress.percentage.toFixed(0)}%`);
+        }
+    });
+    try {
+        process.stderr.write('\n');
+        const run = completion({
+            modelId,
+            history: [{ role: 'user', content: 'Explain distributed inference in one sentence.' }],
+            stream: true
+        });
+        for await (const token of run.tokenStream)
+            process.stdout.write(token);
+        process.stdout.write('\n');
+    }
+    finally {
+        await unloadModel({ modelId });
+    }
+}
+catch (error) {
+    console.error('✖', error);
+    process.exitCode = 1;
+}
+finally {
+    await close();
+}

package/dist/examples/rpc-server.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rpc-server.d.ts.map

package/dist/examples/rpc-server.js

@@ -0,0 +1,32 @@
+// Rebuild the worker with
+// rpcServerProvider: '@qvac/sdk/ggml-rpc-server/provider' in qvac.config.json.
+// npx tsx rpc-server.ts 10.0.0.2 my-private-rpc-group
+import { createInterface } from 'node:readline/promises';
+import { startRpcServer, stopRpcServer, close } from '@qvac/sdk';
+try {
+    const host = process.argv[2];
+    const topic = process.argv[3];
+    if (!host || !topic)
+        throw new Error('Usage: rpc-server.ts <private-ipv4> <topic>');
+    const server = await startRpcServer({
+        host,
+        allowNonLoopbackHost: true,
+        discoveryTopic: topic
+    });
+    const input = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        console.error(`▸ Serving ${server.url}; RDMA capable: ${server.rdmaCapable}`);
+        await input.question('▸ Press Enter to stop after clients unload their models.\n');
+    }
+    finally {
+        input.close();
+        await stopRpcServer({ serverId: server.serverId });
+    }
+}
+catch (error) {
+    console.error('✖', error);
+    process.exitCode = 1;
+}
+finally {
+    await close();
+}

package/dist/examples/tools/llamacpp-deferred-tools.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=llamacpp-deferred-tools.d.ts.map

package/dist/examples/tools/llamacpp-deferred-tools.js

@@ -0,0 +1,77 @@
+// Deferred tool loading: a large tool set stays out of the prompt until the
+// model asks for it. Only `get_weather` and the built-in `tool_search` (whose
+// description carries a name-and-description catalog of the rest) are in the
+// initial prompt; the deferred schemas arrive in the conversation when the
+// model searches for them.
+import { TOOL_SEARCH_NAME, completion, executeToolSearch, loadModel, unloadModel, QWEN3_1_7B_INST_Q4 } from '@qvac/sdk';
+import { z } from 'zod';
+import { weatherSchema, horoscopeSchema, mockExecute } from './shared.js';
+const tools = [
+    {
+        name: 'get_weather',
+        description: 'Get current weather for a city',
+        parameters: weatherSchema
+    },
+    {
+        name: 'get_horoscope',
+        description: "Get today's horoscope for an astrological sign",
+        parameters: horoscopeSchema,
+        deferLoading: true,
+        group: 'astrology'
+    },
+    {
+        name: 'get_moon_phase',
+        description: 'Get the current phase of the moon',
+        parameters: z.object({ date: z.string().describe('ISO date').optional() }),
+        deferLoading: true,
+        group: 'astrology'
+    }
+];
+try {
+    const modelId = await loadModel({
+        modelSrc: QWEN3_1_7B_INST_Q4,
+        modelConfig: { ctx_size: 4096, tools: true }
+    });
+    console.log(`▸ Model loaded. Model ID: ${modelId}`);
+    const history = [
+        {
+            role: 'system',
+            content: 'You are a helpful assistant. Search for a tool before calling it.'
+        },
+        { role: 'user', content: "What's my horoscope for Aquarius?" }
+    ];
+    console.log('\n▸ Turn 1 — only get_weather and tool_search are in the prompt\n');
+    const first = completion({ modelId, history, stream: true, tools });
+    for await (const token of first.tokenStream)
+        process.stdout.write(token);
+    const calls = await first.toolCalls;
+    const search = calls.find((call) => call.name === TOOL_SEARCH_NAME);
+    if (!search) {
+        console.log('\n\n▸ The model answered without searching; nothing more to show.');
+    }
+    else {
+        console.log(`\n\n▸ The model searched: ${JSON.stringify(search.arguments)}`);
+        // Running the search is the SDK's job, not a tool handler's. The result is
+        // an ordinary tool message: appending it is what makes the definitions
+        // callable on the next turn.
+        history.push({ role: 'assistant', content: await first.text });
+        history.push({
+            role: 'tool',
+            content: executeToolSearch(tools, search.arguments, history)
+        });
+        console.log('▸ Definitions appended. Turn 2 — the model can now call them directly.\n');
+        const second = completion({ modelId, history, stream: true, tools });
+        for await (const token of second.tokenStream)
+            process.stdout.write(token);
+        for (const call of await second.toolCalls) {
+            console.log(`\n\n▸ Tool call: ${call.name}(${JSON.stringify(call.arguments)})`);
+            console.log(`▸ Result: ${mockExecute(call.name, call.arguments)}`);
+        }
+    }
+    console.log('\n\n▸ Completed!');
+    await unloadModel({ modelId, clearStorage: false });
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/examples/tts/audio8.js

@@ -4,6 +4,8 @@ import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './uti
 // primary modelSrc is the LM GGUF; the codec decoder loads via modelConfig.
 // For zero-shot voice cloning also pass audio8CodecEncoderModelSrc plus
 // referenceAudioSrc/referenceText (a recording and its exact transcript).
+// On macOS and iOS the decoder downloads with its Core ML bundle, which runs
+// the codec's synthesis stack; `stats.codecOnCoreml` reports whether it did.
 // Only a fallback: the engine reports the rate it actually produced, and
 // `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const AUDIO8_SAMPLE_RATE = 44100;
@@ -35,7 +37,9 @@ try {
     });
     const audioBuffer = await result.buffer;
     const sampleRate = (await result.sampleRate) ?? AUDIO8_SAMPLE_RATE;
+    const stats = await result.stats;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
+    console.log(`▸ Codec ran on ${stats?.codecOnCoreml === 1 ? 'Core ML' : 'ggml'}`);
     console.log('▸ Saving audio to file...');
     createWav(audioBuffer, sampleRate, 'audio8-output.wav');
     console.log('▸ Audio saved to audio8-output.wav');

package/dist/examples/tts/moss-dialogue.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=moss-dialogue.d.ts.map

package/dist/examples/tts/moss-dialogue.js

@@ -0,0 +1,63 @@
+import { loadModel, textToSpeech, unloadModel, TTS_CODEC_DECODER_MOSS_TTS_F16, TTS_CODEC_ENCODER_MOSS_TTS_F16 } from '@qvac/sdk';
+import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './utils.js';
+// MOSS-TTSD (GGML): multi-speaker dialogue in one pass, each voice cloned from
+// a 24 kHz reference recording. The model continues the references, so the
+// text opens with what each recording says under its speaker tag, followed by
+// the lines to generate; only the new lines come out as audio. A dialogue is
+// never split into sentences, so `stream: true` delivers the native chunks of
+// the whole conversation (set `streamChunkTokens` to get them while it is
+// still being generated).
+//
+// The MOSS-TTSD backbone is not in the QVAC Registry yet, so it is a local
+// file; the codec halves it shares with MOSS-TTS download from the registry.
+// Usage: node moss-dialogue.ts <moss-ttsd.gguf> <s1.wav> "<s1 transcript>" <s2.wav> "<s2 transcript>"
+const [backbone, s1Audio, s1Text, s2Audio, s2Text] = process.argv.slice(2);
+if (!backbone || !s1Audio || !s1Text || !s2Audio || !s2Text) {
+    console.error('Usage: node moss-dialogue.ts <moss-ttsd.gguf> <s1.wav> "<s1 transcript>" <s2.wav> "<s2 transcript>"');
+    process.exit(1);
+}
+// Only a fallback: the engine reports the rate it actually produced.
+const MOSS_SAMPLE_RATE = 24000;
+try {
+    const modelId = await loadModel({
+        modelSrc: backbone,
+        modelType: 'tts-ggml',
+        modelConfig: {
+            ttsEngine: 'moss',
+            language: 'en',
+            mossCodecDecoderModelSrc: TTS_CODEC_DECODER_MOSS_TTS_F16,
+            mossCodecEncoderModelSrc: TTS_CODEC_ENCODER_MOSS_TTS_F16,
+            // One recording per speaker, in the order the text tags them.
+            dialogueReferenceSrcs: [s1Audio, s2Audio],
+            streamChunkTokens: 25,
+            useGPU: true
+        }
+    });
+    console.log(`▸ Model loaded: ${modelId}`);
+    console.log('▸ Synthesizing the dialogue...');
+    const result = textToSpeech({
+        modelId,
+        text: `[S1] ${s1Text} [S2] ${s2Text} ` +
+            '[S1] Did the build finish? [S2] Yes, every test passed. [S1] Great, ship it.',
+        stream: true
+    });
+    const samples = [];
+    for await (const sample of result.bufferStream)
+        samples.push(sample);
+    const sampleRate = (await result.sampleRate) ?? MOSS_SAMPLE_RATE;
+    console.log(`▸ Dialogue complete: ${samples.length} samples`);
+    createWav(samples, sampleRate, 'moss-dialogue-output.wav');
+    console.log('▸ Audio saved to moss-dialogue-output.wav');
+    console.log('▸ Playing audio...');
+    const audioData = int16ArrayToBuffer(samples);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
+    playAudio(wavBuffer);
+    console.log('▸ Audio playback complete');
+    await unloadModel({ modelId });
+    console.log('▸ Model unloaded');
+    process.exit(0);
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/examples/tts/moss.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=moss.d.ts.map

package/dist/examples/tts/moss.js

@@ -0,0 +1,71 @@
+import { loadModel, textToSpeech, unloadModel, TTS_DELAY_LLM_MOSS_TTS_F16, TTS_CODEC_DECODER_MOSS_TTS_F16, TTS_CODEC_ENCODER_MOSS_TTS_F16 } from '@qvac/sdk';
+import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './utils.js';
+// MOSS (GGML): OpenMOSS MOSS-TTS v1.5 Delay, an 8B backbone (about 17 GB)
+// plus a codec, so desktop only. The primary modelSrc is the backbone; the
+// codec decoder loads via modelConfig, and the codec encoder is only needed to
+// clone a voice from a 24 kHz reference recording (no transcript needed).
+//
+// MOSS streams natively: with `streamChunkTokens` set, `stream: true` emits a
+// chunk every that-many codec frames (12.5 per second) while the backbone is
+// still generating, and the text is synthesized as one utterance, so the
+// `[pause 1.0s]` marker below and `durationTokens` apply to all of it.
+//
+// Uses registry model constants — downloads automatically from QVAC Registry.
+// Usage: node moss.ts [referenceAudio.wav]
+const [referenceAudioSrc] = process.argv.slice(2);
+// Only a fallback: the engine reports the rate it actually produced.
+const MOSS_SAMPLE_RATE = 24000;
+try {
+    const modelId = await loadModel({
+        modelSrc: TTS_DELAY_LLM_MOSS_TTS_F16,
+        modelConfig: {
+            ttsEngine: 'moss',
+            language: 'en',
+            mossCodecDecoderModelSrc: TTS_CODEC_DECODER_MOSS_TTS_F16,
+            ...(referenceAudioSrc
+                ? { mossCodecEncoderModelSrc: TTS_CODEC_ENCODER_MOSS_TTS_F16, referenceAudioSrc }
+                : {}),
+            streamChunkTokens: 25,
+            useGPU: true,
+            seed: 7
+        },
+        onProgress: (p) => {
+            const mb = (n) => (n / 1e6).toFixed(1);
+            const line = `▸ Downloading ${p.percentage.toFixed(0)}% (${mb(p.downloaded)}/${mb(p.total)} MB)`;
+            process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
+            if (p.percentage >= 100)
+                process.stderr.write('\n');
+        }
+    });
+    console.log(`▸ Model loaded: ${modelId}`);
+    console.log('▸ Streaming MOSS Text-to-Speech...');
+    const started = Date.now();
+    const result = textToSpeech({
+        modelId,
+        text: 'Hold on [pause 1.0s] here it comes: speech that starts playing while the rest is still being generated.',
+        stream: true
+    });
+    const samples = [];
+    for await (const sample of result.bufferStream) {
+        if (samples.length === 0)
+            console.log(`▸ First audio after ${Date.now() - started} ms`);
+        samples.push(sample);
+    }
+    const sampleRate = (await result.sampleRate) ?? MOSS_SAMPLE_RATE;
+    const stats = await result.stats;
+    console.log(`▸ TTS complete: ${samples.length} samples, ${stats?.generatedFrames ?? '?'} codec frames, RTF ${stats?.realTimeFactor?.toFixed(2) ?? '?'}`);
+    createWav(samples, sampleRate, 'moss-output.wav');
+    console.log('▸ Audio saved to moss-output.wav');
+    console.log('▸ Playing audio...');
+    const audioData = int16ArrayToBuffer(samples);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
+    playAudio(wavBuffer);
+    console.log('▸ Audio playback complete');
+    await unloadModel({ modelId });
+    console.log('▸ Model unloaded');
+    process.exit(0);
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/scripts/contract/build-contract.d.ts

@@ -20,7 +20,7 @@ export declare function buildContract(): {
                 condition: string;
                 responseSchema: string;
             };
-            name: "audioGenStream" | "audioEditStream" | "audioUnderstand" | "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";
+            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";
             callShape: "duplex" | "request-reply" | "server-stream";
             requestSchema: string;
             responseSchema: string;
@@ -33,6 +33,7 @@ export declare function renderContractFiles(): Promise<{
     'models.json': string;
     'model-type-maps.json': string;
     'error-codes.json': string;
+    'numeric-constants.json': string;
 }>;
 export {};
 //# sourceMappingURL=build-contract.d.ts.map

package/dist/scripts/contract/build-contract.js

@@ -7,6 +7,7 @@ import { constantsRegistry } from './constants-registry.js';
 import { buildModelsRegistry } from './build-models-registry.js';
 import { buildModelTypeMaps } from './build-model-type-maps.js';
 import { buildErrorCodes } from './build-error-codes.js';
+import { buildNumericConstants } from './build-numeric-constants.js';
 export const contractDir = new URL('../../contract/', import.meta.url);
 export const callShapeByHandlerType = {
     reply: 'request-reply',
@@ -610,11 +611,13 @@ export async function renderContractFiles() {
     const modelsRegistry = buildModelsRegistry();
     const modelTypeMaps = buildModelTypeMaps();
     const errorCodes = buildErrorCodes();
+    const numericConstants = buildNumericConstants();
     return {
         'schema.json': await formatJson(schemaDocument, 'schema.json'),
         'manifest.json': await formatJson(manifest, 'manifest.json'),
         'models.json': await formatJson(modelsRegistry, 'models.json'),
         'model-type-maps.json': await formatJson(modelTypeMaps, 'model-type-maps.json'),
-        'error-codes.json': await formatJson(errorCodes, 'error-codes.json')
+        'error-codes.json': await formatJson(errorCodes, 'error-codes.json'),
+        'numeric-constants.json': await formatJson(numericConstants, 'numeric-constants.json')
     };
 }