@takk/bayesoutputgate 1.0.0

package/dist/bayesfactor/index.cjs

@@ -0,0 +1,152 @@
+'use strict';
+
+// src/errors.ts
+var BayesOutputGateError = class _BayesOutputGateError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "BayesOutputGateError";
+    this.code = code;
+    Object.setPrototypeOf(this, _BayesOutputGateError.prototype);
+  }
+};
+function invariant(condition, code, message) {
+  if (!condition) {
+    throw new BayesOutputGateError(code, message);
+  }
+}
+
+// src/mathspecial.ts
+var LN_SQRT_2PI = 0.9189385332046728;
+var LANCZOS_G = 7;
+var LANCZOS_COEFFICIENTS = [
+  0.9999999999998099,
+  676.5203681218851,
+  -1259.1392167224028,
+  771.3234287776531,
+  -176.6150291621406,
+  12.507343278686905,
+  -0.13857109526572012,
+  9984369578019572e-21,
+  15056327351493116e-23
+];
+function lgamma(x) {
+  if (!Number.isFinite(x) || x <= 0) {
+    throw new BayesOutputGateError(
+      "NUMERIC",
+      `lgamma requires a positive finite argument, got ${x}`
+    );
+  }
+  const z = x - 1;
+  let acc = LANCZOS_COEFFICIENTS[0];
+  for (let i = 1; i < LANCZOS_COEFFICIENTS.length; i++) {
+    acc += LANCZOS_COEFFICIENTS[i] / (z + i);
+  }
+  const t = z + LANCZOS_G + 0.5;
+  return LN_SQRT_2PI + (z + 0.5) * Math.log(t) - t + Math.log(acc);
+}
+function lbeta(a, b) {
+  return lgamma(a) + lgamma(b) - lgamma(a + b);
+}
+function betaLogDensity(x, a, b) {
+  if (a <= 0 || b <= 0) {
+    throw new BayesOutputGateError(
+      "NUMERIC",
+      `Beta shape parameters must be positive, got a=${a}, b=${b}`
+    );
+  }
+  if (x < 0 || x > 1 || !Number.isFinite(x)) {
+    return Number.NEGATIVE_INFINITY;
+  }
+  if (x === 0) {
+    if (a < 1) return Number.POSITIVE_INFINITY;
+    if (a > 1) return Number.NEGATIVE_INFINITY;
+    return -lbeta(a, b) + (b - 1) * Math.log(1);
+  }
+  if (x === 1) {
+    if (b < 1) return Number.POSITIVE_INFINITY;
+    if (b > 1) return Number.NEGATIVE_INFINITY;
+    return -lbeta(a, b);
+  }
+  return (a - 1) * Math.log(x) + (b - 1) * Math.log1p(-x) - lbeta(a, b);
+}
+function clamp(x, lo, hi) {
+  if (x < lo) return lo;
+  if (x > hi) return hi;
+  return x;
+}
+
+// src/bayesfactor/index.ts
+var LN_3 = Math.log(3);
+var LN_10 = Math.log(10);
+var LN_100 = Math.log(100);
+var DENSITY_EPSILON = 1e-6;
+function jeffreysStrength(logBayesFactor) {
+  const x = logBayesFactor;
+  if (x >= LN_100) return "decisive-high";
+  if (x >= LN_10) return "strong-high";
+  if (x >= LN_3) return "substantial-high";
+  if (x > -LN_3) return "inconclusive";
+  if (x > -LN_10) return "substantial-low";
+  if (x > -LN_100) return "strong-low";
+  return "decisive-low";
+}
+function bayesFactor(scores, models) {
+  invariant(models.length > 0, "INVALID_CONFIG", "at least one dimension model is required");
+  const map = /* @__PURE__ */ new Map();
+  for (const s of scores) {
+    invariant(
+      Number.isFinite(s.value) && s.value >= 0 && s.value <= 1,
+      "INVALID_SCORE",
+      `score for "${s.dimension}" must be a finite number in [0, 1], got ${s.value}`
+    );
+    invariant(
+      !map.has(s.dimension),
+      "INVALID_SCORE",
+      `duplicate score for dimension "${s.dimension}"`
+    );
+    map.set(s.dimension, s.value);
+  }
+  const contributions = [];
+  let logBayesFactor = 0;
+  for (const model of models) {
+    const value = map.get(model.dimension);
+    if (value === void 0) {
+      continue;
+    }
+    invariant(
+      Number.isFinite(model.weight) && model.weight >= 0,
+      "INVALID_CONFIG",
+      `weight for "${model.dimension}" must be a non-negative finite number, got ${model.weight}`
+    );
+    const x = clamp(value, DENSITY_EPSILON, 1 - DENSITY_EPSILON);
+    const logHigh = betaLogDensity(x, model.high.a, model.high.b);
+    const logLow = betaLogDensity(x, model.low.a, model.low.b);
+    const weighted = model.weight * (logHigh - logLow);
+    logBayesFactor += weighted;
+    contributions.push({
+      dimension: model.dimension,
+      score: value,
+      logBayesFactor: weighted,
+      weight: model.weight
+    });
+  }
+  invariant(
+    contributions.length > 0,
+    "INVALID_SCORE",
+    "no scored dimension matched a configured dimension model"
+  );
+  invariant(Number.isFinite(logBayesFactor), "NUMERIC", "combined log-Bayes-Factor is not finite");
+  const strength = jeffreysStrength(logBayesFactor);
+  const favored = strength.endsWith("high") ? "high" : strength.endsWith("low") ? "low" : "inconclusive";
+  return {
+    logBayesFactor,
+    bayesFactor: Math.exp(logBayesFactor),
+    favored,
+    strength,
+    contributions
+  };
+}
+
+exports.bayesFactor = bayesFactor;
+exports.jeffreysStrength = jeffreysStrength;

