neurarch 0.1.1 → 0.1.2

package/README.md

@@ -9,6 +9,7 @@ npx neurarch rightsize jobs.csv          # each past job's request next to what
 npx neurarch Qwen/Qwen3-8B --batch 8     # the training peak for one model
 npx neurarch oom error.txt --model Qwen/Qwen3-8B --batch 8   # why it ran out of memory, and the least invasive fix
 npx neurarch Qwen/Qwen3-8B --inference --batch 4 --seq-len 4096 --gen 512   # weights + KV cache for a generation job
+npx neurarch bert-base-uncased --seq-len 1024 --tokenizer-size 30524         # does the data fit what the config accepts
 ```
 
 The memory number is calibrated against measured runs, and every run is public
@@ -117,6 +118,34 @@ prices. Nothing was trained and nothing was measured, which is why the verb is
 "quoted": what it is good for is deciding whether to start the run, not
 predicting what comes out of it.
 
+## Does the data fit what the config accepts
+
+Some jobs never reach their peak: they are admitted, wait for the card, load the
+weights and then index past a table on the first batch. Each of these is
+readable from the config before anything is reserved.
+
+```
+$ npx neurarch bert-base-uncased --seq-len 1024 --tokenizer-size 30524
+
+  data fit checked: sequence length, tokenizer size
+    block Sequences of 1024 tokens are longer than the 512-row position table
+          fix: Truncate or chunk to 512 tokens, or pick a model whose context covers 1024.
+    block The tokenizer has 30524 ids and the embedding has 30522 rows
+          fix: Call model.resize_token_embeddings(len(tokenizer)) before training, and budget for the new rows.
+```
+
+| flag | checked against | when it blocks |
+|---|---|---|
+| `--seq-len N` | the position scheme | past a learned position table (a rotary context only warns: it runs) |
+| `--tokenizer-size N` | rows in the token embedding | more tokenizer ids than rows |
+| `--classes N` | a `*ForSequenceClassification`-style head in the config, or a graph's final Linear | more labels than the head emits (fewer only warns) |
+| `--image-size N` | the patch position table | any other size |
+| `--channels N` | the first layer's input channels | any other count |
+
+A field you do not state is not checked, and the output lists what could not be
+compared and why, so a clean result never stands in for one nobody ran. A block
+sets the exit code to 1. The same check is `data` on `POST /api/v1/check`.
+
 ## Which modules a LoRA can sit on
 
 ```

package/bin/neurarch.mjs

@@ -10,6 +10,7 @@
  *   npx neurarch Qwen/Qwen3-8B --batch 8 --seq-len 8192                # training peak at that length, no price
  *   npx neurarch Qwen/Qwen3-8B --inference --batch 4 --seq-len 4096 --gen 512   # weights + KV cache, which cards hold it
  *   npx neurarch Qwen/Qwen3-8B --lora-targets         # which modules a LoRA can sit on
+ *   npx neurarch bert-base-uncased --seq-len 1024 --tokenizer-size 30524   # will this data crash it after it gets the GPU
  *   npx neurarch rightsize jobs.csv                   # requested vs needed GPU over past jobs
  *
  * The number this exists to print is the second one: parameters derived from
@@ -19,7 +20,7 @@
  *
  * Zero dependencies; the engine is bundled. Set HF_TOKEN for gated repos.
  */
