@myvillage/cli 2.4.0 → 2.6.0

package/src/utils/model-trainer.js

@@ -7,47 +7,37 @@
  * 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.
+ *   - audio:   WAV → 16 kHz → bundled YAMNet backbone → averaged 1024-d embedding → dense head
  *
  * Transfer-learning-style split: featurize once, then train a small head. The
  * featurization params travel in the model record so predict() needs no data.
- * (For image, the backbone itself is bundled — see image-backbone.js — so the
- * embedding can always be recomputed at predict time from the same weights.)
+ * (For image and audio, the backbone itself is bundled — see image-backbone.js
+ * and audio-backbone.js — so the embedding can always be recomputed at predict
+ * time from the same weights.)
  */
 import * as tf from '@tensorflow/tfjs';
 import { readRows, getAssetPath } from './dataset-workspace.js';
 import { embedImage, imageFeaturization } from './image-backbone.js';
+import { embedAudio, audioFeaturization } from './audio-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'];
+export const TRAINABLE_MODALITIES = ['tabular', 'text', 'image', 'audio'];
 
 // ── 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) {
@@ -58,25 +48,38 @@ function toNumericVector(features) {
   throw new Error('Tabular features must be a numeric vector.');
 }
 
-/** Resolve an image row's features to an absolute file path on disk. */
-function imagePathOf(features, slug) {
+/** Resolve an image or sound row's features to an absolute file path on disk. */
+function assetPathOf(features, slug, what = 'Image') {
   // Rows store an AssetRef {kind,path}; path is relative to the dataset assets/.
   const rel = typeof features === 'string' ? features : features?.path;
-  if (!rel) throw new Error('Image rows must reference an image asset.');
+  if (!rel) throw new Error(`${what} rows must reference a${what === 'Image' ? 'n image' : ' sound'} asset.`);
   return getAssetPath(slug, rel);
 }
 
 /** 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)));
+    for (const r of rows) X.push(await embedImage(assetPathOf(r.features, slug)));
     return { X, featurization: imageFeaturization() };
   }
+  if (modality === 'audio') {
+    const X = [];
+    for (const r of rows) X.push(await embedAudio(assetPathOf(r.features, slug, 'Sound')));
+    return { X, featurization: audioFeaturization() };
+  }
   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;
@@ -94,7 +97,7 @@ async function featurize(rows, modality, slug) {
 }
 
 /** Featurize a single input the same way (for predict). Async because the
- *  image path runs the backbone; text/tabular resolve synchronously. */
+ *  image and sound paths run a backbone; text/tabular resolve synchronously. */
 export async function featurizeOne(input, featurization) {
   if (featurization.modality === 'image') {
     // input is an absolute image file path (CLI --image / model_predict tool).
@@ -102,7 +105,26 @@ export async function featurizeOne(input, featurization) {
     if (!path) throw new Error('Image prediction needs an image file path.');
     return embedImage(path);
   }
+  if (featurization.modality === 'audio') {
+    // input is an absolute WAV file path (CLI --audio / model_predict tool).
+    const path = typeof input === 'string' ? input : input?.path;
+    if (!path) throw new Error('Sound prediction needs a WAV file path.');
+    return embedAudio(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));
 }
@@ -137,14 +159,14 @@ export async function trainModel(slug, manifest, { epochs = 40, onProgress } = {
 
   if (!TRAINABLE_MODALITIES.includes(manifest.modality)) {
     throw new Error(
-      `Training for "${manifest.modality}" datasets is coming soon — v1 supports ${TRAINABLE_MODALITIES.join(' and ')}.`,
+      `Training for "${manifest.modality}" datasets is coming soon — this version supports ${TRAINABLE_MODALITIES.join(', ')}.`,
     );
   }
   const rows = readRows(slug, {});
   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;
+}

package/vendor/backbones/yamnet/SOURCE.md

@@ -0,0 +1,22 @@
+# YAMNet (TF.js GraphModel) — vendored backbone
+
+Bundled sound feature-extractor for the Studio "Lab" pillar audio models.
+**Never downloaded at runtime** — shipped inside `@myvillage/cli` so the Studio
+stays "the only thing you install" (see ed-platform docs/architecture/studio-models-pillar.md §0b, §13).
+
+- **Model:** YAMNet (MobileNetV1-style audio event classifier trained on AudioSet)
+- **Input:** `waveform` — 1-D float32 mono samples at **16 kHz**, in `[-1, 1]`, any length
+- **Outputs:** `Identity` `[frames, 521]` class scores, `Identity_1` `[frames, 1024]`
+  embeddings (what we use, averaged over frames), `Identity_2` log-mel spectrogram.
+  One frame per 0.48 s of sound (0.96 s windows); a clip shorter than one window is padded.
+- **Format:** TensorFlow.js `graph-model` (model.json + 4 weight shards, ~16 MB, float32)
+- **Source:** Google YAMNet TF.js (`google/tfjs-model/yamnet/tfjs/1`), TF Hub / Kaggle Models
+  (`google/yamnet`), converted by TensorFlow.js Converter v2.1.0
+- **Downloaded:** 2026-09-24 from `https://tfhub.dev/google/tfjs-model/yamnet/tfjs/1`
+- **SHA-256:**
+  - `model.json` 552a4e59884a7fad25dbdbc1bbe75af2a416bca44de12523081d4b55606d59d3
+  - `group1-shard1of4.bin` 2ba509dbfc875e0483e5e3f6935cd9be9f986dd1219796c649422fd337dde4ca
+  - `group1-shard2of4.bin` b789c08119ef33a534475b964c25447586e18328039c06322d4b5337887d1fca
+  - `group1-shard3of4.bin` 464a4a19cfb207c81bbd6ba079d2f36402902c07faa8b6d305f438dc0ab74212
+  - `group1-shard4of4.bin` 311fcb65f9985e825a9f162b7ef82bdc81a745bff11f90bd7b1eaabbd1f55e6b
+- **License:** Apache-2.0 (TensorFlow Hub / Google)