@tgies/megahal-js 1.0.0

package/src/evaluator.js

@@ -0,0 +1,101 @@
+/**
+ * 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, candidate, keywords) {
+  if (!candidate || candidate.length === 0) {
+    return 0.0;
+  }
+
+  let entropy = 0.0;
+  let num = 0;
+
+  // Forward evaluation.
+  const fwdCtx = model.forwardContext();
+  for (const token of candidate) {
+    const symId = model.dictionary.find(token);
+    if (symId === undefined) {
+      continue;
+    }
+
+    const upperToken = token.toUpperCase();
+    if (keywords.has(upperToken)) {
+      let probability = 0.0;
+      let ctxCount = 0;
+
+      for (let j = 0; j < model.order; j++) {
+        const parentRef = fwdCtx.atDepth(j);
+        if (parentRef !== null && parentRef !== undefined) {
+          const childRef = model.forward.findChild(parentRef, symId);
+          if (childRef !== undefined) {
+            const childNode = model.forward.node(childRef);
+            const parentNode = model.forward.node(parentRef);
+            if (parentNode.usage > 0) {
+              probability += childNode.count / parentNode.usage;
+              ctxCount++;
+            }
+          }
+        }
+      }
+
+      if (ctxCount > 0) {
+        entropy -= Math.log(probability / ctxCount);
+      }
+      num++;
+    }
+
+    fwdCtx.advance(model.forward, symId);
+  }
+
+  // Backward evaluation.
+  const bwdCtx = model.backwardContext();
+  for (let i = candidate.length - 1; i >= 0; i--) {
+    const token = candidate[i];
+    const symId = model.dictionary.find(token);
+    if (symId === undefined) {
+      continue;
+    }
+
+    const upperToken = token.toUpperCase();
+    if (keywords.has(upperToken)) {
+      let probability = 0.0;
+      let ctxCount = 0;
+
+      for (let j = 0; j < model.order; j++) {
+        const parentRef = bwdCtx.atDepth(j);
+        if (parentRef !== null && parentRef !== undefined) {
+          const childRef = model.backward.findChild(parentRef, symId);
+          if (childRef !== undefined) {
+            const childNode = model.backward.node(childRef);
+            const parentNode = model.backward.node(parentRef);
+            if (parentNode.usage > 0) {
+              probability += childNode.count / parentNode.usage;
+              ctxCount++;
+            }
+          }
+        }
+      }
+
+      if (ctxCount > 0) {
+        entropy -= Math.log(probability / ctxCount);
+      }
+      num++;
+    }
+
+    bwdCtx.advance(model.backward, symId);
+  }
+
+  // Length penalty.
+  if (num >= 8) {
+    entropy /= Math.sqrt(num - 1);
+  }
+  if (num >= 16) {
+    entropy /= num;
+  }
+
+  return entropy;
+}

package/src/generator.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Generate a single candidate reply (forward + backward phases).
+ *
+ * @param {BidirectionalModel} model
+ * @param {Set<string>} keywords
+ * @param {Set<string>} auxSet
+ * @param {any} rng
+ * @returns {string[]}
+ */
+export function generateOneReply(model: BidirectionalModel, keywords: Set<string>, auxSet: Set<string>, rng: any): string[];
+/**
+ * Generate the best reply for given input tokens and keywords.
+ * Runs the candidate generation loop for up to TIMEOUT milliseconds or ITERATIONS.
+ *
+ * @param {BidirectionalModel} model
+ * @param {string[]} inputTokens
+ * @param {Set<string>} keywords
+ * @param {Set<string>} auxSet
+ * @param {{ timeout?: number, maxIterations?: number }} limit
+ * @param {any} rng
+ * @returns {string[]}
+ */
+export function generateReply(model: BidirectionalModel, inputTokens: string[], keywords: Set<string>, auxSet: Set<string>, limit: {
+    timeout?: number;
+    maxIterations?: number;
+}, rng: any): string[];
+/**
+ * Capitalize a token sequence per MegaHAL sentence-case rules.
+ *
+ * @param {string[]} tokens
+ * @returns {string}
+ */
+export function capitalize(tokens: string[]): string;
+export type BidirectionalModel = import("./model.js").BidirectionalModel;
+export type ContextWindow = import("./model.js").ContextWindow;
+//# sourceMappingURL=generator.d.ts.map

