@felipenmoura/laya-node 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe N. Moura @DEx01 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# Laya Node Wrapper
+
+The Node.js wrapper for running the [Laya Text Classification Model](https://huggingface.co/convaiinnovations/laya).
+
+Laya is a non-autoregressive decision model designed for text classification, email triage, and moderation. This package exposes Laya's API through an Express HTTP server, allowing you to easily integrate it into your Node.js applications while matching the exact Python API structure natively.
+
+## Features
+- **Zero-Config Installation**: Just follow the instructions during the install process.
+- **API Key Protection**: Built-in authorization token support to secure your endpoint.
+- **Daemon Mode**: Easily run the inference server in the background as a daemon.
+- **Automated Warmup**: Pre-loads the model weights upon startup so your first HTTP request is lightning fast.
+- **Clean CLI UX**: Smooth cli experience.
+
+## Installation
+
+```bash
+npm install
+# or
+pnpm install
+```
+
+During installation, an interactive prompt will ask you:
+1. Which **Port** the Express server should bind to (default: `4000`).
+2. Whether to generate or set a custom **Secret API Key** for route protection.
+3. Whether to automatically set up the Python `venv` environment.
+4. Whether to download the Laya model weights immediately.
+
+Your preferences will be saved securely to a `.env` file (which is automatically git-ignored).
+
+### Additional Environment Variables
+You can manually edit your `.env` file to configure additional parameters:
+- `MAX_LEN`: Controls the maximum token length passed to the Laya model during predictions. Defaults to `8192` if not provided.
+- `PORT`: The port for the Express server. Defaults to `4000` if not provided.
+- `SECRET_API_KEY`: The SECRET API key required to access the API.
+
+## Usage
+
+### Running the Server
+
+To start the server:
+```bash
+npm start
+# or
+pnpm start
+```
+
+The server will initialize, bind to the configured port, require the correct API Secret for any incomming message, automatically wake up the Laya model in the background (warm up).
+
+It will show you a `curl` sample on how to call it, too.
+
+### Running in the Background (Daemon Mode)
+
+To start the server as a background daemon process:
+```bash
+pnpm start -D
+# or
+npm run start -- -D
+```
+The wrapper will boot up, perform the startup warmup routines, print the success logs to your terminal, and detach.
+
+To shut down the background daemon:
+```bash
+pnpm stop
+# or 
+npm run stop
+```
+
+## Making Predictions
+
+Once running, send a `POST` request to `/predict`. Be sure to include your Bearer token if you enabled API Key protection during setup.
+
+### Example Request
+
+```bash
+curl -X POST http://localhost:4000/predict \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-secret-api-key>" \
+  -d '{
+    "state": "The app crashes on startup",
+    "questions": {
+      "issue": {
+        "type": "choice",
+        "instructions": "What is the issue?",
+        "criteria": {
+          "bug": "crash or error",
+          "feature": "new request"
+        }
+      }
+    }
+  }'
+```
+
+### Example Response
+
+```json
+{
+  "model": "laya-rl-agent",
+  "answers": {
+    "issue": {
+      "type": "choice",
+      "choice": "bug",
+      "probabilities": {
+        "bug": 0.9764,
+        "feature": 0.0236
+      },
+      "confidence": 0.8388,
+      "action": {
+        "act_probability": 1.0
+      }
+    }
+  },
+  "usage": {
+    "input_tokens": 28,
+    "output_tokens": 0
+  },
+  "routing": {
+    "model": "english",
+    "repo": "convaiinnovations/laya",
+    "reason": "English Latin text",
+    "detection": {
+      "script": "latin",
+      "script_profile": {
+        "latin": 1.0
+      },
+      "language": "en",
+      "is_english": true,
+      "non_latin_fraction": 0.0
+    },
+    "workflow": null
+  }
+}
+```
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/index.js

@@ -0,0 +1,217 @@
+import 'dotenv/config';
+import express from 'express';
+import { createProxyMiddleware } from 'http-proxy-middleware';
+import { spawn } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pidFile = path.join(__dirname, '.daemon.pid');
+
+if (process.argv.includes('--stop')) {
+  if (fs.existsSync(pidFile)) {
+    const pid = parseInt(fs.readFileSync(pidFile, 'utf8'), 10);
+    try {
+      process.kill(pid, 'SIGTERM');
+      console.log(`\n\x1b[32m✔ Successfully stopped Laya daemon (PID ${pid}).\x1b[0m\n`);
+    } catch (e) {
+      if (e.code === 'ESRCH') {
+        console.log(`\n\x1b[33m⚠ Daemon process (PID ${pid}) was not running.\x1b[0m\n`);
+      } else {
+        console.error(`\n\x1b[31m✖ Failed to stop daemon:\x1b[0m`, e.message, '\n');
+      }
+    }
+
+    try {
+      fs.unlinkSync(pidFile);
+    } catch (e) {
+      // it was probably removed by the processs that finished
+    }
+  } else {
+    console.log(`\n\x1b[33m⚠ No daemon PID file found. Is the server running in the background?\x1b[0m\n`);
+  }
+  process.exit(0);
+}
+
+const isDaemonArg = process.argv.includes('-D');
+const isDaemonChild = process.argv.includes('--is-daemon-child');
+
+if (isDaemonArg) {
+  const childArgs = process.argv.slice(2).filter(a => a !== '-D');
+  childArgs.push('--is-daemon-child');
+
+  const child = spawn(process.execPath, [__filename, ...childArgs], {
+    detached: true,
+    stdio: ['ignore', 'inherit', 'inherit', 'ipc']
+  });
+
+  fs.writeFileSync(pidFile, child.pid.toString());
+
+  child.on('message', (msg) => {
+    if (msg === 'WARMUP_COMPLETE') {
+      console.log('\n\x1b[35m[Daemon] Disconnecting from terminal. Laya is now running in the background.\x1b[0m\n');
+      child.disconnect();
+      child.unref();
+      process.exit(0);
+    }
+  });
+
+  child.on('exit', (code) => {
+    process.exit(code || 0);
+  });
+
+  // Suspend the parent process from running the actual server logic
+  await new Promise(() => {});
+}
+
+const PORT = process.env.PORT || 4000;
+const PYTHON_PORT = parseInt(PORT, 10) + 1; // dynamically assign python port based on node port
+const SECRET_API_KEY = process.env.SECRET_API_KEY;
+
+// Path to the python executable
+const venvPath = path.join(__dirname, 'venv');
+const pythonExec = process.platform === 'win32'
+  ? path.join(venvPath, 'Scripts', 'python')
+  : path.join(venvPath, 'bin', 'python');
+
+const uvicornExec = process.platform === 'win32'
+  ? path.join(venvPath, 'Scripts', 'uvicorn')
+  : path.join(venvPath, 'bin', 'uvicorn');
+
+// Check if venv exists, otherwise fallback to system python
+const useVenv = fs.existsSync(uvicornExec);
+const command = useVenv ? uvicornExec : 'uvicorn';
+
+console.log(`Starting python server via ${command}...`);
+
+const pythonProcess = spawn(command, ['server:app', '--port', PYTHON_PORT.toString()], {
+  cwd: __dirname,
+  stdio: ['ignore', 'pipe', 'pipe']
+});
+
+let warmedUp = false;
+async function warmupModel() {
+  if (warmedUp) return;
+  warmedUp = true;
+  console.log('\x1b[36m⏳ Waking up the Laya model. This might take a moment if weights are loading...\x1b[0m');
+  try {
+    const res = await fetch(`http://127.0.0.1:${PORT}/predict`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(SECRET_API_KEY ? { 'Authorization': `Bearer ${SECRET_API_KEY}` } : {})
+      },
+      body: JSON.stringify({
+        state: "Warmup test",
+        questions: { "status": { "type": "choice", "instructions": "Is it working?", "criteria": {"yes": "yes", "no": "no"} } }
+      })
+    });
+    
+    if (res.ok) {
+      console.log('\n\x1b[32m✔ Laya model is warmed up and the HTTP service is ready to receive requests!\x1b[0m\n');
+      if (isDaemonChild && process.send) {
+        process.send('WARMUP_COMPLETE');
+      }
+    } else {
+      console.log('\x1b[33m⚠ Model warmup returned a non-OK status, but the server is running.\x1b[0m\n');
+    }
+  } catch (e) {
+    console.error('\x1b[31m✖ Failed to warmup the model:\x1b[0m', e.message, '\n');
+  }
+}
+
+pythonProcess.stdout.on('data', (data) => {
+  // Hide standard stdout to keep terminal clean
+});
+
+pythonProcess.stderr.on('data', (data) => {
+  const msg = data.toString().trim();
+  
+  if (msg.includes('Application startup complete.')) {
+    warmupModel();
+  }
+  
+  // Hide INFO and specific verbose warnings to keep terminal clean
+  if (msg.includes('INFO:') || msg.includes('NotOpenSSLWarning') || msg.includes('MPS autocast') || msg.includes('UserWarning:')) {
+    return;
+  } else if (msg.includes('WARNING:')) {
+    console.log(`\x1b[33m[Laya Engine Warning]: ${msg}\x1b[0m`);
+  } else if (msg.includes('%|') || msg.includes('it/s')) {
+    // Let tqdm progress bars for downloads show through, but formatted
+    process.stdout.write(`\r\x1b[36m${msg}\x1b[0m`);
+  } else {
+    // Only show real errors
+    console.error(`\x1b[31m[Laya Engine Error]: ${msg}\x1b[0m`);
+  }
+});
+
+pythonProcess.on('close', (code) => {
+  console.log(`Python process exited with code ${code}`);
+  process.exit(code);
+});
+
+// Setup Express to proxy requests
+const app = express();
+
+// Authorization middleware
+if (SECRET_API_KEY) {
+  app.use((req, res, next) => {
+    const authHeader = req.headers.authorization;
+    if (!authHeader || authHeader !== `Bearer ${SECRET_API_KEY}`) {
+      return res.status(401).json({ error: 'Unauthorized: Invalid or missing API Key' });
+    }
+    next();
+  });
+}
+
+app.use('/', createProxyMiddleware({
+  target: `http://127.0.0.1:${PYTHON_PORT}`,
+  changeOrigin: true,
+  logLevel: 'silent',
+  onError: (err, req, res) => {
+    res.status(502).json({ error: 'Laya Engine is not reachable or still starting up.' });
+  }
+}));
+
+app.listen(PORT, () => {
+  console.log(`Laya Node wrapper is running on http://localhost:${PORT}`);
+  if (SECRET_API_KEY) {
+    console.log(`API Key protection is ENABLED. Please send "Authorization: Bearer <your-key>"`);
+  }
+  console.log(`You can make requests to http://localhost:${PORT}/predict\n`);
+  
+  const authHeader = SECRET_API_KEY ? ` \\\n  -H "\x1b[33mAuthorization: Bearer <your-secret-api-key>\x1b[0m"` : '';
+  const curlExample = 
+    `\x1b[36mcurl\x1b[0m -X POST \x1b[32mhttp://localhost:${PORT}/predict\x1b[0m \\\n` +
+    `  -H \x1b[33m"Content-Type: application/json"\x1b[0m${authHeader} \\\n` +
+    `  -d \x1b[33m'{\n` +
+    `    "state": "The app crashes on startup",\n` +
+    `    "questions": {\n` +
+    `      "issue": {\n` +
+    `        "type": "choice",\n` +
+    `        "instructions": "What is the issue?",\n` +
+    `        "criteria": {\n` +
+    `          "bug": "crash or error",\n` +
+    `          "feature": "new request"\n` +
+    `        }\n` +
+    `      }\n` +
+    `    }\n` +
+    `  }'\x1b[0m\n`;
+
+  console.log(`\x1b[1mExample Request:\x1b[0m\n${curlExample}`);
+});
+
+// Clean up child process on exit
+process.on('SIGINT', () => {
+  pythonProcess.kill('SIGINT');
+  if (isDaemonChild && fs.existsSync(pidFile)) fs.unlinkSync(pidFile);
+  process.exit();
+});
+
+process.on('SIGTERM', () => {
+  pythonProcess.kill('SIGTERM');
+  if (isDaemonChild && fs.existsSync(pidFile)) fs.unlinkSync(pidFile);
+  process.exit();
+});

