@storyteller-platform/align 0.1.9 → 0.1.11

package/dist/errorAlign/__tests__/native.test.js

@@ -0,0 +1,107 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { errorAlignBeamSearch as tsBeamSearch } from "../beamSearch.js";
+import {
+  computeErrorAlignDistanceMatrix as tsErrorAlign,
+  computeLevenshteinDistanceMatrix as tsLevenshtein
+} from "../editDistance.js";
+import { SubgraphMetadata } from "../graphMetadata.js";
+import {
+  computeErrorAlignDistanceMatrix as nativeErrorAlign,
+  computeLevenshteinDistanceMatrix as nativeLevenshtein,
+  errorAlignBeamSearch as nativeBeamSearch
+} from "../native.js";
+import { getAlignments } from "../pathToAlignment.js";
+import {
+  basicNormalizer,
+  basicTokenizer,
+  ensureLengthPreservation,
+  unpackRegexMatch
+} from "../utils.js";
+void describe("native C++ vs TypeScript implementations", () => {
+  void describe("Levenshtein distance matrix", () => {
+    void test("string input", () => {
+      const ref = "kitten";
+      const hyp = "sitting";
+      const tsResult = tsLevenshtein(ref, hyp);
+      const nativeResult = nativeLevenshtein(ref, hyp);
+      assert.deepStrictEqual(nativeResult, tsResult);
+    });
+    void test("string array input", () => {
+      const ref = ["hello", "world"];
+      const hyp = ["hello", "there"];
+      const tsResult = tsLevenshtein(ref, hyp);
+      const nativeResult = nativeLevenshtein(ref, hyp);
+      assert.deepStrictEqual(nativeResult, tsResult);
+    });
+    void test("with backtrace", () => {
+      const ref = "kitten";
+      const hyp = "sitting";
+      const tsResult = tsLevenshtein(ref, hyp, true);
+      const nativeResult = nativeLevenshtein(ref, hyp, true);
+      assert.deepStrictEqual(nativeResult, tsResult);
+    });
+  });
+  void describe("error align distance matrix", () => {
+    void test("string input", () => {
+      const ref = "test";
+      const hyp = "best";
+      const tsResult = tsErrorAlign(ref, hyp);
+      const nativeResult = nativeErrorAlign(ref, hyp);
+      assert.deepStrictEqual(nativeResult, tsResult);
+    });
+    void test("with backtrace", () => {
+      const ref = "test";
+      const hyp = "best";
+      const tsResult = tsErrorAlign(ref, hyp, true);
+      const nativeResult = nativeErrorAlign(ref, hyp, true);
+      assert.deepStrictEqual(nativeResult, tsResult);
+    });
+  });
+  void describe("beam search", () => {
+    function buildSubgraphMetadata(ref, hyp) {
+      const tokenizer = basicTokenizer;
+      const normalizer = basicNormalizer;
+      const unpackedTokenizer = unpackRegexMatch(tokenizer);
+      const ensuredNormalizer = ensureLengthPreservation(normalizer);
+      const refTokenMatches = unpackedTokenizer(ref);
+      const hypTokenMatches = unpackedTokenizer(hyp);
+      const refNorm = refTokenMatches.map(([r]) => ensuredNormalizer(r));
+      const hypNorm = hypTokenMatches.map(([h]) => ensuredNormalizer(h));
+      return new SubgraphMetadata(
+        ref,
+        hyp,
+        refTokenMatches,
+        hypTokenMatches,
+        refNorm,
+        hypNorm
+      );
+    }
+    void test("simple substitution", () => {
+      const src = buildSubgraphMetadata("hello", "jello");
+      const tsPath = tsBeamSearch(src);
+      const nativePath = nativeBeamSearch(src);
+      const tsAlignments = getAlignments(tsPath);
+      const nativeAlignments = getAlignments(nativePath);
+      assert.deepStrictEqual(nativeAlignments, tsAlignments);
+    });
+    void test("multi-word alignment with all op types", () => {
+      const ref = "This is a substitution test deleted.";
+      const hyp = "Inserted this is a contribution test.";
+      const src = buildSubgraphMetadata(ref, hyp);
+      const tsPath = tsBeamSearch(src);
+      const nativePath = nativeBeamSearch(src);
+      const tsAlignments = getAlignments(tsPath);
+      const nativeAlignments = getAlignments(nativePath);
+      assert.deepStrictEqual(nativeAlignments, tsAlignments);
+    });
+    void test("identical strings", () => {
+      const src = buildSubgraphMetadata("test words", "test words");
+      const tsPath = tsBeamSearch(src);
+      const nativePath = nativeBeamSearch(src);
+      const tsAlignments = getAlignments(tsPath);
+      const nativeAlignments = getAlignments(nativePath);
+      assert.deepStrictEqual(nativeAlignments, tsAlignments);
+    });
+  });
+});

