npm - @tgies/megahal-js - Versions diffs - 1.0.0 - Mend

@tgies/megahal-js 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (34) hide show

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,27 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.0.0] - 2026-05-22
+Initial release. A JavaScript port of the MegaHAL conversational engine
+(Jason Hutchens, 1998), targeting both Node.js and browser environments.
+### Added
+- Forward and backward 5th-order Markov trie models with case-insensitive symbols.
+- Tokenization matching the original C boundary rules, including apostrophe
+  handling for contractions and sentence-terminal normalization.
+- Two-pass keyword extraction with banned, auxiliary, and swap-table support.
+- Reply generation with seeded forward and backward babble phases, keyword
+  priority, and the `used_key` discipline.
+- Surprise-based reply scoring with depth-averaged probability and the
+  num >= 8 / num >= 16 length penalties.
+- Binary brain persistence compatible with the `MegaHALv8` cookie format,
+  with optional 64-bit count/usage extensions.
+- Default support file data (banned, auxiliary, greeting, swap) bundled.
+- TypeScript declarations generated from JSDoc.
+[1.0.0]: https://github.com/tgies/megahal-js/releases/tag/v1.0.0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Tony Gies
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,156 @@
+# MegaHAL-JS
+[![CI](https://github.com/tgies/megahal-js/actions/workflows/ci.yml/badge.svg)](https://github.com/tgies/megahal-js/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+A JavaScript port of Jason Hutchens' famous 1998 MegaHAL conversational engine.
+MegaHAL-JS runs natively in Node.js (>= 20) and in all modern browsers.
+---
+## Installation
+```bash
+npm install @tgies/megahal-js
+```
+---
+## Quick Start
+### Modern ESM (Node & Browser)
+```javascript
+import { MegaHal } from '@tgies/megahal-js';
+// Instantiate with order N (default is 5)
+const hal = new MegaHal(5);
+// Train the engine
+hal.learn('The cat sat on the mat.');
+hal.learn('The dog chased the cat around the yard.');
+// Generate a reply (this will also learn from the prompt before generating)
+const reply = hal.respond('Tell me about the cat.');
+console.log(reply);
+// e.g., "The dog chased the cat sat on the mat."
+```
+### Browser direct integration (Vanilla HTML/JS)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>MegaHAL Chatbot</title>
+</head>
+<body>
+  <script type="module">
+    import { MegaHal } from './node_modules/megahal-js/index.js';
+    const hal = new MegaHal(3);
+    hal.learn('Hello world!');
+    hal.learn('Welcome to the web browser version of MegaHAL.');
+    console.log(hal.respond('hello'));
+  </script>
+</body>
+</html>
+```
+---
+## API Reference
+### `class MegaHal`
+#### `constructor(order = 5, rng = null)`
+Creates a new MegaHAL engine.
+- `order`: The Markov n-gram depth (trie depth). Defaults to `5`.
+- `rng`: An optional custom random number generator. Must implement `randomRange(min, max)` returning an integer in `[min, max)`. If omitted, defaults to `Math.random`.
+#### `respond(input)`
+Learns from the input sentence, extracts its keywords, generates a response biased toward those keywords, capitalizes the response according to sentence-casing rules, and returns it.
+- `input`: The prompt string.
+- Returns: `string`
+#### `generate(input)`
+Generates a response to the prompt *without* learning from it. Returns `null` if no reply can be generated.
+- `input`: The prompt string.
+- Returns: `string | null`
+#### `greet()`
+Generates an initial greeting using a random word selected from the greeting keywords list. Falls back to the default fallback greeting if no greeting can be generated.
+- Returns: `string`
+#### `learn(input)`
+Tokenizes and trains both forward and backward models on the given sentence.
+- `input`: Sentence to train on.
+#### `setLimit({ timeout, maxIterations })`
+Configures generation limits for the reply loop.
+- `timeout`: Maximum milliseconds to spend generating candidate responses (defaults to `1000`).
+- `maxIterations`: Maximum candidates to generate.
+#### `setKeywordConfig(config)`
+Overrides the extraction config containing banned words, auxiliary words, and the swap table.
+- `config`: A `KeywordConfig` instance.
+#### `setGreetings(greetings)`
+Sets the keywords list used to seed the initial greeting.
+- `greetings`: Array of string greeting words.
+#### `exportBrain()`
+Serializes the engine's internal dictionary and tries into a spec-compliant C-compatible `.brn` binary format and returns a `Uint8Array`.
+- Returns: `Uint8Array`
+#### `importBrain(data)`
+Deserializes a binary brain from a `Uint8Array` or `ArrayBuffer` into the engine, restoring dictionary and tries.
+- `data`: Binary data buffer.
+#### `trainFromContent(content)`
+Trains the model on multi-line text corpus. Lines starting with `#` are ignored as comments.
+- `content`: Plain text string.
+#### `saveBrain(path)` *(Node-only)*
+Asynchronously saves the serialized binary brain to a file.
+- `path`: Target file path.
+#### `loadBrain(path)` *(Node-only)*
+Asynchronously loads a serialized binary brain from a file.
+- `path`: Source file path.
+#### `trainFromFile(path)` *(Node-only)*
+Asynchronously trains the model from a corpus file.
+- `path`: Text file path.
+---
+## Quality & Verification Commands
+```bash
+# Run unit tests
+npm test
+# Run test coverage
+npm run test:coverage
+# Perform TypeScript check
+npm run typecheck
+# Build declaration types
+npm run build:types
+# Run ESLint linter
+npm run lint
+# Run Stryker Mutation Testing
+npm run test:mutation
+```
+---
+## License
+MIT © [Tony Gies](mailto:tgies@tgies.net)

package/index.d.ts ADDED Viewed

@@ -0,0 +1,6 @@
+export { tokenize } from "./src/tokenizer.js";
+export { SymbolDict } from "./src/dict.js";
+export { Trie } from "./src/trie.js";
+export { MegaHal, parseWordList, parseSwapFile, loadWordList, loadSwapFile } from "./src/engine.js";
+export { extractKeywords, KeywordConfig, SwapTable } from "./src/keywords.js";
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":""}

package/index.js ADDED Viewed

@@ -0,0 +1,29 @@
+/**
+ * MegaHAL conversational engine entry point.
+ */
+export {
+  MegaHal,
+  parseWordList,
+  parseSwapFile,
+  loadWordList,
+  loadSwapFile
+} from './src/engine.js';
+export {
+  tokenize
+} from './src/tokenizer.js';
+export {
+  extractKeywords,
+  KeywordConfig,
+  SwapTable
+} from './src/keywords.js';
+export {
+  SymbolDict
+} from './src/dict.js';
+export {
+  Trie
+} from './src/trie.js';

package/package.json ADDED Viewed

@@ -0,0 +1,83 @@
+{
+  "name": "@tgies/megahal-js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.0",
+  "description": "A JavaScript port of the MegaHAL conversational engine supporting both Node.js and Browser environments.",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "engines": {
+    "node": ">= 20"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "index.d.ts.map",
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "src/**/*.d.ts.map",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:mutation": "stryker run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "build:types": "node scripts/clean-types.js && tsc --declaration --emitDeclarationOnly --noEmit false",
+    "check": "npm run lint && npm run typecheck && npm run test",
+    "prepare": "husky",
+    "prepack": "npm run build:types"
+  },
+  "keywords": [
+    "megahal",
+    "chatbot",
+    "markov",
+    "n-gram",
+    "conversational-ai"
+  ],
+  "author": "Tony Gies <tgies@tgies.net>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tgies/megahal-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tgies/megahal-js/issues"
+  },
+  "homepage": "https://github.com/tgies/megahal-js#readme",
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@commitlint/cli": "^20.4.3",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@eslint/js": "^10.0.1",
+    "@stryker-mutator/core": "^9.6.0",
+    "@stryker-mutator/vitest-runner": "^9.6.0",
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^10.0.3",
+    "globals": "^17.4.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.2",
+    "publint": "^0.3.2",
+    "typescript": "^6.0.3",
+    "vitest": "^3.0.0"
+  },
+  "lint-staged": {
+    "*.js": "eslint --fix"
+  },
+  "overrides": {
+    "fflate": "0.8.2"
+  }
+}