package/src/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["generator.js"],"names":[],"mappings":"AAoHA;;;;;;;;GAQG;AACH,wCANW,kBAAkB,YAClB,GAAG,CAAC,MAAM,CAAC,UACX,GAAG,CAAC,MAAM,CAAC,OACX,GAAG,GACD,MAAM,EAAE,CA8DpB;AAoBD;;;;;;;;;;;GAWG;AACH,qCARW,kBAAkB,eAClB,MAAM,EAAE,YACR,GAAG,CAAC,MAAM,CAAC,UACX,GAAG,CAAC,MAAM,CAAC,SACX;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,OAC5C,GAAG,GACD,MAAM,EAAE,CA4CpB;AAED;;;;;GAKG;AACH,mCAHW,MAAM,EAAE,GACN,MAAM,CA8BlB;iCAnSY,OAAO,YAAY,EAAE,kBAAkB;4BACvC,OAAO,YAAY,EAAE,aAAa"}

package/src/generator.js

@@ -0,0 +1,296 @@
+import { ERROR_ID, FIN_ID } from './dict.js';
+import { evaluateReply } from './evaluator.js';
+
+/**
+ * @typedef {import('./model.js').BidirectionalModel} BidirectionalModel
+ * @typedef {import('./model.js').ContextWindow} ContextWindow
+ */
+
+/**
+ * Pick a random integer in [min, max) using the provided RNG.
+ * @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;
+}
+
+/**
+ * Select a seed symbol ID for forward generation.
+ *
+ * @param {BidirectionalModel} model
+ * @param {Set<string>} keywords
+ * @param {Set<string>} auxSet
+ * @param {any} rng
+ * @returns {number}
+ */
+function seed(model, keywords, auxSet, rng) {
+  const root = model.forward.root();
+  const children = model.forward.children(root);
+
+  if (children.length === 0) {
+    return ERROR_ID;
+  }
+
+  // If keywords exist, try to find a non-auxiliary keyword as seed.
+  if (keywords.size > 0) {
+    const keywordList = Array.from(keywords).sort();
+    const start = randomRange(rng, 0, keywordList.length);
+
+    for (let offset = 0; offset < keywordList.length; offset++) {
+      const idx = (start + offset) % keywordList.length;
+      const kw = keywordList[idx];
+
+      const id = model.dictionary.find(kw);
+      if (id !== undefined && !auxSet.has(kw)) {
+        return id;
+      }
+    }
+  }
+
+  // Default: pick a random child of the forward root.
+  const idx = randomRange(rng, 0, children.length);
+  return model.forward.node(children[idx]).symbol;
+}
+
+/**
+ * Keyword-biased random symbol selection (the "babble" function).
+ *
+ * @param {import('./trie.js').Trie} trie
+ * @param {ContextWindow} ctx
+ * @param {import('./dict.js').SymbolDict} dict
+ * @param {Set<string>} keywords
+ * @param {Set<string>} auxSet
+ * @param {number[]} reply - Array of symbol IDs currently in the reply
+ * @param {{ val: boolean }} usedKey - Object wrapper for usedKey boolean reference
+ * @param {any} rng
+ * @returns {number} Symbol ID
+ */
+function babble(trie, ctx, dict, keywords, auxSet, reply, usedKey, rng) {
+  const nodeRef = ctx.deepest();
+  if (nodeRef === null || nodeRef === undefined) {
+    return ERROR_ID;
+  }
+
+  const node = trie.node(nodeRef);
+  const children = trie.children(nodeRef);
+
+  if (children.length === 0 || node.usage === 0) {
+    return ERROR_ID;
+  }
+
+  const branch = children.length;
+  let i = randomRange(rng, 0, branch);
+  let count = randomRange(rng, 0, node.usage);
+
+  for (let step = 0; step < branch; step++) {
+    const childRef = children[i];
+    const child = trie.node(childRef);
+    const sym = child.symbol;
+
+    const word = dict.resolve(sym);
+    const isKeyword = keywords.has(word);
+    const isAux = auxSet.has(word);
+    const alreadyInReply = reply.includes(sym);
+
+    if (isKeyword && (usedKey.val || !isAux) && !alreadyInReply) {
+      usedKey.val = true;
+      return sym;
+    }
+
+    count -= child.count;
+    if (count < 0) {
+      return sym;
+    }
+
+    i = (i + 1) % branch;
+  }
+
+  return ERROR_ID;
+}
+
+/**
+ * Generate a single candidate reply (forward + backward phases).
+ *
+ * @param {BidirectionalModel} model
+ * @param {Set<string>} keywords
+ * @param {Set<string>} auxSet
+ * @param {any} rng
+ * @returns {string[]}
+ */
+export function generateOneReply(model, keywords, auxSet, rng) {
+  /** @type {number[]} */
+  const replyIds = [];
+  const usedKey = { val: false };
+
+  // Forward generation phase.
+  const fwdCtx = model.forwardContext();
+  const seedId = seed(model, keywords, auxSet, rng);
+
+  if (seedId !== ERROR_ID && seedId !== FIN_ID) {
+    replyIds.push(seedId);
+    fwdCtx.advance(model.forward, seedId);
+
+    while (true) {
+      const sym = babble(
+        model.forward,
+        fwdCtx,
+        model.dictionary,
+        keywords,
+        auxSet,
+        replyIds,
+        usedKey,
+        rng
+      );
+      if (sym === ERROR_ID || sym === FIN_ID) {
+        break;
+      }
+      replyIds.push(sym);
+      fwdCtx.advance(model.forward, sym);
+    }
+  }
+
+  // Backward generation phase.
+  const bwdCtx = model.backwardContext();
+  if (replyIds.length > 0) {
+    const start = Math.min(replyIds.length - 1, model.order);
+    for (let i = start; i >= 0; i--) {
+      bwdCtx.advance(model.backward, replyIds[i]);
+    }
+  }
+
+  while (true) {
+    const sym = babble(
+      model.backward,
+      bwdCtx,
+      model.dictionary,
+      keywords,
+      auxSet,
+      replyIds,
+      usedKey,
+      rng
+    );
+    if (sym === ERROR_ID || sym === FIN_ID) {
+      break;
+    }
+    replyIds.unshift(sym);
+    bwdCtx.advance(model.backward, sym);
+  }
+
+  return replyIds.map(id => model.dictionary.resolve(id));
+}
+
+/**
+ * Check if two token lists are equal (case-insensitive for MegaHAL comparison).
+ * @param {string[]} a
+ * @param {string[]} b
+ * @returns {boolean}
+ */
+function tokensEqual(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (a[i].toUpperCase() !== b[i].toUpperCase()) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Generate the best reply for given input tokens and keywords.
+ * Runs the candidate generation loop for up to TIMEOUT milliseconds or ITERATIONS.
+ *
+ * @param {BidirectionalModel} model
+ * @param {string[]} inputTokens
+ * @param {Set<string>} keywords
+ * @param {Set<string>} auxSet
+ * @param {{ timeout?: number, maxIterations?: number }} limit
+ * @param {any} rng
+ * @returns {string[]}
+ */
+export function generateReply(model, inputTokens, keywords, auxSet, limit, rng) {
+  const emptyKeywords = new Set();
+  const emptyAux = new Set();
+
+  // Establish a baseline reply without keyword bias.
+  let best = generateOneReply(model, emptyKeywords, emptyAux, rng);
+  if (tokensEqual(best, inputTokens)) {
+    best = [];
+  }
+
+  let maxSurprise = -1.0;
+  const start = Date.now();
+  let iterations = 0;
+
+  const timeout = limit.timeout !== undefined ? limit.timeout : 1000;
+  const maxIterations = limit.maxIterations !== undefined ? limit.maxIterations : 0;
+
+  while (true) {
+    if (timeout > 0 && Date.now() - start >= timeout) {
+      break;
+    }
+    if (maxIterations > 0 && iterations >= maxIterations) {
+      break;
+    }
+
+    const candidate = generateOneReply(model, keywords, auxSet, rng);
+    const surprise = evaluateReply(model, candidate, keywords);
+
+    if (surprise > maxSurprise && !tokensEqual(candidate, inputTokens)) {
+      maxSurprise = surprise;
+      best = candidate;
+    }
+
+    iterations++;
+
+    // If no limits are specified, perform at least one iteration.
+    if (timeout === 0 && maxIterations === 0) {
+      break;
+    }
+  }
+
+  return best;
+}
+
+/**
+ * Capitalize a token sequence per MegaHAL sentence-case rules.
+ *
+ * @param {string[]} tokens
+ * @returns {string}
+ */
+export function capitalize(tokens) {
+  const raw = tokens.join('');
+  /** @type {string[]} */
+  const result = [];
+  let start = true;
+
+  for (let i = 0; i < raw.length; i++) {
+    const char = raw[i];
+    if (/^[a-zA-Z]$/.test(char)) {
+      if (start) {
+        result.push(char.toUpperCase());
+      } else {
+        result.push(char.toLowerCase());
+      }
+      start = false;
+    } else {
+      result.push(char);
+    }
+
+    if (i > 2 && /^\s$/.test(char)) {
+      const prev = raw[i - 1];
+      if (prev === '!' || prev === '.' || prev === '?') {
+        start = true;
+      }
+    }
+  }
+
+  return result.join('');
+}

package/src/keywords.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Extract keywords from tokens based on MegaHAL's two-pass algorithm.
+ * @param {string[]} tokens
+ * @param {import('./dict.js').SymbolDict} dict
+ * @param {KeywordConfig} config
+ * @returns {Set<string>}
+ */
+export function extractKeywords(tokens: string[], dict: import("./dict.js").SymbolDict, config: KeywordConfig): Set<string>;
+/**
+ * Perspective-swapping substitution table.
+ */
+export class SwapTable {
+    /** @type {[string, string][]} Array of [from, to] swap pairs. */
+    pairs: [string, string][];
+    /**
+     * Apply swap substitutions to a token.
+     * Returns all matching "to" values. If no match, returns [token].
+     * @param {string} token
+     * @returns {string[]}
+     */
+    apply(token: string): string[];
+}
+/**
+ * Configuration for keyword extraction.
+ */
+export class KeywordConfig {
+    /** @type {Set<string>} Banned words (uppercase). */
+    banned: Set<string>;
+    /** @type {Set<string>} Auxiliary words (uppercase). */
+    auxiliary: Set<string>;
+    /** @type {SwapTable} Perspective-swapping table. */
+    swap: SwapTable;
+}
+//# sourceMappingURL=keywords.d.ts.map

package/src/keywords.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keywords.d.ts","sourceRoot":"","sources":["keywords.js"],"names":[],"mappings":"AAuFA;;;;;;GAMG;AACH,wCALW,MAAM,EAAE,QACR,OAAO,WAAW,EAAE,UAAU,UAC9B,aAAa,GACX,GAAG,CAAC,MAAM,CAAC,CA6BvB;AAxHD;;GAEG;AACH;IAEI,iEAAiE;IACjE,OADW,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CACd;IAGjB;;;;;OAKG;IACH,aAHW,MAAM,GACJ,MAAM,EAAE,CAiBpB;CACF;AAED;;GAEG;AACH;IAEI,oDAAoD;IACpD,QADW,GAAG,CAAC,MAAM,CAAC,CACC;IAEvB,uDAAuD;IACvD,WADW,GAAG,CAAC,MAAM,CAAC,CACI;IAE1B,oDAAoD;IACpD,MADW,SAAS,CACO;CAE9B"}

package/src/keywords.js

@@ -0,0 +1,122 @@
+
+/**
+ * Perspective-swapping substitution table.
+ */
+export class SwapTable {
+  constructor() {
+    /** @type {[string, string][]} Array of [from, to] swap pairs. */
+    this.pairs = [];
+  }
+
+  /**
+   * Apply swap substitutions to a token.
+   * Returns all matching "to" values. If no match, returns [token].
+   * @param {string} token
+   * @returns {string[]}
+   */
+  apply(token) {
+    const upperTok = token.toUpperCase();
+    /** @type {string[]} */
+    const results = [];
+
+    for (const [from, to] of this.pairs) {
+      if (from.toUpperCase() === upperTok) {
+        results.push(to.toUpperCase());
+      }
+    }
+
+    if (results.length === 0) {
+      return [upperTok];
+    }
+    return results;
+  }
+}
+
+/**
+ * Configuration for keyword extraction.
+ */
+export class KeywordConfig {
+  constructor() {
+    /** @type {Set<string>} Banned words (uppercase). */
+    this.banned = new Set();
+
+    /** @type {Set<string>} Auxiliary words (uppercase). */
+    this.auxiliary = new Set();
+
+    /** @type {SwapTable} Perspective-swapping table. */
+    this.swap = new SwapTable();
+  }
+}
+
+/**
+ * Checks if a candidate is eligible for keyword selection.
+ * @param {string} candidate
+ * @param {import('./dict.js').SymbolDict} dict
+ * @param {KeywordConfig} config
+ * @param {boolean} auxPass
+ * @returns {boolean}
+ */
+function isKeywordEligible(candidate, dict, config, auxPass) {
+  if (!candidate || candidate.length === 0) {
+    return false;
+  }
+
+  const firstChar = candidate[0];
+  if (!/^[A-Z0-9]$/.test(firstChar)) {
+    return false;
+  }
+
+  if (dict.find(candidate) === undefined) {
+    return false;
+  }
+
+  const upper = candidate.toUpperCase();
+
+  if (auxPass) {
+    return config.auxiliary.has(upper);
+  } else {
+    if (config.banned.has(upper)) {
+      return false;
+    }
+    if (config.auxiliary.has(upper)) {
+      return false;
+    }
+    return true;
+  }
+}
+
+/**
+ * Extract keywords from tokens based on MegaHAL's two-pass algorithm.
+ * @param {string[]} tokens
+ * @param {import('./dict.js').SymbolDict} dict
+ * @param {KeywordConfig} config
+ * @returns {Set<string>}
+ */
+export function extractKeywords(tokens, dict, config) {
+  /** @type {Set<string>} */
+  const keywords = new Set();
+
+  const candidates = tokens.map(tok => config.swap.apply(tok));
+
+  // Primary keyword selection pass.
+  for (const group of candidates) {
+    for (const candidate of group) {
+      if (isKeywordEligible(candidate, dict, config, false)) {
+        keywords.add(candidate);
+      }
+    }
+  }
+
+  // Auxiliary keyword selection pass (only if primary pass found matches).
+  if (keywords.size > 0) {
+    for (const group of candidates) {
+      for (const candidate of group) {
+        if (isKeywordEligible(candidate, dict, config, true)) {
+          keywords.add(candidate);
+        }
+      }
+    }
+  }
+
+  return keywords;
+}

package/src/model.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A sliding context window tracking position in an n-gram trie.
+ */
+export class ContextWindow {
+    /**
+     * @param {number} order - Markov model order
+     */
+    constructor(order: number);
+    order: number;
+    /** @type {(number|null)[]} Context slots matching the model order. */
+    slots: (number | null)[];
+    /**
+     * Reset the context window using the specified root reference.
+     * @param {number} rootRef
+     */
+    initialize(rootRef: number): void;
+    /**
+     * Update the context window without creating new trie nodes.
+     * @param {Trie} trie
+     * @param {number} symbolId
+     */
+    advance(trie: Trie, symbolId: number): void;
+    /**
+     * Update the context window, creating new trie nodes if necessary.
+     * @param {Trie} trie
+     * @param {number} symbolId
+     */
+    advanceAndLearn(trie: Trie, symbolId: number): void;
+    /**
+     * Get the context node at depth j.
+     * @param {number} j
+     * @returns {number|null}
+     */
+    atDepth(j: number): number | null;
+    /**
+     * 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(): number | null;
+}
+/**
+ * Bidirectional Markov model: forward trie + backward trie + shared dictionary.
+ */
+export class BidirectionalModel {
+    /**
+     * @param {number} order - Markov model order (default: 5)
+     */
+    constructor(order?: number);
+    order: number;
+    forward: Trie;
+    backward: Trie;
+    dictionary: SymbolDict;
+    /**
+     * Learn from a sequence of token strings.
+     * Skips learning if tokens.length <= order.
+     * @param {string[]} tokens
+     */
+    learn(tokens: string[]): void;
+    /**
+     * Create a context window initialized to the forward root.
+     * @returns {ContextWindow}
+     */
+    forwardContext(): ContextWindow;
+    /**
+     * Create a context window initialized to the backward root.
+     * @returns {ContextWindow}
+     */
+    backwardContext(): ContextWindow;
+}
+import { Trie } from './trie.js';
+import { SymbolDict } from './dict.js';
+//# sourceMappingURL=model.d.ts.map

package/src/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["model.js"],"names":[],"mappings":"AAGA;;GAEG;AACH;IACE;;OAEG;IACH,mBAFW,MAAM,EAMhB;IAHC,cAAkB;IAClB,sEAAsE;IACtE,OADW,CAAC,MAAM,GAAC,IAAI,CAAC,EAAE,CACkB;IAG9C;;;OAGG;IACH,oBAFW,MAAM,QAKhB;IAED;;;;OAIG;IACH,cAHW,IAAI,YACJ,MAAM,QAYhB;IAED;;;;OAIG;IACH,sBAHW,IAAI,YACJ,MAAM,QAWhB;IAED;;;;OAIG;IACH,WAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAOvB;IAED;;;;OAIG;IACH,WAFa,MAAM,GAAC,IAAI,CAUvB;CACF;AAED;;GAEG;AACH;IACE;;OAEG;IACH,oBAFW,MAAM,EAOhB;IAJC,cAAkB;IAClB,cAAyB;IACzB,eAA0B;IAC1B,uBAAkC;IAGpC;;;;OAIG;IACH,cAFW,MAAM,EAAE,QA6BlB;IAED;;;OAGG;IACH,kBAFa,aAAa,CAMzB;IAED;;;OAGG;IACH,mBAFa,aAAa,CAMzB;CACF;qBAzJoB,WAAW;2BACG,WAAW"}