package/dist/errorAlign/backtraceGraph.cjs

@@ -0,0 +1,298 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var backtraceGraph_exports = {};
+__export(backtraceGraph_exports, {
+  BacktraceGraph: () => BacktraceGraph,
+  Node: () => Node
+});
+module.exports = __toCommonJS(backtraceGraph_exports);
+var import_node_assert = __toESM(require("node:assert"), 1);
+var import_itertools = require("itertools");
+var import_utils = require("./utils.cjs");
+class Node {
+  constructor(hypIndex, refIndex) {
+    this.hypIndex = hypIndex;
+    this.refIndex = refIndex;
+  }
+  children = /* @__PURE__ */ new Map();
+  parents = /* @__PURE__ */ new Map();
+  get index() {
+    return [this.hypIndex, this.refIndex];
+  }
+  /**
+   * Get the offset index of th enode so indices match the hypothesis and reference strings.
+   *
+   * Root will be at (-1, -1).
+   */
+  get offsetIndex() {
+    return [this.hypIndex - 1, this.refIndex - 1];
+  }
+  /**
+   * Check if the node is a terminal node (i.e., it has no children).
+   */
+  get isTerminal() {
+    return this.children.size === 0;
+  }
+  /**
+   * Check if the node is a root node (i.e., it has no parents).
+   */
+  get isRoot() {
+    return this.parents.size === 0;
+  }
+}
+class NodeMap {
+  map;
+  constructor(entries) {
+    const keyedEntries = entries == null ? void 0 : entries.map(
+      ([index, node]) => [`${index[0]}-${index[1]}`, { index, node }]
+    );
+    this.map = new Map(keyedEntries);
+  }
+  get([hypIndex, refIndex]) {
+    var _a;
+    const key = `${hypIndex}-${refIndex}`;
+    return (_a = this.map.get(key)) == null ? void 0 : _a.node;
+  }
+  set([hypIndex, refIndex], node) {
+    const key = `${hypIndex}-${refIndex}`;
+    this.map.set(key, { index: [hypIndex, refIndex], node });
+  }
+  has([hypIndex, refIndex]) {
+    const key = `${hypIndex}-${refIndex}`;
+    return this.map.has(key);
+  }
+  *entries() {
+    for (const { index, node } of this.map.values()) {
+      yield [index, node];
+    }
+  }
+  *values() {
+    for (const { node } of this.map.values()) {
+      yield node;
+    }
+  }
+}
+class BacktraceGraph {
+  constructor(backtrackMatrix) {
+    this.backtrackMatrix = backtrackMatrix;
+    this.hypDim = backtrackMatrix.length;
+    this.refDim = backtrackMatrix[0].length;
+    this.hypMaxIndex = this.hypDim - 1;
+    this.refMaxIndex = this.refDim - 1;
+  }
+  hypDim;
+  refDim;
+  hypMaxIndex;
+  refMaxIndex;
+  _nodes = null;
+  /**
+   * Get the nodes in the graph.
+   */
+  get nodes() {
+    if (this._nodes) return this._nodes;
+    const terminalNode = new Node(this.hypMaxIndex, this.refMaxIndex);
+    this._nodes = new NodeMap([[terminalNode.index, terminalNode]]);
+    for (const index of this.iterTopologicalOrder({ reverse: true })) {
+      if (this._nodes.has(index) && (index[0] !== 0 || index[1] !== 0)) {
+        this.addParentsFromBacktrace(index);
+      }
+    }
+    this._nodes = new NodeMap(
+      Array.from(this._nodes.entries()).toSorted(([[a1, a2]], [[b1, b2]]) => {
+        if (a1 === b1) return a2 - b2;
+        return a1 - b1;
+      })
+    );
+    return this._nodes;
+  }
+  /**
+   * Get the node at the given index.
+   *
+   * @param hypIndex Hyp/row index.
+   * @param refIndex Ref/column index.
+   */
+  getNode(hypIndex, refIndex) {
+    return this.nodes.get([hypIndex, refIndex]);
+  }
+  /**
+   * Get the set of all node indices in the graph.
+   */
+  getNodeSet() {
+    const transitions = /* @__PURE__ */ new Set();
+    for (const node of this.nodes.values()) {
+      transitions.add(node.offsetIndex);
+    }
+    return transitions;
+  }
+  /**
+   * Get a path through the graph.
+   *
+   * @param sample If true, sample a path randomly based on transition probabilities.
+   *               Otherwise, return the first path deterministically.
+   * @returns A list of nodes representing the path.
+   */
+  getPath({ sample } = { sample: false }) {
+    let node = this.getNode(0, 0);
+    (0, import_node_assert.default)(node == null ? void 0 : node.isRoot, "The node at (-1, -1) was expected to be a root node.");
+    const path = [];
+    while (!node.isTerminal) {
+      const opType = sample ? choose(Array.from(node.children.keys())) : (
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        node.children.keys().next().value
+      );
+      node = node.children.get(opType);
+      path.push([opType, node]);
+    }
+  }
+  /**
+   * Get nodes that can only be accounted for by a match.
+   *
+   * @returns A list of index tuples representing the unambiguous node matches.
+   */
+  getUnambiguousNodeMatches() {
+    const matchIndices = /* @__PURE__ */ new Set();
+    const matchPerToken = {
+      ref: new import_utils.Counter(),
+      hyp: new import_utils.Counter()
+    };
+    const refOpTypes = /* @__PURE__ */ new Set(["MATCH", "SUBSTITUTE", "DELETE"]);
+    const hypOpTypes = /* @__PURE__ */ new Set(["MATCH", "SUBSTITUTE", "INSERT"]);
+    for (const [[hypIndex, refIndex], node] of this.nodes.entries()) {
+      if (node.parents.size === 1 && node.parents.has("MATCH")) {
+        matchIndices.add([hypIndex, refIndex]);
+      }
+      if (refOpTypes.intersection(node.parents).size) {
+        matchPerToken.ref.set(refIndex, matchPerToken.ref.get(refIndex) + 1);
+      }
+      if (hypOpTypes.intersection(node.parents).size) {
+        matchPerToken.hyp.set(hypIndex, matchPerToken.hyp.get(hypIndex) + 1);
+      }
+    }
+    const unambiguousMatches = [];
+    for (const [hypIndex, refIndex] of matchIndices) {
+      if (matchPerToken.ref.get(refIndex) === 1 && matchPerToken.hyp.get(hypIndex) === 1) {
+        unambiguousMatches.push([hypIndex - 1, refIndex - 1]);
+      }
+    }
+    return unambiguousMatches.toSorted(([_a, a], [_b, b]) => a - b);
+  }
+  /**
+   * Get word spans (i.e., <...>) that are unambiguously matched.
+   *
+   * That is, there is only one subpath that can account for the span using MATCH operations.
+   * Other subpaths that include INSERT, DELETE, SUBSTITUTE operations are not considered.
+   *
+   * @returns A list of index tuples representing the end node of unambiguous span matches.
+   */
+  getUnambiguousTokenSpanMatches(ref) {
+    var _a;
+    ref = "_" + ref;
+    const monoMatchEndNodes = /* @__PURE__ */ new Set();
+    const refIndexes = new import_utils.Counter();
+    const hypIndexes = new import_utils.Counter();
+    for (const [[hypIndex, refIndex], node] of this.nodes.entries()) {
+      if (!node.parents.has("MATCH") || ref[refIndex] !== import_utils.START_DELIMITER)
+        continue;
+      let _refIndex = refIndex + 1;
+      let _hypIndex = hypIndex + 1;
+      while (true) {
+        const _index = [_hypIndex, _refIndex];
+        if (!this.nodes.has(_index)) {
+          break;
+        }
+        if (!((_a = this.nodes.get(_index)) == null ? void 0 : _a.parents)) {
+          break;
+        }
+        if (ref[_refIndex] === import_utils.END_DELIMITER) {
+          const endIndex = _index;
+          monoMatchEndNodes.add(endIndex);
+          refIndexes.set(_refIndex, refIndexes.get(_refIndex) + 1);
+          hypIndexes.set(_hypIndex, hypIndexes.get(_hypIndex) + 1);
+          break;
+        }
+        _refIndex += 1;
+        _hypIndex += 1;
+      }
+    }
+    return new Set(
+      Array.from(monoMatchEndNodes).filter(([h, r]) => hypIndexes.get(h) === 1 && refIndexes.get(r) === 1).map(([h, r]) => [h - 1, r - 1])
+    );
+  }
+  /**
+   * Create a parent node based on the index of the current node and the operation type.
+   */
+  parentNodeFromOpType(index, opType) {
+    const hypIndex = opType !== "DELETE" ? index[0] - 1 : index[0];
+    const refIndex = opType !== "INSERT" ? index[1] - 1 : index[1];
+    const parentIndex = [hypIndex, refIndex];
+    const nodes = this._nodes;
+    (0, import_node_assert.default)(!!nodes, "Called parentIndexFromOpType before instantiating _nodes");
+    if (!nodes.has(parentIndex)) {
+      nodes.set(parentIndex, new Node(...parentIndex));
+    }
+    return nodes.get(parentIndex);
+  }
+  /**
+   * Iterate through the nodes in topological order.
+   */
+  *iterTopologicalOrder({ reverse } = { reverse: false }) {
+    for (const i of reverse ? (0, import_utils.reversed)((0, import_itertools.range)(this.hypDim)) : (0, import_itertools.range)(this.hypDim)) {
+      for (const j of reverse ? (0, import_utils.reversed)((0, import_itertools.range)(this.refDim)) : (0, import_itertools.range)(this.refDim)) {
+        yield [i, j];
+      }
+    }
+  }
+  /**
+   * Add parents to the node at the given index based on the backtrace matrix.
+   */
+  addParentsFromBacktrace(index) {
+    var _a;
+    const node = (_a = this._nodes) == null ? void 0 : _a.get(index);
+    (0, import_node_assert.default)(
+      !!node,
+      `Node at index ${index.toString()} does not exist in the graph.`
+    );
+    const opTypeComboCode = this.backtrackMatrix[node.hypIndex][node.refIndex];
+    const opTypeCombo = import_utils.OP_TYPE_COMBO_MAP[opTypeComboCode];
+    for (const opType of opTypeCombo) {
+      const parentNode = this.parentNodeFromOpType(node.index, opType);
+      node.parents.set(opType, parentNode);
+      parentNode.children.set(opType, node);
+    }
+  }
+}
+function choose(choices) {
+  const index = Math.round(Math.random() * choices.length);
+  return choices[index];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BacktraceGraph,
+  Node
+});

