@tgies/megahal-js 1.0.0

package/src/dict.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Symbol ID constants.
+ */
+export const ERROR_ID: 0;
+export const FIN_ID: 1;
+/**
+ * Interning Dictionary mapping symbols (strings) to compact integer IDs.
+ */
+export class SymbolDict {
+    /** @type {string[]} Symbols in insertion order (index is the Symbol ID). */
+    entries: string[];
+    /** @type {number[]} Sorted indices into entries, ordered alphabetically. */
+    sortedIndex: number[];
+    /**
+     * Helper to perform binary search on the sorted index.
+     * @param {string} symbol - The symbol to search for (assumed to be uppercase).
+     * @returns {{ found: boolean, index: number }}
+     */
+    _binarySearch(symbol: string): {
+        found: boolean;
+        index: number;
+    };
+    /**
+     * Intern a symbol (uppercase string), returning its unique ID.
+     * If it already exists, returns the existing ID.
+     * @param {string} symbol
+     * @returns {number}
+     */
+    intern(symbol: string): number;
+    /**
+     * Find the ID of an existing symbol without inserting it.
+     * Returns undefined if the symbol does not exist.
+     * @param {string} symbol
+     * @returns {number|undefined}
+     */
+    find(symbol: string): number | undefined;
+    /**
+     * Resolve a symbol ID back to its string value.
+     * @param {number} id
+     * @returns {string}
+     */
+    resolve(id: number): string;
+    /**
+     * Number of symbols in the dictionary (including sentinels).
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Whether the dictionary contains only the default sentinels.
+     * @returns {boolean}
+     */
+    isEmpty(): boolean;
+}
+//# sourceMappingURL=dict.d.ts.map

package/src/dict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dict.d.ts","sourceRoot":"","sources":["dict.js"],"names":[],"mappings":"AAAA;;GAEG;AACH,uBAAwB,CAAC,CAAC;AAC1B,qBAAsB,CAAC,CAAC;AAExB;;GAEG;AACH;IAEI,4EAA4E;IAC5E,SADW,MAAM,EAAE,CACgB;IAEnC,4EAA4E;IAC5E,aADW,MAAM,EAAE,CACE;IAWvB;;;;OAIG;IACH,sBAHW,MAAM,GACJ;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAqB7C;IAED;;;;;OAKG;IACH,eAHW,MAAM,GACJ,MAAM,CAclB;IAED;;;;;OAKG;IACH,aAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAS5B;IAED;;;;OAIG;IACH,YAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;OAGG;IACH,YAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,WAFa,OAAO,CAInB;CACF"}

package/src/dict.js

