amv-train 0.0.0-stage → 3.0.0

package/lib/doctor.js

@@ -0,0 +1,149 @@
+/**
+ * Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+ */
+/**
+ * amv-train: Hardware & Training Capacity Diagnostic Doctor
+ * Production-grade heuristics with free RAM safety margin calculation.
+ * Open-Source under Apache License 2.0.
+ */
+
+'use strict';
+
+const os = require('os');
+const { spawnSync } = require('child_process');
+
+// Cache holds { cmd: string, resolvedAt: number } or null on failure
+// Cache TTL: 60 seconds — allows re-detection after pyenv / venv switches
+const PYTHON_CACHE_TTL_MS = 60_000;
+let _pythonCache = null;
+
+function resolvePythonCmd() {
+  const now = Date.now();
+
+  // Return cached result if fresh
+  if (_pythonCache !== null && (now - _pythonCache.resolvedAt) < PYTHON_CACHE_TTL_MS) {
+    return _pythonCache.cmd; // May be null if Python was not found at last check
+  }
+
+  const candidates = ['python3', 'python', 'py'];
+  for (const cmd of candidates) {
+    try {
+      const res = spawnSync(cmd, ['--version'], { stdio: 'pipe', encoding: 'utf-8' });
+      if (!res.error && res.status === 0) {
+        _pythonCache = { cmd, resolvedAt: now };
+        return cmd;
+      }
+    } catch (_) {}
+  }
+
+  // Cache the negative result with TTL so repeat calls don't thrash disk
+  _pythonCache = { cmd: null, resolvedAt: now };
+  return null;
+}
+
+/** Force re-detection on the next call (useful after Python installation). */
+function invalidatePythonCache() {
+  _pythonCache = null;
+}
+
+function runDoctor(options = {}) {
+  const isTermux = Boolean(process.env.TERMUX_VERSION || (process.env.PREFIX && process.env.PREFIX.includes('com.termux')));
+  const isAndroid = process.platform === 'android' || isTermux;
+  const totalRamMb = typeof os.totalmem === 'function' ? Math.round(os.totalmem() / (1024 * 1024)) : 4096;
+  const freeRamMb = typeof os.freemem === 'function' ? Math.round(os.freemem() / (1024 * 1024)) : 1024;
+  const cpus = os.cpus();
+  const cpuCores = Array.isArray(cpus) && cpus.length > 0 ? cpus.length : 4;
+
+  // Usable capacity = 60% of currently available free RAM (40% safety headroom)
+  const usableFreeRamMb = Math.max(0, Math.floor(freeRamMb * 0.6));
+
+  let tier;
+  let recLoraRank;
+  let recBatchSize;
+
+  if (usableFreeRamMb >= 4096) {
+    tier = 'High-End Mobile / Workstation';
+    recLoraRank = 16;
+    recBatchSize = 32;
+  } else if (usableFreeRamMb >= 1024) {
+    tier = 'Standard Mobile';
+    recLoraRank = 8;
+    recBatchSize = 16;
+  } else if (usableFreeRamMb >= 256) {
+    tier = 'Low-Memory Mobile';
+    recLoraRank = 4;
+    recBatchSize = 4;
+  } else {
+    tier = 'Critical Low-Memory (<256MB Free)';
+    recLoraRank = 2;
+    recBatchSize = 1;
+  }
+
+  const pyCmd = resolvePythonCmd();
+  let pythonAvailable = false;
+  let pythonVersion = 'Not Installed';
+  let termuxTrainPyInstalled = false;
+  let vulkanDetected = false;
+
+  if (pyCmd) {
+    try {
+      const pyVer = spawnSync(pyCmd, ['--version'], { stdio: 'pipe', encoding: 'utf-8' });
+      if (!pyVer.error && pyVer.status === 0) {
+        pythonAvailable = true;
+        pythonVersion = (pyVer.stdout || pyVer.stderr).trim();
+      }
+
+      const checkMod = spawnSync(
+        pyCmd,
+        ['-c', 'import amv_train as tt; b = tt.get_backend("vulkan") if "vulkan" in tt.available_backends() else None; print(getattr(b, "is_vulkan_active", False))'],
+        { stdio: 'pipe', encoding: 'utf-8' }
+      );
+      if (!checkMod.error && checkMod.status === 0) {
+        termuxTrainPyInstalled = true;
+        vulkanDetected = checkMod.stdout.trim().toLowerCase() === 'true';
+      }
+    } catch (_) {}
+  }
+
+  return {
+    framework: 'amv-train',
+    version: require('../package.json').version,
+    platform: {
+      system: process.platform,
+      arch: process.arch,
+      isTermux,
+      isAndroid
+    },
+    hardware: {
+      cpuCores,
+      totalRamMb,
+      freeRamMb,
+      usableFreeRamMb,
+      tier
+    },
+    python: {
+      available: pythonAvailable,
+      version: pythonVersion,
+      binary: pyCmd,
+      moduleInstalled: termuxTrainPyInstalled
+    },
+    vulkan: {
+      gpuAcceleration: vulkanDetected,
+      status: vulkanDetected ? 'AVAILABLE' : 'CPU_FALLBACK'
+    },
+    recommendedTrainingConfig: {
+      loraRank: recLoraRank,
+      batchSize: recBatchSize,
+      seqLen: 512,
+      safeTensorsMmap: true
+    },
+    status: pythonAvailable && termuxTrainPyInstalled ? 'READY' : 'SETUP_REQUIRED'
+  };
+}
+
+module.exports = {
+  resolvePythonCmd,
+  invalidatePythonCache,
+  runDoctor
+};