package/dist/errorAlign/backtraceGraph.d.cts

@@ -0,0 +1,103 @@
+import { OpType } from './utils.cjs';
+
+type Index = readonly [number, number];
+/**
+ * Node in the backtrace graph corresponding to the index (i, j) in the backtrace matrix.
+ */
+declare class Node {
+    hypIndex: number;
+    refIndex: number;
+    children: Map<OpType, Node>;
+    parents: Map<OpType, Node>;
+    constructor(hypIndex: number, refIndex: number);
+    get index(): Index;
+    /**
+     * Get the offset index of th enode so indices match the hypothesis and reference strings.
+     *
+     * Root will be at (-1, -1).
+     */
+    get offsetIndex(): Index;
+    /**
+     * Check if the node is a terminal node (i.e., it has no children).
+     */
+    get isTerminal(): boolean;
+    /**
+     * Check if the node is a root node (i.e., it has no parents).
+     */
+    get isRoot(): boolean;
+}
+declare class NodeMap {
+    private map;
+    constructor(entries?: readonly (readonly [Index, Node])[] | null);
+    get([hypIndex, refIndex]: Index): Node | undefined;
+    set([hypIndex, refIndex]: Index, node: Node): void;
+    has([hypIndex, refIndex]: Index): boolean;
+    entries(): Generator<readonly [Index, Node], void, unknown>;
+    values(): Generator<Node, void, unknown>;
+}
+/**
+ * Backtrace alignment graph
+ */
+declare class BacktraceGraph {
+    backtrackMatrix: number[][];
+    hypDim: number;
+    refDim: number;
+    hypMaxIndex: number;
+    refMaxIndex: number;
+    private _nodes;
+    constructor(backtrackMatrix: number[][]);
+    /**
+     * Get the nodes in the graph.
+     */
+    get nodes(): NodeMap;
+    /**
+     * Get the node at the given index.
+     *
+     * @param hypIndex Hyp/row index.
+     * @param refIndex Ref/column index.
+     */
+    getNode(hypIndex: number, refIndex: number): Node | undefined;
+    /**
+     * Get the set of all node indices in the graph.
+     */
+    getNodeSet(): Set<Index>;
+    /**
+     * Get a path through the graph.
+     *
+     * @param sample If true, sample a path randomly based on transition probabilities.
+     *               Otherwise, return the first path deterministically.
+     * @returns A list of nodes representing the path.
+     */
+    getPath({ sample }?: {
+        sample: boolean;
+    }): void;
+    /**
+     * Get nodes that can only be accounted for by a match.
+     *
+     * @returns A list of index tuples representing the unambiguous node matches.
+     */
+    getUnambiguousNodeMatches(): Index[];
+    /**
+     * Get word spans (i.e., <...>) that are unambiguously matched.
+     *
+     * That is, there is only one subpath that can account for the span using MATCH operations.
+     * Other subpaths that include INSERT, DELETE, SUBSTITUTE operations are not considered.
+     *
+     * @returns A list of index tuples representing the end node of unambiguous span matches.
+     */
+    getUnambiguousTokenSpanMatches(ref: string): Set<Index>;
+    /**
+     * Create a parent node based on the index of the current node and the operation type.
+     */
+    private parentNodeFromOpType;
+    /**
+     * Iterate through the nodes in topological order.
+     */
+    private iterTopologicalOrder;
+    /**
+     * Add parents to the node at the given index based on the backtrace matrix.
+     */
+    private addParentsFromBacktrace;
+}
+
+export { BacktraceGraph, type Index, Node };

