@qvac/translation-nmtcpp 0.1.0

package/index.d.ts

@@ -0,0 +1,82 @@
+import QvacResponse from "@qvac/response"
+import BaseInference, {
+  BaseInferenceArgs,
+  ReportProgressCallback,
+} from "@qvac/infer-base/WeightsProvider/BaseInference"
+import WeightsProvider from "@qvac/infer-base/WeightsProvider/WeightsProvider"
+
+declare interface Loader {
+  getStream: (path: string) => Promise<ReadableStream>
+  getFileSize?: (path: string) => Promise<number>
+  download?: (path: string, options?: {diskPath: string, progressCallback?: ReportProgressCallback}) => Promise<void>
+  deleteLocal?: () => Promise<void>
+}
+
+declare interface TranslationNmtcppParams {
+  dstLang: string
+  srcLang: string
+  [args: string]: unknown
+}
+
+declare interface TranslationNmtcppArgs extends BaseInferenceArgs {
+  loader: Loader
+  params: TranslationNmtcppParams
+  diskPath: string
+  modelName: string
+  [args: string]: unknown
+}
+
+declare interface TranslationNmtcppModelTypes {
+  readonly IndicTrans: "IndicTrans"
+  readonly Opus: "Opus"
+}
+
+declare interface TranslationNmtcppConfig {
+  modelType: TranslationNmtcppModelTypes[keyof TranslationNmtcppModelTypes];
+  [args: string]: unknown
+}
+
+/**
+ * GGML client implementation for Marian/IndicTrans translation model
+ */
+declare class TranslationNmtcpp extends BaseInference {
+  protected _config: TranslationNmtcppConfig
+  protected _diskPath: string
+  protected _modelName: string
+  protected weightsProvider: WeightsProvider
+  static readonly ModelTypes: TranslationNmtcppModelTypes
+
+  modelType: TranslationNmtcppModelTypes[keyof TranslationNmtcppModelTypes]
+
+  /**
+   * Creates an instance of TranslationNmtcpp.
+   * @constructor
+   * @param {TranslationNmtcppArgs} args arguments for inference setup
+   * @param {TranslationNmtcppConfig} config - environment specific inference setup configuration
+   */
+  constructor(args: TranslationNmtcppArgs, config: TranslationNmtcppConfig)
+
+  /**
+   * Loads the TranslationNmtcpp model files.
+   * @param {boolean} [close=false] - Optional boolean to close the loader after it finish (default: false).
+   * @param {ReportProgressCallback} [reportProgressCallback] - Optional callback function for reporting progress.
+   * @returns {Promise<void>} - A promise that resolves when the model is fully loaded.
+   */
+  load(
+    close?: boolean,
+    reportProgressCallback?: ReportProgressCallback
+  ): Promise<void>
+
+  /**
+   * Runs the process of inference output for a given input
+   * @param {string} input - The input text to translate
+   * @returns {Promise<QvacResponse>} - A promise that resolves with the response object
+   */
+  run(input: string): Promise<QvacResponse>
+}
+
+declare namespace TranslationNmtcpp {
+  export { TranslationNmtcppArgs, TranslationNmtcppConfig }
+}
+
+export = TranslationNmtcpp;

package/index.js

