entity-predictor 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,13 @@
 # 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.
+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** (e.g., "SBI" -> "STATE BANK OF INDIA")
+- **Confidence Scoring** ("Trustable", "High Confidence", etc.)
+- **Top-N Matches** (Get the top 3 best guesses)
+- **Configurable Stop Words** (Ignore "The", "Inc", etc.)
 
 ## Features
 
@@ -77,7 +84,41 @@ Output:
 */
 ```
 
-### 3. Add Entities Dynamically
+### 3. Top-N Matches
+
+Get a list of best matches instead of just one.
+
+```javascript
+const results = predictor.predictTop("Apple", 3);
+// Returns array of matches: [{ entity: "Apple Inc", ... }, ...]
+```
+
+### 4. Stop Words Filtering
+
+Automatically remove noise words like "The", "Inc", "Ltd". **Disabled by default.**
+
+```javascript
+// Enable with default list
+const predictor = new EntityPredictor(entities, { ignoreStopWords: true });
+
+// Enable with custom list
+const predictor = new EntityPredictor(entities, {
+  ignoreStopWords: true,
+  stopWords: ["inc", "co", "corp"],
+});
+```
+
+### 5. Custom Normalization
+
+Pass a custom normalizer to clean data your way.
+
+```javascript
+const predictor = new EntityPredictor(entities, {
+  normalizer: (text) => text.toUpperCase(),
+});
+```
+
+### 6. Add Entities Dynamically
 
 You can add new entities to an existing predictor instance.
 
@@ -87,28 +128,25 @@ predictor.addEntity("PUNJAB NATIONAL BANK", ["PNB"]);
 
 ## API Reference
 
-### `new EntityPredictor(entities)`
+### `new EntityPredictor(entities, options)`
 
 - `entities`: Array of strings or objects `{ name: string, aliases: string[] }`.
+- `options`: (Optional)
+  - `ignoreStopWords`: boolean (default `false`)
+  - `stopWords`: string[] (optional, defaults to internal list)
+  - `normalizer`: (text: string) => string
 
 ### `predict(input, threshold)`
 
 - `input`: String to search for.
-- `threshold`: (Optional) Minimum confidence score to return a match. Default is `0.6`.
+- `threshold`: (Optional) Minimum confidence score (default `0.6`).
+- **Returns**: Best match object or `{ entity: "UNKNOWN", ... }`.
 
-**Returns:**
+### `predictTop(input, limit, threshold)`
 
-- `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.
+- `limit`: Max number of results (default `5`).
+- **Returns**: Array of match objects.
 
-### `addEntity(name, aliases)`
+### Typescript Support
 
-- `name`: Canonical name of the entity.
-- `aliases`: (Optional) Array of alias strings.
+Includes `index.d.ts` for full TypeScript support.

package/index.d.ts