package/src/binary.d.ts ADDED Viewed

@@ -0,0 +1,18 @@
+/**
+ * Serialize a BidirectionalModel into a binary buffer.
+ *
+ * @param {import('./model.js').BidirectionalModel} model
+ * @param {{ use64Bit?: boolean }} [options] - Options for serialization
+ * @returns {Uint8Array}
+ */
+export function serializeBrain(model: import("./model.js").BidirectionalModel, options?: {
+    use64Bit?: boolean;
+}): Uint8Array;
+/**
+ * Deserialize binary brain data into a BidirectionalModel.
+ *
+ * @param {Uint8Array|ArrayBuffer} data
+ * @param {import('./model.js').BidirectionalModel} model
+ */
+export function deserializeBrain(data: Uint8Array | ArrayBuffer, model: import("./model.js").BidirectionalModel): void;
+//# sourceMappingURL=binary.d.ts.map

package/src/binary.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"binary.d.ts","sourceRoot":"","sources":["binary.js"],"names":[],"mappings":"AA0NA;;;;;;GAMG;AACH,sCAJW,OAAO,YAAY,EAAE,kBAAkB,YACvC;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GACpB,UAAU,CA2CtB;AAED;;;;;GAKG;AACH,uCAHW,UAAU,GAAC,WAAW,SACtB,OAAO,YAAY,EAAE,kBAAkB,QAuDjD"}

