entity-predictor 1.0.0

package/README.md

@@ -0,0 +1,114 @@
+# Entity Predictor
+
+A lightweight, zero-dependency (almost) Node.js library for entity name prediction and normalization. It uses fuzzy matching to identify entities from messy input, supporting aliases, acronyms, and common typos.
+
+## Features
+
+- **Fuzzy Matching**: Matches inputs to entities even with typos or partial names.
+- **Alias Support**: Handles acronyms (e.g., "SBI" -> "STATE BANK OF INDIA") and alternative names.
+- **Confidence Scoring**: Returns a confidence score and a human-readable trust level ("Trustable", "High", "Moderate").
+- **Normalization**: Automatically normalizes input to ignore case and special characters.
+
+## Installation
+
+```bash
+npm install entity-predictor
+```
+
+## Usage
+
+### 1. Import and Initialize
+
+You can initialize the predictor with a list of entities. Entities can be simple strings or objects defining aliases.
+
+```javascript
+import { EntityPredictor } from "entity-predictor";
+
+const entities = [
+  // Simple string entity
+  "ICICI BANK",
+  "AXIS BANK",
+
+  // Entity with aliases
+  {
+    name: "STATE BANK OF INDIA",
+    aliases: ["SBI", "State Bank", "S.B.I."],
+  },
+  {
+    name: "HDFC BANK",
+    aliases: ["HDFC", "Housing Development Finance Corporation"],
+  },
+];
+
+const predictor = new EntityPredictor(entities);
+```
+
+### 2. Predict Entities
+
+Use the `predict()` method to find the best match for an input string.
+
+```javascript
+const result = predictor.predict("sbi");
+
+console.log(result);
+/*
+Output:
+{
+  entity: "STATE BANK OF INDIA",
+  confidence: 1,
+  confidenceLevel: "Trustable"
+}
+*/
+```
+
+#### Handling Typos
+
+```javascript
+const result = predictor.predict("icici bk");
+
+console.log(result);
+/*
+Output:
+{
+  entity: "ICICI BANK",
+  confidence: 0.714...,
+  confidenceLevel: "Moderate Confidence"
+}
+*/
+```
+
+### 3. Add Entities Dynamically
+
+You can add new entities to an existing predictor instance.
+
+```javascript
+predictor.addEntity("PUNJAB NATIONAL BANK", ["PNB"]);
+```
+
+## API Reference
+
+### `new EntityPredictor(entities)`
+
+- `entities`: Array of strings or objects `{ name: string, aliases: string[] }`.
+
+### `predict(input, threshold)`
+
+- `input`: String to search for.
+- `threshold`: (Optional) Minimum confidence score to return a match. Default is `0.6`.
+
+**Returns:**
+
+- `entity`: The canonical name of the matched entity.
+- `confidence`: Score between 0 and 1.
+- `confidenceLevel`:
+  - `"Trustable"` (1.0)
+  - `"High Confidence"` (>= 0.8)
+  - `"Moderate Confidence"` (>= 0.6)
+  - `"Low Confidence"` (< 0.6)
+- Returns `null` if the input is invalid.
+- Returns `{ entity: "UNKNOWN", ... }` if no match meets the threshold.
+
+### `addEntity(name, aliases)`
+
+- `name`: Canonical name of the entity.
+- `aliases`: (Optional) Array of alias strings.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "entity-predictor",
+  "version": "1.0.0",
+  "description": "Lightweight entity name prediction and normalization library",
+  "type": "module",
+  "main": "src/index.js",
+  "keywords": [
+    "nlp",
+    "entity",
+    "prediction",
+    "nodejs"
+  ],
+  "author": "Sahil",
+  "email": "dev.sahilkumar02@gmail.com",
+  "license": "MIT",
+  "dependencies": {
+    "string-similarity": "^4.0.4"
+  }
+}

package/src/index.js

@@ -0,0 +1 @@
+export { EntityPredictor } from "./predictor.js";

package/src/predictor.js

@@ -0,0 +1,93 @@
+import stringSimilarity from "string-similarity";
+
+function normalize(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z]/g, "")
+    .trim();
+}
+
+export class EntityPredictor {
+  constructor(entities = []) {
+    this.entities = [];
+    this.searchCandidates = [];
+    this.candidateToEntity = [];
+
+    entities.forEach((item) => {
+      let entityName;
+      let aliases = [];
+
+      if (typeof item === "string") {
+        entityName = item;
+      } else if (typeof item === "object" && item.name) {
+        entityName = item.name;
+        if (Array.isArray(item.aliases)) {
+          aliases = item.aliases;
+        }
+      } else {
+        return; // Skip invalid entries
+      }
+
+      this.entities.push(entityName);
+
+      // Add canonical name to search candidates
+      const normalizedName = normalize(entityName);
+      this.searchCandidates.push(normalizedName);
+      this.candidateToEntity.push(entityName);
+
+      // Add aliases to search candidates
+      aliases.forEach((alias) => {
+        this.searchCandidates.push(normalize(alias));
+        this.candidateToEntity.push(entityName);
+      });
+    });
+  }
+
+  predict(input, threshold = 0.6) {
+    if (!input || typeof input !== "string") {
+      return null;
+    }
+
+    const match = stringSimilarity.findBestMatch(
+      normalize(input),
+      this.searchCandidates
+    );
+
+    const rating = match.bestMatch.rating;
+    let confidenceLevel = "Low Confidence";
+
+    if (rating === 1) {
+      confidenceLevel = "Trustable";
+    } else if (rating >= 0.8) {
+      confidenceLevel = "High Confidence";
+    } else if (rating >= 0.6) {
+      confidenceLevel = "Moderate Confidence";
+    }
+
+    if (rating >= threshold) {
+      return {
+        entity: this.candidateToEntity[match.bestMatchIndex],
+        confidence: rating,
+        confidenceLevel,
+      };
+    }
+
+    return {
+      entity: "UNKNOWN",
+      confidence: rating,
+      confidenceLevel,
+    };
+  }
+
+  addEntity(entity, aliases = []) {
+    this.entities.push(entity);
+    const normalizedName = normalize(entity);
+    this.searchCandidates.push(normalizedName);
+    this.candidateToEntity.push(entity);
+
+    aliases.forEach((alias) => {
+      this.searchCandidates.push(normalize(alias));
+      this.candidateToEntity.push(entity);
+    });
+  }
+}