@tgies/megahal-js 1.0.0

package/src/model.js

@@ -0,0 +1,154 @@
+import { Trie } from './trie.js';
+import { SymbolDict, FIN_ID } from './dict.js';
+
+/**
+ * A sliding context window tracking position in an n-gram trie.
+ */
+export class ContextWindow {
+  /**
+   * @param {number} order - Markov model order
+   */
+  constructor(order) {
+    this.order = order;
+    /** @type {(number|null)[]} Context slots matching the model order. */
+    this.slots = new Array(order + 2).fill(null);
+  }
+
+  /**
+   * Reset the context window using the specified root reference.
+   * @param {number} rootRef
+   */
+  initialize(rootRef) {
+    this.slots.fill(null);
+    this.slots[0] = rootRef;
+  }
+
+  /**
+   * Update the context window without creating new trie nodes.
+   * @param {Trie} trie
+   * @param {number} symbolId
+   */
+  advance(trie, symbolId) {
+    for (let d = this.order + 1; d >= 1; d--) {
+      const parent = this.slots[d - 1];
+      if (parent !== null && parent !== undefined) {
+        const child = trie.findChild(parent, symbolId);
+        this.slots[d] = child !== undefined ? child : null;
+      } else {
+        this.slots[d] = null;
+      }
+    }
+  }
+
+  /**
+   * Update the context window, creating new trie nodes if necessary.
+   * @param {Trie} trie
+   * @param {number} symbolId
+   */
+  advanceAndLearn(trie, symbolId) {
+    for (let d = this.order + 1; d >= 1; d--) {
+      const parent = this.slots[d - 1];
+      if (parent !== null && parent !== undefined) {
+        this.slots[d] = trie.addChild(parent, symbolId);
+      } else {
+        this.slots[d] = null;
+      }
+    }
+  }
+
+  /**
+   * Get the context node at depth j.
+   * @param {number} j
+   * @returns {number|null}
+   */
+  atDepth(j) {
+    if (j < 0 || j >= this.slots.length) {
+      return null;
+    }
+    return this.slots[j];
+  }
+
+  /**
+   * Get the deepest non-null context node.
+   * Scans from slot 0 up to slot `order` (inclusive), returning the last non-null.
+   * @returns {number|null}
+   */
+  deepest() {
+    let best = null;
+    for (let d = 0; d <= this.order; d++) {
+      if (this.slots[d] !== null && this.slots[d] !== undefined) {
+        best = this.slots[d];
+      }
+    }
+    return best;
+  }
+}
+
+/**
+ * Bidirectional Markov model: forward trie + backward trie + shared dictionary.
+ */
+export class BidirectionalModel {
+  /**
+   * @param {number} order - Markov model order (default: 5)
+   */
+  constructor(order = 5) {
+    this.order = order;
+    this.forward = new Trie();
+    this.backward = new Trie();
+    this.dictionary = new SymbolDict();
+  }
+
+  /**
+   * Learn from a sequence of token strings.
+   * Skips learning if tokens.length <= order.
+   * @param {string[]} tokens
+   */
+  learn(tokens) {
+    if (tokens.length <= this.order) {
+      return;
+    }
+
+    // Forward pass: learn the sequence in the forward trie.
+    const fwdCtx = new ContextWindow(this.order);
+    fwdCtx.initialize(this.forward.root());
+
+    /** @type {number[]} */
+    const symbolIds = [];
+    for (const tok of tokens) {
+      const id = this.dictionary.intern(tok);
+      symbolIds.push(id);
+      fwdCtx.advanceAndLearn(this.forward, id);
+    }
+    fwdCtx.advanceAndLearn(this.forward, FIN_ID);
+
+    // Backward pass: learn the reverse sequence in the backward trie.
+    const bwdCtx = new ContextWindow(this.order);
+    bwdCtx.initialize(this.backward.root());
+
+    for (let i = symbolIds.length - 1; i >= 0; i--) {
+      const id = symbolIds[i];
+      bwdCtx.advanceAndLearn(this.backward, id);
+    }
+    bwdCtx.advanceAndLearn(this.backward, FIN_ID);
+  }
+
+  /**
+   * Create a context window initialized to the forward root.
+   * @returns {ContextWindow}
+   */
+  forwardContext() {
+    const ctx = new ContextWindow(this.order);
+    ctx.initialize(this.forward.root());
+    return ctx;
+  }
+
+  /**
+   * Create a context window initialized to the backward root.
+   * @returns {ContextWindow}
+   */
+  backwardContext() {
+    const ctx = new ContextWindow(this.order);
+    ctx.initialize(this.backward.root());
+    return ctx;
+  }
+}