package/src/binary.js ADDED Viewed

@@ -0,0 +1,328 @@
+import { Trie, TrieNode } from './trie.js';
+import { SymbolDict } from './dict.js';
+const COOKIE = 'MegaHALv8';
+class BinaryWriter {
+  constructor() {
+    this.buffer = new Uint8Array(4096);
+    this.offset = 0;
+    this.view = new DataView(this.buffer.buffer);
+  }
+  /**
+   * Ensure the internal buffer is large enough.
+   * @private
+   * @param {number} size
+   */
+  _ensure(size) {
+    if (this.offset + size > this.buffer.byteLength) {
+      let newLength = this.buffer.byteLength * 2;
+      while (this.offset + size > newLength) {
+        newLength *= 2;
+      }
+      const newBuffer = new Uint8Array(newLength);
+      newBuffer.set(this.buffer);
+      this.buffer = newBuffer;
+      this.view = new DataView(this.buffer.buffer);
+    }
+  }
+  /**
+   * Write a uint8 byte.
+   * @param {number} val
+   */
+  writeUint8(val) {
+    this._ensure(1);
+    this.view.setUint8(this.offset, val);
+    this.offset += 1;
+  }
+  /**
+   * Write a uint16 word.
+   * @param {number} val
+   */
+  writeUint16(val) {
+    this._ensure(2);
+    this.view.setUint16(this.offset, val, true);
+    this.offset += 2;
+  }
+  /**
+   * Write a uint32 double word.
+   * @param {number} val
+   */
+  writeUint32(val) {
+    this._ensure(4);
+    this.view.setUint32(this.offset, val, true);
+    this.offset += 4;
+  }
+  /**
+   * Write a raw byte array.
+   * @param {Uint8Array} bytes
+   */
+  writeBytes(bytes) {
+    this._ensure(bytes.length);
+    this.buffer.set(bytes, this.offset);
+    this.offset += bytes.length;
+  }
+  /**
+   * Write a UTF-8 string.
+   * @param {string} str
+   */
+  writeString(str) {
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(str);
+    this.writeBytes(bytes);
+  }
+  /**
+   * Get the written contents as a Uint8Array.
+   * @returns {Uint8Array}
+   */
+  getUint8Array() {
+    return this.buffer.subarray(0, this.offset);
+  }
+}
+class BinaryReader {
+  /**
+   * @param {ArrayBuffer|Uint8Array} buffer
+   */
+  constructor(buffer) {
+    this.buffer = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+    this.view = new DataView(this.buffer.buffer, this.buffer.byteOffset, this.buffer.byteLength);
+    this.offset = 0;
+  }
+  /**
+   * Read a uint8 byte.
+   * @returns {number}
+   */
+  readUint8() {
+    const val = this.view.getUint8(this.offset);
+    this.offset += 1;
+    return val;
+  }
+  /**
+   * Read a uint16 word.
+   * @returns {number}
+   */
+  readUint16() {
+    const val = this.view.getUint16(this.offset, true);
+    this.offset += 2;
+    return val;
+  }
+  /**
+   * Read a uint32 double word.
+   * @returns {number}
+   */
+  readUint32() {
+    const val = this.view.getUint32(this.offset, true);
+    this.offset += 4;
+    return val;
+  }
+  /**
+   * Read raw bytes.
+   * @param {number} length
+   * @returns {Uint8Array}
+   */
+  readBytes(length) {
+    if (this.offset + length > this.buffer.byteLength) {
+      throw new Error('Unexpected end of file while reading bytes');
+    }
+    const bytes = this.buffer.subarray(this.offset, this.offset + length);
+    this.offset += length;
+    return bytes;
+  }
+  /**
+   * Read a UTF-8 string.
+   * @param {number} length
+   * @returns {string}
+   */
+  readString(length) {
+    const bytes = this.readBytes(length);
+    const decoder = new TextDecoder();
+    return decoder.decode(bytes);
+  }
+  /**
+   * Check if there are more bytes to read.
+   * @returns {boolean}
+   */
+  hasMore() {
+    return this.offset < this.buffer.byteLength;
+  }
+}
+/**
+ * Serialize a Trie node recursively.
+ * @param {Trie} trie
+ * @param {number} ref
+ * @param {BinaryWriter} writer
+ * @param {boolean} use64Bit
+ */
+function serializeNode(trie, ref, writer, use64Bit) {
+  const node = trie.node(ref);
+  writer.writeUint16(node.symbol);
+  if (use64Bit) {
+    writer.writeUint32(node.usage);
+    writer.writeUint32(0); // High 4 bytes
+  } else {
+    writer.writeUint32(node.usage);
+  }
+  writer.writeUint16(node.count);
+  writer.writeUint16(node.children.length);
+  for (const childRef of node.children) {
+    serializeNode(trie, childRef, writer, use64Bit);
+  }
+}
+/**
+ * Deserialize a Trie node recursively.
+ * @param {Trie} trie
+ * @param {BinaryReader} reader
+ * @param {number} byte4Size
+ * @returns {number} NodeRef
+ */
+function deserializeNode(trie, reader, byte4Size) {
+  const symbol = reader.readUint16();
+  const usage = reader.readUint32();
+  if (byte4Size === 8) {
+    reader.readUint32(); // Skip high 4 bytes
+  }
+  const count = reader.readUint16();
+  const branch = reader.readUint16();
+  const node = new TrieNode(symbol);
+  node.usage = usage;
+  node.count = count;
+  const ref = trie.nodes.length;
+  trie.nodes.push(node);
+  for (let i = 0; i < branch; i++) {
+    const childRef = deserializeNode(trie, reader, byte4Size);
+    node.children.push(childRef);
+  }
+  return ref;
+}
+/**
+ * Serialize a BidirectionalModel into a binary buffer.
+ *
+ * @param {import('./model.js').BidirectionalModel} model
+ * @param {{ use64Bit?: boolean }} [options] - Options for serialization
+ * @returns {Uint8Array}
+ */
+export function serializeBrain(model, options = {}) {
+  const use64Bit = !!options.use64Bit;
+  const writer = new BinaryWriter();
+  const cookieBytes = new TextEncoder().encode(COOKIE);
+  if (cookieBytes.length !== 9) {
+    throw new Error('Cookie size must be exactly 9 bytes');
+  }
+  writer.writeBytes(cookieBytes);
+  writer.writeUint8(model.order);
+  serializeNode(model.forward, model.forward.root(), writer, use64Bit);
+  serializeNode(model.backward, model.backward.root(), writer, use64Bit);
+  const dict = model.dictionary;
+  if (dict.entries.length > 65536) {
+    throw new RangeError(
+      `Dictionary size (${dict.entries.length}) exceeds maximum of 65536 symbols supported by the binary format`
+    );
+  }
+  if (use64Bit) {
+    writer.writeUint32(dict.entries.length);
+    writer.writeUint32(0); // High 4 bytes
+  } else {
+    writer.writeUint32(dict.entries.length);
+  }
+  for (let i = 0; i < dict.entries.length; i++) {
+    const word = dict.entries[i];
+    const wordBytes = new TextEncoder().encode(word);
+    if (wordBytes.length > 255) {
+      throw new Error(`Symbol '${word}' exceeds maximum byte size of 255`);
+    }
+    writer.writeUint8(wordBytes.length);
+    writer.writeBytes(wordBytes);
+  }
+  return writer.getUint8Array();
+}
+/**
+ * Deserialize binary brain data into a BidirectionalModel.
+ *
+ * @param {Uint8Array|ArrayBuffer} data
+ * @param {import('./model.js').BidirectionalModel} model
+ */
+export function deserializeBrain(data, model) {
+  const reader = new BinaryReader(data);
+  const cookie = reader.readString(9);
+  if (cookie !== COOKIE) {
+    throw new Error('Invalid brain file: Magic cookie mismatch');
+  }
+  const order = reader.readUint8();
+  model.order = order;
+  // Auto-detect byte4Size (4 or 8 bytes) by inspecting the root node of the forward tree.
+  let byte4Size = 4;
+  if (data.byteLength >= 24) {
+    const buffer = data instanceof Uint8Array ? data.buffer : data;
+    const byteOffset = data instanceof Uint8Array ? data.byteOffset : 0;
+    const byteLength = data.byteLength;
+    const view = new DataView(buffer, byteOffset, byteLength);
+    const branch4 = view.getUint16(18, true);
+    const branch8 = view.getUint16(22, true);
+    if (branch4 === 0 && branch8 > 0) {
+      byte4Size = 8;
+    }
+  }
+  model.forward = new Trie();
+  model.forward.nodes = []; // Clear default root
+  deserializeNode(model.forward, reader, byte4Size);
+  model.backward = new Trie();
+  model.backward.nodes = []; // Clear default root
+  deserializeNode(model.backward, reader, byte4Size);
+  const dictSize = reader.readUint32();
+  if (byte4Size === 8) {
+    reader.readUint32(); // Skip high 4 bytes of dictionary size
+  }
+  const dict = new SymbolDict();
+  dict.entries = [];
+  dict.sortedIndex = [];
+  for (let i = 0; i < dictSize; i++) {
+    const len = reader.readUint8();
+    const word = reader.readString(len);
+    dict.entries.push(word);
+    // Reconstruct sorted index using binary search insert position.
+    const { index } = dict._binarySearch(word);
+    dict.sortedIndex.splice(index, 0, i);
+  }
+  model.dictionary = dict;
+}