@tuned-tensor/cli 0.13.1-beta.1 → 0.13.1-beta.2

package/README.md

@@ -84,7 +84,7 @@ such as `runs list` and `doctor` work immediately. Chat waits until you choose
 a provider and model from inside the shell:
 
 ```text
-tt v0.13.1-beta.1
+tt v0.13.1-beta.2
 agent not configured · workflow model base
 ctrl+c stop/clear · ctrl+d exit · /help commands · tab complete
 
@@ -113,7 +113,7 @@ After a model is selected, the banner shows it and ordinary sentences go to
 the agent:
 
 ```text
-tt v0.13.1-beta.1
+tt v0.13.1-beta.2
 agent anthropic/claude-sonnet-4-5 · workflow model base
 ctrl+c stop/clear · ctrl+d exit · /help commands · tab complete
 
@@ -174,28 +174,47 @@ explicitly.
 
 ## Composable pipelines (v1)
 
-A pipeline is an ordered JSON recipe. Version 1 supports `train`, `evaluate`,
-and `compare` steps. This CLI executes local plans only. The v1 evaluator is
-`evaluate.with.evaluator: "behavior"`. `evaluate.with.model` is `"base"` or
-`{ "from": "step.model" }`; `compare.with.before` and
-`after` are `{ "from": "step.report" }`. References must point to an earlier
-step and to an output the producer actually exposes. The document contract
-itself is defined by the published `@tuned-tensor/pipeline-contract` package;
-the CLI adds only execution planning (step selection) on top of it.
+A pipeline is an ordered JSON recipe. This CLI executes local plans only. The
+portable document contract lives in `@tuned-tensor/pipeline-contract`. The CLI
+adds execution planning (step selection) on top of it.
+
+Two local engines share that document version:
+
+- **Adapter** (default): LoRA SFT on a certified Hugging Face checkpoint.
+  `tt run` and `tt pipeline` both work. Uses `train` / `evaluate` / `compare`
+  with `evaluate.with.evaluator: "behavior"`.
+- **Foundation**: from-scratch tokenizer + GPT. `tt pipeline` only. Uses
+  `tokenize` / `pretrain` / `finetune` / optional `rl` plus `bpb`, `chat`, and
+  `inference` evaluators. Requires a foundation `tunedtensor.json`
+  (`engine: "foundation"`, at least two examples, no `base_model`).
+
+The foundation engine is a small, readable local baseline inspired by Andrej
+Karpathy's [nanochat](https://github.com/karpathy/nanochat), not a port of its
+compute-optimal training stack. The first version deliberately builds a bounded
+pretraining corpus from the spec prompt and examples, reports chat accuracy on
+those same contract examples, and supports one training process. Foundation
+plans reject `compare` before creating run artifacts; comparison remains an
+adapter-engine capability. Optional RL samples one seeded on-policy completion
+per step with a sparse last-number exact reward and therefore requires a numeric
+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.
 
 ```bash
 tt pipeline init --file pipeline.json
+tt pipeline init --engine foundation --file foundation.pipeline.json
 tt pipeline validate --file pipeline.json
 tt --json pipeline plan --file pipeline.json
 tt --json pipeline run --dry-run --file pipeline.json --only baseline
 tt --json pipeline run --file pipeline.json \
   --spec tunedtensor.json --config local-runner.json
+tt init --engine foundation --name "Tiny GPT"
+tt --json pipeline run --spec tunedtensor.json --dry-run
 ```
 
 `--only` and `--skip` preserve dependency safety: a selected step cannot refer
 to an omitted predecessor. Cloud-targeted steps fail closed unless you pass
-`--dry-run`. The TT agent may describe, validate, and prepare a plan, but has
-no direct pipeline-execute tool.
+`--dry-run`. Foundation documents are local-only. The TT agent may describe,
+validate, and prepare a plan, but has no direct pipeline-execute tool.
 
 ## Quick start
 

package/dist/{chunk-YJYCGSHJ.js → chunk-2P2RL23O.js}

@@ -851,6 +851,28 @@ var specSnapshotSchema = z.object({
   constraints: z.array(z.string()).default([]),
   base_model: z.string().transform((value) => canonicalizeTrainingModel(value))
 }).strict();
