oracular 0.13.0 → 0.15.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 long after the intent's outcome event `shouldReveal` stays false. Default: `cooldown`.
+     * 0 is allowed: the outcome then pauses nothing, while a reveal still starts its cooldown, for
+     * an intent whose outcome recurs within minutes, or a "stuck" intent whose help should be back
+     * at the next attempt.
+     */
+    outcomeCooldown?: 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
@@ -131,6 +138,18 @@ interface IntentConfig {
      * weight.
      */
     saturate?: boolean;
+    /**
+     * Each outcome is an episode of its own for this intent, rather than the session. After the
+     * outcome arrives, the intent's bookkeeping starts over: a later outcome in the same session
+     * counts as another episode even with nothing seen since, and signals seen after an outcome
+     * take a miss at the session's close (or wait under `attribution`), as a first attempt would.
+     * Default false: the episode is the session, a repeated outcome with nothing seen since counts
+     * nothing, and signals seen after an outcome are neutral at the close. For intents shaped as
+     * attempts (an upload that fails, then completes, then completes again), where the second
+     * attempt is the contrast learning needs. With it set, a duplicated outcome event counts twice:
+     * dedupe such events in the app.
+     */
+    episodePerOutcome?: boolean;
     /**
      * How long a closed episode's signals wait for the outcome before they take a miss, in the same
      * unit as `at`. With it set, an episode that ends without the outcome is held instead of
@@ -307,8 +326,8 @@ interface Prediction {
     revealedAt: number | null;
     /**
      * When the current suppression ends: the later of the reveal cooldown (after `markRevealed`)
-     * and the outcome cooldown (after the outcome event) still running at `at`, or null when
-     * neither is. `shouldReveal` is false while this is non-null.
+     * and the outcome cooldown (`outcomeCooldown` after the outcome event) still running at `at`,
+     * or null when neither is. `shouldReveal` is false while this is non-null.
      */
     suppressedUntil: number | null;
 }
@@ -650,7 +669,8 @@ declare function explain(state: EngineState, intent: string, at: number, opts?:
  * it either way; otherwise every occurrence adds all of `w`. For every intent the event is the
  * outcome of: give the signals remembered since the episode started or the outcome last arrived a
  * hit and count the episode toward the base rate (a repeated outcome with nothing seen since
- * counts nothing), credit
+ * counts nothing, unless `IntentConfig.episodePerOutcome` makes every outcome an episode of its
+ * own for the intent), credit
  * the closed episodes still waiting under `IntentConfig.attribution` by `2^(−age / halfLife)`
  * each, record `lastOutcomeAt`, and (by default) reset the evidence to the prior. Any event opens
  * or extends the current episode; an idle gap longer than `config.episodeTimeout` closes the