package/src/tokenizer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tokenize input text per MegaHAL rules.
+ *
+ * @param {string} input
+ * @returns {string[]}
+ */
+export function tokenize(input: string): string[];
+//# sourceMappingURL=tokenizer.d.ts.map

package/src/tokenizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenizer.d.ts","sourceRoot":"","sources":["tokenizer.js"],"names":[],"mappings":"AAmFA;;;;;GAKG;AACH,gCAHW,MAAM,GACJ,MAAM,EAAE,CAqCpB"}

package/src/tokenizer.js

@@ -0,0 +1,125 @@
+/**
+ * MegaHAL Tokenizer.
+ * Splits input text into an alternating sequence of word tokens and separator tokens.
+ */
+
+/**
+ * Checks if a character is ASCII alphabetic.
+ * @param {string} char
+ * @returns {boolean}
+ */
+function isAlpha(char) {
+  return typeof char === 'string' && char.length === 1 && /^[A-Z]$/.test(char);
+}
+
+/**
+ * Checks if a character is ASCII digit.
+ * @param {string} char
+ * @returns {boolean}
+ */
+function isDigit(char) {
+  return typeof char === 'string' && char.length === 1 && /^[0-9]$/.test(char);
+}
+
+/**
+ * Checks if a character is ASCII alphanumeric.
+ * @param {string} char
+ * @returns {boolean}
+ */
+function isAlphanumeric(char) {
+  return typeof char === 'string' && char.length === 1 && /^[A-Z0-9]$/.test(char);
+}
+
+/**
+ * Determine if position `pos` in the uppercase `input` string is a word boundary.
+ *
+ * Rules (from MEGAHAL_SPEC.md Section 4.1):
+ * 1. pos == 0: never a boundary
+ * 2. pos == len: always a boundary
+ * 3. Apostrophe rule: if char at pos is `'` and both neighbors are alpha, no boundary.
+ *    If char at pos-1 is `'` and both pos-2 and pos are alpha, no boundary.
+ * 4. Alpha transition: exactly one of pos and pos-1 is alphabetic -> boundary
+ * 5. Digit transition: digit status differs between pos and pos-1 -> boundary
+ *
+ * @param {string} input - Uppercase string
+ * @param {number} pos - 0-indexed position to test
+ * @returns {boolean}
+ */
+function isBoundary(input, pos) {
+  if (pos === 0) {
+    return false;
+  }
+  if (pos === input.length) {
+    return true;
+  }
+
+  const curr = input[pos];
+  const prev = input[pos - 1];
+
+  // Apostrophe rule.
+  if (curr === '\'' && pos + 1 < input.length && isAlpha(prev) && isAlpha(input[pos + 1])) {
+    return false;
+  }
+  if (prev === '\'' && pos >= 2 && isAlpha(input[pos - 2]) && isAlpha(curr)) {
+    return false;
+  }
+
+  // Alpha transition.
+  const currAlpha = isAlpha(curr);
+  const prevAlpha = isAlpha(prev);
+  if (currAlpha !== prevAlpha) {
+    return true;
+  }
+
+  // Digit transition.
+  const currDigit = isDigit(curr);
+  const prevDigit = isDigit(prev);
+  if (currDigit !== prevDigit) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Tokenize input text per MegaHAL rules.
+ *
+ * @param {string} input
+ * @returns {string[]}
+ */
+export function tokenize(input) {
+  if (!input || input.trim() === '') {
+    return ['.'];
+  }
+
+  const upper = input.toUpperCase();
+  /** @type {string[]} */
+  const tokens = [];
+  let start = 0;
+
+  for (let pos = 1; pos <= upper.length; pos++) {
+    if (isBoundary(upper, pos)) {
+      if (pos > start) {
+        tokens.push(upper.substring(start, pos));
+      }
+      start = pos;
+    }
+  }
+
+  if (tokens.length === 0) {
+    return ['.'];
+  }
+
+  // Sentence-terminal normalization.
+  const last = tokens[tokens.length - 1];
+  const firstChar = last[0];
+  const lastChar = last[last.length - 1];
+
+  if (isAlphanumeric(firstChar)) {
+    tokens.push('.');
+  } else if (lastChar !== '!' && lastChar !== '.' && lastChar !== '?') {
+    tokens[tokens.length - 1] = '.';
+  }
+
+  return tokens;
+}

package/src/trie.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Node in the frequency trie.
+ */
+export class TrieNode {
+    /**
+     * @param {number} symbolId
+     */
+    constructor(symbolId: number);
+    /** @type {number} Symbol ID. */
+    symbol: number;
+    /** @type {number} Total count of all child observations. */
+    usage: number;
+    /** @type {number} Observation count of this symbol in its parent's context. */
+    count: number;
+    /** @type {number[]} References to child nodes in the arena. */
+    children: number[];
+}
+/**
+ * Arena-based frequency trie.
+ */
+export class Trie {
+    /** @type {TrieNode[]} Arena storing all trie nodes (root at index 0). */
+    nodes: TrieNode[];
+    /**
+     * Get the root node reference (always index 0).
+     * @returns {number}
+     */
+    root(): number;
+    /**
+     * Helper to perform binary search on a parent node's children list.
+     * @private
+     * @param {number} parentRef - The index of the parent node in nodes.
+     * @param {number} symbolId - The symbol ID to search for.
+     * @returns {{ found: boolean, index: number }}
+     */
+    private _findChildIndex;
+    /**
+     * Find an existing child node of parent matching symbolId.
+     * Returns undefined if no such child exists.
+     * @param {number} parentRef
+     * @param {number} symbolId
+     * @returns {number|undefined}
+     */
+    findChild(parentRef: number, symbolId: number): number | undefined;
+    /**
+     * Find or create a child node of parent matching symbolId, incrementing counts.
+     * @param {number} parentRef
+     * @param {number} symbolId
+     * @returns {number} NodeRef (index in nodes arena)
+     */
+    addChild(parentRef: number, symbolId: number): number;
+    /**
+     * Get the children node references for a node.
+     * @param {number} parentRef
+     * @returns {number[]}
+     */
+    children(parentRef: number): number[];
+    /**
+     * Get the number of children of a node.
+     * @param {number} parentRef
+     * @returns {number}
+     */
+    branchCount(parentRef: number): number;
+    /**
+     * Access a node by its reference index.
+     * @param {number} ref
+     * @returns {TrieNode}
+     */
+    node(ref: number): TrieNode;
+    /**
+     * Total number of nodes in the trie (including root).
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Whether the trie contains only the root node.
+     * @returns {boolean}
+     */
+    isEmpty(): boolean;
+}
+//# sourceMappingURL=trie.d.ts.map

package/src/trie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trie.d.ts","sourceRoot":"","sources":["trie.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IACE;;OAEG;IACH,sBAFW,MAAM,EAchB;IAXC,gCAAgC;IAChC,QADW,MAAM,CACK;IAEtB,4DAA4D;IAC5D,OADW,MAAM,CACH;IAEd,+EAA+E;IAC/E,OADW,MAAM,CACH;IAEd,+DAA+D;IAC/D,UADW,MAAM,EAAE,CACD;CAErB;AAED;;GAEG;AACH;IAEI,yEAAyE;IACzE,OADW,QAAQ,EAAE,CACgB;IAGvC;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,wBAsBC;IAED;;;;;;OAMG;IACH,qBAJW,MAAM,YACN,MAAM,GACJ,MAAM,GAAC,SAAS,CAQ5B;IAED;;;;;OAKG;IACH,oBAJW,MAAM,YACN,MAAM,GACJ,MAAM,CAuBlB;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACJ,MAAM,EAAE,CAIpB;IAED;;;;OAIG;IACH,uBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,UAHW,MAAM,GACJ,QAAQ,CAOpB;IAED;;;OAGG;IACH,YAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,WAFa,OAAO,CAInB;CACF"}

package/src/trie.js

@@ -0,0 +1,164 @@
+import { ERROR_ID } from './dict.js';
+
+const U16_MAX = 65535;
+
+/**
+ * Node in the frequency trie.
+ */
+export class TrieNode {
+  /**
+   * @param {number} symbolId
+   */
+  constructor(symbolId) {
+    /** @type {number} Symbol ID. */
+    this.symbol = symbolId;
+
+    /** @type {number} Total count of all child observations. */
+    this.usage = 0;
+
+    /** @type {number} Observation count of this symbol in its parent's context. */
+    this.count = 0;
+
+    /** @type {number[]} References to child nodes in the arena. */
+    this.children = [];
+  }
+}
+
+/**
+ * Arena-based frequency trie.
+ */
+export class Trie {
+  constructor() {
+    /** @type {TrieNode[]} Arena storing all trie nodes (root at index 0). */
+    this.nodes = [new TrieNode(ERROR_ID)];
+  }
+
+  /**
+   * Get the root node reference (always index 0).
+   * @returns {number}
+   */
+  root() {
+    return 0;
+  }
+
+  /**
+   * Helper to perform binary search on a parent node's children list.
+   * @private
+   * @param {number} parentRef - The index of the parent node in nodes.
+   * @param {number} symbolId - The symbol ID to search for.
+   * @returns {{ found: boolean, index: number }}
+   */
+  _findChildIndex(parentRef, symbolId) {
+    const parentNode = this.nodes[parentRef];
+    const childrenRefs = parentNode.children;
+
+    let low = 0;
+    let high = childrenRefs.length - 1;
+
+    while (low <= high) {
+      const mid = (low + high) >> 1;
+      const childRef = childrenRefs[mid];
+      const childSym = this.nodes[childRef].symbol;
+
+      if (childSym < symbolId) {
+        low = mid + 1;
+      } else if (childSym > symbolId) {
+        high = mid - 1;
+      } else {
+        return { found: true, index: mid };
+      }
+    }
+
+    return { found: false, index: low };
+  }
+
+  /**
+   * Find an existing child node of parent matching symbolId.
+   * Returns undefined if no such child exists.
+   * @param {number} parentRef
+   * @param {number} symbolId
+   * @returns {number|undefined}
+   */
+  findChild(parentRef, symbolId) {
+    const { found, index } = this._findChildIndex(parentRef, symbolId);
+    if (found) {
+      return this.nodes[parentRef].children[index];
+    }
+    return undefined;
+  }
+
+  /**
+   * Find or create a child node of parent matching symbolId, incrementing counts.
+   * @param {number} parentRef
+   * @param {number} symbolId
+   * @returns {number} NodeRef (index in nodes arena)
+   */
+  addChild(parentRef, symbolId) {
+    const { found, index } = this._findChildIndex(parentRef, symbolId);
+
+    if (found) {
+      const childRef = this.nodes[parentRef].children[index];
+      const child = this.nodes[childRef];
+      if (child.count < U16_MAX) {
+        child.count++;
+        this.nodes[parentRef].usage++;
+      }
+      return childRef;
+    }
+
+    const childRef = this.nodes.length;
+    const newChild = new TrieNode(symbolId);
+    newChild.count = 1;
+    this.nodes.push(newChild);
+
+    this.nodes[parentRef].usage++;
+    this.nodes[parentRef].children.splice(index, 0, childRef);
+    return childRef;
+  }
+
+  /**
+   * Get the children node references for a node.
+   * @param {number} parentRef
+   * @returns {number[]}
+   */
+  children(parentRef) {
+    return this.nodes[parentRef].children;
+  }
+
+  /**
+   * Get the number of children of a node.
+   * @param {number} parentRef
+   * @returns {number}
+   */
+  branchCount(parentRef) {
+    return this.nodes[parentRef].children.length;
+  }
+
+  /**
+   * Access a node by its reference index.
+   * @param {number} ref
+   * @returns {TrieNode}
+   */
+  node(ref) {
+    if (ref < 0 || ref >= this.nodes.length) {
+      throw new RangeError(`Node reference ${ref} is out of bounds`);
+    }
+    return this.nodes[ref];
+  }
+
+  /**
+   * Total number of nodes in the trie (including root).
+   * @returns {number}
+   */
+  get size() {
+    return this.nodes.length;
+  }
+
+  /**
+   * Whether the trie contains only the root node.
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return this.nodes.length <= 1;
+  }
+}