package/dist/bayesfactor/index.d.cts

@@ -0,0 +1,15 @@
+import { S as ScoreVector, e as DimensionModel, a as BayesFactorResult, E as EvidenceStrength } from '../types-bMjn1j4e.cjs';
+
+/**
+ * Map a natural-log Bayes Factor to a Jeffreys-scale strength category (Jeffreys 1961, the symmetric
+ * boundaries 3, 10, 100). Positive favors high quality, negative favors low quality.
+ */
+declare function jeffreysStrength(logBayesFactor: number): EvidenceStrength;
+/**
+ * Weigh an output's scores against the high-quality and low-quality hypotheses. The combined
+ * log-Bayes-Factor is the weighted sum of per-dimension log-density differences. Only dimensions
+ * that have both a score and a model contribute.
+ */
+declare function bayesFactor(scores: ScoreVector, models: readonly DimensionModel[]): BayesFactorResult;
+
+export { bayesFactor, jeffreysStrength };

package/dist/bayesfactor/index.d.ts

@@ -0,0 +1,15 @@
+import { S as ScoreVector, e as DimensionModel, a as BayesFactorResult, E as EvidenceStrength } from '../types-bMjn1j4e.js';
+
+/**
+ * Map a natural-log Bayes Factor to a Jeffreys-scale strength category (Jeffreys 1961, the symmetric
+ * boundaries 3, 10, 100). Positive favors high quality, negative favors low quality.
+ */
+declare function jeffreysStrength(logBayesFactor: number): EvidenceStrength;
+/**
+ * Weigh an output's scores against the high-quality and low-quality hypotheses. The combined
+ * log-Bayes-Factor is the weighted sum of per-dimension log-density differences. Only dimensions
+ * that have both a score and a model contribute.
+ */
+declare function bayesFactor(scores: ScoreVector, models: readonly DimensionModel[]): BayesFactorResult;
+
+export { bayesFactor, jeffreysStrength };

package/dist/bayesfactor/index.js

