@tuned-tensor/cli 0.16.0 → 0.17.0

package/README.md

@@ -21,6 +21,11 @@ Inference choice is independent of where training uses a GPU. Your AWS GPU
 needs AWS credentials and SSH access; TT account operations under `tt cloud`
 require a TT access token.
 
+New to cloud GPU training? Follow [your first AWS run](docs/local-runtime/aws-gpu.md)
+for project creation, AWS quota and SSH setup, a preview, training, result
+verification, and shutdown. You still run `tt pipeline run` on your laptop;
+`tt cloud` is for TT account records, not user-owned GPU execution.
+
 ## Unified commands
 
 Local workflows remain the default: `tt pipeline run`, `tt runs list`,
@@ -86,6 +91,14 @@ npm run build
 npm link
 ```
 
+## Behavior spec workflow
+
+`tunedtensor.json` is the source of truth for behavior and training settings.
+Use `/spec`, `/spec diff`, `/spec validate`, and `/spec history` in the shell to
+review it without a model call. Ask the agent for changes, inspect its proposed
+diff, then `/approve` to save a validated edit with revision history. Pipeline
+runs use the saved spec. See [the spec workflow](docs/spec-workflow.md).
+
 ## Conversational terminal
 
 The interactive agent harness and conversation state run on your laptop.
@@ -157,11 +170,11 @@ Ask TT anything. Known commands run directly.
 ```
 
 Ordinary sentences go through the locally orchestrated model session. The
-model has no shell or general filesystem tool. It can prepare one new folder
-directly beneath the shell's current working directory with a validated
+model has no shell or general filesystem tool. It can read and propose reviewed
+edits to an existing spec, or prepare one new folder directly beneath the shell's current working directory with a validated
 `tunedtensor.json`, or prepare a local pipeline dry-run sealed to the reviewed
-workspace and spec contents. Neither action starts until `/approve`. The tools refuse path
-traversal, symlinked workspace roots, existing spec targets, unsupported spec
+workspace and spec contents. Writes and pipeline previews wait for `/approve`. The tools refuse path
+traversal, symlinked workspace roots, overwriting a new-project target, unsupported spec
 fields, cloud pipeline targets, and spec changes after review. Known CLI
 commands such as `runs list`, `doctor`, and `models list` still execute directly.
 Prefix a command with `:` when you want to make that intent explicit.
@@ -275,6 +288,10 @@ expected output for every example. Treat those metrics as an end-to-end
 execution and overfit check—not held-out capability or multi-GPU evidence when
 no validation corpus is configured.
 
+Without `--file`, pipeline plan/run/validate derive the recipe from the behavior
+spec. Adjacent recipe files are no longer loaded implicitly. Explicit foundation
+recipes must agree with the spec’s training settings.
+
 ```bash
 tt pipeline init --file pipeline.json
 tt pipeline init --engine foundation --file foundation.pipeline.json
@@ -370,7 +387,7 @@ tt init \
   --model Qwen/Qwen3.5-2B
 ```
 
-Edit the generated `tunedtensor.json`, replacing both placeholder examples.
+Edit the generated `tunedtensor.json`, replacing the placeholder system prompt and both placeholder examples.
 For a local GPU, `tt hardware` reports this machine's training and serving
 capacity. For an AWS GPU, save the following as `local-runner.json` beside the
 spec, replacing the instance, region, profile and SSH settings with your own:

package/dist/{chunk-6RLNBTM6.js → chunk-KRKISPHG.js}

@@ -1438,6 +1438,56 @@ async function loadLocalRunInput(path, options = {}) {
     options
   );
 }
+function specHash(source) {
+  return createHash2("sha256").update(source).digest("hex");
+}
+function validateBehaviorSpec(input) {
+  const errors = [];
+  const warnings = [];
+  if (input.kind === "request") {
+    return { valid: false, errors: ["Use a behavior spec, not a run request."], warnings };
+  }
+  const { spec } = input;
+  const placeholders = input.kind === "foundation-spec" ? foundationPlaceholderIssues(input.spec) : generatedPlaceholderIssues(input.request);
+  if (placeholders.length) {
+    errors.push(`Edit the generated behavior spec before training: ${placeholders.join("; ")}.`);
+  }
+  if (input.kind === "foundation-spec") {
+    if (input.spec.foundation.nproc_per_node !== 1) {
+      errors.push("Foundation nproc_per_node must be 1 for this runtime.");
+    }
+    const nonNumericOutput = spec.examples.some(
+      (example) => !/-?\d+(?:\.\d+)?/.test(example.output.replaceAll(",", ""))
+    );
+    if (input.spec.foundation.rl_steps > 0 && nonNumericOutput) {
+      errors.push("Foundation RL requires numeric expected outputs in every example.");
+    }
+  }
+  for (const key of ["name", "system_prompt"]) {
+    if (!spec[key].trim()) errors.push(`${key} must not be blank.`);
+  }
+  if (spec.examples.length < 2 && !(input.kind === "spec" && input.spec.dataset_prebuilt)) {
+    errors.push("Add at least two examples for training and evaluation.");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, example] of spec.examples.entries()) {
+    if (!example.input.trim() || !example.output.trim()) {
+      errors.push(`examples[${index}] input and output must not be blank.`);
+    }
+    const key = example.input.trim();
+    if (seen.has(key)) {
+      errors.push(`examples[${index}] repeats an input; use distinct examples to avoid conflicting labels or train/eval overlap.`);
+    }
+    seen.add(key);
+  }
+  if (!spec.guidelines.length) {
+    warnings.push("Add guidelines to make expected behavior explicit.");
+  }
+  if (spec.examples.length < 10) {
+    warnings.push("This is a small example set; passing validation does not establish model quality.");
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
 
 // src/local-runtime/dataset.ts
 import { readFile as readFile3 } from "fs/promises";
@@ -6077,6 +6127,8 @@ export {
   runRequestFromLocalSpec,
   parseLocalRunInput,
   loadLocalRunInput,
+  specHash,
+  validateBehaviorSpec,
   normalizeChatJsonlForRelocation,
   buildSystemMessage,
   exampleToChatRow,
@@ -6126,4 +6178,4 @@ export {
   formatAgentHostBlock,
   assessHardware
 };
-//# sourceMappingURL=chunk-6RLNBTM6.js.map
+//# sourceMappingURL=chunk-KRKISPHG.js.map