@@ -0,0 +1,188 @@
+'use strict'
+
+const path = require('bare-path')
+const BaseInference = require('@qvac/infer-base/WeightsProvider/BaseInference')
+const WeightsProvider = require('@qvac/infer-base/WeightsProvider/WeightsProvider')
+
+const { TranslationInterface } = require('./marian')
+const QvacResponse = require('@qvac/response')
+const { IndicProcessor } = require('./third-party/indic-processor')
+
+const END_OF_INPUT = 'end of job'
+
+class QvacIndicTransResponse extends QvacResponse {
+  /**
+     * Creates an instance of QvacIndicTransResponse.
+     * @constructor
+     * @param {IndicProcessor} processor
+     * @param {string} dstLang
+     * @param {Object} handlers
+     */
+  constructor (processor, dstLang, handlers) {
+    super(handlers)
+    this.processor = processor
+    this.dstLang = dstLang
+  }
+
+  onCancel (callback) {
+    return super.onCancel(callback)
+  }
+
+  onError (callback) {
+    return super.onError(callback)
+  }
+
+  onFinish (callback) {
+    return super.onFinish(callback)
+  }
+
+  onUpdate (callback) {
+    return super.onUpdate((data) => {
+      const [postProcessedText] = this.processor.postprocessBatch(
+        [data],
+        this.dstLang
+      )
+      return callback(postProcessedText)
+    })
+  }
+
+  async * iterate () {
+    for await (const output of super.iterate()) {
+      const [postProcessedText] = this.processor.postprocessBatch(
+        [output],
+        this.dstLang
+      )
+      yield postProcessedText
+    }
+  }
+}
+
+/**
+ * TranslationNmtcpp implementation for Marian/IndicTrans translation model
+ */
+class TranslationNmtcpp extends BaseInference {
+  /**
+   * Available model types for translation
+   * @static
+   * @type {Object}
+   * @property {string} IndicTrans
+   * @property {string} Opus
+   */
+  static ModelTypes = {
+    IndicTrans: 'IndicTrans',
+    Opus: 'Opus'
+  }
+
+  /**
+     * Creates an instance of MLCInference.
+     * @constructor
+   *
+     * @param {Object} args arguments for inference setup
+     * @param {Object} config - environment specific inference setup configuration
+     */
+  constructor ({ loader, diskPath, modelName, params, logger = null, exclusiveRun = true, ...args }, config = {}) {
+    super({ logger, exclusiveRun, ...args })
+    this.loader = loader
+    this.weightsProvider = new WeightsProvider(loader, this.logger)
+    const { modelType, ...additionalConfig } = config
+    this._modelType = modelType
+    this._config = additionalConfig
+    this._diskPath = diskPath
+    this._modelName = modelName
+    this._params = params
+  }
+
+  async _load (close = false, reportProgressCallback) {
+    await this.loader.ready()
+    try {
+      await this.downloadWeights(reportProgressCallback)
+
+      const configurationParams = {
+        path: this._config.path || path.join(this._diskPath, this._modelName),
+        config: this._config
+      }
+      this.addon = this.createAddon(configurationParams)
+      await this.addon.activate()
+      this.state.configLoaded = true
+    } finally {
+      if (close) {
+        await this.loader.close()
+      }
+    }
+  }
+
+  async _runInternal (input) {
+    if (this._modelType === TranslationNmtcpp.ModelTypes.IndicTrans) {
+      const processor = new IndicProcessor()
+      const [processedText] = processor.preprocessBatch(
+        [input],
+        this._params.srcLang,
+        this._params.dstLang
+      )
+      const jobId = await this.addon.append({
+        type: 'text',
+        input: processedText
+      })
+      const response = new QvacIndicTransResponse(
+        processor,
+        this._params.dstLang,
+        {
+          cancelHandler: () => {
+            return this.addon.cancel(jobId)
+          },
+          pauseHandler: () => {
+            return this.addon.pause()
+          },
+          continueHandler: () => {
+            return this.addon.activate()
+          }
+        }
+      )
+
+      this._saveJobToResponseMapping(jobId, response)
+      await this.addon.append({ type: END_OF_INPUT })
+      return response
+    }
+
+    const jobId = await this.addon.append({ type: 'text', input })
+
+    const response = new QvacResponse({
+      cancelHandler: () => {
+        return this.addon.cancel(jobId)
+      },
+      pauseHandler: () => {
+        return this.addon.pause()
+      },
+      continueHandler: () => {
+        return this.addon.activate()
+      }
+    })
+
+    this._saveJobToResponseMapping(jobId, response)
+    await this.addon.append({ type: END_OF_INPUT })
+    return response
+  }
+
+  createAddon (configurationParams) {
+    return new TranslationInterface(
+      configurationParams,
+      this._outputCallback.bind(this),
+      this.logger
+    )
+  }
+
+  async _downloadWeights (reportProgressCallback) {
+    const models = [this._modelName]
+
+    this.logger.info('Loading weight files:', models)
+
+    const result = await this.weightsProvider.downloadFiles(models, this._diskPath, {
+      closeLoader: true,
+      onDownloadProgress: reportProgressCallback
+    })
+    this.logger.info('Weight files downloaded successfully', { models })
+    return result
+  }
+}
+
+module.exports = TranslationNmtcpp

package/lib/error.js