@@ -0,0 +1,149 @@
+// src/errors.ts
+var BayesOutputGateError = class _BayesOutputGateError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "BayesOutputGateError";
+    this.code = code;
+    Object.setPrototypeOf(this, _BayesOutputGateError.prototype);
+  }
+};
+function invariant(condition, code, message) {
+  if (!condition) {
+    throw new BayesOutputGateError(code, message);
+  }
+}
+
+// src/mathspecial.ts
+var LN_SQRT_2PI = 0.9189385332046728;
+var LANCZOS_G = 7;
+var LANCZOS_COEFFICIENTS = [
+  0.9999999999998099,
+  676.5203681218851,
+  -1259.1392167224028,
+  771.3234287776531,
+  -176.6150291621406,
+  12.507343278686905,
+  -0.13857109526572012,
+  9984369578019572e-21,
+  15056327351493116e-23
+];
+function lgamma(x) {
+  if (!Number.isFinite(x) || x <= 0) {
+    throw new BayesOutputGateError(
+      "NUMERIC",
+      `lgamma requires a positive finite argument, got ${x}`
+    );
+  }
+  const z = x - 1;
+  let acc = LANCZOS_COEFFICIENTS[0];
+  for (let i = 1; i < LANCZOS_COEFFICIENTS.length; i++) {
+    acc += LANCZOS_COEFFICIENTS[i] / (z + i);
+  }
+  const t = z + LANCZOS_G + 0.5;
+  return LN_SQRT_2PI + (z + 0.5) * Math.log(t) - t + Math.log(acc);
+}
+function lbeta(a, b) {
+  return lgamma(a) + lgamma(b) - lgamma(a + b);
+}
+function betaLogDensity(x, a, b) {
+  if (a <= 0 || b <= 0) {
+    throw new BayesOutputGateError(
+      "NUMERIC",
+      `Beta shape parameters must be positive, got a=${a}, b=${b}`
+    );
+  }
+  if (x < 0 || x > 1 || !Number.isFinite(x)) {
+    return Number.NEGATIVE_INFINITY;
+  }
+  if (x === 0) {
+    if (a < 1) return Number.POSITIVE_INFINITY;
+    if (a > 1) return Number.NEGATIVE_INFINITY;
+    return -lbeta(a, b) + (b - 1) * Math.log(1);
+  }
+  if (x === 1) {
+    if (b < 1) return Number.POSITIVE_INFINITY;
+    if (b > 1) return Number.NEGATIVE_INFINITY;
+    return -lbeta(a, b);
+  }
+  return (a - 1) * Math.log(x) + (b - 1) * Math.log1p(-x) - lbeta(a, b);
+}
+function clamp(x, lo, hi) {
+  if (x < lo) return lo;
+  if (x > hi) return hi;
+  return x;
+}
+
+// src/bayesfactor/index.ts
+var LN_3 = Math.log(3);
+var LN_10 = Math.log(10);
+var LN_100 = Math.log(100);
+var DENSITY_EPSILON = 1e-6;
+function jeffreysStrength(logBayesFactor) {
+  const x = logBayesFactor;
+  if (x >= LN_100) return "decisive-high";
+  if (x >= LN_10) return "strong-high";
+  if (x >= LN_3) return "substantial-high";
+  if (x > -LN_3) return "inconclusive";
+  if (x > -LN_10) return "substantial-low";
+  if (x > -LN_100) return "strong-low";
+  return "decisive-low";
+}
+function bayesFactor(scores, models) {
+  invariant(models.length > 0, "INVALID_CONFIG", "at least one dimension model is required");
+  const map = /* @__PURE__ */ new Map();
+  for (const s of scores) {
+    invariant(
+      Number.isFinite(s.value) && s.value >= 0 && s.value <= 1,
+      "INVALID_SCORE",
+      `score for "${s.dimension}" must be a finite number in [0, 1], got ${s.value}`
+    );
+    invariant(
+      !map.has(s.dimension),
+      "INVALID_SCORE",
+      `duplicate score for dimension "${s.dimension}"`
+    );
+    map.set(s.dimension, s.value);
+  }
+  const contributions = [];
+  let logBayesFactor = 0;
+  for (const model of models) {
+    const value = map.get(model.dimension);
+    if (value === void 0) {
+      continue;
+    }
+    invariant(
+      Number.isFinite(model.weight) && model.weight >= 0,
+      "INVALID_CONFIG",
+      `weight for "${model.dimension}" must be a non-negative finite number, got ${model.weight}`
+    );
+    const x = clamp(value, DENSITY_EPSILON, 1 - DENSITY_EPSILON);
+    const logHigh = betaLogDensity(x, model.high.a, model.high.b);
+    const logLow = betaLogDensity(x, model.low.a, model.low.b);
+    const weighted = model.weight * (logHigh - logLow);
+    logBayesFactor += weighted;
+    contributions.push({
+      dimension: model.dimension,
+      score: value,
+      logBayesFactor: weighted,
+      weight: model.weight
+    });
+  }
+  invariant(
+    contributions.length > 0,
+    "INVALID_SCORE",
+    "no scored dimension matched a configured dimension model"
+  );
+  invariant(Number.isFinite(logBayesFactor), "NUMERIC", "combined log-Bayes-Factor is not finite");
+  const strength = jeffreysStrength(logBayesFactor);
+  const favored = strength.endsWith("high") ? "high" : strength.endsWith("low") ? "low" : "inconclusive";
+  return {
+    logBayesFactor,
+    bayesFactor: Math.exp(logBayesFactor),
+    favored,
+    strength,
+    contributions
+  };
+}
+
+export { bayesFactor, jeffreysStrength };

