@myvillage/cli 1.71.0 → 1.73.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "1.71.0",
+  "version": "1.73.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "bin/",
     "src/",
     "tools/",
+    "vendor/",
     "README.md"
   ],
   "keywords": [
@@ -37,9 +38,11 @@
     "commander": "^11.1.0",
     "conf": "^12.0.0",
     "inquirer": "^9.2.12",
+    "jpeg-js": "^0.4.4",
     "open": "^10.0.3",
     "ora": "^8.0.1",
     "p-limit": "^5.0.0",
+    "pngjs": "^7.0.0",
     "tar": "^7.5.16",
     "update-notifier": "^7.0.0",
     "yaml": "^2.3.0",

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

@@ -14,13 +14,16 @@
 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`). For classification provide `label`; for ' +
+  '`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 ' +
   '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. ' +
-  'Returns the predicted class with per-class confidence scores ' +
+  '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 ' +
   '(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

@@ -14,7 +14,7 @@
  */
 import { tool } from 'ai';
 import { z } from 'zod';
-import { appendRows, datasetExists } from '../utils/dataset-workspace.js';
+import { appendRows, datasetExists, readManifest, ingestAsset } from '../utils/dataset-workspace.js';
 import { DATASET_APPEND_DESCRIPTION, MODEL_PREDICT_DESCRIPTION } from './builtin-tools-registry.js';
 
 export { BUILTIN_TOOL_DEFS } from './builtin-tools-registry.js';
@@ -36,7 +36,10 @@ export function getBuiltinTools(agentName, config) {
             z.object({
               features: z
                 .union([z.string(), z.array(z.number())])
-                .describe('Text content, or a numeric vector for tabular data'),
+                .describe(
+                  'Text content; a numeric vector for tabular data; 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)'),
               split: z.enum(['train', 'val']).optional(),
@@ -57,7 +60,19 @@ export function getBuiltinTools(agentName, config) {
           const provenance = { source: `agent:${agentName}` };
           const agentId = config?.man?.village_agent_id;
           if (agentId) provenance.agentId = agentId;
-          const result = appendRows(datasetId, rows, provenance);
+          // 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).
+          const manifest = readManifest(datasetId);
+          let toAppend = rows;
+          if (manifest?.modality === 'image') {
+            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') };
+            });
+          }
+          const result = appendRows(datasetId, toAppend, provenance);
           return {
             ok: true,
             datasetId: result.datasetId,
@@ -78,7 +93,10 @@ export function getBuiltinTools(agentName, config) {
         modelId: z.string().describe('Slug of the local trained model'),
         input: z
           .union([z.string(), z.array(z.number())])
-          .describe('Text, or a numeric vector for tabular models'),
+          .describe(
+            'Text; a numeric vector for tabular models; or, for image models, ' +
+              'an absolute path to a local image file (.jpg/.png).',
+          ),
       }),
       execute: async ({ modelId, input }) => {
         try {

package/src/agent-runtime/context.js

@@ -3,6 +3,8 @@
 // This becomes the user message sent to the LLM.
 
 import { getAgentFeed, getAgentMentions, getAgentEvents } from '../utils/api.js';
+import { listDatasets } from '../utils/dataset-workspace.js';
+import { listModels } from '../utils/model-workspace.js';
 
 export async function gatherContext(agentConfig, lastCheckIn, recentActions = []) {
   const parts = [];
@@ -110,6 +112,33 @@ export async function gatherContext(agentConfig, lastCheckIn, recentActions = []
     }
   }
 
+  // Local Lab datasets & models, so the agent knows what it can append to /
+  // predict with (and the exact slugs to pass to dataset_append / model_predict).
+  // Local-only, synchronous file reads; tfjs is NOT loaded by listing models.
+  try {
+    const datasets = listDatasets();
+    if (datasets.length > 0) {
+      parts.push('\nLocal datasets you can add to with dataset_append (use the slug as datasetId):');
+      for (const d of datasets.slice(0, 25)) {
+        parts.push(`- ${d.slug} — ${d.modality}/${d.taskType}, ${d.stats?.rowCount ?? 0} rows`);
+      }
+    }
+  } catch {
+    /* no local datasets / store unavailable — skip */
+  }
+  try {
+    const models = listModels();
+    if (models.length > 0) {
+      parts.push('\nLocal models you can run with model_predict (use the slug as modelId):');
+      for (const m of models.slice(0, 25)) {
+        const labels = m.labels?.length ? ` → ${m.labels.join('/')}` : '';
+        parts.push(`- ${m.slug} — ${m.modality}/${m.taskType}${labels}`);
+      }
+    }
+  } catch {
+    /* no local models / store unavailable — skip */
+  }
+
   parts.push('\nDecide what actions to take based on your personality and the current context.');
   parts.push('IMPORTANT: If you already commented on a post, only comment again if someone ELSE has replied since your last comment. Do not leave multiple unanswered comments on the same post.');
   parts.push('If there is no new activity and no one has responded to your previous comments, do nothing — that is a valid choice.');

package/src/commands/dataset.js

@@ -16,6 +16,7 @@ import {
   readManifest,
   datasetExists,
   appendRows,
+  ingestAsset,
   readRows,
   freezeVersion,
 } from '../utils/dataset-workspace.js';
@@ -83,8 +84,20 @@ export async function datasetAppendCommand(options) {
     if (!slug) throw new Error('--dataset <slug> is required.');
     if (!datasetExists(slug)) throw new Error(`Dataset "${slug}" not found.`);
 
+    const manifest = readManifest(slug);
+
     let rows;
-    if (options.file) {
+    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}").`);
+      }
+      const asset = ingestAsset(slug, options.image, 'image');
+      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);
+      rows = [row];
+    } else if (options.file) {
       rows = readRowsFromFile(options.file);
     } else if (options.text !== undefined || options.features !== undefined) {
       const row = { split: options.split || 'train' };
@@ -93,7 +106,7 @@ export async function datasetAppendCommand(options) {
       if (options.target !== undefined) row.target = Number(options.target);
       rows = [row];
     } else {
-      throw new Error('Provide either --file <jsonl> or --text/--features (with --label or --target).');
+      throw new Error('Provide --image <path> (image datasets), --file <jsonl>, or --text/--features (with --label or --target).');
     }
 
     const spinner = options.json ? null : villageSpinner('Appending rows...').start();
@@ -132,7 +145,10 @@ export async function datasetShowCommand(slug, options) {
     if (sample.length) {
       console.log(brand.cream(`\n  sample (${sample.length}):`));
       for (const r of sample) {
-        const feat = typeof r.features === 'string' ? truncate(r.features, 50) : JSON.stringify(r.features);
+        const feat =
+          typeof r.features === 'string' ? truncate(r.features, 50)
+          : r.features?.path ? `📎 ${r.features.path}`
+          : JSON.stringify(r.features);
         const tgt = r.label != null ? `label=${r.label}` : `target=${r.target}`;
         console.log(`    [${r.split}] ${tgt}  ${brand.teal(feat)}`);
       }

package/src/commands/model.js

@@ -57,7 +57,8 @@ 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}`);
-    info(`  test it:  myvillage model predict ${manifest.slug} --input "..."`);
+    const testFlag = manifest.modality === 'image' ? '--image <path>' : '--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');
     else error(e.message);
@@ -121,10 +122,15 @@ export async function modelShowCommand(slug, options) {
 export async function modelPredictCommand(slug, options) {
   try {
     if (!modelExists(slug)) throw new Error(`Model "${slug}" not found.`);
-    if (options.input === undefined) throw new Error('--input <value> is required.');
     const record = readModelManifest(slug);
+    // Image models take a file path (--image); text/tabular take --input.
+    const isImage = record.modality === 'image';
+    const input = isImage ? options.image : options.input;
+    if (input === undefined) {
+      throw new Error(isImage ? '--image <path> is required for image models.' : '--input <value> is required.');
+    }
     const model = await loadModel(slug);
-    const result = predictWithModel(model, record, options.input);
+    const result = await predictWithModel(model, record, input);
     if (options.json) {
       console.log(JSON.stringify(result, null, 2));
       return;

package/src/index.js

@@ -877,6 +877,7 @@ export function run() {
     .description('Append labeled example(s) to a dataset')
     .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('--text <text>', 'Single-row text features')
     .option('--features <value>', 'Single-row features (string, or numeric vector for tabular)')
     .option('--label <label>', 'Class label (classification)')
@@ -928,7 +929,8 @@ export function run() {
   modelCmd
     .command('predict <slug>')
     .description('Run a prediction with a trained model')
-    .requiredOption('--input <value>', 'Input: text, or a comma-separated numeric vector for tabular')
+    .option('--input <value>', 'Input: text, or a comma-separated numeric vector for tabular')
+    .option('--image <path>', 'Image file to classify (image models)')
     .option('--json', 'Output raw JSON')
     .action(modelPredictCommand);
 

package/src/utils/dataset-workspace.js

@@ -25,8 +25,9 @@ import {
   appendFileSync,
   readdirSync,
   copyFileSync,
+  statSync,
 } from 'fs';
-import { join } from 'path';
+import { join, extname, basename } from 'path';
 import { randomUUID } from 'crypto';
 import { getConfigDir } from './config.js';
 
@@ -54,6 +55,46 @@ export function getAssetsDir(slug) {
   return dir;
 }
 
+/** Resolve an AssetRef's dataset-relative path to an absolute path on disk. */
+export function getAssetPath(slug, relPath) {
+  return join(getAssetsDir(slug), relPath);
+}
+
+const IMAGE_MIME = {
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+};
+const AUDIO_MIME = { '.wav': 'audio/wav' };
+
+/**
+ * Copy a media file into a dataset's assets/ dir and return an AssetRef.
+ * Raw media stays local (never leaves the machine) — this is the on-disk side
+ * of image/audio collection. The stored path is relative to assets/ so the
+ * dataset dir stays portable.
+ *
+ * @param {string} slug
+ * @param {string} srcPath  absolute path to the source media file
+ * @param {'image'|'audio'} kind
+ * @returns {{kind:string, path:string, mime?:string, bytes:number}}
+ */
+export function ingestAsset(slug, srcPath, kind) {
+  if (!existsSync(srcPath)) throw new Error(`File not found: ${srcPath}`);
+  const ext = extname(srcPath).toLowerCase();
+  const mimeTable = kind === 'audio' ? AUDIO_MIME : IMAGE_MIME;
+  const mime = mimeTable[ext];
+  if (!mime) {
+    const ok = Object.keys(mimeTable).join(', ');
+    throw new Error(`Unsupported ${kind} type "${ext}". Supported: ${ok}.`);
+  }
+  // Unique, collision-proof filename; keep a hint of the original name.
+  const stem = basename(srcPath, ext).replace(/[^a-z0-9_-]+/gi, '-').slice(0, 32) || kind;
+  const fileName = `${stem}-${randomUUID().slice(0, 8)}${ext}`;
+  const destAbs = join(getAssetsDir(slug), fileName);
+  copyFileSync(srcPath, destAbs);
+  return { kind, path: fileName, mime, bytes: statSync(destAbs).size };
+}
+
 function getManifestPath(slug) {
   return join(getDatasetDir(slug), 'manifest.json');
 }
@@ -214,6 +255,17 @@ function normalizeRow(raw, manifest) {
   if (raw.features === undefined || raw.features === null) {
     throw new Error('Each row needs a "features" value.');
   }
+  // image/audio rows carry an AssetRef {kind, path}; the caller ingests the
+  // file (see ingestAsset) before appending, so by here features is the ref.
+  if (manifest.modality === 'image' || manifest.modality === 'audio') {
+    const f = raw.features;
+    if (typeof f !== 'object' || !f.path) {
+      throw new Error(
+        `${manifest.modality} rows need an ingested asset reference {kind, path}. ` +
+          'Append with --image <path> (CLI) or pass an image path to the tool.',
+      );
+    }
+  }
   const row = { features: raw.features, split };
   if (manifest.taskType === 'classification') {
     if (raw.label == null || String(raw.label).length === 0) {

package/src/utils/image-backbone.js

@@ -0,0 +1,144 @@
+/**
+ * Image feature-extractor for the Studio "Lab" pillar.
+ *
+ * Turns an image file into a fixed-length embedding using a MobileNetV3-Small
+ * backbone that is **bundled inside this package** (vendor/backbones/) and
+ * loaded from disk — never downloaded — so the Studio stays "the only thing you
+ * install" (see ed-platform docs/architecture/studio-models-pillar.md §0b, §13).
+ *
+ * Pipeline: decode (pure-JS jpeg-js / pngjs, no native binary) → RGB tensor →
+ * resize 224×224 → normalize to [0,1] → MobileNetV3-Small → 1024-d embedding.
+ *
+ * The embedding then feeds the SAME dense head the text/tabular trainer uses;
+ * image only adds this featurization step. tfjs is imported lazily so listing
+ * datasets/models never pulls the heavy runtime in.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname, extname } from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+// CommonJS interop for the pure-JS decoders (this module is ESM).
+const _require = createRequire(import.meta.url);
+function requirePkg(name) {
+  return _require(name);
+}
+
+export const BACKBONE_ID = 'mobilenet-v3-small';
+export const INPUT_SIZE = 224;
+export const EMBED_DIM = 1024;
+
+const BACKBONE_DIR = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  'vendor',
+  'backbones',
+  BACKBONE_ID,
+);
+
+let _backbonePromise = null;
+
+/**
+ * A tf.io.IOHandler that reads the vendored GraphModel (model.json + weight
+ * shards) straight off disk. We can't use tf.loadGraphModel('file://…') because
+ * the bundled pure-JS @tensorflow/tfjs has no file:// handler (that lives in
+ * tfjs-node); reading the artifacts ourselves keeps it native-binary-free —
+ * the same trick model-workspace.js uses for saved models.
+ */
+function diskGraphHandler(dir) {
+  return {
+    load: async () => {
+      const manifestPath = join(dir, 'model.json');
+      if (!existsSync(manifestPath)) {
+        throw new Error(
+          `Bundled image backbone not found at ${dir}. The MobileNet 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);
+      // Slice to the exact backing range so tfjs sees a clean ArrayBuffer.
+      const weightData = concat.buffer.slice(
+        concat.byteOffset,
+        concat.byteOffset + concat.byteLength,
+      );
+      return {
+        modelTopology: j.modelTopology,
+        weightSpecs: specs,
+        weightData,
+        format: j.format,
+        generatedBy: j.generatedBy,
+        convertedBy: j.convertedBy,
+      };
+    },
+  };
+}
+
+/** Load (once) and cache the bundled backbone GraphModel. */
+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));
+    })();
+  }
+  return _backbonePromise;
+}
+
+/** Decode an image file to {width, height, data:RGBA Uint8Array} (pure JS). */
+function decodeImage(path) {
+  if (!existsSync(path)) throw new Error(`Image not found: ${path}`);
+  const buf = readFileSync(path);
+  const ext = extname(path).toLowerCase();
+  if (ext === '.png') {
+    // Lazy require keeps these decoders out of the hot path for text/tabular.
+    const { PNG } = requirePkg('pngjs');
+    const png = PNG.sync.read(buf);
+    return { width: png.width, height: png.height, data: png.data };
+  }
+  if (ext === '.jpg' || ext === '.jpeg') {
+    const jpeg = requirePkg('jpeg-js');
+    const img = jpeg.decode(buf, { useTArray: true, maxMemoryUsageInMB: 512 });
+    return { width: img.width, height: img.height, data: img.data };
+  }
+  throw new Error(`Unsupported image type "${ext}". Use .jpg, .jpeg, or .png.`);
+}
+
+/**
+ * Embed a single image file → Float array of length EMBED_DIM (1024).
+ * Used by both training (featurize) and prediction (featurizeOne).
+ */
+export async function embedImage(path) {
+  const tf = await import('@tensorflow/tfjs');
+  const model = await getBackbone();
+  const { width, height, data } = decodeImage(path);
+
+  return tf.tidy(() => {
+    // RGBA → RGB float [0,1], shaped [h, w, 3], resized to the backbone input.
+    const rgb = new Float32Array(width * height * 3);
+    for (let i = 0, j = 0; i < data.length; i += 4, j += 3) {
+      rgb[j] = data[i] / 255;
+      rgb[j + 1] = data[i + 1] / 255;
+      rgb[j + 2] = data[i + 2] / 255;
+    }
+    const img = tf.tensor3d(rgb, [height, width, 3]);
+    const resized = tf.image.resizeBilinear(img, [INPUT_SIZE, INPUT_SIZE]);
+    const batched = resized.expandDims(0); // [1, 224, 224, 3]
+    const out = model.predict(batched); // [1, 1024]
+    return Array.from(out.dataSync());
+  });
+}
+
+/** Featurization params persisted in the model record for image models. */
+export function imageFeaturization() {
+  return { modality: 'image', dim: EMBED_DIM, backbone: BACKBONE_ID, inputSize: INPUT_SIZE };
+}

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/src/utils/model-workspace.js

