@myvillage/cli 2.3.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {

package/src/agent-runtime/builtin-tools-registry.js

@@ -14,15 +14,18 @@
 export const DATASET_APPEND_DESCRIPTION =
   'Append labeled training example(s) to a LOCAL dataset on this machine. ' +
   'The dataset must already exist (created via the Studio Lab or ' +
-  '`myvillage dataset create`). `features` is text, a numeric vector ' +
-  '(tabular), or a local image file path (image datasets — the file is ' +
+  '`myvillage dataset create`). `features` is text (words datasets); for a ' +
+  'table dataset, its values in column order or an object keyed by column ' +
+  'name (numbers, category text, true/false, short notes); or a local image ' +
+  'file path (image datasets — the file is ' +
   'copied into the dataset). For classification provide `label`; for ' +
   'regression provide a numeric `target`. Data stays local; provenance ' +
   'is recorded automatically.';
 
 export const MODEL_PREDICT_DESCRIPTION =
   'Run a prediction with a LOCAL trained model on this machine. `input` is ' +
-  'text, a numeric vector (tabular), or a local image file path (image ' +
+  'text (words models), the values of one table row as a list in column ' +
+  'order or an object keyed by column name (table models), or a local image file path (image ' +
   'models). Returns the predicted class with per-class confidence scores ' +
   '(classification) or a numeric value (regression). The model must already ' +
   'exist (trained in the Studio Lab or via `myvillage model train`).';

package/src/agent-runtime/builtin-tools.js

@@ -65,10 +65,15 @@ export function getBuiltinTools(agentName, config) {
           .array(
             z.object({
               features: z
-                .union([z.string(), z.array(z.number())])
+                .union([
+                  z.string(),
+                  z.array(z.union([z.number(), z.string(), z.boolean()])),
+                  z.record(z.union([z.number(), z.string(), z.boolean()])),
+                ])
                 .describe(
-                  'Text content; a numeric vector for tabular data; or, for image ' +
-                    'datasets, an absolute path to a local image file (.jpg/.png).',
+                  'Text content for a words dataset; for a table dataset, its values in column ' +
+                    'order or an object keyed by column name (numbers, category text, true/false, ' +
+                    'short notes); or, for image datasets, an absolute path to a local image file (.jpg/.png).',
                 ),
               label: z.string().optional().describe('Class label (classification datasets)'),
               target: z.number().optional().describe('Numeric target (regression datasets)'),
@@ -122,10 +127,14 @@ export function getBuiltinTools(agentName, config) {
       inputSchema: z.object({
         modelId: z.string().describe('Slug of the local trained model'),
         input: z
-          .union([z.string(), z.array(z.number())])
+          .union([
+            z.string(),
+            z.array(z.union([z.number(), z.string(), z.boolean()])),
+            z.record(z.union([z.number(), z.string(), z.boolean()])),
+          ])
           .describe(
-            'Text; a numeric vector for tabular models; or, for image models, ' +
-              'an absolute path to a local image file (.jpg/.png).',
+            'Text for a words model; for a table model, its values in column order or an ' +
+              'object keyed by column name; or, for image models, an absolute path to a local image file (.jpg/.png).',
           ),
       }),
       execute: async ({ modelId, input }) => {

package/src/commands/dataset.js

@@ -103,7 +103,7 @@ export async function datasetAppendCommand(options) {
       rows = readRowsFromFile(options.file);
     } else if (options.text !== undefined || options.features !== undefined) {
       const row = { split: options.split || 'train' };
-      row.features = options.features !== undefined ? parseFeatures(options.features) : options.text;
+      row.features = options.features !== undefined ? parseFeatures(options.features, manifest.modality, manifest) : options.text;
       if (options.label !== undefined) row.label = options.label;
       if (options.target !== undefined) row.target = Number(options.target);
       rows = [row];
@@ -111,15 +111,29 @@ export async function datasetAppendCommand(options) {
       throw new Error('Provide --image <path> (image datasets), --file <jsonl>, or --text/--features (with --label or --target).');
     }
 
+    if (options.replace && !options.file) {
+      throw new Error('--replace only works with --file (it swaps in the whole working set).');
+    }
+    const featureNames = options.featureNames !== undefined ? parseNameList(options.featureNames) : undefined;
+    const featureTypes = options.featureTypes !== undefined ? parseNameList(options.featureTypes) : undefined;
+
     const spinner = options.json ? null : villageSpinner('Appending rows...').start();
-    const result = appendRows(slug, rows, { source: 'cli' });
-    if (spinner) spinner.stop();
+    let result;
+    try {
+      result = appendRows(slug, rows, { source: options.source || 'cli' }, {
+        replace: Boolean(options.replace),
+        featureNames,
+        featureTypes,
+      });
+    } finally {
+      if (spinner) spinner.stop();
+    }
 
     if (options.json) {
       console.log(JSON.stringify(result, null, 2));
       return;
     }
-    success(`Appended ${result.appended} row(s) to ${slug}`);
+    success(`${result.replaced ? 'Replaced the working set with' : 'Appended'} ${result.appended} row(s) ${result.replaced ? 'in' : 'to'} ${slug}`);
     info(`  total: ${result.stats.rowCount} (train ${result.stats.bySplit.train} / val ${result.stats.bySplit.val})`);
   } catch (e) {
     error(e.message);
@@ -133,8 +147,13 @@ export async function datasetShowCommand(slug, options) {
   try {
     const manifest = readManifest(slug);
     if (!manifest) throw new Error(`Dataset "${slug}" not found.`);
-    const limit = options.limit ? parseInt(options.limit, 10) : 5;
-    const sample = readRows(slug, { limit });
+    // --limit 0 returns every row (used by Studio's export).
+    const limit = options.limit !== undefined ? parseInt(options.limit, 10) : 5;
+    const version = options.frozen !== undefined ? parseInt(options.frozen, 10) : undefined;
+    if (version !== undefined && !manifest.versions.some((v) => v.version === version)) {
+      throw new Error(`Dataset "${slug}" has no frozen v${options.frozen}.`);
+    }
+    const sample = readRows(slug, { limit, version });
     if (options.json) {
       console.log(JSON.stringify({ manifest, sample }, null, 2));
       return;
@@ -206,7 +225,10 @@ export async function datasetRowUpdateCommand(options) {
     if (!slug) throw new Error('--dataset <slug> is required.');
     if (!options.id) throw new Error('--id <rowId> is required.');
     const updates = {};
-    if (options.features !== undefined) updates.features = parseFeatures(options.features);
+    if (options.features !== undefined) {
+      const m = readManifest(slug);
+      updates.features = parseFeatures(options.features, m?.modality, m);
+    }
     else if (options.text !== undefined) updates.features = options.text;
     if (options.label !== undefined) updates.label = options.label;
     if (options.target !== undefined) updates.target = Number(options.target);
@@ -244,9 +266,31 @@ function readRowsFromFile(path) {
   return rows;
 }
 
-function parseFeatures(raw) {
-  // tabular features may be passed as a comma/JSON numeric vector
+/** A JSON array of names, or a comma-separated list. */
+function parseNameList(raw) {
+  const trimmed = String(raw).trim();
+  if (trimmed.startsWith('[')) {
+    const parsed = JSON.parse(trimmed);
+    if (!Array.isArray(parsed)) throw new Error('--feature-names must be a list.');
+    return parsed.map(String);
+  }
+  return trimmed.split(',').map((s) => s.trim());
+}
+
+function parseFeatures(raw, modality, manifest) {
+  // Tabular features are a numeric vector, passed as JSON ("[12, 45]") or a
+  // comma list ("12, 45" or a single "12"). Anything that isn't a number stays
+  // NaN so row validation rejects it rather than storing it as text.
+  if (modality !== 'tabular') return raw;
   const trimmed = raw.trim();
+  // Typed tables take JSON: a list in column order or an object by column name.
+  if (manifest?.featureTypes?.some((t) => t !== 'number')) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      throw new Error('This table has typed columns; pass --features as JSON, e.g. \'{"Role": "student", "Hours": 3}\'.');
+    }
+  }
   if (trimmed.startsWith('[')) {
     try {
       return JSON.parse(trimmed);
@@ -254,10 +298,7 @@ function parseFeatures(raw) {
       /* fall through */
     }
   }
-  if (/^-?\d.*,/.test(trimmed)) {
-    return trimmed.split(',').map((n) => Number(n.trim()));
-  }
-  return raw;
+  return trimmed.split(',').map((n) => (n.trim() === '' ? NaN : Number(n.trim())));
 }
 
 function truncate(s, n) {

package/src/index.js

@@ -1006,17 +1006,22 @@ export function run() {
     .option('--file <path>', 'JSONL file of rows ({features,label|target,split})')
     .option('--image <path>', 'Image file to add (image datasets); copied into the dataset')
     .option('--text <text>', 'Single-row text features')
-    .option('--features <value>', 'Single-row features (string, or numeric vector for tabular)')
+    .option('--features <value>', 'Single-row features (string; numbers for a table, or JSON for a typed table)')
     .option('--label <label>', 'Class label (classification)')
     .option('--target <number>', 'Numeric target (regression)')
     .option('--split <split>', 'train | val', 'train')
+    .option('--replace', 'With --file: replace the working set instead of adding to it')
+    .option('--source <source>', 'Provenance source stamped on each row (e.g. import:csv)')
+    .option('--feature-names <list>', 'Tabular column names (JSON array or comma-separated)')
+    .option('--feature-types <list>', 'Tabular column types, same order: number | category | boolean | text')
     .option('--json', 'Output raw JSON')
     .action(datasetAppendCommand);
 
   datasetCmd
     .command('show <slug>')
     .description('Show a dataset manifest and a sample of rows')
-    .option('--limit <n>', 'Number of sample rows to show', '5')
+    .option('--limit <n>', 'Number of sample rows to show (0 = all)', '5')
+    .option('--frozen <n>', 'Read frozen version n instead of the working set')
     .option('--json', 'Output raw JSON')
     .action(datasetShowCommand);
 
@@ -1041,7 +1046,7 @@ export function run() {
     .requiredOption('--dataset <slug>', 'Target dataset slug')
     .requiredOption('--id <rowId>', 'Row id to update')
     .option('--text <text>', 'New text features')
-    .option('--features <value>', 'New features (string, or numeric vector for tabular)')
+    .option('--features <value>', 'New features (string; numbers for a table, or JSON for a typed table)')
     .option('--label <label>', 'New class label (classification)')
     .option('--target <number>', 'New numeric target (regression)')
     .option('--split <split>', 'train | val')
@@ -1077,7 +1082,7 @@ export function run() {
   modelCmd
     .command('predict <slug>')
     .description('Run a prediction with a trained model')
-    .option('--input <value>', 'Input: text, or a comma-separated numeric vector for tabular')
+    .option('--input <value>', 'Input: text; comma-separated numbers for a table; or JSON for a typed table')
     .option('--image <path>', 'Image file to classify (image models)')
     .option('--json', 'Output raw JSON')
     .action(modelPredictCommand);

package/src/utils/dataset-workspace.js

@@ -30,6 +30,7 @@ import {
 import { join, extname, basename } from 'path';
 import { randomUUID } from 'crypto';
 import { getConfigDir } from './config.js';
+import { columnTypesOf, normalizeTypedFeatures, validateColumnTypes } from './table-columns.js';
 
 const DATASETS_DIR_NAME = 'datasets';
 export const DATASET_SCHEMA_VERSION = '1.0.0';
@@ -202,23 +203,58 @@ export function createDataset({ name, modality, taskType = 'classification', lab
  * Append rows to a dataset's working set, stamping provenance, validating
  * against the dataset's modality/task, and updating manifest stats.
  *
+ * Every row is validated before anything is written, so a bad row leaves the
+ * dataset untouched. With `replace`, the working set is overwritten instead of
+ * extended (frozen versions are never touched) and the label list is rebuilt
+ * from the new rows. `featureNames` names the columns of a table (tabular)
+ * dataset and `featureTypes` optionally types them (number / category /
+ * boolean / text, see table-columns.js); without types every column is a
+ * number, as before. Rows may then give their values as a list in column
+ * order or as an object keyed by column name. Once set, every row must fit
+ * those columns.
+ *
  * @param {string} slug
  * @param {Array<{features:any, label?:string, target?:number, split?:string}>} rows
  * @param {object} provenance  partial provenance ({ source, agentId, villagerId, villageId })
- * @returns {{datasetId:string, appended:number, stats:object}}
+ * @param {{replace?:boolean, featureNames?:string[], featureTypes?:string[]}} opts
+ * @returns {{datasetId:string, appended:number, replaced:boolean, stats:object}}
  */
-export function appendRows(slug, rows, provenance = {}) {
+export function appendRows(slug, rows, provenance = {}, { replace = false, featureNames, featureTypes } = {}) {
   const manifest = readManifest(slug);
   if (!manifest) throw new Error(`Dataset "${slug}" not found.`);
   if (!Array.isArray(rows) || rows.length === 0) {
     throw new Error('No rows to append.');
   }
-  const source = provenance.source || 'cli';
-  const lines = [];
-  let appended = 0;
+  if (featureTypes !== undefined && featureNames === undefined) {
+    throw new Error('Column types need column names too.');
+  }
+  if (featureNames !== undefined) {
+    applyFeatureNames(manifest, featureNames, replace);
+    applyFeatureTypes(manifest, featureTypes, replace);
+  } else if (replace) {
+    delete manifest.featureNames;
+    delete manifest.featureTypes;
+  }
 
-  for (const raw of rows) {
-    const row = normalizeRow(raw, manifest);
+  const existing = replace ? [] : readRows(slug);
+  // Without named columns, hold tabular rows to the width already on disk
+  // (the trainer needs every vector the same length).
+  let width = manifest.featureNames?.length;
+  if (width == null && manifest.modality === 'tabular') {
+    const first = existing.find((r) => Array.isArray(r.features));
+    if (first) width = first.features.length;
+  }
+
+  const source = provenance.source || 'cli';
+  const newRows = [];
+  rows.forEach((raw, i) => {
+    let row;
+    try {
+      row = normalizeRow(raw, manifest, width);
+    } catch (e) {
+      throw new Error(rows.length > 1 ? `Row ${i + 1}: ${e.message}` : e.message);
+    }
+    if (width == null && Array.isArray(row.features)) width = row.features.length;
     row.id = randomUUID();
     row.provenance = {
       source,
@@ -227,24 +263,65 @@ export function appendRows(slug, rows, provenance = {}) {
       ...(provenance.villageId ? { villageId: provenance.villageId } : {}),
       ts: nowISO(),
     };
-    lines.push(JSON.stringify(row));
+    newRows.push(row);
+  });
 
-    // stats
-    manifest.stats.rowCount += 1;
-    manifest.stats.bySplit[row.split] += 1;
-    if (row.label != null) {
-      manifest.stats.byLabel[row.label] = (manifest.stats.byLabel[row.label] || 0) + 1;
-      if (!manifest.labels.includes(row.label)) manifest.labels.push(row.label);
-    }
-    appended += 1;
+  if (replace) manifest.labels = [];
+  for (const row of newRows) {
+    if (row.label != null && !manifest.labels.includes(row.label)) manifest.labels.push(row.label);
+  }
+  if (replace) {
+    writeWorkingSet(slug, manifest, newRows);
+  } else {
+    appendFileSync(getCurrentDataFile(slug), newRows.map((r) => JSON.stringify(r)).join('\n') + '\n');
+    manifest.stats = recomputeStats([...existing, ...newRows]);
+    writeManifest(slug, manifest);
+  }
+  return { datasetId: slug, appended: newRows.length, replaced: replace, stats: manifest.stats };
+}
+
+/** Swap the whole working set for `rows` (e.g. a spreadsheet import). */
+export function replaceRows(slug, rows, provenance = {}, { featureNames, featureTypes } = {}) {
+  return appendRows(slug, rows, provenance, { replace: true, featureNames, featureTypes });
+}
+
+/** Set a tabular dataset's column names, refusing a mismatch on append. */
+function applyFeatureNames(manifest, featureNames, replace) {
+  if (manifest.modality !== 'tabular') {
+    throw new Error('Feature names only apply to tabular datasets.');
   }
+  const names = featureNames.map((n) => String(n).trim());
+  if (names.length === 0 || names.some((n) => !n)) {
+    throw new Error('Feature names must be non-empty.');
+  }
+  const current = manifest.featureNames;
+  if (!replace && manifest.stats.rowCount > 0 && current?.length && current.join('\u0000') !== names.join('\u0000')) {
+    throw new Error(
+      `These columns don't match the dataset. It expects: ${current.join(', ')}.`,
+    );
+  }
+  manifest.featureNames = names;
+}
 
-  appendFileSync(getCurrentDataFile(slug), lines.join('\n') + '\n');
-  writeManifest(slug, manifest);
-  return { datasetId: slug, appended, stats: manifest.stats };
+/** Set (replace) or check (append) a table's column types, alongside its names. */
+function applyFeatureTypes(manifest, featureTypes, replace) {
+  const incoming = featureTypes === undefined ? undefined : featureTypes.map((t) => String(t).trim());
+  if (incoming) validateColumnTypes(incoming, manifest.featureNames);
+  // An empty dataset takes whatever columns the first rows bring.
+  if (replace || manifest.stats.rowCount === 0) {
+    if (incoming && incoming.some((t) => t !== 'number')) manifest.featureTypes = incoming;
+    else delete manifest.featureTypes;
+    return;
+  }
+  const current = columnTypesOf(manifest) ?? manifest.featureNames.map(() => 'number');
+  const want = incoming ?? manifest.featureNames.map(() => 'number');
+  if (current.join('\u0000') !== want.join('\u0000')) {
+    const describe = manifest.featureNames.map((n, k) => `${n} (${current[k]})`).join(', ');
+    throw new Error(`These columns don't match the dataset. It expects: ${describe}.`);
+  }
 }
 
-function normalizeRow(raw, manifest) {
+function normalizeRow(raw, manifest, width) {
   if (raw == null || typeof raw !== 'object') {
     throw new Error('Each row must be an object.');
   }
@@ -266,14 +343,34 @@ function normalizeRow(raw, manifest) {
       );
     }
   }
-  const row = { features: raw.features, split };
+  let features = raw.features;
+  const types = manifest.modality === 'tabular' ? columnTypesOf(manifest) : null;
+  if (types) {
+    features = normalizeTypedFeatures(raw.features, manifest.featureNames, types);
+  } else if (manifest.modality === 'tabular') {
+    // An object keyed by column name is fine for a named all-numbers table too.
+    if (features && typeof features === 'object' && !Array.isArray(features) && manifest.featureNames?.length) {
+      features = normalizeTypedFeatures(features, manifest.featureNames, manifest.featureNames.map(() => 'number'));
+    }
+    const f = features;
+    if (!Array.isArray(f) || f.length === 0 || f.some((n) => typeof n !== 'number' || !Number.isFinite(n))) {
+      throw new Error('Tabular rows need features that are all numbers (e.g. [12, 45, 8]).');
+    }
+    if (width != null && f.length !== width) {
+      throw new Error(`Expected ${width} number(s) in each row, got ${f.length}.`);
+    }
+  }
+  if (manifest.modality === 'text' && (typeof raw.features !== 'string' || !raw.features.trim())) {
+    throw new Error('Text rows need some text.');
+  }
+  const row = { features, split };
   if (manifest.taskType === 'classification') {
     if (raw.label == null || String(raw.label).length === 0) {
       throw new Error('Classification rows require a "label".');
     }
     row.label = String(raw.label);
   } else {
-    if (raw.target == null || Number.isNaN(Number(raw.target))) {
+    if (raw.target == null || raw.target === '' || !Number.isFinite(Number(raw.target))) {
       throw new Error('Regression rows require a numeric "target".');
     }
     row.target = Number(raw.target);
@@ -376,6 +473,7 @@ export function updateRow(slug, rowId, updates = {}) {
   if ((manifest.modality === 'image' || manifest.modality === 'audio') && updates.features !== undefined) {
     throw new Error(`Can't edit the asset of an ${manifest.modality} row — delete it and re-add.`);
   }
+  const sibling = rows.find((r, i) => i !== idx && Array.isArray(r.features));
   const merged = normalizeRow(
     {
       features: updates.features !== undefined ? updates.features : existing.features,
@@ -384,6 +482,7 @@ export function updateRow(slug, rowId, updates = {}) {
       target: updates.target !== undefined ? updates.target : existing.target,
     },
     manifest,
+    manifest.featureNames?.length ?? sibling?.features.length,
   );
   merged.id = existing.id;
   merged.provenance = { ...(existing.provenance || {}), editedAt: nowISO() };

package/src/utils/model-trainer.js

@@ -7,7 +7,8 @@
  * the Studio is just a front-door that streams the progress it emits.
  *
  * v1 modalities:
- *   - tabular: numeric feature vectors → standardized → dense head
+ *   - tabular: numeric feature vectors → standardized → dense head; typed
+ *              tables (numbers, categories, yes/no, notes) → see table-columns.js
  *   - text:    hashing vectorizer (pure JS) → dense head
  *   - image:   bundled MobileNetV3-Small backbone → 1024-d embedding → dense head
  * audio needs a bundled audio backbone and lands in a later slice.
@@ -20,34 +21,21 @@
 import * as tf from '@tensorflow/tfjs';
 import { readRows, getAssetPath } from './dataset-workspace.js';
 import { embedImage, imageFeaturization } from './image-backbone.js';
+import {
+  columnTypesOf,
+  fitTableFeaturization,
+  featurizeTableRow,
+  normalizeTypedFeatures,
+  vectorizeText as vectorizeWords,
+} from './table-columns.js';
 
 const TEXT_DIM = 1024;
 export const TRAINABLE_MODALITIES = ['tabular', 'text', 'image'];
 
 // ── Featurization ──────────────────────────────────────
 
-function tokenize(s) {
-  return String(s).toLowerCase().match(/[a-z0-9]+/g) || [];
-}
-
-// FNV-1a → bucket. Stable across runs/machines (no Math.random).
-function hashToken(t) {
-  let h = 2166136261 >>> 0;
-  for (let i = 0; i < t.length; i++) {
-    h ^= t.charCodeAt(i);
-    h = Math.imul(h, 16777619) >>> 0;
-  }
-  return h >>> 0;
-}
-
 function vectorizeText(s) {
-  const v = new Array(TEXT_DIM).fill(0);
-  for (const tok of tokenize(s)) v[hashToken(tok) % TEXT_DIM] += 1;
-  let norm = 0;
-  for (let i = 0; i < TEXT_DIM; i++) norm += v[i] * v[i];
-  norm = Math.sqrt(norm);
-  if (norm > 0) for (let i = 0; i < TEXT_DIM; i++) v[i] /= norm;
-  return v;
+  return vectorizeWords(s, TEXT_DIM);
 }
 
 function toNumericVector(features) {
@@ -68,7 +56,7 @@ function imagePathOf(features, slug) {
 
 /** Build the feature matrix + the featurization params to persist. Async to
  *  allow the image backbone to embed each example off disk. */
-async function featurize(rows, modality, slug) {
+async function featurize(rows, modality, slug, manifest) {
   if (modality === 'image') {
     const X = [];
     for (const r of rows) X.push(await embedImage(imagePathOf(r.features, slug)));
@@ -77,6 +65,14 @@ async function featurize(rows, modality, slug) {
   if (modality === 'text') {
     return { X: rows.map((r) => vectorizeText(r.features)), featurization: { modality, dim: TEXT_DIM } };
   }
+  // typed table: each column featurized by its type (featurization.columns)
+  const types = columnTypesOf(manifest);
+  if (types) {
+    const values = rows.map((r) => normalizeTypedFeatures(r.features, manifest.featureNames, types));
+    const featurization = fitTableFeaturization(values, manifest.featureNames, types);
+    if (featurization.dim === 0) throw new Error('None of the columns give the model anything to learn from.');
+    return { X: values.map((v) => featurizeTableRow(v, featurization)), featurization };
+  }
   // tabular: standardize each column (store mean/std for predict)
   const raw = rows.map((r) => toNumericVector(r.features));
   const dim = raw[0].length;
@@ -103,6 +99,19 @@ export async function featurizeOne(input, featurization) {
     return embedImage(path);
   }
   if (featurization.modality === 'text') return vectorizeText(input);
+  if (featurization.columns) {
+    const names = featurization.columns.map((c) => c.name);
+    const types = featurization.columns.map((c) => c.type);
+    let raw = input;
+    if (typeof raw === 'string') {
+      try {
+        raw = JSON.parse(raw); // CLI --input '{"Role":"student", ...}' or '[3, "student"]'
+      } catch {
+        throw new Error(`Send the values as JSON, for example {${names.map((n) => JSON.stringify(n) + ': …').join(', ')}}.`);
+      }
+    }
+    return featurizeTableRow(normalizeTypedFeatures(raw, names, types), featurization);
+  }
   const v = toNumericVector(input);
   return v.map((x, j) => (x - featurization.mean[j]) / (featurization.std[j] || 1));
 }
@@ -144,7 +153,7 @@ export async function trainModel(slug, manifest, { epochs = 40, onProgress } = {
   if (rows.length < 4) throw new Error('Need at least 4 examples to train (more is better).');
 
   const task = manifest.taskType;
-  const { X, featurization } = await featurize(rows, manifest.modality, slug);
+  const { X, featurization } = await featurize(rows, manifest.modality, slug, manifest);
   const inputDim = X[0].length;
 
   // Build targets: one-hot rows (classification) or standardized scalars (regression)

package/src/utils/table-columns.js

@@ -0,0 +1,162 @@
+/**
+ * Typed columns for "table" (tabular) datasets.
+ *
+ * A table dataset names its columns (manifest.featureNames) and, optionally,
+ * gives each a type (manifest.featureTypes, same order):
+ *
+ *   number    3, 4.5          scaled to mean 0 / std 1 for training
+ *   category  "student"       one slot per value seen in training (one-hot)
+ *   boolean   true / false    1 or 0
+ *   text      "I worked on…"  hashed words, like a words dataset (short notes)
+ *
+ * A row's features are its values in column order: [3, "student", true, "…"].
+ * Datasets with no featureTypes are all numbers, exactly as before, so every
+ * existing dataset and model keeps working unchanged.
+ *
+ * The featurization here must match myvillage-studio packages/lab-runtime
+ * (myvillage-model.js), which runs these models outside the CLI; its parity
+ * test trains with this code and compares answers.
+ */
+
+export const COLUMN_TYPES = ['number', 'category', 'boolean', 'text'];
+
+/** Hash-bucket width for a writing column inside a table (a words dataset uses 1024). */
+export const TABLE_TEXT_DIM = 256;
+/** Most distinct values a category column one-hot encodes; the rest count as "other" (all zeros). */
+export const MAX_CATEGORY_VALUES = 50;
+
+const TRUE_WORDS = new Set(['true', 'yes', 'y', '1', 't']);
+const FALSE_WORDS = new Set(['false', 'no', 'n', '0', 'f']);
+
+/** The dataset's column types, or null for a plain all-numbers table. */
+export function columnTypesOf(manifest) {
+  const t = manifest?.featureTypes;
+  return Array.isArray(t) && t.length && t.some((x) => x !== 'number') ? t : null;
+}
+
+/** Check a featureTypes list against its names. */
+export function validateColumnTypes(types, names) {
+  if (!Array.isArray(types) || types.length === 0) throw new Error('Column types must be a list.');
+  const bad = types.find((t) => !COLUMN_TYPES.includes(t));
+  if (bad !== undefined) throw new Error(`Unknown column type "${bad}". Use: ${COLUMN_TYPES.join(', ')}.`);
+  if (names && names.length !== types.length) {
+    throw new Error(`There are ${names.length} column names but ${types.length} column types.`);
+  }
+}
+
+function coerce(value, type, name) {
+  const label = name ? `"${name}"` : 'A value';
+  if (type === 'number') {
+    const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() !== '' ? Number(value.trim()) : NaN;
+    if (!Number.isFinite(n)) throw new Error(`${label} needs a number.`);
+    return n;
+  }
+  if (type === 'boolean') {
+    if (typeof value === 'boolean') return value;
+    const w = String(value ?? '').trim().toLowerCase();
+    if (TRUE_WORDS.has(w)) return true;
+    if (FALSE_WORDS.has(w)) return false;
+    throw new Error(`${label} needs yes or no (true/false).`);
+  }
+  // category / text: any scalar, kept as trimmed text; blank is allowed.
+  if (value !== null && value !== undefined && typeof value === 'object') {
+    throw new Error(`${label} needs a single value, not a list or object.`);
+  }
+  return value === null || value === undefined ? '' : String(value).trim();
+}
+
+/**
+ * Turn a raw typed-table row (a list in column order, or an object keyed by
+ * column name) into the stored list of values. Throws a message a person can act on.
+ */
+export function normalizeTypedFeatures(raw, names, types) {
+  let values;
+  if (Array.isArray(raw)) {
+    values = raw;
+  } else if (raw && typeof raw === 'object') {
+    values = names.map((n) => {
+      if (!(n in raw)) throw new Error(`Missing "${n}".`);
+      return raw[n];
+    });
+  } else {
+    throw new Error(`Table rows need a value for each column: ${names.join(', ')}.`);
+  }
+  if (values.length !== types.length) {
+    throw new Error(`Expected ${types.length} values (${names.join(', ')}), got ${values.length}.`);
+  }
+  return values.map((v, i) => coerce(v, types[i], names[i]));
+}
+
+// ── Featurization ─────────────────────────────────────────────────────────
+
+function tokenize(s) {
+  return String(s).toLowerCase().match(/[a-z0-9]+/g) || [];
+}
+
+// FNV-1a, the same stable hash words datasets use.
+export function hashToken(t) {
+  let h = 2166136261 >>> 0;
+  for (let i = 0; i < t.length; i++) {
+    h ^= t.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h >>> 0;
+}
+
+export function vectorizeText(s, dim) {
+  const v = new Array(dim).fill(0);
+  for (const tok of tokenize(s)) v[hashToken(tok) % dim] += 1;
+  let norm = 0;
+  for (let i = 0; i < dim; i++) norm += v[i] * v[i];
+  norm = Math.sqrt(norm);
+  if (norm > 0) for (let i = 0; i < dim; i++) v[i] /= norm;
+  return v;
+}
+
+/**
+ * Learn how to turn each column into numbers from the training rows (already
+ * normalized). Returns the featurization record saved with the model.
+ */
+export function fitTableFeaturization(rows, names, types) {
+  const columns = types.map((type, j) => {
+    const col = rows.map((r) => r[j]);
+    if (type === 'number') {
+      const mean = col.reduce((a, b) => a + b, 0) / col.length;
+      const std = Math.sqrt(col.reduce((a, b) => a + (b - mean) ** 2, 0) / col.length) || 1;
+      return { name: names[j], type, mean, std };
+    }
+    if (type === 'category') {
+      const counts = new Map();
+      for (const v of col) if (v !== '') counts.set(v, (counts.get(v) || 0) + 1);
+      // Most common first, ties alphabetically, so the order is stable.
+      const values = [...counts.entries()]
+        .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+        .slice(0, MAX_CATEGORY_VALUES)
+        .map(([v]) => v);
+      return { name: names[j], type, values };
+    }
+    if (type === 'text') return { name: names[j], type, dim: TABLE_TEXT_DIM };
+    return { name: names[j], type };
+  });
+  const dim = columns.reduce((n, c) => n + columnWidth(c), 0);
+  return { modality: 'tabular', dim, columns };
+}
+
+function columnWidth(c) {
+  if (c.type === 'category') return c.values.length;
+  if (c.type === 'text') return c.dim;
+  return 1;
+}
+
+/** One normalized row → the model's input vector. */
+export function featurizeTableRow(values, featurization) {
+  const out = [];
+  featurization.columns.forEach((c, j) => {
+    const v = values[j];
+    if (c.type === 'number') out.push((v - c.mean) / (c.std || 1));
+    else if (c.type === 'boolean') out.push(v ? 1 : 0);
+    else if (c.type === 'category') for (const value of c.values) out.push(v === value ? 1 : 0);
+    else for (const x of vectorizeText(v, c.dim)) out.push(x);
+  });
+  return out;
+}