hoomanjs 1.42.0 → 1.43.0

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

@@ -0,0 +1,47 @@
+import { StrandsMlxModel } from "./strands-mlx.js";
+import { REASONING_BUDGET_TOKENS } from "../types.js";
+import { markTotalInclusiveInputUsage } from "../usage.js";
+/**
+ * Strands {@link Model} backed by in-process Apple MLX via `mlex.js`
+ * (Apple Silicon Metal GPU; supported architectures: Qwen2/Llama-shaped,
+ * Qwen3, Qwen3.5 dense/MoE/vision, Gemma 4 text/multi-modal, NemotronH,
+ * DharaAR). Any quantization scheme MLX ships loads — bf16/fp16, affine
+ * 2–8 bit, mxfp4/mxfp8/nvfp4, and mixed per-layer checkpoints like OptiQ or
+ * Google QAT. MLX-format weights (e.g. `mlx-community` repos) are fetched
+ * from the Hugging Face Hub via `@huggingface/hub` into
+ * `~/.hooman/cache/huggingface` on first use.
+ */
+export function create(providerOptions, llmOptions) {
+    // Shared `reasoning` semantics: presence enables thinking (`effort`
+    // capping the reasoning span via mlex's reasoningBudgetTokens); omitting
+    // it renders the chat template with thinking off.
+    const reasoning = providerOptions.reasoning;
+    const effort = reasoning?.effort;
+    // `undefined`/`null`/`false` all disable caching; an object (even `{}`)
+    // enables it. Normalize `null` away since the internal model config only
+    // distinguishes `MlxPromptCacheConfig | false`.
+    const promptCache = providerOptions.promptCache;
+    const model = new StrandsMlxModel({
+        modelId: llmOptions.model,
+        ...(providerOptions.hfToken ? { hfToken: providerOptions.hfToken } : {}),
+        ...(promptCache !== undefined
+            ? { promptCache: promptCache === null ? false : promptCache }
+            : {}),
+        ...(reasoning !== undefined
+            ? {
+                reasoning: { ...(effort !== undefined ? { effort } : {}) },
+                thoughtBudgetTokens: REASONING_BUDGET_TOKENS[effort ?? "medium"],
+            }
+            : {}),
+        ...(llmOptions.temperature !== undefined
+            ? { temperature: llmOptions.temperature }
+            : {}),
+        ...(llmOptions.maxTokens !== undefined
+            ? { maxTokens: llmOptions.maxTokens }
+            : {}),
+    });
+    // mlex usage is OpenAI-style: promptTokens includes cachedTokens.
+    markTotalInclusiveInputUsage(model);
+    return model;
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/models/mlx/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAG3D;;;;;;;;;GASG;AACH,MAAM,UAAU,MAAM,CACpB,eAAmC,EACnC,UAAsB;IAEtB,oEAAoE;IACpE,yEAAyE;IACzE,kDAAkD;IAClD,MAAM,SAAS,GAAG,eAAe,CAAC,SAAS,CAAC;IAC5C,MAAM,MAAM,GAAG,SAAS,EAAE,MAAM,CAAC;IACjC,wEAAwE;IACxE,yEAAyE;IACzE,gDAAgD;IAChD,MAAM,WAAW,GAAG,eAAe,CAAC,WAAW,CAAC;IAChD,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC;QAChC,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,WAAW,KAAK,SAAS;YAC3B,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE;YAC7D,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;IACH,kEAAkE;IAClE,4BAA4B,CAAC,KAAK,CAAC,CAAC;IACpC,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/models/mlx/resolve-model.d.ts

@@ -0,0 +1,31 @@
+/**
+ * MLX model repos are cached under `~/.hooman/cache/huggingface` (HF cache
+ * layout), shared with the llama-cpp provider's GGUF downloads.
+ */
+export declare const mlxCacheDir: () => string;
+export type ParsedModelSpec = {
+    kind: "local";
+    path: string;
+} | {
+    kind: "hub";
+    repo: string;
+};
+/**
+ * Parse an LLM `model` value into either a local MLX model directory or a
+ * Hugging Face repo designation. Accepted shapes (an optional `hf:` prefix is
+ * stripped):
+ * - `/abs/path/to/model-dir`, `./rel/model-dir`, `~/models/model-dir`
+ *   (a directory containing `config.json` + safetensors weights)
+ * - `owner/repo` (an MLX-format repo, e.g. from `mlx-community`)
+ */
+export declare function parseModelSpec(model: string): ParsedModelSpec;
+/**
+ * Resolve a model spec to a local MLX model directory, downloading the repo
+ * (config, safetensors weights, tokenizer files) from the Hugging Face Hub
+ * into the Hooman cache when needed. Weight shards are reported as shards of
+ * one download via `subscribeModelDownloadProgress`; the smaller JSON/
+ * tokenizer files download silently unless they exceed the reporter's
+ * blob-size threshold. Returns the snapshot directory containing
+ * `config.json`, which `mlex.js`'s `MlexModel.load` consumes directly.
+ */
+export declare function resolveModelDir(model: string, hfToken?: string): Promise<string>;

package/dist/core/models/mlx/resolve-model.js

@@ -0,0 +1,149 @@
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { dirname, join, sep } from "path";
+import { listFiles, modelInfo } from "@huggingface/hub";
+import { cachePath } from "../../utils/paths.js";
+import { downloadFileWithProgress } from "../hub-download.js";
+/**
+ * MLX model repos are cached under `~/.hooman/cache/huggingface` (HF cache
+ * layout), shared with the llama-cpp provider's GGUF downloads.
+ */
+export const mlxCacheDir = () => join(cachePath(), "huggingface");
+function expandHome(p) {
+    if (p === "~" || p.startsWith(`~${sep}`) || p.startsWith("~/")) {
+        return join(homedir(), p.slice(1));
+    }
+    return p;
+}
+/**
+ * Parse an LLM `model` value into either a local MLX model directory or a
+ * Hugging Face repo designation. Accepted shapes (an optional `hf:` prefix is
+ * stripped):
+ * - `/abs/path/to/model-dir`, `./rel/model-dir`, `~/models/model-dir`
+ *   (a directory containing `config.json` + safetensors weights)
+ * - `owner/repo` (an MLX-format repo, e.g. from `mlx-community`)
+ */
+export function parseModelSpec(model) {
+    const spec = (model.startsWith("hf:") ? model.slice(3) : model).trim();
+    if (spec.length === 0) {
+        throw new Error("MLX model is not configured");
+    }
+    const expanded = expandHome(spec);
+    const looksLikePath = spec.startsWith("/") ||
+        spec.startsWith("./") ||
+        spec.startsWith("../") ||
+        spec.startsWith("~");
+    if (looksLikePath || existsSync(join(expanded, "config.json"))) {
+        return { kind: "local", path: expanded };
+    }
+    const segments = spec.split("/").filter((s) => s.length > 0);
+    if (segments.length === 2) {
+        return { kind: "hub", repo: spec };
+    }
+    throw new Error(`Invalid MLX model "${model}". Use a local MLX model directory ` +
+        `or an "owner/repo" Hugging Face repo (MLX format, e.g. mlx-community/...).`);
+}
+/**
+ * Repo files the MLX runtime needs: model config + weights + tokenizer
+ * assets. Everything else (README, images, .gitattributes) is skipped.
+ */
+const MODEL_FILE_EXTENSIONS = [
+    ".safetensors",
+    ".json",
+    ".jinja",
+    ".txt",
+    ".model",
+];
+function isModelFile(path) {
+    const lower = path.toLowerCase();
+    if (lower === ".gitattributes") {
+        return false;
+    }
+    return MODEL_FILE_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+/**
+ * Resolve a model spec to a local MLX model directory, downloading the repo
+ * (config, safetensors weights, tokenizer files) from the Hugging Face Hub
+ * into the Hooman cache when needed. Weight shards are reported as shards of
+ * one download via `subscribeModelDownloadProgress`; the smaller JSON/
+ * tokenizer files download silently unless they exceed the reporter's
+ * blob-size threshold. Returns the snapshot directory containing
+ * `config.json`, which `mlex.js`'s `MlexModel.load` consumes directly.
+ */
+export async function resolveModelDir(model, hfToken) {
+    const parsed = parseModelSpec(model);
+    if (parsed.kind === "local") {
+        if (!existsSync(join(parsed.path, "config.json"))) {
+            throw new Error(`MLX model directory not found (no config.json): ${parsed.path}`);
+        }
+        return parsed.path;
+    }
+    const accessToken = hfToken?.trim() || process.env.HF_TOKEN?.trim();
+    const credentials = accessToken ? { accessToken } : {};
+    const cacheDir = mlxCacheDir();
+    // Pin every file to the repo's current head commit: the HF cache layout
+    // names snapshot dirs after the revision each file resolved to, so
+    // un-pinned multi-file downloads would scatter across snapshot dirs and
+    // never form one complete model directory.
+    const info = await modelInfo({
+        name: parsed.repo,
+        additionalFields: ["sha"],
+        ...(accessToken ? { accessToken } : {}),
+    });
+    const revision = info.sha;
+    if (typeof revision !== "string" || revision.length === 0) {
+        throw new Error(`Cannot resolve the current revision of Hugging Face repo "${parsed.repo}".`);
+    }
+    const files = [];
+    for await (const entry of listFiles({
+        repo: parsed.repo,
+        recursive: true,
+        revision,
+        ...(accessToken ? { accessToken } : {}),
+    })) {
+        if (entry.type === "file" && isModelFile(entry.path)) {
+            files.push(entry.path);
+        }
+    }
+    if (!files.includes("config.json")) {
+        throw new Error(`Hugging Face repo "${parsed.repo}" does not look like an MLX model ` +
+            `(no config.json). Use an MLX-format repo, e.g. from mlx-community.`);
+    }
+    const weights = files.filter((f) => f.toLowerCase().endsWith(".safetensors"));
+    if (weights.length === 0) {
+        throw new Error(`No .safetensors weights found in Hugging Face repo "${parsed.repo}".`);
+    }
+    // Small metadata files first (cheap, near-instant), then the weight shards
+    // with shard-indexed progress so the UI shows "shard i of n".
+    const metadata = files.filter((f) => !f.toLowerCase().endsWith(".safetensors"));
+    let configPath;
+    for (const filePath of metadata.sort()) {
+        const local = await downloadFileWithProgress({
+            repo: parsed.repo,
+            filePath,
+            cacheDir,
+            credentials,
+            model,
+            revision,
+        });
+        if (filePath === "config.json") {
+            configPath = local;
+        }
+    }
+    weights.sort();
+    for (let i = 0; i < weights.length; i++) {
+        await downloadFileWithProgress({
+            repo: parsed.repo,
+            filePath: weights[i],
+            cacheDir,
+            credentials,
+            model,
+            revision,
+            ...(weights.length > 1
+                ? { shard: { index: i + 1, total: weights.length } }
+                : {}),
+        });
+    }
+    return dirname(configPath);
+}
+//# sourceMappingURL=resolve-model.js.map

package/dist/core/models/mlx/resolve-model.js.map

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

package/dist/core/models/mlx/strands-mlx.d.ts

@@ -0,0 +1,45 @@
+import { Model } from "@strands-agents/sdk";
+import type { BaseModelConfig, Message, StreamOptions } from "@strands-agents/sdk";
+import type { ModelStreamEvent } from "@strands-agents/sdk";
+import type { MlxPromptCacheConfig } from "../types.js";
+export interface MlxModelConfig extends BaseModelConfig {
+    /**
+     * Model spec: `owner/repo` Hugging Face repo in MLX format (e.g.
+     * `mlx-community/...`) or a local MLX model directory containing
+     * `config.json` + safetensors weights.
+     */
+    modelId?: string;
+    /** Hugging Face access token for gated/private repos (falls back to `HF_TOKEN`). */
+    hfToken?: string;
+    /**
+     * Whether turns may reuse KV state from mlex's internal prompt-cache pool
+     * (prefix matching against previous calls), applied once when the model
+     * is loaded. `undefined`/`false` disables caching entirely (every
+     * generate call forwards `promptCache: false`); an object (even `{}`)
+     * enables it, with its fields overriding mlex's own pool-sizing defaults.
+     */
+    promptCache?: MlxPromptCacheConfig | false;
+    /**
+     * Thinking controls. Presence enables reasoning (`enableThinking: true` on
+     * the chat template) with `effort` capping the reasoning span via
+     * `reasoningBudgetTokens`. Absence disables it: the template renders with
+     * thinking off and reasoning content is dropped.
+     */
+    reasoning?: {
+        effort?: "minimal" | "low" | "medium" | "high";
+    };
+    /** Cap on reasoning-span tokens while thinking is enabled. */
+    thoughtBudgetTokens?: number;
+}
+/** Strands {@link Model} backed by in-process Apple MLX via `mlex.js`. */
+export declare class StrandsMlxModel extends Model<MlxModelConfig> {
+    private config;
+    private modelPromise;
+    constructor(config: MlxModelConfig);
+    updateConfig(modelConfig: MlxModelConfig): void;
+    getConfig(): MlxModelConfig;
+    private getModel;
+    private initModel;
+    private buildGenerateOptions;
+    stream(messages: Message[], options?: StreamOptions): AsyncIterable<ModelStreamEvent>;
+}