-import { inspectHFModel, keyFor, AGREE_TOLERANCE, priceHFModel, parseHumanSize, PREFLIGHT_GPUS, specFromFlags, renderLoraText, rightsize, renderMarkdown, headline, applyPrices, DEFAULT_CARDS, oomReport, renderOomText, readAttention, attentionPhrase, readSeqLen, DEFAULT_SEQ_LEN, inferHFModel, readInferencePrecision, INFERENCE_PRECISIONS, DEFAULT_GEN_TOKENS, DEFAULT_INFERENCE_BATCH, CHANGE_HEADROOM, storedTwiceSentence } from '../engine.bundle.mjs';
+import { inspectHFModel, keyFor, AGREE_TOLERANCE, priceHFModel, parseHumanSize, PREFLIGHT_GPUS, specFromFlags, renderLoraText, rightsize, renderMarkdown, headline, applyPrices, DEFAULT_CARDS, oomReport, renderOomText, readAttention, attentionPhrase, readSeqLen, DEFAULT_SEQ_LEN, inferHFModel, readInferencePrecision, INFERENCE_PRECISIONS, DEFAULT_GEN_TOKENS, DEFAULT_INFERENCE_BATCH, CHANGE_HEADROOM, storedTwiceSentence, dataFitHFModel } from '../engine.bundle.mjs';
 /** The channel tag on every link this program prints. `docs/DISTRIBUTION.md`
  *  has asked for one since the first release: without it a visit from a tool
  *  and a visit from a search result are the same row, and "which channel brings
@@ -197,7 +198,7 @@ for gated repos); nothing is uploaded.
 
 // `--data 3M` and `--gpu a100` take a value, so their value must not fall
 // through to `positional` and be read as a second model id.
-const VALUED = new Set(['--data', '--gpu', '--lora', '--quant', '--fit', '--serve', '--batch', '--attention', '--seq-len', '--gen', '--precision']);
+const VALUED = new Set(['--data', '--gpu', '--lora', '--quant', '--fit', '--serve', '--batch', '--attention', '--seq-len', '--gen', '--precision', '--tokenizer-size', '--classes', '--image-size', '--channels']);
 const flags = new Set();
 const opts = {};
 const positional = [];
@@ -234,6 +235,11 @@ if (flags.has('-h') || flags.has('--help') || positional.length === 0) {
                                      the change record: what may move on this base, and whether the gate approves it
   npx neurarch <model-id> --lora-targets   every Linear a LoRA can target, and PEFT target_modules
                                      for the attention and all-linear presets with r=8 / r=16 totals
+  npx neurarch <model-id> --seq-len 1024 --tokenizer-size 30524 --classes 5 [--image-size 384 --channels 1]
+                                     does YOUR data fit what the config accepts: sequence vs the
+                                     position table, tokenizer vs the embedding, labels vs the head,
+                                     image size and channels vs the first layer. These crash on the
+                                     first batch, after the reservation; this says so before it.
 
 --data takes the size of YOUR training set (3M, 500k, 2B). Without it there is
 no price, because a cost with no workload behind it is a cost for somebody
@@ -303,7 +309,21 @@ if (opts.gen != null) {
 const inferOpts = { batch: batchSize, promptTokens: seqLen, genTokens, precision };
 /** The training-peak block runs on any of these; `--inference` replaces it. */
 const trainingSizing = !inference && (opts.data != null || batchSize != null || seqLen != null || opts.attention != null);
-const sizingAsked = inference || trainingSizing || opts.lora != null;
+// The data the caller describes. `--seq-len` is the same number the peak is
+// sized at, so it is checked against the position scheme whenever it is given.
+const DATA_FLAGS = [['seq-len', 'seqLen'], ['tokenizer-size', 'tokenizerSize'], ['classes', 'numClasses'], ['image-size', 'imageSize'], ['channels', 'channels']];
+const dataSpec = {};
+for (const [flag, key] of DATA_FLAGS) {
+  if (opts[flag] == null) continue;
+  const n = Number(opts[flag]);
+  if (!Number.isInteger(n) || n < 1) {
+    process.stderr.write(`\n  ${red('cannot read')} --${flag} ${opts[flag]}. Use a positive integer.\n`);
+    process.exit(2);
+  }
+  dataSpec[key] = n;
+}
+const dataAsked = Object.keys(dataSpec).length > 0;
+const sizingAsked = inference || trainingSizing || opts.lora != null || dataAsked;
 
 const modelId = positional[0];
 const result = await inspectHFModel(modelId);