package/lib/errors.js

@@ -0,0 +1,60 @@
+/**
+ * Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+ */
+/**
+ * amv-train: Standard Error Definitions
+ * Open-Source under Apache License 2.0.
+ */
+
+'use strict';
+
+class TermuxTrainError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+class PythonRuntimeNotFoundError extends TermuxTrainError {
+  constructor(msg = 'Python runtime (python3 or python) was not found in PATH.') {
+    super(msg);
+  }
+}
+
+class TermuxTrainModuleNotFoundError extends TermuxTrainError {
+  constructor(msg = 'amv_train Python module is not installed or importable. Run "pip install amv-train".') {
+    super(msg);
+  }
+}
+
+class TrainingExecutionError extends TermuxTrainError {
+  constructor(message, exitCode = 1, stderr = '') {
+    super(message);
+    this.exitCode = exitCode;
+    this.stderr = stderr;
+  }
+}
+
+class VulkanNotAvailableError extends TermuxTrainError {
+  constructor(msg = 'Vulkan GPU acceleration is requested but not available on this device.') {
+    super(msg);
+  }
+}
+
+class InvalidCheckpointError extends TermuxTrainError {
+  constructor(path, reason = 'Corrupted or unreadable SafeTensors checkpoint.') {
+    super(`Invalid checkpoint at "${path}": ${reason}`);
+    this.path = path;
+  }
+}
+
+module.exports = {
+  TermuxTrainError,
+  PythonRuntimeNotFoundError,
+  TermuxTrainModuleNotFoundError,
+  TrainingExecutionError,
+  VulkanNotAvailableError,
+  InvalidCheckpointError
+};

package/lib/multimodal.js

