@myvillage/cli 1.72.0 → 1.74.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "1.72.0",
+  "version": "1.74.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/commands/dataset.js

@@ -16,8 +16,11 @@ import {
   readManifest,
   datasetExists,
   appendRows,
+  ingestAsset,
   readRows,
   freezeVersion,
+  deleteRow,
+  updateRow,
 } from '../utils/dataset-workspace.js';
 
 // ── create ─────────────────────────────────────────────
@@ -83,8 +86,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 +108,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 +147,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)}`);
       }
@@ -160,6 +178,55 @@ export async function datasetFreezeCommand(slug, options) {
   }
 }
 
+// ── delete a row ───────────────────────────────────────
+
+export async function datasetRowDeleteCommand(options) {
+  try {
+    const slug = options.dataset;
+    if (!slug) throw new Error('--dataset <slug> is required.');
+    if (!options.id) throw new Error('--id <rowId> is required.');
+    const result = deleteRow(slug, options.id);
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    success(`Deleted row ${options.id} from ${slug}`);
+    info(`  total: ${result.stats.rowCount} (train ${result.stats.bySplit.train} / val ${result.stats.bySplit.val})`);
+  } catch (e) {
+    error(e.message);
+    process.exitCode = 1;
+  }
+}
+
+// ── update a row ───────────────────────────────────────
+
+export async function datasetRowUpdateCommand(options) {
+  try {
+    const slug = options.dataset;
+    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);
+    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);
+    if (options.split !== undefined) updates.split = options.split;
+    if (Object.keys(updates).length === 0) {
+      throw new Error('Nothing to update. Pass --text/--features, --label, --target, or --split.');
+    }
+    const result = updateRow(slug, options.id, updates);
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    success(`Updated row ${options.id} in ${slug}`);
+    info(`  total: ${result.stats.rowCount} (train ${result.stats.bySplit.train} / val ${result.stats.bySplit.val})`);
+  } catch (e) {
+    error(e.message);
+    process.exitCode = 1;
+  }
+}
+
 // ── helpers ────────────────────────────────────────────
 
 function readRowsFromFile(path) {

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

@@ -124,6 +124,8 @@ import {
   datasetAppendCommand,
   datasetShowCommand,
   datasetFreezeCommand,
+  datasetRowDeleteCommand,
+  datasetRowUpdateCommand,
 } from './commands/dataset.js';
 import {
   modelTrainCommand,
@@ -877,6 +879,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)')
@@ -899,6 +902,27 @@ export function run() {
     .option('--json', 'Output raw JSON')
     .action(datasetFreezeCommand);
 
+  datasetCmd
+    .command('rm-row')
+    .description('Delete a row from the working set (by id)')
+    .requiredOption('--dataset <slug>', 'Target dataset slug')
+    .requiredOption('--id <rowId>', 'Row id to delete')
+    .option('--json', 'Output raw JSON')
+    .action(datasetRowDeleteCommand);
+
+  datasetCmd
+    .command('update-row')
+    .description('Update a working-set row (by id)')
+    .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('--label <label>', 'New class label (classification)')
+    .option('--target <number>', 'New numeric target (regression)')
+    .option('--split <split>', 'train | val')
+    .option('--json', 'Output raw JSON')
+    .action(datasetRowUpdateCommand);
+
   // ── Studio Lab: model training (local, TF.js CPU engine) ───────────────
   const modelCmd = program
     .command('model')
@@ -928,7 +952,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) {
@@ -256,6 +308,93 @@ export function readRows(slug, { version, split, limit } = {}) {
   return out;
 }
 
+// ── Edit / delete working-set rows ─────────────────────
+//
+// Only the working set (current.jsonl) is mutable; frozen versions (v*.jsonl)
+// are immutable snapshots and are never touched here. Both ops rewrite the
+// whole working-set file and recompute manifest stats from the result, so the
+// manifest can never drift from the rows on disk.
+
+/** Recompute manifest stats (rowCount / bySplit / byLabel) from a row array. */
+function recomputeStats(rows) {
+  const stats = emptyStats();
+  for (const row of rows) {
+    stats.rowCount += 1;
+    if (stats.bySplit[row.split] != null) stats.bySplit[row.split] += 1;
+    if (row.label != null) {
+      stats.byLabel[row.label] = (stats.byLabel[row.label] || 0) + 1;
+    }
+  }
+  return stats;
+}
+
+/** Overwrite the working set with `rows` and refresh the manifest's stats. */
+function writeWorkingSet(slug, manifest, rows) {
+  const body = rows.map((r) => JSON.stringify(r)).join('\n');
+  writeFileSync(getCurrentDataFile(slug), rows.length ? body + '\n' : '');
+  manifest.stats = recomputeStats(rows);
+  return writeManifest(slug, manifest);
+}
+
+/**
+ * Delete one working-set row by id. Throws if the id isn't in current.jsonl
+ * (e.g. it only exists in a frozen version, which can't be edited).
+ * @returns {{datasetId:string, deleted:string, stats:object}}
+ */
+export function deleteRow(slug, rowId) {
+  const manifest = readManifest(slug);
+  if (!manifest) throw new Error(`Dataset "${slug}" not found.`);
+  if (!rowId) throw new Error('A row id is required.');
+  const rows = readRows(slug);
+  const idx = rows.findIndex((r) => r.id === rowId);
+  if (idx === -1) {
+    throw new Error(`Row "${rowId}" not found in the working set of "${slug}".`);
+  }
+  const [removed] = rows.splice(idx, 1);
+  writeWorkingSet(slug, manifest, rows);
+  return { datasetId: slug, deleted: removed.id, stats: manifest.stats };
+}
+
+/**
+ * Update one working-set row by id. `updates` is a partial
+ * {features, label, target, split}; the merged row is re-validated against the
+ * dataset's modality/task (same rules as append). The row id is preserved and
+ * provenance.editedAt is stamped. Image/audio asset refs can't be edited here —
+ * delete the row and re-add the asset instead.
+ * @returns {{datasetId:string, updated:string, stats:object}}
+ */
+export function updateRow(slug, rowId, updates = {}) {
+  const manifest = readManifest(slug);
+  if (!manifest) throw new Error(`Dataset "${slug}" not found.`);
+  if (!rowId) throw new Error('A row id is required.');
+  const rows = readRows(slug);
+  const idx = rows.findIndex((r) => r.id === rowId);
+  if (idx === -1) {
+    throw new Error(`Row "${rowId}" not found in the working set of "${slug}".`);
+  }
+  const existing = rows[idx];
+  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 merged = normalizeRow(
+    {
+      features: updates.features !== undefined ? updates.features : existing.features,
+      split: updates.split !== undefined ? updates.split : existing.split,
+      label: updates.label !== undefined ? updates.label : existing.label,
+      target: updates.target !== undefined ? updates.target : existing.target,
+    },
+    manifest,
+  );
+  merged.id = existing.id;
+  merged.provenance = { ...(existing.provenance || {}), editedAt: nowISO() };
+  if (merged.label != null && !manifest.labels.includes(merged.label)) {
+    manifest.labels.push(merged.label);
+  }
+  rows[idx] = merged;
+  writeWorkingSet(slug, manifest, rows);
+  return { datasetId: slug, updated: merged.id, stats: manifest.stats };
+}
+
 // ── Freeze a version ───────────────────────────────────
 
 /**

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 };
+}