@myvillage/cli 1.68.0 → 1.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "1.68.0",
+  "version": "1.70.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {
@@ -30,6 +30,7 @@
     "@ai-sdk/anthropic": "^3.0.78",
     "@ai-sdk/mcp": "^1.0.42",
     "@ai-sdk/openai": "^3.0.33",
+    "@tensorflow/tfjs": "^4.22.0",
     "ai": "^6.0.0",
     "axios": "^1.6.2",
     "chalk": "^5.3.0",

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

@@ -0,0 +1,30 @@
+/**
+ * Registry of native built-in agent tools — plain data only (no `ai`/`zod`/
+ * tfjs imports), so the Studio can read tool metadata cheaply to show built-ins
+ * in its tool palette / allowlist alongside MCP tools.
+ *
+ * Single source of truth for built-in tool name + description + tier:
+ *   - the agent loop's builtin-tools.js pulls descriptions from here
+ *   - the Studio (via cli-bridge) imports this to list selectable built-ins
+ *
+ * `builtin: true` marks them so the UI can distinguish them from MCP tools.
+ * Permission `tier` reuses the notification send-tier model.
+ */
+
+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 ' +
+  'regression provide a numeric `target`. Data stays local; provenance ' +
+  'is recorded automatically.';
+
+/** All native built-in tools available to every local agent. */
+export const BUILTIN_TOOL_DEFS = [
+  {
+    name: 'dataset_append',
+    description: DATASET_APPEND_DESCRIPTION,
+    tier: 'villager',
+    builtin: true,
+  },
+  // model_predict lands here when L3 (use a trained model as a tool) ships.
+];

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

@@ -15,6 +15,9 @@
 import { tool } from 'ai';
 import { z } from 'zod';
 import { appendRows, datasetExists } from '../utils/dataset-workspace.js';