@@ -0,0 +1,95 @@
+/**
+ * Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+ */
+/**
+ * amv-train: Multimodal & Distributed Training Node.js Bridge
+ * Provides asynchronous JavaScript SDK bindings for Diffusion, Vision VLM,
+ * Whisper STT, TTS Speaker Adaptation, and Cluster Orchestration.
+ * Open-Source under Apache License 2.0.
+ */
+
+'use strict';
+
+const { spawn } = require('child_process');
+const { resolvePythonCmd } = require('./doctor');
+const { PythonRuntimeNotFoundError, TrainingExecutionError } = require('./errors');
+
+function _executePythonCli(subcommand, optArgs = {}) {
+  return new Promise((resolve, reject) => {
+    const pyCmd = resolvePythonCmd();
+    if (!pyCmd) {
+      return reject(new PythonRuntimeNotFoundError('Python runtime required for multimodal training execution.'));
+    }
+
+    const cliArgs = ['-m', 'amv_train.cli', subcommand];
+    for (const [k, v] of Object.entries(optArgs)) {
+      if (v === null || v === undefined) continue;
+      const flagName = k.replace(/([A-Z])/g, '-$1').toLowerCase();
+      if (typeof v === 'boolean') {
+        if (v) cliArgs.push(`--${flagName}`);
+      } else {
+        cliArgs.push(`--${flagName}`, String(v));
+      }
+    }
+
+    const child = spawn(pyCmd, cliArgs, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdoutData = '';
+    let stderrData = '';
+
+    child.stdout.on('data', (d) => {
+      stdoutData += d.toString();
+    });
+
+    child.stderr.on('data', (d) => {
+      stderrData += d.toString();
+    });
+
+    child.on('error', (err) => {
+      reject(err);
+    });
+
+    child.on('close', (code) => {
+      if (code !== 0) {
+        const err = new TrainingExecutionError(`Execution of '${subcommand}' failed with exit code ${code}:\n${stderrData || stdoutData}`);
+        err.exitCode = code;
+        err.stderr = stderrData;
+        return reject(err);
+      }
+      resolve({
+        status: 'SUCCESS',
+        subcommand,
+        stdout: stdoutData.trim(),
+        stderr: stderrData.trim()
+      });
+    });
+  });
+}
+
+function trainDiffusion(options = {}) {
+  return _executePythonCli('diffusion-train', options);
+}
+
+function trainVision(options = {}) {
+  return _executePythonCli('vision-train', options);
+}
+
+function trainSTT(options = {}) {
+  return _executePythonCli('stt-train', options);
+}
+
+function trainTTS(options = {}) {
+  return _executePythonCli('tts-train', options);
+}
+
+function runClusterProbe(options = {}) {
+  return _executePythonCli('cluster-probe', options);
+}
+
+module.exports = {
+  trainDiffusion,
+  trainVision,
+  trainSTT,
+  trainTTS,
+  runClusterProbe,
+};

package/lib/trainer.js

@@ -0,0 +1,350 @@
+/**
+ * Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+ */
+/**
+ * amv-train: Production-Grade On-Device Training Orchestrator
+ * True Dual-Engine LoRA, Transformer & MLP Training Pipeline with SafeTensors I/O.
+ * Open-Source under Apache License 2.0.
+ */
+
+'use strict';
+
+const { EventEmitter } = require('events');
+const { spawn, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const { resolvePythonCmd } = require('./doctor');
+const {
+  PythonRuntimeNotFoundError,
+  TrainingExecutionError,
+  InvalidCheckpointError
+} = require('./errors');
+
+// Maximum stderr accumulation per session: 1MB cap to prevent heap exhaustion
+const MAX_STDERR_BYTES = 1024 * 1024;
+
+class TermuxTrainer extends EventEmitter {
+  constructor(config = {}) {
+    super();
+    // Default max listener count raised to support multi-epoch long training
+    this.setMaxListeners(50);
+
+    const modelType = typeof config.modelType === 'string'
+      ? config.modelType.toLowerCase().trim()
+      : 'mlp';
+
+    const dim = Number.isInteger(config.dim) && config.dim >= 4 && config.dim <= 4096
+      ? config.dim
+      : 32;
+
+    const hiddenDim = Number.isInteger(config.hiddenDim) && config.hiddenDim >= 4
+      ? config.hiddenDim
+      : dim * 2;
+
+    const outDim = Number.isInteger(config.outDim) && config.outDim >= 1
+      ? config.outDim
+      : (modelType.includes('lora') ? dim : 1);
+
+    const maxRank = Math.min(dim, outDim);
+    const loraRank = Number.isInteger(config.loraRank) && config.loraRank >= 1
+      ? Math.min(config.loraRank, maxRank)
+      : Math.min(4, maxRank);
+
+    const loraAlpha = typeof config.loraAlpha === 'number' && isFinite(config.loraAlpha) && config.loraAlpha > 0
+      ? config.loraAlpha
+      : 1.0;
+
+    const vocabSize = Number.isInteger(config.vocabSize) && config.vocabSize >= 2
+      ? config.vocabSize
+      : 256;
+
+    const layers = Number.isInteger(config.layers) && config.layers >= 1 && config.layers <= 32
+      ? config.layers
+      : 2;
+
+    // Determine heads: use explicit user configuration, or choose adaptive default that divides dim evenly
+    let heads = Number.isInteger(config.heads) && config.heads >= 1 ? config.heads : 2;
+
+    // Strict division & RoPE invariants only apply to Transformer / Attention models
+    if (modelType.includes('transformer') || modelType.includes('rope')) {
+      if (!Number.isInteger(config.heads) || config.heads < 1) {
+        // Adaptive default for transformer: 2 for even dim
+        heads = (dim % 2 === 0) ? 2 : 1;
+      }
+
+      if (dim % heads !== 0) {
+        throw new TypeError(
+          `Transformer model dimension (dim=${dim}) is not divisible by heads (heads=${heads}). ` +
+          `Choose heads that evenly divide dim (e.g., ${this._suggestHeads(dim)}).`
+        );
+      }
+
+      if (dim % 2 !== 0) {
+        throw new TypeError(
+          `Transformer models with RoPE rotary embeddings require an even dimension, got dim=${dim}. ` +
+          `RoPE operates on 2D coordinate pairs. Choose an even dimension (e.g., ${dim + 1}).`
+        );
+      }
+      const headDim = Math.floor(dim / heads);
+      if (headDim % 2 !== 0) {
+        throw new TypeError(
+          `head_dim = dim / heads (${dim} / ${heads} = ${headDim}) must be even for RoPE embeddings. ` +
+          `Choose heads such that dim / heads is even.`
+        );
+      }
+    }
+
+    const lr = typeof config.lr === 'number' && isFinite(config.lr) && config.lr > 0 && config.lr <= 10.0
+      ? config.lr
+      : 1e-3;
+
+    const batchSize = Number.isInteger(config.batchSize) && config.batchSize >= 1 && config.batchSize <= 1024
+      ? config.batchSize
+      : 16;
+
+    const seqLen = Number.isInteger(config.seqLen) && config.seqLen >= 2 && config.seqLen <= 2048
+      ? config.seqLen
+      : 32;
+
+    const backend = typeof config.backend === 'string'
+      ? config.backend.replace(/[^a-zA-Z0-9_-]/g, '').toLowerCase()
+      : 'auto';
+
+    this.config = {
+      modelType,
+      dim,
+      hiddenDim,
+      outDim,
+      loraRank,
+      loraAlpha,
+      vocabSize,
+      layers,
+      heads,
+      lr,
+      batchSize,
+      seqLen,
+      backend
+    };
+
+    this.process = null;
+    this.isRunning = false;
+    this._lineBuffer = '';
+    this._stoppedEmitted = false;
+  }
+
+  _suggestHeads(dim) {
+    const candidates = [1, 2, 4, 8, 16];
+    return candidates.filter(h => dim % h === 0).join(', ');
+  }
+
+  async fit(options = {}) {
+    if (this.isRunning) {
+      throw new Error('Training session is already running. Concurrent execution on single device is restricted.');
+    }
+
+    const pyCmd = resolvePythonCmd();
+    if (!pyCmd) {
+      throw new PythonRuntimeNotFoundError();
+    }
+
+    const rawEpochs = options.epochs !== undefined ? options.epochs : 5;
+    const rawLr = options.lr !== undefined ? options.lr : this.config.lr;
+    const checkpointPath = options.checkpointPath ? path.resolve(String(options.checkpointPath)) : null;
+    const dataPath = options.dataPath ? path.resolve(String(options.dataPath)) : null;
+
+    if (!Number.isInteger(rawEpochs) || rawEpochs <= 0 || rawEpochs > 100000) {
+      throw new TypeError(`Invalid epochs: ${rawEpochs}. Must be an integer between 1 and 100000.`);
+    }
+
+    if (typeof rawLr !== 'number' || !isFinite(rawLr) || rawLr <= 0 || rawLr > 10.0) {
+      throw new TypeError(`Invalid learning rate: ${rawLr}. Must be a finite positive number <= 10.0.`);
+    }
+
+    if (dataPath && !fs.existsSync(dataPath)) {
+      throw new Error(`Specified dataPath does not exist: "${dataPath}"`);
+    }
+
+    if (checkpointPath) {
+      const parent = path.dirname(checkpointPath);
+      try {
+        if (!fs.existsSync(parent)) {
+          fs.mkdirSync(parent, { recursive: true });
+        }
+      } catch (mkdirErr) {
+        throw new InvalidCheckpointError(checkpointPath, `Cannot create parent directory: ${mkdirErr.message}`);
+      }
+    }
+
+    const safeEpochs = Math.floor(rawEpochs);
+    const safeLr = Number(rawLr.toPrecision(8));
+
+    const sessionConfig = {
+      ...this.config,
+      epochs: safeEpochs,
+      lr: safeLr,
+      checkpointPath,
+      dataPath
+    };
+
+    return new Promise((resolve, reject) => {
+      this.isRunning = true;
+      this._lineBuffer = '';
+      this._stoppedEmitted = false;
+
+      this.process = spawn(pyCmd, ['-m', 'amv_train.runtime.runner', '--stdin-json'], {
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+
+      this.process.stdin.write(JSON.stringify(sessionConfig));
+      this.process.stdin.end();
+
+      let stderrBytes = 0;
+      let stderrAcc = '';
+      let checkpointInfo = null;
+
+      this.process.stdout.on('data', (chunk) => {
+        this._lineBuffer += chunk.toString('utf-8');
+        let newlineIdx;
+        while ((newlineIdx = this._lineBuffer.indexOf('\n')) !== -1) {
+          const line = this._lineBuffer.slice(0, newlineIdx).trim();
+          this._lineBuffer = this._lineBuffer.slice(newlineIdx + 1);
+
+          if (line.startsWith('__METRICS__:')) {
+            try {
+              const data = JSON.parse(line.slice('__METRICS__:'.length));
+              if (data.event === 'checkpoint') {
+                checkpointInfo = data;
+                this.emit('checkpoint', data);
+              } else {
+                this.emit('step', data);
+                if (data.epoch) {
+                  this.emit('epoch', data);
+                }
+              }
+            } catch (parseErr) {
+              this.emit('warning', `Failed to parse telemetry line: ${parseErr.message}`);
+            }
+          } else if (line.startsWith('__ERROR__:')) {
+            this.emit('warning', `Remote backend error: ${line}`);
+          }
+        }
+      });
+
+      this.process.stderr.on('data', (chunk) => {
+        const chunkStr = chunk.toString('utf-8');
+        stderrBytes += Buffer.byteLength(chunkStr, 'utf-8');
+        if (stderrBytes <= MAX_STDERR_BYTES) {
+          stderrAcc += chunkStr;
+        }
+        // Beyond cap: silently drop to prevent heap exhaustion. Error is still propagated via exit code.
+      });
+
+      this.process.on('close', (code) => {
+        this.isRunning = false;
+        this.process = null;
+        this._lineBuffer = '';
+
+        if (code === 0) {
+          const result = {
+            status: 'SUCCESS',
+            epochs: safeEpochs,
+            modelType: this.config.modelType,
+            checkpoint: checkpointInfo
+          };
+          this.emit('complete', result);
+          resolve(result);
+        } else {
+          const err = new TrainingExecutionError(
+            `Training process terminated with exit code ${code}`,
+            code,
+            stderrAcc
+          );
+          if (this.listenerCount('error') > 0) {
+            this.emit('error', err);
+          }
+          reject(err);
+        }
+      });
+
+      this.process.on('error', (procErr) => {
+        this.isRunning = false;
+        this.process = null;
+        if (this.listenerCount('error') > 0) {
+          this.emit('error', procErr);
+        }
+        reject(procErr);
+      });
+    });
+  }
+
+  async stop() {
+    if (!this.process || !this.isRunning) {
+      return;
+    }
+
+    const proc = this.process;
+    const pid = proc.pid;
+
+    // Guard: pid must be a valid positive integer before any kill attempt
+    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) {
+      this.isRunning = false;
+      this.process = null;
+      this._emitStopped();
+      return;
+    }
+
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        try {
+          if (process.platform === 'win32') {
+            spawnSync('taskkill', ['/pid', String(pid), '/f', '/t']);
+          } else {
+            proc.kill('SIGKILL');
+          }
+        } catch (_) {}
+        this.isRunning = false;
+        this.process = null;
+        this._lineBuffer = '';
+        this._emitStopped();
+        resolve();
+      }, 2000);
+
+      proc.once('close', () => {
+        clearTimeout(timer);
+        this.isRunning = false;
+        this.process = null;
+        this._lineBuffer = '';
+        this._emitStopped();
+        resolve();
+      });
+
+      try {
+        if (process.platform === 'win32') {
+          spawn('taskkill', ['/pid', String(pid), '/f', '/t']);
+        } else {
+          proc.kill('SIGTERM');
+        }
+      } catch (_) {
+        try { proc.kill('SIGKILL'); } catch (_2) {}
+      }
+    });
+  }
+
+  /** Ensures 'stopped' is emitted exactly once per stop() call. */
+  _emitStopped() {
+    if (!this._stoppedEmitted) {
+      this._stoppedEmitted = true;
+      this.emit('stopped');
+    }
+  }
+
+  /** Deterministically remove all event listeners after a session. */
+  dispose() {
+    this.removeAllListeners();
+  }
+}
+
+module.exports = {
+  TermuxTrainer
+};