package/dist/beta/index.cjs

@@ -0,0 +1,180 @@
+'use strict';
+
+// src/errors.ts
+var BayesOutputGateError = class _BayesOutputGateError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "BayesOutputGateError";
+    this.code = code;
+    Object.setPrototypeOf(this, _BayesOutputGateError.prototype);
+  }
+};
+function invariant(condition, code, message) {
+  if (!condition) {
+    throw new BayesOutputGateError(code, message);
+  }
+}
+
+// src/mathspecial.ts
+var LN_SQRT_2PI = 0.9189385332046728;
+var LANCZOS_G = 7;
+var LANCZOS_COEFFICIENTS = [
+  0.9999999999998099,
+  676.5203681218851,
+  -1259.1392167224028,
+  771.3234287776531,
+  -176.6150291621406,
+  12.507343278686905,
+  -0.13857109526572012,
+  9984369578019572e-21,
+  15056327351493116e-23
+];
+function lgamma(x) {
+  if (!Number.isFinite(x) || x <= 0) {
+    throw new BayesOutputGateError(
+      "NUMERIC",
+      `lgamma requires a positive finite argument, got ${x}`
+    );
+  }
+  const z = x - 1;
+  let acc = LANCZOS_COEFFICIENTS[0];
+  for (let i = 1; i < LANCZOS_COEFFICIENTS.length; i++) {
+    acc += LANCZOS_COEFFICIENTS[i] / (z + i);
+  }
+  const t = z + LANCZOS_G + 0.5;
+  return LN_SQRT_2PI + (z + 0.5) * Math.log(t) - t + Math.log(acc);
+}
+function lbeta(a, b) {
+  return lgamma(a) + lgamma(b) - lgamma(a + b);
+}
+function betaLogDensity(x, a, b) {
+  if (a <= 0 || b <= 0) {
+    throw new BayesOutputGateError(
+      "NUMERIC",
+      `Beta shape parameters must be positive, got a=${a}, b=${b}`
+    );
+  }
+  if (x < 0 || x > 1 || !Number.isFinite(x)) {
+    return Number.NEGATIVE_INFINITY;
+  }
+  if (x === 0) {
+    if (a < 1) return Number.POSITIVE_INFINITY;
+    if (a > 1) return Number.NEGATIVE_INFINITY;
+    return -lbeta(a, b) + (b - 1) * Math.log(1);
+  }
+  if (x === 1) {
+    if (b < 1) return Number.POSITIVE_INFINITY;
+    if (b > 1) return Number.NEGATIVE_INFINITY;
+    return -lbeta(a, b);
+  }
+  return (a - 1) * Math.log(x) + (b - 1) * Math.log1p(-x) - lbeta(a, b);
+}
+function clamp(x, lo, hi) {
+  if (x < lo) return lo;
+  if (x > hi) return hi;
+  return x;
+}
+
+// src/beta/index.ts
+var VARIANCE_FLOOR = 1e-9;
+var CONCENTRATION_FLOOR = 1e-3;
+var BetaModel = class _BetaModel {
+  priorA;
+  priorB;
+  count = 0;
+  sum = 0;
+  sumSquares = 0;
+  constructor(options = {}) {
+    const prior = options.prior ?? { a: 1, b: 1 };
+    invariant(
+      prior.a > 0 && prior.b > 0 && Number.isFinite(prior.a) && Number.isFinite(prior.b),
+      "INVALID_CONFIG",
+      `prior Beta parameters must be positive and finite, got a=${prior.a}, b=${prior.b}`
+    );
+    this.priorA = prior.a;
+    this.priorB = prior.b;
+  }
+  /** Build a model from labeled scores in one pass. */
+  static fromSamples(samples, options = {}) {
+    const model = new _BetaModel(options);
+    for (const s of samples) {
+      model.observe(s);
+    }
+    return model;
+  }
+  /** Restore a model from a snapshot. */
+  static fromSnapshot(snapshot) {
+    const model = new _BetaModel({ prior: snapshot.prior });
+    invariant(
+      snapshot.count >= 0 && Number.isFinite(snapshot.sum) && Number.isFinite(snapshot.sumSquares),
+      "INVALID_SNAPSHOT",
+      "snapshot fields must be finite and non-negative"
+    );
+    model.count = snapshot.count;
+    model.sum = snapshot.sum;
+    model.sumSquares = snapshot.sumSquares;
+    return model;
+  }
+  /** Number of real observations folded into this model so far. */
+  get observations() {
+    return this.count;
+  }
+  /** Fold a single score in [0, 1] into the model, updating its calibration online. */
+  observe(score) {
+    invariant(
+      Number.isFinite(score) && score >= 0 && score <= 1,
+      "INVALID_SCORE",
+      `score must be a finite number in [0, 1], got ${score}`
+    );
+    this.count += 1;
+    this.sum += score;
+    this.sumSquares += score * score;
+    return this;
+  }
+  /**
+   * The fitted Beta parameters. The prior is mixed in as `priorA + priorB` pseudo-observations with
+   * the prior's own mean and variance, then a and b come from method of moments on the blend, so a
+   * cold model returns its prior and a warm model is data-driven.
+   */
+  params() {
+    const priorStrength = this.priorA + this.priorB;
+    const priorMean = this.priorA / priorStrength;
+    const priorVariance = priorMean * (1 - priorMean) / (priorStrength + 1);
+    const totalCount = this.count + priorStrength;
+    const totalSum = this.sum + priorStrength * priorMean;
+    const totalSumSquares = this.sumSquares + priorStrength * (priorVariance + priorMean * priorMean);
+    const mean = clamp(totalSum / totalCount, VARIANCE_FLOOR, 1 - VARIANCE_FLOOR);
+    const rawVariance = totalSumSquares / totalCount - mean * mean;
+    const maxVariance = mean * (1 - mean);
+    const variance = clamp(rawVariance, VARIANCE_FLOOR, maxVariance * (1 - VARIANCE_FLOOR));
+    const concentration = Math.max(mean * (1 - mean) / variance - 1, CONCENTRATION_FLOOR);
+    const a = Math.max(mean * concentration, CONCENTRATION_FLOOR);
+    const b = Math.max((1 - mean) * concentration, CONCENTRATION_FLOOR);
+    if (!Number.isFinite(a) || !Number.isFinite(b)) {
+      throw new BayesOutputGateError("NUMERIC", "Beta fit produced non-finite parameters");
+    }
+    return { a, b };
+  }
+  /** Mean of the fitted Beta. */
+  mean() {
+    const { a, b } = this.params();
+    return a / (a + b);
+  }
+  /** Log-density of an observed score under the fitted Beta. */
+  logDensity(score) {
+    const { a, b } = this.params();
+    return betaLogDensity(score, a, b);
+  }
+  /** A serializable snapshot of the current state. */
+  snapshot() {
+    return {
+      count: this.count,
+      sum: this.sum,
+      sumSquares: this.sumSquares,
+      prior: { a: this.priorA, b: this.priorB }
+    };
+  }
+};
+
+exports.BetaModel = BetaModel;

