hoomanjs 1.41.0 → 1.42.0

package/dist/core/models/download-progress.js

@@ -0,0 +1,154 @@
+/**
+ * Process-wide progress feed for model weight downloads (currently the
+ * llama-cpp provider fetching GGUF files from the Hugging Face Hub).
+ *
+ * The provider emits {@link ModelDownloadProgress} events while a file is
+ * actually being downloaded (nothing is emitted for cache hits); frontends
+ * subscribe once per process and render however fits their surface (chat TUI
+ * chrome row, exec/daemon stderr line, ACP `_hoomanjs/model_download`
+ * notification for the VS Code extension).
+ */
+const listeners = new Set();
+/** Subscribe to model download progress; returns an unsubscribe function. */
+export function subscribeModelDownloadProgress(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+/** Fan an event out to all subscribers (provider-side; listener errors are swallowed). */
+export function emitModelDownloadProgress(progress) {
+    for (const listener of [...listeners]) {
+        try {
+            listener(progress);
+        }
+        catch {
+            // A broken frontend listener must not fail the download itself.
+        }
+    }
+}
+// ---- Formatting helpers (shared by the chat TUI and CLI loggers) -----------
+const BYTE_UNITS = ["B", "KB", "MB", "GB", "TB"];
+/** "512 B", "1.5 MB", "1.71 GB" — human-readable byte size. */
+export function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0) {
+        return "0 B";
+    }
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < BYTE_UNITS.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    const digits = unit === 0 ? 0 : value >= 100 ? 0 : value >= 10 ? 1 : 2;
+    return `${value.toFixed(digits)} ${BYTE_UNITS[unit]}`;
+}
+/** "12.3 MB/s" — human-readable transfer rate. */
+export function formatBytesPerSecond(bytesPerSecond) {
+    return `${formatBytes(bytesPerSecond)}/s`;
+}
+/** "45s", "01:23", "1:02:03" — remaining-time estimate. */
+export function formatEtaSeconds(seconds) {
+    const total = Math.max(0, Math.round(seconds));
+    if (total < 60) {
+        return `${total}s`;
+    }
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const secs = total % 60;
+    const mmss = `${String(minutes).padStart(2, "0")}:${String(secs).padStart(2, "0")}`;
+    return hours > 0 ? `${hours}:${mmss}` : mmss;
+}
+/** Completion ratio in [0, 1], or `undefined` while the total is unknown. */
+export function downloadRatio(progress) {
+    if (progress.totalBytes === undefined || progress.totalBytes <= 0) {
+        return undefined;
+    }
+    return Math.min(1, progress.receivedBytes / progress.totalBytes);
+}
+/** "██████░░░░" — a fixed-width unicode progress bar for terminal surfaces. */
+export function renderDownloadBar(ratio, width = 20) {
+    const filled = Math.max(0, Math.min(width, Math.round(ratio * width)));
+    return "█".repeat(filled) + "░".repeat(width - filled);
+}
+/**
+ * One-line human summary, e.g.
+ * `model.gguf (shard 2/5) 42% • 730 MB / 1.71 GB • 12.3 MB/s • eta 01:23`.
+ */
+export function formatModelDownloadLine(progress) {
+    const shard = progress.shard
+        ? ` (shard ${progress.shard.index}/${progress.shard.total})`
+        : "";
+    if (progress.status === "error") {
+        return `${progress.file}${shard} download failed: ${progress.error ?? "unknown error"}`;
+    }
+    const parts = [];
+    const ratio = downloadRatio(progress);
+    const size = progress.totalBytes !== undefined
+        ? `${formatBytes(progress.receivedBytes)} / ${formatBytes(progress.totalBytes)}`
+        : formatBytes(progress.receivedBytes);
+    if (progress.status === "done") {
+        parts.push("done", size);
+    }
+    else {
+        if (ratio !== undefined) {
+            parts.push(`${Math.floor(ratio * 100)}%`);
+        }
+        parts.push(size);
+        if (progress.bytesPerSecond !== undefined) {
+            parts.push(formatBytesPerSecond(progress.bytesPerSecond));
+        }
+        if (progress.etaSeconds !== undefined) {
+            parts.push(`eta ${formatEtaSeconds(progress.etaSeconds)}`);
+        }
+    }
+    return `${progress.file}${shard} ${parts.join(" • ")}`;
+}
+/**
+ * Progress listener that renders to a terminal stream (exec/daemon stderr).
+ * On a TTY it redraws a single status line in place (with a bar); otherwise
+ * it logs a plain line at ~10% increments plus start/done/error, so piped
+ * logs stay readable.
+ */
+export function createModelDownloadLogger(options) {
+    const { stream } = options;
+    const prefix = options.prefix ?? "";
+    const tty = stream.isTTY === true;
+    let lastLoggedPercent = -1;
+    let lineOpen = false;
+    return (progress) => {
+        if (tty) {
+            const ratio = downloadRatio(progress);
+            const bar = progress.status === "downloading" && ratio !== undefined
+                ? `[${renderDownloadBar(ratio)}] `
+                : "";
+            const line = `${prefix}downloading ${bar}${formatModelDownloadLine(progress)}`;
+            stream.write(`\r\x1b[2K${line}`);
+            lineOpen = true;
+            if (progress.status !== "downloading") {
+                stream.write("\n");
+                lineOpen = false;
+                lastLoggedPercent = -1;
+            }
+            return;
+        }
+        if (lineOpen) {
+            lineOpen = false;
+        }
+        if (progress.status !== "downloading") {
+            stream.write(`${prefix}model download ${formatModelDownloadLine(progress)}\n`);
+            lastLoggedPercent = -1;
+            return;
+        }
+        const ratio = downloadRatio(progress);
+        const percent = ratio !== undefined ? Math.floor(ratio * 100) : undefined;
+        const shouldLog = lastLoggedPercent === -1 ||
+            (percent !== undefined && percent >= lastLoggedPercent + 10);
+        if (!shouldLog) {
+            return;
+        }
+        lastLoggedPercent = percent ?? 0;
+        stream.write(`${prefix}model download ${formatModelDownloadLine(progress)}\n`);
+    };
+}
+//# sourceMappingURL=download-progress.js.map