+var foundationHyperparametersSchema = z.object({
+  vocab_size: z.number().int().min(64).max(65536).default(256),
+  max_chars: z.number().int().min(1e3).max(2e9).default(2e4),
+  depth: z.number().int().min(1).max(64).default(2),
+  pretrain_steps: z.number().int().min(1).max(1e7).default(2),
+  finetune_steps: z.number().int().min(1).max(1e7).default(2),
+  rl_steps: z.number().int().min(0).max(1e7).default(0),
+  batch_size: z.number().int().min(1).max(1024).default(2),
+  sequence_length: z.number().int().min(16).max(8192).default(64),
+  nproc_per_node: z.number().int().min(1).max(16).default(1)
+}).strict();
+var localFoundationSpecFileSchema = z.object({
+  engine: z.literal("foundation"),
+  id: z.string().uuid().optional(),
+  name: z.string().min(1),
+  description: z.string().default(""),
+  system_prompt: z.string().default(""),
+  guidelines: z.array(z.string()).default([]),
+  examples: z.array(behaviorSpecExampleSchema).min(2),
+  constraints: z.array(z.string()).default([]),
+  foundation: foundationHyperparametersSchema
+}).strict();
 var datasetPrebuiltSchema = z.object({
   training: z.string().min(1),
   validation: z.string().min(1).optional(),
@@ -895,11 +917,16 @@ var fineTuneRunRequestSchema = z.object({
     });
   }
 });
