@qvac/sdk 0.18.2 → 0.19.1

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

@@ -0,0 +1,218 @@
+/**
+ * Demo: assessModelFit's verdict next to what actually happens.
+ *
+ * Serves a page listing catalog models with two buttons. "Estimate" calls
+ * `assessModelFit` — no weights, no load. "Run" loads the model for real and
+ * runs one completion, so the verdict can be checked against the outcome.
+ *
+ * Expect `likely-too-large` to mean "will not go well" rather than "will not
+ * load": an OS with swap usually runs it anyway. Measured here, a 1.7B called
+ * too-large took 519s against 7.8s for a 600M called fits — same 32 tokens.
+ * The verdict is about the interactive budget, not about whether the load
+ * throws.
+ *
+ * Memory is read through `getSystemResources`, not `process.memoryUsage()`:
+ * inference runs in a spawned worker, so this process's own RSS never sees the
+ * model. The numbers are therefore system-wide and include whatever else the
+ * machine is doing — fine for a demo, not a measurement.
+ *
+ * Run (Node or Bun, not Bare — this uses node:http):
+ *   bun run examples/model-fit-ui/server.ts
+ *   node dist/examples/model-fit-ui/server.js
+ */
+import { createServer } from 'node:http';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { assessModelFit, getSystemResources, loadModel, unloadModel, completion, close, QWEN3_600M_INST_Q4, QWEN3_1_7B_INST_Q4, QWEN3_4B_INST_Q4_K_M, QWEN3_8B_INST_Q4_K_M, GEMMA4_31B_MULTIMODAL_Q4_K_M } from '@qvac/sdk';
+const PORT = 8712;
+// A ladder ending past what a laptop has, so one screen shows every verdict.
+// The 31B is here to be refused: 18 GiB against a 24 GiB machine leaves the OS
+// no way to satisfy it without paging.
+const CATALOG = [
+    QWEN3_600M_INST_Q4,
+    QWEN3_1_7B_INST_Q4,
+    QWEN3_4B_INST_Q4_K_M,
+    QWEN3_8B_INST_Q4_K_M,
+    GEMMA4_31B_MULTIMODAL_Q4_K_M
+];
+const PAGE_PATH = new URL('index.html', import.meta.url);
+// Read per request, not once at startup: editing the page and reloading is the
+// normal way to poke at this, and a cached copy makes that silently not work.
+function page() {
+    return readFileSync(PAGE_PATH);
+}
+// Download progress for a run in flight. `loadModel` only streams it when
+// `onProgress` is passed, and without it a 29 GiB download, a stall and a dead
+// worker all look identical from the browser: "loading…" forever.
+const progress = new Map();
+// Whether the weights are already on disk, so a Run costs no download. The
+// cache layout is not API, so this matches on file size — enough to label a
+// button, and it errs towards promising a download that may not happen.
+function cachedSizes() {
+    try {
+        const dir = join(homedir(), '.qvac', 'models');
+        return new Set(readdirSync(dir).map((file) => statSync(join(dir, file)).size));
+    }
+    catch {
+        return new Set();
+    }
+}
+function byName(name) {
+    const model = CATALOG.find((entry) => entry.name === name);
+    if (!model)
+        throw new Error(`unknown model: ${name}`);
+    return model;
+}
+async function systemUsedBytes() {
+    const resources = await getSystemResources({ sample: true });
+    const used = resources.sample?.memory.usedBytes;
+    return used?.status === 'supported' ? used.value : undefined;
+}
+function readBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        request.on('data', (chunk) => chunks.push(chunk));
+        request.on('error', reject);
+        request.on('end', () => {
+            try {
+                resolve(chunks.length > 0 ? JSON.parse(Buffer.concat(chunks).toString()) : {});
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    });
+}
+// The demo reports which error happened, never its message: a message can carry
+// a path or a host detail, and this server answers a browser. The full error
+// goes to the console, where the person running the demo can read it.
+function errorLabel(error) {
+    console.error(error);
+    if (!(error instanceof Error))
+        return 'unknown error';
+    const code = error.code;
+    return typeof code === 'number' ? `${error.name} (${code})` : error.name;
+}
+function sendJson(response, status, payload) {
+    const body = JSON.stringify(payload);
+    response.writeHead(status, { 'content-type': 'application/json' });
+    response.end(body);
+}
+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 })),
+        // Declared for aggregation only. 'sequential' counts the largest operation
+        // peak; 'concurrent' counts one per model.
+        execution: 'sequential',
+        policy: 'interactive-v1'
+    });
+}
+/** Loads for real, generates a few tokens, unloads. The reality check. */
+async function run(body) {
+    const model = byName(String(body['name']));
+    const contextTokens = Number(body['contextTokens'] ?? 8192);
+    const startedAt = Date.now();
+    const before = await systemUsedBytes();
+    let modelId;
+    try {
+        modelId = await loadModel({
+            modelSrc: model,
+            modelType: 'llm',
+            modelConfig: { ctx_size: contextTokens },
+            onProgress: (update) => {
+                progress.set(model.name, {
+                    percentage: update.percentage,
+                    downloaded: update.downloaded,
+                    total: update.total,
+                    at: Date.now()
+                });
+            }
+        });
+        const afterLoad = await systemUsedBytes();
+        const result = completion({
+            modelId,
+            history: [{ role: 'user', content: 'Reply with one short sentence about maps.' }],
+            stream: false,
+            generationParams: { predict: 32 }
+        });
+        const final = await result.final;
+        return {
+            ok: true,
+            elapsedMs: Date.now() - startedAt,
+            systemUsedBeforeBytes: before,
+            systemUsedAfterLoadBytes: afterLoad,
+            backendDevice: final.stats?.backendDevice,
+            // The engine's own numbers for the run: tokens/s, time to first token,
+            // token counts. Worth showing next to the memory figures.
+            stats: final.stats,
+            // `cacheableAssistantContent` is the same text with <think> blocks
+            // stripped; a reasoning model otherwise leads with its scratchpad.
+            sample: (final.cacheableAssistantContent ?? final.contentText).trim().slice(0, 160) ||
+                '(no plain text — the model returned reasoning only)'
+        };
+    }
+    catch (error) {
+        // The interesting negative case: the estimate said too large, and the load
+        // proves it. Report it as a result, not a crash.
+        return {
+            ok: false,
+            elapsedMs: Date.now() - startedAt,
+            systemUsedBeforeBytes: before,
+            error: errorLabel(error)
+        };
+    }
+    finally {
+        progress.delete(model.name);
+        if (modelId)
+            await unloadModel({ modelId }).catch(() => { });
+    }
+}
+const server = createServer((request, response) => {
+    const url = request.url ?? '/';
+    if (request.method === 'GET' && (url === '/' || url.startsWith('/?'))) {
+        response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+        response.end(page());
+        return;
+    }
+    // Polled while a run is in flight; `at` lets the page say "no progress for
+    // 30s" instead of implying the download is still moving.
+    if (request.method === 'GET' && url === '/api/progress') {
+        sendJson(response, 200, Object.fromEntries(progress));
+        return;
+    }
+    if (request.method === 'GET' && url === '/api/models') {
+        const sizes = cachedSizes();
+        sendJson(response, 200, CATALOG.map((model) => ({
+            name: model.name,
+            expectedSize: model.expectedSize,
+            cached: sizes.has(model.expectedSize)
+        })));
+        return;
+    }
+    if (request.method === 'POST' && (url === '/api/assess' || url === '/api/run')) {
+        readBody(request)
+            .then(async (body) => (url === '/api/assess' ? await estimate(body) : await run(body)))
+            .then((payload) => sendJson(response, 200, payload))
+            .catch((error) => {
+            sendJson(response, 500, { error: errorLabel(error) });
+        });
+        return;
+    }
+    sendJson(response, 404, { error: 'not found' });
+});
+server.listen(PORT, () => {
+    console.log(`▸ assessModelFit demo on http://localhost:${PORT}`);
+    console.log('▸ "Run" downloads weights on first use — the 8B is ~4.7 GiB.');
+});
+for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, () => {
+        server.close();
+        close()
+            .catch(() => { })
+            .finally(() => process.exit(0));
+    });
+}