@@ -0,0 +1,115 @@
+/**
+ * Symbol ID constants.
+ */
+export const ERROR_ID = 0;
+export const FIN_ID = 1;
+
+/**
+ * Interning Dictionary mapping symbols (strings) to compact integer IDs.
+ */
+export class SymbolDict {
+  constructor() {
+    /** @type {string[]} Symbols in insertion order (index is the Symbol ID). */
+    this.entries = ['<ERROR>', '<FIN>'];
+
+    /** @type {number[]} Sorted indices into entries, ordered alphabetically. */
+    this.sortedIndex = [];
+
+    const err = this.entries[ERROR_ID];
+    const fin = this.entries[FIN_ID];
+    if (err <= fin) {
+      this.sortedIndex.push(ERROR_ID, FIN_ID);
+    } else {
+      this.sortedIndex.push(FIN_ID, ERROR_ID);
+    }
+  }
+
+  /**
+   * Helper to perform binary search on the sorted index.
+   * @param {string} symbol - The symbol to search for (assumed to be uppercase).
+   * @returns {{ found: boolean, index: number }}
+   */
+  _binarySearch(symbol) {
+    let low = 0;
+    let high = this.sortedIndex.length - 1;
+
+    while (low <= high) {
+      const mid = (low + high) >> 1;
+      const midId = this.sortedIndex[mid];
+      const midSym = this.entries[midId];
+
+      if (midSym < symbol) {
+        low = mid + 1;
+      } else if (midSym > symbol) {
+        high = mid - 1;
+      } else {
+        return { found: true, index: mid };
+      }
+    }
+
+    return { found: false, index: low };
+  }
+
+  /**
+   * Intern a symbol (uppercase string), returning its unique ID.
+   * If it already exists, returns the existing ID.
+   * @param {string} symbol
+   * @returns {number}
+   */
+  intern(symbol) {
+    const sym = symbol.toUpperCase();
+    const { found, index } = this._binarySearch(sym);
+
+    if (found) {
+      return this.sortedIndex[index];
+    }
+
+    const newId = this.entries.length;
+    this.entries.push(sym);
+    this.sortedIndex.splice(index, 0, newId);
+    return newId;
+  }
+
+  /**
+   * Find the ID of an existing symbol without inserting it.
+   * Returns undefined if the symbol does not exist.
+   * @param {string} symbol
+   * @returns {number|undefined}
+   */
+  find(symbol) {
+    const sym = symbol.toUpperCase();
+    const { found, index } = this._binarySearch(sym);
+    if (found) {
+      return this.sortedIndex[index];
+    }
+    return undefined;
+  }
+
+  /**
+   * Resolve a symbol ID back to its string value.
+   * @param {number} id
+   * @returns {string}
+   */
+  resolve(id) {
+    if (id < 0 || id >= this.entries.length) {
+      throw new RangeError(`Symbol ID ${id} is out of bounds`);
+    }
+    return this.entries[id];
+  }
+
+  /**
+   * Number of symbols in the dictionary (including sentinels).
+   * @returns {number}
+   */
+  get size() {
+    return this.entries.length;
+  }
+
+  /**
+   * Whether the dictionary contains only the default sentinels.
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return this.entries.length <= 2;
+  }
+}

package/src/engine.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Universal helper to parse a plain word list.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function parseWordList(text: string): string[];
+/**
+ * Universal helper to parse a swap table file content.
+ * @param {string} text
+ * @returns {[string, string][]}
+ */
+export function parseSwapFile(text: string): [string, string][];
+/**
+ * Node-only helper to load a plain word list from a file.
+ * @param {string} path
+ * @returns {Promise<string[]>}
+ */
+export function loadWordList(path: string): Promise<string[]>;
+/**
+ * Node-only helper to load a swap table from a file.
+ * @param {string} path
+ * @returns {Promise<[string, string][]>}
+ */
+export function loadSwapFile(path: string): Promise<[string, string][]>;
+/**
+ * Main MegaHAL engine class.
+ */
+export class MegaHal {
+    /**
+     * @param {number} [order=5] - Markov model order
+     * @param {any} [rng=null] - Optional custom random number generator
+     */
+    constructor(order?: number, rng?: any);
+    model: BidirectionalModel;
+    rng: any;
+    keywordConfig: KeywordConfig;
+    /** @type {string[]} */
+    greetings: string[];
+    limit: {
+        timeout: number;
+        maxIterations: number;
+    };
+    fallbackReply: string;
+    fallbackGreeting: string;
+    /**
+     * Override fallback message when respond() cannot produce output.
+     * @param {string} msg
+     */
+    setFallbackReply(msg: string): void;
+    /**
+     * Override fallback greeting when greet() cannot produce output.
+     * @param {string} msg
+     */
+    setFallbackGreeting(msg: string): void;
+    /**
+     * Set reply generation limits.
+     * @param {{ timeout?: number, maxIterations?: number }} limit
+     */
+    setLimit(limit: {
+        timeout?: number;
+        maxIterations?: number;
+    }): void;
+    /**
+     * Set keyword configuration (banned words, auxiliary words, and swap table).
+     * @param {KeywordConfig} config
+     */
+    setKeywordConfig(config: KeywordConfig): void;
+    /**
+     * Set greeting keywords.
+     * @param {string[]} greetings
+     */
+    setGreetings(greetings: string[]): void;
+    /**
+     * Learn from input text without generating a reply.
+     * @param {string} input
+     */
+    learn(input: string): void;
+    /**
+     * Learn from input and generate a reply.
+     * @param {string} input
+     * @returns {string}
+     */
+    respond(input: string): string;
+    /**
+     * Generate a reply without learning from the input.
+     * Returns null if no reply can be generated.
+     * @param {string} input
+     * @returns {string|null}
+     */
+    generate(input: string): string | null;
+    /**
+     * Generate an initial greeting before user input.
+     * @returns {string}
+     */
+    greet(): string;
+    /**
+     * Export the model state as a binary Uint8Array.
+     * Works in both Node and Browser.
+     * @param {{ use64Bit?: boolean }} [options] - Options for serialization
+     * @returns {Uint8Array}
+     */
+    exportBrain(options?: {
+        use64Bit?: boolean;
+    }): Uint8Array;
+    /**
+     * Import the model state from binary brain data.
+     * Works in both Node and Browser.
+     * @param {Uint8Array|ArrayBuffer} data
+     */
+    importBrain(data: Uint8Array | ArrayBuffer): void;
+    /**
+     * Train from a text string containing multiple lines of sentences.
+     * @param {string} content
+     */
+    trainFromContent(content: string): void;
+    /**
+     * Node-only: Save the model to a binary brain file.
+     * @param {string} path
+     * @param {{ use64Bit?: boolean }} [options] - Options for serialization
+     * @returns {Promise<void>}
+     */
+    saveBrain(path: string, options?: {
+        use64Bit?: boolean;
+    }): Promise<void>;
+    /**
+     * Node-only: Load the model from a binary brain file.
+     * @param {string} path
+     * @returns {Promise<void>}
+     */
+    loadBrain(path: string): Promise<void>;
+    /**
+     * Node-only: Train from a text file.
+     * @param {string} path
+     * @returns {Promise<void>}
+     */
+    trainFromFile(path: string): Promise<void>;
+}
+import { BidirectionalModel } from './model.js';
+import { KeywordConfig } from './keywords.js';
+//# sourceMappingURL=engine.d.ts.map

package/src/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["engine.js"],"names":[],"mappings":"AA+PA;;;;GAIG;AACH,oCAHW,MAAM,GACJ,MAAM,EAAE,CAQpB;AAED;;;;GAIG;AACH,oCAHW,MAAM,GACJ,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAiB9B;AAED;;;;GAIG;AACH,mCAHW,MAAM,GACJ,OAAO,CAAC,MAAM,EAAE,CAAC,CAS7B;AAED;;;;GAIG;AACH,mCAHW,MAAM,GACJ,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CASvC;AArSD;;GAEG;AACH;IACE;;;OAGG;IACH,oBAHW,MAAM,QACN,GAAG,EAWb;IARC,0BAA0C;IAC1C,SAAc;IACd,6BAAwC;IACxC,uBAAuB;IACvB,WADW,MAAM,EAAE,CACA;IACnB;;;MAAgD;IAChD,sBAA2C;IAC3C,yBAAiD;IAGnD;;;OAGG;IACH,sBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,yBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,gBAFW;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,QAItD;IAED;;;OAGG;IACH,yBAFW,aAAa,QAIvB;IAED;;;OAGG;IACH,wBAFW,MAAM,EAAE,QAIlB;IAED;;;OAGG;IACH,aAFW,MAAM,QAKhB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,MAAM,CAwBlB;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAqBvB;IAED;;;OAGG;IACH,SAFa,MAAM,CA0BlB;IAED;;;;;OAKG;IACH,sBAHW;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GACpB,UAAU,CAItB;IAED;;;;OAIG;IACH,kBAFW,UAAU,GAAC,WAAW,QAIhC;IAED;;;OAGG;IACH,0BAFW,MAAM,QAWhB;IAED;;;;;OAKG;IACH,gBAJW,MAAM,YACN;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GACpB,OAAO,CAAC,IAAI,CAAC,CASzB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CASzB;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CASzB;CACF;mCA7PkC,YAAY;8BAEA,eAAe"}

