@takk/bayesoutputgate 1.0.0

package/dist/adapter/index.cjs

@@ -0,0 +1,411 @@
+'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
+  };
+}
+
+// src/policy/index.ts
+function posteriorHighQuality(logBayesFactor, priorHighQuality) {
+  invariant(
+    priorHighQuality > 0 && priorHighQuality < 1,
+    "INVALID_CONFIG",
+    `priorHighQuality must be in (0, 1), got ${priorHighQuality}`
+  );
+  invariant(
+    Number.isFinite(logBayesFactor),
+    "NUMERIC",
+    `logBayesFactor must be finite, got ${logBayesFactor}`
+  );
+  const logPosteriorOdds = logBayesFactor + Math.log(priorHighQuality / (1 - priorHighQuality));
+  if (logPosteriorOdds >= 0) {
+    return 1 / (1 + Math.exp(-logPosteriorOdds));
+  }
+  const odds = Math.exp(logPosteriorOdds);
+  return odds / (1 + odds);
+}
+function decide(logBayesFactor, policy) {
+  if (policy.kind === "bayes-factor") {
+    invariant(
+      policy.passAbove >= 1,
+      "INVALID_CONFIG",
+      `passAbove must be >= 1, got ${policy.passAbove}`
+    );
+    invariant(
+      policy.failBelow > 0 && policy.failBelow <= 1,
+      "INVALID_CONFIG",
+      `failBelow must be in (0, 1], got ${policy.failBelow}`
+    );
+    invariant(
+      policy.passAbove > policy.failBelow,
+      "INVALID_CONFIG",
+      "passAbove must be greater than failBelow"
+    );
+    const bayesFactor2 = Math.exp(logBayesFactor);
+    const action2 = bayesFactor2 >= policy.passAbove ? "pass" : bayesFactor2 <= policy.failBelow ? "fail" : "escalate";
+    return { action: action2, rationale: "bayes-factor" };
+  }
+  invariant(
+    policy.lossFalsePass >= 0 && policy.lossFalseFail >= 0 && policy.escalationCost >= 0,
+    "INVALID_CONFIG",
+    "decision-theoretic losses must be non-negative"
+  );
+  invariant(
+    Number.isFinite(policy.lossFalsePass) && Number.isFinite(policy.lossFalseFail) && Number.isFinite(policy.escalationCost),
+    "INVALID_CONFIG",
+    "decision-theoretic losses must be finite"
+  );
+  const posterior = posteriorHighQuality(logBayesFactor, policy.priorHighQuality);
+  const expectedLoss = {
+    pass: (1 - posterior) * policy.lossFalsePass,
+    fail: posterior * policy.lossFalseFail,
+    escalate: policy.escalationCost
+  };
+  let action = "pass";
+  let best = expectedLoss.pass;
+  if (expectedLoss.fail < best) {
+    action = "fail";
+    best = expectedLoss.fail;
+  }
+  if (expectedLoss.escalate < best) {
+    action = "escalate";
+  }
+  return { action, rationale: "expected-loss", posteriorHighQuality: posterior, expectedLoss };
+}
+
+// src/gate/index.ts
+function toDecision(factor, policy, guards) {
+  const base = {
+    action: policy.action,
+    bayesFactor: factor.bayesFactor,
+    logBayesFactor: factor.logBayesFactor,
+    strength: factor.strength,
+    rationale: policy.rationale,
+    contributions: factor.contributions,
+    ...policy.posteriorHighQuality !== void 0 ? { posteriorHighQuality: policy.posteriorHighQuality } : {},
+    ...policy.expectedLoss !== void 0 ? { expectedLoss: policy.expectedLoss } : {}
+  };
+  {
+    return base;
+  }
+}
+function evaluate(scores, models, policy, guards) {
+  const factor = bayesFactor(scores, models);
+  const decision = decide(factor.logBayesFactor, policy);
+  return toDecision(factor, decision);
+}
+
+// src/adapter/index.ts
+var TOOL_NAME = "bayes_output_gate";
+var DEFAULT_POLICY = { kind: "bayes-factor", passAbove: 10, failBelow: 0.1 };
+function toJsonSafe(value) {
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => toJsonSafe(item));
+  }
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+      out[key] = toJsonSafe(item);
+    }
+    return out;
+  }
+  return value;
+}
+function asObject(value, message) {
+  invariant(
+    typeof value === "object" && value !== null && !Array.isArray(value),
+    "INVALID_CONFIG",
+    message
+  );
+  return value;
+}
+function parseBeta(value, where) {
+  const obj = asObject(value, `${where} must be an object with positive a and b`);
+  const a = obj["a"];
+  const b = obj["b"];
+  invariant(
+    typeof a === "number" && typeof b === "number" && a > 0 && b > 0,
+    "INVALID_CONFIG",
+    `${where} must have positive numeric a and b`
+  );
+  return { a, b };
+}
+function parseScore(value) {
+  const obj = asObject(value, "each score must be an object with dimension and value");
+  const dimension = obj["dimension"];
+  const score = obj["value"];
+  invariant(
+    typeof dimension === "string" && dimension.length > 0,
+    "INVALID_SCORE",
+    "score dimension must be a non-empty string"
+  );
+  invariant(
+    typeof score === "number" && Number.isFinite(score) && score >= 0 && score <= 1,
+    "INVALID_SCORE",
+    `score value for "${dimension}" must be a finite number in [0, 1]`
+  );
+  return { dimension, value: score };
+}
+function parseModel(value) {
+  const obj = asObject(value, "each model must be an object");
+  const dimension = obj["dimension"];
+  invariant(
+    typeof dimension === "string" && dimension.length > 0,
+    "INVALID_CONFIG",
+    "model dimension must be a non-empty string"
+  );
+  const rawWeight = obj["weight"];
+  const weight = rawWeight === void 0 ? 1 : rawWeight;
+  invariant(
+    typeof weight === "number" && Number.isFinite(weight) && weight >= 0,
+    "INVALID_CONFIG",
+    `model weight for "${dimension}" must be a non-negative number`
+  );
+  return {
+    dimension,
+    high: parseBeta(obj["high"], `model "${dimension}" high`),
+    low: parseBeta(obj["low"], `model "${dimension}" low`),
+    weight
+  };
+}
+function parsePolicy(value) {
+  if (value === void 0) {
+    return DEFAULT_POLICY;
+  }
+  const obj = asObject(value, "policy must be an object");
+  const kind = obj["kind"];
+  if (kind === "decision-theoretic") {
+    const prior = obj["priorHighQuality"];
+    const lossFalsePass = obj["lossFalsePass"];
+    const lossFalseFail = obj["lossFalseFail"];
+    const escalationCost = obj["escalationCost"];
+    invariant(
+      typeof prior === "number" && typeof lossFalsePass === "number" && typeof lossFalseFail === "number" && typeof escalationCost === "number",
+      "INVALID_CONFIG",
+      "decision-theoretic policy requires numeric priorHighQuality, lossFalsePass, lossFalseFail, escalationCost"
+    );
+    return {
+      kind: "decision-theoretic",
+      priorHighQuality: prior,
+      lossFalsePass,
+      lossFalseFail,
+      escalationCost
+    };
+  }
+  invariant(kind === "bayes-factor", "INVALID_CONFIG", `unknown policy kind ${String(kind)}`);
+  const passAbove = obj["passAbove"];
+  const failBelow = obj["failBelow"];
+  invariant(
+    typeof passAbove === "number" && typeof failBelow === "number",
+    "INVALID_CONFIG",
+    "bayes-factor policy requires numeric passAbove and failBelow"
+  );
+  return { kind: "bayes-factor", passAbove, failBelow };
+}
+function parseGateInput(input) {
+  const obj = asObject(input, "tool input must be an object");
+  invariant(Array.isArray(obj["scores"]), "INVALID_SCORE", "scores must be an array");
+  invariant(Array.isArray(obj["models"]), "INVALID_CONFIG", "models must be an array");
+  const scores = obj["scores"].map(parseScore);
+  const models = obj["models"].map(parseModel);
+  invariant(models.length > 0, "INVALID_CONFIG", "at least one model is required");
+  return { scores, models, policy: parsePolicy(obj["policy"]) };
+}
+function runTool(input) {
+  const { scores, models, policy } = parseGateInput(input);
+  return evaluate(scores, models, policy);
+}
+function describeTool() {
+  return {
+    name: TOOL_NAME,
+    description: "Weigh an output's per-dimension quality scores against a high-quality and a low-quality hypothesis with a calibrated Bayes Factor, and return a pass, fail, or escalate decision on the Jeffreys scale.",
+    inputSchema: {
+      type: "object",
+      required: ["scores", "models"],
+      properties: {
+        scores: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["dimension", "value"],
+            properties: {
+              dimension: { type: "string" },
+              value: { type: "number", minimum: 0, maximum: 1 }
+            }
+          }
+        },
+        models: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["dimension", "high", "low"],
+            properties: {
+              dimension: { type: "string" },
+              high: { type: "object", required: ["a", "b"] },
+              low: { type: "object", required: ["a", "b"] },
+              weight: { type: "number", minimum: 0 }
+            }
+          }
+        },
+        policy: { type: "object" }
+      }
+    }
+  };
+}
+var bayesOutputGateTool = {
+  ...describeTool(),
+  handler: (input) => toJsonSafe(runTool(input))
+};
+
+exports.TOOL_NAME = TOOL_NAME;
+exports.bayesOutputGateTool = bayesOutputGateTool;
+exports.describeTool = describeTool;
+exports.parseGateInput = parseGateInput;
+exports.runTool = runTool;
+exports.toJsonSafe = toJsonSafe;