@@ -730,9 +750,10 @@ 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`, `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}.
+ * @param opts - Overrides for `threshold`, `z`, `cooldown`, `outcomeCooldown` and `bound`,
+ *   resolved as call → intent → engine → defaults. `z` and `bound` set `lower`; `cooldown` sets
+ *   `revealed` and, with `outcomeCooldown` (default: `cooldown`), `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.
@@ -755,7 +776,8 @@ declare function predict(state: EngineState, intent: string, at: number, opts?:
  * @param intent - Name of an intent declared in the config.
  * @param at - The time to evaluate at.
  * @param opts - Overrides for `threshold` (default 0.5), `z` (default 1.28, a one-sided 90%
- *   bound) and `cooldown` (default: the intent's `halfLife`).
+ *   bound), `cooldown` (default: the intent's `halfLife`) and `outcomeCooldown` (default:
+ *   `cooldown`; 0 lets the outcome pause nothing).
  * @returns True when the app should show, offer or reveal whatever this intent gates.
  * @throws `RangeError` when `intent` is not declared in the config.
  * @throws `TypeError` when `state` is not an engine state, `at` is not finite, or `opts` is

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 long after the intent's outcome event `shouldReveal` stays false. Default: `cooldown`.
+     * 0 is allowed: the outcome then pauses nothing, while a reveal still starts its cooldown, for
+     * an intent whose outcome recurs within minutes, or a "stuck" intent whose help should be back
+     * at the next attempt.
+     */
+    outcomeCooldown?: 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
@@ -131,6 +138,18 @@ interface IntentConfig {
      * weight.
      */
     saturate?: boolean;
+    /**
+     * Each outcome is an episode of its own for this intent, rather than the session. After the
+     * outcome arrives, the intent's bookkeeping starts over: a later outcome in the same session
+     * counts as another episode even with nothing seen since, and signals seen after an outcome
+     * take a miss at the session's close (or wait under `attribution`), as a first attempt would.
+     * Default false: the episode is the session, a repeated outcome with nothing seen since counts
+     * nothing, and signals seen after an outcome are neutral at the close. For intents shaped as
+     * attempts (an upload that fails, then completes, then completes again), where the second
+     * attempt is the contrast learning needs. With it set, a duplicated outcome event counts twice:
+     * dedupe such events in the app.
+     */
+    episodePerOutcome?: boolean;
     /**
      * How long a closed episode's signals wait for the outcome before they take a miss, in the same
      * unit as `at`. With it set, an episode that ends without the outcome is held instead of
@@ -307,8 +326,8 @@ interface Prediction {
     revealedAt: number | null;
     /**
      * When the current suppression ends: the later of the reveal cooldown (after `markRevealed`)
-     * and the outcome cooldown (after the outcome event) still running at `at`, or null when
-     * neither is. `shouldReveal` is false while this is non-null.
+     * and the outcome cooldown (`outcomeCooldown` after the outcome event) still running at `at`,
+     * or null when neither is. `shouldReveal` is false while this is non-null.
      */
     suppressedUntil: number | null;
 }
@@ -650,7 +669,8 @@ declare function explain(state: EngineState, intent: string, at: number, opts?:
  * it either way; otherwise every occurrence adds all of `w`. For every intent the event is the
  * outcome of: give the signals remembered since the episode started or the outcome last arrived a
  * hit and count the episode toward the base rate (a repeated outcome with nothing seen since
- * counts nothing), credit
+ * counts nothing, unless `IntentConfig.episodePerOutcome` makes every outcome an episode of its
+ * own for the intent), credit
  * the closed episodes still waiting under `IntentConfig.attribution` by `2^(−age / halfLife)`
  * each, record `lastOutcomeAt`, and (by default) reset the evidence to the prior. Any event opens
  * or extends the current episode; an idle gap longer than `config.episodeTimeout` closes the
@@ -730,9 +750,10 @@ 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`, `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}.
+ * @param opts - Overrides for `threshold`, `z`, `cooldown`, `outcomeCooldown` and `bound`,
+ *   resolved as call → intent → engine → defaults. `z` and `bound` set `lower`; `cooldown` sets
+ *   `revealed` and, with `outcomeCooldown` (default: `cooldown`), `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.
@@ -755,7 +776,8 @@ declare function predict(state: EngineState, intent: string, at: number, opts?:
  * @param intent - Name of an intent declared in the config.
  * @param at - The time to evaluate at.
  * @param opts - Overrides for `threshold` (default 0.5), `z` (default 1.28, a one-sided 90%
- *   bound) and `cooldown` (default: the intent's `halfLife`).
+ *   bound), `cooldown` (default: the intent's `halfLife`) and `outcomeCooldown` (default:
+ *   `cooldown`; 0 lets the outcome pause nothing).
  * @returns True when the app should show, offer or reveal whatever this intent gates.
  * @throws `RangeError` when `intent` is not declared in the config.
  * @throws `TypeError` when `state` is not an engine state, `at` is not finite, or `opts` is

package/dist/index.js

@@ -284,10 +284,11 @@ var INTENT_KEYS = [
   "outcome",
   "resetOnOutcome",
   "saturate",
+  "episodePerOutcome",
   "attribution",
   "reveal"
 ];
-var REVEAL_KEYS = ["threshold", "z", "cooldown", "bound"];
+var REVEAL_KEYS = ["threshold", "z", "cooldown", "outcomeCooldown", "bound"];
 var LEARNING_KEYS = ["halfLife", "gain", "priorEpisodes", "lift"];
 var LIFT_TYPES = [
   "absolute-difference",
@@ -373,6 +374,9 @@ function normalizeRevealOptions(value, path, strict = true) {
   if (record2.cooldown !== void 0) {
     out.cooldown = expectNonNegative(record2.cooldown, `${path}.cooldown`);
   }
+  if (record2.outcomeCooldown !== void 0) {
+    out.outcomeCooldown = expectNonNegative(record2.outcomeCooldown, `${path}.outcomeCooldown`);
+  }
   if (record2.bound !== void 0) {
     if (record2.bound !== "normal" && record2.bound !== "exact") {
       typeError(`${path}.bound`, 'must be "normal" or "exact"');
@@ -438,6 +442,12 @@ function normalizeIntentConfig(value, path, strict = true) {
     if (typeof record2.saturate !== "boolean") typeError(`${path}.saturate`, "must be a boolean");
     out.saturate = record2.saturate;
   }
+  if (record2.episodePerOutcome !== void 0) {
+    if (typeof record2.episodePerOutcome !== "boolean") {
+      typeError(`${path}.episodePerOutcome`, "must be a boolean");
+    }
+    out.episodePerOutcome = record2.episodePerOutcome;
+  }
   if (record2.attribution !== void 0) {
     out.attribution = expectPositive(record2.attribution, `${path}.attribution`);
   }
@@ -511,10 +521,12 @@ function splitEvaluateOptions(value, path) {
 }
 function resolveReveal(config, intent, opts, normalized = false) {
   const o = opts === void 0 ? {} : normalized ? opts : normalizeRevealOptions(opts, "options", false);
+  const cooldown = o.cooldown ?? intent.reveal?.cooldown ?? config?.reveal?.cooldown ?? intent.halfLife;
   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,
+    outcomeCooldown: o.outcomeCooldown ?? intent.reveal?.outcomeCooldown ?? config?.reveal?.outcomeCooldown ?? cooldown,
     bound: o.bound ?? intent.reveal?.bound ?? config?.reveal?.bound ?? "normal"
   };
 }
@@ -619,7 +631,7 @@ function buildPrediction(is, name, reveal, at) {
   const p = betaMean(is.alpha, is.beta);
   const sd = betaSd(is.alpha, is.beta);
   const revealEnd = cooldownEnd(is.lastRevealedAt, reveal.cooldown, at);
-  const outcomeEnd = cooldownEnd(is.lastOutcomeAt, reveal.cooldown, at);
+  const outcomeEnd = cooldownEnd(is.lastOutcomeAt, reveal.outcomeCooldown, at);
   const suppressedUntil = revealEnd === null ? outcomeEnd : outcomeEnd === null ? revealEnd : Math.max(revealEnd, outcomeEnd);
   return {
     intent: name,
@@ -752,7 +764,9 @@ function observe(state, event) {
     }
     if (isOutcome) {
       const record2 = episodeRecord(episode, intentName);
-      if (!record2.resolved || record2.seen.length > 0) is = recordEpisode(is, record2.seen, 1);
+      if (!record2.resolved || record2.seen.length > 0 || intent.episodePerOutcome === true) {
+        is = recordEpisode(is, record2.seen, 1);
+      }
       is = creditPending(is, intent, at);
       episode = markResolved(episode, intentName);
       is = { ...is, lastOutcomeAt: at };
@@ -805,7 +819,8 @@ function closeEpisode(state, at) {
   const intents = { ...state.intents };
   for (const [intentName, intent] of Object.entries(state.config.intents)) {
     const record2 = episodeRecord(state.episode, intentName);
-    if (record2.resolved) continue;
+    if (record2.resolved && (intent.episodePerOutcome !== true || record2.seen.length === 0))
+      continue;
     let is = getIntentState(state, intentName, intent);
     is = settlePending(is, intent, learning, at);
     is = intent.attribution === void 0 ? recordEpisode(is, record2.seen, 0) : deferEpisode(is, record2.seen, at);