oracular 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.9.0
+
+### Minor Changes
+
+- [#52](https://github.com/Yuribenjamin/oracular/pull/52) [`e8ea457`](https://github.com/Yuribenjamin/oracular/commit/e8ea457b29edd23d0cda8446d6826ad45478b9b9) Thanks [@omaremam](https://github.com/omaremam)! - **Choosing the comparison.** `learning.lift` chooses how a signal's outcome rate is compared with its baseline: absolute difference, relative lift, risk ratio, log lift, odds ratio, normalized difference or association-rule lift. Every choice becomes a signed score in [−1, 1], with no association at zero, before it changes a weight. A risk ratio of 1 learns zero, 3 gives a score of 0.5 and 1/3 gives −0.5; `gain` caps the learned magnitude at `gain × |initial weight|` whichever comparison is set. `oracular tune` uses the same score for weights and intervals, and reports the raw measure alongside it when the two differ. Nothing moves unless the option is set: normalized difference remains the default, with exactly the same arithmetic.
+  
+  **Rollback.** A stored config that sets `lift` is read by 0.9 and later; a 0.8 reader throws a `TypeError` on the unknown key, so remove `learning.lift` from the saved config before rolling a deploy back. Passing an older config to `deserialize` alone does not avoid that check. The state version is unchanged. Existing learned counts are kept; evidence already accumulated under another comparison is not rebuilt and continues to decay or reset on outcome.
+
+## 0.8.1
+
+### Patch Changes
+
+- [#46](https://github.com/Yuribenjamin/oracular/pull/46) [`d796e99`](https://github.com/Yuribenjamin/oracular/commit/d796e990fed2b15d2fbf9afa1744782f9da41433) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **Release tags.** From this release, each release is tagged `oracular@<version>` instead of `v<version>`, and the GitHub release that goes with it is created per package. The reason is the repository's shape: it is now an npm workspace, with the root still the `oracular` package, so that a second package can be published from it; Changesets names tags that way in a workspace, and this release is the one that proves the pipeline end to end before anything depends on it. Nothing in the library changes. What also does not change: the existing `v0.1.0` to `v0.8.0` tags stay where they are, and there is no `v` alias for new releases. If you pin by tag, `oracular@0.8.1` is the first of the new form, and from here on the tag is the package name followed by the version.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -21,12 +21,19 @@
   · <a href="https://yuribenjamin.github.io/oracular/guide/introduction">Guide</a>
   · <a href="https://yuribenjamin.github.io/oracular/api/">API</a>
   · <a href="https://yuribenjamin.github.io/oracular/playground">Playground</a>
+  · <a href="https://yuribenjamin.github.io/oracular/guide/is-it-for-me">Is it for me?</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Yuribenjamin/oracular/main/assets/inspector.gif" width="800" alt="A pricing page next to the oracular inspector panel. Over a simulated day, each click adds a signal and p and the lower bound rise, until both clear 0.5: the gate opens, an upgrade offer appears and a cooldown starts. Eight days later the evidence has decayed back toward the prior.">
 </p>
 
 **oracular** is a tiny, zero-dependency, pure-functional intent engine that runs entirely on the device. Feed it the events your app already emits. It keeps a probabilistic estimate of what the user is about to do (upgrade, churn, get stuck, buy…) and tells you when that estimate crosses a threshold *with enough confidence* to act on it: show a tip, make an offer, reveal a feature, place an ad. It learns from each user's own outcomes, so your initial guesses get corrected on their device, not on a server.
 
 It never touches the network, storage, DOM, timers or globals. Your app owns persistence and side effects; the library owns the math.
 
+The job, concretely: your pricing page learns when to show *this* user the upgrade offer, and their events never leave their browser. On a [public clickstream of 2.7 million events](https://yuribenjamin.github.io/oracular/guide/case-study-clickstream#the-rule-a-skeptic-would-write), among the visitors who came back, the tuned engine caught 27.9% of the orders at 48.9% precision, where the best rule a skeptic would write caught 6.4% at 39.2%; for first-time visitors the two tie, as they must.
+
 ## Why oracular
 
 |                              | oracular                                              | Hosted analytics SDKs                        | Rule engines                              |
@@ -79,8 +86,8 @@ On a public clickstream of 2.7 million events, a hand-written config scored wors
 
 - [Why oracular](#why-oracular)
 - [The workflow: shadow, tune, ship, learn](#the-workflow-shadow-tune-ship-learn)
-- [How it works](#how-it-works)
 - [Examples](#examples)
+- [How it works](#how-it-works)
 - [Using with React](#using-with-react)
 - [API](#api)
 - [Persistence](#persistence)
@@ -92,66 +99,6 @@ On a public clickstream of 2.7 million events, a hand-written config scored wors
 
 The [documentation site](https://yuribenjamin.github.io/oracular/) has the long form: one page per concept, a tuning guide with tables, recipes, framework examples, the generated API reference and a playground that runs the engine in your browser.
 
-## How it works
-
-### Intents are Beta distributions
-
-You declare intents. Each has a `prior` probability and a `priorStrength` (how many observations the prior is worth). Internally an intent is a Beta(α, β) distribution with α₀ = prior × priorStrength and β₀ = (1 − prior) × priorStrength. Its current estimate is p = α / (α + β).
-
-### Signals add evidence
-
-Each intent maps event names to weights. A positive weight is evidence *for* the intent and is added to α; a negative weight is evidence *against* and its magnitude is added to β. Events the config doesn't mention cost nothing.
-
-### Repeats within a session count for less
-
-Ten views of the pricing page in one sitting are one burst of interest, not ten independent pieces of evidence. Within an episode, the n-th occurrence of a signal adds less than the first:
-
-```
-n-th occurrence adds   w × log2(1 + 1/n)     1, 0.58, 0.42, 0.32 … of the weight
-n occurrences add      w × log2(1 + n)       every doubling adds one more weight; ten add 3.46, not 10
-```
-
-The count restarts when the episode ends or the intent's outcome arrives, so the same signal in a new session counts fully again. Saturation is on by default when `episodeTimeout` is set. Without it, episodes end only when you call `endEpisode`, so repeats add their full weight unless you set `saturate: true`. For intents where the repetition itself is the evidence (a user stuck on the same step), set `saturate: false` and every occurrence adds its full weight.
-
-### Evidence decays toward the prior
-
-Before any update or reading, the evidence decays by 2^(−Δt / halfLife), where Δt is the time since the intent was last updated. Only the *excess over the prior* decays: with no events, p drifts back to `prior` and α + β back to `priorStrength`. Someone who looked at pricing a month ago is not someone who looked at pricing today.
-
-### 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**.
-
-A signal's weight is then a blend of your prior and the learned estimate:
-
-```
-nWith    = hits + misses                                      episodes with the signal
-nWithout = episodes − nWith                                   episodes without it
-qWith    = (hits + 1) / (nWith + 2)                           outcome rate with the signal
-qWithout = (outcomes − hits + 1) / (nWithout + 2)             outcome rate without it
-lift     = (qWith − qWithout) / (1 − qWithout)  if qWith ≥ qWithout,  else  (qWith − qWithout) / qWithout   → in [−1, 1]
-learned  = gain × |w₀| × lift                                 0 until the signal has history
-nEff     = (nWith × nWithout) / (nWith + nWithout)            0 if either side is 0
-effective = (k × w₀ + nEff × learned) / (k + nEff)            k = priorEpisodes
-```
-
-`w₀` is your initial weight, `gain` (default 2) caps how far a perfectly predictive signal can grow, and `priorEpisodes` (default 10) is how much contrast it takes for the user's own history to count as much as your guess. A signal's strength and your confidence in it are separate knobs. A signal is judged against the sessions in which it did *not* appear, so for an outcome that happens in 3% of sessions, a signal followed by it 30% of the time is strong evidence, not weak. And learning needs contrast: a signal that has never been absent has no counterfactual, so its weight stands until there are sessions without it. Nothing drifts after a single outcome.
-
-Learned counts never decay unless you set `learning.halfLife`.
-
-### Reveal only when confident
-
-`shouldReveal` is true when p ≥ threshold **and** p − z·sd ≥ threshold, where sd is the Beta standard deviation and z defaults to 1.28 (a one-sided 90% bound). Thin evidence with a high mean does not fire; it takes a few consistent signals. That lower bound is a normal approximation; `bound: 'exact'` swaps in the Beta distribution's own quantile at the same level, which asks for a little more on thin evidence. After you `markRevealed`, the intent stays revealed for a `cooldown` (default: its half-life) so you don't fire on every event. The same cooldown runs after the intent's outcome event. `predict` reports both: `revealed` is true inside a reveal cooldown, and `suppressedUntil` is when the later of the two cooldowns ends, or null when `shouldReveal` is free to fire.
-
-### Outcomes reset the slate and pause reveals
-
-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`.
-
-### Every answer comes with its reasons
-
-`explain` returns, per signal, how much evidence it currently holds and how much p would move without it, plus the initial, learned and effective weights and the hit/miss record. If a reveal looks wrong, you can see exactly why it fired.
-
 ## Examples
 
 The ad case is one of these, not the point of the library.
@@ -212,36 +159,93 @@ const willBuy = {
 
 More in the docs: [Recipes](https://yuribenjamin.github.io/oracular/guide/recipes) and the [Tuning guide](https://yuribenjamin.github.io/oracular/guide/tuning).
 
+## How it works
+
+### Intents are Beta distributions
+
+You declare intents. Each has a `prior` probability and a `priorStrength` (how many observations the prior is worth). Internally an intent is a Beta(α, β) distribution with α₀ = prior × priorStrength and β₀ = (1 − prior) × priorStrength. Its current estimate is p = α / (α + β).
+
+### Signals add evidence
+
+Each intent maps event names to weights. A positive weight is evidence *for* the intent and is added to α; a negative weight is evidence *against* and its magnitude is added to β. Events the config doesn't mention cost nothing.
+
+### Repeats within a session count for less
+
+Ten views of the pricing page in one sitting are one burst of interest, not ten independent pieces of evidence. Within an episode, the n-th occurrence of a signal adds less than the first:
+
+```
+n-th occurrence adds   w × log2(1 + 1/n)     1, 0.58, 0.42, 0.32 … of the weight
+n occurrences add      w × log2(1 + n)       every doubling adds one more weight; ten add 3.46, not 10
+```
+
+The count restarts when the episode ends or the intent's outcome arrives, so the same signal in a new session counts fully again. Saturation is on by default when `episodeTimeout` is set. Without it, episodes end only when you call `endEpisode`, so repeats add their full weight unless you set `saturate: true`. For intents where the repetition itself is the evidence (a user stuck on the same step), set `saturate: false` and every occurrence adds its full weight.
+
+### Evidence decays toward the prior
+
+Before any update or reading, the evidence decays by 2^(−Δt / halfLife), where Δt is the time since the intent was last updated. Only the *excess over the prior* decays: with no events, p drifts back to `prior` and α + β back to `priorStrength`. Someone who looked at pricing a month ago is not someone who looked at pricing today.
+
+### 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**.
+
+A signal's weight is then a blend of your prior and the learned estimate:
+
+```
+nWith    = hits + misses                                      episodes with the signal
+nWithout = episodes − nWith                                   episodes without it
+qWith    = (hits + 1) / (nWith + 2)                           outcome rate with the signal
+qWithout = (outcomes − hits + 1) / (nWithout + 2)             outcome rate without it
+lift     = (qWith − qWithout) / (1 − qWithout)  if qWith ≥ qWithout,  else  (qWith − qWithout) / qWithout   → in [−1, 1]
+learned  = gain × |w₀| × lift                                 0 until the signal has history
+nEff     = (nWith × nWithout) / (nWith + nWithout)            0 if either side is 0
+effective = (k × w₀ + nEff × learned) / (k + nEff)            k = priorEpisodes
+```
+
+`w₀` is your initial weight, `gain` (default 2) caps the learned magnitude at `gain × |w₀|` for every lift option, and `priorEpisodes` (default 10) is how much contrast it takes for the user's own history to count as much as your guess. A signal's strength and your confidence in it are separate knobs. A signal is judged against the sessions in which it did *not* appear, so for an outcome that happens in 3% of sessions, a signal followed by it 30% of the time is strong evidence, not weak. And learning needs contrast: a signal that has never been absent has no counterfactual, so its weight stands until there are sessions without it. Nothing drifts after a single outcome.
+
+The formula above is the default **normalized difference**. `learning.lift` is an optional
+setting for advanced users who want to choose the learning scale. Choose another at construction with
+`createState({ intents, learning: { lift: 'relative-lift' } })`. Omit `learning.lift` to keep the
+current behavior, including when loading older saved states. The available names and formulas
+are listed in [Episodes & learning](https://yuribenjamin.github.io/oracular/guide/concepts/episodes-and-learning#choosing-a-lift-formula).
+Every choice produces a signed evidence score in [−1, 1], with independence at zero. Ratios use
+`(R − 1) / (R + 1)`, relative/log lift use `x / (1 + |x|)`, and absolute/normalized differences
+keep their scale. Learning uses `gain × |w₀| × score`; `oracular tune` uses the same score for
+weights and intervals and reports raw lift separately when it differs from the score.
+
+Learned counts never decay unless you set `learning.halfLife`.
+
+### Reveal only when confident
+
+`shouldReveal` is true when p ≥ threshold **and** p − z·sd ≥ threshold, where sd is the Beta standard deviation and z defaults to 1.28 (a one-sided 90% bound). Thin evidence with a high mean does not fire; it takes a few consistent signals. That lower bound is a normal approximation; `bound: 'exact'` swaps in the Beta distribution's own quantile at the same level, which asks for a little more on thin evidence. After you `markRevealed`, the intent stays revealed for a `cooldown` (default: its half-life) so you don't fire on every event. The same cooldown runs after the intent's outcome event. `predict` reports both: `revealed` is true inside a reveal cooldown, and `suppressedUntil` is when the later of the two cooldowns ends, or null when `shouldReveal` is free to fire.
+
+### Outcomes reset the slate and pause reveals
+
+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`.
+
+### Every answer comes with its reasons
+
+`explain` returns, per signal, how much evidence it currently holds and how much p would move without it, plus the initial, learned and effective weights and the hit/miss record. If a reveal looks wrong, you can see exactly why it fired.
+
 ## Using with React
 
-oracular ships no framework code; this is the userland shape. Load with your current config, observe, persist on change:
+`@oracular/react` is the binding: a framework-free store, the `useIntent` hook, a provider, and adapters for `localStorage`, AsyncStorage and MMKV.
 
 ```tsx
-import { useEffect, useState } from 'react';
-import { createState, deserialize, markRevealed, observe, serialize, shouldReveal } from 'oracular';
+import { createIntentStore, localStorageAdapter, useIntent } from '@oracular/react';
 import { config } from './intent-config';
 
-function load() {
-  const saved = localStorage.getItem('oracular');
-  return saved ? deserialize(saved, { config }) : createState(config); // always pass the config you ship now
-}
-
-export function useIntent() {
-  const [state, setState] = useState(load);
-  useEffect(() => localStorage.setItem('oracular', serialize(state)), [state]);
+export const store = createIntentStore(config, { persist: localStorageAdapter() }); // once, for the app
 
-  const track = (name: string) => setState((s) => observe(s, { name, at: Date.now() }));
-  const reveal = (intent: string) => {
-    const now = Date.now();
-    if (!shouldReveal(state, intent, now)) return false;
-    setState((s) => markRevealed(s, intent, now));
-    return true;
-  };
-  return { track, reveal };
+export function Pricing() {
+  const { track, reveal } = useIntent(store);
+  return <button onClick={() => { track('pricing.viewed'); if (reveal('upgrade')) openOffer(); }}>See plans</button>;
 }
 ```
 
-Add `endEpisode` on `pagehide` and you have the whole lifecycle. The same loop for Vue, React Native and Node is on the [frameworks page](https://yuribenjamin.github.io/oracular/guide/frameworks).
+Reads go to the store's current state, so `track` then `reveal` in the same click sees the event. The hook loads the persisted state on mount, flushes the pending save when the page hides and on unmount, and never ends an episode on those events; set `episodeTimeout` and idle gaps end sessions on their own. The same loop for Vue, React Native and Node, and the hook written by hand, are on the [frameworks page](https://yuribenjamin.github.io/oracular/guide/frameworks); a runnable app is in [`examples/react-vite`](./examples/react-vite).
 
 ## API
 
@@ -277,7 +281,8 @@ interface EngineConfig {
   episodeTimeout?: number;   // idle gap that ends an episode; off if omitted
   learning?: {
     halfLife?: number;       // forgetting of learned counts; off if omitted
-    gain?: number;           // learned weight cap = gain × |initial|; default 2, at most 1e6
+    gain?: number;           // learned weight multiplier; default 2, at most 1e6
+    lift?: LiftType;         // default 'normalized-difference'; see Episodes & learning
     priorEpisodes?: number;  // pseudo-count behind your weights; default 10, at most 1e6
   };
   reveal?: RevealOptions;    // defaults for every intent
@@ -411,7 +416,7 @@ npx oracular tune shadow.ndjson --config oracular.config.json
 
 ## Roadmap
 
-The 0.4 theme, **learning that matches how people behave**, is complete: cross-episode attribution (`attribution` on an intent, so a session's signals earn a share of an outcome days later), `npx oracular tune` to seed a config from a shadow log, presets, and small ergonomics (`validateConfig`, `ms`, a JSON Schema for the config). 0.3 shipped shadow mode, `npx oracular replay` and per-episode saturation. Next is the road to 1.0, whose criteria are on [Stability and 1.0](https://yuribenjamin.github.io/oracular/guide/stability). Framework bindings wait for a third integration. The full list, with the reasoning and what was declined, is on the [roadmap page](https://yuribenjamin.github.io/oracular/guide/roadmap).
+The 0.4 theme, **learning that matches how people behave**, is complete: cross-episode attribution (`attribution` on an intent, so a session's signals earn a share of an outcome days later), `npx oracular tune` to seed a config from a shadow log, presets, and small ergonomics (`validateConfig`, `ms`, a JSON Schema for the config). 0.3 shipped shadow mode, `npx oracular replay` and per-episode saturation. Next is the road to 1.0, whose criteria are on [Stability and 1.0](https://yuribenjamin.github.io/oracular/guide/stability). `@oracular/react` ships the React binding; a Vue composable follows the same store. The full list, with the reasoning and what was declined, is on the [roadmap page](https://yuribenjamin.github.io/oracular/guide/roadmap).
 
 ## Contributing
 

package/dist/cli.js

@@ -432,10 +432,39 @@ import {
 function laplace(successes, total) {
   return (successes + 1) / (total + 2);
 }
-function lift(q, b) {
+function lift(q, b, type = "normalized-difference") {
+  if (type === "absolute-difference") return q - b;
+  if (type !== "normalized-difference") {
+    const rate = Math.max(Number.EPSILON, Math.min(1 - Number.EPSILON, q));
+    const base = Math.max(Number.EPSILON, Math.min(1 - Number.EPSILON, b));
+    switch (type) {
+      case "relative-lift":
+        return (rate - base) / base;
+      case "log-lift":
+        return Math.log(rate / base);
+      case "odds-ratio":
+        return rate / (1 - rate) / (base / (1 - base));
+      case "risk-ratio":
+      case "association-rule":
+        return rate / base;
+    }
+  }
   if (q >= b) return b >= 1 ? 0 : (q - b) / (1 - b);
   return b <= 0 ? 0 : (q - b) / b;
 }
+function learningScore(value, type = "normalized-difference") {
+  switch (type) {
+    case "risk-ratio":
+    case "odds-ratio":
+    case "association-rule":
+      return (value - 1) / (value + 1);
+    case "relative-lift":
+    case "log-lift":
+      return value / (1 + Math.abs(value));
+    default:
+      return value;
+  }
+}
 
 // cli/tune.ts
 var HOUR2 = 36e5;
@@ -488,7 +517,7 @@ function wilson(successes, n, z) {
   const half = z / (1 + z2 / n) * Math.sqrt(p * (1 - p) / n + z2 / (4 * n * n));
   return [Math.max(0, centre - half), Math.min(1, centre + half)];
 }
-function fitSignal(signal, current, tally, strength, priorEpisodes) {
+function fitSignal(signal, current, tally, strength, priorEpisodes, liftType) {
   const hits = own(tally.hits, signal);
   const misses = own(tally.misses, signal);
   const nWith = hits + misses;
@@ -496,10 +525,12 @@ function fitSignal(signal, current, tally, strength, priorEpisodes) {
   const outcomesWithout = Math.min(without, Math.max(0, tally.outcomes - hits));
   const qWith = laplace(hits, nWith);
   const qWithout = laplace(outcomesWithout, without);
-  const l = nWith === 0 ? 0 : lift(qWith, qWithout);
+  const baseline = liftType === "association-rule" ? (hits + outcomesWithout + 2) / (nWith + without + 4) : qWithout;
+  const rawLift = nWith === 0 ? 0 : lift(qWith, baseline, liftType);
+  const score = nWith === 0 ? 0 : learningScore(rawLift, liftType);
   const contrast = nWith + without === 0 ? 0 : nWith * without / (nWith + without);
   const [qLow, qHigh] = wilson(hits, nWith, Z90);
-  const rounded = Math.round(strength * l * 100) / 100;
+  const rounded = Math.round(strength * score * 100) / 100;
   const share = tally.episodes === 0 ? 0 : nWith / tally.episodes;
   const ubiquitous = nWith > UBIQUITY_SHARE * tally.episodes;
   return {
@@ -511,12 +542,13 @@ function fitSignal(signal, current, tally, strength, priorEpisodes) {
     outcomesWithout,
     qWith,
     qWithout,
-    lift: l,
+    lift: rawLift,
+    score,
     weight: nWith === 0 || ubiquitous || rounded === 0 ? null : rounded,
     share,
     ubiquitous,
-    low: strength * lift(qLow, qWithout),
-    high: strength * lift(qHigh, qWithout),
+    low: strength * learningScore(lift(qLow, baseline, liftType), liftType),
+    high: strength * learningScore(lift(qHigh, baseline, liftType), liftType),
     contrast,
     thin: contrast < priorEpisodes
   };
@@ -593,6 +625,7 @@ function tune(entries, config, options = {}) {
   const normalized = base.config;
   const includeLive = options.includeLive === true;
   const priorEpisodes = normalized.learning?.priorEpisodes ?? DEFAULT_PRIOR_EPISODES;
+  const liftType = normalized.learning?.lift ?? "normalized-difference";
   const skipped = [];
   const names = options.intents ?? Object.keys(normalized.intents);
   for (const name of names) {
@@ -691,10 +724,17 @@ function tune(entries, config, options = {}) {
     const prior = laplace(tally.outcomes, tally.episodes);
     const strength = fitStrength(plan.installs, intent.priorStrength);
     const signals = Object.keys(intent.signals).map(
-      (signal) => fitSignal(signal, intent.signals[signal], tally, strength.value, priorEpisodes)
+      (signal) => fitSignal(
+        signal,
+        intent.signals[signal],
+        tally,
+        strength.value,
+        priorEpisodes,
+        liftType
+      )
     );
     const candidates = plan.candidates.map(
-      (signal) => fitSignal(signal, null, tally, strength.value, priorEpisodes)
+      (signal) => fitSignal(signal, null, tally, strength.value, priorEpisodes, liftType)
     );
     const roundedPrior = Math.round(prior * 1e4) / 1e4;
     const fittedIntent = {
@@ -816,12 +856,14 @@ function note(fit, priorEpisodes) {
   return notes.join("; ");
 }
 function signalTable(fits, priorEpisodes, withCurrent) {
+  const showScore = fits.some((fit) => fit.score !== fit.lift);
   const headers = [
     "signal",
     "weight",
     ...withCurrent ? ["was"] : [],
     "90% interval",
     "lift",
+    ...showScore ? ["score"] : [],
     "with: hits / misses",
     "without: outcomes / episodes",
     "note"
@@ -834,6 +876,7 @@ function signalTable(fits, priorEpisodes, withCurrent) {
       ...withCurrent ? [num(f.current, 2)] : [],
       `${f.low.toFixed(2)} to ${f.high.toFixed(2)}`,
       signed(f.lift, 2),
+      ...showScore ? [signed(f.score, 2)] : [],
       `${f.hits} / ${f.misses}`,
       `${f.outcomesWithout} / ${f.without}`,
       note(f, priorEpisodes)

package/dist/index.cjs

@@ -82,10 +82,39 @@ function repeatFactor(n) {
 function laplace(successes, total) {
   return (successes + 1) / (total + 2);
 }
-function lift(q, b) {
+function lift(q, b, type = "normalized-difference") {
+  if (type === "absolute-difference") return q - b;
+  if (type !== "normalized-difference") {
+    const rate = Math.max(Number.EPSILON, Math.min(1 - Number.EPSILON, q));
+    const base = Math.max(Number.EPSILON, Math.min(1 - Number.EPSILON, b));
+    switch (type) {
+      case "relative-lift":
+        return (rate - base) / base;
+      case "log-lift":
+        return Math.log(rate / base);
+      case "odds-ratio":
+        return rate / (1 - rate) / (base / (1 - base));
+      case "risk-ratio":
+      case "association-rule":
+        return rate / base;
+    }
+  }
   if (q >= b) return b >= 1 ? 0 : (q - b) / (1 - b);
   return b <= 0 ? 0 : (q - b) / b;
 }
+function learningScore(value, type = "normalized-difference") {
+  switch (type) {
+    case "risk-ratio":
+    case "odds-ratio":
+    case "association-rule":
+      return (value - 1) / (value + 1);
+    case "relative-lift":
+    case "log-lift":
+      return value / (1 + Math.abs(value));
+    default:
+      return value;
+  }
+}
 
 // src/util.ts
 function isRecord(value) {
@@ -131,7 +160,9 @@ function signalWeights(state, intent, learning, signal) {
   const nWithout = Math.max(0, totalEpisodes - nWith);
   const outcomesWithout = Math.min(nWithout, Math.max(0, state.episodes.hits - record2.hits));
   const qWithout = laplace(outcomesWithout, nWithout);
-  const learned = nWith === 0 ? 0 : learning.gain * Math.abs(initial) * lift(qWith, qWithout);
+  const baseline = learning.lift === "association-rule" ? (record2.hits + outcomesWithout + 2) / (nWith + nWithout + 4) : qWithout;
+  const score = learningScore(lift(qWith, baseline, learning.lift), learning.lift);
+  const learned = nWith === 0 ? 0 : learning.gain * Math.abs(initial) * score;
   const nEff = nWith + nWithout === 0 ? 0 : nWith * nWithout / (nWith + nWithout);
   const k = learning.priorEpisodes;
   const effective = (k * initial + nEff * learned) / (k + nEff);
@@ -257,7 +288,16 @@ var INTENT_KEYS = [
   "reveal"
 ];
 var REVEAL_KEYS = ["threshold", "z", "cooldown", "bound"];
-var LEARNING_KEYS = ["halfLife", "gain", "priorEpisodes"];
+var LEARNING_KEYS = ["halfLife", "gain", "priorEpisodes", "lift"];
+var LIFT_TYPES = [
+  "absolute-difference",
+  "relative-lift",
+  "risk-ratio",
+  "log-lift",
+  "odds-ratio",
+  "normalized-difference",
+  "association-rule"
+];
 var EXPLAIN_KEYS = ["nonZero", "limit"];
 function typeError(path, message) {
   throw new TypeError(`oracular: ${path} ${message}`);
@@ -342,6 +382,12 @@ function normalizeLearning(value, path) {
   const record2 = expectRecord(value, path);
   expectKeys(record2, LEARNING_KEYS, path);
   const out = {};
+  if (record2.lift !== void 0) {
+    if (!LIFT_TYPES.includes(record2.lift)) {
+      typeError(`${path}.lift`, `must be one of: ${LIFT_TYPES.join(", ")}`);
+    }
+    out.lift = record2.lift;
+  }
   if (record2.halfLife !== void 0)
     out.halfLife = expectPositive(record2.halfLife, `${path}.halfLife`);
   if (record2.gain !== void 0) out.gain = expectBoundedPositive(record2.gain, `${path}.gain`);
@@ -462,6 +508,7 @@ function resolveReveal(config, intent, opts, normalized = false) {
 }
 function resolveLearning(config) {
   return {
+    lift: config.learning?.lift ?? "normalized-difference",
     halfLife: config.learning?.halfLife ?? null,
     gain: config.learning?.gain ?? DEFAULT_GAIN,
     priorEpisodes: config.learning?.priorEpisodes ?? DEFAULT_PRIOR_EPISODES