package/src/engine.js

@@ -0,0 +1,317 @@
+import { BidirectionalModel } from './model.js';
+import { tokenize } from './tokenizer.js';
+import { extractKeywords, KeywordConfig } from './keywords.js';
+import { generateReply, capitalize } from './generator.js';
+import { serializeBrain, deserializeBrain } from './binary.js';
+
+const DEFAULT_FALLBACK_REPLY = "I don't know enough to answer you yet!";
+const DEFAULT_FALLBACK_GREETING = 'Hello!';
+
+/**
+ * Helper to pick a random range value.
+ * @param {any} rng
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+function randomRange(rng, min, max) {
+  if (rng && typeof rng.randomRange === 'function') {
+    return rng.randomRange(min, max);
+  }
+  return Math.floor(Math.random() * (max - min)) + min;
+}
+
+/**
+ * Main MegaHAL engine class.
+ */
+export class MegaHal {
+  /**
+   * @param {number} [order=5] - Markov model order
+   * @param {any} [rng=null] - Optional custom random number generator
+   */
+  constructor(order = 5, rng = null) {
+    this.model = new BidirectionalModel(order);
+    this.rng = rng;
+    this.keywordConfig = new KeywordConfig();
+    /** @type {string[]} */
+    this.greetings = [];
+    this.limit = { timeout: 1000, maxIterations: 0 };
+    this.fallbackReply = DEFAULT_FALLBACK_REPLY;
+    this.fallbackGreeting = DEFAULT_FALLBACK_GREETING;
+  }
+
+  /**
+   * Override fallback message when respond() cannot produce output.
+   * @param {string} msg
+   */
+  setFallbackReply(msg) {
+    this.fallbackReply = msg;
+  }
+
+  /**
+   * Override fallback greeting when greet() cannot produce output.
+   * @param {string} msg
+   */
+  setFallbackGreeting(msg) {
+    this.fallbackGreeting = msg;
+  }
+
+  /**
+   * Set reply generation limits.
+   * @param {{ timeout?: number, maxIterations?: number }} limit
+   */
+  setLimit(limit) {
+    this.limit = { ...this.limit, ...limit };
+  }
+
+  /**
+   * Set keyword configuration (banned words, auxiliary words, and swap table).
+   * @param {KeywordConfig} config
+   */
+  setKeywordConfig(config) {
+    this.keywordConfig = config;
+  }
+
+  /**
+   * Set greeting keywords.
+   * @param {string[]} greetings
+   */
+  setGreetings(greetings) {
+    this.greetings = greetings.map(g => g.toUpperCase());
+  }
+
+  /**
+   * Learn from input text without generating a reply.
+   * @param {string} input
+   */
+  learn(input) {
+    const tokens = tokenize(input);
+    this.model.learn(tokens);
+  }
+
+  /**
+   * Learn from input and generate a reply.
+   * @param {string} input
+   * @returns {string}
+   */
+  respond(input) {
+    const tokens = tokenize(input);
+
+    // Learn from the input first.
+    this.model.learn(tokens);
+
+    const keywords = extractKeywords(tokens, this.model.dictionary, this.keywordConfig);
+
+    const replyTokens = generateReply(
+      this.model,
+      tokens,
+      keywords,
+      this.keywordConfig.auxiliary,
+      this.limit,
+      this.rng
+    );
+
+    if (replyTokens.length === 0) {
+      return this.fallbackReply;
+    }
+
+    return capitalize(replyTokens);
+  }
+
+  /**
+   * Generate a reply without learning from the input.
+   * Returns null if no reply can be generated.
+   * @param {string} input
+   * @returns {string|null}
+   */
+  generate(input) {
+    const tokens = tokenize(input);
+
+    const keywords = extractKeywords(tokens, this.model.dictionary, this.keywordConfig);
+
+    const replyTokens = generateReply(
+      this.model,
+      tokens,
+      keywords,
+      this.keywordConfig.auxiliary,
+      this.limit,
+      this.rng
+    );
+
+    if (replyTokens.length === 0) {
+      return null;
+    }
+
+    return capitalize(replyTokens);
+  }
+
+  /**
+   * Generate an initial greeting before user input.
+   * @returns {string}
+   */
+  greet() {
+    if (this.greetings.length === 0) {
+      return this.fallbackGreeting;
+    }
+
+    const idx = randomRange(this.rng, 0, this.greetings.length);
+    const greetingWord = this.greetings[idx];
+
+    const keywords = new Set([greetingWord]);
+
+    const replyTokens = generateReply(
+      this.model,
+      [],
+      keywords,
+      this.keywordConfig.auxiliary,
+      this.limit,
+      this.rng
+    );
+
+    if (replyTokens.length === 0) {
+      return this.fallbackGreeting;
+    }
+
+    return capitalize(replyTokens);
+  }
+
+  /**
+   * Export the model state as a binary Uint8Array.
+   * Works in both Node and Browser.
+   * @param {{ use64Bit?: boolean }} [options] - Options for serialization
+   * @returns {Uint8Array}
+   */
+  exportBrain(options) {
+    return serializeBrain(this.model, options);
+  }
+
+  /**
+   * Import the model state from binary brain data.
+   * Works in both Node and Browser.
+   * @param {Uint8Array|ArrayBuffer} data
+   */
+  importBrain(data) {
+    deserializeBrain(data, this.model);
+  }
+
+  /**
+   * Train from a text string containing multiple lines of sentences.
+   * @param {string} content
+   */
+  trainFromContent(content) {
+    const lines = content.split(/\r?\n/);
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed === '' || trimmed.startsWith('#')) {
+        continue;
+      }
+      this.learn(trimmed);
+    }
+  }
+
+  /**
+   * Node-only: Save the model to a binary brain file.
+   * @param {string} path
+   * @param {{ use64Bit?: boolean }} [options] - Options for serialization
+   * @returns {Promise<void>}
+   */
+  async saveBrain(path, options) {
+    if (typeof window !== 'undefined' || typeof process === 'undefined') {
+      throw new Error('saveBrain is only supported in Node.js environment');
+    }
+    const fs = await import('node:fs/promises');
+    const data = this.exportBrain(options);
+    await fs.writeFile(path, data);
+  }
+
+  /**
+   * Node-only: Load the model from a binary brain file.
+   * @param {string} path
+   * @returns {Promise<void>}
+   */
+  async loadBrain(path) {
+    if (typeof window !== 'undefined' || typeof process === 'undefined') {
+      throw new Error('loadBrain is only supported in Node.js environment');
+    }
+    const fs = await import('node:fs/promises');
+    const data = await fs.readFile(path);
+    this.importBrain(data);
+  }
+
+  /**
+   * Node-only: Train from a text file.
+   * @param {string} path
+   * @returns {Promise<void>}
+   */
+  async trainFromFile(path) {
+    if (typeof window !== 'undefined' || typeof process === 'undefined') {
+      throw new Error('trainFromFile is only supported in Node.js environment');
+    }
+    const fs = await import('node:fs/promises');
+    const content = await fs.readFile(path, 'utf8');
+    this.trainFromContent(content);
+  }
+}
+
+/**
+ * Universal helper to parse a plain word list.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function parseWordList(text) {
+  return text
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(line => line !== '' && !line.startsWith('#'))
+    .map(line => line.toUpperCase());
+}
+
+/**
+ * Universal helper to parse a swap table file content.
+ * @param {string} text
+ * @returns {[string, string][]}
+ */
+export function parseSwapFile(text) {
+  /** @type {[string, string][]} */
+  const pairs = [];
+  const lines = text.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) {
+      continue;
+    }
+    const parts = trimmed.split(/\s+/);
+    if (parts.length >= 2) {
+      pairs.push([parts[0].toUpperCase(), parts[1].toUpperCase()]);
+    }
+  }
+  return pairs;
+}
+
+/**
+ * Node-only helper to load a plain word list from a file.
+ * @param {string} path
+ * @returns {Promise<string[]>}
+ */
+export async function loadWordList(path) {
+  if (typeof window !== 'undefined' || typeof process === 'undefined') {
+    throw new Error('loadWordList is only supported in Node.js environment');
+  }
+  const fs = await import('node:fs/promises');
+  const content = await fs.readFile(path, 'utf8');
+  return parseWordList(content);
+}
+
+/**
+ * Node-only helper to load a swap table from a file.
+ * @param {string} path
+ * @returns {Promise<[string, string][]>}
+ */
+export async function loadSwapFile(path) {
+  if (typeof window !== 'undefined' || typeof process === 'undefined') {
+    throw new Error('loadSwapFile is only supported in Node.js environment');
+  }
+  const fs = await import('node:fs/promises');
+  const content = await fs.readFile(path, 'utf8');
+  return parseSwapFile(content);
+}

package/src/evaluator.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Score a candidate reply by keyword surprise (Shannon entropy of keywords in context).
+ *
+ * @param {import('./model.js').BidirectionalModel} model
+ * @param {string[]} candidate - Tokens of the candidate reply
+ * @param {Set<string>} keywords - Set of uppercase keywords
+ * @returns {number}
+ */
+export function evaluateReply(model: import("./model.js").BidirectionalModel, candidate: string[], keywords: Set<string>): number;
+//# sourceMappingURL=evaluator.d.ts.map

package/src/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["evaluator.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qCALW,OAAO,YAAY,EAAE,kBAAkB,aACvC,MAAM,EAAE,YACR,GAAG,CAAC,MAAM,CAAC,GACT,MAAM,CA8FlB"}