create-byan-agent 2.7.9 → 2.8.0

package/lib/stt/parakeet-backend.js

@@ -0,0 +1,262 @@
+/**
+ * Parakeet TDT STT Backend
+ *
+ * Handles installation, configuration and status checks for
+ * NVIDIA Parakeet TDT (local NeMo or Docker).
+ *
+ * @module stt/parakeet-backend
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const { execSync } = require('child_process');
+const chalk = require('chalk');
+const ora = require('ora');
+const { detectGPU, commandExists, checkPython } = require('./engine');
+
+const PARAKEET_PORT = 8001;
+const DEFAULT_MODEL = 'nvidia/parakeet-tdt-0.6b-v2';
+const MIN_PYTHON_VERSION = '3.8';
+const MIN_VRAM = 4000;
+
+/**
+ * Install and configure the Parakeet TDT backend.
+ *
+ * @param {object} options
+ * @param {'local'|'docker'} options.mode
+ * @param {string} [options.model]
+ * @param {string[]} [options.languages]
+ * @param {string} options.projectRoot
+ * @returns {Promise<{ success: boolean, model: string, mode: string }>}
+ */
+async function setup(options) {
+  const { mode, projectRoot } = options;
+  const model = options.model || DEFAULT_MODEL;
+  const languages = options.languages || ['fr', 'en'];
+
+  console.log(chalk.blue('\n  Setting up Parakeet TDT backend...'));
+  console.log(chalk.gray(`  Mode: ${mode} | Model: ${model} | Languages: ${languages.join(', ')}`));
+
+  const gpu = detectGPU();
+  if (!gpu.hasGPU || gpu.vram < MIN_VRAM) {
+    throw new Error(
+      `Parakeet TDT requires a GPU with >= ${MIN_VRAM} MB VRAM. `
+      + `Detected: ${gpu.hasGPU ? gpu.vram + ' MB' : 'no GPU'}. Use Whisper instead.`
+    );
+  }
+
+  if (mode === 'docker') {
+    await setupDocker(projectRoot);
+  } else {
+    await setupLocal(model);
+  }
+
+  return { success: true, model, mode };
+}
+
+/**
+ * Set up Parakeet via Docker Compose.
+ *
+ * @param {string} projectRoot
+ */
+async function setupDocker(projectRoot) {
+  const spinner = ora('Generating Parakeet Docker Compose...').start();
+
+  try {
+    if (!commandExists('docker')) {
+      throw new Error('Docker is required for Parakeet Docker mode');
+    }
+
+    const content = getDockerCompose();
+    const composePath = path.join(projectRoot, 'docker-compose.parakeet.yml');
+    await fs.writeFile(composePath, content, 'utf-8');
+    spinner.succeed(`Parakeet Docker Compose written to ${composePath}`);
+
+    console.log(chalk.gray('  Start with: docker compose -f docker-compose.parakeet.yml up -d'));
+  } catch (err) {
+    spinner.fail('Failed to generate Parakeet Docker Compose');
+    throw err;
+  }
+}
+
+/**
+ * Set up Parakeet locally via pip + NeMo.
+ *
+ * @param {string} model
+ */
+async function setupLocal(model) {
+  const spinner = ora('Checking Python environment...').start();
+
+  try {
+    const python = checkPython();
+    if (!python.available) {
+      throw new Error('Python 3 is required for local Parakeet installation');
+    }
+
+    if (!meetsMinVersion(python.version, MIN_PYTHON_VERSION)) {
+      throw new Error(
+        `Python >= ${MIN_PYTHON_VERSION} required, found ${python.version}`
+      );
+    }
+
+    spinner.succeed(`Python ${python.version} detected`);
+
+    if (!python.hasNemo) {
+      const pipSpinner = ora('Installing NVIDIA NeMo ASR toolkit (this may take a while)...').start();
+      try {
+        execSync('pip3 install "nvidia-nemo[asr]"', {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: 600000 // 10 min
+        });
+        pipSpinner.succeed('NVIDIA NeMo ASR installed');
+      } catch (err) {
+        pipSpinner.fail('NeMo installation failed');
+        console.log(chalk.yellow('  Try manually: pip3 install "nvidia-nemo[asr]"'));
+        throw err;
+      }
+    } else {
+      console.log(chalk.green('  NeMo ASR already installed'));
+    }
+
+    // Pre-download model so first inference is not slow
+    const dlSpinner = ora(`Downloading model ${model}...`).start();
+    try {
+      execSync(
+        `python3 -c "from nemo.collections.asr.models import EncDecRNNTBPEModel; EncDecRNNTBPEModel.from_pretrained('${model}')"`,
+        { stdio: ['pipe', 'pipe', 'pipe'], timeout: 600000 }
+      );
+      dlSpinner.succeed('Model downloaded');
+    } catch (err) {
+      dlSpinner.fail('Model download failed');
+      console.log(chalk.yellow(`  Try manually: python3 -c "from nemo.collections.asr.models import EncDecRNNTBPEModel; EncDecRNNTBPEModel.from_pretrained('${model}')"`));
+      throw err;
+    }
+  } catch (err) {
+    spinner.isSpinning && spinner.fail();
+    throw err;
+  }
+}
+
+/**
+ * Generate Docker Compose YAML for the Parakeet NeMo container.
+ *
+ * @returns {string}
+ */
+function getDockerCompose() {
+  return `version: '3.8'
+
+services:
+  parakeet-server:
+    image: nvcr.io/nvidia/nemo:24.07
+    ports:
+      - "${PARAKEET_PORT}:${PARAKEET_PORT}"
+    environment:
+      - MODEL_NAME=${DEFAULT_MODEL}
+      - NVIDIA_VISIBLE_DEVICES=all
+    volumes:
+      - parakeet-models:/root/.cache/huggingface
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:${PARAKEET_PORT}/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 120s
+    command: >
+      python -c "
+      from nemo.collections.asr.models import EncDecRNNTBPEModel;
+      import json, http.server, io, soundfile as sf, numpy as np;
+      model = EncDecRNNTBPEModel.from_pretrained('${DEFAULT_MODEL}');
+
+      class Handler(http.server.BaseHTTPRequestHandler):
+          def do_GET(self):
+              if self.path == '/health':
+                  self.send_response(200);
+                  self.end_headers();
+                  self.wfile.write(b'ok');
+              else:
+                  self.send_response(404);
+                  self.end_headers();
+          def do_POST(self):
+              length = int(self.headers['Content-Length']);
+              audio_bytes = self.rfile.read(length);
+              audio, sr = sf.read(io.BytesIO(audio_bytes));
+              transcription = model.transcribe([audio]);
+              result = json.dumps({'text': transcription[0] if transcription else ''});
+              self.send_response(200);
+              self.send_header('Content-Type', 'application/json');
+              self.end_headers();
+              self.wfile.write(result.encode());
+          def log_message(self, format, *args):
+              pass;
+
+      httpd = http.server.HTTPServer(('', ${PARAKEET_PORT}), Handler);
+      print('Parakeet TDT server listening on port ${PARAKEET_PORT}');
+      httpd.serve_forever()
+      "
+
+volumes:
+  parakeet-models:
+`;
+}
+
+/**
+ * Describe system requirements for Parakeet TDT.
+ *
+ * @returns {{ python: string, vram: string, packages: string[] }}
+ */
+function getRequirements() {
+  return {
+    python: `>=${MIN_PYTHON_VERSION}`,
+    vram: `>=${MIN_VRAM} MB`,
+    packages: ['nvidia-nemo[asr]']
+  };
+}
+
+/**
+ * Check whether the Parakeet server is responding.
+ *
+ * @returns {boolean}
+ */
+function isRunning() {
+  try {
+    execSync(`curl -sf http://localhost:${PARAKEET_PORT}/health`, {
+      stdio: ['pipe', 'pipe', 'ignore'],
+      timeout: 3000
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Semver-light comparison: is `actual` >= `minimum`?
+ * Only compares major.minor.
+ *
+ * @param {string} actual  - e.g. "3.10.12"
+ * @param {string} minimum - e.g. "3.8"
+ * @returns {boolean}
+ */
+function meetsMinVersion(actual, minimum) {
+  const parse = v => v.split('.').map(Number);
+  const [aMaj, aMin = 0] = parse(actual);
+  const [mMaj, mMin = 0] = parse(minimum);
+  return aMaj > mMaj || (aMaj === mMaj && aMin >= mMin);
+}
+
+module.exports = {
+  setup,
+  getDockerCompose,
+  getRequirements,
+  isRunning,
+  PARAKEET_PORT,
+  DEFAULT_MODEL
+};

package/lib/stt/whisper-backend.js

@@ -0,0 +1,171 @@
+/**
+ * Whisper STT Backend
+ *
+ * Handles installation, configuration and status checks for
+ * faster-whisper-server (Docker or local).
+ *
+ * @module stt/whisper-backend
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const { execSync } = require('child_process');
+const chalk = require('chalk');
+const ora = require('ora');
+const { detectGPU, commandExists, getWhisperModel } = require('./engine');
+
+const WHISPER_PORT = 8000;
+
+/**
+ * Install and configure the Whisper STT backend.
+ *
+ * @param {object} options
+ * @param {'local'|'docker'} options.mode
+ * @param {string} [options.model] - Override model selection
+ * @param {string} options.projectRoot - Absolute path to project root
+ * @returns {Promise<{ success: boolean, model: string, mode: string }>}
+ */
+async function setup(options) {
+  const { mode, projectRoot } = options;
+  const gpu = detectGPU();
+  const model = options.model || getWhisperModel(gpu.vram);
+
+  console.log(chalk.blue('\n  Setting up Whisper STT backend...'));
+  console.log(chalk.gray(`  Mode: ${mode} | Model: ${model}`));
+
+  if (mode === 'docker') {
+    await setupDocker(projectRoot, gpu, model);
+  } else {
+    await setupLocal();
+  }
+
+  return { success: true, model, mode };
+}
+
+/**
+ * Set up Whisper via Docker Compose.
+ *
+ * @param {string} projectRoot
+ * @param {object} gpu
+ * @param {string} model
+ */
+async function setupDocker(projectRoot, gpu, model) {
+  const spinner = ora('Generating Whisper Docker Compose...').start();
+
+  try {
+    const content = getDockerCompose({ gpu, model });
+    const composePath = path.join(projectRoot, 'docker-compose.turbo-whisper.yml');
+    await fs.writeFile(composePath, content, 'utf-8');
+    spinner.succeed(`Whisper Docker Compose written to ${composePath}`);
+  } catch (err) {
+    spinner.fail('Failed to generate Docker Compose');
+    throw err;
+  }
+}
+
+/**
+ * Set up Whisper locally (clone repo, create venv, install deps).
+ */
+async function setupLocal() {
+  const spinner = ora('Installing Whisper locally...').start();
+
+  try {
+    const serverDir = path.join(process.env.HOME, 'faster-whisper-server');
+
+    if (await fs.pathExists(serverDir)) {
+      spinner.text = 'Updating faster-whisper-server...';
+      execSync('git pull', { cwd: serverDir, stdio: 'pipe' });
+    } else {
+      spinner.text = 'Cloning faster-whisper-server...';
+      execSync(
+        `git clone https://github.com/fedirz/faster-whisper-server.git ${serverDir}`,
+        { stdio: 'pipe' }
+      );
+    }
+
+    spinner.text = 'Installing Python dependencies...';
+    execSync('python3 -m venv .venv && .venv/bin/pip install -e .', {
+      cwd: serverDir,
+      stdio: 'pipe'
+    });
+
+    spinner.succeed('Whisper local installation complete');
+  } catch (err) {
+    spinner.fail('Whisper local installation failed');
+    throw err;
+  }
+}
+
+/**
+ * Generate Docker Compose YAML content for Whisper.
+ *
+ * @param {object} [opts]
+ * @param {object} [opts.gpu] - GPU detection result
+ * @param {string} [opts.model] - Whisper model name
+ * @returns {string}
+ */
+function getDockerCompose(opts = {}) {
+  const gpu = opts.gpu || detectGPU();
+  const model = opts.model || getWhisperModel(gpu.vram);
+  const modelFullName = `Systran/faster-whisper-${model}`;
+  const useGPU = gpu.hasGPU;
+
+  const gpuBlock = useGPU
+    ? `
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]`
+    : '';
+
+  return `version: '3.8'
+
+services:
+  whisper-server:
+    image: fedirz/faster-whisper-server:latest-${useGPU ? 'cuda' : 'cpu'}
+    ports:
+      - "${WHISPER_PORT}:${WHISPER_PORT}"
+    environment:
+      - WHISPER__MODEL=${modelFullName}${gpuBlock}
+    restart: unless-stopped
+`;
+}
+
+/**
+ * Select the best Whisper model for the given VRAM.
+ * Delegates to the shared engine helper.
+ *
+ * @param {number} vram - VRAM in MB
+ * @returns {string}
+ */
+function getRecommendedModel(vram) {
+  return getWhisperModel(vram);
+}
+
+/**
+ * Check whether the Whisper server is responding on its port.
+ *
+ * @returns {boolean}
+ */
+function isRunning() {
+  try {
+    execSync(`curl -sf http://localhost:${WHISPER_PORT}/health`, {
+      stdio: ['pipe', 'pipe', 'ignore'],
+      timeout: 3000
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  setup,
+  getDockerCompose,
+  getRecommendedModel,
+  isRunning,
+  WHISPER_PORT
+};

package/lib/utils/file-differ.js

@@ -0,0 +1,110 @@
+/**
+ * File Differ Utility
+ *
+ * Compares installed files against template files using SHA-256 hashes.
+ *
+ * @module utils/file-differ
+ */
+
+const crypto = require('crypto');
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Compute SHA-256 hash of a file.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @returns {Promise<string>} Hex-encoded SHA-256 hash
+ */
+async function hashFile(filePath) {
+  const content = await fs.readFile(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Recursively collect all file paths relative to a root directory.
+ *
+ * @param {string} dir - Root directory to scan
+ * @param {string} [base] - Base path for recursion (internal)
+ * @returns {Promise<string[]>} Array of relative POSIX paths
+ */
+async function collectFiles(dir, base) {
+  base = base || dir;
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  let files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await collectFiles(fullPath, base);
+      files = files.concat(nested);
+    } else if (entry.isFile()) {
+      const rel = path.relative(base, fullPath).split(path.sep).join('/');
+      files.push(rel);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * @typedef {Object} DiffResult
+ * @property {string[]} toUpdate - Files that exist in both dirs but differ
+ * @property {string[]} toAdd - Files only in template (new files)
+ * @property {string[]} toSkip - Files identical in both dirs
+ * @property {string[]} toKeep - Files only in installed dir (user-created)
+ */
+
+/**
+ * Compare an installed directory against a template directory.
+ *
+ * @param {string} installedDir - Path to the installed _byan/ directory
+ * @param {string} templateDir - Path to the template _byan/ directory
+ * @returns {Promise<DiffResult>}
+ */
+async function diffFiles(installedDir, templateDir) {
+  const [installedFiles, templateFiles] = await Promise.all([
+    collectFiles(installedDir),
+    collectFiles(templateDir)
+  ]);
+
+  const installedSet = new Set(installedFiles);
+  const templateSet = new Set(templateFiles);
+
+  const toUpdate = [];
+  const toAdd = [];
+  const toSkip = [];
+  const toKeep = [];
+
+  for (const file of templateFiles) {
+    if (!installedSet.has(file)) {
+      toAdd.push(file);
+      continue;
+    }
+
+    const [installedHash, templateHash] = await Promise.all([
+      hashFile(path.join(installedDir, file)),
+      hashFile(path.join(templateDir, file))
+    ]);
+
+    if (installedHash === templateHash) {
+      toSkip.push(file);
+    } else {
+      toUpdate.push(file);
+    }
+  }
+
+  for (const file of installedFiles) {
+    if (!templateSet.has(file)) {
+      toKeep.push(file);
+    }
+  }
+
+  return { toUpdate, toAdd, toSkip, toKeep };
+}
+
+module.exports = {
+  hashFile,
+  collectFiles,
+  diffFiles
+};

package/lib/utils/manifest.js

@@ -0,0 +1,118 @@
+/**
+ * Manifest Manager
+ *
+ * Tracks installed BYAN files and their hashes in _byan/.manifest.json.
+ * Used by the update system to detect user modifications.
+ *
+ * @module utils/manifest
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const { hashFile, collectFiles } = require('./file-differ');
+
+const MANIFEST_FILENAME = '.manifest.json';
+
+/**
+ * @typedef {Object} FileEntry
+ * @property {string} hash - SHA-256 hex hash at install time
+ * @property {boolean} userModified - Whether user changed the file after install
+ */
+
+/**
+ * @typedef {Object} Manifest
+ * @property {string} version - BYAN version when manifest was created
+ * @property {string} createdAt - ISO timestamp
+ * @property {string} updatedAt - ISO timestamp
+ * @property {Object<string, FileEntry>} files - Map of relative path to file entry
+ */
+
+/**
+ * Read the manifest file from a project.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @returns {Promise<Manifest|null>} Manifest object or null if not found
+ */
+async function readManifest(projectRoot) {
+  const manifestPath = path.join(projectRoot, '_byan', MANIFEST_FILENAME);
+
+  if (!await fs.pathExists(manifestPath)) {
+    return null;
+  }
+
+  return fs.readJSON(manifestPath);
+}
+
+/**
+ * Write manifest to _byan/.manifest.json.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @param {Manifest} manifest - Manifest object to write
+ * @returns {Promise<void>}
+ */
+async function writeManifest(projectRoot, manifest) {
+  const manifestPath = path.join(projectRoot, '_byan', MANIFEST_FILENAME);
+  manifest.updatedAt = new Date().toISOString();
+  await fs.writeJSON(manifestPath, manifest, { spaces: 2 });
+}
+
+/**
+ * Generate a fresh manifest by scanning the _byan/ directory.
+ *
+ * @param {string} byanDir - Absolute path to _byan/ directory
+ * @param {string} version - BYAN version string
+ * @returns {Promise<Manifest>}
+ */
+async function generateManifest(byanDir, version) {
+  const files = await collectFiles(byanDir);
+  const fileEntries = {};
+  const now = new Date().toISOString();
+
+  for (const relPath of files) {
+    if (relPath === MANIFEST_FILENAME) continue;
+    const hash = await hashFile(path.join(byanDir, relPath));
+    fileEntries[relPath] = { hash, userModified: false };
+  }
+
+  return {
+    version,
+    createdAt: now,
+    updatedAt: now,
+    files: fileEntries
+  };
+}
+
+/**
+ * Detect which files the user has modified since installation.
+ * Compares current file hashes against those recorded in the manifest.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @returns {Promise<string[]>} Array of relative paths that were modified by the user
+ */
+async function detectUserModifications(projectRoot) {
+  const manifest = await readManifest(projectRoot);
+  if (!manifest) return [];
+
+  const byanDir = path.join(projectRoot, '_byan');
+  const modified = [];
+
+  for (const [relPath, entry] of Object.entries(manifest.files)) {
+    const fullPath = path.join(byanDir, relPath);
+    if (!await fs.pathExists(fullPath)) continue;
+
+    const currentHash = await hashFile(fullPath);
+    if (currentHash !== entry.hash) {
+      modified.push(relPath);
+    }
+  }
+
+  return modified;
+}
+
+module.exports = {
+  readManifest,
+  writeManifest,
+  generateManifest,
+  detectUserModifications,
+  MANIFEST_FILENAME
+};