offgrid-ai 0.6.3 → 0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "offgrid-ai",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Privacy-first CLI for running local LLMs — discover, configure, run, benchmark",
   "author": "Eeshan Srivastava (https://eeshans.com)",
   "type": "module",

package/src/autodetect.mjs

@@ -73,13 +73,14 @@ export function computeFlags(capabilities, modelPath, mmprojPath, draftModelPath
     flags.chatTemplateKwargs = { enable_thinking: true };
   }
 
-  // Build argv
-  const argv = [
-    "--model", modelPath,
-  ];
-
-  if (mmprojPath) argv.push("--mmproj", mmprojPath);
-  if (draftModelPath) argv.push("--spec-draft-model", draftModelPath);
+  // Build argv. Prefer llama.cpp's Hugging Face resolver when a repo ref is
+  // known, so companion files such as Gemma 4 MTP drafters are discovered by
+  // llama.cpp instead of offgrid-ai maintaining repo-specific file rules.
+  const hfRef = capabilities.hfRepo ? `${capabilities.hfRepo}${capabilities.hfVariant ? `:${capabilities.hfVariant}` : ""}` : null;
+  const argv = hfRef ? ["-hf", hfRef] : ["--model", modelPath];
+
+  if (mmprojPath && !hfRef) argv.push("--mmproj", mmprojPath);
+  if (draftModelPath && !hfRef) argv.push("--spec-draft-model", draftModelPath);
 
   argv.push(
     "--host", String(flags.host),

package/src/benchmark.mjs

@@ -7,7 +7,6 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { ensureDirs, loadConfig, saveConfig } from "./config.mjs";
 import { backendFor } from "./backends.mjs";
-import { serverMatchesProfile, serverReady } from "./process.mjs";
 import { pc, createPrompt, renderRows, renderSection } from "./ui.mjs";
 
 const execFileAsync = promisify(execFile);
@@ -151,35 +150,15 @@ function intendedRunnerForProfile(profile) {
   return harnessDisplayName(id);
 }
 
-async function profileServerStatus(profile) {
-  if (!profile) return null;
-  const ready = await serverReady(profile.baseUrl).catch(() => false);
-  if (!ready) return { running: false };
-  const match = await serverMatchesProfile(profile).catch(() => ({ matches: true, reason: "server responded" }));
-  return { running: match.matches, reason: match.reason };
-}
+function printBenchmarkNextSteps({ repoPath, runDirectory, profile, modelId, runnerLabel }) {
+  const runCommand = profile ? `offgrid-ai run ${profile.id}` : null;
+  const runnerCommand = runCommand ?? `Open ${runnerLabel} for ${modelId}`;
 
-function printBenchmarkNextSteps({ repoPath, profile, modelId, runnerLabel, serverStatus }) {
   console.log("");
   console.log(pc.bold("Next steps"));
-
-  let step = 1;
-  if (profile) {
-    const command = `offgrid-ai run ${profile.id}`;
-    if (serverStatus?.running) {
-      const reason = serverStatus.reason ? pc.dim(` (${serverStatus.reason})`) : "";
-      console.log(`  ${step++}. Model server is already running at ${pc.cyan(profile.baseUrl)}${reason}`);
-      console.log(`     ${pc.dim(`If you still need to open ${runnerLabel}, run: ${command}`)}`);
-    } else {
-      console.log(`  ${step++}. If the model server is not already running, run: ${pc.cyan(command)}`);
-    }
-  } else {
-    console.log(`  ${step++}. Open ${runnerLabel} for ${pc.bold(modelId)}`);
-  }
-
-  console.log(`  ${step++}. ${pc.cyan(`cd ${repoPath}`)}`);
-  console.log(`  ${step++}. ${pc.cyan("npm run dev")}`);
-  console.log(`  ${step}. In the gallery, find this run, copy the prompt, and paste it into ${runnerLabel}`);
+  console.log(`  1. Open the gallery. If it is not running: ${pc.cyan(`cd ${repoPath} && npm run dev`)}`);
+  console.log(`  2. ${pc.cyan(`cd ${runDirectory}`)}`);
+  console.log(`  3. ${pc.cyan(runnerCommand)}, then copy this run's prompt from the gallery and paste it into ${runnerLabel}`);
 }
 
 async function prepareBenchmarkRun({ repoPath, benchmark, kind, modelId, modelSource, backendLabel, profile }) {
@@ -188,7 +167,6 @@ async function prepareBenchmarkRun({ repoPath, benchmark, kind, modelId, modelSo
   const runId = createRunId(now);
   const modelSlug = slugModelId(modelId);
   const runnerLabel = intendedRunnerForProfile(profile);
-  const serverStatus = await profileServerStatus(profile);
   const runsDir = join(repoPath, "runs");
   const benchmarkDirectory = join(runsDir, benchmark.id);
   const modelDirectory = join(benchmarkDirectory, modelSlug);
@@ -237,7 +215,7 @@ async function prepareBenchmarkRun({ repoPath, benchmark, kind, modelId, modelSo
     ["Source", backendLabel || modelSource],
   ])));
 
-  printBenchmarkNextSteps({ repoPath, profile, modelId, runnerLabel, serverStatus });
+  printBenchmarkNextSteps({ repoPath, runDirectory, profile, modelId, runnerLabel });
 
   return runDirectory;
 }

package/src/cli.mjs

@@ -299,6 +299,7 @@ function optionSourceTag(sourceId, label) {
     ollama: pc.green,
     omlx: pc.magenta,
     gguf: pc.cyan,
+    hf: pc.cyan,
   };
   return optionTag(label, colors[sourceId] ?? pc.dim, OPTION_SOURCE_WIDTH);
 }
@@ -331,13 +332,13 @@ function modelSelectOption(item, { runningProfilesNow, drafters }) {
   if (item.type === "new") {
     const { model, drafter } = item;
     const caps = detectCapabilities(model.path, model.mmprojPath);
-    const mtpAvailable = caps.mtp || Boolean(drafter);
+    const mtpAvailable = caps.mtp || Boolean(drafter) || Boolean(model.hfRepo && /gemma-?4/i.test(`${model.hfRepo} ${model.label}`));
     let mtpLabel;
     if (mtpAvailable) mtpLabel = pc.green("MTP available");
     else if (caps.architecture === "gemma4") mtpLabel = pc.yellow("MTP needs drafter");
     const label = optionLabel({
       status: optionStatusTag("setup"),
-      source: optionSourceTag("gguf", "GGUF file"),
+      source: optionSourceTag(model.hfRepo ? "hf" : "gguf", model.hfRepo ? "Hugging Face" : "GGUF file"),
       name: model.label,
       details: [pc.dim(formatBytes(model.sizeBytes)), mtpLabel],
     });
@@ -434,7 +435,7 @@ function printModelCards(items, { runningProfilesNow, drafters }) {
     for (const item of newModels) {
       const { model, drafter } = item;
       const caps = detectCapabilities(model.path, model.mmprojPath);
-      const mtpAvailable = caps.mtp || Boolean(drafter);
+      const mtpAvailable = caps.mtp || Boolean(drafter) || Boolean(model.hfRepo && /gemma-?4/i.test(`${model.hfRepo} ${model.label}`));
       const mtpLabel = mtpAvailable
         ? pc.green("MTP ✓")
         : (caps.architecture === "gemma4")
@@ -542,6 +543,7 @@ async function printProfileDetails(profile) {
   ];
   if (!isManaged) {
     detailRows.push(
+      ...(profile.hfRepo ? [["Hugging Face", `${profile.hfRepo}${profile.hfVariant ? `:${profile.hfVariant}` : ""}`]] : []),
       ["Local file", fileMissing ? pc.red(`${profile.modelPath} (not found)`) : profile.modelPath ?? "unknown"],
       ["Vision file", profile.mmprojPath ? (existsSync(profile.mmprojPath) ? profile.mmprojPath : pc.red(`${profile.mmprojPath} (not found)`)) : "none"],
       ["Model size", profile.modelPath && existsSync(profile.modelPath) ? formatBytes(statSync(profile.modelPath).size) : "unknown"],
@@ -564,7 +566,7 @@ async function printProfileDetails(profile) {
 
 function printGgufModelDetails(model, drafter) {
   const caps = detectCapabilities(model.path, model.mmprojPath);
-  const mtpAvailable = caps.mtp || Boolean(drafter);
+  const mtpAvailable = caps.mtp || Boolean(drafter) || Boolean(model.hfRepo && /gemma-?4/i.test(`${model.hfRepo} ${model.label}`));
   const mtpLabel = mtpAvailable
     ? pc.green("MTP ✓")
     : (caps.architecture === "gemma4")
@@ -582,6 +584,7 @@ function printGgufModelDetails(model, drafter) {
   ];
   console.log("\n" + renderSection("Downloaded model", renderRows(overviewRows)));
   const detailRows = [
+    ...(model.hfRepo ? [["Hugging Face", `${model.hfRepo}${model.hfVariant ? `:${model.hfVariant}` : ""}`]] : []),
     ["Local file", model.path],
     ["Vision file", model.mmprojPath ?? "none"],
     ["Detected", capabilitySummary(caps)],

package/src/profile-setup.mjs

@@ -34,14 +34,16 @@ export async function configureLocalProfile(prompt, profile) {
   let configured = profile;
   // Re-detect capabilities from the model file and check for drafters
   // so that re-setup can pick up MTP availability, vision changes, etc.
-  const freshCaps = detectCapabilities(profile.modelPath, profile.mmprojPath);
+  const hfSource = profile.hfRepo ? { hfRepo: profile.hfRepo, hfVariant: profile.hfVariant } : {};
+  const freshCaps = { ...detectCapabilities(profile.modelPath, profile.mmprojPath), ...hfSource };
   let drafterPath = profile.drafterPath ?? null;
-  if (!drafterPath) {
+  if (!drafterPath && !profile.hfRepo) {
     const { drafters } = await scanGgufModels();
     const drafter = matchDrafter(profile.modelPath, drafters);
     if (drafter) drafterPath = drafter.path;
   }
-  const hasMtp = freshCaps.mtp || Boolean(drafterPath);
+  const hfGemma4Mtp = Boolean(profile.hfRepo && /gemma-?4/i.test(`${profile.hfRepo} ${profile.label}`));
+  const hasMtp = freshCaps.mtp || Boolean(drafterPath) || hfGemma4Mtp;
   const caps = { ...freshCaps, mtp: hasMtp };
   // If MTP is newly available, switch backend and add drafter path
   if (hasMtp && configured.backend !== "llama-cpp-mtp") {
@@ -71,7 +73,7 @@ export async function configureLocalProfile(prompt, profile) {
     console.log(renderSection("MTP detected", renderRows([
       ["Backend", "llama.cpp MTP"],
       ["Port", String(LLAMA_CPP_MTP_PORT)],
-      ["Flags", `--spec-type draft-mtp --spec-draft-n-max 4${configured.drafterPath ? " --spec-draft-model <drafter>" : ""}`],
+      ["Flags", `--spec-type draft-mtp --spec-draft-n-max 4${configured.drafterPath && !configured.hfRepo ? " --spec-draft-model <drafter>" : ""}`],
     ])));
     if (drafterInfo) console.log(pc.dim(drafterInfo));
     const useMtp = await prompt.yesNo("Use MTP speculative decoding?", true);
@@ -142,7 +144,7 @@ function applyMtpDefaults(profile) {
   const edits = {
     values: { "--spec-type": "draft-mtp", "--spec-draft-n-max": 4 },
   };
-  if (profile.drafterPath) {
+  if (profile.drafterPath && !profile.hfRepo) {
     edits.values["--spec-draft-model"] = profile.drafterPath;
   }
   return applyProfileFlags({ ...profile, backend: "llama-cpp-mtp", providerId: "llama-cpp-mtp" }, flags, edits);

package/src/profiles.mjs

@@ -134,11 +134,15 @@ export function normalizeProfile(profile) {
 export async function createProfileFromModel(model, backendId, drafterPath) {
   const { detectCapabilities } = await import("./autodetect.mjs");
   const caps = detectCapabilities(model.path, model.mmprojPath);
-  // If a drafter is provided, this model supports MTP regardless of filename
-  const hasMtp = caps.mtp || Boolean(drafterPath);
+  // If a drafter is provided, this model supports MTP regardless of filename.
+  // For Hugging Face Gemma 4 GGUF repos, prefer llama.cpp's -hf companion-file
+  // discovery so root mtp-*.gguf drafters do not need offgrid-ai file matching.
+  const hfGemma4Mtp = Boolean(model.hfRepo && /gemma-?4/i.test(`${model.hfRepo} ${model.label}`));
+  const hasMtp = caps.mtp || Boolean(drafterPath) || hfGemma4Mtp;
   const backend = backendId ?? (hasMtp ? "llama-cpp-mtp" : "llama-cpp");
+  const hfSource = model.hfRepo ? { hfRepo: model.hfRepo, hfVariant: model.hfVariant } : {};
   const { flags, argv } = computeFlags(
-    { ...caps, mtp: hasMtp },
+    { ...caps, mtp: hasMtp, ...hfSource },
     model.path,
     model.mmprojPath,
     drafterPath ?? null,
@@ -150,10 +154,12 @@ export async function createProfileFromModel(model, backendId, drafterPath) {
     backend,
     providerId: backend,
     modelAlias: model.aliasSuggestion,
+    source: model.hfRepo ? "huggingface" : model.source,
     modelPath: model.path,
-    mmprojPath: model.mmprojPath,
+    mmprojPath: model.hfRepo ? null : model.mmprojPath,
+    ...hfSource,
     drafterPath: drafterPath ?? null,
-    capabilities: summarizeCapabilities({ ...caps, mtp: hasMtp }),
+    capabilities: summarizeCapabilities({ ...caps, mtp: hasMtp, ...hfSource }),
     preset: null, // no presets — auto-detected
     flags,
     commandArgv: argv,
@@ -171,6 +177,8 @@ function summarizeCapabilities(caps) {
     quant: caps.quant,
     metaCtx: caps.metaCtx,
     mmprojProjectorType: caps.mmprojProjectorType,
+    hfRepo: caps.hfRepo,
+    hfVariant: caps.hfVariant,
     ctxSize: caps.ctxSize,
   };
 }

package/src/scan.mjs

@@ -1,6 +1,6 @@
 import { statSync } from "node:fs";
 import { readdir } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, sep } from "node:path";
 import { getModelScanDirs } from "./config.mjs";
 import { readGgufMetadata } from "./gguf.mjs";
 
@@ -67,6 +67,7 @@ async function scanOneDir(root) {
         source: "local-gguf",
       });
     } else {
+      const hf = inferHfRef(path, name);
       models.push({
         path,
         mmprojPath,
@@ -75,7 +76,8 @@ async function scanOneDir(root) {
         quant: quantFromName(name),
         sizeBytes,
         backend: "llama-cpp",
-        source: "local-gguf",
+        source: hf ? "huggingface" : "local-gguf",
+        ...(hf ? { hfRepo: hf.repo, hfVariant: hf.variant } : {}),
       });
     }
   }
@@ -158,6 +160,24 @@ function quantFromName(name) {
   return name.match(/(Q\d_K_[A-Z]+|Q\d_[01]|UD-[A-Z0-9_]+)/)?.[1];
 }
 
+export function inferHfRef(path, name = basename(path).replace(/\.gguf$/i, "")) {
+  const parts = path.split(sep);
+  const hubIndex = parts.lastIndexOf("hub");
+  const hfCacheRepo = hubIndex >= 0 ? parts.find((part, index) => index > hubIndex && part.startsWith("models--")) : null;
+  if (hfCacheRepo) {
+    return { repo: hfCacheRepo.replace(/^models--/u, "").replace(/--/gu, "/"), variant: quantFromName(name) ?? name };
+  }
+
+  const lmStudioIndex = parts.lastIndexOf(".lmstudio");
+  if (lmStudioIndex >= 0 && parts[lmStudioIndex + 1] === "models") {
+    const org = parts[lmStudioIndex + 2];
+    const repo = parts[lmStudioIndex + 3];
+    if (org && repo) return { repo: `${org}/${repo}`, variant: quantFromName(name) ?? name };
+  }
+
+  return null;
+}
+
 function safeReadGgufMetadata(path) {
   try {
     return readGgufMetadata(path);