+import { DATASET_APPEND_DESCRIPTION } from './builtin-tools-registry.js';
+
+export { BUILTIN_TOOL_DEFS } from './builtin-tools-registry.js';
 
 /**
  * Build the native built-in tools for an agent.
@@ -25,12 +28,7 @@ import { appendRows, datasetExists } from '../utils/dataset-workspace.js';
 export function getBuiltinTools(agentName, config) {
   return {
     dataset_append: tool({
-      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 ' +
-        'regression provide a numeric `target`. Data stays local; provenance ' +
-        'is recorded automatically.',
+      description: DATASET_APPEND_DESCRIPTION,
       inputSchema: z.object({
         datasetId: z.string().describe('Slug of the local dataset to append to'),
         rows: z

package/src/commands/model.js

@@ -0,0 +1,143 @@
+/**
+ * `myvillage model *` — train and use local models for the Studio Lab.
+ *
+ * Training runs in-process on TF.js (CPU). This is the single training engine;
+ * the Studio drives these same commands and streams the progress they emit
+ * (with --json, one progress line per epoch, then a final result object).
+ */
+import { brand, success, error, info, header, villageSpinner } from '../utils/brand.js';
+import { readManifest as readDatasetManifest, datasetExists } from '../utils/dataset-workspace.js';
+import { trainModel, predictWithModel, TRAINABLE_MODALITIES } from '../utils/model-trainer.js';
+import { saveModel, listModels, readModelManifest, modelExists, loadModel } from '../utils/model-workspace.js';
+
+// ── train ──────────────────────────────────────────────
+
+export async function modelTrainCommand(options) {
+  try {
+    const datasetSlug = options.dataset;
+    if (!datasetSlug) throw new Error('--dataset <slug> is required.');
+    if (!datasetExists(datasetSlug)) throw new Error(`Dataset "${datasetSlug}" not found.`);
+    const ds = readDatasetManifest(datasetSlug);
+    if (!TRAINABLE_MODALITIES.includes(ds.modality)) {
+      throw new Error(
+        `Training "${ds.modality}" datasets is coming soon — v1 supports ${TRAINABLE_MODALITIES.join(' and ')}.`,
+      );
+    }
+    const name = options.name || `${ds.name} model`;
+    const epochs = options.epochs ? parseInt(options.epochs, 10) : 40;
+
+    // Progress: stream JSON lines when --json (Studio parses these); else spinner.
+    const spinner = options.json ? null : villageSpinner('Training…').start();
+    const onProgress = (p) => {
+      if (options.json) {
+        process.stdout.write(JSON.stringify({ type: 'progress', ...p }) + '\n');
+      } else {
+        const metric =
+          p.valAccuracy != null ? `val acc ${(p.valAccuracy * 100).toFixed(1)}%`
+          : p.valMae != null ? `val MAE ${p.valMae}`
+          : `loss ${p.loss}`;
+        spinner.text = `Training… epoch ${p.epoch}/${p.totalEpochs} · ${metric}`;
+      }
+    };
+
+    const { model, record } = await trainModel(datasetSlug, ds, { epochs, onProgress });
+    const manifest = await saveModel(name, {
+      model,
+      record,
+      datasetSlug,
+      datasetVersion: ds.currentVersion || 0,
+    });
+    if (spinner) spinner.stop();
+
+    if (options.json) {
+      process.stdout.write(JSON.stringify({ type: 'result', model: manifest }) + '\n');
+      return;
+    }
+    success(`Trained "${manifest.name}" (${manifest.slug}) from ${record.examplesUsed} examples`);
+    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 "..."`);
+  } catch (e) {
+    if (options.json) process.stdout.write(JSON.stringify({ type: 'error', error: e.message }) + '\n');
+    else error(e.message);
+    process.exitCode = 1;
+  }
+}
+
+// ── list ───────────────────────────────────────────────
+
+export async function modelListCommand(options) {
+  try {
+    const models = listModels();
+    if (options.json) {
+      console.log(JSON.stringify(models, null, 2));
+      return;
+    }
+    if (models.length === 0) {
+      info('No models yet. Train one with: myvillage model train --dataset <slug>');
+      return;
+    }
+    header('Local models');
+    for (const m of models) {
+      const score =
+        m.metrics?.accuracy != null ? `${(m.metrics.accuracy * 100).toFixed(0)}% acc`
+        : m.metrics?.mae != null ? `MAE ${m.metrics.mae}`
+        : '—';
+      console.log(`  ${brand.gold(m.slug.padEnd(28))} ${String(m.taskType).padEnd(15)} ${String(score).padStart(10)}  ← ${m.datasetSlug}`);
+    }
+    console.log('');
+  } catch (e) {
+    error(e.message);
+    process.exitCode = 1;
+  }
+}
+
+// ── show ───────────────────────────────────────────────
+
+export async function modelShowCommand(slug, options) {
+  try {
+    const m = readModelManifest(slug);
+    if (!m) throw new Error(`Model "${slug}" not found.`);
+    if (options.json) {
+      console.log(JSON.stringify(m, null, 2));
+      return;
+    }
+    header(`${m.name} (${m.slug})`);
+    info(`  task: ${m.taskType} · modality: ${m.modality} · trained on: ${m.datasetSlug} (v${m.datasetVersion})`);
+    info(`  examples: ${m.examplesUsed} · format: ${m.format}`);
+    if (m.metrics?.accuracy != null) info(`  accuracy: ${(m.metrics.accuracy * 100).toFixed(1)}% over ${m.metrics.classes} classes`);
+    if (m.metrics?.mae != null) info(`  MAE: ${m.metrics.mae} · R²: ${m.metrics.r2}`);
+    if (m.labels?.length) info(`  labels: ${m.labels.join(', ')}`);
+    console.log('');
+  } catch (e) {
+    error(e.message);
+    process.exitCode = 1;
+  }
+}
+
+// ── predict ────────────────────────────────────────────
+
+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);
+    const model = await loadModel(slug);
+    const result = predictWithModel(model, record, options.input);
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    if (result.label != null) {
+      success(`Prediction: ${result.label}`);
+      const ranked = Object.entries(result.scores).sort((a, b) => b[1] - a[1]);
+      for (const [label, score] of ranked) info(`  ${label}: ${(score * 100).toFixed(1)}%`);
+    } else {
+      success(`Prediction: ${result.score}`);
+    }
+  } catch (e) {
+    error(e.message);
+    process.exitCode = 1;
+  }
+}

package/src/index.js

@@ -125,6 +125,12 @@ import {
   datasetShowCommand,
   datasetFreezeCommand,
 } from './commands/dataset.js';
+import {
+  modelTrainCommand,
+  modelListCommand,
+  modelShowCommand,
+  modelPredictCommand,
+} from './commands/model.js';
 
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
@@ -893,5 +899,38 @@ export function run() {
     .option('--json', 'Output raw JSON')
     .action(datasetFreezeCommand);
 
+  // ── Studio Lab: model training (local, TF.js CPU engine) ───────────────
+  const modelCmd = program
+    .command('model')
+    .description('Train and use local models for the Studio Lab (runs on your machine)');
+
+  modelCmd
+    .command('train')
+    .description('Train a model from a local dataset (tabular or text in v1)')
+    .requiredOption('--dataset <slug>', 'Dataset slug to train on')
+    .option('--name <name>', 'Name for the resulting model')
+    .option('--epochs <n>', 'Training epochs (default 40)')
+    .option('--json', 'Stream progress as JSON lines, then a final result object')
+    .action(modelTrainCommand);
+
+  modelCmd
+    .command('list')
+    .description('List local trained models')
+    .option('--json', 'Output raw JSON')
+    .action(modelListCommand);
+
+  modelCmd
+    .command('show <slug>')
+    .description('Show a model: task, metrics, training dataset')
+    .option('--json', 'Output raw JSON')
+    .action(modelShowCommand);
+
+  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('--json', 'Output raw JSON')
+    .action(modelPredictCommand);
+
   program.parse();
 }

package/src/utils/model-trainer.js

@@ -0,0 +1,249 @@
+/**
+ * Local model trainer for the Studio "Lab" pillar.
+ *
+ * Runs IN NODE on TensorFlow.js (CPU backend) — no GPU, no native binary, no
+ * downloads — so it works headless from `myvillage model train` AND when the
+ * 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):
+ *   - 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.
+ *
+ * Transfer-learning-style split: featurize once, then train a small head. The
+ * featurization params travel in the model record so predict() needs no data.
+ */
+import * as tf from '@tensorflow/tfjs';
+import { readRows } from './dataset-workspace.js';
+
+const TEXT_DIM = 1024;
+export const TRAINABLE_MODALITIES = ['tabular', 'text'];
+
+// ── 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;
+}
+
+function toNumericVector(features) {
+  if (Array.isArray(features)) return features.map(Number);
+  if (typeof features === 'string') {
+    return features.split(',').map((n) => Number(n.trim()));
+  }
+  throw new Error('Tabular features must be a numeric vector.');
+}
+
+/** Build the feature matrix + the featurization params to persist. */
+function featurize(rows, modality) {
+  if (modality === 'text') {
+    return { X: rows.map((r) => vectorizeText(r.features)), featurization: { modality, dim: TEXT_DIM } };
+  }
+  // tabular: standardize each column (store mean/std for predict)
+  const raw = rows.map((r) => toNumericVector(r.features));
+  const dim = raw[0].length;
+  if (raw.some((v) => v.length !== dim)) {
+    throw new Error('All tabular rows must have the same number of features.');
+  }
+  const mean = new Array(dim).fill(0);
+  const std = new Array(dim).fill(0);
+  for (const v of raw) for (let j = 0; j < dim; j++) mean[j] += v[j];
+  for (let j = 0; j < dim; j++) mean[j] /= raw.length;
+  for (const v of raw) for (let j = 0; j < dim; j++) std[j] += (v[j] - mean[j]) ** 2;
+  for (let j = 0; j < dim; j++) std[j] = Math.sqrt(std[j] / raw.length) || 1;
+  const X = raw.map((v) => v.map((x, j) => (x - mean[j]) / std[j]));
+  return { X, featurization: { modality, dim, mean, std } };
+}
+
+/** Featurize a single input the same way (for predict). */
+export function featurizeOne(input, featurization) {
+  if (featurization.modality === 'text') return vectorizeText(input);
+  const v = toNumericVector(input);
+  return v.map((x, j) => (x - featurization.mean[j]) / (featurization.std[j] || 1));
+}
+
+// ── Model ──────────────────────────────────────────────
+
+function buildModel(inputDim, task, numClasses) {
+  const model = tf.sequential();
+  model.add(tf.layers.dense({ inputShape: [inputDim], units: 32, activation: 'relu' }));
+  model.add(tf.layers.dropout({ rate: 0.2 }));
+  if (task === 'classification') {
+    model.add(tf.layers.dense({ units: numClasses, activation: 'softmax' }));
+    // one-hot targets + categoricalCrossentropy (avoids int32/sparse dtype traps)
+    model.compile({ optimizer: tf.train.adam(0.01), loss: 'categoricalCrossentropy', metrics: ['accuracy'] });
+  } else {
+    model.add(tf.layers.dense({ units: 1 }));
+    model.compile({ optimizer: tf.train.adam(0.01), loss: 'meanSquaredError', metrics: ['mae'] });
+  }
+  return model;
+}
+
+// ── Train ──────────────────────────────────────────────
+
+/**
+ * Train a model from a local dataset's working set.
+ * @returns {{ model: tf.LayersModel, record: object }} record holds everything
+ *          predict() needs (featurization, labels/target stats, metrics).
+ */
+export async function trainModel(slug, manifest, { epochs = 40, onProgress } = {}) {
+  await tf.setBackend('cpu');
+  await tf.ready();
+
+  if (!TRAINABLE_MODALITIES.includes(manifest.modality)) {
+    throw new Error(
+      `Training for "${manifest.modality}" datasets is coming soon — v1 supports ${TRAINABLE_MODALITIES.join(' and ')}.`,
+    );
+  }
+  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 } = featurize(rows, manifest.modality);
+  const inputDim = X[0].length;
+
+  // Build targets: one-hot rows (classification) or standardized scalars (regression)
+  let labels = [], targetMean = null, targetStd = null, numClasses = 0;
+  let Y;
+  if (task === 'classification') {
+    labels = [...new Set(rows.map((r) => String(r.label)))].sort();
+    if (labels.length < 2) throw new Error('Classification needs at least 2 distinct labels.');
+    const idx = new Map(labels.map((l, i) => [l, i]));
+    numClasses = labels.length;
+    Y = rows.map((r) => {
+      const o = new Array(numClasses).fill(0);
+      o[idx.get(String(r.label))] = 1;
+      return o;
+    });
+  } else {
+    const t = rows.map((r) => Number(r.target));
+    targetMean = t.reduce((a, b) => a + b, 0) / t.length;
+    targetStd = Math.sqrt(t.reduce((a, b) => a + (b - targetMean) ** 2, 0) / t.length) || 1;
+    Y = t.map((v) => (v - targetMean) / targetStd);
+  }
+
+  // train/val split in plain JS (explicit val rows, else hold out the last ~20%)
+  const explicitVal = rows.map((r, i) => (r.split === 'val' ? i : -1)).filter((i) => i >= 0);
+  let valSet;
+  if (explicitVal.length >= 2 && explicitVal.length < rows.length) {
+    valSet = new Set(explicitVal);
+  } else {
+    const n = Math.max(1, Math.floor(rows.length * 0.2));
+    valSet = new Set(rows.map((_, i) => i).slice(rows.length - n));
+  }
+  const trI = [], vaI = [];
+  rows.forEach((_, i) => (valSet.has(i) ? vaI : trI).push(i));
+  if (trI.length === 0) { trI.push(...vaI); vaI.length = 0; }
+
+  const pick = (arr, idxs) => idxs.map((i) => arr[i]);
+  const mkY = (vals) => (task === 'classification' ? tf.tensor2d(vals) : tf.tensor1d(vals));
+  const trainXs = tf.tensor2d(pick(X, trI));
+  const trainYs = mkY(pick(Y, trI));
+  const valXs = vaI.length ? tf.tensor2d(pick(X, vaI)) : null;
+  const valYs = vaI.length ? mkY(pick(Y, vaI)) : null;
+
+  const model = buildModel(inputDim, task, numClasses);
+  const fitConfig = {
+    epochs,
+    shuffle: true,
+    callbacks: {
+      onEpochEnd: (epoch, logs) => {
+        onProgress?.({
+          epoch: epoch + 1,
+          totalEpochs: epochs,
+          loss: round(logs.loss),
+          valLoss: round(logs.val_loss),
+          accuracy: round(logs.acc ?? logs.accuracy),
+          valAccuracy: round(logs.val_acc ?? logs.val_accuracy),
+          mae: round(logs.mae),
+          valMae: round(logs.val_mae),
+        });
+      },
+    },
+  };
+  if (valXs) fitConfig.validationData = [valXs, valYs];
+  await model.fit(trainXs, trainYs, fitConfig);
+
+  // Metrics over the eval set (val if we have one, else the training set).
+  const evalXs = valXs || trainXs;
+  const evalYs = valYs || trainYs;
+  const metrics = computeMetrics(model, evalXs, evalYs, task, labels, targetMean, targetStd);
+  trainXs.dispose(); trainYs.dispose();
+  if (valXs) { valXs.dispose(); valYs.dispose(); }
+
+  const record = {
+    modality: manifest.modality,
+    taskType: task,
+    inputDim,
+    featurization,
+    labels: labels ?? [],
+    targetMean: targetMean ?? null,
+    targetStd: targetStd ?? null,
+    metrics,
+    hyperparams: { epochs, optimizer: 'adam', learningRate: 0.01 },
+    examplesUsed: rows.length,
+  };
+  return { model, record };
+}
+
+function computeMetrics(model, xs, ys, task, labels, targetMean, targetStd) {
+  return tf.tidy(() => {
+    const pred = model.predict(xs);
+    if (task === 'classification') {
+      const yhat = pred.argMax(1);
+      const ytrue = ys.argMax(1); // ys is one-hot
+      const acc = yhat.equal(ytrue).mean().arraySync();
+      return { accuracy: round(acc), classes: labels.length };
+    }
+    // regression: de-standardize, compute MAE + R²
+    const yhat = pred.flatten().mul(targetStd).add(targetMean);
+    const ytrue = ys.mul(targetStd).add(targetMean);
+    const mae = yhat.sub(ytrue).abs().mean().arraySync();
+    const ssRes = yhat.sub(ytrue).square().sum().arraySync();
+    const yMean = ytrue.mean().arraySync();
+    const ssTot = ytrue.sub(yMean).square().sum().arraySync();
+    return { mae: round(mae), r2: round(ssTot > 0 ? 1 - ssRes / ssTot : 0) };
+  });
+}
+
+/** Run a prediction with an already-loaded model + its record. */
+export function predictWithModel(model, record, input) {
+  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());
+      let best = 0;
+      for (let i = 1; i < scores.length; i++) if (scores[i] > scores[best]) best = i;
+      const byLabel = {};
+      record.labels.forEach((l, i) => (byLabel[l] = round(scores[i])));
+      return { label: record.labels[best], scores: byLabel };
+    }
+    const z = out.dataSync()[0];
+    return { score: round(z * record.targetStd + record.targetMean) };
+  });
+}
+
+function round(n) {
+  return n == null || Number.isNaN(n) ? undefined : Math.round(n * 1e4) / 1e4;
+}

package/src/utils/model-workspace.js

@@ -0,0 +1,113 @@
+/**
+ * Local trained-model store for the Studio "Lab" pillar.
+ *
+ * Models live under ~/.myvillage/models/<slug>/ — local-only, like datasets.
+ *   manifest.json   # TrainedModelRecord (modality, task, metrics, featurization…)
+ *   model.json      # tfjs topology + weight specs
+ *   weights.b64     # base64 weight data
+ *
+ * Save/load go through TF.js's in-memory IO handlers (no tfjs-node needed),
+ * so this stays pure-JS and matches the trainer's CPU runtime.
+ */
+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';
+
+const MODELS_DIR_NAME = 'models';
+export const MODEL_SCHEMA_VERSION = '1.0.0';
+
+export function getModelsRootDir() {
+  const dir = join(getConfigDir(), MODELS_DIR_NAME);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function getModelDir(slug) {
+  return join(getModelsRootDir(), slug);
+}
+
+function manifestPath(slug) {
+  return join(getModelDir(slug), 'manifest.json');
+}
+
+export function modelExists(slug) {
+  return existsSync(manifestPath(slug));
+}
+
+export function readModelManifest(slug) {
+  const p = manifestPath(slug);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function listModels() {
+  const root = getModelsRootDir();
+  return readdirSync(root, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => readModelManifest(e.name))
+    .filter(Boolean);
+}
+
+export function deleteModel(slug) {
+  rmSync(getModelDir(slug), { recursive: true, force: true });
+}
+
+/**
+ * Persist a trained model + its record.
+ * @param {string} name human-readable model name (slug derived from it)
+ * @param {object} opts { model: tf.LayersModel, record, datasetSlug, datasetVersion }
+ * @returns {object} the saved manifest
+ */
+export async function saveModel(name, { model, record, datasetSlug, datasetVersion }) {
+  const slug = slugify(name);
+  if (!slug) throw new Error('Could not derive a slug from the model name.');
+  const dir = getModelDir(slug);
+  mkdirSync(dir, { recursive: true });
+
+  let modelTopology, weightSpecs, weightB64;
+  await model.save(
+    tf.io.withSaveHandler(async (artifacts) => {
+      modelTopology = artifacts.modelTopology;
+      weightSpecs = artifacts.weightSpecs;
+      weightB64 = Buffer.from(artifacts.weightData).toString('base64');
+      return { modelArtifactsInfo: { dateSaved: new Date(), modelTopologyType: 'JSON' } };
+    }),
+  );
+  writeFileSync(join(dir, 'model.json'), JSON.stringify({ modelTopology, weightSpecs }));
+  writeFileSync(join(dir, 'weights.b64'), weightB64);
+
+  const ts = new Date().toISOString();
+  const manifest = {
+    schemaVersion: MODEL_SCHEMA_VERSION,
+    id: randomUUID(),
+    slug,
+    name,
+    datasetSlug,
+    datasetVersion: datasetVersion ?? 0,
+    format: 'tfjs',
+    artifacts: ['model.json', 'weights.b64'],
+    ...record,
+    status: 'ready',
+    createdAt: ts,
+    updatedAt: ts,
+  };
+  writeFileSync(manifestPath(slug), JSON.stringify(manifest, null, 2));
+  return manifest;
+}
+
+/** Load a saved tf model back into memory (for predict). */
+export async function loadModel(slug) {
+  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'));
+  const buf = Buffer.from(readFileSync(join(dir, 'weights.b64'), 'utf-8'), 'base64');
+  const weightData = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  return tf.loadLayersModel(tf.io.fromMemory({ modelTopology, weightSpecs, weightData }));
+}