oracular 0.14.0 → 0.16.0

package/dist/index.d.cts

@@ -138,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
@@ -462,6 +474,15 @@ interface RecordedDecision {
     }[];
     /** Effective weight of every declared signal, in config order. */
     weights: Record<string, number>;
+    /**
+     * The prediction just before the event, on the record of this intent's own outcome event, when
+     * {@link createRecord} was given the state before it: the number `resetOnOutcome` wipes, which
+     * `p` above no longer shows. Absent on every other record.
+     */
+    before?: {
+        p: number;
+        lower: number;
+    };
 }
 /**
  * One line of a recorder log: an event the app observed and what the engine decided right after
@@ -657,7 +678,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
@@ -808,25 +830,33 @@ declare function markRevealed(state: EngineState, intent: string, at: number): E
  * and the effective weight of every signal. Pure: the install id comes from the app, never from
  * here. See the Shadow mode guide for the whole workflow.
  *
+ * On the record of an intent's own outcome event, `p` is what the engine decides right after it,
+ * which with `resetOnOutcome` is the prior: the estimate the outcome confirmed is gone. Pass the
+ * state from before the event as `previous` and that intent's decision gains `before`, its `p`
+ * and `lower` at `event.at` on that state. Replay never reads it; people reading the log do.
+ *
  * @param state - The state after `observe(state, event)`. Not mutated.
  * @param event - The event just observed. Only `name` and `at` are recorded.
  * @param opts - `installId` (generated and stored by the app), `mode` (`'shadow'` while
  *   reveals are computed but not shown, `'live'` once they are), and `top` (default 3).
+ * @param previous - The state before `observe(state, event)`, optional. Only read for the
+ *   intents whose outcome the event is.
  * @returns A plain, JSON-serializable {@link EventRecord}.
- * @throws `TypeError` when `state` is not an engine state, the event is malformed, `opts` is
- *   not an object, has an unknown key, an empty `installId` or a `mode` other than
- *   `'shadow'` or `'live'`.
+ * @throws `TypeError` when `state` or `previous` is not an engine state, the event is
+ *   malformed, `opts` is not an object, has an unknown key, an empty `installId` or a `mode`
+ *   other than `'shadow'` or `'live'`.
  * @throws `RangeError` when `opts.top` is negative or fractional.
  * @example
  * ```ts
  * const recording = { installId: localStorage.getItem('oracular.install')!, mode: 'shadow' } as const;
  *
  * const event = { name: 'pricing.viewed', at: Date.now() };
+ * const previous = state;
  * state = observe(state, event);
- * appendLine(JSON.stringify(createRecord(state, event, recording)));
+ * appendLine(JSON.stringify(createRecord(state, event, recording, previous)));
  * ```
  */
-declare function createRecord(state: EngineState, event: IntentEvent, opts: RecordOptions): EventRecord;
+declare function createRecord(state: EngineState, event: IntentEvent, opts: RecordOptions, previous?: EngineState): EventRecord;
 /**
  * A recorder record for the end of an episode. Write one whenever the app calls
  * {@link endEpisode}, with the same `at`, so that replay can end the episode at the same moment

package/dist/index.d.ts

@@ -138,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
@@ -462,6 +474,15 @@ interface RecordedDecision {
     }[];
     /** Effective weight of every declared signal, in config order. */
     weights: Record<string, number>;