@@ -332,6 +352,7 @@ if (flags.has('--json')) {
     const spec = specFromFlags({ lora: opts.lora, quant: opts.quant, fit: opts.fit, serve: opts.serve });
     if (spec) out.change = priceHFModel(f, { samples: 50_000, source: 'assumed' }, runFrom(gpuFromFlag(opts.gpu)), spec, attention, seqLen).plan.change;
     if (flags.has('--lora-targets')) out.lora = priceHFModel(f, { samples: 50_000, source: 'assumed' }).plan.lora;
+    if (dataAsked) out.dataFit = dataFitHFModel(f, dataSpec);
     return out;
   };
   const payload = result.ok
@@ -365,7 +386,7 @@ if (flags.has('--json')) {
         }
       : { ok: false, modelId, reason: result.reason };
   process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
-  process.exit(payload.ok ? 0 : 1);
+  process.exit(payload.ok && !(payload.dataFit?.findings ?? []).some((f) => f.severity === 'block') ? 0 : 1);
 }
 
 if (!result.ok && !sizingOnly) {
@@ -442,6 +463,24 @@ if (sizingOnly) {
   }
 }
 
+// ── Does the data fit what the config accepts ───────────────────────────────
+//
+// Before memory, because a job that indexes past a table on its first batch
+// does not get far enough for its peak to matter.
+if (dataAsked) {
+  const fit = dataFitHFModel(facts, dataSpec);
+  const blocks = fit.findings.filter((f) => f.severity === 'block');
+  process.stdout.write(`\n  ${bold('data fit')} ${dim(`checked: ${fit.checked.join(', ') || 'nothing'}`)}\n`);
+  if (!fit.findings.length && fit.checked.length) process.stdout.write(`    ${green('fits')}  ${dim('every stated field is within what the config accepts')}\n`);
+  for (const f of fit.findings) {
+    process.stdout.write(`    ${f.severity === 'block' ? red('block') : yellow('warn ')} ${f.title}\n`);
+    process.stdout.write(`          ${dim(f.detail)}\n`);
+    process.stdout.write(`          ${dim(`fix: ${f.fix}`)}\n`);
+  }
+  for (const s of fit.skipped) process.stdout.write(`    ${dim(`not checked: ${s.check} (${s.reason})`)}\n`);
+  for (const b of blocks) blockers.push({ title: b.title });
+}
+
 // ── What an inference job needs ────────────────────────────────────────────
 //
 // Weights at the stated precision plus the KV cache at the last generated

package/engine.bundle.mjs

@@ -43892,6 +43892,165 @@ function storedTwiceSentence(t) {
   return `The checkpoint stores the tied embedding twice: +${n2} (\`${t.head}\` and \`${t.embedding}\`, ${t.shape.join(" x ")}). The model has one such matrix and the count above has it once; the delta compares that count plus the second copy against the file.`;
 }
 
