oracular 0.15.0 → 0.17.0

package/dist/index.d.cts

@@ -69,8 +69,25 @@ interface RevealOptions {
      */
     bound?: 'normal' | 'exact';
 }
-/** The association measure converted to a signed, bounded score when learning signal weights. */
-type LiftType = 'absolute-difference' | 'relative-lift' | 'risk-ratio' | 'log-lift' | 'odds-ratio' | 'normalized-difference' | 'association-rule';
+/**
+ * The association measure converted to a signed, bounded score when learning signal weights.
+ * Every value but the default, `'normalized-difference'`, is deprecated: a sweep of all seven on
+ * the clickstream case study found none that beats the default on either split, so the six are
+ * removed in 1.0. They keep working, unchanged, until then; `learning.lift` itself stays.
+ */
+type LiftType = 
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+'absolute-difference'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'relative-lift'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'risk-ratio'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'log-lift'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'odds-ratio' | 'normalized-difference'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'association-rule';
 /**
  * How the engine learns from the user's own outcomes.
  *
@@ -89,6 +106,7 @@ interface LearningConfig {
      * absolute/normalized differences keep their scale. Omit to preserve the existing normalized
      * difference exactly. 'association-rule' uses the overall outcome rate as its baseline; the
      * others use episodes without the signal. Raw ratios are reporting metrics, never weights.
+     * Every value but the default is deprecated and removed in 1.0 (see {@link LiftType}).
      */
     lift?: LiftType;
     /** Half-life of learned hit/miss counts, in the same unit as `at`. Omit for no forgetting. */
@@ -474,6 +492,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
@@ -821,25 +848,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

@@ -69,8 +69,25 @@ interface RevealOptions {
      */
     bound?: 'normal' | 'exact';
 }
-/** The association measure converted to a signed, bounded score when learning signal weights. */
-type LiftType = 'absolute-difference' | 'relative-lift' | 'risk-ratio' | 'log-lift' | 'odds-ratio' | 'normalized-difference' | 'association-rule';
+/**
+ * The association measure converted to a signed, bounded score when learning signal weights.
+ * Every value but the default, `'normalized-difference'`, is deprecated: a sweep of all seven on
+ * the clickstream case study found none that beats the default on either split, so the six are
+ * removed in 1.0. They keep working, unchanged, until then; `learning.lift` itself stays.
+ */
+type LiftType = 
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+'absolute-difference'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'relative-lift'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'risk-ratio'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'log-lift'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'odds-ratio' | 'normalized-difference'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'association-rule';
 /**
  * How the engine learns from the user's own outcomes.
  *
@@ -89,6 +106,7 @@ interface LearningConfig {
      * absolute/normalized differences keep their scale. Omit to preserve the existing normalized
      * difference exactly. 'association-rule' uses the overall outcome rate as its baseline; the
      * others use episodes without the signal. Raw ratios are reporting metrics, never weights.
+     * Every value but the default is deprecated and removed in 1.0 (see {@link LiftType}).
      */
     lift?: LiftType;
     /** Half-life of learned hit/miss counts, in the same unit as `at`. Omit for no forgetting. */
@@ -474,6 +492,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
@@ -821,25 +848,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

@@ -897,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)) {
@@ -912,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),
@@ -920,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 };
 }