oracular 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.8.0
+
+### Minor Changes
+
+- [#44](https://github.com/Yuribenjamin/oracular/pull/44) [`912f60d`](https://github.com/Yuribenjamin/oracular/commit/912f60da297fe01a64decc1f91916cdcd3a98c60) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **Exact lower bound.** `RevealOptions.bound: 'exact'` makes `lower` the Beta distribution's own quantile at the one-sided level `z` names (Φ(−z), so 1.28 is still a 90% bound) instead of the normal approximation p − z·sd, which is optimistic exactly where the gate matters: thin evidence near the threshold. Beta(4, 3) puts p at 0.571, the approximation at 0.347 and the exact tenth percentile at 0.333; by Beta(30, 20) the two agree to a thousandth. `predict`, `shouldReveal`, `evaluate`, the recorder and `evidenceToReveal` all follow the option, resolved per call → intent → engine → default like the others, and the config schema lists it. Nothing moves unless it is set: every state and every number without `bound` is exactly what it was. Under `'exact'`, `z: 0` is the median rather than the mean, and `lower` can sit above `p` for a prior near 1 with little strength. A stored config that sets `bound` is read by 0.8 and later; 0.7 throws a `TypeError` on the unknown key, so drop the option before rolling a deploy back. The state version is unchanged. The quantile costs 0.54 kB: the core goes from 6.65 kB to 7.19 kB minified and gzipped, past the 7 kB ceiling the stability page set, so the ceiling moves once, to 7.9 kB (the shipped size plus about 10%), and the quickstart budget from 3.9 kB to 4.5 kB; the stability page records the decision.
+
 ## 0.7.1
 
 ### Patch Changes

package/README.md

@@ -140,7 +140,7 @@ Learned counts never decay unless you set `learning.halfLife`.
 
 ### Reveal only when confident
 
-`shouldReveal` is true when p ≥ threshold **and** p − z·sd ≥ threshold, where sd is the Beta standard deviation and z defaults to 1.28 (a one-sided 90% bound). Thin evidence with a high mean does not fire; it takes a few consistent signals. After you `markRevealed`, the intent stays revealed for a `cooldown` (default: its half-life) so you don't fire on every event. The same cooldown runs after the intent's outcome event. `predict` reports both: `revealed` is true inside a reveal cooldown, and `suppressedUntil` is when the later of the two cooldowns ends, or null when `shouldReveal` is free to fire.
+`shouldReveal` is true when p ≥ threshold **and** p − z·sd ≥ threshold, where sd is the Beta standard deviation and z defaults to 1.28 (a one-sided 90% bound). Thin evidence with a high mean does not fire; it takes a few consistent signals. That lower bound is a normal approximation; `bound: 'exact'` swaps in the Beta distribution's own quantile at the same level, which asks for a little more on thin evidence. After you `markRevealed`, the intent stays revealed for a `cooldown` (default: its half-life) so you don't fire on every event. The same cooldown runs after the intent's outcome event. `predict` reports both: `revealed` is true inside a reveal cooldown, and `suppressedUntil` is when the later of the two cooldowns ends, or null when `shouldReveal` is free to fire.
 
 ### Outcomes reset the slate and pause reveals
 
@@ -299,6 +299,7 @@ interface RevealOptions {
   threshold?: number;  // default 0.5
   z?: number;          // default 1.28
   cooldown?: number;   // default: the intent's halfLife
+  bound?: 'normal' | 'exact';  // default 'normal': p − z·sd; 'exact': the Beta quantile at Φ(−z)
 }
 ```
 
@@ -311,7 +312,7 @@ interface Prediction {
   intent: string;
   p: number;            // α / (α + β)
   sd: number;           // Beta standard deviation
-  lower: number;        // p − z·sd, clamped to [0, 1]; what shouldReveal compares to threshold
+  lower: number;        // p − z·sd clamped to [0, 1], or the exact Beta quantile with bound: 'exact'; what shouldReveal compares to threshold
   confidence: number;   // 1 − 2·sd, clamped to [0, 1]. A heuristic: 1 is a sharp estimate, 0 is as vague as a Beta gets
   evidence: number;     // α + β, prior strength included
   revealed: boolean;    // inside the cooldown after markRevealed

package/dist/index.cjs

@@ -20,6 +20,62 @@ function clamp01(x) {
   if (x > 1) return 1;
   return x;
 }
+function normalTail(z) {
+  const x = z / Math.SQRT2;
+  const t = 1 / (1 + 0.3275911 * x);
+  const poly = t * (0.254829592 + t * (-0.284496736 + t * (1.421413741 + t * (-1.453152027 + t * 1.061405429))));
+  return 0.5 * poly * Math.exp(-x * x);
+}
+function lgamma(x) {
+  let acc = 0;
+  let v = x;
+  while (v < 8) {
+    acc -= Math.log(v);
+    v += 1;
+  }
+  const r = 1 / v;
+  const r2 = r * r;
+  return acc + (v - 0.5) * Math.log(v) - v + 0.9189385332046728 + r * (1 / 12 - r2 * (1 / 360 - r2 * (1 / 1260 - r2 / 1680)));
+}
+function betacf(x, a, b) {
+  const tiny = 1e-300;
+  const guard = (v) => Math.abs(v) < tiny ? tiny : v;
+  let c = 1 / tiny;
+  let d = 1;
+  let h = 1;
+  for (let i = 1; i < 2e4; i++) {
+    const m = i >> 1;
+    const aa = (i & 1 ? -(a + m) * (a + b + m) : m * (b - m)) * x / ((a + i - 1) * (a + i));
+    d = 1 / guard(1 + aa * d);
+    c = guard(1 + aa / c);
+    const del = c * d;
+    h *= del;
+    if (Math.abs(del - 1) < 1e-12) break;
+  }
+  return h;
+}
+function incompleteBeta(x, a, b) {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+  const front = Math.exp(
+    lgamma(a + b) - lgamma(a) - lgamma(b) + a * Math.log(x) + b * Math.log(1 - x)
+  );
+  return x < (a + 1) / (a + b + 2) ? front * betacf(x, a, b) / a : 1 - front * betacf(1 - x, b, a) / b;
+}
+function betaQuantile(q, a, b) {
+  let lo = 0;
+  let hi = 1;
+  for (let i = 0; i < 40 && hi - lo > 1e-9; i++) {
+    const mid = (lo + hi) / 2;
+    if (incompleteBeta(mid, a, b) < q) lo = mid;
+    else hi = mid;
+  }
+  return (lo + hi) / 2;
+}
+function lowerBound(alpha, beta, z, bound) {
+  if (bound === "exact") return betaQuantile(normalTail(z), alpha, beta);
+  return clamp01(betaMean(alpha, beta) - z * betaSd(alpha, beta));
+}
 function repeatFactor(n) {
   return Math.log1p(1 / n) / Math.LN2;
 }
@@ -200,7 +256,7 @@ var INTENT_KEYS = [
   "attribution",
   "reveal"
 ];
-var REVEAL_KEYS = ["threshold", "z", "cooldown"];
+var REVEAL_KEYS = ["threshold", "z", "cooldown", "bound"];
 var LEARNING_KEYS = ["halfLife", "gain", "priorEpisodes"];
 var EXPLAIN_KEYS = ["nonZero", "limit"];
 function typeError(path, message) {
@@ -274,6 +330,12 @@ function normalizeRevealOptions(value, path) {
   if (record2.cooldown !== void 0) {
     out.cooldown = expectNonNegative(record2.cooldown, `${path}.cooldown`);
   }
+  if (record2.bound !== void 0) {
+    if (record2.bound !== "normal" && record2.bound !== "exact") {
+      typeError(`${path}.bound`, 'must be "normal" or "exact"');
+    }
+    out.bound = record2.bound;
+  }
   return out;
 }
 function normalizeLearning(value, path) {
@@ -394,7 +456,8 @@ function resolveReveal(config, intent, opts, normalized = false) {
   return {
     threshold: o.threshold ?? intent.reveal?.threshold ?? config?.reveal?.threshold ?? DEFAULT_THRESHOLD,
     z: o.z ?? intent.reveal?.z ?? config?.reveal?.z ?? DEFAULT_Z,
-    cooldown: o.cooldown ?? intent.reveal?.cooldown ?? config?.reveal?.cooldown ?? intent.halfLife
+    cooldown: o.cooldown ?? intent.reveal?.cooldown ?? config?.reveal?.cooldown ?? intent.halfLife,
+    bound: o.bound ?? intent.reveal?.bound ?? config?.reveal?.bound ?? "normal"
   };
 }
 function resolveLearning(config) {
@@ -501,7 +564,7 @@ function buildPrediction(is, name, reveal, at) {
     intent: name,
     p,
     sd,
-    lower: clamp01(p - reveal.z * sd),
+    lower: lowerBound(is.alpha, is.beta, reveal.z, reveal.bound),
     confidence: clamp01(1 - 2 * sd),
     evidence: is.alpha + is.beta,
     revealed: revealEnd !== null,
@@ -569,13 +632,9 @@ function inspect(state, at, opts) {
 // src/evidence.ts
 function evidenceToReveal(intent, opts) {
   const config = normalizeIntentConfig(intent, "intent");
-  const { threshold, z } = resolveReveal(void 0, config, opts);
+  const { threshold, z, bound } = resolveReveal(void 0, config, opts);
   const { alpha0, beta0 } = priorCounts(config);
-  const open = (w) => {
-    const alpha = alpha0 + w;
-    const p = betaMean(alpha, beta0);
-    return p >= threshold && clamp01(p - z * betaSd(alpha, beta0)) >= threshold;
-  };
+  const open = (w) => betaMean(alpha0 + w, beta0) >= threshold && lowerBound(alpha0 + w, beta0, z, bound) >= threshold;
   if (threshold >= 1) return Number.POSITIVE_INFINITY;
   if (open(0)) return 0;
   let lo = 0;