@takk/bayesoutputgate 1.0.0

package/dist/hypothesis/index.cjs

@@ -0,0 +1,268 @@
+'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 }
+    };
+  }
+};
+
+// src/hypothesis/index.ts
+var HypothesisManager = class {
+  entries = /* @__PURE__ */ new Map();
+  defaultWeight;
+  defaultPriorHigh;
+  defaultPriorLow;
+  configured = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.defaultWeight = options.defaultWeight ?? 1;
+    this.defaultPriorHigh = options.defaultPriorHigh ?? { a: 2, b: 1 };
+    this.defaultPriorLow = options.defaultPriorLow ?? { a: 1, b: 2 };
+    invariant(
+      Number.isFinite(this.defaultWeight) && this.defaultWeight >= 0,
+      "INVALID_CONFIG",
+      `defaultWeight must be a non-negative finite number, got ${this.defaultWeight}`
+    );
+    for (const config of options.dimensions ?? []) {
+      this.configured.set(config.dimension, config);
+      this.ensure(config.dimension);
+    }
+  }
+  ensure(dimension) {
+    const existing = this.entries.get(dimension);
+    if (existing) {
+      return existing;
+    }
+    const config = this.configured.get(dimension);
+    const entry = {
+      high: new BetaModel({ prior: config?.priorHigh ?? this.defaultPriorHigh }),
+      low: new BetaModel({ prior: config?.priorLow ?? this.defaultPriorLow }),
+      weight: config?.weight ?? this.defaultWeight
+    };
+    invariant(
+      Number.isFinite(entry.weight) && entry.weight >= 0,
+      "INVALID_CONFIG",
+      `weight for "${dimension}" must be a non-negative finite number, got ${entry.weight}`
+    );
+    this.entries.set(dimension, entry);
+    return entry;
+  }
+  /** Fold one labeled output into the high or low model of each scored dimension. */
+  observe(observation) {
+    invariant(
+      observation.label === "high" || observation.label === "low",
+      "INVALID_OBSERVATION",
+      `observation label must be "high" or "low", got ${String(observation.label)}`
+    );
+    for (const score of observation.scores) {
+      const entry = this.ensure(score.dimension);
+      const model = observation.label === "high" ? entry.high : entry.low;
+      model.observe(score.value);
+    }
+    return this;
+  }
+  /** Fold a batch of labeled observations. */
+  fit(observations) {
+    for (const observation of observations) {
+      this.observe(observation);
+    }
+    return this;
+  }
+  /** The dimension names this manager currently tracks. */
+  get dimensions() {
+    return [...this.entries.keys()];
+  }
+  /** Snapshot the current calibrated models as the dimension models the Bayes Factor consumes. */
+  models() {
+    const out = [];
+    for (const [dimension, entry] of this.entries) {
+      out.push({
+        dimension,
+        high: entry.high.params(),
+        low: entry.low.params(),
+        weight: entry.weight
+      });
+    }
+    return out;
+  }
+  /** Number of labeled observations folded into a dimension under one hypothesis. */
+  observationCount(dimension, kind) {
+    const entry = this.entries.get(dimension);
+    if (!entry) {
+      return 0;
+    }
+    return (kind === "high" ? entry.high : entry.low).observations;
+  }
+};
+
+exports.HypothesisManager = HypothesisManager;

package/dist/hypothesis/index.d.cts

@@ -0,0 +1,38 @@
+import { b as BetaParams, L as LabeledObservation, e as DimensionModel } from '../types-bMjn1j4e.cjs';
+
+/** Per-dimension configuration: weight in the combined Bayes Factor and the two regularizing priors. */
+interface DimensionConfig {
+    readonly dimension: string;
+    readonly weight?: number;
+    readonly priorHigh?: BetaParams;
+    readonly priorLow?: BetaParams;
+}
+/** Options for a {@link HypothesisManager}. */
+interface HypothesisManagerOptions {
+    readonly dimensions?: readonly DimensionConfig[];
+    readonly defaultWeight?: number;
+    readonly defaultPriorHigh?: BetaParams;
+    readonly defaultPriorLow?: BetaParams;
+}
+/** Manages the high-quality and low-quality score models for every dimension. */
+declare class HypothesisManager {
+    private readonly entries;
+    private readonly defaultWeight;
+    private readonly defaultPriorHigh;
+    private readonly defaultPriorLow;
+    private readonly configured;
+    constructor(options?: HypothesisManagerOptions);
+    private ensure;
+    /** Fold one labeled output into the high or low model of each scored dimension. */
+    observe(observation: LabeledObservation): this;
+    /** Fold a batch of labeled observations. */
+    fit(observations: Iterable<LabeledObservation>): this;
+    /** The dimension names this manager currently tracks. */
+    get dimensions(): string[];
+    /** Snapshot the current calibrated models as the dimension models the Bayes Factor consumes. */
+    models(): DimensionModel[];
+    /** Number of labeled observations folded into a dimension under one hypothesis. */
+    observationCount(dimension: string, kind: "high" | "low"): number;
+}
+
+export { type DimensionConfig, HypothesisManager, type HypothesisManagerOptions };