package/dist/beta/index.d.cts

@@ -0,0 +1,45 @@
+import { b as BetaParams } from '../types-bMjn1j4e.cjs';
+
+/** Options controlling the regularizing prior of a {@link BetaModel}. */
+interface BetaModelOptions {
+    /** Prior Beta acting as a regularizer. Defaults to the uniform Beta(1, 1). */
+    readonly prior?: BetaParams;
+}
+/** A serializable snapshot of a {@link BetaModel}, for persistence across processes. */
+interface BetaModelSnapshot {
+    readonly count: number;
+    readonly sum: number;
+    readonly sumSquares: number;
+    readonly prior: BetaParams;
+}
+/** A calibrated, online-updatable Beta model of a score under one hypothesis. */
+declare class BetaModel {
+    private readonly priorA;
+    private readonly priorB;
+    private count;
+    private sum;
+    private sumSquares;
+    constructor(options?: BetaModelOptions);
+    /** Build a model from labeled scores in one pass. */
+    static fromSamples(samples: Iterable<number>, options?: BetaModelOptions): BetaModel;
+    /** Restore a model from a snapshot. */
+    static fromSnapshot(snapshot: BetaModelSnapshot): BetaModel;
+    /** Number of real observations folded into this model so far. */
+    get observations(): number;
+    /** Fold a single score in [0, 1] into the model, updating its calibration online. */
+    observe(score: number): this;
+    /**
+     * The fitted Beta parameters. The prior is mixed in as `priorA + priorB` pseudo-observations with
+     * the prior's own mean and variance, then a and b come from method of moments on the blend, so a
+     * cold model returns its prior and a warm model is data-driven.
+     */
+    params(): BetaParams;
+    /** Mean of the fitted Beta. */
+    mean(): number;
+    /** Log-density of an observed score under the fitted Beta. */
+    logDensity(score: number): number;
+    /** A serializable snapshot of the current state. */
+    snapshot(): BetaModelSnapshot;
+}
+
+export { BetaModel, type BetaModelOptions, type BetaModelSnapshot };

