@myvillage/cli 1.72.0 → 1.74.0

package/src/utils/model-trainer.js

@@ -6,19 +6,23 @@
  * Studio shells out to that same command. This is the single training engine;
  * the Studio is just a front-door that streams the progress it emits.
  *
- * v1 modalities (zero downloaded backbones):
+ * v1 modalities:
  *   - tabular: numeric feature vectors → standardized → dense head
  *   - text:    hashing vectorizer (pure JS) → dense head
- * image/audio need a bundled vision/audio backbone and land in a later slice.
+ *   - image:   bundled MobileNetV3-Small backbone → 1024-d embedding → dense head
+ * audio needs a bundled audio backbone and lands in a later slice.
  *
  * 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.)
  */
 import * as tf from '@tensorflow/tfjs';
-import { readRows } from './dataset-workspace.js';
+import { readRows, getAssetPath } from './dataset-workspace.js';
+import { embedImage, imageFeaturization } from './image-backbone.js';
 
 const TEXT_DIM = 1024;
-export const TRAINABLE_MODALITIES = ['tabular', 'text'];
+export const TRAINABLE_MODALITIES = ['tabular', 'text', 'image'];
 
 // ── Featurization ──────────────────────────────────────
 
@@ -54,8 +58,22 @@ function toNumericVector(features) {
   throw new Error('Tabular features must be a numeric vector.');
 }
 
-/** Build the feature matrix + the featurization params to persist. */
-function featurize(rows, modality) {
+/** Resolve an image row's features to an absolute file path on disk. */
+function imagePathOf(features, slug) {
+  // 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.');
+  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) {
+  if (modality === 'image') {
+    const X = [];
+    for (const r of rows) X.push(await embedImage(imagePathOf(r.features, slug)));
+    return { X, featurization: imageFeaturization() };
+  }
   if (modality === 'text') {
     return { X: rows.map((r) => vectorizeText(r.features)), featurization: { modality, dim: TEXT_DIM } };
   }
@@ -75,8 +93,15 @@ function featurize(rows, modality) {
   return { X, featurization: { modality, dim, mean, std } };
 }
 
-/** Featurize a single input the same way (for predict). */
-export function featurizeOne(input, featurization) {
+/** Featurize a single input the same way (for predict). Async because the
+ *  image path runs the 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).
+    const path = typeof input === 'string' ? input : input?.path;
+    if (!path) throw new Error('Image prediction needs an image file path.');
+    return embedImage(path);
+  }
   if (featurization.modality === 'text') return vectorizeText(input);
   const v = toNumericVector(input);
   return v.map((x, j) => (x - featurization.mean[j]) / (featurization.std[j] || 1));
@@ -119,7 +144,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 } = featurize(rows, manifest.modality);
+  const { X, featurization } = await featurize(rows, manifest.modality, slug);
   const inputDim = X[0].length;
 
   // Build targets: one-hot rows (classification) or standardized scalars (regression)
@@ -226,10 +251,12 @@ function computeMetrics(model, xs, ys, task, labels, targetMean, targetStd) {
   });
 }
 
-/** Run a prediction with an already-loaded model + its record. */
-export function predictWithModel(model, record, input) {
+/** Run a prediction with an already-loaded model + its record. Async because
+ *  image featurization runs the backbone; the head forward pass stays in a
+ *  tidy() so intermediate tensors are freed. */
+export async function predictWithModel(model, record, input) {
+  const feats = await featurizeOne(input, record.featurization);
   return tf.tidy(() => {
-    const feats = featurizeOne(input, record.featurization);
     const out = model.predict(tf.tensor2d([feats]));
     if (record.taskType === 'classification') {
       const scores = Array.from(out.dataSync());

package/vendor/backbones/mobilenet-v3-small/SOURCE.md

@@ -0,0 +1,13 @@
+# MobileNetV3-Small (TF.js GraphModel) — vendored backbone
+
+Bundled feature-extractor for the Studio "Lab" pillar image classification.
+**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:** MobileNetV3-Small, 1.0 depth, 224×224, ImageNet feature-vector head removed
+- **Input:** `[-1, 224, 224, 3]` float32, pixels normalized to `[0, 1]`
+- **Output:** `[-1, 1024]` embedding (fed to the trained dense head)
+- **Format:** TensorFlow.js `graph-model` (model.json + 2 weight shards, ~5.85 MB)
+- **Source:** Google MobileNetV3 TfJs feature-vector (`small-100-224`), Kaggle Models
+  (`google/mobilenet-v3`), converted by TensorFlow.js Converter v3.0.0
+- **License:** Apache-2.0 (TensorFlow Hub / Google)