oracular 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.15.0
+
+### Minor Changes
+
+- [#73](https://github.com/Yuribenjamin/oracular/pull/73) [`3363311`](https://github.com/Yuribenjamin/oracular/commit/3363311a66fa2f3208a3be43f71523ac93979101) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **An episode per outcome, for intents shaped as attempts.** The episode is the session, shared by every intent, so for an upload that fails, completes, and completes again in one session the engine counted one episode: the second completion, with nothing seen before it, was a duplicate under 0.10's rule, and a second attempt that failed and never completed stayed neutral at the close. The failure signal never saw an outcome without it, which is the contrast learning needs, and `tune` printed "1 counted episode" where the app saw two. `IntentConfig.episodePerOutcome: true` makes each outcome an episode of its own for that intent: 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`. Everything else is as before, `resetOnOutcome` is independent, and `tune` follows the engine's counts. Off unless set: every state and every number without it is exactly what it was. With it set, a duplicated outcome event counts twice, so dedupe such events in the app for these intents. The JSON Schema lists it. Found by the second production integration, whose workaround, `endEpisode` on the outcome, ends the session for every other intent too.
+  
+  **Rollback.** A stored config that sets `episodePerOutcome` loads in 0.13 and later, which do not read the stored snapshot when the app passes its config; 0.12 and earlier throw a `TypeError` on the unknown key, so remove it from the saved config before rolling a deploy back that far. The state version is unchanged.
+
+## 0.14.0
+
+### Minor Changes
+
+- [#71](https://github.com/Yuribenjamin/oracular/pull/71) [`d9e9769`](https://github.com/Yuribenjamin/oracular/commit/d9e9769e922c3bc4251f4585a6cc1c7697468958) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **A cooldown of its own after the outcome.** The outcome event paused reveals for the reveal `cooldown`: after a "stuck" intent's outcome, help was suppressed for the hour the cooldown named, and the next attempt that went wrong, exactly when the help should be back, got nothing; the only way out, `cooldown: 0`, disabled the reveal cooldown too. `reveal.outcomeCooldown` is the pause after the outcome, resolved per call → intent → engine like the other reveal options, 0 allowed; it defaults to the resolved `cooldown`, so nothing moves unless it is set. The JSON Schema lists it. Found by the second production integration.
+  
+  **Rollback.** A stored config that sets `outcomeCooldown` loads in 0.13 and later, which do not read the stored snapshot when the app passes its config; 0.12 and earlier throw a `TypeError` on the unknown key, so remove it from the saved config before rolling a deploy back that far. The state version is unchanged.
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -186,7 +186,7 @@ Before any update or reading, the evidence decays by 2^(−Δt / halfLife), wher
 
 ### The user's history corrects your weights
 
-Events happen inside **episodes** (sessions). An episode ends when you call `endEpisode`, or on its own after `episodeTimeout` of inactivity. Signals seen in the episode are remembered per intent. When the intent's `outcome` event arrives, each remembered signal gets a **hit**; when the episode ends without it, each gets a **miss**, or, with `attribution` set on the intent, the episode waits and takes the share `2^(−age / halfLife)` of a hit if the outcome arrives inside the window. The engine also counts, per intent, how many episodes ended with and without the outcome: the intent's **base rate**. Signals seen after an outcome in the same episode count only if another outcome follows them; a repeated outcome with nothing seen since counts nothing.
+Events happen inside **episodes** (sessions). An episode ends when you call `endEpisode`, or on its own after `episodeTimeout` of inactivity. Signals seen in the episode are remembered per intent. When the intent's `outcome` event arrives, each remembered signal gets a **hit**; when the episode ends without it, each gets a **miss**, or, with `attribution` set on the intent, the episode waits and takes the share `2^(−age / halfLife)` of a hit if the outcome arrives inside the window. The engine also counts, per intent, how many episodes ended with and without the outcome: the intent's **base rate**. Signals seen after an outcome in the same episode count only if another outcome follows them; a repeated outcome with nothing seen since counts nothing. For an intent shaped as attempts (an upload that fails, completes, and completes again), set `episodePerOutcome` and each outcome is an episode of its own: the second completion counts, with nothing seen, as the contrast learning needs, and failures after a completion take a miss when the session ends.
 
 A signal's weight is then a blend of your prior and the learned estimate:
 
@@ -224,7 +224,7 @@ Learned counts never decay unless you set `learning.halfLife`.
 
 When the outcome event arrives, the intent's evidence returns to the prior (α, β and contributions), while everything learned is kept. The user already upgraded; stop predicting that they will. Set `resetOnOutcome: false` for intents where the outcome can repeat inside one episode.
 
-The outcome also starts the intent's `cooldown`: `shouldReveal` stays false until it ends, however strong the fresh evidence, so a user who just bought is not immediately pitched again. The time of the last outcome is kept on the state as `lastOutcomeAt`.
+The outcome also starts a cooldown, `outcomeCooldown`, by default the same `cooldown` a reveal starts: `shouldReveal` stays false until it ends, however strong the fresh evidence, so a user who just bought is not immediately pitched again. Set it on its own, 0 included, for an intent whose outcome recurs within minutes, or a "stuck" intent whose help should be back at the next attempt: the outcome then pauses nothing while a reveal still starts its cooldown. The time of the last outcome is kept on the state as `lastOutcomeAt`.
 
 ### Every answer comes with its reasons
 
@@ -297,14 +297,16 @@ interface IntentConfig {
   outcome?: string;                 // event that confirms the intent
   resetOnOutcome?: boolean;         // default true
   saturate?: boolean;               // repeats within an episode add less; default: episodeTimeout is set
+  episodePerOutcome?: boolean;      // each outcome is an episode of its own for this intent; default false: the session is
   attribution?: number;             // how long a closed episode waits for the outcome before it is a miss; off if omitted
   reveal?: RevealOptions;
 }
 
 interface RevealOptions {
-  threshold?: number;  // default 0.5
-  z?: number;          // default 1.28
-  cooldown?: number;   // default: the intent's halfLife
+  threshold?: number;        // default 0.5
+  z?: number;                // default 1.28
+  cooldown?: number;         // after markRevealed; default: the intent's halfLife
+  outcomeCooldown?: number;  // after the outcome event; default: cooldown. 0 lets the outcome pause nothing
   bound?: 'normal' | 'exact';  // default 'normal': p − z·sd; 'exact': the Beta quantile at Φ(−z)
 }
 ```

package/dist/index.cjs

@@ -286,10 +286,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",
@@ -375,6 +376,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"');
@@ -440,6 +444,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`);
   }
@@ -513,10 +523,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"
   };
 }
@@ -621,7 +633,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,
@@ -754,7 +766,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 };
@@ -807,7 +821,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);