package/dist/errorAlign/backtraceGraph.d.ts

@@ -0,0 +1,103 @@
+import { OpType } from './utils.js';
+
+type Index = readonly [number, number];
+/**
+ * Node in the backtrace graph corresponding to the index (i, j) in the backtrace matrix.
+ */
+declare class Node {
+    hypIndex: number;
+    refIndex: number;
+    children: Map<OpType, Node>;
+    parents: Map<OpType, Node>;
+    constructor(hypIndex: number, refIndex: number);
+    get index(): Index;
+    /**
+     * Get the offset index of th enode so indices match the hypothesis and reference strings.
+     *
+     * Root will be at (-1, -1).
+     */
+    get offsetIndex(): Index;
+    /**
+     * Check if the node is a terminal node (i.e., it has no children).
+     */
+    get isTerminal(): boolean;
+    /**
+     * Check if the node is a root node (i.e., it has no parents).
+     */
+    get isRoot(): boolean;
+}
+declare class NodeMap {
+    private map;
+    constructor(entries?: readonly (readonly [Index, Node])[] | null);
+    get([hypIndex, refIndex]: Index): Node | undefined;
+    set([hypIndex, refIndex]: Index, node: Node): void;
+    has([hypIndex, refIndex]: Index): boolean;
+    entries(): Generator<readonly [Index, Node], void, unknown>;
+    values(): Generator<Node, void, unknown>;
+}
+/**
+ * Backtrace alignment graph
+ */
+declare class BacktraceGraph {
+    backtrackMatrix: number[][];
+    hypDim: number;
+    refDim: number;
+    hypMaxIndex: number;
+    refMaxIndex: number;
+    private _nodes;
+    constructor(backtrackMatrix: number[][]);
+    /**
+     * Get the nodes in the graph.
+     */
+    get nodes(): NodeMap;
+    /**
+     * Get the node at the given index.
+     *
+     * @param hypIndex Hyp/row index.
+     * @param refIndex Ref/column index.
+     */
+    getNode(hypIndex: number, refIndex: number): Node | undefined;
+    /**
+     * Get the set of all node indices in the graph.
+     */
+    getNodeSet(): Set<Index>;
+    /**
+     * Get a path through the graph.
+     *
+     * @param sample If true, sample a path randomly based on transition probabilities.
+     *               Otherwise, return the first path deterministically.
+     * @returns A list of nodes representing the path.
+     */
+    getPath({ sample }?: {
+        sample: boolean;
+    }): void;
+    /**
+     * Get nodes that can only be accounted for by a match.
+     *
+     * @returns A list of index tuples representing the unambiguous node matches.
+     */
+    getUnambiguousNodeMatches(): Index[];
+    /**
+     * Get word spans (i.e., <...>) that are unambiguously matched.
+     *
+     * That is, there is only one subpath that can account for the span using MATCH operations.
+     * Other subpaths that include INSERT, DELETE, SUBSTITUTE operations are not considered.
+     *
+     * @returns A list of index tuples representing the end node of unambiguous span matches.
+     */
+    getUnambiguousTokenSpanMatches(ref: string): Set<Index>;
+    /**
+     * Create a parent node based on the index of the current node and the operation type.
+     */
+    private parentNodeFromOpType;
+    /**
+     * Iterate through the nodes in topological order.
+     */
+    private iterTopologicalOrder;
+    /**
+     * Add parents to the node at the given index based on the backtrace matrix.
+     */
+    private addParentsFromBacktrace;
+}
+
+export { BacktraceGraph, type Index, Node };