@rebelstack-io/intent

Modern TypeScript and native ESM intent classification and entity extraction, inspired by a minimized subset of node-nlp.

This package focuses on:

• intent classification
• entity extraction
• synonym-style entity option mapping
• number extraction
• confidence scores
• model training
• JSON model import/export

It intentionally does not include chatbot dialogs, response generation, actions, sentiment analysis, servers, connectors, Excel import, speech features, LLM integrations, or filesystem-based model loading.

Runtime

The package targets modern Node.js and native ESM.

import { NlpManager } from "@rebelstack-io/intent";

Core source avoids required filesystem access and Node-only runtime APIs. Browser use is expected to go through the consumer's bundler.

Basic Usage

import { NlpManager } from "@rebelstack-io/intent";

const manager = new NlpManager();

manager.addDocument("en", "fire the missiles", "attack.fire");
manager.addDocument("en", "launch missiles", "attack.fire");
manager.addDocument("en", "hold position", "defense.hold");
manager.addDocument("en", "stay where you are", "defense.hold");

await manager.train();

const result = await manager.classify("en", "please launch the missile");

console.log(result.intent);
console.log(result.score);
console.log(result.classifications);

Classification results include the winning intent, its score, and ranked classifications.

Entity Extraction

Enum entities map one or more source texts to a shared option.

const manager = new NlpManager();

manager.addNamedEntityText("weapon", "missile", "en", [
  "missile",
  "rocket"
]);

const entities = await manager.extractEntities("en", "launch the rocket");

console.log(entities[0]?.entity); // "weapon"
console.log(entities[0]?.option); // "missile"

Regex entities are supported:

manager.addRegexEntity("order", "en", /ORD-\d+/iu);

Trim entities are supported with before, after, and between conditions:

manager.addBetweenCondition("target", "en", "target", "now");

Number Extraction

Numbers are extracted as the built-in number entity.

const entities = await manager.extractEntities(
  "en",
  "load twenty one missiles"
);

console.log(entities[0]?.resolution?.value); // 21

Supported number scope:

• digit integers
• digit decimals
• signed digit numbers where unambiguous
• English cardinal numbers
• basic Spanish cardinal numbers

High-Level Processing

process() combines classification and entity extraction. Entity placeholders in training utterances act as slot metadata.

const manager = new NlpManager();

manager.addDocument("en", "fire %weapon%", "attack.fire");
manager.addNamedEntityText("weapon", "missile", "en", "missile");

await manager.train();

const result = await manager.process("en", "fire missile");

console.log(result.intent); // "attack.fire"
console.log(result.entities);

By default, process() extracts entities for the winning intent's slots. Pass { forceNER: true } to extract all matching entities.

Model Export and Import

Models are JSON-compatible objects or strings. Runtime consumers do not need to retrain after import.

const exported = manager.export(true);

const fresh = new NlpManager();
fresh.import(exported);

const result = await fresh.classify("en", "launch missiles");

Object hooks are also available:

const model = manager.toObj();
fresh.fromObj(model);

The minimized model format records classifier backend identity and retained NLU, NER, and slot metadata. Unsupported upstream-style top-level sections such as NLG and actions are ignored when the retained sections are structurally compatible.

Classifier Backends

Two classifier backends are available:

• neural: the default backend, intended for stronger classification quality as corpora become less keyword-like.
• bayes: a compact probabilistic backend, useful for small corpora, fast training, and deterministic baseline behavior.

Select a backend explicitly:

const neural = new NlpManager({ classifier: "neural" });
const bayes = new NlpManager({ classifier: "bayes" });

Both backends support training, classification, export, and import without retraining.

Language Support

Supported base locales:

• en
• es

Accepted aliases include en-US, en-GB, es-ES, es-MX, and other unambiguous Spanish regional aliases registered by the package.

Unsupported locales throw clear errors:

manager.addDocument("fr", "bonjour", "greeting.hello");
// Error: Unsupported locale: fr

Language support is intentionally added deliberately rather than through a broad language bundle.

Differences From node-nlp

This package is a retained subset, not a full port of node-nlp.

Intentional differences:

• Native ESM only.
• TypeScript source only.
• Modern Node.js target only.
• No CommonJS build.
• No service container or dynamic pipeline clone.
• No required filesystem model IO.
• No NLG, action manager, sentiment, dialog, bot, server, connector, Excel, speech, or LLM subsystems.
• Model compatibility is tolerant for retained structures, but full upstream model compatibility is not a goal.
• Language support is currently English and Spanish only.
• Built-in entity extraction is intentionally limited to focused local number extraction.

The public API keeps the retained NlpManager workflow where practical: addDocument, removeDocument, train, classify, process, extractEntities, entity registration helpers, toObj, fromObj, export, and import.

Development

Tests use Node's built-in test harness.

npm run typecheck
npm test
npm run test:tsx
npm run build