@@ -12,10 +12,13 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync } from 'fs';
 import { join } from 'path';
 import { randomUUID } from 'crypto';
-import * as tf from '@tensorflow/tfjs';
 import { getConfigDir } from './config.js';
 import { slugify } from './dataset-workspace.js';
 
+// tfjs is loaded lazily (only in save/load) so listing/reading model manifests —
+// e.g. when injecting "available models" into the agent loop's context — never
+// pulls the heavy tfjs runtime into agent startup.
+
 const MODELS_DIR_NAME = 'models';
 export const MODEL_SCHEMA_VERSION = '1.0.0';
 
@@ -71,6 +74,7 @@ export async function saveModel(name, { model, record, datasetSlug, datasetVersi
   const dir = getModelDir(slug);
   mkdirSync(dir, { recursive: true });
 
+  const tf = await import('@tensorflow/tfjs');
   let modelTopology, weightSpecs, weightB64;
   await model.save(
     tf.io.withSaveHandler(async (artifacts) => {
@@ -104,6 +108,7 @@ export async function saveModel(name, { model, record, datasetSlug, datasetVersi
 
 /** Load a saved tf model back into memory (for predict). */
 export async function loadModel(slug) {
+  const tf = await import('@tensorflow/tfjs');
   const dir = getModelDir(slug);
   if (!existsSync(join(dir, 'model.json'))) throw new Error(`Model "${slug}" not found.`);
   const { modelTopology, weightSpecs } = JSON.parse(readFileSync(join(dir, 'model.json'), 'utf-8'));

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)