oracular 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -54,6 +54,13 @@ interface RevealOptions {
     z?: number;
     /** How long after `markRevealed` the intent stays revealed and `shouldReveal` is false. Default: the intent's `halfLife`. */
     cooldown?: number;
+    /**
+     * How `lower` is computed. `'normal'` (default): p − z·sd, clamped to [0, 1]. `'exact'`: the
+     * Beta distribution's own quantile at the same one-sided level, Φ(−z), so `z` keeps its
+     * meaning. The two differ on thin evidence near the threshold, where the approximation is
+     * optimistic; under `'exact'`, `z: 0` is the median rather than the mean.
+     */
+    bound?: 'normal' | 'exact';
 }
 /**
  * How the engine learns from the user's own outcomes.
@@ -261,7 +268,10 @@ interface Prediction {
     p: number;
     /** Standard deviation of the Beta distribution. */
     sd: number;
-    /** p − z·sd, clamped to [0, 1]. This is what `shouldReveal` compares to the threshold. */
+    /**
+     * The lower confidence bound `shouldReveal` compares to the threshold: p − z·sd clamped to
+     * [0, 1], or with `bound: 'exact'` the Beta quantile at Φ(−z).
+     */
     lower: number;
     /** 1 − 2·sd, clamped to [0, 1]. A heuristic: 1 when the estimate is sharp, 0 when it is as vague as possible. */
     confidence: number;
@@ -515,8 +525,8 @@ interface PresetSource {
  * @param state - The current state. Not mutated.
  * @param intent - Name of an intent declared in the config.
  * @param at - The time to evaluate at.
- * @param opts - Reveal overrides (`threshold`, `z`, `cooldown`) and explain filters (`nonZero`,
- *   `limit`) in one object.
+ * @param opts - Reveal overrides (`threshold`, `z`, `cooldown`, `bound`) and explain filters
+ *   (`nonZero`, `limit`) in one object.
  * @returns `prediction` (as `predict`), `reveal` (as `shouldReveal`) and `explanation` (as
  *   `explain` with the same filters).
  * @throws `RangeError` when `intent` is not declared in the config.
@@ -552,7 +562,8 @@ declare function inspect(state: EngineState, at: number, opts?: EvaluateOptions)
 /**
  * How much positive evidence an intent needs before {@link shouldReveal} first becomes true:
  * the smallest pseudo-count `w` such that Beta(α₀ + w, β₀) clears both `p ≥ threshold` and
- * `p − z·sd ≥ threshold`. Divide by a signal's weight and round up for the number of full-weight
+ * `lower ≥ threshold`, with `lower` as `bound` defines it (p − z·sd, or the exact Beta quantile).
+ * Divide by a signal's weight and round up for the number of full-weight
  * occurrences that open the gate: distinct signals, or one occurrence per episode. Repeats within
  * one episode add less (n of them add `w × log2(1 + n)`, see {@link IntentConfig.saturate}).
  * Solved numerically to 1e-9.
@@ -560,8 +571,8 @@ declare function inspect(state: EngineState, at: number, opts?: EvaluateOptions)
  * Cooldowns and decay are not part of the answer: this is the evidence needed at one instant.
  *
  * @param intent - One intent's config, validated as `createState` would.
- * @param opts - `threshold` and `z` overrides, resolved as call → intent → defaults (there is
- *   no engine config here). `cooldown` is accepted and ignored.
+ * @param opts - `threshold`, `z` and `bound` overrides, resolved as call → intent → defaults
+ *   (there is no engine config here). `cooldown` is accepted and ignored.
  * @returns The pseudo-count sum; 0 when the prior alone already clears the gate; `Infinity`
  *   when no finite amount of evidence can (threshold 1).
  * @throws `TypeError` or `RangeError` when `intent` or `opts` is invalid.
@@ -679,9 +690,9 @@ declare function episodeClosed(prev: EngineState, next: EngineState): boolean;
  * @param state - The current state. Not mutated.
  * @param intent - Name of an intent declared in the config.
  * @param at - The time to evaluate at, in the same unit as your durations.
- * @param opts - Overrides for `threshold`, `z` and `cooldown`, resolved as call → intent →
- *   engine → defaults. `z` sets `lower`; `cooldown` sets `revealed` and `suppressedUntil`;
- *   `threshold` only matters to {@link shouldReveal}.
+ * @param opts - Overrides for `threshold`, `z`, `cooldown` and `bound`, resolved as call →
+ *   intent → engine → defaults. `z` and `bound` set `lower`; `cooldown` sets `revealed` and
+ *   `suppressedUntil`; `threshold` only matters to {@link shouldReveal}.
  * @returns The prediction. `p`, `sd`, `lower` and `confidence` are in [0, 1]; `evidence` is
  *   α + β.
  * @throws `RangeError` when `intent` is not declared in the config.
@@ -696,7 +707,8 @@ declare function episodeClosed(prev: EngineState, next: EngineState): boolean;
 declare function predict(state: EngineState, intent: string, at: number, opts?: RevealOptions): Prediction;
 /**
  * Whether to act on the intent now. True when p ≥ `threshold`, the lower confidence bound
- * p − z·sd also clears `threshold`, and no cooldown is running: neither the one started by
+ * (p − z·sd, or the exact Beta quantile with `bound: 'exact'`) also clears `threshold`, and no
+ * cooldown is running: neither the one started by
  * {@link markRevealed} nor the one started by the intent's outcome event.
  *
  * @param state - The current state. Not mutated.

package/dist/index.d.ts

@@ -54,6 +54,13 @@ interface RevealOptions {
     z?: number;
     /** How long after `markRevealed` the intent stays revealed and `shouldReveal` is false. Default: the intent's `halfLife`. */
     cooldown?: number;
+    /**
+     * How `lower` is computed. `'normal'` (default): p − z·sd, clamped to [0, 1]. `'exact'`: the
+     * Beta distribution's own quantile at the same one-sided level, Φ(−z), so `z` keeps its
+     * meaning. The two differ on thin evidence near the threshold, where the approximation is
+     * optimistic; under `'exact'`, `z: 0` is the median rather than the mean.
+     */
+    bound?: 'normal' | 'exact';
 }
 /**
  * How the engine learns from the user's own outcomes.
@@ -261,7 +268,10 @@ interface Prediction {
     p: number;
     /** Standard deviation of the Beta distribution. */
     sd: number;
