@octocodeai/freellama-mcp-server 0.6.1 → 0.6.2

package/README.md

@@ -190,7 +190,7 @@ flowchart TD
     S --> G["Primary Ollama"]
     S --> U["Optional CPU Ollama"]
     B -->|"detail, raw; manage; delete"| G
-    B -->|"library view"| W["ollama.com library"]
+    B -->|"library view"| W["ollama.com library + Hugging Face GGUF"]
     B -->|"delegate_research"| A["allowlisted local adapter subprocess"]
     A --> S
     C -->|"resources/read on demand"| D["packaged docs/*.md"]
@@ -265,7 +265,7 @@ see `FREELLAMA_MCP_AUTOSTART_SERVE` in [Configuration](CONFIGURATION.md#environm
 | Tool | Needs `freellama serve`? | What it does |
 |---|---|---|
 | `doctor` | No (except `status`/`usage`) | Runtime/configuration diagnostic. Target another Ollama with `ollamaEndpoint` and serve with `serveEndpoint`. `summary` (default) returns endpoint, version, resident count, host/profile signals, and next step; `full` adds all non-duplicated diagnostics, including admission and categorized Ollama settings; `status` returns serve's live view (per-backend queues, current and adaptive limits, circuit breakers, loaded models, host memory, Ollama's effective settings, today's usage); `usage` returns task and token totals per day and model (`days`, default 7). The report distinguishes an observed same-user macOS process from configuration hints and never claims remote process visibility. |
-| `models` | `installed` (default) and `resident` do; `detail`/`raw`/`library` don't | Views: `installed` (capabilities, use explanations, derived `model_type`, VRAM, context, policy_rank), `resident` (loaded now + managed GPU/CPU split), `detail` (one model, maximum context), paged `raw` (`GET /api/tags`), `library` (two-step ollama.com search: omit `model` for families, pass `model:"<family>"` for all tags/`fitsInMemory`). `includeLibrary:true` enriches installed/detail views with sourced public guidance; `includeReadme:true` returns bounded README text in library step 2 or enriched detail. |
+| `models` | `installed` (default) and `resident` do; `detail`/`raw`/`library` don't | Views: `installed` (capabilities, use explanations, derived `model_type`, VRAM, context, policy_rank), `resident` (loaded now + managed GPU/CPU split), `detail` (one model, maximum context), paged `raw` (`GET /api/tags`), `library` (two-step public search: omit `model` to search ollama.com families and, for a `query`, Hugging Face GGUF repos (`source` limits it to one; `limit` applies per source); pass `model:"<family>"` or `model:"hf.co/<owner>/<repo>"` for every pullable tag with its size and `fitsInMemory`). `includeLibrary:true` enriches installed/detail views with sourced public guidance; `includeReadme:true` returns bounded README text in library step 2 or enriched detail. |
 | `run_task` | Yes | **Routes or executes** a chat/generate/embed call. `preview: true` accepts routing fields only and returns a decision without generation. Execution omits preview and supplies the payload. Embedding results withhold raw vectors by default (`returnEmbeddings: true` to get them). `tasks: [{id, independent:true, task}]` (max 64, `maxParallelism` bounds fan-out) runs a batch whose nested `task` takes the same fields; it is not a dependency scheduler. `warm: true` warms an exact installed `model` through managed admission with residency/profile controls and optional `defer:true`. |
 | `scope` | Yes | Creates, inspects, forks, or deletes process-local message history; history inclusion requires `includeMessages:true`. |
 | `session` | Yes | Creates, deletes, or kills model affinity without storing messages or KV; `kill` cancels the session's in-flight work. |

package/dist/index.js

@@ -22377,27 +22377,38 @@ function libraryTrialCandidate(tag, embedding) {
     caution: "Measure this exact tag on representative tasks before choosing it. Include resident runners, context/KV caches and OS headroom in memory fit. Discovery does not authorize a pull."
   };
 }