package/dist/beta/index.d.ts

@@ -0,0 +1,45 @@
+import { b as BetaParams } from '../types-bMjn1j4e.js';
+
+/** Options controlling the regularizing prior of a {@link BetaModel}. */
+interface BetaModelOptions {
+    /** Prior Beta acting as a regularizer. Defaults to the uniform Beta(1, 1). */
+    readonly prior?: BetaParams;
+}
+/** A serializable snapshot of a {@link BetaModel}, for persistence across processes. */
+interface BetaModelSnapshot {
+    readonly count: number;
+    readonly sum: number;
+    readonly sumSquares: number;
+    readonly prior: BetaParams;
+}
+/** A calibrated, online-updatable Beta model of a score under one hypothesis. */
+declare class BetaModel {
+    private readonly priorA;
+    private readonly priorB;
+    private count;
+    private sum;
+    private sumSquares;
+    constructor(options?: BetaModelOptions);
+    /** Build a model from labeled scores in one pass. */
+    static fromSamples(samples: Iterable<number>, options?: BetaModelOptions): BetaModel;
+    /** Restore a model from a snapshot. */
+    static fromSnapshot(snapshot: BetaModelSnapshot): BetaModel;
+    /** Number of real observations folded into this model so far. */
+    get observations(): number;
+    /** Fold a single score in [0, 1] into the model, updating its calibration online. */
+    observe(score: number): this;
+    /**
+     * The fitted Beta parameters. The prior is mixed in as `priorA + priorB` pseudo-observations with
+     * the prior's own mean and variance, then a and b come from method of moments on the blend, so a
+     * cold model returns its prior and a warm model is data-driven.
+     */
+    params(): BetaParams;
+    /** Mean of the fitted Beta. */
+    mean(): number;
+    /** Log-density of an observed score under the fitted Beta. */
+    logDensity(score: number): number;
+    /** A serializable snapshot of the current state. */
+    snapshot(): BetaModelSnapshot;
+}
+
+export { BetaModel, type BetaModelOptions, type BetaModelSnapshot };