-    /** p − z·sd, clamped to [0, 1]. This is what `shouldReveal` compares to the threshold. */
+    /**
+     * The lower confidence bound `shouldReveal` compares to the threshold: p − z·sd clamped to
+     * [0, 1], or with `bound: 'exact'` the Beta quantile at Φ(−z).
+     */
     lower: number;
     /** 1 − 2·sd, clamped to [0, 1]. A heuristic: 1 when the estimate is sharp, 0 when it is as vague as possible. */
     confidence: number;
@@ -515,8 +525,8 @@ interface PresetSource {
  * @param state - The current state. Not mutated.
  * @param intent - Name of an intent declared in the config.
  * @param at - The time to evaluate at.
- * @param opts - Reveal overrides (`threshold`, `z`, `cooldown`) and explain filters (`nonZero`,
- *   `limit`) in one object.
+ * @param opts - Reveal overrides (`threshold`, `z`, `cooldown`, `bound`) and explain filters
+ *   (`nonZero`, `limit`) in one object.
  * @returns `prediction` (as `predict`), `reveal` (as `shouldReveal`) and `explanation` (as
  *   `explain` with the same filters).
  * @throws `RangeError` when `intent` is not declared in the config.
@@ -552,7 +562,8 @@ declare function inspect(state: EngineState, at: number, opts?: EvaluateOptions)
 /**
  * How much positive evidence an intent needs before {@link shouldReveal} first becomes true:
  * the smallest pseudo-count `w` such that Beta(α₀ + w, β₀) clears both `p ≥ threshold` and
- * `p − z·sd ≥ threshold`. Divide by a signal's weight and round up for the number of full-weight
+ * `lower ≥ threshold`, with `lower` as `bound` defines it (p − z·sd, or the exact Beta quantile).
+ * Divide by a signal's weight and round up for the number of full-weight
  * occurrences that open the gate: distinct signals, or one occurrence per episode. Repeats within
  * one episode add less (n of them add `w × log2(1 + n)`, see {@link IntentConfig.saturate}).
  * Solved numerically to 1e-9.
@@ -560,8 +571,8 @@ declare function inspect(state: EngineState, at: number, opts?: EvaluateOptions)
  * Cooldowns and decay are not part of the answer: this is the evidence needed at one instant.
  *
  * @param intent - One intent's config, validated as `createState` would.
- * @param opts - `threshold` and `z` overrides, resolved as call → intent → defaults (there is
- *   no engine config here). `cooldown` is accepted and ignored.
+ * @param opts - `threshold`, `z` and `bound` overrides, resolved as call → intent → defaults
+ *   (there is no engine config here). `cooldown` is accepted and ignored.
  * @returns The pseudo-count sum; 0 when the prior alone already clears the gate; `Infinity`
  *   when no finite amount of evidence can (threshold 1).
  * @throws `TypeError` or `RangeError` when `intent` or `opts` is invalid.
@@ -679,9 +690,9 @@ declare function episodeClosed(prev: EngineState, next: EngineState): boolean;
  * @param state - The current state. Not mutated.
  * @param intent - Name of an intent declared in the config.
  * @param at - The time to evaluate at, in the same unit as your durations.
- * @param opts - Overrides for `threshold`, `z` and `cooldown`, resolved as call → intent →
- *   engine → defaults. `z` sets `lower`; `cooldown` sets `revealed` and `suppressedUntil`;
- *   `threshold` only matters to {@link shouldReveal}.
+ * @param opts - Overrides for `threshold`, `z`, `cooldown` and `bound`, resolved as call →
+ *   intent → engine → defaults. `z` and `bound` set `lower`; `cooldown` sets `revealed` and
+ *   `suppressedUntil`; `threshold` only matters to {@link shouldReveal}.
  * @returns The prediction. `p`, `sd`, `lower` and `confidence` are in [0, 1]; `evidence` is
  *   α + β.
  * @throws `RangeError` when `intent` is not declared in the config.
@@ -696,7 +707,8 @@ declare function episodeClosed(prev: EngineState, next: EngineState): boolean;
 declare function predict(state: EngineState, intent: string, at: number, opts?: RevealOptions): Prediction;
 /**
  * Whether to act on the intent now. True when p ≥ `threshold`, the lower confidence bound
- * p − z·sd also clears `threshold`, and no cooldown is running: neither the one started by
+ * (p − z·sd, or the exact Beta quantile with `bound: 'exact'`) also clears `threshold`, and no
+ * cooldown is running: neither the one started by
  * {@link markRevealed} nor the one started by the intent's outcome event.
  *
  * @param state - The current state. Not mutated.

package/dist/index.js

@@ -18,6 +18,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;
 }
@@ -198,7 +254,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) {
@@ -272,6 +328,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) {
@@ -392,7 +454,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) {
@@ -499,7 +562,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,
@@ -567,13 +630,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;
@@ -1009,8 +1068,11 @@ function reconcile(raw, config) {
         keep(stored.contributions, intent.signals)
       );
     }
-    const episode = getOwn(raw.episode.intents, name);
-    if (episode !== void 0 && raw.episode.startedAt !== null) {
+  }
+  if (raw.episode.startedAt !== null) {
+    for (const [name, episode] of Object.entries(raw.episode.intents)) {
+      const intent = getOwn(config.intents, name);
+      if (intent === void 0) continue;
       const seen = episode.seen.filter(
         (s, i) => hasOwn(intent.signals, s) && episode.seen.indexOf(s) === i
       );