package/dist/hypothesis/index.d.ts

@@ -0,0 +1,38 @@
+import { b as BetaParams, L as LabeledObservation, e as DimensionModel } from '../types-bMjn1j4e.js';
+
+/** Per-dimension configuration: weight in the combined Bayes Factor and the two regularizing priors. */
+interface DimensionConfig {
+    readonly dimension: string;
+    readonly weight?: number;
+    readonly priorHigh?: BetaParams;
+    readonly priorLow?: BetaParams;
+}
+/** Options for a {@link HypothesisManager}. */
+interface HypothesisManagerOptions {
+    readonly dimensions?: readonly DimensionConfig[];
+    readonly defaultWeight?: number;
+    readonly defaultPriorHigh?: BetaParams;
+    readonly defaultPriorLow?: BetaParams;
+}
+/** Manages the high-quality and low-quality score models for every dimension. */
+declare class HypothesisManager {
+    private readonly entries;
+    private readonly defaultWeight;
+    private readonly defaultPriorHigh;
+    private readonly defaultPriorLow;
+    private readonly configured;
+    constructor(options?: HypothesisManagerOptions);
+    private ensure;
+    /** Fold one labeled output into the high or low model of each scored dimension. */
+    observe(observation: LabeledObservation): this;
+    /** Fold a batch of labeled observations. */
+    fit(observations: Iterable<LabeledObservation>): this;
+    /** The dimension names this manager currently tracks. */
+    get dimensions(): string[];
+    /** Snapshot the current calibrated models as the dimension models the Bayes Factor consumes. */
+    models(): DimensionModel[];
+    /** Number of labeled observations folded into a dimension under one hypothesis. */
+    observationCount(dimension: string, kind: "high" | "low"): number;
+}
+
+export { type DimensionConfig, HypothesisManager, type HypothesisManagerOptions };

package/dist/hypothesis/index.js

@@ -0,0 +1,266 @@
+// 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 }
+    };
+  }
+};
+
+// src/hypothesis/index.ts
+var HypothesisManager = class {
+  entries = /* @__PURE__ */ new Map();
+  defaultWeight;
+  defaultPriorHigh;
+  defaultPriorLow;
+  configured = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.defaultWeight = options.defaultWeight ?? 1;
+    this.defaultPriorHigh = options.defaultPriorHigh ?? { a: 2, b: 1 };
+    this.defaultPriorLow = options.defaultPriorLow ?? { a: 1, b: 2 };
+    invariant(
+      Number.isFinite(this.defaultWeight) && this.defaultWeight >= 0,
+      "INVALID_CONFIG",
+      `defaultWeight must be a non-negative finite number, got ${this.defaultWeight}`
+    );
+    for (const config of options.dimensions ?? []) {
+      this.configured.set(config.dimension, config);
+      this.ensure(config.dimension);
+    }
+  }
+  ensure(dimension) {
+    const existing = this.entries.get(dimension);
+    if (existing) {
+      return existing;
+    }
+    const config = this.configured.get(dimension);
+    const entry = {
+      high: new BetaModel({ prior: config?.priorHigh ?? this.defaultPriorHigh }),
+      low: new BetaModel({ prior: config?.priorLow ?? this.defaultPriorLow }),
+      weight: config?.weight ?? this.defaultWeight
+    };
+    invariant(
+      Number.isFinite(entry.weight) && entry.weight >= 0,
+      "INVALID_CONFIG",
+      `weight for "${dimension}" must be a non-negative finite number, got ${entry.weight}`
+    );
+    this.entries.set(dimension, entry);
+    return entry;
+  }
+  /** Fold one labeled output into the high or low model of each scored dimension. */
+  observe(observation) {
+    invariant(
+      observation.label === "high" || observation.label === "low",
+      "INVALID_OBSERVATION",
+      `observation label must be "high" or "low", got ${String(observation.label)}`
+    );
+    for (const score of observation.scores) {
+      const entry = this.ensure(score.dimension);
+      const model = observation.label === "high" ? entry.high : entry.low;
+      model.observe(score.value);
+    }
+    return this;
+  }
+  /** Fold a batch of labeled observations. */
+  fit(observations) {
+    for (const observation of observations) {
+      this.observe(observation);
+    }
+    return this;
+  }
+  /** The dimension names this manager currently tracks. */
+  get dimensions() {
+    return [...this.entries.keys()];
+  }
+  /** Snapshot the current calibrated models as the dimension models the Bayes Factor consumes. */
+  models() {
+    const out = [];
+    for (const [dimension, entry] of this.entries) {
+      out.push({
+        dimension,
+        high: entry.high.params(),
+        low: entry.low.params(),
+        weight: entry.weight
+      });
+    }
+    return out;
+  }
+  /** Number of labeled observations folded into a dimension under one hypothesis. */
+  observationCount(dimension, kind) {
+    const entry = this.entries.get(dimension);
+    if (!entry) {
+      return 0;
+    }
+    return (kind === "high" ? entry.high : entry.low).observations;
+  }
+};
+
+export { HypothesisManager };