+    /**
+     * The prediction just before the event, on the record of this intent's own outcome event, when
+     * {@link createRecord} was given the state before it: the number `resetOnOutcome` wipes, which
+     * `p` above no longer shows. Absent on every other record.
+     */
+    before?: {
+        p: number;
+        lower: number;
+    };
 }
 /**
  * One line of a recorder log: an event the app observed and what the engine decided right after
@@ -657,7 +678,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
@@ -808,25 +830,33 @@ declare function markRevealed(state: EngineState, intent: string, at: number): E
  * and the effective weight of every signal. Pure: the install id comes from the app, never from
  * here. See the Shadow mode guide for the whole workflow.
  *
+ * On the record of an intent's own outcome event, `p` is what the engine decides right after it,
+ * which with `resetOnOutcome` is the prior: the estimate the outcome confirmed is gone. Pass the
+ * state from before the event as `previous` and that intent's decision gains `before`, its `p`
+ * and `lower` at `event.at` on that state. Replay never reads it; people reading the log do.
+ *
  * @param state - The state after `observe(state, event)`. Not mutated.
  * @param event - The event just observed. Only `name` and `at` are recorded.
  * @param opts - `installId` (generated and stored by the app), `mode` (`'shadow'` while
  *   reveals are computed but not shown, `'live'` once they are), and `top` (default 3).
+ * @param previous - The state before `observe(state, event)`, optional. Only read for the
+ *   intents whose outcome the event is.
  * @returns A plain, JSON-serializable {@link EventRecord}.
- * @throws `TypeError` when `state` is not an engine state, the event is malformed, `opts` is
- *   not an object, has an unknown key, an empty `installId` or a `mode` other than
- *   `'shadow'` or `'live'`.
+ * @throws `TypeError` when `state` or `previous` is not an engine state, the event is
+ *   malformed, `opts` is not an object, has an unknown key, an empty `installId` or a `mode`
+ *   other than `'shadow'` or `'live'`.
  * @throws `RangeError` when `opts.top` is negative or fractional.
  * @example
  * ```ts
  * const recording = { installId: localStorage.getItem('oracular.install')!, mode: 'shadow' } as const;
  *
  * const event = { name: 'pricing.viewed', at: Date.now() };
+ * const previous = state;
  * state = observe(state, event);
- * appendLine(JSON.stringify(createRecord(state, event, recording)));
+ * appendLine(JSON.stringify(createRecord(state, event, recording, previous)));
  * ```
  */
-declare function createRecord(state: EngineState, event: IntentEvent, opts: RecordOptions): EventRecord;
+declare function createRecord(state: EngineState, event: IntentEvent, opts: RecordOptions, previous?: EngineState): EventRecord;
 /**
  * A recorder record for the end of an episode. Write one whenever the app calls
  * {@link endEpisode}, with the same `at`, so that replay can end the episode at the same moment

package/dist/index.js

@@ -284,6 +284,7 @@ var INTENT_KEYS = [
   "outcome",
   "resetOnOutcome",
   "saturate",
+  "episodePerOutcome",
   "attribution",
   "reveal"
 ];
@@ -441,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`);
   }
@@ -757,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 };
@@ -810,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);
@@ -887,10 +897,11 @@ function normalizeRecordOptions(value) {
   }
   return { installId, mode, top };
 }
-function createRecord(state, event, opts) {
+function createRecord(state, event, opts, previous) {
   const s = requireState(state);
   const { name, at } = validateEvent(event);
   const { installId, mode, top } = normalizeRecordOptions(opts);
+  const prev = previous === void 0 ? void 0 : requireState(previous);
   const learning = resolveLearning(s.config);
   const decisions = {};
   for (const [intentName, intent] of Object.entries(s.config.intents)) {
@@ -902,7 +913,7 @@ function createRecord(state, event, opts) {
     for (const signal of Object.keys(intent.signals)) {
       weights[signal] = rows.find((row) => row.signal === signal).effectiveWeight;
     }
-    decisions[intentName] = {
+    const decision = {
       p: prediction.p,
       lower: prediction.lower,
       shouldReveal: decideReveal(prediction, reveal),
@@ -910,6 +921,17 @@ function createRecord(state, event, opts) {
       top: rows.filter((row) => row.contribution !== 0).slice(0, top).map((row) => ({ signal: row.signal, impact: row.impact })),
       weights
     };
+    const prevIntent = prev === void 0 ? void 0 : getOwn(prev.config.intents, intentName);
+    if (prev !== void 0 && prevIntent !== void 0 && intent.outcome === name) {
+      const was = buildPrediction(
+        assessIntent(prev, intentName, prevIntent, resolveLearning(prev.config), at),
+        intentName,
+        resolveReveal(prev.config, prevIntent, void 0),
+        at
+      );
+      decision.before = { p: was.p, lower: was.lower };
+    }
+    decisions[intentName] = decision;
   }
   return { v: RECORD_VERSION, kind: "event", installId, mode, event: { name, at }, decisions };
 }