+// src/utils/configDataFit.ts
+var CLASSIFIER_ARCH = /For(Sequence|Token|Image|Audio|MultipleChoice)Classification$/;
+var posInt2 = (v) => {
+  const n2 = typeof v === "string" && v.trim() !== "" ? Number(v) : v;
+  return typeof n2 === "number" && Number.isInteger(n2) && n2 > 0 ? n2 : null;
+};
+function inputContractOf(model, config) {
+  const comps = model.components ?? [];
+  const first = (t) => comps.find((c) => c.type === t);
+  const source = {};
+  const emb = first("embedding");
+  const vocabSize = posInt2(emb?.params?.vocabSize);
+  if (vocabSize != null) source.vocabSize = "the token embedding";
+  const patch = first("patchEmbed");
+  const learned = first("learnedPositionalEmbedding");
+  let maxPositions = null;
+  let positionKind = null;
+  if (!patch) {
+    if (learned && posInt2(learned.params?.maxLen) != null) {
+      maxPositions = posInt2(learned.params?.maxLen);
+      positionKind = "learned";
+      source.maxPositions = "the learned position table";
+    } else if (posInt2(emb?.params?.maxSeqLen) != null) {
+      maxPositions = posInt2(emb?.params?.maxSeqLen);
+      positionKind = comps.some((c) => c.type === "rope") ? "rotary" : "declared";
+      source.maxPositions = positionKind === "rotary" ? "max_position_embeddings (rotary)" : "the declared maximum length";
+    }
+  }
+  let imageSize = null;
+  let channels = null;
+  if (patch) {
+    imageSize = posInt2(patch.params?.imgSize);
+    channels = posInt2(patch.params?.inChans);
+    if (imageSize != null) source.imageSize = "the patch embedding";
+    if (channels != null) source.channels = "the patch embedding";
+  } else if (!emb) {
+    const shape = first("input")?.params?.shape ?? null;
+    if (Array.isArray(shape) && shape.length === 3 && shape.every((x) => posInt2(x) != null)) {
+      channels = shape[0];
+      source.channels = "the input shape";
+    }
+  }
+  let numLabels = null;
+  const archs = Array.isArray(config?.architectures) ? config.architectures.map(String) : [];
+  if (archs.some((a) => CLASSIFIER_ARCH.test(a))) {
+    const id2label = config?.id2label;
+    numLabels = id2label && typeof id2label === "object" ? Object.keys(id2label).length || null : posInt2(config?.num_labels);
+    if (numLabels != null) source.numLabels = `the ${archs.find((a) => CLASSIFIER_ARCH.test(a))} head`;
+  } else if (!emb) {
+    const tail = [...comps].reverse().find((c) => !["output", "softmax", "dropout", "flatten", "activation", "relu"].includes(c.type));
+    if (tail?.type === "linear" && posInt2(tail.params?.outFeatures) != null) {
+      numLabels = posInt2(tail.params?.outFeatures);
+      source.numLabels = "the final Linear";
+    }
+  }
+  return { vocabSize, maxPositions, positionKind, numLabels, imageSize, channels, source };
+}
+function checkDataFit(contract, data) {
+  const checked = [];
+  const skipped = [];
+  const findings = [];
+  const c = contract;
+  if (data.seqLen != null) {
+    if (c.maxPositions == null) {
+      skipped.push({ check: "sequence length", reason: c.imageSize != null ? "a vision model: its position table is checked against the image size" : "the model declares no maximum length" });
+    } else {
+      checked.push("sequence length");
+      if (data.seqLen > c.maxPositions) {
+        if (c.positionKind === "learned") {
+          findings.push({
+            rule: "seq-over-positions",
+            severity: "block",
+            title: `Sequences of ${data.seqLen} tokens are longer than the ${c.maxPositions}-row position table`,
+            detail: `Position ids past ${c.maxPositions - 1} index outside a learned table, so the first batch that long raises an IndexError (a device-side assert on GPU) after the reservation is taken.`,
+            fix: `Truncate or chunk to ${c.maxPositions} tokens, or pick a model whose context covers ${data.seqLen}.`
+          });
+        } else {
+          findings.push({
+            rule: "seq-over-context",
+            severity: "warn",
+            title: `Sequences of ${data.seqLen} tokens are past the model's ${c.maxPositions}-token context`,
+            detail: c.positionKind === "rotary" ? "Rotary positions are computed, so the job runs; quality past the trained length is not something the config can vouch for, and attention memory grows with the length." : "The config declares this as the longest input; past it, behaviour depends on the implementation.",
+            fix: c.positionKind === "rotary" ? "Set rope_scaling for the longer context, or truncate to the trained length." : `Truncate to ${c.maxPositions} tokens.`
+          });
+        }
+      }
+    }
+  }
+  if (data.tokenizerSize != null) {
+    if (c.vocabSize == null) skipped.push({ check: "tokenizer size", reason: "the model has no token embedding" });
+    else {
+      checked.push("tokenizer size");
+      if (data.tokenizerSize > c.vocabSize) {
+        findings.push({
+          rule: "tokenizer-over-vocab",
+          severity: "block",
+          title: `The tokenizer has ${data.tokenizerSize} ids and the embedding has ${c.vocabSize} rows`,
+          detail: `Any of the ${data.tokenizerSize - c.vocabSize} ids past ${c.vocabSize - 1} indexes outside the embedding. The usual cause is special tokens added to the tokenizer without resizing the model.`,
+          fix: "Call model.resize_token_embeddings(len(tokenizer)) before training, and budget for the new rows."
+        });
+      }
+    }
+  }
+  if (data.numClasses != null) {
+    if (c.numLabels == null) skipped.push({ check: "label count", reason: "no classification head is visible in the config or the graph" });
+    else {
+      checked.push("label count");
+      if (data.numClasses > c.numLabels) {
+        findings.push({
+          rule: "labels-over-head",
+          severity: "block",
+          title: `The data has ${data.numClasses} labels and ${c.source.numLabels ?? "the head"} emits ${c.numLabels}`,
+          detail: `A label id of ${c.numLabels} or more is out of range for the loss, which on GPU is a device-side assert with no line number.`,
+          fix: `Load with num_labels=${data.numClasses} (and ignore_mismatched_sizes=True for a pretrained head).`
+        });
+      } else if (data.numClasses < c.numLabels) {
+        findings.push({
+          rule: "labels-under-head",
+          severity: "warn",
+          title: `The data has ${data.numClasses} labels and the head emits ${c.numLabels}`,
+          detail: "It runs; the extra outputs are never a target, which is usually a head left over from a different task.",
+          fix: `Load with num_labels=${data.numClasses} if the head is meant for this data.`
+        });
+      }
+    }
+  }
+  if (data.imageSize != null) {
+    if (c.imageSize == null) skipped.push({ check: "image size", reason: "the model has no fixed image size (no patch position table)" });
+    else {
+      checked.push("image size");
+      if (data.imageSize !== c.imageSize) {
+        findings.push({
+          rule: "image-size-mismatch",
+          severity: "block",
+          title: `Images are ${data.imageSize}px and the position table was built for ${c.imageSize}px`,
+          detail: "The patch count no longer matches the learned position table, so the forward pass raises on the first batch.",
+          fix: `Resize to ${c.imageSize}px, or pass interpolate_pos_encoding=True where the model supports it.`
+        });
+      }
+    }
+  }
+  if (data.channels != null) {
+    if (c.channels == null) skipped.push({ check: "channels", reason: "the model states no input channels" });
+    else {
+      checked.push("channels");
+      if (data.channels !== c.channels) {
+        findings.push({
+          rule: "channels-mismatch",
+          severity: "block",
+          title: `Images have ${data.channels} channel${data.channels === 1 ? "" : "s"} and the first layer expects ${c.channels}`,
+          detail: "The first convolution or patch projection has a fixed input-channel count; a mismatch raises on the first batch.",
+          fix: data.channels === 1 && c.channels === 3 ? "Repeat the grey channel to three in the transform." : `Convert the images to ${c.channels} channels.`
+        });
+      }
+    }
+  }
+  return { checked, skipped, findings, contract };
+}
+
 // src/utils/trainCost.ts
 init_paramEstimator();
 var GPU_CATALOG = {
@@ -44614,6 +44773,9 @@ function graphOfFacts(facts) {
     updatedAt: ""
   };
 }
+function dataFitHFModel(facts, data) {
+  return checkDataFit(inputContractOf(graphOfFacts(facts), facts.snap.config), data);
+}
 function inferHFModel(facts, opts) {
   const model = graphOfFacts(facts);
   const prompt = opts.promptTokens ?? withSeqLen(model, null).seqLen ?? DEFAULT_SEQ_LEN;
@@ -44700,6 +44862,7 @@ export {
   PRICE_SOURCE,
   applyPrices,
   attentionPhrase,
+  dataFitHFModel,
   graphOfFacts,
   headline,
   inferHFModel,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neurarch",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Know what a GPU job needs before it takes a reservation: training peak memory, the smallest card that holds it and what a run costs, read from a Hugging Face config or a traced graph. `neurarch rightsize jobs.csv` puts each past job's request next to what it needed.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",