@@ -0,0 +1,26 @@
+export interface EntityOption {
+    name: string;
+    aliases?: string[];
+}
+
+export interface PredictorOptions {
+    ignoreStopWords?: boolean;
+    stopWords?: string[];
+    normalizer?: (text: string) => string;
+}
+
+export interface PredictionResult {
+    entity: string;
+    confidence: number;
+    confidenceLevel: "Trustable" | "High Confidence" | "Moderate Confidence" | "Low Confidence";
+}
+
+export class EntityPredictor {
+    constructor(entities: (string | EntityOption)[], options?: PredictorOptions);
+
+    predict(input: string, threshold?: number): PredictionResult;
+
+    predictTop(input: string, limit?: number, threshold?: number): PredictionResult[];
+
+    addEntity(entity: string | EntityOption): void;
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "entity-predictor",
-  "version": "1.0.0",
-  "description": "Lightweight entity name prediction and normalization library",
+  "version": "1.1.0",
+  "description": "Lightweight entity prediction with fuzzy matching, aliases, and confidence scoring.",
+  "types": "index.d.ts",
   "type": "module",
   "main": "src/index.js",
   "keywords": [

package/src/predictor.js

@@ -1,45 +1,84 @@
 import stringSimilarity from "string-similarity";
 
-function normalize(text) {
-  return text
-    .toLowerCase()
-    .replace(/[^a-z]/g, "")
-    .trim();
+const DEFAULT_STOP_WORDS = [
+  "the",
+  "inc",
+  "ltd",
+  "pvt",
+  "corp",
+  "corporation",
+  "co",
+  "company",
+  "limited",
+  "private",
+  "bank",
+];
+
+function defaultNormalize(
+  text,
+  ignoreStopWords = true,
+  stopWords = DEFAULT_STOP_WORDS
+) {
+  let processed = text.toLowerCase();
+
+  if (ignoreStopWords) {
+    // Remove stop words (must be surrounded by word boundaries or start/end)
+    const regex = new RegExp(`\\b(${stopWords.join("|")})\\b`, "g");
+    processed = processed.replace(regex, " ");
+  }
+
+  return processed.replace(/[^a-z]/g, "").trim();
 }
 
 export class EntityPredictor {
-  constructor(entities = []) {
+  constructor(entities = [], options = {}) {
     this.entities = [];
     this.searchCandidates = [];
     this.candidateToEntity = [];
 
+    this.ignoreStopWords = options.ignoreStopWords === true; // Default false
+    this.stopWords = options.stopWords || DEFAULT_STOP_WORDS;
+    this.customNormalizer = options.normalizer;
+
     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.addEntity(item, true); // true = internal call, delay re-indexing if needed (not needed here)
+    });
+  }
+
+  normalize(text) {
+    if (this.customNormalizer) {
+      return this.customNormalizer(text);
+    }
+    return defaultNormalize(text, this.ignoreStopWords, this.stopWords);
+  }
+
+  addEntity(item, isInternal = false) {
+    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;
+    }
 
+    if (!this.entities.includes(entityName)) {
       this.entities.push(entityName);
+    }
 
-      // Add canonical name to search candidates
-      const normalizedName = normalize(entityName);
-      this.searchCandidates.push(normalizedName);
-      this.candidateToEntity.push(entityName);
+    // Add canonical
+    this.searchCandidates.push(this.normalize(entityName));
+    this.candidateToEntity.push(entityName);
 
-      // Add aliases to search candidates
-      aliases.forEach((alias) => {
-        this.searchCandidates.push(normalize(alias));
-        this.candidateToEntity.push(entityName);
-      });
+    // Add aliases
+    aliases.forEach((alias) => {
+      this.searchCandidates.push(this.normalize(alias));
+      this.candidateToEntity.push(entityName);
     });
   }
 
@@ -47,47 +86,57 @@ export class EntityPredictor {
     if (!input || typeof input !== "string") {
       return null;
     }
+    const results = this.predictTop(input, 1, threshold);
+    if (results.length > 0) {
+      return results[0];
+    }
+    return {
+      entity: "UNKNOWN",
+      confidence: 0,
+      confidenceLevel: "Low Confidence",
+    };
+  }
+
+  predictTop(input, limit = 5, threshold = 0.6) {
+    if (!input || typeof input !== "string") {
+      return [];
+    }
 
-    const match = stringSimilarity.findBestMatch(
-      normalize(input),
+    const normalizedInput = this.normalize(input);
+    const matches = stringSimilarity.findBestMatch(
+      normalizedInput,
       this.searchCandidates
     );
 
-    const rating = match.bestMatch.rating;
-    let confidenceLevel = "Low Confidence";
+    // Map all ratings to our format and sort
+    const sortedMatches = matches.ratings
+      .map((rating, index) => ({
+        entity: this.candidateToEntity[index],
+        confidence: rating.rating,
+        confidenceLevel: this._getConfidenceLevel(rating.rating),
+      }))
+      .filter((m) => m.confidence >= threshold)
+      .sort((a, b) => b.confidence - a.confidence);
 
-    if (rating === 1) {
-      confidenceLevel = "Trustable";
-    } else if (rating >= 0.8) {
-      confidenceLevel = "High Confidence";
-    } else if (rating >= 0.6) {
-      confidenceLevel = "Moderate Confidence";
-    }
+    // Deduplicate entities (picking the highest score for each unique entity)
+    const uniqueMatches = [];
+    const seenEntities = new Set();
 
-    if (rating >= threshold) {
-      return {
-        entity: this.candidateToEntity[match.bestMatchIndex],
-        confidence: rating,
-        confidenceLevel,
-      };
+    for (const match of sortedMatches) {
+      if (!seenEntities.has(match.entity)) {
+        uniqueMatches.push(match);
+        seenEntities.add(match.entity);
+        if (uniqueMatches.length >= limit) break;
+      }
     }
 
-    return {
-      entity: "UNKNOWN",
-      confidence: rating,
-      confidenceLevel,
-    };
+    return uniqueMatches;
   }
 
-  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);
-    });
+  _getConfidenceLevel(rating) {
+    if (rating === 1) return "Trustable";
+    if (rating >= 0.8) return "High Confidence";
+    if (rating >= 0.6) return "Moderate Confidence";
+    return "Low Confidence";
   }
 }