@myvillage/cli 2.4.0 → 2.6.0

package/package.json

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

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

@@ -14,16 +14,19 @@
 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 ' +
-  'copied into the dataset). For classification provide `label`; for ' +
+  '`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) or .wav file path (audio 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 ' +
-  'models). Returns the predicted class with per-class confidence scores ' +
+  'text (words models), the values of one table row as a list in column ' +
+  'order or an object keyed by column name (table models), a local image file path (image ' +
+  'models), or a local .wav file path (sound 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,16 @@ 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); ' +
+                    'or, for audio datasets, an absolute path to a local .wav file.',
                 ),
               label: z.string().optional().describe('Class label (classification datasets)'),
               target: z.number().optional().describe('Numeric target (regression datasets)'),
@@ -90,16 +96,21 @@ export function getBuiltinTools(agentName, config) {
           const provenance = { source: `agent:${agentName}` };
           const agentId = config?.man?.village_agent_id;
           if (agentId) provenance.agentId = agentId;
-          // For image datasets, the agent passes a file path; ingest each into
-          // the dataset's assets/ and swap in the resulting AssetRef before the
-          // shared appendRows() runs (same path the CLI --image flow takes).
+          // For image and audio datasets, the agent passes a file path; ingest
+          // each into the dataset's assets/ and swap in the resulting AssetRef
+          // before the shared appendRows() runs (same path as CLI --image/--audio).
           const manifest = readManifest(datasetId);
           let toAppend = rows;
-          if (manifest?.modality === 'image') {
+          if (manifest?.modality === 'image' || manifest?.modality === 'audio') {
+            const kind = manifest.modality;
             toAppend = rows.map((r) => {
               const path = typeof r.features === 'string' ? r.features : r.features?.path;
-              if (!path) throw new Error('Image rows need a local image file path in "features".');
-              return { ...r, features: ingestAsset(datasetId, path, 'image') };
+              if (!path) {
+                throw new Error(kind === 'image'
+                  ? 'Image rows need a local image file path in "features".'
+                  : 'Sound rows need a local .wav file path in "features".');
+              }
+              return { ...r, features: ingestAsset(datasetId, path, kind) };
             });
           }
           const result = appendRows(datasetId, toAppend, provenance);
@@ -122,10 +133,15 @@ 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); ' +
+              'or, for sound models, an absolute path to a local .wav file.',
           ),
       }),
       execute: async ({ modelId, input }) => {

package/src/commands/dataset.js

@@ -89,12 +89,13 @@ export async function datasetAppendCommand(options) {
     const manifest = readManifest(slug);
 
     let rows;
-    if (options.image) {
-      // Copy the image into the dataset's assets/ and reference it by AssetRef.
-      if (manifest.modality !== 'image') {
-        throw new Error(`--image is only valid for image datasets (this one is "${manifest.modality}").`);
+    if (options.image || options.audio) {
+      // Copy the picture or sound into the dataset's assets/ and reference it by AssetRef.
+      const kind = options.image ? 'image' : 'audio';
+      if (manifest.modality !== kind) {
+        throw new Error(`--${options.image ? 'image' : 'audio'} is only valid for ${kind} datasets (this one is "${manifest.modality}").`);
       }
-      const asset = ingestAsset(slug, options.image, 'image');
+      const asset = ingestAsset(slug, options.image || options.audio, kind);
       const row = { split: options.split || 'train', features: asset };
       if (options.label !== undefined) row.label = options.label;
       if (options.target !== undefined) row.target = Number(options.target);
@@ -103,18 +104,19 @@ 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, manifest.modality) : 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];
     } else {
-      throw new Error('Provide --image <path> (image datasets), --file <jsonl>, or --text/--features (with --label or --target).');
+      throw new Error('Provide --image <path> (image datasets), --audio <path> (audio 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();
     let result;
@@ -122,6 +124,7 @@ export async function datasetAppendCommand(options) {
       result = appendRows(slug, rows, { source: options.source || 'cli' }, {
         replace: Boolean(options.replace),
         featureNames,
+        featureTypes,
       });
     } finally {
       if (spinner) spinner.stop();
@@ -224,7 +227,8 @@ export async function datasetRowUpdateCommand(options) {
     if (!options.id) throw new Error('--id <rowId> is required.');
     const updates = {};
     if (options.features !== undefined) {
-      updates.features = parseFeatures(options.features, readManifest(slug)?.modality);
+      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;
@@ -274,12 +278,20 @@ function parseNameList(raw) {
   return trimmed.split(',').map((s) => s.trim());
 }
 
-function parseFeatures(raw, modality) {
+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);

package/src/commands/model.js

@@ -57,7 +57,7 @@ export async function modelTrainCommand(options) {
     const m = record.metrics;
     if (m.accuracy != null) info(`  accuracy: ${(m.accuracy * 100).toFixed(1)}% over ${m.classes} classes`);
     if (m.mae != null) info(`  MAE: ${m.mae} · R²: ${m.r2}`);
-    const testFlag = manifest.modality === 'image' ? '--image <path>' : '--input "..."';
+    const testFlag = manifest.modality === 'image' ? '--image <path>' : manifest.modality === 'audio' ? '--audio <file.wav>' : '--input "..."';
     info(`  test it:  myvillage model predict ${manifest.slug} ${testFlag}`);
   } catch (e) {
     if (options.json) process.stdout.write(JSON.stringify({ type: 'error', error: e.message }) + '\n');
@@ -123,11 +123,16 @@ export async function modelPredictCommand(slug, options) {
   try {
     if (!modelExists(slug)) throw new Error(`Model "${slug}" not found.`);
     const record = readModelManifest(slug);
-    // Image models take a file path (--image); text/tabular take --input.
+    // Image and sound models take a file path (--image / --audio); text/tabular take --input.
     const isImage = record.modality === 'image';
-    const input = isImage ? options.image : options.input;
+    const isAudio = record.modality === 'audio';
+    const input = isImage ? options.image : isAudio ? options.audio : options.input;
     if (input === undefined) {
-      throw new Error(isImage ? '--image <path> is required for image models.' : '--input <value> is required.');
+      throw new Error(
+        isImage ? '--image <path> is required for image models.'
+        : isAudio ? '--audio <file.wav> is required for sound models.'
+        : '--input <value> is required.',
+      );
     }
     const model = await loadModel(slug);
     const result = await predictWithModel(model, record, input);

package/src/index.js

@@ -1005,14 +1005,16 @@ export function run() {
     .requiredOption('--dataset <slug>', 'Target dataset slug')
     .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('--audio <path>', 'WAV file to add (audio 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);
 
@@ -1045,7 +1047,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')
@@ -1081,8 +1083,9 @@ 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('--audio <path>', 'WAV file to classify (sound models)')
     .option('--json', 'Output raw JSON')
     .action(modelPredictCommand);
 

package/src/utils/audio-backbone.js

@@ -0,0 +1,194 @@
+/**
+ * Sound feature-extractor for the Studio "Lab" pillar.
+ *
+ * Turns a WAV file into a fixed-length embedding using YAMNet, which is
+ * **bundled inside this package** (vendor/backbones/yamnet/) and loaded from
+ * disk — never downloaded — the same way image-backbone.js bundles MobileNet.
+ *
+ * Pipeline: read the WAV (pure JS, any common PCM or float format) → mix to
+ * mono → keep the first MAX_SECONDS → resample to 16 kHz → YAMNet → one
+ * 1024-d embedding per 0.48 s frame → averaged into a single 1024-d vector.
+ *
+ * The embedding feeds the SAME dense head the other modalities train; sound
+ * only adds this featurization step. Studio records clips as 16-bit mono WAV,
+ * so WAV is the only format read here. tfjs is imported lazily.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+export const BACKBONE_ID = 'yamnet';
+export const SAMPLE_RATE = 16000;
+export const EMBED_DIM = 1024;
+/** Only the start of a long clip is used, so training and predicting stay quick. */
+export const MAX_SECONDS = 10;
+const EMBEDDINGS_OUTPUT = 'Identity_1';
+
+const BACKBONE_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'vendor', 'backbones', BACKBONE_ID);
+
+let _backbonePromise = null;
+
+/** A GraphModel IOHandler reading the vendored files off disk (see image-backbone.js). */
+function diskGraphHandler(dir) {
+  return {
+    load: async () => {
+      const manifestPath = join(dir, 'model.json');
+      if (!existsSync(manifestPath)) {
+        throw new Error(
+          `Bundled sound backbone not found at ${dir}. The YAMNet weights ship ` +
+            'inside @myvillage/cli (vendor/backbones/); reinstall the CLI if this is missing.',
+        );
+      }
+      const j = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+      const specs = [];
+      const buffers = [];
+      for (const grp of j.weightsManifest) {
+        for (const p of grp.paths) buffers.push(readFileSync(join(dir, p)));
+        specs.push(...grp.weights);
+      }
+      const concat = Buffer.concat(buffers);
+      return {
+        modelTopology: j.modelTopology,
+        weightSpecs: specs,
+        weightData: concat.buffer.slice(concat.byteOffset, concat.byteOffset + concat.byteLength),
+        format: j.format,
+        generatedBy: j.generatedBy,
+        convertedBy: j.convertedBy,
+      };
+    },
+  };
+}
+
+async function getBackbone() {
+  if (!_backbonePromise) {
+    _backbonePromise = (async () => {
+      const tf = await import('@tensorflow/tfjs');
+      await tf.setBackend('cpu');
+      await tf.ready();
+      return tf.loadGraphModel(diskGraphHandler(BACKBONE_DIR));
+    })().catch((e) => {
+      _backbonePromise = null;
+      throw e;
+    });
+  }
+  return _backbonePromise;
+}
+
+/**
+ * A WAV file's bytes → { sampleRate, samples: Float32Array (mono, [-1, 1]) }.
+ * Reads 8/16/24/32-bit PCM and 32/64-bit float, any number of channels
+ * (mixed down by averaging), including WAVE_FORMAT_EXTENSIBLE files.
+ */
+export function decodeWav(buf) {
+  const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const tag = (at) => String.fromCharCode(bytes[at], bytes[at + 1], bytes[at + 2], bytes[at + 3]);
+  if (bytes.length < 12 || tag(0) !== 'RIFF' || tag(8) !== 'WAVE') {
+    throw new Error('That sound isn\'t a WAV file. Record it in Studio, or save it as WAV first.');
+  }
+  let fmt = null;
+  let data = null;
+  for (let at = 12; at + 8 <= bytes.length; ) {
+    const id = tag(at);
+    const size = view.getUint32(at + 4, true);
+    const body = at + 8;
+    if (id === 'fmt ') {
+      let format = view.getUint16(body, true);
+      // WAVE_FORMAT_EXTENSIBLE: the real format is the first 2 bytes of the sub-format GUID.
+      if (format === 0xfffe && size >= 26) format = view.getUint16(body + 24, true);
+      fmt = {
+        format,
+        channels: view.getUint16(body + 2, true),
+        sampleRate: view.getUint32(body + 4, true),
+        bits: view.getUint16(body + 14, true),
+      };
+    } else if (id === 'data') {
+      data = { start: body, length: Math.min(size, bytes.length - body) };
+    }
+    at = body + size + (size % 2); // chunks are padded to an even length
+  }
+  if (!fmt || !data) throw new Error('That WAV file is missing its sound data.');
+  const { format, channels, sampleRate, bits } = fmt;
+  const pcm = format === 1;
+  const float = format === 3;
+  if (!(pcm && [8, 16, 24, 32].includes(bits)) && !(float && (bits === 32 || bits === 64))) {
+    throw new Error('That WAV file uses a format Studio can\'t read. Save it as 16-bit PCM WAV.');
+  }
+  if (!channels || !sampleRate) throw new Error('That WAV file looks damaged.');
+  const width = bits / 8;
+  const frames = Math.floor(data.length / (width * channels));
+  const read = (o) => {
+    if (float) return bits === 32 ? view.getFloat32(o, true) : view.getFloat64(o, true);
+    if (bits === 8) return (bytes[o] - 128) / 128;
+    if (bits === 16) return view.getInt16(o, true) / 32768;
+    if (bits === 24) {
+      const v = bytes[o] | (bytes[o + 1] << 8) | (bytes[o + 2] << 16);
+      return (v & 0x800000 ? v - 0x1000000 : v) / 8388608;
+    }
+    return view.getInt32(o, true) / 2147483648;
+  };
+  const samples = new Float32Array(frames);
+  for (let i = 0, o = data.start; i < frames; i++) {
+    let s = 0;
+    for (let c = 0; c < channels; c++, o += width) s += read(o);
+    samples[i] = s / channels;
+  }
+  return { sampleRate, samples };
+}
+
+/**
+ * Mono samples at any rate → the first MAX_SECONDS at 16 kHz. Going down, each
+ * output sample averages the input samples it covers (a box filter, so higher
+ * pitches don't fold back in); going up, it interpolates linearly. No trig,
+ * so the result is the same on every computer.
+ */
+export function toModelRate(samples, sampleRate) {
+  const input = samples.subarray(0, Math.min(samples.length, Math.round(sampleRate * MAX_SECONDS)));
+  if (sampleRate === SAMPLE_RATE) return Float32Array.from(input);
+  const ratio = sampleRate / SAMPLE_RATE;
+  const n = Math.floor(input.length / ratio);
+  const out = new Float32Array(n);
+  if (ratio > 1) {
+    for (let k = 0; k < n; k++) {
+      const from = k * ratio;
+      const to = from + ratio;
+      let sum = 0;
+      for (let i = Math.floor(from); i < to && i < input.length; i++) {
+        const overlap = Math.min(i + 1, to) - Math.max(i, from);
+        sum += input[i] * overlap;
+      }
+      out[k] = sum / ratio;
+    }
+  } else {
+    for (let k = 0; k < n; k++) {
+      const x = k * ratio;
+      const i = Math.floor(x);
+      const t = x - i;
+      out[k] = input[i] * (1 - t) + (i + 1 < input.length ? input[i + 1] : input[i]) * t;
+    }
+  }
+  return out;
+}
+
+/** 16 kHz mono samples → the averaged 1024-d YAMNet embedding. */
+export async function embedSamples(samples16k) {
+  if (!samples16k.length) throw new Error('That sound is empty.');
+  const tf = await import('@tensorflow/tfjs');
+  const model = await getBackbone();
+  return tf.tidy(() => {
+    const frames = model.execute(tf.tensor1d(samples16k), EMBEDDINGS_OUTPUT); // [frames, 1024]
+    return Array.from(tf.mean(frames, 0).dataSync());
+  });
+}
+
+/** A WAV file → Float array of length EMBED_DIM (1024). Used by training and predict. */
+export async function embedAudio(path) {
+  if (!existsSync(path)) throw new Error(`Sound not found: ${path}`);
+  const { samples, sampleRate } = decodeWav(readFileSync(path));
+  return embedSamples(toModelRate(samples, sampleRate));
+}
+
+/** Featurization params persisted in the model record for sound models. */
+export function audioFeaturization() {
+  return { modality: 'audio', dim: EMBED_DIM, backbone: BACKBONE_ID, sampleRate: SAMPLE_RATE, maxSeconds: MAX_SECONDS };
+}

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';
@@ -205,26 +206,34 @@ export function createDataset({ name, modality, taskType = 'classification', lab
  * 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 tabular vector
- * (e.g. from a spreadsheet header); once set, every tabular row must have
- * exactly that many numbers.
+ * 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 })
- * @param {{replace?:boolean, featureNames?:string[]}} opts
+ * @param {{replace?:boolean, featureNames?:string[], featureTypes?:string[]}} opts
  * @returns {{datasetId:string, appended:number, replaced:boolean, stats:object}}
  */
-export function appendRows(slug, rows, provenance = {}, { replace = false, featureNames } = {}) {
+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.');
   }
+  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;
   }
 
   const existing = replace ? [] : readRows(slug);
@@ -272,8 +281,8 @@ export function appendRows(slug, rows, provenance = {}, { replace = false, featu
 }
 
 /** Swap the whole working set for `rows` (e.g. a spreadsheet import). */
-export function replaceRows(slug, rows, provenance = {}, { featureNames } = {}) {
-  return appendRows(slug, rows, provenance, { replace: true, featureNames });
+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. */
@@ -286,7 +295,7 @@ function applyFeatureNames(manifest, featureNames, replace) {
     throw new Error('Feature names must be non-empty.');
   }
   const current = manifest.featureNames;
-  if (!replace && current?.length && current.join('\u0000') !== names.join('\u0000')) {
+  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(', ')}.`,
     );
@@ -294,6 +303,24 @@ function applyFeatureNames(manifest, featureNames, replace) {
   manifest.featureNames = names;
 }
 
+/** 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, width) {
   if (raw == null || typeof raw !== 'object') {
     throw new Error('Each row must be an object.');
@@ -316,8 +343,16 @@ function normalizeRow(raw, manifest, width) {
       );
     }
   }
-  if (manifest.modality === 'tabular') {
-    const f = raw.features;
+  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]).');
     }
@@ -328,7 +363,7 @@ function normalizeRow(raw, manifest, width) {
   if (manifest.modality === 'text' && (typeof raw.features !== 'string' || !raw.features.trim())) {
     throw new Error('Text rows need some text.');
   }
-  const row = { features: raw.features, split };
+  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".');