package/dist/core/models/download-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download-progress.js","sourceRoot":"","sources":["../../../src/core/models/download-progress.ts"],"names":[],"mappings":"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"}

package/dist/core/models/index.js

@@ -4,6 +4,7 @@ export const modelProviders = {
     bedrock: () => import("./bedrock.js"),
     google: () => import("./google.js"),
     groq: () => import("./groq.js"),
+    "llama-cpp": () => import("./llama-cpp/index.js"),
     minimax: () => import("./minimax.js"),
     moonshot: () => import("./moonshot.js"),
     ollama: () => import("./ollama/index.js"),

package/dist/core/models/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/models/index.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,cAAc,GAAiD;IAC1E,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC;IACzC,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC;IACjC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC;IACrC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC;IACnC,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC;IAC/B,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC;IACrC,QAAQ,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC;IACvC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC;IACzC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC;IACnC,UAAU,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC;IAC3C,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC;CAC9B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/models/index.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,cAAc,GAAiD;IAC1E,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC;IACzC,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC;IACjC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC;IACrC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC;IACnC,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC;IAC/B,WAAW,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,sBAAsB,CAAC;IACjD,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC;IACrC,QAAQ,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC;IACvC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC;IACzC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC;IACnC,UAAU,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC;IAC3C,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC;CAC9B,CAAC"}

package/dist/core/models/llama-cpp/gbnf-schema.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Conversion from standard JSON Schema (what Strands emits for tool specs via
+ * `z.toJSONSchema`) into node-llama-cpp's GBNF JSON schema subset.
+ *
+ * The GBNF subset (see node-llama-cpp `GbnfJsonSchema`) differs from JSON
+ * Schema in ways that break real tool schemas:
+ * - `anyOf`/`allOf` are not supported (only `oneOf`); a schema without a
+ *   recognized shape falls through to an "immutable type" check and throws
+ *   `Unknown immutable type undefined` at generation time.
+ * - Every property listed under `properties` is treated as required — there
+ *   is no way to express an optional key. We encode optionals as
+ *   `oneOf: [<schema>, { type: "null" }]` and strip the `null`s from the
+ *   generated params afterwards ({@link pruneOptionalNulls}).
+ * - Only `date-time`/`time`/`date` string formats are known; numeric bounds
+ *   (`minimum`/`maximum`/...), `default`, `propertyNames`, etc. are not.
+ */
+/** Whether the original schema itself accepts `null` as a value. */
+export declare function schemaAllowsNull(schema: unknown): boolean;
+/**
+ * Convert a JSON Schema into node-llama-cpp's GBNF subset. Lossy where the
+ * subset cannot express the original (numeric ranges, string formats, ...);
+ * untranslatable shapes degrade to an any-JSON-value grammar rather than
+ * failing generation.
+ */
+export declare function jsonSchemaToGbnf(schema: unknown): object;
+/**
+ * Remove `null` values that only exist because {@link jsonSchemaToGbnf}
+ * encodes optional properties as `oneOf: [<schema>, null]`. Walks the value
+ * together with the ORIGINAL JSON schema: a key is dropped when it is null,
+ * declared optional, and the original schema does not itself allow null.
+ */
+export declare function pruneOptionalNulls(value: unknown, schema: unknown): unknown;

package/dist/core/models/llama-cpp/gbnf-schema.js

@@ -0,0 +1,272 @@
+/**
+ * Conversion from standard JSON Schema (what Strands emits for tool specs via
+ * `z.toJSONSchema`) into node-llama-cpp's GBNF JSON schema subset.
+ *
+ * The GBNF subset (see node-llama-cpp `GbnfJsonSchema`) differs from JSON
+ * Schema in ways that break real tool schemas:
+ * - `anyOf`/`allOf` are not supported (only `oneOf`); a schema without a
+ *   recognized shape falls through to an "immutable type" check and throws
+ *   `Unknown immutable type undefined` at generation time.
+ * - Every property listed under `properties` is treated as required — there
+ *   is no way to express an optional key. We encode optionals as
+ *   `oneOf: [<schema>, { type: "null" }]` and strip the `null`s from the
+ *   generated params afterwards ({@link pruneOptionalNulls}).
+ * - Only `date-time`/`time`/`date` string formats are known; numeric bounds
+ *   (`minimum`/`maximum`/...), `default`, `propertyNames`, etc. are not.
+ */
+const IMMUTABLE_TYPES = new Set([
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "null",
+]);
+const GBNF_STRING_FORMATS = new Set(["date-time", "time", "date"]);
+/** Grammar for "any JSON value" — used when a schema cannot be translated. */
+const ANY_VALUE = {
+    oneOf: [
+        { type: ["string", "number", "boolean", "null"] },
+        { type: "object", additionalProperties: true },
+        { type: "array" },
+    ],
+};
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function descriptionOf(schema) {
+    return typeof schema.description === "string" && schema.description.length
+        ? { description: schema.description }
+        : {};
+}
+/** Whether the original schema itself accepts `null` as a value. */
+export function schemaAllowsNull(schema) {
+    if (!isObject(schema)) {
+        return false;
+    }
+    const type = schema.type;
+    if (type === "null" || (Array.isArray(type) && type.includes("null"))) {
+        return true;
+    }
+    if (schema.const === null) {
+        return true;
+    }
+    if (Array.isArray(schema.enum) && schema.enum.includes(null)) {
+        return true;
+    }
+    for (const key of ["anyOf", "oneOf", "allOf"]) {
+        const variants = schema[key];
+        if (Array.isArray(variants) && variants.some(schemaAllowsNull)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Convert a JSON Schema into node-llama-cpp's GBNF subset. Lossy where the
+ * subset cannot express the original (numeric ranges, string formats, ...);
+ * untranslatable shapes degrade to an any-JSON-value grammar rather than
+ * failing generation.
+ */
+export function jsonSchemaToGbnf(schema) {
+    if (schema === true || schema === undefined || schema === null) {
+        return ANY_VALUE;
+    }
+    if (!isObject(schema)) {
+        return ANY_VALUE;
+    }
+    if (Object.keys(schema).length === 0) {
+        return ANY_VALUE;
+    }
+    const desc = descriptionOf(schema);
+    if (schema.const !== undefined) {
+        const c = schema.const;
+        if (typeof c === "string" ||
+            typeof c === "number" ||
+            typeof c === "boolean" ||
+            c === null) {
+            return { const: c, ...desc };
+        }
+        return ANY_VALUE;
+    }
+    if (Array.isArray(schema.enum)) {
+        const values = schema.enum.filter((v) => typeof v === "string" ||
+            typeof v === "number" ||
+            typeof v === "boolean" ||
+            v === null);
+        if (values.length > 0) {
+            return { enum: values, ...desc };
+        }
+        return ANY_VALUE;
+    }
+    const variants = Array.isArray(schema.anyOf)
+        ? schema.anyOf
+        : Array.isArray(schema.oneOf)
+            ? schema.oneOf
+            : undefined;
+    if (variants !== undefined) {
+        if (variants.length === 0) {
+            return ANY_VALUE;
+        }
+        if (variants.length === 1) {
+            return { ...jsonSchemaToGbnf(variants[0]), ...desc };
+        }
+        return { oneOf: variants.map(jsonSchemaToGbnf), ...desc };
+    }
+    if (Array.isArray(schema.allOf)) {
+        // Proper allOf merging is out of scope; a single member is common (zod
+        // wraps descriptions this way), otherwise fall back to any-value.
+        if (schema.allOf.length === 1) {
+            return { ...jsonSchemaToGbnf(schema.allOf[0]), ...desc };
+        }
+        return ANY_VALUE;
+    }
+    const type = schema.type;
+    if (Array.isArray(type)) {
+        const types = type.filter((t) => typeof t === "string" && IMMUTABLE_TYPES.has(t));
+        if (types.length === type.length && types.length > 0) {
+            return { type: types, ...desc };
+        }
+        if (type.length > 0) {
+            return {
+                oneOf: type.map((t) => jsonSchemaToGbnf({ ...schema, type: t })),
+                ...desc,
+            };
+        }
+        return ANY_VALUE;
+    }
+    switch (type) {
+        case "string": {
+            const out = { type: "string", ...desc };
+            if (typeof schema.minLength === "number") {
+                out.minLength = schema.minLength;
+            }
+            if (typeof schema.maxLength === "number") {
+                out.maxLength = schema.maxLength;
+            }
+            if (typeof schema.format === "string" &&
+                GBNF_STRING_FORMATS.has(schema.format)) {
+                out.format = schema.format;
+            }
+            return out;
+        }
+        case "number":
+        case "integer":
+        case "boolean":
+        case "null":
+            return { type, ...desc };
+        case "object": {
+            const properties = isObject(schema.properties)
+                ? schema.properties
+                : undefined;
+            const required = new Set(Array.isArray(schema.required)
+                ? schema.required.filter((k) => typeof k === "string")
+                : []);
+            if (properties === undefined || Object.keys(properties).length === 0) {
+                return {
+                    type: "object",
+                    additionalProperties: convertAdditionalProperties(schema.additionalProperties, true),
+                    ...desc,
+                };
+            }
+            const props = {};
+            for (const [key, value] of Object.entries(properties)) {
+                const converted = jsonSchemaToGbnf(value);
+                if (required.has(key) || schemaAllowsNull(value)) {
+                    props[key] = converted;
+                    continue;
+                }
+                // GBNF grammars force every listed property to be generated, so
+                // optional keys accept null as an explicit "omitted" marker; the
+                // nulls are pruned before the tool call is emitted.
+                const note = "Optional — set to null to omit.";
+                const innerDesc = isObject(value)
+                    ? descriptionOf(value).description
+                    : undefined;
+                props[key] = {
+                    oneOf: [converted, { type: "null" }],
+                    description: innerDesc ? `${innerDesc} ${note}` : note,
+                };
+            }
+            return {
+                type: "object",
+                properties: props,
+                additionalProperties: convertAdditionalProperties(schema.additionalProperties, false),
+                ...desc,
+            };
+        }
+        case "array": {
+            const out = { type: "array", ...desc };
+            if (schema.items !== undefined && schema.items !== true) {
+                out.items = jsonSchemaToGbnf(schema.items);
+            }
+            if (Array.isArray(schema.prefixItems)) {
+                out.prefixItems = schema.prefixItems.map(jsonSchemaToGbnf);
+            }
+            if (typeof schema.minItems === "number") {
+                out.minItems = schema.minItems;
+            }
+            if (typeof schema.maxItems === "number") {
+                out.maxItems = schema.maxItems;
+            }
+            return out;
+        }
+        default:
+            return ANY_VALUE;
+    }
+}
+function convertAdditionalProperties(value, fallback) {
+    if (value === true || value === false) {
+        return value;
+    }
+    if (isObject(value)) {
+        return jsonSchemaToGbnf(value);
+    }
+    return fallback;
+}
+/**
+ * Remove `null` values that only exist because {@link jsonSchemaToGbnf}
+ * encodes optional properties as `oneOf: [<schema>, null]`. Walks the value
+ * together with the ORIGINAL JSON schema: a key is dropped when it is null,
+ * declared optional, and the original schema does not itself allow null.
+ */
+export function pruneOptionalNulls(value, schema) {
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    const s = isObject(schema) ? schema : {};
+    const variants = Array.isArray(s.anyOf)
+        ? s.anyOf
+        : Array.isArray(s.oneOf)
+            ? s.oneOf
+            : undefined;
+    if (variants !== undefined) {
+        const branch = variants.find((v) => isObject(v)
+            ? Array.isArray(value)
+                ? v.type === "array" || v.items !== undefined
+                : v.type === "object" || v.properties !== undefined
+            : false);
+        return pruneOptionalNulls(value, branch);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => pruneOptionalNulls(item, s.items));
+    }
+    const properties = isObject(s.properties) ? s.properties : undefined;
+    const required = new Set(Array.isArray(s.required)
+        ? s.required.filter((k) => typeof k === "string")
+        : []);
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        const propSchema = properties?.[key];
+        if (entry === null &&
+            properties !== undefined &&
+            propSchema !== undefined &&
+            !required.has(key) &&
+            !schemaAllowsNull(propSchema)) {
+            continue;
+        }
+        out[key] = pruneOptionalNulls(entry, propSchema ??
+            (isObject(s.additionalProperties) ? s.additionalProperties : undefined));
+    }
+    return out;
+}
+//# sourceMappingURL=gbnf-schema.js.map

package/dist/core/models/llama-cpp/gbnf-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gbnf-schema.js","sourceRoot":"","sources":["../../../../src/core/models/llama-cpp/gbnf-schema.ts"],"names":[],"mappings":"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"}

package/dist/core/models/llama-cpp/index.d.ts

@@ -0,0 +1,8 @@
+import { StrandsLlamaCppModel } from "./strands-llama-cpp.js";
+import type { LlamaCppProviderOptions, LlmOptions } from "../types.js";
+/**
+ * Strands {@link Model} backed by in-process llama.cpp via `node-llama-cpp`.
+ * GGUF weights are fetched from the Hugging Face Hub (via `@huggingface/hub`)
+ * into `~/.hooman/cache/huggingface` on first use.
+ */
+export declare function create(providerOptions: LlamaCppProviderOptions, llmOptions: LlmOptions): StrandsLlamaCppModel;

package/dist/core/models/llama-cpp/index.js

@@ -0,0 +1,37 @@
+import { StrandsLlamaCppModel } from "./strands-llama-cpp.js";
+import { REASONING_BUDGET_TOKENS } from "../types.js";
+/**
+ * Strands {@link Model} backed by in-process llama.cpp via `node-llama-cpp`.
+ * GGUF weights are fetched from the Hugging Face Hub (via `@huggingface/hub`)
+ * into `~/.hooman/cache/huggingface` on first use.
+ */
+export function create(providerOptions, llmOptions) {
+    // The shared `reasoning` option follows the usual Hooman semantics: its
+    // presence enables thinking (chat wrapper configured to allow thought
+    // segments, effort mapped to a thought-token budget and, on Harmony models,
+    // to the native reasoning-effort level); omitting it disables thinking
+    // (wrappers discourage thoughts, thought budget forced to 0).
+    const reasoning = providerOptions.reasoning;
+    const effort = reasoning?.effort;
+    return new StrandsLlamaCppModel({
+        modelId: llmOptions.model,
+        ...(providerOptions.hfToken ? { hfToken: providerOptions.hfToken } : {}),
+        ...(providerOptions.gpu !== undefined ? { gpu: providerOptions.gpu } : {}),
+        ...(providerOptions.contextSize !== undefined
+            ? { contextSize: providerOptions.contextSize }
+            : {}),
+        ...(reasoning !== undefined
+            ? {
+                reasoning: { ...(effort !== undefined ? { effort } : {}) },
+                thoughtBudgetTokens: REASONING_BUDGET_TOKENS[effort ?? "medium"],
+            }
+            : {}),
+        ...(llmOptions.temperature !== undefined
+            ? { temperature: llmOptions.temperature }
+            : {}),
+        ...(llmOptions.maxTokens !== undefined
+            ? { maxTokens: llmOptions.maxTokens }
+            : {}),
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/core/models/llama-cpp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/models/llama-cpp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAGtD;;;;GAIG;AACH,MAAM,UAAU,MAAM,CACpB,eAAwC,EACxC,UAAsB;IAEtB,wEAAwE;IACxE,sEAAsE;IACtE,4EAA4E;IAC5E,uEAAuE;IACvE,8DAA8D;IAC9D,MAAM,SAAS,GAAG,eAAe,CAAC,SAAS,CAAC;IAC5C,MAAM,MAAM,GAAG,SAAS,EAAE,MAAM,CAAC;IACjC,OAAO,IAAI,oBAAoB,CAAC;QAC9B,OAAO,EAAE,UAAU,CAAC,KAAK;QACzB,GAAG,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,GAAG,CAAC,eAAe,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1E,GAAG,CAAC,eAAe,CAAC,WAAW,KAAK,SAAS;YAC3C,CAAC,CAAC,EAAE,WAAW,EAAE,eAAe,CAAC,WAAW,EAAE;YAC9C,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,SAAS,KAAK,SAAS;YACzB,CAAC,CAAC;gBACE,SAAS,EAAE,EAAE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;gBAC1D,mBAAmB,EAAE,uBAAuB,CAAC,MAAM,IAAI,QAAQ,CAAC;aACjE;YACH,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,UAAU,CAAC,WAAW,KAAK,SAAS;YACtC,CAAC,CAAC,EAAE,WAAW,EAAE,UAAU,CAAC,WAAW,EAAE;YACzC,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,UAAU,CAAC,SAAS,KAAK,SAAS;YACpC,CAAC,CAAC,EAAE,SAAS,EAAE,UAAU,CAAC,SAAS,EAAE;YACrC,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC;AACL,CAAC"}

package/dist/core/models/llama-cpp/resolve-model.d.ts

@@ -0,0 +1,28 @@
+/** GGUF files are cached under `~/.hooman/cache/huggingface` (HF cache layout). */
+export declare const llamaCppCacheDir: () => string;
+export type ParsedModelSpec = {
+    kind: "local";
+    path: string;
+} | {
+    kind: "hub";
+    repo: string;
+    filePath?: string;
+    quant?: string;
+};
+/**
+ * Parse an LLM `model` value into either a local GGUF path or a Hugging Face
+ * repo designation. Accepted shapes (an optional `hf:` prefix is stripped):
+ * - `/abs/path/model.gguf`, `./rel/model.gguf`, `~/models/model.gguf`
+ * - `owner/repo` (the repo's GGUF file is auto-detected)
+ * - `owner/repo:Q8_0` (pick the variant matching a quant tag, llama.cpp style)
+ * - `owner/repo/path/to/file.gguf` (pin an exact file, e.g. a quant variant)
+ */
+export declare function parseModelSpec(model: string): ParsedModelSpec;
+/**
+ * Resolve a model spec to a local GGUF file path, downloading it from the
+ * Hugging Face Hub into the Hooman cache when needed. For sharded GGUFs all
+ * shards are fetched and the first shard's path is returned (llama.cpp finds
+ * the siblings next to it). Download progress is reported process-wide via
+ * `subscribeModelDownloadProgress` (see `../download-progress.ts`).
+ */
+export declare function resolveModelFile(model: string, hfToken?: string): Promise<string>;