@qvac/sdk 0.9.2 → 0.10.1

package/dist/server/utils/cache/types.d.ts

@@ -0,0 +1,8 @@
+export interface CacheMessage {
+    role: string;
+    content: string;
+    attachments?: {
+        path: string;
+    }[] | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/server/utils/cache/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/utils/checksum.d.ts

@@ -1,4 +1,4 @@
-import type { DownloadMetricsHooks } from "../rpc/handlers/load-model/types";
+import type { DownloadHooks } from "../rpc/handlers/load-model/types";
 export declare function calculateFileChecksum(filePath: string): Promise<string>;
-export declare function measureChecksum(filePath: string, hooks?: DownloadMetricsHooks): Promise<string>;
+export declare function measureChecksum(filePath: string, hooks?: DownloadHooks): Promise<string>;
 //# sourceMappingURL=checksum.d.ts.map

package/dist/server/utils/checksum.js

@@ -26,6 +26,6 @@ export async function calculateFileChecksum(filePath) {
 export async function measureChecksum(filePath, hooks) {
     const start = nowMs();
     const checksum = await calculateFileChecksum(filePath);
-    hooks?.addChecksumValidationTimeMs(nowMs() - start);
+    hooks?.addChecksumValidationTimeMs?.(nowMs() - start);
     return checksum;
 }

package/dist/server/utils/clear-storage.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveClearStorageTarget(modelPath: string, modelsCacheDir: string): {
+    path: string;
+    kind: "file" | "directory";
+};
+//# sourceMappingURL=clear-storage.d.ts.map

package/dist/server/utils/clear-storage.js

@@ -0,0 +1,17 @@
+export function resolveClearStorageTarget(modelPath, modelsCacheDir) {
+    const normalizedCache = modelsCacheDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    const normalizedPath = modelPath.replace(/\\/g, "/");
+    if (!normalizedPath.startsWith(`${normalizedCache}/`)) {
+        return { path: modelPath, kind: "file" };
+    }
+    const relativePath = normalizedPath.slice(normalizedCache.length + 1);
+    const parts = relativePath.split("/");
+    if (parts.length === 3 &&
+        (parts[0] === "sets" || parts[0] === "onnx") &&
+        parts[1] &&
+        parts[2]) {
+        const lastSlash = normalizedPath.lastIndexOf("/");
+        return { path: normalizedPath.slice(0, lastSlash), kind: "directory" };
+    }
+    return { path: modelPath, kind: "file" };
+}

package/dist/server/utils/completion-normalizer.d.ts

@@ -0,0 +1,17 @@
+import type { CompletionEvent, CompletionError, CompletionStats, NormalizerConfig, StopReason, ToolCall } from "../../schemas/index";
+export type CompletionNormalizer = ReturnType<typeof createCompletionNormalizer>;
+export declare function createCompletionNormalizer(config: NormalizerConfig): {
+    push: (token: string) => CompletionEvent[];
+    finish: (opts?: {
+        stats?: CompletionStats;
+        toolCalls?: ToolCall[];
+        error?: CompletionError;
+        stopReason?: StopReason;
+    }) => CompletionEvent[];
+    getAccumulated: () => {
+        rawText: string;
+        contentText: string;
+        thinkingText: string | undefined;
+    };
+};
+//# sourceMappingURL=completion-normalizer.d.ts.map

package/dist/server/utils/completion-normalizer.js

@@ -0,0 +1,413 @@
+import { parseToolCalls } from "./tools/index.js";
+const DIALECT_SPECS = {
+    hermes: {
+        toolFrames: [{ open: "<tool_call>", close: "</tool_call>" }],
+    },
+    // No streaming framing — tool calls are only recovered at finalization.
+    json: {
+        toolFrames: [],
+    },
+    pythonic: {
+        toolFrames: [
+            { open: "<|tool_call_start|>", close: "<|tool_call_end|>" },
+            {
+                open: "<|start_header_id|>tool_call<|end_header_id|>",
+                close: "<|eot_id|>",
+            },
+        ],
+    },
+    harmony: {
+        toolFrames: [
+            { open: "<|channel|>commentary to=functions.", close: "<|call|>" },
+        ],
+        thinkingFrames: [
+            { open: "<|channel|>analysis<|message|>", close: "<|end|>" },
+        ],
+        contentFrames: [
+            { open: "<|channel|>final<|message|>", close: "<|return|>" },
+        ],
+        // Role headers between channel frames + stray `<|return|>` closes.
+        dropTokens: [
+            "<|start|>assistant",
+            "<|start|>system",
+            "<|start|>user",
+            "<|return|>",
+        ],
+    },
+};
+// Capture-gated reasoning marker — the generic `<think>...</think>`
+// convention used by reasoning-tuned models. When the gate is off the
+// markers pass through into `contentDelta` unchanged (preserves the
+// pre-dialect behavior).
+const BUILTIN_THINKING = { open: "<think>", close: "</think>" };
+export function createCompletionNormalizer(config) {
+    let seq = 0;
+    let state = "content";
+    let rawText = "";
+    const contentParts = [];
+    const thinkingParts = [];
+    // Tool frame: buffer keeps the open + close markers in place so
+    // `parseToolCalls` can match its own dialect markers.
+    let toolCallBuffer = "";
+    let activeToolFrame = null;
+    // Thinking frame: tracks which frame's close marker we're scanning for
+    // (could be the built-in `<think>` or a dialect-specific frame like
+    // Harmony's `<|channel|>analysis<|message|>...<|end|>`).
+    let activeThinkingFrame = null;
+    // Content frame: inner streamed as it arrives; partial close tail buffered.
+    let activeContentFrame = null;
+    // Trailing chars that could be a prefix of a watched marker, so markers
+    // split across token pushes aren't missed by indexOf.
+    let contentTail = "";
+    let toolFramingTail = "";
+    let thinkingFramingTail = "";
+    let contentFramingTail = "";
+    const streamedToolCallKeys = new Set();
+    const toolsEnabled = config.tools.length > 0 && config.capabilities.toolCalling !== "none";
+    const useToolFraming = toolsEnabled && config.capabilities.toolCalling === "textParse";
+    // Register `<think>` only when both capability + capture opt in.
+    // Dialect protocol markers always register; capture only gates emission.
+    const useBuiltinThinkTags = config.captureThinking &&
+        config.capabilities.thinkingFraming === "thinkTags";
+    const dialect = config.toolDialect ?? "hermes";
+    const dialectSpec = DIALECT_SPECS[dialect];
+    const toolFrames = useToolFraming
+        ? dialectSpec.toolFrames
+        : [];
+    const thinkingFrames = [
+        ...(useBuiltinThinkTags ? [BUILTIN_THINKING] : []),
+        ...(dialectSpec.thinkingFrames ?? []),
+    ];
+    const contentFrames = dialectSpec.contentFrames ?? [];
+    const dropTokens = dialectSpec.dropTokens ?? [];
+    const markerToEntry = new Map();
+    const dropTokenSet = new Set();
+    const contentMarkers = [];
+    function registerFrames(frames, kind) {
+        for (const f of frames) {
+            if (markerToEntry.has(f.open))
+                continue;
+            markerToEntry.set(f.open, { kind, spec: f });
+            contentMarkers.push(f.open);
+        }
+    }
+    registerFrames(toolFrames, "tool");
+    registerFrames(thinkingFrames, "thinking");
+    registerFrames(contentFrames, "content");
+    for (const t of dropTokens) {
+        if (markerToEntry.has(t) || dropTokenSet.has(t))
+            continue;
+        dropTokenSet.add(t);
+        contentMarkers.push(t);
+    }
+    function nextSeq() {
+        return seq++;
+    }
+    function emitContent(events, text) {
+        if (!text)
+            return;
+        contentParts.push(text);
+        events.push({ type: "contentDelta", seq: nextSeq(), text });
+    }
+    // Capture-gated: thinking frames may register even when `captureThinking`
+    // is false (e.g. harmony's analysis channel, to strip markers from
+    // `contentDelta`) — drop the inner here instead of buffering it.
+    function emitThinking(events, text) {
+        if (!text)
+            return;
+        if (config.captureThinking) {
+            thinkingParts.push(text);
+            events.push({ type: "thinkingDelta", seq: nextSeq(), text });
+        }
+    }
+    function getToolCallKey(call) {
+        return `${call.name}:${JSON.stringify(call.arguments)}`;
+    }
+    function emitStreamedToolCall(events, call) {
+        streamedToolCallKeys.add(getToolCallKey(call));
+        events.push({ type: "toolCall", seq: nextSeq(), call });
+    }
+    function emitFinalToolCall(events, call) {
+        if (streamedToolCallKeys.has(getToolCallKey(call)))
+            return;
+        events.push({ type: "toolCall", seq: nextSeq(), call });
+    }
+    // Length of the longest suffix of `buf` that is also a prefix of any marker.
+    function trailingPartialMarkerLen(buf, markers) {
+        if (markers.length === 0 || buf.length === 0)
+            return 0;
+        const maxLen = Math.min(buf.length, markers.reduce((m, s) => Math.max(m, s.length), 0) - 1);
+        for (let len = maxLen; len > 0; len--) {
+            const suffix = buf.slice(buf.length - len);
+            for (const m of markers) {
+                if (m.startsWith(suffix))
+                    return len;
+            }
+        }
+        return 0;
+    }
+    function findEarliestMarker(buf, markers) {
+        let best = null;
+        for (const m of markers) {
+            const i = buf.indexOf(m);
+            if (i < 0)
+                continue;
+            if (best === null || i < best.idx)
+                best = { idx: i, marker: m };
+        }
+        return best;
+    }
+    function flushToolBuffer(events, closed) {
+        const raw = toolCallBuffer;
+        const frame = activeToolFrame;
+        toolCallBuffer = "";
+        activeToolFrame = null;
+        toolFramingTail = "";
+        if (!frame)
+            return;
+        // Empty-payload guard. Strip frame markers and check the inner is
+        // non-empty; surface a toolError on empty payloads so the literal
+        // markers don't leak into contentDelta.
+        let inner = raw;
+        if (inner.startsWith(frame.open))
+            inner = inner.slice(frame.open.length);
+        if (inner.endsWith(frame.close)) {
+            inner = inner.slice(0, inner.length - frame.close.length);
+        }
+        if (inner.trim().length === 0) {
+            events.push({
+                type: "toolError",
+                seq: nextSeq(),
+                error: { code: "PARSE_ERROR", message: "Empty tool_call frame" },
+            });
+            return;
+        }
+        const { toolCalls, errors } = parseToolCalls(raw, config.tools, dialect);
+        for (const call of toolCalls)
+            emitStreamedToolCall(events, call);
+        if (toolCalls.length === 0) {
+            if (errors.length > 0) {
+                for (const error of errors) {
+                    events.push({ type: "toolError", seq: nextSeq(), error });
+                }
+            }
+            else {
+                events.push({
+                    type: "toolError",
+                    seq: nextSeq(),
+                    error: {
+                        code: "PARSE_ERROR",
+                        message: closed
+                            ? "Failed to parse tool call from framed region"
+                            : "Incomplete tool call frame at stream end",
+                        raw,
+                    },
+                });
+            }
+            emitContent(events, raw);
+        }
+    }
+    function getStateTail() {
+        switch (state) {
+            case "content":
+                return contentTail;
+            case "thinkingFraming":
+                return thinkingFramingTail;
+            case "toolFraming":
+                return toolFramingTail;
+            case "contentFraming":
+                return contentFramingTail;
+        }
+    }
+    function processSegment(events, text) {
+        let buf = getStateTail() + text;
+        contentTail = "";
+        thinkingFramingTail = "";
+        toolFramingTail = "";
+        contentFramingTail = "";
+        while (buf.length > 0) {
+            if (state === "toolFraming") {
+                if (!activeToolFrame) {
+                    state = "content";
+                    continue;
+                }
+                const hit = buf.indexOf(activeToolFrame.close);
+                if (hit >= 0) {
+                    toolCallBuffer += buf.slice(0, hit + activeToolFrame.close.length);
+                    buf = buf.slice(hit + activeToolFrame.close.length);
+                    state = "content";
+                    flushToolBuffer(events, true);
+                    continue;
+                }
+                const tailLen = trailingPartialMarkerLen(buf, [activeToolFrame.close]);
+                const safeLen = buf.length - tailLen;
+                toolCallBuffer += buf.slice(0, safeLen);
+                toolFramingTail = buf.slice(safeLen);
+                buf = "";
+                continue;
+            }
+            if (state === "thinkingFraming") {
+                if (!activeThinkingFrame) {
+                    state = "content";
+                    continue;
+                }
+                const closeMarker = activeThinkingFrame.close;
+                const closeIdx = buf.indexOf(closeMarker);
+                if (closeIdx >= 0) {
+                    emitThinking(events, buf.slice(0, closeIdx));
+                    buf = buf.slice(closeIdx + closeMarker.length);
+                    activeThinkingFrame = null;
+                    state = "content";
+                    continue;
+                }
+                const tailLen = trailingPartialMarkerLen(buf, [closeMarker]);
+                const safeLen = buf.length - tailLen;
+                emitThinking(events, buf.slice(0, safeLen));
+                thinkingFramingTail = buf.slice(safeLen);
+                buf = "";
+                continue;
+            }
+            if (state === "contentFraming") {
+                if (!activeContentFrame) {
+                    state = "content";
+                    continue;
+                }
+                const closeMarker = activeContentFrame.close;
+                const closeIdx = buf.indexOf(closeMarker);
+                if (closeIdx >= 0) {
+                    emitContent(events, buf.slice(0, closeIdx));
+                    activeContentFrame = null;
+                    contentFramingTail = "";
+                    buf = buf.slice(closeIdx + closeMarker.length);
+                    state = "content";
+                    continue;
+                }
+                const tailLen = trailingPartialMarkerLen(buf, [closeMarker]);
+                const safeLen = buf.length - tailLen;
+                emitContent(events, buf.slice(0, safeLen));
+                contentFramingTail = buf.slice(safeLen);
+                buf = "";
+                continue;
+            }
+            const hit = findEarliestMarker(buf, contentMarkers);
+            if (hit) {
+                emitContent(events, buf.slice(0, hit.idx));
+                buf = buf.slice(hit.idx + hit.marker.length);
+                if (dropTokenSet.has(hit.marker)) {
+                    // Glue token between frames — strip and stay in content state.
+                    continue;
+                }
+                const entry = markerToEntry.get(hit.marker);
+                if (entry.kind === "tool") {
+                    toolCallBuffer = hit.marker;
+                    activeToolFrame = entry.spec;
+                    state = "toolFraming";
+                }
+                else if (entry.kind === "thinking") {
+                    activeThinkingFrame = entry.spec;
+                    state = "thinkingFraming";
+                }
+                else {
+                    activeContentFrame = entry.spec;
+                    state = "contentFraming";
+                }
+                continue;
+            }
+            const tailLen = trailingPartialMarkerLen(buf, contentMarkers);
+            const safeLen = buf.length - tailLen;
+            emitContent(events, buf.slice(0, safeLen));
+            contentTail = buf.slice(safeLen);
+            buf = "";
+        }
+    }
+    function push(token) {
+        const events = [];
+        rawText += token;
+        if (config.emitRawDeltas) {
+            events.push({ type: "rawDelta", seq: nextSeq(), text: token });
+        }
+        processSegment(events, token);
+        return events;
+    }
+    function finish(opts) {
+        const events = [];
+        // Drain pending tail bytes so we don't lose trailing chars when the
+        // stream ends mid-marker.
+        if (state === "content" && contentTail) {
+            emitContent(events, contentTail);
+            contentTail = "";
+        }
+        else if (state === "thinkingFraming" && thinkingFramingTail) {
+            emitThinking(events, thinkingFramingTail);
+            thinkingFramingTail = "";
+        }
+        else if (state === "toolFraming" && toolFramingTail) {
+            toolCallBuffer += toolFramingTail;
+            toolFramingTail = "";
+        }
+        else if (state === "contentFraming" && contentFramingTail) {
+            // Cutoff inside a partial close marker — emit tail as content.
+            emitContent(events, contentFramingTail);
+            contentFramingTail = "";
+        }
+        if (state === "toolFraming" && activeToolFrame) {
+            if (opts?.error) {
+                emitContent(events, toolCallBuffer);
+                toolCallBuffer = "";
+                activeToolFrame = null;
+            }
+            else {
+                flushToolBuffer(events, false);
+            }
+        }
+        else if (state === "contentFraming") {
+            activeContentFrame = null;
+        }
+        activeThinkingFrame = null;
+        state = "content";
+        if (!opts?.error) {
+            if (opts?.toolCalls) {
+                for (const call of opts.toolCalls) {
+                    emitFinalToolCall(events, call);
+                }
+            }
+        }
+        if (opts?.stats) {
+            events.push({
+                type: "completionStats",
+                seq: nextSeq(),
+                stats: opts.stats,
+            });
+        }
+        const raw = { fullText: rawText };
+        if (opts?.error) {
+            events.push({
+                type: "completionDone",
+                seq: nextSeq(),
+                stopReason: "error",
+                error: opts.error,
+                raw,
+            });
+        }
+        else if (opts?.stopReason) {
+            events.push({
+                type: "completionDone",
+                seq: nextSeq(),
+                stopReason: opts.stopReason,
+                raw,
+            });
+        }
+        else {
+            events.push({ type: "completionDone", seq: nextSeq(), raw });
+        }
+        return events;
+    }
+    function getAccumulated() {
+        return {
+            rawText,
+            contentText: contentParts.join(""),
+            thinkingText: thinkingParts.length > 0 ? thinkingParts.join("") : undefined,
+        };
+    }
+    return { push, finish, getAccumulated };
+}

package/dist/server/utils/expand-gguf-shards.d.ts

@@ -0,0 +1,3 @@
+/** Expand a sharded GGUF path into `.tensors.txt` plus all shards. */
+export declare function expandGGUFIntoShards(modelPath: string): string[];
+//# sourceMappingURL=expand-gguf-shards.d.ts.map

package/dist/server/utils/expand-gguf-shards.js

@@ -0,0 +1,22 @@
+const SHARD_PATTERN = /^(.+)-(\d{5})-of-(\d{5})\.gguf$/;
+/** Expand a sharded GGUF path into `.tensors.txt` plus all shards. */
+export function expandGGUFIntoShards(modelPath) {
+    const lastSep = Math.max(modelPath.lastIndexOf("/"), modelPath.lastIndexOf("\\"));
+    const dir = lastSep >= 0 ? modelPath.slice(0, lastSep) : "";
+    const sep = lastSep >= 0 ? modelPath.charAt(lastSep) : "/";
+    const filename = lastSep >= 0 ? modelPath.slice(lastSep + 1) : modelPath;
+    const match = filename.match(SHARD_PATTERN);
+    if (!match || !match[1] || !match[3])
+        return [modelPath];
+    const baseFilename = match[1];
+    const totalDigits = match[3];
+    const totalShards = Number.parseInt(totalDigits, 10);
+    if (totalShards <= 0)
+        return [modelPath];
+    const join = (name) => (dir ? `${dir}${sep}${name}` : name);
+    const shards = [join(`${baseFilename}.tensors.txt`)];
+    for (let i = 1; i <= totalShards; i++) {
+        shards.push(join(`${baseFilename}-${String(i).padStart(5, "0")}-of-${totalDigits}.gguf`));
+    }
+    return shards;
+}

package/dist/server/utils/formatting.js

@@ -13,7 +13,7 @@ function isModelDescriptor(value) {
     return (typeof value === "object" &&
         value !== null &&
         "src" in value &&
-        typeof value.src === "string");
+        typeof (value).src === "string");
 }
 function normalizeValue(value) {
     if (isModelDescriptor(value)) {

package/dist/server/utils/index.d.ts

@@ -1,10 +1,12 @@
 export * from "./archive";
-export * from "./cache";
+export * from "./cache/types";
+export * from "./cache/auto-history";
+export * from "./cache/paths";
 export * from "./checksum";
 export * from "./config-transform";
+export * from "./expand-gguf-shards";
 export * from "./formatting";
 export * from "./gguf-tensor-extractor";
-export * from "./model-path";
 export * from "./path-security";
 export * from "./shard-utils";
 //# sourceMappingURL=index.d.ts.map

package/dist/server/utils/index.js

@@ -1,9 +1,11 @@
 export * from "./archive.js";
-export * from "./cache.js";
+export * from "./cache/types.js";
+export * from "./cache/auto-history.js";
+export * from "./cache/paths.js";
 export * from "./checksum.js";
 export * from "./config-transform.js";
+export * from "./expand-gguf-shards.js";
 export * from "./formatting.js";
 export * from "./gguf-tensor-extractor.js";
-export * from "./model-path.js";
 export * from "./path-security.js";
 export * from "./shard-utils.js";

package/dist/server/utils/qvac-paths.d.ts

@@ -0,0 +1,2 @@
+export declare function getQvacPath(...subPaths: string[]): string;
+//# sourceMappingURL=qvac-paths.d.ts.map

package/dist/server/utils/qvac-paths.js

@@ -0,0 +1,5 @@
+import path from "bare-path";
+import { getEnv } from "../env.js";
+export function getQvacPath(...subPaths) {
+    return path.join(getEnv().HOME_DIR, ".qvac", ...subPaths);
+}

package/dist/server/utils/response-format.d.ts

@@ -0,0 +1,3 @@
+import type { ResponseFormat } from "../../schemas/index";
+export declare function getResponseFormatJsonSchema(responseFormat: ResponseFormat): string | undefined;
+//# sourceMappingURL=response-format.d.ts.map

package/dist/server/utils/response-format.js

@@ -0,0 +1,20 @@
+// Translates the request-level `responseFormat` into the JSON Schema string
+// that the llama.cpp addon's per-request `generationParams.json_schema`
+// expects. Returns `undefined` for `{ type: "text" }` (no constraint).
+//
+// The addon converts the schema to GBNF natively via
+// `json_schema_to_grammar()` and applies it for the duration of the request
+// only, restoring the prior sampling block afterwards — so this surface is
+// safe to use under concurrent completions on the same model. (Tool calling
+// still goes through `setupToolGrammar` / `modelConfig.grammar`; see the
+// mutual-exclusion check in `completionClientParamsSchema`.)
+export function getResponseFormatJsonSchema(responseFormat) {
+    switch (responseFormat.type) {
+        case "text":
+            return undefined;
+        case "json_object":
+            return JSON.stringify({ type: "object" });
+        case "json_schema":
+            return JSON.stringify(responseFormat.json_schema.schema);
+    }
+}

package/dist/server/utils/tool-integration.d.ts

@@ -1,4 +1,4 @@
-import type { Tool, ToolCallEvent } from "../../schemas/index";
+import type { Tool, ToolDialect } from "../../schemas/index";
 interface HistoryMessage {
     role: string;
     content: string;
@@ -6,8 +6,19 @@ interface HistoryMessage {
         path: string;
     }[] | undefined;
 }
-export declare function insertToolsIntoHistory(history: HistoryMessage[], tools: Tool[]): Array<HistoryMessage | Tool>;
-export declare function setupToolGrammar(modelConfig: Record<string, unknown>, tools: Tool[]): void;
-export declare function checkForToolEvents(accumulatedText: string, currentToken: string, tools: Tool[], emittedToolCallPositions: Set<number>): ToolCallEvent[];
+/**
+ * Static tools mode: prepend tools right after the system message (or at the
+ * very start when no system message is present). The tool block stays in the
+ * kv-cache for the whole chat session.
+ */
+export declare function prependToolsToHistory(history: HistoryMessage[], tools: Tool[]): Array<HistoryMessage | Tool>;
+/**
+ * Dynamic tools mode: append tools after the last history message. The
+ * addon's compact-tools mode anchors the block after the last user message
+ * and trims it from the kv-cache once the tool-call chain resolves, so a
+ * subsequent turn can ship a different tool set without poisoning the cache.
+ */
+export declare function appendToolsToHistory(history: HistoryMessage[], tools: Tool[]): Array<HistoryMessage | Tool>;
+export declare function detectToolDialect(modelId: string): ToolDialect;
 export {};
 //# sourceMappingURL=tool-integration.d.ts.map