amv-train 0.0.0-stage → 2.1.0

package/bin/cli.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+ */
+
+/**
+ * termux-train: Node.js Global CLI Binary.
+ * High-performance on-device Deep Learning & LoRA Training Framework.
+ * Open-Source under Apache License 2.0.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { version } = require('../package.json');
+const { runDoctor, resolvePythonCmd } = require('../lib/doctor');
+const { runBenchmark } = require('../lib/benchmark');
+const { TermuxTrainer } = require('../lib/trainer');
+const {
+  PythonRuntimeNotFoundError,
+  TermuxTrainModuleNotFoundError
+} = require('../lib/errors');
+
+const args = process.argv.slice(2);
+const command = args[0] || '--help';
+
+function getArg(flag, alias = null) {
+  for (let i = 0; i < args.length; i++) {
+    const item = args[i];
+    if (item.startsWith(`${flag}=`)) {
+      return item.slice(flag.length + 1);
+    }
+    if (alias && item.startsWith(`${alias}=`)) {
+      return item.slice(alias.length + 1);
+    }
+    if (item === flag || (alias && item === alias)) {
+      if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
+        return args[i + 1];
+      }
+    }
+  }
+  return null;
+}
+
+function hasFlag(flag, alias = null) {
+  return args.includes(flag) || (alias && args.includes(alias));
+}
+
+function printHelp() {
+  console.log(`termux-train CLI v${version} (Unified Node.js & Python Dual Engine)`);
+  console.log('Usage: termux-train <command> [options]\n');
+  console.log('Core Commands:');
+  console.log('  doctor                           Inspect device hardware, RAM tier, and Vulkan GPU');
+  console.log('  check                            Run self-diagnostic mathematical checks across backends');
+  console.log('  score                            Run 0-point baseline granular audit scoring system');
+  console.log('  benchmark [options]              Run on-device GEMM & Autograd latency benchmark');
+  console.log('  train [options]                  Run on-device training / LoRA loop');
+  console.log('  peft [options]                   Run on-device PEFT (LoRA / DoRA) training & export');
+  console.log('  diffusion-train [options]        Run on-device Image Folder Diffusion LoRA training');
+  console.log('  vision-train [options]           Run on-device Vision VLM Multimodal LoRA training');
+  console.log('  stt-train [options]              Run on-device Whisper STT Cross-Attention LoRA training');
+  console.log('  tts-train [options]              Run on-device Audio TTS Speaker Adaptation LoRA training');
+  console.log('  rl [options]                     Run on-device Reinforcement Learning (GRPO / DPO / PPO)');
+  console.log('  cluster-worker [options]         Start symmetric RPC worker server for Virtual RAM pooling');
+  console.log('  cluster-probe [options]          Probe cluster RPC nodes and inspect pooled virtual RAM');
+  console.log('  export [options]                 Export trained adapter to target runtime format');
+  console.log('  demo <1..8>                      Execute one of 8 canonical example demos\n');
+  console.log('Options:');
+  console.log('  --json                           Output results in standard JSON format');
+  console.log('  --dim <num>                      Matrix dimension for benchmark / model dim (default: 256 / 32)');
+  console.log('  --data <path>                    Path to dataset file (.safetensors, .jsonl, .txt)');
+  console.log('  --image-dir <path>               Directory containing training images for diffusion');
+  console.log('  --output <path>                  Output path for exported SafeTensors LoRA adapter');
+  console.log('  --epochs <num>                   Number of training epochs (default: 5)');
+  console.log('  --lr <val>                       Learning rate (default: 0.001)');
+  console.log('  --batch-size <num>               Mini-batch size (default: 16)');
+  console.log('  --rank <num>                     LoRA rank (default: 4 / 8)');
+  console.log('  --backend <name>                 Compute backend (auto, vulkan, amuda, numpy, python)');
+  console.log('  --checkpoint <path>              Path to save SafeTensors checkpoint');
+  console.log('  -v, --version                    Display version information');
+  console.log('  -h, --help                       Show this help message');
+}
+
+async function main() {
+  if (hasFlag('-v') || hasFlag('--version')) {
+    console.log(`termux-train ${version}`);
+    process.exit(0);
+  }
+
+  if (command === '--help' || command === '-h' || command === 'help') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (command === 'doctor') {
+    const isJson = hasFlag('--json');
+    const rep = runDoctor();
+
+    if (isJson) {
+      console.log(JSON.stringify(rep, null, 2));
+    } else {
+      console.log('=== termux-train Diagnostic Doctor (Node.js Engine) ===');
+      console.log(`  Platform       : ${rep.platform.system} (${rep.platform.arch}) | Android/Termux: ${rep.platform.isAndroid || rep.platform.isTermux}`);
+      console.log(`  Hardware Tier  : ${rep.hardware.tier} (RAM: ${rep.hardware.totalRamMb}MB | Cores: ${rep.hardware.cpuCores})`);
+      console.log(`  Python Runtime : ${rep.python.available ? rep.python.version : 'NOT FOUND'} (${rep.python.moduleInstalled ? 'termux_train installed' : 'module missing'})`);
+      console.log(`  Vulkan GPU     : ${rep.vulkan.status}`);
+      console.log(`  Preset Config  : Max LoRA Rank r=${rep.recommendedTrainingConfig.loraRank} | Batch Size=${rep.recommendedTrainingConfig.batchSize}`);
+      console.log(`  Overall Status : ${rep.status}`);
+    }
+    process.exit(0);
+  }
+
+  if (command === 'benchmark') {
+    const isJson = hasFlag('--json');
+    const dim = parseInt(getArg('--dim') || '256', 10);
+    try {
+      const res = runBenchmark({ dim });
+      if (isJson) {
+        console.log(JSON.stringify(res, null, 2));
+      } else {
+        console.log(`=== termux-train Benchmark (Dimension: ${res.dimension}) ===`);
+        console.log(`  Backend                   : ${res.backend}`);
+        console.log(`  Forward GEMM Latency      : ${res.gemmLatencyMs} ms`);
+        console.log(`  Full Autograd Step (F+B)  : ${res.autogradStepLatencyMs} ms`);
+        console.log(`  Throughput                : ${res.throughputGflops} GFLOPS`);
+      }
+      process.exit(0);
+    } catch (err) {
+      console.error(`[ERROR] Benchmark failed: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  if (command === 'train') {
+    const epochs = parseInt(getArg('--epochs') || '5', 10);
+    const lr = parseFloat(getArg('--lr') || '0.001');
+    const modelType = getArg('--model') || 'mlp';
+    const loraRank = parseInt(getArg('--rank') || '8', 10);
+    const dim = parseInt(getArg('--dim') || '32', 10);
+    const checkpoint = getArg('--checkpoint') || null;
+    const resume = getArg('--resume') || null;
+    const data = getArg('--data') || getArg('--dataPath') || null;
+    const backend = getArg('--backend') || 'auto';
+    const batchSize = parseInt(getArg('--batch-size') || getArg('--batchSize') || '16', 10);
+    const seqLen = parseInt(getArg('--seq-len') || getArg('--seqLen') || '32', 10);
+
+    if (data && !fs.existsSync(path.resolve(data))) {
+      console.error(`[ERROR] Specified dataset path does not exist: "${data}"`);
+      process.exit(1);
+    }
+
+    if (resume && !fs.existsSync(path.resolve(resume))) {
+      console.error(`[ERROR] Specified resume checkpoint path does not exist: "${resume}"`);
+      process.exit(1);
+    }
+
+    console.log(`[*] Initializing TermuxTrainer (model=${modelType}, dim=${dim}, rank=${loraRank}, epochs=${epochs}, lr=${lr}, batchSize=${batchSize}, backend=${backend}, data=${data || 'synthetic'}, resume=${resume || 'none'})...`);
+    const trainer = new TermuxTrainer({
+      modelType,
+      dim,
+      loraRank,
+      lr,
+      batchSize,
+      seqLen,
+      backend
+    });
+
+    trainer.on('step', (m) => {
+      console.log(`  [Epoch ${m.epoch}/${m.totalEpochs}] Loss: ${m.loss.toFixed(6)} (${m.latencyMs} ms)`);
+    });
+
+    trainer.on('checkpoint', (ckpt) => {
+      console.log(`  [Checkpoint] Saved SafeTensors to: ${ckpt.path} (${ckpt.sizeBytes} bytes)`);
+    });
+
+    try {
+      const res = await trainer.fit({
+        epochs,
+        checkpointPath: checkpoint,
+        resumePath: resume ? path.resolve(resume) : null,
+        dataPath: data ? path.resolve(data) : null
+      });
+      console.log(`[+] Training completed successfully in ${res.epochs} epochs.`);
+      trainer.dispose();
+      process.exit(0);
+    } catch (err) {
+      console.error(`[ERROR] Training failed: ${err.message}`);
+      trainer.dispose();
+      process.exit(1);
+    }
+  }
+
+  const forwardedCommands = new Set([
+    'check', 'score', 'demo', 'info',
+    'diffusion-train', 'vision-train', 'stt-train', 'tts-train',
+    'peft', 'lora', 'rl', 'export',
+    'cluster-worker', 'cluster-probe',
+    'component', 'model', 'instance'
+  ]);
+
+  if (forwardedCommands.has(command)) {
+    const pyCmd = resolvePythonCmd();
+    if (!pyCmd) {
+      console.error('[ERROR] Python runtime is required to execute native training pipelines.');
+      process.exit(1);
+    }
+    const pyArgs = ['-m', 'termux_train.cli', ...args];
+    const res = spawnSync(pyCmd, pyArgs, { stdio: 'inherit' });
+    process.exit(res.status || 0);
+  }
+
+  console.error(`[ERROR] Unknown command: '${command}'`);
+  printHelp();
+  process.exit(2);
+}
+
+main().catch((err) => {
+  console.error(`[FATAL] ${err.message}`);
+  process.exit(1);
+});

package/index.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+ */
+/**
+ * Type declarations for termux-train Node.js SDK
+ * Open-Source under Apache License 2.0.
+ */
+
+import { EventEmitter } from 'events';
+
+export const version: string;
+export const __version__: string;
+
+export interface DoctorPlatformInfo {
+  system: string;
+  arch: string;
+  isTermux: boolean;
+  isAndroid: boolean;
+}
+
+export interface DoctorHardwareInfo {
+  cpuCores: number;
+  totalRamMb: number;
+  freeRamMb: number;
+  tier: string;
+}
+
+export interface DoctorPythonInfo {
+  available: boolean;
+  version: string;
+  binary: string | null;
+  moduleInstalled: boolean;
+}
+
+export interface DoctorVulkanInfo {
+  gpuAcceleration: boolean;
+  status: 'AVAILABLE' | 'CPU_FALLBACK';
+}
+
+export interface RecommendedTrainingConfig {
+  loraRank: number;
+  batchSize: number;
+  seqLen: number;
+  safeTensorsMmap: boolean;
+}
+
+export interface DoctorReport {
+  framework: 'termux-train';
+  version: string;
+  platform: DoctorPlatformInfo;
+  hardware: DoctorHardwareInfo;
+  python: DoctorPythonInfo;
+  vulkan: DoctorVulkanInfo;
+  recommendedTrainingConfig: RecommendedTrainingConfig;
+  status: 'READY' | 'SETUP_REQUIRED';
+}
+
+export interface BenchmarkOptions {
+  dim?: number;
+  iters?: number;
+}
+
+export interface BenchmarkResult {
+  dimension: string;
+  iterations: number;
+  backend: string;
+  gemmLatencyMs: number;
+  autogradStepLatencyMs: number;
+  throughputGflops: number;
+}
+
+export interface TrainerConfig {
+  modelType?: 'mlp' | 'transformer' | 'transformer-lm' | 'lora' | 'linear-lora' | 'rope';
+  dim?: number;
+  hiddenDim?: number;
+  outDim?: number;
+  loraRank?: number;
+  loraAlpha?: number;
+  vocabSize?: number;
+  layers?: number;
+  heads?: number;
+  lr?: number;
+  batchSize?: number;
+  seqLen?: number;
+  backend?: 'auto' | 'cpu' | 'numpy' | 'vulkan';
+}
+
+export interface FitOptions {
+  epochs?: number;
+  lr?: number;
+  checkpointPath?: string;
+  dataPath?: string;
+}
+
+export interface TrainingMetrics {
+  event: 'step' | 'epoch';
+  epoch: number;
+  totalEpochs: number;
+  loss: number;
+  latencyMs: number;
+}
+
+export interface CheckpointInfo {
+  event: 'checkpoint';
+  path: string;
+  tensorsSaved: number;
+  sizeBytes: number;
+}
+
+export interface FitResult {
+  status: 'SUCCESS' | 'FAILED';
+  epochs: number;
+  modelType: string;
+  checkpoint: CheckpointInfo | null;
+}
+
+export class TermuxTrainer extends EventEmitter {
+  constructor(config?: TrainerConfig);
+  fit(options?: FitOptions): Promise<FitResult>;
+  stop(): Promise<void>;
+
+  on(event: 'step', listener: (metrics: TrainingMetrics) => void): this;
+  on(event: 'epoch', listener: (metrics: TrainingMetrics) => void): this;
+  on(event: 'checkpoint', listener: (info: CheckpointInfo) => void): this;
+  on(event: 'complete', listener: (res: FitResult) => void): this;
+  on(event: 'warning', listener: (msg: string) => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'stopped', listener: () => void): this;
+}
+
+export const Trainer: typeof TermuxTrainer;
+
+export function doctor(options?: Record<string, unknown>): DoctorReport;
+export function runDoctor(options?: Record<string, unknown>): DoctorReport;
+export function benchmark(options?: BenchmarkOptions): Promise<BenchmarkResult>;
+export function runBenchmark(options?: BenchmarkOptions): BenchmarkResult;
+export interface MultimodalTrainingOptions {
+  data?: string;
+  imageDir?: string;
+  output?: string;
+  prompt?: string;
+  resolution?: 256 | 512 | 768;
+  epochs?: number;
+  lr?: number;
+  batchSize?: number;
+  rank?: number;
+  alpha?: number;
+  backend?: 'auto' | 'vulkan' | 'amuda' | 'numpy' | 'python';
+}
+
+export interface MultimodalTrainingResult {
+  status: 'SUCCESS' | 'FAILED';
+  subcommand: string;
+  stdout: string;
+  stderr: string;
+}
+
+export interface ClusterProbeOptions {
+  rpc: string;
+  guardBand?: number;
+}
+
+export function trainDiffusion(options?: MultimodalTrainingOptions): Promise<MultimodalTrainingResult>;
+export function trainVision(options?: MultimodalTrainingOptions): Promise<MultimodalTrainingResult>;
+export function trainSTT(options?: MultimodalTrainingOptions): Promise<MultimodalTrainingResult>;
+export function trainTTS(options?: MultimodalTrainingOptions): Promise<MultimodalTrainingResult>;
+export function runClusterProbe(options: ClusterProbeOptions): Promise<MultimodalTrainingResult>;
+
+export namespace errors {
+  export class TermuxTrainError extends Error {}
+  export class PythonRuntimeNotFoundError extends TermuxTrainError {}
+  export class TermuxTrainModuleNotFoundError extends TermuxTrainError {}
+  export class TrainingExecutionError extends TermuxTrainError {
+    exitCode: number;
+    stderr: string;
+  }
+  export class VulkanNotAvailableError extends TermuxTrainError {}
+  export class InvalidCheckpointError extends TermuxTrainError {
+    path: string;
+  }
+}

