@tuned-tensor/cli 0.4.17 → 0.4.18

package/README.md

@@ -55,8 +55,24 @@ tt models base
 tt balance
 ```
 
+Export a model to GGUF and package it for Ollama (so it's pluggable like any
+other local model, e.g. in OpenClaw via Ollama's native `/api/chat`):
+
+```bash
+# Convert + quantize to GGUF, write a Modelfile, and run `ollama create`
+tt models export <model-id> --format gguf --quant q4_k_m --ollama
+
+# Inspect the planned llama.cpp / ollama commands without running them
+tt models export <model-id> --quant q8_0 --ollama --print-command
+```
+
+This wraps llama.cpp's `convert_hf_to_gguf.py` + `llama-quantize` and Ollama's
+`ollama create`. Point `tt` at your llama.cpp checkout with `--llama-cpp <dir>`
+(or `--convert-script` / `--quantize-bin`); with `--ollama` the behaviour spec's
+system prompt is embedded as the Modelfile `SYSTEM` block.
+
 For the full command reference, including dataset-backed runs, long-example
-policies, continued fine-tuning, evaluation caps, local model serving,
+policies, eval token budgets, continued fine-tuning, evaluation caps, local model serving,
 configuration, and billing, see the [CLI docs](https://tunedtensor.com/docs/cli).
 
 ## Development

package/dist/index.js

@@ -801,7 +801,7 @@ Eval Results (${data._evals.length}):`);
       );
     }
   });