package/dist/examples/multi-job-completion.d.ts

@@ -17,9 +17,8 @@
  *  - `requestId`  — cancel just this call with `cancel({ requestId })`; peers
  *                   keep decoding.
  *
- * Non-cached completions and batches share the model's `parallel` admission
- * cap: with `parallel` in flight, admitting one more waits FIFO until a slot
- * frees.
+ * Completions and batches share the model's `parallel` admission cap: with
+ * `parallel` in flight, admitting one more waits FIFO until a slot frees.
  *
  * Run from packages/sdk:
  *   bun run examples/multi-job-completion.ts

package/dist/examples/multi-job-completion.js

@@ -17,9 +17,8 @@
  *  - `requestId`  — cancel just this call with `cancel({ requestId })`; peers
  *                   keep decoding.
  *
- * Non-cached completions and batches share the model's `parallel` admission
- * cap: with `parallel` in flight, admitting one more waits FIFO until a slot
- * frees.
+ * Completions and batches share the model's `parallel` admission cap: with
+ * `parallel` in flight, admitting one more waits FIFO until a slot frees.
  *
  * Run from packages/sdk:
  *   bun run examples/multi-job-completion.ts

package/dist/examples/parallel-download.js

@@ -18,11 +18,11 @@ try {
             assetSrc: asset.src,
             onProgress: (progress) => {
                 const t = timers[asset.name];
-                if (t.firstProgress == null) {
+                if (t.firstProgress === undefined) {
                     t.firstProgress = now();
                     console.log(`▸ [${asset.name}] first progress at ${((t.firstProgress - wallStart) / 1000).toFixed(1)}s — ${progress.percentage}%`);
                 }
-                if (progress.percentage === 100 && t.end == null) {
+                if (progress.percentage === 100 && t.end === undefined) {
                     t.end = now();
                     console.log(`▸ [${asset.name}] done at ${((t.end - wallStart) / 1000).toFixed(1)}s`);
                 }
@@ -38,8 +38,8 @@ try {
         const t = timers[asset.name];
         const status = result.status === 'fulfilled' ? 'OK' : 'FAILED';
         const reason = result.status === 'rejected' ? ` — ${result.reason}` : '';
-        const timeToFirst = t.firstProgress != null ? `${((t.firstProgress - t.start) / 1000).toFixed(1)}s` : 'N/A';
-        const total = t.end != null ? `${((t.end - t.start) / 1000).toFixed(1)}s` : 'N/A';
+        const timeToFirst = t.firstProgress !== undefined ? `${((t.firstProgress - t.start) / 1000).toFixed(1)}s` : 'N/A';
+        const total = t.end !== undefined ? `${((t.end - t.start) / 1000).toFixed(1)}s` : 'N/A';
         console.log(`▸ ${status} ${asset.name}: first-progress=${timeToFirst}, total=${total}${reason}`);
     }
     console.log(`\n▸ Wall time: ${((wallEnd - wallStart) / 1000).toFixed(1)}s`);

package/dist/examples/plugins.js

@@ -10,7 +10,7 @@
  *   3. Embeddings        -> fails (plugin not selected)
  *
  */
-import { bundleSdk } from '../commands/index.js';
+import { bundleSdk } from '../src/commands/index.js';
 import { existsSync, rmSync } from 'fs';
 import path from 'path';
 const configDir = import.meta.dirname ?? process.cwd();

package/dist/examples/profiling/basic.js

@@ -68,7 +68,6 @@ try {
     if (resourceEvent?.resources) {
         const resources = resourceEvent.resources;
         console.log('  op:', resourceEvent.op);
-        console.log('  origin:', resources.origin);
         console.log('  cpu:', resources.cpu.status === 'supported'
             ? `${(resources.cpu.value * 100).toFixed(1)}%`
             : resources.cpu.status);

package/dist/examples/system-resources.js

@@ -33,6 +33,8 @@ try {
     if (sample) {
         printMetric('Used', sample.memory.usedBytes, formatBytes);
         printMetric('Total (sampled)', sample.memory.totalBytes, formatBytes);
+        printMetric('Process used', sample.memory.processUsedBytes, formatBytes);
+        printMetric('Process available', sample.memory.processAvailableBytes, formatBytes);
     }
     console.log('\n▸ GPUs');
     const gpuLabels = new Map();

package/dist/examples/translation/translation-bergamot-batch-stream.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=translation-bergamot-batch-stream.d.ts.map

package/dist/examples/translation/translation-bergamot-batch-stream.js

@@ -0,0 +1,43 @@
+import { loadModel, translate, unloadModel, BERGAMOT_EN_FR } from '@qvac/sdk';
+try {
+    const modelId = await loadModel({
+        modelSrc: BERGAMOT_EN_FR,
+        modelConfig: {
+            engine: 'Bergamot',
+            from: 'en',
+            to: 'fr'
+        },
+        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(`▸ Bergamot model loaded: ${modelId}`);
+    const texts = [
+        'Hello world',
+        'How are you today?',
+        'This is a test of batch translation',
+        'The weather is nice'
+    ];
+    console.log('▸ Streaming a batch, one translation per token:');
+    const result = translate({
+        modelId,
+        text: texts,
+        modelType: 'nmtcpp-translation',
+        stream: true
+    });
+    let index = 0;
+    for await (const translation of result.tokenStream) {
+        console.log(`  ${index + 1}. ${texts[index]} -> "${translation}"`);
+        index++;
+    }
+    console.log(`▸ Translated ${index} texts`);
+    await unloadModel({ modelId });
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/examples/translation/translation-bergamot-batch.js

@@ -36,13 +36,10 @@ try {
         modelType: 'nmtcpp-translation',
         stream: false
     });
-    const translatedText = await result.text;
-    const translations = translatedText.split('\n');
+    const translations = await result.translations;
     console.log('▸ Translations:');
     translations.forEach((translation, i) => {
-        if (i < texts.length) {
-            console.log(`  ${i + 1}. ${texts[i]} -> "${translation}"`);
-        }
+        console.log(`  ${i + 1}. ${texts[i]} -> "${translation}"`);
     });
     await unloadModel({ modelId });
 }

package/dist/examples/vla-groot.js

@@ -91,7 +91,7 @@ try {
     // (numCameras, actionDim, ...) — rebuild them after every embodiment switch.
     async function runInference(hp) {
         const patchElems = hp.imagePatchElems;
-        if (hp.imageInputMode !== 'patches' || patchElems == null) {
+        if (hp.imageInputMode !== 'patches' || patchElems === undefined) {
             throw new Error(`expected a patch-input model (imageInputMode 'patches' + imagePatchElems); ` +
                 `got imageInputMode=${hp.imageInputMode}`);
         }

package/dist/scripts/check-resource-collectors-packaging.d.ts

@@ -1,5 +1,5 @@
-import { type BundleSdkOptions, type BundleSdkResult } from '../commands/bundle/index.js';
-import { type ResourceCollectorAcceptanceOptions, type ResourceCollectorAcceptanceReport } from '../commands/verify/resource-collectors.js';
+import { type BundleSdkOptions, type BundleSdkResult } from '../src/commands/bundle/index.js';
+import { type ResourceCollectorAcceptanceOptions, type ResourceCollectorAcceptanceReport } from '../src/commands/verify/resource-collectors.js';
 declare const DESKTOP_HOSTS: readonly ["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64", "win32-arm64", "win32-x64"];
 type DesktopHost = (typeof DESKTOP_HOSTS)[number];
 export interface ResourceCollectorCheckArgs {

package/dist/scripts/check-resource-collectors-packaging.js

@@ -2,9 +2,9 @@ import { promises as fsp } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { bundleSdk } from '../commands/bundle/index.js';
-import { acceptResourceCollectorPackaging, formatResourceCollectorAcceptanceReport } from '../commands/verify/resource-collectors.js';
-import { RequestValidationFailedError } from '../utils/errors-client.js';
+import { bundleSdk } from '../src/commands/bundle/index.js';
+import { acceptResourceCollectorPackaging, formatResourceCollectorAcceptanceReport } from '../src/commands/verify/resource-collectors.js';
+import { RequestValidationFailedError } from '../src/utils/errors-client.js';
 const DESKTOP_HOSTS = [
     'darwin-arm64',
     'darwin-x64',

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

@@ -20,7 +20,7 @@ export declare function buildContract(): {
                 condition: string;
                 responseSchema: string;
             };
-            name: "cancel" | "transcribe" | "translate" | "finetune" | "loadModel" | "downloadAsset" | "rag" | "pluginInvoke" | "pluginInvokeStream" | "modelRegistryList" | "modelRegistrySearch" | "modelRegistryGetModel" | "completionStream" | "completionOrchestrate" | "batchCompletionStream" | "deleteCache" | "audioGenStream" | "heartbeat" | "unloadModel" | "transcribeStream" | "bciTranscribe" | "bciTranscribeStream" | "loggingStream" | "embed" | "textToSpeech" | "textToSpeechStream" | "provide" | "stopProvide" | "getModelInfo" | "getLoadedModelInfo" | "ocrStream" | "diffusionStream" | "videoStream" | "upscaleStream" | "resume" | "suspend" | "state" | "getSystemResources" | "classify";
+            name: "audioGenStream" | "heartbeat" | "loadModel" | "downloadAsset" | "completionStream" | "completionOrchestrate" | "batchCompletionStream" | "unloadModel" | "transcribe" | "transcribeStream" | "bciTranscribe" | "bciTranscribeStream" | "loggingStream" | "embed" | "translate" | "textToSpeech" | "textToSpeechStream" | "cancel" | "finetune" | "rag" | "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;

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

@@ -1,9 +1,9 @@
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import prettier from 'prettier';
-import { requestSchema, responseSchema } from '../../schemas/common.js';
-import { methodShapes } from '../../server/rpc/method-shapes.js';
-import { constantsRegistry } from '../../schemas/constants-registry.js';
+import { requestSchema, responseSchema } from '@qvac/inference/surface';
+import { methodShapes } from './method-shapes.js';
+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';
@@ -422,7 +422,7 @@ function titleNestedSchemas(root, rootTitle, seenTitles) {
     }
 }
 export function toWireJsonSchema(schema, io, defName) {
-    const json = z.toJSONSchema(schema, {
+    const json = schema.toJSONSchema({
         target: 'draft-2020-12',
         io,
         unrepresentable: 'any'
@@ -539,7 +539,7 @@ export function buildContract() {
         defEntries.push([`${type}.response`, schema, 'output', classTitleFor(type, 'Response')]);
     }
     // Public constants (@/schemas/constants-registry), merged into the same
-    // $defs as every request/response type via the same z.toJSONSchema call —
+    // $defs as every request/response type via the same toJSONSchema call —
     // not a separate artifact. `x-enum-varnames` preserves each entry's
     // original key names (`ModelType.llamacppCompletion`, `PluginId.LLM`, ...)
     // through codegen; plain JSON Schema `enum:` only carries values.

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

@@ -1,6 +1,6 @@
-import { SDK_SERVER_ERROR_CODES } from '../../schemas/sdk-errors-server.js';
-import { SDK_CLIENT_ERROR_CODES } from '../../schemas/sdk-errors-client.js';
-import { REGISTRY_ERROR_CODES } from '../../schemas/sdk-errors-registry.js';
+import { SDK_SERVER_ERROR_CODES } from '../../src/schemas/sdk-errors-server.js';
+import { SDK_CLIENT_ERROR_CODES } from '../../src/schemas/sdk-errors-client.js';
+import { REGISTRY_ERROR_CODES } from '@qvac/inference/surface';
 function sortedEntries(record) {
     const entries = Object.entries(record);
     entries.sort(function (a, b) {

package/dist/scripts/contract/build-model-type-maps.js

@@ -1,5 +1,4 @@
-import { ModelTypeAliases } from '../../schemas/model-types.js';
-import { ENGINE_TO_ADDON, LEGACY_ENGINE_TO_CANONICAL } from '../../schemas/engine-addon-map.js';
+import { ModelTypeAliases, ENGINE_TO_ADDON, LEGACY_ENGINE_TO_CANONICAL } from '@qvac/inference/surface';
 function sortedEntries(record) {
     const entries = Object.entries(record);
     entries.sort(function (a, b) {

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

@@ -1,6 +1,6 @@
-import type { ModelConstant } from '../../models/registry/index.js';
+import type { ModelConstant } from '@qvac/inference/models';
 /**
- * JSON export of every named model constant in `@/models/registry`
+ * JSON export of every named model constant in `@qvac/inference/models`
  * (`QWEN3_600M_INST_Q4`, `BCI_EMBEDDER`, ...) — the same constants JS
  * consumers import directly and pass as `modelSrc`
  * (`loadModel({ modelSrc: QWEN3_600M_INST_Q4, ... })`). Only the ~440

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

@@ -1,4 +1,4 @@
-import * as registry from '../../models/registry/index.js';
+import * as registry from '@qvac/inference/models';
 function isModelConstant(value) {
     return (value !== null &&
         typeof value === 'object' &&
@@ -6,7 +6,7 @@ function isModelConstant(value) {
         typeof value.src === 'string');
 }
 /**
- * JSON export of every named model constant in `@/models/registry`
+ * JSON export of every named model constant in `@qvac/inference/models`
  * (`QWEN3_600M_INST_Q4`, `BCI_EMBEDDER`, ...) — the same constants JS
  * consumers import directly and pass as `modelSrc`
  * (`loadModel({ modelSrc: QWEN3_600M_INST_Q4, ... })`). Only the ~440

package/dist/scripts/contract/constants-registry.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+/**
+ * Every public constant `enum` from the SDK surface that downstream (non-JS)
+ * client generators should get as a real, named type instead of a
+ * hardcoded string/number. `build-contract.ts` merges each of these
+ * directly into `schema.json`'s `$defs` (same `z.toJSONSchema` call, same
+ * generator run as every request/response type), tagged with an
+ * `x-enum-varnames` hint so datamodel-code-generator preserves the
+ * original key names instead of slugging them from the bare value — plain
+ * JSON Schema `enum:` only carries values, not names, so without that hint
+ * `PluginId`/`Verbosity` (whose keys aren't derivable from their values)
+ * would lose their names entirely.
+ *
+ * A constant only reaches other languages if it's registered here. See
+ * `.cursor/rules/sdk/public-constants-contract.mdc`: any new public
+ * constant meant for downstream SDKs must be a `z.enum(...)` added here,
+ * not just a bare `export const` in its own schema file — otherwise it
+ * silently never leaves JS.
+ *
+ * Scoped to name→value maps (`z.enum`) only. A standalone scalar constant
+ * (e.g. `VLA_DEFAULT_IMAGE_SIZE`) has no natural JSON Schema representation
+ * as a plain value — a `const`-only schema generates an awkward
+ * `RootModel[Literal[...]]` wrapper class in Python, not a usable
+ * constant — so scalars aren't covered by this registry.
+ */
+export declare const constantsRegistry: {
+    readonly ModelType: z.ZodEnum<{
+        readonly llamacppCompletion: "llamacpp-completion";
+        readonly whispercppTranscription: "whispercpp-transcription";
+        readonly bciWhispercppTranscription: "bci-whispercpp-transcription";
+        readonly llamacppEmbedding: "llamacpp-embedding";
+        readonly nmtcppTranslation: "nmtcpp-translation";
+        readonly onnxTts: "onnx-tts";
+        readonly ttsGgml: "tts-ggml";
+        readonly parakeetTranscription: "parakeet-transcription";
+        readonly ggmlOcr: "ggml-ocr";
+        readonly sdcppGeneration: "sdcpp-generation";
+        readonly audiogenGgml: "audiogen-ggml";
+        readonly ggmlVla: "ggml-vla";
+        readonly ggmlClassification: "ggml-classification";
+    }>;
+    readonly Verbosity: z.ZodEnum<{
+        readonly ERROR: 0;
+        readonly WARN: 1;
+        readonly INFO: 2;
+        readonly DEBUG: 3;
+    }>;
+    readonly PluginId: z.ZodEnum<{
+        readonly LLM: "@qvac/sdk/llamacpp-completion/plugin";
+        readonly EMBEDDING: "@qvac/sdk/llamacpp-embedding/plugin";
+        readonly WHISPER: "@qvac/sdk/whispercpp-transcription/plugin";
+        readonly BCI: "@qvac/sdk/bci-whispercpp-transcription/plugin";
+        readonly NMT: "@qvac/sdk/nmtcpp-translation/plugin";
+        readonly TTS: "@qvac/sdk/tts-ggml/plugin";
+        readonly OCR: "@qvac/sdk/ggml-ocr/plugin";
+        readonly DIFFUSION: "@qvac/sdk/sdcpp-generation/plugin";
+        readonly AUDIOGEN: "@qvac/sdk/audiogen-ggml/plugin";
+        readonly VLA: "@qvac/sdk/ggml-vla/plugin";
+        readonly CLASSIFICATION: "@qvac/sdk/ggml-classification/plugin";
+    }>;
+    readonly SupportedAudioFormat: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsPace: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsCosyvoice3Emotion: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsCosyvoice3InstructDialect: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsCosyvoice3InstructVolume: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsCosyvoice3InstructStyle: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly AudioGenEngine: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly AudioGenTaskType: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+};
+//# sourceMappingURL=constants-registry.d.ts.map

package/dist/scripts/contract/constants-registry.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { ModelType, VERBOSITY, SUPPORTED_AUDIO_FORMATS, AUDIOGEN_ENGINES, AUDIOGEN_TASK_TYPES, TTS_PACES, TTS_COSYVOICE3_EMOTIONS, TTS_COSYVOICE3_INSTRUCT_DIALECTS, TTS_COSYVOICE3_INSTRUCT_VOLUMES, TTS_COSYVOICE3_INSTRUCT_STYLES } from '@qvac/inference/surface';
+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';
+// Uppercases each vocabulary value into an identifier-safe varname (e.g.
+// 'slow' -> 'SLOW', 'cover-nofsq' -> 'COVER_NOFSQ'), mirroring the
+// SupportedAudioFormat derivation so names can't drift from the single
+// source-of-truth array.
+function enumFromVocabulary(values) {
+    return z.enum(Object.fromEntries(values.map((value) => [value.toUpperCase().replace(/-/g, '_'), value])));
+}
+/**
+ * Every public constant `enum` from the SDK surface that downstream (non-JS)
+ * client generators should get as a real, named type instead of a
+ * hardcoded string/number. `build-contract.ts` merges each of these
+ * directly into `schema.json`'s `$defs` (same `z.toJSONSchema` call, same
+ * generator run as every request/response type), tagged with an
+ * `x-enum-varnames` hint so datamodel-code-generator preserves the
+ * original key names instead of slugging them from the bare value — plain
+ * JSON Schema `enum:` only carries values, not names, so without that hint
+ * `PluginId`/`Verbosity` (whose keys aren't derivable from their values)
+ * would lose their names entirely.
+ *
+ * A constant only reaches other languages if it's registered here. See
+ * `.cursor/rules/sdk/public-constants-contract.mdc`: any new public
+ * constant meant for downstream SDKs must be a `z.enum(...)` added here,
+ * not just a bare `export const` in its own schema file — otherwise it
+ * silently never leaves JS.
+ *
+ * Scoped to name→value maps (`z.enum`) only. A standalone scalar constant
+ * (e.g. `VLA_DEFAULT_IMAGE_SIZE`) has no natural JSON Schema representation
+ * as a plain value — a `const`-only schema generates an awkward
+ * `RootModel[Literal[...]]` wrapper class in Python, not a usable
+ * constant — so scalars aren't covered by this registry.
+ */
+export const constantsRegistry = {
+    ModelType: z.enum(ModelType),
+    Verbosity: z.enum(VERBOSITY),
+    PluginId: z.enum({
+        LLM: PLUGIN_LLM,
+        EMBEDDING: PLUGIN_EMBEDDING,
+        WHISPER: PLUGIN_WHISPER,
+        BCI: PLUGIN_BCI,
+        NMT: PLUGIN_NMT,
+        TTS: PLUGIN_TTS,
+        OCR: PLUGIN_OCR,
+        DIFFUSION: PLUGIN_DIFFUSION,
+        AUDIOGEN: PLUGIN_AUDIOGEN,
+        VLA: PLUGIN_VLA,
+        CLASSIFICATION: PLUGIN_CLASSIFICATION
+    }),
+    // Derived from SUPPORTED_AUDIO_FORMATS itself (e.g. '.mp3' -> 'MP3') rather
+    // than a hand-written record, so the varnames can't drift from the one
+    // source of truth every other consumer of SUPPORTED_AUDIO_FORMATS shares.
+    SupportedAudioFormat: z.enum(Object.fromEntries(SUPPORTED_AUDIO_FORMATS.map((ext) => [ext.slice(1).toUpperCase(), ext]))),
+    TtsPace: enumFromVocabulary(TTS_PACES),
+    TtsCosyvoice3Emotion: enumFromVocabulary(TTS_COSYVOICE3_EMOTIONS),
+    TtsCosyvoice3InstructDialect: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_DIALECTS),
+    TtsCosyvoice3InstructVolume: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_VOLUMES),
+    TtsCosyvoice3InstructStyle: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_STYLES),
+    AudioGenEngine: enumFromVocabulary(AUDIOGEN_ENGINES),
+    AudioGenTaskType: enumFromVocabulary(AUDIOGEN_TASK_TYPES)
+};