package/index.js

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+ */
+/**
+ * termux-train: Native On-Device Deep Learning & LoRA Training Framework
+ * Dual-Engine (Python & Node.js/TypeScript) Native Module for Android Termux & ARM64.
+ * Open-Source under Apache License 2.0.
+ */
+
+'use strict';
+
+const errors = require('./lib/errors');
+const doctor = require('./lib/doctor');
+const benchmark = require('./lib/benchmark');
+const trainer = require('./lib/trainer');
+const multimodal = require('./lib/multimodal');
+const packageJson = require('./package.json');
+
+const version = packageJson.version;
+
+module.exports = {
+  version,
+  __version__: version,
+  errors,
+  doctor: doctor.runDoctor,
+  runDoctor: doctor.runDoctor,
+  invalidatePythonCache: doctor.invalidatePythonCache,
+  benchmark: benchmark.runBenchmarkAsync,
+  runBenchmark: benchmark.runBenchmark,
+  runBenchmarkAsync: benchmark.runBenchmarkAsync,
+  TermuxTrainer: trainer.TermuxTrainer,
+  Trainer: trainer.TermuxTrainer,
+  trainDiffusion: multimodal.trainDiffusion,
+  trainVision: multimodal.trainVision,
+  trainSTT: multimodal.trainSTT,
+  trainTTS: multimodal.trainTTS,
+  runClusterProbe: multimodal.runClusterProbe,
+};