-  runs.command("start").description("Start a new run for a behaviour spec").argument("<spec-id>", "Behaviour spec ID (full UUID or 8+ char prefix)").option("--no-augment", "Disable data augmentation").option("--no-llm-judge", "Disable LLM judging").option("--epochs <n>", "Number of training epochs").option("--lr <rate>", "Learning rate").option("--batch-size <n>", "Batch size").option("--dataset <id>", "Dataset ID to use instead of inline spec examples (full UUID or 4+ char prefix)").option("--parent-model <id>", "Fine-tuned model ID to continue training from (full UUID or 4+ char prefix)").option("--train-ratio <ratio>", "Dataset training split ratio (default: 0.8 when any split ratio is set)").option("--validation-ratio <ratio>", "Dataset validation split ratio (default: 0.1 when any split ratio is set)").option("--test-ratio <ratio>", "Dataset test split ratio (default: 0.1 when any split ratio is set)").option("--lora-rank <n>", "LoRA rank").option("--lora-alpha <n>", "LoRA alpha").option("--max-eval-examples <n>", "Max examples for the primary eval pass").option("--max-test-eval-examples <n>", "Max examples for the secondary test eval pass").option("--long-examples <policy>", "Long training row policy: error, truncate, or skip").option("--max-seq-length <tokens>", "Maximum training sequence length in tokens").action(async (specId, cmdOpts) => {
+  runs.command("start").description("Start a new run for a behaviour spec").argument("<spec-id>", "Behaviour spec ID (full UUID or 8+ char prefix)").option("--no-augment", "Disable data augmentation").option("--no-llm-judge", "Disable LLM judging").option("--epochs <n>", "Number of training epochs").option("--lr <rate>", "Learning rate").option("--batch-size <n>", "Batch size").option("--dataset <id>", "Dataset ID to use instead of inline spec examples (full UUID or 4+ char prefix)").option("--parent-model <id>", "Fine-tuned model ID to continue training from (full UUID or 4+ char prefix)").option("--train-ratio <ratio>", "Dataset training split ratio (default: 0.8 when any split ratio is set)").option("--validation-ratio <ratio>", "Dataset validation split ratio (default: 0.1 when any split ratio is set)").option("--test-ratio <ratio>", "Dataset test split ratio (default: 0.1 when any split ratio is set)").option("--lora-rank <n>", "LoRA rank").option("--lora-alpha <n>", "LoRA alpha").option("--max-eval-examples <n>", "Max examples for the primary eval pass").option("--max-test-eval-examples <n>", "Max examples for the secondary test eval pass").option("--long-examples <policy>", "Long training row policy: error, truncate, or skip").option("--max-seq-length <tokens>", "Maximum training sequence length in tokens").option("--max-output-tokens <tokens>", "Desired evaluation output budget in tokens").option("--eval-reserved-output-tokens <tokens>", "Minimum evaluation output tokens reserved per row").action(async (specId, cmdOpts) => {
     const opts = parent.opts();
     const body = {};
     if (cmdOpts.augment === false) body.augment = false;
@@ -831,6 +831,10 @@ Eval Results (${data._evals.length}):`);
     if (cmdOpts.maxTestEvalExamples) hp.max_test_eval_examples = Number(cmdOpts.maxTestEvalExamples);
     if (cmdOpts.longExamples) hp.long_examples = parseLongExamplesPolicy(cmdOpts.longExamples);
     if (cmdOpts.maxSeqLength) hp.max_seq_length = Number(cmdOpts.maxSeqLength);
+    if (cmdOpts.maxOutputTokens) hp.max_output_tokens = Number(cmdOpts.maxOutputTokens);
+    if (cmdOpts.evalReservedOutputTokens) {
+      hp.eval_reserved_output_tokens = Number(cmdOpts.evalReservedOutputTokens);
+    }
     if (cmdOpts.llmJudge === false) body.use_llm_judge = false;
     if (Object.keys(hp).length) body.hyperparameters = hp;
     const fullSpecId = await resolveSpecId(specId, opts);
@@ -2370,6 +2374,174 @@ function printServeCommand(command, args, env, managed) {
   }
   printDetail(fields);
 }
+var CONVERT_NATIVE_OUTTYPES = /* @__PURE__ */ new Set([
+  "f32",
+  "f16",
+  "bf16",
+  "q8_0",
+  "tq1_0",
+  "tq2_0"
+]);
+var QUANTIZE_TYPES = /* @__PURE__ */ new Set([
+  "q4_0",
+  "q4_1",
+  "q5_0",
+  "q5_1",
+  "q2_k",
+  "q2_k_s",
+  "q3_k_s",
+  "q3_k_m",
+  "q3_k_l",
+  "q4_k_s",
+  "q4_k_m",
+  "q5_k_s",
+  "q5_k_m",
+  "q6_k",
+  "iq1_s",
+  "iq1_m",
+  "iq2_xxs",
+  "iq2_xs",
+  "iq2_s",
+  "iq2_m",
+  "iq3_xxs",
+  "iq3_s",
+  "iq3_m",
+  "iq4_nl",
+  "iq4_xs"
+]);
+function planQuant(quant) {
+  const lower = quant.trim().toLowerCase();
+  if (!lower) {
+    throw new Error("--quant requires a value (e.g. q4_k_m, q8_0, f16).");
+  }
+  if (CONVERT_NATIVE_OUTTYPES.has(lower)) {
+    return { quant: lower, requiresQuantize: false, convertOuttype: lower };
+  }
+  if (QUANTIZE_TYPES.has(lower)) {
+    return {
+      quant: lower,
+      requiresQuantize: true,
+      convertOuttype: "f16",
+      quantizeType: lower.toUpperCase()
+    };
+  }
+  const supported = [...CONVERT_NATIVE_OUTTYPES, ...QUANTIZE_TYPES].sort().join(", ");
+  throw new Error(`Unsupported --quant "${quant}". Supported types: ${supported}.`);
+}
+function ollamaSlug(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "");
+  return slug || "model";
+}
+function firstExisting(candidates) {
+  for (const candidate of candidates) {
+    if (candidate && existsSync4(candidate) && statSync3(candidate).isFile()) {
+      return resolve2(candidate);
+    }
+  }
+  return null;
+}
+function llamaCppDir(explicit) {
+  return explicit || process.env.LLAMA_CPP_DIR || process.env.LLAMA_CPP_HOME || void 0;
+}
+function resolveConvertScript(opts, required) {
+  if (opts.convertScript) {
+    const resolved = resolve2(opts.convertScript);
+    if (required && !existsSync4(resolved)) {
+      throw new Error(`Conversion script not found: ${opts.convertScript}`);
+    }
+    return resolved;
+  }
+  const dir = llamaCppDir(opts.llamaCpp);
+  const candidates = dir ? [join2(dir, "convert_hf_to_gguf.py"), join2(dir, "convert-hf-to-gguf.py")] : [];
+  const found = firstExisting(candidates);
+  if (found) return found;
+  if (required) {
+    throw new Error(
+      "Could not find convert_hf_to_gguf.py. Pass --llama-cpp <dir> (a llama.cpp checkout) or --convert-script <path>. Get it from https://github.com/ggml-org/llama.cpp."
+    );
+  }
+  return dir ? join2(dir, "convert_hf_to_gguf.py") : "convert_hf_to_gguf.py";
+}
+function resolveQuantizeBin(opts, required) {
+  if (opts.quantizeBin) {
+    const resolved = resolve2(opts.quantizeBin);
+    if (required && !existsSync4(resolved)) {
+      throw new Error(`llama-quantize binary not found: ${opts.quantizeBin}`);
+    }
+    return resolved;
+  }
+  const dir = llamaCppDir(opts.llamaCpp);
+  if (dir) {
+    const candidates = [
+      join2(dir, "build", "bin", "llama-quantize"),
+      join2(dir, "build", "bin", "quantize"),
+      join2(dir, "llama-quantize"),
+      join2(dir, "quantize")
+    ];
+    const found = firstExisting(candidates);
+    if (found) return found;
+  }
+  if (required && !commandExists("llama-quantize")) {
+    throw new Error(
+      "Could not find the llama-quantize binary. Build llama.cpp and pass --llama-cpp <dir> or --quantize-bin <path>, or add llama-quantize to your PATH."
+    );
+  }
+  return "llama-quantize";
+}
+function buildModelfile(ggufBasename, systemPrompt) {
+  const lines = [`FROM ./${ggufBasename}`];
+  if (systemPrompt.trim()) {
+    const escaped = systemPrompt.trim().replace(/"""/g, '\\"\\"\\"');
+    lines.push("", `SYSTEM """${escaped}"""`);
+  }
+  return lines.join("\n") + "\n";
+}
+function buildExportStep(name, command, args) {
+  return {
+    name,
+    command,
+    args,
+    command_line: [command, ...args].map(quoteCommandPart).join(" ")
+  };
+}
+function printExportPlan(plan) {
+  if (isJsonMode()) return printJson(plan);
+  printDetail([
+    ["Model", `${plan.model.name} (${plan.model.source})`],
+    ["Format", plan.format],
+    ["Quant", plan.quant],
+    ["Output dir", plan.output_dir],
+    ["GGUF", plan.gguf_path]
+  ]);
+  console.log("\nPlanned steps:");
+  for (const step of plan.steps) {
+    console.log(`  ${step.name}: ${step.command_line}`);
+  }
+  if (plan.ollama) {
+    console.log(`
+Modelfile (${plan.ollama.modelfile_path}):`);
+    console.log(plan.ollama.modelfile.replace(/^/gm, "  "));
+  }
+}
+function printOpenClawHints(ollamaName) {
+  console.log("\nUse it with OpenClaw via Ollama's native /api/chat (not /v1):");
+  console.log(
+    [
+      "  {",
+      "    models: { providers: { ollama: {",
+      '      api: "ollama",',
+      '      baseUrl: "http://127.0.0.1:11434",',
+      `      models: [{ id: "${ollamaName}" }]`,
+      "    }}}",
+      "  }"
+    ].join("\n")
+  );
+  console.log("\nThen run it through the infer surface:");
+  console.log(
+    `  openclaw infer model run --local --model ollama/${ollamaName} \\
+    --prompt "<payload>" --json`
+  );
+}
 function registerModelsCommands(parent) {
   const models = parent.command("models").description("Manage fine-tuned models");
   models.command("base").description("List supported base models").action(async () => {
@@ -2444,6 +2616,149 @@ function registerModelsCommands(parent) {
     const size = bytes == null ? "" : ` (${bytes} bytes)`;
     printSuccess(`Model downloaded to ${outputPath}${size}`);
   });
+  models.command("export").description("Export a fine-tuned model to GGUF and (optionally) package it for Ollama").argument("<target>", "Model ID/prefix, model directory, or .tar.gz artifact").option("--format <format>", "Export format", "gguf").option("--quant <type>", "Quantization type (e.g. q4_k_m, q8_0, f16)", "q4_k_m").option("-o, --output <dir>", "Output directory for the GGUF (and Modelfile)").option("--ollama", "Also write an Ollama Modelfile and run `ollama create`").option("--ollama-name <name>", "Ollama model name (default: tt-<slug>)").option("--no-ollama-create", "With --ollama, write the Modelfile but skip `ollama create`").option("--spec <path>", "Behavior spec JSON to embed as the Ollama SYSTEM prompt").option("--no-spec-prompt", "Do not embed a behavior spec system prompt in the Modelfile").option("--llama-cpp <dir>", "Path to a llama.cpp checkout/build (convert script + quantize binary)").option("--convert-script <path>", "Path to convert_hf_to_gguf.py").option("--quantize-bin <path>", "Path to the llama-quantize binary").option("--ollama-bin <path>", "Path to the ollama binary", "ollama").option("--python <path>", "Python executable to run the conversion script", "python3").option("--cache-dir <path>", "Cache directory for downloaded/extracted models").option("--force-download", "Re-download and re-extract model artifacts").option("-f, --force", "Overwrite existing GGUF/Modelfile outputs").option("--keep-intermediate", "Keep the intermediate f16 GGUF after quantization").option("--print-command", "Print the planned commands without executing them").action(async (target, cmdOpts) => {
+    const opts = parent.opts();
+    const format = String(cmdOpts.format).toLowerCase();
+    if (format !== "gguf") {
+      throw new Error(`Unsupported --format "${cmdOpts.format}". Only "gguf" is supported.`);
+    }
+    const quantPlan = planQuant(String(cmdOpts.quant));
+    const printOnly = Boolean(cmdOpts.printCommand);
+    const cacheDir = resolve2(cmdOpts.cacheDir || defaultCacheDir());
+    mkdirSync3(cacheDir, { recursive: true });
+    const serveTarget = await resolveServeTarget(
+      target,
+      opts,
+      cacheDir,
+      Boolean(cmdOpts.forceDownload)
+    );
+    const slug = ollamaSlug(serveTarget.modelName);
+    const outputDir = resolve2(cmdOpts.output || join2(process.cwd(), `${slug}-gguf`));
+    const finalPath = join2(outputDir, `${slug}.${quantPlan.quant}.gguf`);
+    const intermediatePath = quantPlan.requiresQuantize ? join2(outputDir, `${slug}.f16.gguf`) : void 0;
+    const convertScript = resolveConvertScript(cmdOpts, !printOnly);
+    const convertOutfile = intermediatePath ?? finalPath;
+    const steps = [
+      buildExportStep("convert", cmdOpts.python, [
+        convertScript,
+        serveTarget.modelPath,
+        "--outfile",
+        convertOutfile,
+        "--outtype",
+        quantPlan.convertOuttype
+      ])
+    ];
+    let quantizeBin;
+    if (quantPlan.requiresQuantize) {
+      quantizeBin = resolveQuantizeBin(cmdOpts, !printOnly);
+      steps.push(
+        buildExportStep("quantize", quantizeBin, [
+          intermediatePath,
+          finalPath,
+          quantPlan.quantizeType
+        ])
+      );
+    }
+    const wantOllama = Boolean(cmdOpts.ollama);
+    const ollamaName = cmdOpts.ollamaName || `tt-${slug}`;
+    let ollamaInfo;
+    let modelfileContent = "";
+    let modelfilePath = "";
+    if (wantOllama) {
+      let systemPrompt = "";
+      if (cmdOpts.specPrompt !== false) {
+        const specPath = findSpecPath(cmdOpts.spec, serveTarget.modelPath);
+        if (cmdOpts.spec && !specPath) {
+          throw new Error(`Spec file not found: ${cmdOpts.spec}`);
+        }
+        if (specPath) systemPrompt = loadSystemPromptFromSpec(specPath);
+      }
+      modelfilePath = join2(outputDir, "Modelfile");
+      modelfileContent = buildModelfile(basename2(finalPath), systemPrompt);
+      const createModel = cmdOpts.ollamaCreate !== false;
+      if (createModel) {
+        steps.push(
+          buildExportStep("ollama-create", cmdOpts.ollamaBin, [
+            "create",
+            ollamaName,
+            "-f",
+            modelfilePath
+          ])
+        );
+      }
+      ollamaInfo = {
+        name: ollamaName,
+        modelfile_path: modelfilePath,
+        modelfile: modelfileContent,
+        create: createModel
+      };
+    }
+    const plan = {
+      format: "gguf",
+      quant: quantPlan.quant,
+      model: {
+        name: serveTarget.modelName,
+        path: serveTarget.modelPath,
+        source: serveTarget.source,
+        id: serveTarget.modelId
+      },
+      output_dir: outputDir,
+      gguf_path: finalPath,
+      intermediate_path: intermediatePath,
+      steps,
+      ollama: ollamaInfo
+    };
+    if (printOnly) return printExportPlan(plan);
+    if (existsSync4(finalPath) && !cmdOpts.force) {
+      throw new Error(`Output already exists: ${finalPath}. Use --force to overwrite.`);
+    }
+    mkdirSync3(outputDir, { recursive: true });
+    const runStep = (command, args) => execFileSync(command, args, { stdio: "inherit" });
+    if (!isJsonMode()) printSuccess(`Converting ${serveTarget.modelName} \u2192 ${quantPlan.convertOuttype} GGUF`);
+    runStep(cmdOpts.python, [
+      convertScript,
+      serveTarget.modelPath,
+      "--outfile",
+      convertOutfile,
+      "--outtype",
+      quantPlan.convertOuttype
+    ]);
+    if (quantPlan.requiresQuantize && quantizeBin) {
+      if (!isJsonMode()) printSuccess(`Quantizing \u2192 ${quantPlan.quantizeType}`);
+      runStep(quantizeBin, [
+        intermediatePath,
+        finalPath,
+        quantPlan.quantizeType
+      ]);
+      if (!cmdOpts.keepIntermediate && intermediatePath && existsSync4(intermediatePath)) {
+        rmSync(intermediatePath, { force: true });
+      }
+    }
+    if (ollamaInfo) {
+      writeFileSync3(modelfilePath, modelfileContent, "utf8");
+      if (!isJsonMode()) printSuccess(`Wrote Modelfile to ${modelfilePath}`);
+      if (ollamaInfo.create) {
+        if (!isJsonMode()) printSuccess(`Creating Ollama model ${ollamaName}`);
+        runStep(cmdOpts.ollamaBin, ["create", ollamaName, "-f", modelfilePath]);
+      }
+    }
+    if (isJsonMode()) {
+      return printJson({
+        format: "gguf",
+        quant: quantPlan.quant,
+        output_dir: outputDir,
+        gguf_path: finalPath,
+        ollama: ollamaInfo ? { name: ollamaName, modelfile_path: modelfilePath, created: ollamaInfo.create } : void 0
+      });
+    }
+    printSuccess(`GGUF written to ${finalPath}`);
+    if (ollamaInfo?.create) {
+      console.log(`Run it: ollama run ${ollamaName}`);
+      printOpenClawHints(ollamaName);
+    } else if (ollamaInfo) {
+      console.log(`Create the Ollama model: ollama create ${ollamaName} -f ${modelfilePath}`);
+    }
+  });
   models.command("setup-runtime").description("Install an isolated Python runtime for local model serving").option("--python <path>", "Python 3.10-3.12 executable to create the runtime").option("--cache-dir <path>", "Cache directory for the managed runtime").option("-f, --force", "Recreate the runtime if it already exists").option("--print-command", "Print the setup commands without running them").action(async (cmdOpts) => {
     const cacheDir = resolve2(cmdOpts.cacheDir || defaultCacheDir());
     const venvDir = runtimeDir(cacheDir);
@@ -2979,7 +3294,7 @@ function registerPushCommand(parent) {
 
 // src/index.ts
 var program = new Command();
-program.name("tt").description("Tuned Tensor CLI \u2014 fine-tune and evaluate LLMs").version("0.4.17").option("-k, --api-key <key>", "API key (overrides stored key)").option(
+program.name("tt").description("Tuned Tensor CLI \u2014 fine-tune and evaluate LLMs").version("0.4.18").option("-k, --api-key <key>", "API key (overrides stored key)").option(
   "-u, --base-url <url>",
   "API base URL (default: https://tunedtensor.com)"
 ).option("--json", "Output raw JSON").option("--no-color", "Disable colors").hook("preAction", (_thisCommand, actionCommand) => {