package/install.js

@@ -0,0 +1,155 @@
+import util from 'util';
+import { exec } from 'child_process';
+import ora from 'ora';
+import inquirer from 'inquirer';
+
+const execAsync = util.promisify(exec);
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import crypto from 'crypto';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function runSetup() {
+  console.log('Laya Node wrapper setup');
+  
+  if (process.env.CI || !process.stdout.isTTY) {
+    console.log('Non-interactive environment detected. Skipping python setup.');
+    return;
+  }
+
+  const envPath = path.join(__dirname, '.env');
+  const envExists = fs.existsSync(envPath);
+  
+  let currentPort = '4000';
+  let currentApiKey = '';
+  
+  if (envExists) {
+    const envContent = fs.readFileSync(envPath, 'utf8');
+    const portMatch = envContent.match(/^PORT=(.*)$/m);
+    if (portMatch) currentPort = portMatch[1];
+  }
+
+  const { port, apiKeyChoice, customApiKey, setupPython, downloadModel } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'port',
+      message: 'The port for the HTTP service',
+      default: currentPort
+    },
+    {
+      type: 'select',
+      name: 'apiKeyChoice',
+      message: 'How do you want to configure the SECRET_API_KEY?',
+      choices: [
+        { name: 'Generate a random key', value: 'generate' },
+        { name: 'Enter a custom key', value: 'custom' },
+        { name: 'Skip (no key needed / keep existing)', value: 'skip' }
+      ]
+    },
+    {
+      type: 'input',
+      name: 'customApiKey',
+      message: 'Enter the SECRET_API_KEY:',
+      when: (answers) => answers.apiKeyChoice === 'custom'
+    },
+    {
+      type: 'select',
+      name: 'setupPython',
+      message: 'Setup all dependencies (python env, laya, etc)?',
+      choices: [
+        { name: 'Yes, do your thing', value: true },
+        { name: 'No, I will set them up manually myself', value: false },
+        { name: 'No, I already have everything set up', value: false },
+      ]
+    },
+    {
+      type: 'select',
+      name: 'downloadModel',
+      message: 'Download the model immediately or during first use?',
+      choices: [
+        { name: 'Yes, download it now', value: true },
+        { name: 'No, download it when the service starts for the first time', value: false },
+      ]
+    }
+  ]);
+
+  let finalApiKey = '';
+  if (apiKeyChoice === 'generate') {
+    finalApiKey = crypto.randomBytes(32).toString('hex');
+  } else if (apiKeyChoice === 'custom') {
+    finalApiKey = customApiKey;
+  }
+
+  // Write or update .env file
+  if (!envExists || apiKeyChoice !== 'skip' || port !== currentPort) {
+    let envContent = envExists ? fs.readFileSync(envPath, 'utf8') : '';
+    
+    // Update or append PORT
+    if (envContent.match(/^PORT=/m)) {
+      envContent = envContent.replace(/^PORT=.*$/m, `PORT=${port}`);
+    } else {
+      envContent += `\nPORT=${port}`;
+    }
+
+    // Update or append SECRET_API_KEY
+    if (finalApiKey) {
+      if (envContent.match(/^SECRET_API_KEY=/m)) {
+        envContent = envContent.replace(/^SECRET_API_KEY=.*$/m, `SECRET_API_KEY=${finalApiKey}`);
+      } else {
+        envContent += `\nSECRET_API_KEY=${finalApiKey}`;
+      }
+    }
+
+    fs.writeFileSync(envPath, envContent.trim() + '\n');
+    console.log(`Updated .env file with Port: ${port}${finalApiKey ? ' and Secret API Key' : ''}`);
+  }
+
+  if (setupPython) {
+    const spinner = ora('Setting up Python virtual environment...').start();
+    try {
+      const venvPath = path.join(__dirname, 'venv');
+      if (!fs.existsSync(venvPath)) {
+        await execAsync('python3 -m venv venv', { cwd: __dirname });
+      }
+      
+      spinner.text = 'Installing dependencies (laya, fastapi, uvicorn)...';
+      const pipCommand = process.platform === 'win32' 
+        ? path.join(venvPath, 'Scripts', 'pip')
+        : path.join(venvPath, 'bin', 'pip');
+        
+      await execAsync(`${pipCommand} install fastapi uvicorn laya`, { cwd: __dirname });
+      spinner.succeed('Setup complete!');
+    } catch (error) {
+      spinner.fail('Setup failed during python environment creation or pip install.');
+      console.error(error.stdout || error.message);
+      if (error.stderr) console.error(error.stderr);
+    }
+  } else {
+    console.log('Skipping python setup. Please ensure laya is available in your python environment.');
+  }
+
+  if (downloadModel) {
+    const spinner = ora('Downloading Laya model checkpoints...').start();
+    try {
+      const venvPath = path.join(__dirname, 'venv');
+      const pythonCommand = fs.existsSync(venvPath)
+        ? (process.platform === 'win32' ? path.join(venvPath, 'Scripts', 'python') : path.join(venvPath, 'bin', 'python'))
+        : 'python3';
+      
+      await execAsync(`${pythonCommand} -c "import warnings; warnings.filterwarnings('ignore'); from laya import Router; Router(preload=True)"`, { cwd: __dirname });
+      spinner.succeed('Model downloaded successfully!');
+    } catch (error) {
+      spinner.fail('Failed to download the model.');
+      console.error(error.stdout || error.message);
+      if (error.stderr) console.error(error.stderr);
+    }
+  }
+}
+
+runSetup().catch(err => {
+  console.error('Setup failed:', err);
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@felipenmoura/laya-node",
+  "version": "1.0.0",
+  "description": "Node wrapper for laya text classification",
+  "license": "MIT",
+  "author": "Felipe N. Moura",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "start": "node index.js",
+    "stop": "node index.js --stop",
+    "postinstall": "node install.js"
+  },
+  "dependencies": {
+    "dotenv": "^18.0.4",
+    "express": "^4.21.0",
+    "http-proxy-middleware": "^3.0.0",
+    "inquirer": "^14.2.2",
+    "ora": "^9.4.1"
+  }
+}

package/server.py

@@ -0,0 +1,34 @@
+from fastapi import FastAPI
+from pydantic import BaseModel
+from typing import Dict, Any, Optional
+import os
+
+from laya import Router
+
+app = FastAPI()
+
+# Optionally preload models based on environment variables or just default Router
+preload = os.environ.get("LAYA_PRELOAD", "false").lower() == "true"
+router = Router(preload=preload)
+
+class PredictRequest(BaseModel):
+    state: str
+    questions: Dict[str, Any]
+    model: Optional[str] = None
+    max_len: Optional[int] = None
+
+@app.post("/predict")
+def predict(req: PredictRequest):
+    kwargs = {}
+    if req.model is not None:
+        kwargs["model"] = req.model
+        
+    max_len = req.max_len if req.max_len is not None else int(os.getenv("MAX_LEN", 8192))
+    kwargs["max_len"] = max_len
+        
+    result = router.predict(req.state, req.questions, **kwargs)
+    return result
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}