+var SIZE_CHIP = /^(?:\d+x)?(?:e)?\d+(?:\.\d+)?[kmbt]$/i;
 function parseModelSearch(html) {
   const results = [];
-  for (const block of html.split(/<li\s/).slice(1)) {
+  for (const block of html.split(/<li\b/).slice(1)) {
     const link = block.match(/href="\/(?:library\/([\w.-]+)|([\w.-]+\/[\w.-]+))"/);
     const name = link?.[1] ?? link?.[2];
     if (!name) continue;
-    if (!/<p\b[^>]*class="max-w-lg/.test(block)) continue;
-    const rawDescription = block.match(/<p class="max-w-lg[^"]*">([\s\S]*?)<\/p>/)?.[1];
-    const description = rawDescription === void 0 ? "" : decodeHtml(rawDescription.replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim();
-    const capabilities = [...block.matchAll(/text-(?:indigo-600|cyan-500)[^>]*>([a-z]+)<\/span>/g)].map(
-      (m) => m[1]
-    );
-    const stat = (label) => block.match(
-      new RegExp(`<span >([\\d.,KMB]+)<\\/span>\\s*<span class="hidden sm:flex">&nbsp;${label}`)
-    )?.[1] ?? null;
+    const rawDescription = block.match(/<p\b[^>]*>([\s\S]*?)<\/p>/)?.[1];
+    if (rawDescription === void 0) continue;
+    const description = decodeHtml(rawDescription.replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim();
+    const chips = [...block.matchAll(/<span\b[^>]*class="[^"]*\b(?:rounded-md|text-(?:indigo|cyan|blue)-\d+)\b[^"]*"[^>]*>\s*([\w.-]+)\s*<\/span>/g)].map((m) => ({ text: m[1].toLowerCase(), at: m.index }));
+    const first = chips.find((chip) => !SIZE_CHIP.test(chip.text));
+    const groupStart = first ? block.lastIndexOf("<div", first.at) : -1;
+    const groupEnd = groupStart >= 0 ? block.indexOf("</div>", first.at) : -1;
+    const inGroup = (at) => groupStart < 0 || groupEnd < 0 || at > groupStart && at < groupEnd;
+    const words = chips.filter((chip) => !SIZE_CHIP.test(chip.text) && /^[a-z]+$/.test(chip.text));
+    const sizes = chips.filter((chip) => SIZE_CHIP.test(chip.text)).map((chip) => chip.text);
+    const capabilities = [...new Set(words.filter((chip) => inGroup(chip.at)).map((chip) => chip.text))];
+    const labels = [...new Set(words.filter((chip) => !inGroup(chip.at)).map((chip) => chip.text))];
+    const legacyStat = (label) => block.match(new RegExp(`<span >([\\d.,KMB]+)<\\/span>\\s*<span class="hidden sm:flex">&nbsp;${label}`))?.[1] ?? null;
+    const downloads = block.match(/title="([\d,]+) downloads"/)?.[1];
+    const pullsShort = block.match(/title="[\d,]+ downloads"[\s\S]*?<span\s*>([\d.,]+[KMB]?)<\/span>/)?.[1];
+    const tagCount = block.match(/>\s*(\d+)\s+tags?\s*</)?.[1];
     results.push({
       name,
       description: clipText(description, 160),
       capabilities,
-      pulls: stat("Pulls"),
-      tags: stat("Tag"),
+      ...labels.length ? { labels } : {},
+      ...sizes.length ? { sizes } : {},
+      pulls: pullsShort ?? legacyStat("Pulls"),
+      ...downloads ? { downloads: Number(downloads.replace(/,/g, "")) } : {},
+      tags: tagCount ?? legacyStat("Tag"),
       cloudAvailable: capabilities.includes("cloud")
     });
   }
@@ -22436,6 +22447,130 @@ function parseModelTags(html, family) {
   return { family, tags };
 }
 
+// src/huggingface.ts
+var HUB = "https://huggingface.co";
+var MAX_JSON_BYTES = 4 * 1024 * 1024;
+function huggingFaceReference(model) {
+  const match = model.match(/^(?:https?:\/\/)?(?:hf\.co|huggingface\.co)\/([\w.-]+)\/([\w.-]+?)(?::([\w.-]+))?$/i);
+  if (!match || [match[1], match[2]].some((part) => part === "." || part === "..")) return null;
+  const repo = `${match[1]}/${match[2]}`;
+  return { repo, family: `hf.co/${repo}`, quant: match[3] ?? null, url: `${HUB}/${repo}` };
+}
+var QUANT = /^(?:UD-)?(?:I?Q\d(?:_[A-Z0-9]+)*|BF16|F16|F32|MXFP4(?:_MOE)?|TQ\d_\d)$/i;
+var SPLIT = /-\d{5}-of-\d{5}$/;
+function quantOf(path6) {
+  const parts = path6.split("/");
+  const stem = parts.pop().replace(/\.gguf$/i, "").replace(SPLIT, "");
+  for (let index = 0; index <= stem.length; index++) {
+    if (index > 0 && !/[-.]/.test(stem[index - 1])) continue;
+    if (QUANT.test(stem.slice(index))) return stem.slice(index);
+  }
+  return parts.reverse().find((dir) => QUANT.test(dir)) ?? null;
+}
+var decimalSize = (bytes) => bytes >= 1e9 ? `${(bytes / 1e9).toFixed(1)}GB` : `${Math.round(bytes / 1e6)}MB`;
+function parseHuggingFaceFiles(tree, repo) {
+  const builds = /* @__PURE__ */ new Map();
+  const projectors = [];
+  for (const entry of tree) {
+    if (entry.type !== "file" || !entry.path || !/\.gguf$/i.test(entry.path)) continue;
+    const file = entry.path.split("/").pop();
+    if (/mmproj/i.test(file)) {
+      projectors.push(entry.path);
+      continue;
+    }
+    const key = entry.path.replace(/-\d{5}-of-(\d{5})\.gguf$/i, "-00001-of-$1.gguf");
+    const bytes = entry.lfs?.size ?? entry.size ?? 0;
+    const build = builds.get(key) ?? { path: key, file: key.split("/").pop(), quant: quantOf(entry.path), bytes: 0, files: 0 };
+    builds.set(key, { ...build, bytes: build.bytes + bytes, files: build.files + 1 });
+  }
+  const perQuant = /* @__PURE__ */ new Map();
+  for (const { quant } of builds.values()) if (quant) perQuant.set(quant.toLowerCase(), (perQuant.get(quant.toLowerCase()) ?? 0) + 1);
+  const tags = [...builds.values()].sort((a, b) => a.bytes - b.bytes).map(({ path: path6, file, quant, bytes, files }) => ({
+    tag: `hf.co/${repo}:${quant && perQuant.get(quant.toLowerCase()) === 1 ? quant : file}`,
+    quant,
+    path: path6,
+    size: bytes ? decimalSize(bytes) : null,
+    sizeBytes: bytes || null,
+    files,
+    cloud: false,
+    // Hugging Face's Ollama guide shows single-file builds; say so rather than promise a pull.
+    ...files > 1 ? { note: `Split into ${files} files; the Hub's Ollama guide documents single-file GGUFs, so confirm the pull.` } : {}
+  }));
+  return { tags, projectors };
+}
+function parseHuggingFaceSearch(models) {
+  return models.filter((model) => model.id).map((model) => ({
+    name: `hf.co/${model.id}`,
+    source: "huggingface",
+    task: model.pipeline_tag ?? null,
+    downloads: model.downloads ?? null,
+    likes: model.likes ?? null,
+    updated: model.lastModified ?? null
+  }));
+}
+var HUB_EMBEDDING_TASKS = /* @__PURE__ */ new Set(["feature-extraction", "sentence-similarity"]);
+var HuggingFaceClient = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  options;
+  async json(url) {
+    const response = await (this.options.fetch ?? fetch)(url, {
+      method: "GET",
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(this.options.timeoutMs ?? Math.min(DEFAULT_OLLAMA_FETCH_TIMEOUT_SECONDS * 1e3, 1e4))
+    });
+    if (!response.ok) {
+      await response.body?.cancel();
+      throw new Error(response.status === 404 || response.status === 401 ? `Hugging Face has no public model at ${url} (HTTP ${response.status}).` : `Hugging Face returned HTTP ${response.status}.`);
+    }
+    const text = await response.text();
+    if (text.length > MAX_JSON_BYTES) throw new Error("Hugging Face response exceeds the 4 MiB limit.");
+    return JSON.parse(text);
+  }
+  stamp() {
+    return new Date((this.options.now ?? Date.now)()).toISOString();
+  }
+  /** GGUF repositories matching `query`, most downloaded (or newest) first. */
+  async search(query, { limit = 10, order = "popular", task } = {}) {
+    const params = new URLSearchParams({
+      search: query,
+      filter: "gguf",
+      sort: order === "newest" ? "lastModified" : "downloads",
+      direction: "-1",
+      limit: String(limit)
+    });
+    for (const field of ["downloads", "likes", "pipeline_tag", "lastModified"]) params.append("expand[]", field);
+    if (task) params.set("pipeline_tag", task);
+    const url = `${HUB}/api/models?${params}`;
+    return { url, models: parseHuggingFaceSearch(await this.json(url)), fetchedAt: this.stamp() };
+  }
+  /** One repo's pullable quants, task, architecture and context length. */
+  async lookup(model) {
+    const ref = huggingFaceReference(model);
+    if (!ref) throw new Error("Use hf.co/<owner>/<repo>, the name Ollama pulls from Hugging Face.");
+    const info = await this.json(
+      `${HUB}/api/models/${ref.repo}?expand[]=gguf&expand[]=pipeline_tag&expand[]=downloads&expand[]=likes&expand[]=lastModified&expand[]=sha&expand[]=gated`
+    );
+    const tree = await this.json(`${HUB}/api/models/${ref.repo}/tree/${info.sha ?? "main"}?recursive=true`);
+    return {
+      ...ref,
+      task: info.pipeline_tag ?? null,
+      revision: info.sha ?? null,
+      // "auto" or "manual": Hugging Face serves the files only after you accept the repo's terms.
+      gated: info.gated && info.gated !== "false" ? info.gated : false,
+      architecture: info.gguf?.architecture ?? null,
+      contextLength: info.gguf?.context_length ?? null,
+      parameters: info.gguf?.total ?? null,
+      downloads: info.downloads ?? null,
+      likes: info.likes ?? null,
+      updated: info.lastModified ?? null,
+      ...parseHuggingFaceFiles(tree, ref.repo),
+      fetchedAt: this.stamp()
+    };
+  }
+};
+
 // src/model-knowledge.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
 var FAILURE_TTL_MS = 60 * 1e3;
@@ -22713,12 +22848,32 @@ var modelsResultSchema = external_exports.object({
   library: external_exports.unknown().optional()
 }).passthrough();
 var ollamaLibrary = new OllamaLibraryClient();
+var huggingFace = new HuggingFaceClient();
 var HOST_MEMORY_FIT_FRACTION = 0.6;
+var HUB_TASKS = /* @__PURE__ */ new Map([
+  ["embedding", ["feature-extraction", "sentence-similarity"]],
+  ["vision", ["image-text-to-text"]]
+]);
+function annotateTags(tags, installed, memoryBytes, embedding) {
+  const budget = memoryBytes ? memoryBytes * HOST_MEMORY_FIT_FRACTION : null;
+  const local = installed ? new Set([...installed].map((name) => name.toLowerCase())) : null;
+  const annotated = tags.map((t) => ({
+    ...t,
+    installed: local ? local.has(t.tag.toLowerCase()) : null,
+    fitsInMemory: budget && t.sizeBytes ? t.sizeBytes <= budget : null,
+    fitScope: "host_memory_budget_only"
+  }));
+  const sized = annotated.filter((t) => t.fitsInMemory === true && !t.cloud && t.sizeBytes);
+  const best = budget ? sized.sort((a, b) => embedding ? (a.sizeBytes ?? 0) - (b.sizeBytes ?? 0) : (b.sizeBytes ?? 0) - (a.sizeBytes ?? 0))[0] : void 0;
+  return { annotated, budget, best };
+}
+var NO_PROFILE = "No machine profile (freellama serve unreachable), so memory fit could not be checked and no tag is recommended. Start serve, or read the sizes yourself.";
 async function libraryLookup({
   model,
   query,
   capabilities,
   order,
+  source,
   limit,
   cursor,
   includeReadme,
@@ -22746,6 +22901,40 @@ async function libraryLookup({
     return errorResult(new Error("Library step 1 has no `cursor`; it pages step-2 tags. Use `limit` for search, or pass `model`."));
   }
   try {
+    if (model && huggingFaceReference(model)) {
+      const hub2 = await huggingFace.lookup(model);
+      const { installed: installed2, installedUnavailable: installedUnavailable2, memoryBytes } = await localState();
+      const embedding = HUB_EMBEDDING_TASKS.has(hub2.task ?? "");
+      const { annotated, budget, best } = annotateTags(hub2.tags, installed2, memoryBytes, embedding);
+      const tagPage = pageLiveList(annotated, limit, cursor, (tag) => tag.tag);
+      return structuredResult({
+        family: hub2.family,
+        source: "huggingface",
+        sourcePage: hub2.url,
+        library: {
+          status: hub2.tags.length ? "available" : "no_gguf",
+          fetchedAt: hub2.fetchedAt,
+          task: hub2.task,
+          revision: hub2.revision,
+          ...hub2.gated ? { gated: hub2.gated, gatedNote: "Accept the repo's terms on Hugging Face first; its Ollama guide documents private pulls through your Ollama SSH key added to your Hugging Face account." } : {},
+          architecture: hub2.architecture,
+          contextLength: hub2.contextLength,
+          parameters: hub2.parameters,
+          downloads: hub2.downloads,
+          likes: hub2.likes,
+          updated: hub2.updated,
+          ...hub2.projectors.length ? { visionProjectors: hub2.projectors } : {}
+        },
+        ...installedUnavailable2 ? { installedUnavailable: installedUnavailable2 } : {},
+        machineMemoryBytes: memoryBytes,
+        fitBudgetBytes: budget,
+        tags: tagPage.items,
+        page: { returned: tagPage.returned, total: tagPage.total, next_cursor: tagPage.next_cursor },
+        pull: hub2.tags.length ? `ollama_manage {action:"pull", model:"<tag>"} after approval; Ollama picks Q4_K_M for a bare ${hub2.family} when the repo has it.` : "This repository has no GGUF files Ollama can pull.",
+        recommendationUnavailable: budget ? void 0 : NO_PROFILE,
+        recommendation: best ? libraryTrialCandidate(best.tag, embedding) : null
+      });
+    }
     if (model) {
       const ref = libraryReference(model);
       if (!ref) throw new Error("Use an exact Ollama family or namespace/model name, not a URL or path.");
@@ -22761,20 +22950,12 @@ async function libraryLookup({
       });
       const tags = library.tags;
       const { installed: installed2, installedUnavailable: installedUnavailable2, memoryBytes } = await localState();
-      const budget = memoryBytes ? memoryBytes * HOST_MEMORY_FIT_FRACTION : null;
-      const annotated = tags.map((t) => ({
-        ...t,
-        installed: installed2 ? installed2.has(t.tag) : null,
-        fitsInMemory: budget && t.sizeBytes ? t.sizeBytes <= budget : null,
-        fitScope: "host_memory_budget_only"
-      }));
-      const runnable = annotated.filter((t) => t.fitsInMemory === true && !t.cloud);
       const isEmbeddingFamily = library.card.capabilities.includes("embedding");
-      const sized = runnable.filter((t) => t.sizeBytes);
-      const best = budget ? isEmbeddingFamily ? sized.sort((a, b) => (a.sizeBytes ?? 0) - (b.sizeBytes ?? 0))[0] : sized.sort((a, b) => (b.sizeBytes ?? 0) - (a.sizeBytes ?? 0))[0] : void 0;
+      const { annotated, budget, best } = annotateTags(tags, installed2, memoryBytes, isEmbeddingFamily);
       const tagPage = pageLiveList(annotated, limit, cursor, (tag) => tag.tag);
       return structuredResult({
         family,
+        source: "ollama",
         sourcePage: ref.url,
         library: {
           status: library.status,
@@ -22790,7 +22971,7 @@ async function libraryLookup({
         fitBudgetBytes: budget,
         tags: tagPage.items,
         page: { returned: tagPage.returned, total: tagPage.total, next_cursor: tagPage.next_cursor },
-        recommendationUnavailable: budget ? void 0 : "No machine profile (freellama serve unreachable), so memory fit could not be checked and no tag is recommended. Start serve, or read the sizes yourself.",
+        recommendationUnavailable: budget ? void 0 : NO_PROFILE,
         recommendation: best ? libraryTrialCandidate(best.tag, isEmbeddingFamily) : null
       });
     }
@@ -22798,20 +22979,44 @@ async function libraryLookup({
     for (const c of capabilities ?? []) params.append("c", c);
     if (query) params.set("q", query);
     if (order === "newest") params.set("o", "newest");
-    const search = await ollamaLibrary.search(params);
-    const url = search.url;
-    const parsed = search.models.slice(0, limit ?? 10);
+    const hubTasks = (capabilities ?? []).map((c) => HUB_TASKS.get(c));
+    const hubSkipped = source === "ollama" ? "source is ollama" : !query ? "the Hub is searched only with a query" : hubTasks.length > 1 || hubTasks.some((tasks) => !tasks) ? `the Hub has no filter for ${(capabilities ?? []).filter((c) => !HUB_TASKS.has(c)).join(", ") || "several capabilities at once"}` : null;
+    if (source === "huggingface" && hubSkipped) throw new Error(`source "huggingface" cannot be searched: ${hubSkipped}.`);
+    const searchHub = async () => {
+      const results = await Promise.all((hubTasks[0] ?? [void 0]).map((task) => huggingFace.search(query, { limit: limit ?? 10, order, task })));
+      const seen = /* @__PURE__ */ new Set();
+      const models = results.flatMap((r) => r.models).filter((m) => !seen.has(m.name) && seen.add(m.name)).sort((a, b) => order === "newest" ? String(b.updated).localeCompare(String(a.updated)) : (b.downloads ?? 0) - (a.downloads ?? 0)).slice(0, limit ?? 10);
+      return { url: results[0].url, models, fetchedAt: results[0].fetchedAt };
+    };
+    const [ollamaSearch, hubSearch] = await Promise.allSettled([
+      source === "huggingface" ? Promise.resolve(null) : ollamaLibrary.search(params),
+      hubSkipped ? Promise.resolve(null) : searchHub()
+    ]);
+    const tried = [source === "huggingface" ? null : ollamaSearch, hubSkipped ? null : hubSearch].filter(Boolean);
+    if (tried.every((result) => result.status === "rejected")) {
+      throw new Error(tried.map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason)).join("; "));
+    }
+    const ollama = ollamaSearch.status === "fulfilled" ? ollamaSearch.value : null;
+    const hub = hubSearch.status === "fulfilled" ? hubSearch.value : null;
+    const ollamaRows = (ollama?.models ?? []).slice(0, limit ?? 10).map((m) => ({ ...m, source: "ollama" }));
+    const hubRows = hub?.models ?? [];
     const { installed, installedUnavailable } = await localState();
-    const installedFamilies = installed ? new Set([...installed].map((n) => n.split(":")[0])) : null;
+    const local = installed ? [...installed].map((n) => n.toLowerCase()) : null;
+    const isInstalled = (name) => local ? local.some((n) => n.split(":")[0] === name.toLowerCase()) : null;
+    const reason = (result) => result.status === "rejected" ? result.reason instanceof Error ? result.reason.message : String(result.reason) : void 0;
     return structuredResult({
-      query: url,
-      fetchedAt: search.fetchedAt,
-      ...parsed.length === 0 ? { searchUnavailable: "No result cards were recognized. The query may have no matches or Ollama's markup may have changed; inspect the source URL." } : {},
+      query: ollama?.url ?? hub?.url ?? null,
+      ...ollama && hub ? { hubQuery: hub.url } : {},
+      fetchedAt: ollama?.fetchedAt ?? hub?.fetchedAt ?? null,
+      ...ollama && ollamaRows.length === 0 ? { searchUnavailable: "No ollama.com result cards were recognized. The query may have no matches or Ollama's markup may have changed; inspect the source URL." } : {},
+      ...reason(ollamaSearch) ? { ollamaUnavailable: reason(ollamaSearch) } : {},
+      ...reason(hubSearch) ? { huggingFaceUnavailable: reason(hubSearch) } : {},
+      ...hubSkipped && source !== "ollama" ? { huggingFaceSkipped: hubSkipped } : {},
       order: order ?? "popular",
-      count: parsed.length,
+      count: ollamaRows.length + hubRows.length,
       ...installedUnavailable ? { installedUnavailable } : {},
-      nextStep: 'Not pullable yet. Call again with view:"library", model:"<name>" to get tags, sizes and memory fit.',
-      models: parsed.map((m) => ({ ...m, installed: installedFamilies ? installedFamilies.has(m.name) : null }))
+      nextStep: 'Not pullable yet. Call again with view:"library", model:"<name>" (an Ollama family or hf.co/<owner>/<repo>) to get tags, sizes and memory fit.',
+      models: [...ollamaRows, ...hubRows].map((m) => ({ ...m, installed: isInstalled(m.name) }))
     });
   } catch (error2) {
     return errorResult(error2);
@@ -22821,7 +23026,7 @@ function registerModelsTool(server2) {
   server2.registerTool(
     "models",
     {
-      description: "Use when: listing installed or loaded models with capabilities, policy rank and memory fit, inspecting one model, or searching ollama.com (view:library). Do not use when: running work (run_task) or pulling (ollama_manage). Returns: models; library lists families first, then one family's tags.",
+      description: "Use when: listing installed or loaded models with capabilities, policy rank and memory fit, inspecting one model, or searching ollama.com and Hugging Face GGUF repos (view:library). Do not use when: running work (run_task) or pulling (ollama_manage). Returns: models; library lists families first, then one family's tags.",
       inputSchema: external_exports.object({
         view: external_exports.enum(["installed", "resident", "detail", "raw", "library"]).optional(),
         model: external_exports.string().min(1).optional(),
@@ -22829,8 +23034,9 @@ function registerModelsTool(server2) {
         includeLibrary: external_exports.boolean().optional(),
         includeReadme: external_exports.boolean().optional(),
         query: external_exports.string().min(1).optional(),
-        capabilities: external_exports.array(external_exports.enum(["vision", "tools", "thinking", "embedding", "cloud"])).min(1).max(5).optional(),
+        capabilities: external_exports.array(external_exports.string().regex(/^[a-z][a-z-]*$/).describe("ollama.com capability word, e.g. vision, tools, thinking, embedding, audio, decision, cloud")).min(1).max(8).optional(),
         order: external_exports.enum(["popular", "newest"]).optional(),
+        source: external_exports.enum(["ollama", "huggingface"]).optional(),
         limit: external_exports.number().int().positive().max(50).optional(),
         cursor: external_exports.string().min(1).optional(),
         endpoint: endpointParam,
@@ -22839,7 +23045,7 @@ function registerModelsTool(server2) {
       outputSchema: modelsResultSchema,
       annotations: { readOnlyHint: true }
     },
-    async ({ view, model, includeVerbose, includeLibrary, includeReadme, query, capabilities, order, limit, cursor, endpoint, ollamaEndpoint }) => {
+    async ({ view, model, includeVerbose, includeLibrary, includeReadme, query, capabilities, order, source, limit, cursor, endpoint, ollamaEndpoint }) => {
       try {
         const selectedView = view ?? "installed";
         if (includeLibrary !== void 0 && selectedView !== "installed" && selectedView !== "detail") {
@@ -22848,7 +23054,7 @@ function registerModelsTool(server2) {
         if (includeReadme !== void 0 && !(selectedView === "library" && model || selectedView === "detail" && includeLibrary === true)) {
           return errorResult(new Error('`includeReadme` needs library step 2, or view "detail" with `includeLibrary:true`.'));
         }
-        if (selectedView !== "library" && [query, capabilities, order].some((value) => value !== void 0)) {
+        if (selectedView !== "library" && [query, capabilities, order, source].some((value) => value !== void 0)) {
           return errorResult(new Error(`view "${selectedView}" does not accept library search fields.`));
         }
         if (selectedView !== "library" && selectedView !== "raw" && [limit, cursor].some((value) => value !== void 0)) {
@@ -22860,7 +23066,7 @@ function registerModelsTool(server2) {
         if (selectedView !== "detail" && selectedView !== "library" && model !== void 0) {
           return errorResult(new Error('`model` is valid only for views "detail" and "library".'));
         }
-        if (selectedView === "library" && model && [query, capabilities, order].some((value) => value !== void 0)) {
+        if (selectedView === "library" && model && [query, capabilities, order, source].some((value) => value !== void 0)) {
           return errorResult(
             new Error("Library step 2 accepts only `model` plus endpoint overrides; omit step-1 search fields.")
           );
@@ -22923,7 +23129,7 @@ function registerModelsTool(server2) {
             });
           }
           case "library":
-            return await libraryLookup({ model, query, capabilities, order, limit, cursor, includeReadme, endpoint, ollamaEndpoint });
+            return await libraryLookup({ model, query, capabilities, order, source, limit, cursor, includeReadme, endpoint, ollamaEndpoint });
           default: {
             const result = parsedResult(await listModels2(endpoint));
             if (!isStructuredSuccess(result)) return result;

package/docs/ARCHITECTURE.md

@@ -395,9 +395,11 @@ authority. Configured settings alone do not prove physical processor placement.
 The shared [resource governor](https://github.com/bgauryy/FreeLlama/blob/main/packages/rust-core/src/platform/resources/mod.rs) samples local
 available-memory estimates, load per logical CPU, OS memory pressure, active swap-out growth, and
 thermal throttling when reported. OS memory pressure holds every local demand; active swap-out
-growth holds new loads; CPU-load and thermal holds apply to CPU-assigned work and to cold loads
-(decoding weights is CPU work and a new heat source) but not to a bounded request on a runner
-already resident on the GPU, which neither waits for the cores nor cools the package by waiting (`ResourceDemand::is_held_by`; the assessment's
+growth holds new loads; the CPU-load hold applies only to CPU-assigned work (saturated cores slow
+nothing on the GPU, so raw passthrough, which cannot know residency, is not refused for it), and to
+all work on a host whose sampler sees no accelerator; the
+thermal hold applies to CPU-assigned work and to cold loads (a new heat source) but not to a bounded
+request on a runner already resident on the GPU (`ResourceDemand::is_held_by`; the assessment's
 `held_by` lists the holds that applied). Low available RAM (below the larger of 15% or 1 GiB, clearing after two
 healthy samples above the larger of 20% or 2 GiB) depends on the platform (`ResourcePolicy::low_memory`).
 A new load must leave that reserve free, but never more than its own size above the 1 GiB floor.

package/docs/CLI.md

@@ -148,10 +148,13 @@ cache (and is the hard cap in a container), the same shortfall unloads idle runn
 new load with `held_insufficient_capacity` until capacity returns, refusing with 503 at its deadline.
 OS memory pressure holds all work where the OS reports it (macOS, and Linux when the kernel
 exposes `/proc/pressure/memory`; Windows has no host collector yet). Active swapping and low RAM hold new loads only:
-an already-resident runner adds no memory and stays admitted. CPU-load (one-minute load at or above
-1.5 per logical CPU) and thermal-throttling holds apply to CPU-assigned work and to cold loads, which
-decode weights on the host cores and add a new heat source; a bounded request on a runner already
-resident on the GPU neither waits for the cores nor cools the package by waiting, so it proceeds. The receipt's `resource_admission.assessment.held_by`
+an already-resident runner adds no memory and stays admitted. The CPU-load hold (one-minute load at
+or above 1.5 per logical CPU) applies only to CPU-assigned work, which decodes on those cores; GPU
+work, loaded or not, proceeds, so another program's build never blocks a GPU model. On a host where
+the sampler sees no accelerator (no GPU device or GPU memory), every model runs on the CPU, so the
+hold applies to all work there. The
+thermal-throttling hold applies to CPU-assigned work and to cold loads, a new heat source; a bounded
+request on a runner already resident on the GPU proceeds. The receipt's `resource_admission.assessment.held_by`
 lists the holds that applied to the request.
 Both `serve` and `proxy` accept `--resource-telemetry-policy`:
 

package/docs/MODEL_SELECTION.md

@@ -4,8 +4,9 @@ To offload a task, select an installed model with the required capabilities and
 then check its memory fit under the intended concurrency. FreeLlama applies model eligibility
 and admission; the calling agent still verifies the output.
 
-The measurements in this guide come from one Apple M4 Pro machine with 48 GB unified memory and
-are not compiled into routing. Re-run
+The measurements in this guide come from single machines and are not compiled into routing:
+[Recommended starting points](#recommended-starting-points-by-form) from an Apple M2 Pro with 32 GB,
+the sections after it from an Apple M4 Pro with 48 GB unified memory. Re-run
 `npx @octocodeai/freellama doctor`, `models`, `bench-all`, and your quality suite on the target hardware.
 `doctor.machine.memory_bytes` is host RAM; a discrete GPU's usable VRAM must be observed separately.
 
@@ -26,6 +27,46 @@ flowchart TD
     M -->|"Yes"| B["Benchmark locally and add policy evidence"]
 ```
 
+## Recommended starting points by form
+
+Measured on an Apple M2 Pro with 32 GB, Ollama 0.40.8 and FreeLlama 0.6.1 on 2026-10-30, while
+other builds kept the one-minute load near 14 on 12 cores. Every check had a known answer; the
+batteries are small, so treat these as first picks to re-check on your machine, not rankings.
+
+| Form | Model (download) | Measured | Speed (warm) | How an agent calls it |
+|---|---|---|---|---|
+| Text, tools, JSON, reasoning | `gpt-oss:20b` (13.8 GB) | 7/7: exact output, arithmetic, bat-and-ball, code reading, JSON extraction, tool call, 9/9 ticket routing | 1.4 s per routed ticket | `run_task {model:"gpt-oss:20b", prompt, think:"low"}`; add `tools` or `format:"json"` |
+| Embeddings | `nomic-embed-text:v1.5` (274 MB) | Retrieval 4/4 top-1; ticket routing 9/9 from two examples per team | 51 ms per item, batched | `run_task {task:"embedding", input:[...], returnEmbeddings:true}` |
+| Decisions (classify, route, score) | `strands-decider:2b-nvfp4` (1.3 GB) | Ticket routing 9/9, return-policy yes/no 3/3, damage rubric 2/3 | 0.17 s per question | `POST <serve>/v1/systemone {model, state, questions}`: passthrough, no MCP tool yet |
+| OCR | `glm-ocr:latest` (2.2 GB) | 4/4 phrases from a dense report strip; 0/7 on text tasks | 11 s per strip at a 400-token cap | `run_task {task:"vision", model:"glm-ocr", prompt:"Text Recognition:", images:[...], stopOnRepetition:true}` |
+
+`gpt-oss:20b` reasons before answering; the battery ran it with `think:"low"` and a 2,048-token
+output cap, so leave room for the reasoning when you set `num_predict`. `glm-ocr` reads text from images only and keeps generating
+after the visible text ends, so cap its output or set `stopOnRepetition`. The decision model needs
+Apple silicon and answers only through Ollama's decision API; reach it through `serve` so the call
+still passes FreeLlama's memory checks and stream cap (from 0.6.2 a busy CPU no longer refuses it).
+
+### Classify text three ways
+
+The same nine support tickets, routed to billing, technical or returns:
+
+| Approach | Model | Correct | Per item | Use when |
+|---|---|---:|---:|---|
+| Embeddings and per-class centroids | `nomic-embed-text:v1.5` | 9/9 | 51 ms | Many items, stable classes, a few labeled examples per class |
+| Decision model | `strands-decider:2b-nvfp4` | 9/9 | 0.5 s (first call includes the load) | You need probabilities, yes/no policy checks or rubric scores |
+| Instruction model with JSON output | `gpt-oss:20b` | 9/9 | 1.4 s | Classes change per request or need explanation |
+
+A decision API request names its questions; each answer comes back under the same name:
+
+```bash
+curl -s http://127.0.0.1:11435/v1/systemone -H 'content-type: application/json' -d '{
+  "model": "strands-decider:2b-nvfp4",
+  "state": "Why did my credit card get billed two times?",
+  "questions": {"team": {"type": "choice", "instructions": "Which team handles this ticket?",
+    "criteria": {"billing": "Charges and invoices", "technical": "App errors", "returns": "Returns and refunds"}}}
+}'
+```
+
 ## Text, code, and vision
 
 `qwen3.8:27b-mlx` was the strongest general model in the local evaluations. It handled coding,

package/docs/PRODUCTION.md

@@ -42,8 +42,10 @@ release-artifacts release`, then `yarn release:verify:publish`. The publish veri
 Live E2E and hardware qualification remain separate operator checks; verify those receipts before tagging.
 
 Attach `release/SHA256SUMS` and binaries to the release. Publish the eight `@octocodeai/freellama-native-*` packages
-first, followed by the exact-version `@octocodeai/freellama` and `@octocodeai/freellama-mcp-server` packages. Configure
-registry credentials in the release environment; never store them in the repository.
+first, followed by the exact-version `@octocodeai/freellama` and `@octocodeai/freellama-mcp-server` packages. Publish
+the Rust crates from the same commit with `cargo publish --workspace` (it uploads `freellama-core`
+before `freellama-cli`; run it with `--dry-run` first). Configure registry credentials (`npm login`,
+`cargo login`) in the release environment; never store them in the repository.
 
 ## Configure Ollama explicitly
 

package/docs/TESTING.md

@@ -210,7 +210,8 @@ yarn release:verify:publish
 Build every claimed CLI/native target in a clean environment, assemble `SHA256SUMS`, run the full
 deterministic suite, and inspect every platform package dry run before publishing explicitly.
 Publish the eight `@octocodeai/freellama-native-*` packages before `@octocodeai/freellama` and `@octocodeai/freellama-mcp-server`, all
-at the exact same version. A successful local pack dry run proves package contents; it does not
+at the exact same version, then the crates with `cargo publish --workspace` (`--dry-run` first packages
+and compiles both crates from their published sources). A successful local pack dry run proves package contents; it does not
 prove registry publication or another hardware class.
 
 ## Test one layer while iterating

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octocodeai/freellama-mcp-server",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "MCP server exposing FreeLlama core as tools, via native NAPI bindings into packages/rust-core.",
   "repository": {
     "type": "git",
@@ -50,14 +50,14 @@
     "zod": "^3.24.1"
   },
   "optionalDependencies": {
-    "@octocodeai/freellama-native-darwin-arm64": "0.6.1",
-    "@octocodeai/freellama-native-darwin-x64": "0.6.1",
-    "@octocodeai/freellama-native-linux-arm64-gnu": "0.6.1",
-    "@octocodeai/freellama-native-linux-arm64-musl": "0.6.1",
-    "@octocodeai/freellama-native-linux-x64-gnu": "0.6.1",
-    "@octocodeai/freellama-native-linux-x64-musl": "0.6.1",
-    "@octocodeai/freellama-native-win32-arm64-msvc": "0.6.1",
-    "@octocodeai/freellama-native-win32-x64-msvc": "0.6.1"
+    "@octocodeai/freellama-native-darwin-arm64": "0.6.2",
+    "@octocodeai/freellama-native-darwin-x64": "0.6.2",
+    "@octocodeai/freellama-native-linux-arm64-gnu": "0.6.2",
+    "@octocodeai/freellama-native-linux-arm64-musl": "0.6.2",
+    "@octocodeai/freellama-native-linux-x64-gnu": "0.6.2",
+    "@octocodeai/freellama-native-linux-x64-musl": "0.6.2",
+    "@octocodeai/freellama-native-win32-arm64-msvc": "0.6.2",
+    "@octocodeai/freellama-native-win32-x64-msvc": "0.6.2"
   },
   "author": "Guy Bary",
   "license": "Apache-2.0 OR MIT",