package/lib/benchmark.js

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+ */
+/**
+ * termux-train: Benchmark Suite
+ * High-performance GEMM & DAG Autograd Latency & Throughput Benchmark.
+ * All benchmark execution uses stdin JSON IPC via termux_train.runtime.benchmarker
+ * — zero python -c inline script injection.
+ * Open-Source under Apache License 2.0.
+ */
+
+'use strict';
+
+const { spawn, spawnSync } = require('child_process');
+const { resolvePythonCmd } = require('./doctor');
+const { PythonRuntimeNotFoundError, TermuxTrainModuleNotFoundError } = require('./errors');
+
+function _validateBenchmarkOptions(options = {}) {
+  const rawDim = options.dim !== undefined ? options.dim : 256;
+  const rawIters = options.iters !== undefined ? options.iters : 10;
+
+  if (!Number.isInteger(rawDim) || rawDim < 2 || rawDim > 4096) {
+    throw new TypeError(`Invalid dimension: ${rawDim}. Must be an integer between 2 and 4096.`);
+  }
+
+  if (!Number.isInteger(rawIters) || rawIters < 1 || rawIters > 1000) {
+    throw new TypeError(`Invalid iterations: ${rawIters}. Must be an integer between 1 and 1000.`);
+  }
+
+  return {
+    dim: Math.floor(rawDim),
+    iters: Math.floor(rawIters)
+  };
+}
+
+async function runBenchmarkAsync(options = {}) {
+  const { dim, iters } = _validateBenchmarkOptions(options);
+  const pyCmd = resolvePythonCmd();
+
+  if (!pyCmd) {
+    throw new PythonRuntimeNotFoundError();
+  }
+
+  const cfg = JSON.stringify({ dim, iters });
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn(pyCmd, ['-m', 'termux_train.runtime.benchmarker', '--stdin-json'], {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    proc.stdin.write(cfg);
+    proc.stdin.end();
+
+    let stdoutAcc = '';
+    let stderrAcc = '';
+
+    proc.stdout.on('data', (c) => { stdoutAcc += c.toString('utf-8'); });
+    proc.stderr.on('data', (c) => { stderrAcc += c.toString('utf-8'); });
+
+    proc.on('close', (code) => {
+      if (code !== 0) {
+        if (stderrAcc.includes('No module named termux_train')) {
+          return reject(new TermuxTrainModuleNotFoundError());
+        }
+        return reject(new Error(`Benchmark process failed (exit code ${code}): ${stderrAcc}`));
+      }
+
+      try {
+        const parsed = JSON.parse(stdoutAcc.trim());
+        resolve(parsed);
+      } catch (e) {
+        reject(new Error(`Failed to parse benchmark JSON output: ${stdoutAcc}`));
+      }
+    });
+
+    proc.on('error', (err) => {
+      reject(err);
+    });
+  });
+}
+
+function runBenchmark(options = {}) {
+  const { dim, iters } = _validateBenchmarkOptions(options);
+  const pyCmd = resolvePythonCmd();
+
+  if (!pyCmd) {
+    throw new PythonRuntimeNotFoundError();
+  }
+
+  const cfg = JSON.stringify({ dim, iters });
+
+  const res = spawnSync(pyCmd, ['-m', 'termux_train.runtime.benchmarker', '--stdin-json'], {
+    input: cfg,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    encoding: 'utf-8'
+  });
+
+  if (res.status !== 0) {
+    const err = res.stderr || res.stdout || '';
+    if (err.includes('No module named termux_train')) {
+      throw new TermuxTrainModuleNotFoundError();
+    }
+    throw new Error(`Benchmark failed: ${err}`);
+  }
+
+  try {
+    return JSON.parse(res.stdout.trim());
+  } catch (e) {
+    throw new Error(`Failed to parse benchmark output: ${res.stdout}`);
+  }
+}
+
+module.exports = {
+  runBenchmark,
+  runBenchmarkAsync,
+  benchmark: runBenchmarkAsync
+};