@@ -0,0 +1,65 @@
+'use strict'
+
+const { QvacErrorBase, addCodes } = require('@qvac/error')
+const { name, version } = require('../package.json')
+
+class QvacErrorAddonMarian extends QvacErrorBase { }
+
+// This library has error code range from 8001 to 9000
+const ERR_CODES = Object.freeze({
+  FAILED_TO_LOAD_WEIGHTS: 8001,
+  FAILED_TO_CANCEL: 8002,
+  FAILED_TO_APPEND: 8003,
+  FAILED_TO_GET_STATUS: 8004,
+  FAILED_TO_DESTROY: 8005,
+  FAILED_TO_ACTIVATE: 8006,
+  FAILED_TO_RESET: 8007,
+  FAILED_TO_PAUSE: 8008
+})
+
+addCodes(
+  {
+    [ERR_CODES.FAILED_TO_LOAD_WEIGHTS]: {
+      name: 'FAILED_TO_LOAD_WEIGHTS',
+      message: message => `Failed to load weights, error: ${message}`
+    },
+    [ERR_CODES.FAILED_TO_CANCEL]: {
+      name: 'FAILED_TO_CANCEL',
+      message: message => `Failed to cancel inference, error: ${message}`
+    },
+    [ERR_CODES.FAILED_TO_APPEND]: {
+      name: 'FAILED_TO_APPEND',
+      message: message =>
+        `Failed to append data to processing queue, error: ${message}`
+    },
+    [ERR_CODES.FAILED_TO_GET_STATUS]: {
+      name: 'FAILED_TO_GET_STATUS',
+      message: message => `Failed to get addon status, error: ${message}`
+    },
+    [ERR_CODES.FAILED_TO_DESTROY]: {
+      name: 'FAILED_TO_DESTROY',
+      message: message => `Failed to destroy instance, error: ${message}`
+    },
+    [ERR_CODES.FAILED_TO_ACTIVATE]: {
+      name: 'FAILED_TO_ACTIVATE',
+      message: message => `Failed to activate model, error: ${message}`
+    },
+    [ERR_CODES.FAILED_TO_RESET]: {
+      name: 'FAILED_TO_RESET',
+      message: message => `Failed to reset model state, error: ${message}`
+    },
+    [ERR_CODES.FAILED_TO_PAUSE]: {
+      name: 'FAILED_TO_PAUSE',
+      message: message => `Failed to pause inference, error: ${message}`
+    }
+  },
+  {
+    name,
+    version
+  }
+)
+
+module.exports = {
+  ERR_CODES,
+  QvacErrorAddonMarian
+}

package/marian.js