package/dist/adapter/index.d.cts

@@ -0,0 +1,29 @@
+import { Q as QualityScore, e as DimensionModel, P as PolicyConfig, g as GateDecision } from '../types-bMjn1j4e.cjs';
+
+/** The tool name an MCP server or LLM tool-calling API registers. */
+declare const TOOL_NAME = "bayes_output_gate";
+/** Recursively replace non-finite numbers with null so the value is safe to JSON-serialize. */
+declare function toJsonSafe(value: unknown): unknown;
+/** Defensively parse tool input from a model into validated scores, models, and policy. */
+declare function parseGateInput(input: unknown): {
+    scores: QualityScore[];
+    models: DimensionModel[];
+    policy: PolicyConfig;
+};
+/** Run the gate from raw tool input and return the decision. */
+declare function runTool(input: unknown): GateDecision;
+/** The JSON Schema descriptor an MCP server or tool-calling API registers. */
+declare function describeTool(): {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+};
+/** The framework-agnostic tool: descriptor plus a JSON-safe handler. */
+declare const bayesOutputGateTool: {
+    handler: (input: unknown) => unknown;
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+};
+
+export { TOOL_NAME, bayesOutputGateTool, describeTool, parseGateInput, runTool, toJsonSafe };

package/dist/adapter/index.d.ts

@@ -0,0 +1,29 @@
+import { Q as QualityScore, e as DimensionModel, P as PolicyConfig, g as GateDecision } from '../types-bMjn1j4e.js';
+
+/** The tool name an MCP server or LLM tool-calling API registers. */
+declare const TOOL_NAME = "bayes_output_gate";
+/** Recursively replace non-finite numbers with null so the value is safe to JSON-serialize. */
+declare function toJsonSafe(value: unknown): unknown;
+/** Defensively parse tool input from a model into validated scores, models, and policy. */
+declare function parseGateInput(input: unknown): {
+    scores: QualityScore[];
+    models: DimensionModel[];
+    policy: PolicyConfig;
+};
+/** Run the gate from raw tool input and return the decision. */
+declare function runTool(input: unknown): GateDecision;
+/** The JSON Schema descriptor an MCP server or tool-calling API registers. */
+declare function describeTool(): {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+};
+/** The framework-agnostic tool: descriptor plus a JSON-safe handler. */
+declare const bayesOutputGateTool: {
+    handler: (input: unknown) => unknown;
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+};
+
+export { TOOL_NAME, bayesOutputGateTool, describeTool, parseGateInput, runTool, toJsonSafe };