-var localBehaviorSpecFileSchema = specSnapshotSchema.extend({
+var localAdapterSpecFileSchema = specSnapshotSchema.extend({
+  engine: z.literal("adapter").optional(),
   id: z.string().uuid().optional(),
   hyperparameters: fineTuneHyperparametersSchema.optional(),
   dataset_prebuilt: datasetPrebuiltSchema.optional()
 }).strict();
+var localBehaviorSpecFileSchema = z.union([
+  localFoundationSpecFileSchema,
+  localAdapterSpecFileSchema
+]);
 var evalExampleResultSchema = z.object({
   prompt: z.string(),
   expected: z.string(),
@@ -1080,6 +1107,9 @@ var localRunnerConfigSchema = z.object({
     baselineCache: true
   })
 }).strict();
+function isFoundationSpecFile(spec) {
+  return spec.engine === "foundation";
+}
 
 // src/local-runtime/local-project.ts
 import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
@@ -1121,7 +1151,48 @@ async function initLocalSpecFile(args) {
   if (!args.force && await exists(args.outputPath)) {
     throw new Error(`Refusing to overwrite existing file: ${args.outputPath}`);
   }
-  const spec = localBehaviorSpecFileSchema.parse({
+  if (args.engine === "foundation") {
+    const spec2 = localFoundationSpecFileSchema.parse({
+      engine: "foundation",
+      id: randomUUID2(),
+      name: args.name,
+      description: "From-scratch tokenizer, pretrain, chat SFT, and eval.",
+      system_prompt: "You are a helpful assistant.",
+      guidelines: [
+        "Answer the user request directly."
+      ],
+      constraints: [],
+      examples: [
+        {
+          input: "Replace this with representative chat input.",
+          output: "Replace this with the expected assistant reply."
+        },
+        {
+          input: "Replace this with a different chat input.",
+          output: "Replace this with the expected assistant reply."
+        }
+      ],
+      foundation: {
+        depth: 2,
+        pretrain_steps: 2,
+        finetune_steps: 2,
+        rl_steps: 0,
+        vocab_size: 256,
+        max_chars: 2e4,
+        sequence_length: 64,
+        batch_size: 2,
+        nproc_per_node: 1
+      }
+    });
+    await mkdir2(dirname2(args.outputPath), { recursive: true });
+    await writeFile2(args.outputPath, `${JSON.stringify(spec2, null, 2)}
+`, "utf8");
+    return spec2;
+  }
+  if (!args.baseModel) {
+    throw new Error("Adapter specs require --model.");
+  }
+  const spec = localAdapterSpecFileSchema.parse({
     id: randomUUID2(),
     name: args.name,
     description: "",
@@ -1172,27 +1243,45 @@ async function initLocalRunnerConfigFile(args) {
 `, "utf8");
   return config;
 }
-function generatedPlaceholderIssues(request) {
+function placeholderIssues(systemPrompt, examples) {
   const issues = [];
-  if (/describe the behavior this local model should learn/i.test(request.spec_snapshot.system_prompt)) {
+  if (/describe the behavior this local model should learn/i.test(systemPrompt)) {
     issues.push("system_prompt still contains the generated placeholder");
   }
-  request.spec_snapshot.examples.forEach((example, index) => {
+  examples.forEach((example, index) => {
     if (/replace this with/i.test(example.input) || /replace this with/i.test(example.output)) {
       issues.push(`examples[${index}] still contains generated placeholder text`);
     }
   });
   return issues;
 }
+function generatedPlaceholderIssues(request) {
+  return placeholderIssues(request.spec_snapshot.system_prompt, request.spec_snapshot.examples);
+}
 function assertLocalRunInputReady(request) {
   const issues = generatedPlaceholderIssues(request);
   if (issues.length > 0) {
     throw new Error(`Edit the generated behavior spec before training: ${issues.join("; ")}.`);
   }
 }
+function foundationPlaceholderIssues(spec) {
+  return placeholderIssues(spec.system_prompt, spec.examples);
+}
+function assertFoundationSpecReady(spec) {
+  const issues = foundationPlaceholderIssues(spec);
+  if (issues.length > 0) {
+    throw new Error(`Edit the generated foundation spec before training: ${issues.join("; ")}.`);
+  }
+}
 function runRequestFromLocalSpec(spec, options = {}) {
+  if (isFoundationSpecFile(spec)) {
+    throw new Error(
+      "Foundation specs cannot be converted into a LoRA run request. Use `tt pipeline run --spec`."
+    );
+  }
   const {
     id,
+    engine: _engine,
     hyperparameters,
     dataset_prebuilt: datasetPrebuilt,
     ...specSnapshot
@@ -1229,6 +1318,9 @@ async function loadLocalRunInput(path, options = {}) {
     return { kind: "request", path, request: request.data };
   }
   const spec = localBehaviorSpecFileSchema.parse(raw);
+  if (isFoundationSpecFile(spec)) {
+    return { kind: "foundation-spec", path, spec };
+  }
   return {
     kind: "spec",
     path,
@@ -1914,6 +2006,20 @@ var BUNDLED_PYTHON_ENVIRONMENT = join3(
   "uv",
   bundledRuntimeHash
 );
+var foundationProject = join3(packageRoot, "training/foundation");
+var foundationRuntimeHash = (() => {
+  const hash = createHash3("sha256");
+  for (const name of ["pyproject.toml", "uv.lock"]) {
+    hash.update(readFileSync(join3(foundationProject, name)));
+  }
+  return hash.digest("hex").slice(0, 20);
+})();
+var FOUNDATION_PYTHON_ENVIRONMENT = join3(
+  resolve6(process.env.XDG_CACHE_HOME ?? join3(homedir3(), ".cache")),
+  "tuned-tensor-local",
+  "uv-foundation",
+  foundationRuntimeHash
+);
 function buildBundledPythonCommand(entrypoint, args = []) {
   const target = entrypoint === "-c" ? entrypoint : join3(bundledProject, "src", entrypoint);
   const commandArgs = [
@@ -1938,6 +2044,29 @@ function withBundledPythonEnvironment(env) {
     UV_PROJECT_ENVIRONMENT: BUNDLED_PYTHON_ENVIRONMENT
   };
 }
+function buildFoundationPythonCommand(entrypoint, args = []) {
+  const commandArgs = [
+    "run",
+    "--frozen",
+    "--quiet",
+    "--project",
+    foundationProject,
+    "python",
+    join3(foundationProject, "src", entrypoint),
+    ...args
+  ];
+  return {
+    command: "uv",
+    commandArgs,
+    displayCommand: ["uv", ...commandArgs]
+  };
+}
+function withFoundationPythonEnvironment(env) {
+  return {
+    ...env,
+    UV_PROJECT_ENVIRONMENT: FOUNDATION_PYTHON_ENVIRONMENT
+  };
+}
 var ProcessCancelledError = class extends Error {
   constructor(message = "Process cancelled.") {
     super(message);
@@ -4755,9 +4884,12 @@ export {
   baseModelRevisionSchema,
   behaviorSpecExampleSchema,
   specSnapshotSchema,
+  foundationHyperparametersSchema,
+  localFoundationSpecFileSchema,
   datasetPrebuiltSchema,
   fineTuneHyperparametersSchema,
   fineTuneRunRequestSchema,
+  localAdapterSpecFileSchema,
   localBehaviorSpecFileSchema,
   evalExampleResultSchema,
   jsonFieldMetricsSchema,
@@ -4767,12 +4899,15 @@ export {
   trainingReportSchema,
   runReportSchema,
   localRunnerConfigSchema,
+  isFoundationSpecFile,
   DEFAULT_LOCAL_SPEC_PATH,
   resolveLocalRunInputPaths,
   initLocalSpecFile,
   initLocalRunnerConfigFile,
   generatedPlaceholderIssues,
   assertLocalRunInputReady,
+  foundationPlaceholderIssues,
+  assertFoundationSpecReady,
   runRequestFromLocalSpec,
   loadLocalRunInput,
   normalizeChatJsonlForRelocation,
@@ -4788,6 +4923,9 @@ export {
   localRuntimePackageRoot,
   buildBundledPythonCommand,
   withBundledPythonEnvironment,
+  buildFoundationPythonCommand,
+  withFoundationPythonEnvironment,
+  runLoggedProcess,
   isTerminalRunState,
   defaultLocalHome,
   localStorePaths,
@@ -4811,4 +4949,4 @@ export {
   runLocalPipeline,
   runLocalFineTune
 };
-//# sourceMappingURL=chunk-YJYCGSHJ.js.map
+//# sourceMappingURL=chunk-2P2RL23O.js.map