@@ -0,0 +1,186 @@
+const binding = require('./binding')
+const { QvacErrorAddonMarian, ERR_CODES } = require('./lib/error')
+
+/**
+ * An interface between Bare addon in C++ and JS runtime.
+ */
+class TranslationInterface {
+  /**
+   *
+   * @param {Object} configurationParams - all the required configuration for inference setup
+   * @param {Function} outputCb - to be called on any inference event ( started, new output, error, etc )
+   * @param {Function} transitionCb - to be called on addon state changes (LISTENING, IDLE, STOPPED, etc )
+   */
+  constructor (configurationParams, outputCb, transitionCb = null) {
+    this._handle = binding.createInstance(
+      this,
+      configurationParams,
+      outputCb,
+      transitionCb
+    )
+  }
+
+  /**
+   * Stops the current process execution,
+   * frees memory allocated for configuration and weights,
+   * and moves addon to the UNLOADED state.
+   */
+  async unload () {
+    binding.unload(this._handle)
+  }
+
+  /**
+   * Moves addon the the LOADING state and loads configuration for the model.
+   * Can only be invoked after unload()
+   * @param {Object} configurationParams - all the required configuration for inference setup
+   */
+  async load (configurationParams) {
+    binding.load(this._handle, configurationParams)
+  }
+
+  /**
+   * Stops the current process execution,
+   * frees memory allocated for configuration and weights,
+   * loads the new configuration,
+   * and moves addon to the LOADING state.
+   * @param {Object} configurationParams - all the required configuration for inference setup
+   */
+  async reload (configurationParams) {
+    binding.reload(this._handle, configurationParams)
+  }
+
+  /**
+   * Loads weights for the model.
+   * Can only be invoked after instance is constructed or after load()/reload() are called
+   * @param {Object} weightsData
+   * @param {String} weightsData.filename
+   * @param {Uint8Array} weightsData.contents
+   * @param {Boolean} weightsData.completed
+   */
+  async loadWeights (weightsData) {
+    try {
+      binding.loadWeights(this._handle, weightsData)
+    } catch (err) {
+      throw new QvacErrorAddonMarian({
+        code: ERR_CODES.FAILED_TO_LOAD_WEIGHTS,
+        adds: err.message,
+        cause: err
+      })
+    }
+  }
+
+  /**
+   * Unloads weights for the model.
+   * Can only be invoked after instance has loaded weights
+   */
+  async unloadWeights () {
+    binding.unloadWeights(this._handle)
+  }
+
+  /**
+   * Moves addon to the LISTENING state after all the initialization is done
+   */
+  async activate () {
+    try {
+      binding.activate(this._handle)
+    } catch (err) {
+      throw new QvacErrorAddonMarian({
+        code: ERR_CODES.FAILED_TO_ACTIVATE,
+        adds: err.message,
+        cause: err
+      })
+    }
+  }
+
+  /**
+   * Pauses current inference process
+   */
+  async pause () {
+    try {
+      binding.pause(this._handle)
+    } catch (err) {
+      throw new QvacErrorAddonMarian({
+        code: ERR_CODES.FAILED_TO_PAUSE,
+        adds: err.message,
+        cause: err
+      })
+    }
+  }
+
+  /**
+   * Pauses current inference process
+   */
+  async stop () {
+    binding.stop(this._handle)
+  }
+
+  /**
+   * Cancel a inference process by jobId, if no jobId is provided it cancel the whole queue
+   */
+  async cancel (jobId) {
+    try {
+      binding.cancel(this._handle, jobId)
+    } catch (err) {
+      throw new QvacErrorAddonMarian({
+        code: ERR_CODES.FAILED_TO_CANCEL,
+        adds: err.message,
+        cause: err
+      })
+    }
+  }
+
+  /**
+   * Adds new input to the processing queue
+   * @param {Object} data
+   * @param {String} data.type
+   * @param {String} data.input
+   * @returns {Number} - job ID
+   */
+  async append (data) {
+    try {
+      return binding.append(this._handle, data)
+    } catch (err) {
+      throw new QvacErrorAddonMarian({
+        code: ERR_CODES.FAILED_TO_APPEND,
+        adds: err.message,
+        cause: err
+      })
+    }
+  }
+
+  /**
+   * Addon process status
+   * @returns {String}
+   */
+  async status () {
+    try {
+      return binding.status(this._handle)
+    } catch (err) {
+      throw new QvacErrorAddonMarian({
+        code: ERR_CODES.FAILED_TO_GET_STATUS,
+        adds: err.message,
+        cause: err
+      })
+    }
+  }
+
+  /**
+   * Stops addon process and clears resources (including memory).
+   */
+  async destroy () {
+    try {
+      binding.destroyInstance(this._handle)
+      this._handle = null
+    } catch (err) {
+      throw new QvacErrorAddonMarian({
+        code: ERR_CODES.FAILED_TO_DESTROY,
+        adds: err.message,
+        cause: err
+      })
+    }
+  }
+}
+
+module.exports = {
+  TranslationInterface
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@qvac/translation-nmtcpp",
+  "version": "0.1.0",
+  "description": "translation addon for qvac",
+  "addon": true,
+  "engines": {
+    "bare": ">=1.19.0"
+  },
+  "scripts": {
+    "build": "bare-make generate && bare-make build && bare-make install",
+    "lint": "standard",
+    "lint:fix": "standard --fix",
+    "test:unit:generate": "brittle -r test/unit/all.js test/unit/*.test.js",
+    "test:unit": "npm run test:unit:generate && bare test/unit/all.js",
+    "test:integration:generate": "brittle -r test/integration/all.js test/integration/*.test.js",
+    "test:integration": "npm run test:integration:generate && bare test/integration/all.js",
+    "test": "npm run lint && npm run test:unit && npm run test:integration",
+    "model:init": "qvac-dev model init",
+    "model:new": "qvac-dev model new",
+    "model:generate": "qvac-dev model generate",
+    "test:dts": "tsc index.d.ts --noEmit"
+  },
+  "files": [
+    "binding.js",
+    "index.js",
+    "marian.js",
+    "prebuilds",
+    "third-party",
+    "lib",
+    "index.d.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tetherto/qvac-lib-infer-nmtcpp.git"
+  },
+  "author": "Tether",
+  "keywords": [
+    "tether",
+    "addon",
+    "marian",
+    "qvac"
+  ],
+  "license": "Apache-2.0",
+  "bugs": "https://github.com/tetherto/qvac-lib-infer-nmtcpp/issues",
+  "homepage": "https://github.com/tetherto/qvac-lib-infer-nmtcpp#readme",
+  "devDependencies": {
+    "@qvac/dl-base": "^0.1.0",
+    "bare-fs": "^3.1.1",
+    "bare-process": "^4.2.1",
+    "bare-stream": "^2.3.0",
+    "bare-subprocess": "^5.0.3",
+    "brittle": "^3.4.0",
+    "cmake-bare": "^1.5.2",
+    "cmake-vcpkg": "^1.1.0",
+    "standard": "^17.0.0"
+  },
+  "dependencies": {
+    "@qvac/infer-base": "^0.1.0",
+    "@qvac/dl-hyperdrive": "^0.1.0",
+    "@qvac/error": "^0.1.0",
+    "@qvac/response": "^0.1.0",
+    "bare-path": "^3.0.0"
+  },
+  "exports": {
+    "./package": "./package.json",
+    ".": "./index.js"
+  },
+  "types": "index.d.ts"
+}