@qvac/sdk 0.10.2 → 0.12.0

package/dist/commands/verify/index.js

@@ -0,0 +1,371 @@
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { resolveConfigFileInProject, loadConfigFromPath, } from "../../client/config-loader/resolve-config.node.js";
+import { createCollectDiagnostics, formatAddonId, } from "./addon-source.js";
+import { collectAddonsFromBundle, InvalidBundleSourceError, } from "./bundle-source.js";
+import { collectAddonsFromNodeModules, InvalidNodeModulesSourceError, } from "./node-modules-source.js";
+import { checkPrebuilds, } from "./prebuilds.js";
+import { checkAbi, formatConfigLabel, normalizeVersion, resolveBareRuntime, } from "./abi.js";
+export async function verifyBundle(options) {
+    const { projectRoot, addonsSource, hosts, bareRuntimeVersion, configPath } = options;
+    const resolvedAddonsSource = path.isAbsolute(addonsSource)
+        ? addonsSource
+        : path.resolve(projectRoot, addonsSource);
+    if (hosts.length === 0) {
+        return {
+            addonsSource,
+            resolvedAddonsSource,
+            sourceKind: null,
+            hosts,
+            runtime: null,
+            addons: [],
+            issues: [
+                {
+                    code: 'invalid-source',
+                    level: 'error',
+                    addonsSource,
+                    message: 'At least one host is required.'
+                }
+            ]
+        };
+    }
+    let invalidRuntimeVersion = null;
+    if (bareRuntimeVersion !== undefined && normalizeVersion(bareRuntimeVersion) === null) {
+        invalidRuntimeVersion = {
+            code: 'invalid-runtime-version',
+            level: 'error',
+            providedValue: bareRuntimeVersion,
+            source: 'flag',
+            message: `bareRuntimeVersion "${bareRuntimeVersion}" is not a valid semver. ` +
+                'Use a version like 1.15.0 (with optional v-prefix and pre-release tag) or omit it to use auto-detection.'
+        };
+    }
+    let configRuntimeVersion;
+    let resolvedConfigPath = null;
+    let configLoadFailed = null;
+    try {
+        resolvedConfigPath = await resolveConfigFileInProject(projectRoot, configPath ?? undefined);
+        if (resolvedConfigPath !== null) {
+            const config = await loadConfigFromPath(resolvedConfigPath);
+            if (typeof config.bareRuntimeVersion === "string") {
+                configRuntimeVersion = config.bareRuntimeVersion;
+            }
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (configPath !== undefined) {
+            return {
+                addonsSource,
+                resolvedAddonsSource,
+                sourceKind: null,
+                hosts,
+                runtime: null,
+                addons: [],
+                issues: [
+                    {
+                        code: 'invalid-source',
+                        level: 'error',
+                        addonsSource,
+                        message: `Failed to load config from '${configPath}': ${message}`
+                    }
+                ]
+            };
+        }
+        if (resolvedConfigPath !== null) {
+            configLoadFailed = {
+                code: 'config-load-failed',
+                level: 'warning',
+                configPath: resolvedConfigPath,
+                reason: message,
+                message: `Found ${formatConfigLabel(projectRoot, resolvedConfigPath)} but failed to load it: ${message}. ` +
+                    'Falling back to auto-detection for Bare runtime; the project-pinned ' +
+                    '`bareRuntimeVersion` is being ignored. Fix the config file or pass `configPath` explicitly to surface it as an error.'
+            };
+        }
+    }
+    if (invalidRuntimeVersion === null &&
+        bareRuntimeVersion === undefined &&
+        configRuntimeVersion !== undefined &&
+        normalizeVersion(configRuntimeVersion) === null) {
+        invalidRuntimeVersion = {
+            code: 'invalid-runtime-version',
+            level: 'error',
+            providedValue: configRuntimeVersion,
+            source: 'config',
+            message: `\`bareRuntimeVersion\` in ${formatConfigLabel(projectRoot, resolvedConfigPath ?? undefined)} ` +
+                `"${configRuntimeVersion}" is not a valid semver. ` +
+                'Use a version like 1.15.0 (with optional v-prefix and pre-release tag), or remove the field to use auto-detection.'
+        };
+    }
+    const sourceKind = await detectSourceKind(resolvedAddonsSource);
+    if (sourceKind === null) {
+        return {
+            addonsSource,
+            resolvedAddonsSource,
+            sourceKind: null,
+            hosts,
+            runtime: null,
+            addons: [],
+            issues: [
+                {
+                    code: 'invalid-source',
+                    level: 'error',
+                    addonsSource,
+                    message: `--addons-source ${addonsSource} is not a readable file or directory ` +
+                        `(resolved to ${resolvedAddonsSource}).`
+                }
+            ]
+        };
+    }
+    const diagnostics = createCollectDiagnostics();
+    let addons;
+    try {
+        addons = sourceKind === 'bare-pack-bundle'
+            ? await collectAddonsFromBundle({
+                bundlePath: resolvedAddonsSource,
+                projectRoot,
+                diagnostics
+            })
+            : await collectAddonsFromNodeModules({
+                nodeModulesRoot: resolvedAddonsSource,
+                diagnostics
+            });
+    }
+    catch (error) {
+        if (error instanceof InvalidBundleSourceError ||
+            error instanceof InvalidNodeModulesSourceError) {
+            return {
+                addonsSource,
+                resolvedAddonsSource,
+                sourceKind,
+                hosts,
+                runtime: null,
+                addons: [],
+                issues: [
+                    {
+                        code: 'invalid-source',
+                        level: 'error',
+                        addonsSource,
+                        message: error.message
+                    }
+                ]
+            };
+        }
+        throw error;
+    }
+    const issues = [];
+    if (configLoadFailed !== null)
+        issues.push(configLoadFailed);
+    if (invalidRuntimeVersion !== null)
+        issues.push(invalidRuntimeVersion);
+    issues.push(...buildInvalidPackageJsonIssues(diagnostics.invalidPackageJsons));
+    if (sourceKind === 'bare-pack-bundle' && diagnostics.emptyResolutions) {
+        issues.push({
+            code: 'empty-bundle-resolutions',
+            level: 'warning',
+            bundlePath: resolvedAddonsSource,
+            message: `Bundle at ${resolvedAddonsSource} has no resolutions in its bare-pack header ` +
+                '(0 packages discoverable). The verifier cannot inspect any addons in this bundle; ' +
+                '`Native addon verification passed` would be vacuous. Regenerate the bundle via ' +
+                '`qvac bundle sdk` and re-run, or check for a corrupted/empty bundle file.'
+        });
+    }
+    for (const addon of addons) {
+        const prebuildIssues = await checkPrebuilds({ addon, hosts });
+        issues.push(...prebuildIssues);
+    }
+    let runtime = null;
+    if (invalidRuntimeVersion === null) {
+        const runtimeOptions = { projectRoot };
+        if (bareRuntimeVersion !== undefined) {
+            runtimeOptions.explicitVersion = bareRuntimeVersion;
+            runtimeOptions.explicitSource = 'flag';
+        }
+        else if (configRuntimeVersion !== undefined) {
+            runtimeOptions.explicitVersion = configRuntimeVersion;
+            runtimeOptions.explicitSource = 'config';
+        }
+        runtime = await resolveBareRuntime(runtimeOptions);
+        issues.push(...checkAbi({ addons, runtime }));
+    }
+    return {
+        addonsSource,
+        resolvedAddonsSource,
+        sourceKind,
+        hosts,
+        runtime,
+        addons,
+        issues
+    };
+}
+function buildInvalidPackageJsonIssues(records) {
+    return records.map((record) => {
+        const issue = {
+            code: 'invalid-package-json',
+            level: 'warning',
+            packageJsonPath: record.packageJsonPath,
+            reason: record.reason,
+            message: `Skipping ${record.expectedName ?? record.packageJsonPath}: ` +
+                `${record.reason}. The package is being treated as a non-addon; if it ships ` +
+                'native code, the verifier cannot check its prebuilds or ABI. ' +
+                'Fix the package.json or remove the package.'
+        };
+        if (record.expectedName !== undefined)
+            issue.expectedName = record.expectedName;
+        return issue;
+    });
+}
+async function detectSourceKind(resolvedAddonsSource) {
+    try {
+        const stat = await fsp.stat(resolvedAddonsSource);
+        if (stat.isFile())
+            return 'bare-pack-bundle';
+        if (stat.isDirectory())
+            return 'node-modules';
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function hasErrors(result) {
+    return result.issues.some((issue) => issue.level === 'error');
+}
+export function hasWarnings(result) {
+    return result.issues.some((issue) => issue.level === 'warning');
+}
+export function formatVerifyBundleResult(result) {
+    const sections = [];
+    const hostList = result.hosts.join(', ');
+    if (result.issues.length === 0) {
+        sections.push(`Native addon verification passed for ${result.addons.length} ` +
+            `addon${result.addons.length === 1 ? '' : 's'} across ${result.hosts.length} ` +
+            `host${result.hosts.length === 1 ? '' : 's'}: ${hostList}`);
+        if (result.addons.length > 0) {
+            sections.push('');
+            sections.push('  Verified addons:');
+            for (const addon of result.addons) {
+                sections.push(`    - ${formatAddonId(addon)}`);
+            }
+        }
+        return sections.join('\n');
+    }
+    if (hasErrors(result)) {
+        sections.push('Native addon verification failed:');
+    }
+    else {
+        sections.push('Native addon verification produced warnings:');
+    }
+    sections.push('');
+    sections.push(...formatMissingPrebuilds(result.issues));
+    sections.push(...formatAbiMismatches(result.issues));
+    sections.push(...formatInvalidRuntimeVersions(result.issues));
+    sections.push(...formatMalformedEnginesBare(result.issues));
+    sections.push(...formatConfigLoadFailed(result.issues));
+    sections.push(...formatInvalidPackageJsons(result.issues));
+    sections.push(...formatEmptyBundleResolutions(result.issues));
+    sections.push(...formatUnknownRuntime(result.issues));
+    sections.push(...formatInvalidSources(result.issues));
+    return sections.join('\n').trimEnd();
+}
+function formatConfigLoadFailed(issues) {
+    const matches = issues.filter((issue) => issue.code === 'config-load-failed');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Config load failed:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatMissingPrebuilds(issues) {
+    const matches = issues.filter((issue) => issue.code === 'missing-prebuild');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Missing prebuild:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.addon} for ${issue.host}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatAbiMismatches(issues) {
+    const matches = issues.filter((issue) => issue.code === 'abi-mismatch');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  ABI mismatch:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.addon} requires bare ${issue.enginesBare}, ` +
+            `runtime is ${issue.runtimeVersion}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatUnknownRuntime(issues) {
+    const matches = issues.filter((issue) => issue.code === 'unknown-runtime-version');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Unknown runtime version:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatMalformedEnginesBare(issues) {
+    const matches = issues.filter((issue) => issue.code === 'malformed-engines-bare');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Malformed engines.bare:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatInvalidSources(issues) {
+    const matches = issues.filter((issue) => issue.code === 'invalid-source');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Invalid source:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatInvalidRuntimeVersions(issues) {
+    const matches = issues.filter((issue) => issue.code === 'invalid-runtime-version');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Invalid Bare runtime version:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatInvalidPackageJsons(issues) {
+    const matches = issues.filter((issue) => issue.code === 'invalid-package-json');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Invalid package.json (skipped):'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}
+function formatEmptyBundleResolutions(issues) {
+    const matches = issues.filter((issue) => issue.code === 'empty-bundle-resolutions');
+    if (matches.length === 0)
+        return [];
+    const lines = ['  Empty bundle resolutions:'];
+    for (const issue of matches) {
+        lines.push(`    - ${issue.message}`);
+    }
+    lines.push('');
+    return lines;
+}

package/dist/commands/verify/node-modules-source.d.ts

@@ -0,0 +1,11 @@
+import { type CollectDiagnostics, type NativeAddon } from "./addon-source";
+export declare class InvalidNodeModulesSourceError extends Error {
+    nodeModulesPath: string;
+    constructor(nodeModulesPath: string, cause: unknown);
+}
+export interface CollectAddonsFromNodeModulesOptions {
+    nodeModulesRoot: string;
+    diagnostics?: CollectDiagnostics;
+}
+export declare function collectAddonsFromNodeModules(options: CollectAddonsFromNodeModulesOptions): Promise<NativeAddon[]>;
+//# sourceMappingURL=node-modules-source.d.ts.map

package/dist/commands/verify/node-modules-source.js

@@ -0,0 +1,76 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { deduplicateAddons, readAddonPackageJson, } from "./addon-source.js";
+export class InvalidNodeModulesSourceError extends Error {
+    nodeModulesPath;
+    constructor(nodeModulesPath, cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        super(`node_modules at ${nodeModulesPath} could not be read.\n\n` +
+            `  Reason: ${reason}\n\n` +
+            "  Run `npm install` before invoking verifyBundle against a node_modules tree.");
+        this.name = "InvalidNodeModulesSourceError";
+        this.nodeModulesPath = nodeModulesPath;
+    }
+}
+export async function collectAddonsFromNodeModules(options) {
+    const { nodeModulesRoot, diagnostics } = options;
+    const addons = [];
+    await walkNodeModules(nodeModulesRoot, addons, diagnostics, true);
+    return deduplicateAddons(addons);
+}
+async function walkNodeModules(nodeModulesDir, addons, diagnostics, isRoot) {
+    let entries;
+    try {
+        entries = await fsp.readdir(nodeModulesDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isRoot)
+            throw new InvalidNodeModulesSourceError(nodeModulesDir, error);
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        if (!isPackageEntry(entry))
+            continue;
+        if (entry.name.startsWith("@")) {
+            await walkScopeDirectory(path.join(nodeModulesDir, entry.name), addons, diagnostics);
+            continue;
+        }
+        await visitPackageDirectory(path.join(nodeModulesDir, entry.name), entry.name, addons, diagnostics);
+    }
+}
+async function walkScopeDirectory(scopeDir, addons, diagnostics) {
+    const scope = path.basename(scopeDir);
+    let entries;
+    try {
+        entries = await fsp.readdir(scopeDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        if (!isPackageEntry(entry))
+            continue;
+        await visitPackageDirectory(path.join(scopeDir, entry.name), `${scope}/${entry.name}`, addons, diagnostics);
+    }
+}
+function isPackageEntry(entry) {
+    return entry.isDirectory() || entry.isSymbolicLink();
+}
+async function visitPackageDirectory(packageDir, packageName, addons, diagnostics) {
+    const result = await readAddonPackageJson({
+        packageJsonPath: path.join(packageDir, "package.json"),
+        expectedName: packageName,
+    });
+    if (result.isAddon && result.addon) {
+        addons.push(result.addon);
+    }
+    else if (result.invalid !== undefined && diagnostics !== undefined) {
+        diagnostics.invalidPackageJsons.push(result.invalid);
+    }
+    const nestedNodeModules = path.join(packageDir, "node_modules");
+    await walkNodeModules(nestedNodeModules, addons, diagnostics, false);
+}

package/dist/commands/verify/prebuilds.d.ts

@@ -0,0 +1,15 @@
+import { type NativeAddon } from "./addon-source";
+export interface MissingPrebuildIssue {
+    code: "missing-prebuild";
+    level: "error";
+    addon: string;
+    host: string;
+    message: string;
+    packageRoot: string;
+}
+export interface CheckPrebuildsOptions {
+    addon: NativeAddon;
+    hosts: string[];
+}
+export declare function checkPrebuilds(options: CheckPrebuildsOptions): Promise<MissingPrebuildIssue[]>;
+//# sourceMappingURL=prebuilds.d.ts.map

package/dist/commands/verify/prebuilds.js

@@ -0,0 +1,39 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { formatAddonId } from "./addon-source.js";
+export async function checkPrebuilds(options) {
+    const { addon, hosts } = options;
+    const issues = [];
+    for (const host of hosts) {
+        const hostDir = path.join(addon.packageRoot, "prebuilds", host);
+        const present = await hasBarePrebuild(hostDir);
+        if (!present) {
+            issues.push({
+                code: "missing-prebuild",
+                level: "error",
+                addon: formatAddonId(addon),
+                host,
+                packageRoot: addon.packageRoot,
+                message: `${formatAddonId(addon)} is missing a prebuild for ${host} ` +
+                    `(expected ${path.join(hostDir, "*.bare")}).`,
+            });
+        }
+    }
+    return issues;
+}
+async function hasBarePrebuild(hostDir) {
+    let entries;
+    try {
+        entries = await fsp.readdir(hostDir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile() && !entry.isSymbolicLink())
+            continue;
+        if (entry.name.endsWith(".bare"))
+            return true;
+    }
+    return false;
+}

package/dist/examples/cancel-by-request-id.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cancel a specific in-flight completion by `requestId`.
+ *
+ * `completion(...)` exposes a stable `requestId` (UUIDv4, generated
+ * client-side) on the returned `CompletionRun`. Pass it to
+ * `cancel({ requestId })` to abort that exact run without affecting any
+ * other inference happening on the same model.
+ *
+ * Two cancel paths exist:
+ *
+ *  1. `cancel({ requestId })` — targeted cancel, the primary path
+ *     introduced in 0.11.0. The `requestId` is available synchronously
+ *     on the `CompletionRun`. Same-tick cancels (issued before the
+ *     server has registered the request) are recorded and applied
+ *     retroactively when `begin(...)` arrives, so they aren't silently
+ *     dropped.
+ *  2. `cancel({ operation: "inference", modelId })` — broad cancel
+ *     (escape hatch, kept indefinitely). Cancels every inference running
+ *     on the model. Useful for unload, app shutdown, admin sweeps when
+ *     the caller doesn't have a `requestId` to hand.
+ *
+ * --- Cancel outcomes (0.11.0+) ---
+ *
+ * A cancel surfaces on two channels:
+ *
+ *  - `run.events` ends *normally* with a `completionDone` event carrying
+ *    `stopReason: "cancelled"`. The loop exits cleanly, no thrown error.
+ *  - `run.text` / `run.final` / `run.stats` / `run.toolCalls` reject
+ *    with `InferenceCancelledError(requestId, partial)`, where `partial`
+ *    holds whatever the model produced before the cancel landed
+ *    (accumulated `text`, completed `toolCalls`, last-known `stats`).
+ *
+ * Pick the channel that matches how you consume the run: event-loop
+ * consumers don't need to catch anything; promise-aggregate consumers
+ * pattern-match on `instanceof InferenceCancelledError`.
+ */
+export {};
+//# sourceMappingURL=cancel-by-request-id.d.ts.map

package/dist/examples/cancel-by-request-id.js

@@ -0,0 +1,103 @@
+/**
+ * Cancel a specific in-flight completion by `requestId`.
+ *
+ * `completion(...)` exposes a stable `requestId` (UUIDv4, generated
+ * client-side) on the returned `CompletionRun`. Pass it to
+ * `cancel({ requestId })` to abort that exact run without affecting any
+ * other inference happening on the same model.
+ *
+ * Two cancel paths exist:
+ *
+ *  1. `cancel({ requestId })` — targeted cancel, the primary path
+ *     introduced in 0.11.0. The `requestId` is available synchronously
+ *     on the `CompletionRun`. Same-tick cancels (issued before the
+ *     server has registered the request) are recorded and applied
+ *     retroactively when `begin(...)` arrives, so they aren't silently
+ *     dropped.
+ *  2. `cancel({ operation: "inference", modelId })` — broad cancel
+ *     (escape hatch, kept indefinitely). Cancels every inference running
+ *     on the model. Useful for unload, app shutdown, admin sweeps when
+ *     the caller doesn't have a `requestId` to hand.
+ *
+ * --- Cancel outcomes (0.11.0+) ---
+ *
+ * A cancel surfaces on two channels:
+ *
+ *  - `run.events` ends *normally* with a `completionDone` event carrying
+ *    `stopReason: "cancelled"`. The loop exits cleanly, no thrown error.
+ *  - `run.text` / `run.final` / `run.stats` / `run.toolCalls` reject
+ *    with `InferenceCancelledError(requestId, partial)`, where `partial`
+ *    holds whatever the model produced before the cancel landed
+ *    (accumulated `text`, completed `toolCalls`, last-known `stats`).
+ *
+ * Pick the channel that matches how you consume the run: event-loop
+ * consumers don't need to catch anything; promise-aggregate consumers
+ * pattern-match on `instanceof InferenceCancelledError`.
+ */
+import { cancel, completion, loadModel, unloadModel, InferenceCancelledError, QWEN3_600M_INST_Q4, } from "@qvac/sdk";
+try {
+    const modelId = await loadModel({
+        modelSrc: QWEN3_600M_INST_Q4,
+        modelType: "llm",
+        modelConfig: { ctx_size: 4096 },
+    });
+    const run = completion({
+        modelId,
+        history: [
+            {
+                role: "user",
+                content: "Write a long, detailed essay about the history of the Roman Empire.",
+            },
+        ],
+        stream: true,
+    });
+    console.log(`requestId: ${run.requestId}`);
+    // Cancel after a short delay so we exercise the cancel-mid-decode path.
+    setTimeout(() => {
+        void cancel({ requestId: run.requestId });
+        console.log("(cancel issued)");
+    }, 250);
+    // Channel 1: the events stream ends normally on cancel. The
+    // `completionDone` event's `stopReason` tells you why the loop is
+    // about to exit ("eos" | "length" | "cancelled" | "error" | ...).
+    let tokenCount = 0;
+    let endReason;
+    for await (const event of run.events) {
+        if (event.type === "contentDelta") {
+            tokenCount++;
+            process.stdout.write(event.text);
+        }
+        else if (event.type === "completionDone") {
+            endReason = event.stopReason;
+        }
+    }
+    console.log(`\n\nstreamed ${tokenCount} content deltas, stopReason=${endReason}.`);
+    // Channel 2: promise-aggregates reject with InferenceCancelledError
+    // on cancel. The accumulated state up to the cancel point is preserved
+    // on `err.partial`.
+    try {
+        const text = await run.text;
+        console.log(`completed normally (${text.length} chars).`);
+    }
+    catch (err) {
+        if (err instanceof InferenceCancelledError) {
+            console.log(`run.text rejected: cancelled (requestId=${err.requestId})`);
+            console.log(`partial text length: ${(err.partial.text ?? "").length}`);
+            if (err.partial.stats?.tokensPerSecond !== undefined) {
+                console.log(`partial stats: ${err.partial.stats.tokensPerSecond.toFixed(1)} tok/s`);
+            }
+            if (err.partial.toolCalls && err.partial.toolCalls.length > 0) {
+                console.log(`partial tool calls: ${err.partial.toolCalls.length}`);
+            }
+        }
+        else {
+            throw err;
+        }
+    }
+    await unloadModel({ modelId });
+    process.exit(0);
+}
+catch (error) {
+    console.error("Error:", error);
+    process.exit(1);
+}

package/dist/examples/classification/classify-image.d.ts

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

package/dist/examples/classification/classify-image.js

@@ -0,0 +1,23 @@
+import fs from "fs";
+import { startQVACProvider, stopQVACProvider, loadModel, classify, unloadModel } from "@qvac/sdk";
+/**
+ * Classify an image using the bundled MobileNetV3-Small model.
+ *
+ * The bundled model produces three classes: "food", "report", "other".
+ * No modelSrc is needed — the model ships inside @qvac/classification-ggml.
+ */
+async function main() {
+    await startQVACProvider({});
+    const modelId = await loadModel({
+        modelType: "ggml-classification",
+    });
+    const image = fs.readFileSync("image.jpg");
+    const results = await classify({ modelId, image });
+    console.log("Classification results:");
+    for (const { label, confidence } of results) {
+        console.log(`  ${label}: ${(confidence * 100).toFixed(1)}%`);
+    }
+    await unloadModel({ modelId });
+    await stopQVACProvider();
+}
+main().catch(console.error);

package/dist/examples/diffusion-esrgan-upscale.d.ts

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