oracular 0.8.1 → 0.10.0

package/dist/presets.cjs

@@ -47,13 +47,20 @@ var churn = {
   outcome: "account.cancelled",
   reveal: { threshold: 0.5, z: 1.64 }
 };
-var presets = {
+function freeze(value) {
+  if (typeof value === "object" && value !== null) {
+    for (const inner of Object.values(value)) freeze(inner);
+    Object.freeze(value);
+  }
+  return value;
+}
+var presets = freeze({
   willBuy,
   upgrade,
   stuck,
   churn
-};
-var presetSources = {
+});
+var presetSources = freeze({
   willBuy: {
     kind: "tuned",
     note: "oracular tune on a public e-commerce clickstream: one shop, May to September 2015, 2.7 million events, 4.8% of sessions ending with an order; fitted October 2026, the fitted 0.0477 and 2.32 rounded",
@@ -78,7 +85,7 @@ var presetSources = {
     episodes: null,
     installs: null
   }
-};
+});
 
 exports.presetSources = presetSources;
 exports.presets = presets;

package/dist/presets.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/units.ts","../src/presets.ts"],"names":[],"mappings":"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","file":"presets.cjs","sourcesContent":["/** The units of {@link ms}: each takes a count and returns milliseconds. */\nexport interface Units {\n  /** `n` seconds in milliseconds: `n × 1000`. */\n  readonly seconds: (n: number) => number;\n  /** `n` minutes in milliseconds: `n × 60 000`. */\n  readonly minutes: (n: number) => number;\n  /** `n` hours in milliseconds: `n × 3 600 000`. */\n  readonly hours: (n: number) => number;\n  /** `n` days in milliseconds: `n × 86 400 000`. */\n  readonly days: (n: number) => number;\n  /** `n` weeks in milliseconds: `n × 604 800 000`. */\n  readonly weeks: (n: number) => number;\n}\n\n/**\n * Durations in milliseconds, the unit of `Date.now()`: `ms.days(7)` is `604800000`. Plain\n * multiplications and nothing else, for `halfLife`, `cooldown`, `episodeTimeout` and\n * `learning.halfLife` when your timestamps are in milliseconds. If your `at` is in another unit,\n * write durations in that unit instead: the engine only needs the two to agree.\n *\n * @example\n * ```ts\n * const config = {\n *   episodeTimeout: ms.minutes(30),\n *   intents: {\n *     upgrade: {\n *       prior: 0.05,\n *       priorStrength: 10,\n *       halfLife: ms.days(7),\n *       signals: { 'pricing.viewed': 3 },\n *       reveal: { cooldown: ms.weeks(2) },\n *     },\n *   },\n * };\n * ```\n */\nexport const ms: Units = {\n  seconds: (n) => n * 1_000,\n  minutes: (n) => n * 60_000,\n  hours: (n) => n * 3_600_000,\n  days: (n) => n * 86_400_000,\n  weeks: (n) => n * 604_800_000,\n};\n","import type { IntentConfig, PresetName, PresetSource } from './types';\nimport { ms } from './units';\n\nexport type { PresetName, PresetSource } from './types';\n\n/**\n * A visitor about to buy. Tuned on a public e-commerce clickstream of 2.7 million events (see the\n * case study in the guide): one shop, one summer (May to September 2015), 181,080 sessions from\n * 93,537 visitors, 8,628 of them ending with an order, a session conversion of 4.8%; scored on as\n * many visitors the fit never saw. A measured starting point, not a universal number: a shop that\n * converts 1% or 20% of its sessions has a different prior and most likely a different weight.\n * Start here, run in shadow mode, and let `tune` replace these with your own numbers.\n *\n * - `prior` 0.048: the share of sessions that end with an order (fitted 0.0477).\n * - `priorStrength` 4: visitors differ a lot in how often they buy, so one visitor's own history\n *   should outweigh the population after a handful of sessions.\n * - `halfLife` one hour: the best point of the grid; buying intent within a visit is a matter of\n *   minutes, and tomorrow's visit starts over.\n * - `cart.added` 2.3: its measured lift (fitted 2.32). 58% of sessions with a cart add end with an\n *   order, against 0.8% of those without. There is no weight for viewing a product: on that data a\n *   view is in 99% of sessions and says nothing about buying. Add one only if your data disagrees.\n * - `cooldown` one day: after an order, or after acting on the intent, stay quiet for a day; the\n *   half-life would otherwise make the default cooldown an hour.\n *\n * Rename `cart.added` and `checkout.completed` to your events by spreading.\n */\nconst willBuy: IntentConfig = {\n  prior: 0.048,\n  priorStrength: 4,\n  halfLife: ms.hours(1),\n  signals: { 'cart.added': 2.3 },\n  outcome: 'checkout.completed',\n  reveal: { cooldown: ms.days(1) },\n};\n\n/**\n * A user about to upgrade: the quickstart config, hand-written. Interest in a paid plan builds over\n * days, so the half-life is a week; the prior is a guess at the share of users who upgrade in a\n * week; `priorStrength` 10 means about six full-weight signals across sessions open the default\n * gate; the weights rank the signals by how directly they point at paying. Nobody has measured\n * these against a log.\n */\nconst upgrade: IntentConfig = {\n  prior: 0.05,\n  priorStrength: 10,\n  halfLife: ms.days(7),\n  signals: { 'pricing.viewed': 3, 'limit.hit': 2, 'export.clicked': 1 },\n  outcome: 'upgrade.completed',\n};\n\n/**\n * A user stuck on a task, hand-written. Being stuck is a state of the current session, so the\n * half-life is ten minutes and the cooldown an hour; `saturate: false` because here repetition is\n * the evidence (the fifth undo in a row says more than the first); `task.completed` is strong\n * evidence against; the gate is raised to 0.6 because an unwanted tip is an interruption. Nobody\n * has measured these against a log.\n */\nconst stuck: IntentConfig = {\n  prior: 0.1,\n  priorStrength: 5,\n  halfLife: ms.minutes(10),\n  signals: { 'editor.undo': 1, 'search.empty': 2, 'help.opened': 3, 'task.completed': -4 },\n  outcome: 'help.article.read',\n  saturate: false,\n  reveal: { threshold: 0.6, cooldown: ms.hours(1) },\n};\n\n/**\n * A user about to leave, hand-written. Churn builds over weeks, so the half-life is two weeks and\n * the prior strength 20: it should take a lot to call someone a churn risk. Exporting all their\n * data is the strongest signal; using a new feature counts against. `z` 1.64 asks for a one-sided\n * 95% bound before a save offer, because a discount has a real cost. Nobody has measured these\n * against a log.\n */\nconst churn: IntentConfig = {\n  prior: 0.08,\n  priorStrength: 20,\n  halfLife: ms.days(14),\n  signals: {\n    'session.short': 1,\n    'notifications.disabled': 3,\n    'export.all': 4,\n    'feature.new.used': -2,\n  },\n  outcome: 'account.cancelled',\n  reveal: { threshold: 0.5, z: 1.64 },\n};\n\n/**\n * Starting points for four common intents, as plain config objects. Spread one into your config,\n * rename its events to yours, override what you know better; see {@link presetSources} for where\n * each preset's numbers come from.\n *\n * @example\n * ```ts\n * import { presets } from 'oracular/presets';\n *\n * const config = {\n *   episodeTimeout: 30 * 60 * 1000,\n *   intents: {\n *     buy: { ...presets.willBuy, outcome: 'order.placed' },\n *   },\n * };\n * ```\n */\nexport const presets: Readonly<Record<PresetName, IntentConfig>> = {\n  willBuy,\n  upgrade,\n  stuck,\n  churn,\n};\n\n/**\n * Where each preset's numbers come from. Read it before trusting a preset: a tuned one carries its\n * sample size, a hand-written one carries nothing but reasoning.\n *\n * @example\n * ```ts\n * import { presetSources } from 'oracular/presets';\n * presetSources.willBuy.kind; // 'tuned'\n * ```\n */\nexport const presetSources: Readonly<Record<PresetName, PresetSource>> = {\n  willBuy: {\n    kind: 'tuned',\n    note: 'oracular tune on a public e-commerce clickstream: one shop, May to September 2015, 2.7 million events, 4.8% of sessions ending with an order; fitted October 2026, the fitted 0.0477 and 2.32 rounded',\n    episodes: 181_080,\n    installs: 93_537,\n  },\n  upgrade: {\n    kind: 'hand-written',\n    note: 'the quickstart config from the documentation; no log behind it',\n    episodes: null,\n    installs: null,\n  },\n  stuck: {\n    kind: 'hand-written',\n    note: 'the onboarding-tip example from the documentation; no log behind it',\n    episodes: null,\n    installs: null,\n  },\n  churn: {\n    kind: 'hand-written',\n    note: 'the churn-save example from the documentation; no log behind it',\n    episodes: null,\n    installs: null,\n  },\n};\n"]}
+{"version":3,"sources":["../src/units.ts","../src/presets.ts"],"names":[],"mappings":"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","file":"presets.cjs","sourcesContent":["/** The units of {@link ms}: each takes a count and returns milliseconds. */\nexport interface Units {\n  /** `n` seconds in milliseconds: `n × 1000`. */\n  readonly seconds: (n: number) => number;\n  /** `n` minutes in milliseconds: `n × 60 000`. */\n  readonly minutes: (n: number) => number;\n  /** `n` hours in milliseconds: `n × 3 600 000`. */\n  readonly hours: (n: number) => number;\n  /** `n` days in milliseconds: `n × 86 400 000`. */\n  readonly days: (n: number) => number;\n  /** `n` weeks in milliseconds: `n × 604 800 000`. */\n  readonly weeks: (n: number) => number;\n}\n\n/**\n * Durations in milliseconds, the unit of `Date.now()`: `ms.days(7)` is `604800000`. Plain\n * multiplications and nothing else, for `halfLife`, `cooldown`, `episodeTimeout` and\n * `learning.halfLife` when your timestamps are in milliseconds. If your `at` is in another unit,\n * write durations in that unit instead: the engine only needs the two to agree.\n *\n * @example\n * ```ts\n * const config = {\n *   episodeTimeout: ms.minutes(30),\n *   intents: {\n *     upgrade: {\n *       prior: 0.05,\n *       priorStrength: 10,\n *       halfLife: ms.days(7),\n *       signals: { 'pricing.viewed': 3 },\n *       reveal: { cooldown: ms.weeks(2) },\n *     },\n *   },\n * };\n * ```\n */\nexport const ms: Units = {\n  seconds: (n) => n * 1_000,\n  minutes: (n) => n * 60_000,\n  hours: (n) => n * 3_600_000,\n  days: (n) => n * 86_400_000,\n  weeks: (n) => n * 604_800_000,\n};\n","import type { IntentConfig, PresetName, PresetSource } from './types';\nimport { ms } from './units';\n\nexport type { PresetName, PresetSource } from './types';\n\n/**\n * A visitor about to buy. Tuned on a public e-commerce clickstream of 2.7 million events (see the\n * case study in the guide): one shop, one summer (May to September 2015), 181,080 sessions from\n * 93,537 visitors, 8,628 of them ending with an order, a session conversion of 4.8%; scored on as\n * many visitors the fit never saw. A measured starting point, not a universal number: a shop that\n * converts 1% or 20% of its sessions has a different prior and most likely a different weight.\n * Start here, run in shadow mode, and let `tune` replace these with your own numbers.\n *\n * - `prior` 0.048: the share of sessions that end with an order (fitted 0.0477).\n * - `priorStrength` 4: visitors differ a lot in how often they buy, so one visitor's own history\n *   should outweigh the population after a handful of sessions.\n * - `halfLife` one hour: the best point of the grid; buying intent within a visit is a matter of\n *   minutes, and tomorrow's visit starts over.\n * - `cart.added` 2.3: its measured lift (fitted 2.32). 58% of sessions with a cart add end with an\n *   order, against 0.8% of those without. There is no weight for viewing a product: on that data a\n *   view is in 99% of sessions and says nothing about buying. Add one only if your data disagrees.\n * - `cooldown` one day: after an order, or after acting on the intent, stay quiet for a day; the\n *   half-life would otherwise make the default cooldown an hour.\n *\n * Rename `cart.added` and `checkout.completed` to your events by spreading.\n */\nconst willBuy: IntentConfig = {\n  prior: 0.048,\n  priorStrength: 4,\n  halfLife: ms.hours(1),\n  signals: { 'cart.added': 2.3 },\n  outcome: 'checkout.completed',\n  reveal: { cooldown: ms.days(1) },\n};\n\n/**\n * A user about to upgrade: the quickstart config, hand-written. Interest in a paid plan builds over\n * days, so the half-life is a week; the prior is a guess at the share of users who upgrade in a\n * week; `priorStrength` 10 means about six full-weight signals across sessions open the default\n * gate; the weights rank the signals by how directly they point at paying. Nobody has measured\n * these against a log.\n */\nconst upgrade: IntentConfig = {\n  prior: 0.05,\n  priorStrength: 10,\n  halfLife: ms.days(7),\n  signals: { 'pricing.viewed': 3, 'limit.hit': 2, 'export.clicked': 1 },\n  outcome: 'upgrade.completed',\n};\n\n/**\n * A user stuck on a task, hand-written. Being stuck is a state of the current session, so the\n * half-life is ten minutes and the cooldown an hour; `saturate: false` because here repetition is\n * the evidence (the fifth undo in a row says more than the first); `task.completed` is strong\n * evidence against; the gate is raised to 0.6 because an unwanted tip is an interruption. Nobody\n * has measured these against a log.\n */\nconst stuck: IntentConfig = {\n  prior: 0.1,\n  priorStrength: 5,\n  halfLife: ms.minutes(10),\n  signals: { 'editor.undo': 1, 'search.empty': 2, 'help.opened': 3, 'task.completed': -4 },\n  outcome: 'help.article.read',\n  saturate: false,\n  reveal: { threshold: 0.6, cooldown: ms.hours(1) },\n};\n\n/**\n * A user about to leave, hand-written. Churn builds over weeks, so the half-life is two weeks and\n * the prior strength 20: it should take a lot to call someone a churn risk. Exporting all their\n * data is the strongest signal; using a new feature counts against. `z` 1.64 asks for a one-sided\n * 95% bound before a save offer, because a discount has a real cost. Nobody has measured these\n * against a log.\n */\nconst churn: IntentConfig = {\n  prior: 0.08,\n  priorStrength: 20,\n  halfLife: ms.days(14),\n  signals: {\n    'session.short': 1,\n    'notifications.disabled': 3,\n    'export.all': 4,\n    'feature.new.used': -2,\n  },\n  outcome: 'account.cancelled',\n  reveal: { threshold: 0.5, z: 1.64 },\n};\n\n/**\n * Starting points for four common intents, as plain config objects. Spread one into your config,\n * rename its events to yours, override what you know better; see {@link presetSources} for where\n * each preset's numbers come from.\n *\n * @example\n * ```ts\n * import { presets } from 'oracular/presets';\n *\n * const config = {\n *   episodeTimeout: 30 * 60 * 1000,\n *   intents: {\n *     buy: { ...presets.willBuy, outcome: 'order.placed' },\n *   },\n * };\n * ```\n */\n/** Frozen through and through: a preset is shared, so a change by one caller would reach every other. */\nfunction freeze<T>(value: T): T {\n  if (typeof value === 'object' && value !== null) {\n    for (const inner of Object.values(value)) freeze(inner);\n    Object.freeze(value);\n  }\n  return value;\n}\n\nexport const presets: Readonly<Record<PresetName, IntentConfig>> = freeze({\n  willBuy,\n  upgrade,\n  stuck,\n  churn,\n});\n\n/**\n * Where each preset's numbers come from. Read it before trusting a preset: a tuned one carries its\n * sample size, a hand-written one carries nothing but reasoning.\n *\n * @example\n * ```ts\n * import { presetSources } from 'oracular/presets';\n * presetSources.willBuy.kind; // 'tuned'\n * ```\n */\nexport const presetSources: Readonly<Record<PresetName, PresetSource>> = freeze({\n  willBuy: {\n    kind: 'tuned',\n    note: 'oracular tune on a public e-commerce clickstream: one shop, May to September 2015, 2.7 million events, 4.8% of sessions ending with an order; fitted October 2026, the fitted 0.0477 and 2.32 rounded',\n    episodes: 181_080,\n    installs: 93_537,\n  },\n  upgrade: {\n    kind: 'hand-written',\n    note: 'the quickstart config from the documentation; no log behind it',\n    episodes: null,\n    installs: null,\n  },\n  stuck: {\n    kind: 'hand-written',\n    note: 'the onboarding-tip example from the documentation; no log behind it',\n    episodes: null,\n    installs: null,\n  },\n  churn: {\n    kind: 'hand-written',\n    note: 'the churn-save example from the documentation; no log behind it',\n    episodes: null,\n    installs: null,\n  },\n});\n"]}

package/dist/presets.d.cts

@@ -103,23 +103,6 @@ interface PresetSource {
     installs: number | null;
 }
 
-/**
- * Starting points for four common intents, as plain config objects. Spread one into your config,
- * rename its events to yours, override what you know better; see {@link presetSources} for where
- * each preset's numbers come from.
- *
- * @example
- * ```ts
- * import { presets } from 'oracular/presets';
- *
- * const config = {
- *   episodeTimeout: 30 * 60 * 1000,
- *   intents: {
- *     buy: { ...presets.willBuy, outcome: 'order.placed' },
- *   },
- * };
- * ```
- */
 declare const presets: Readonly<Record<PresetName, IntentConfig>>;
 /**
  * Where each preset's numbers come from. Read it before trusting a preset: a tuned one carries its

package/dist/presets.d.ts

@@ -103,23 +103,6 @@ interface PresetSource {
     installs: number | null;
 }
 
-/**
- * Starting points for four common intents, as plain config objects. Spread one into your config,
- * rename its events to yours, override what you know better; see {@link presetSources} for where
- * each preset's numbers come from.
- *
- * @example
- * ```ts
- * import { presets } from 'oracular/presets';
- *
- * const config = {
- *   episodeTimeout: 30 * 60 * 1000,
- *   intents: {
- *     buy: { ...presets.willBuy, outcome: 'order.placed' },
- *   },
- * };
- * ```
- */
 declare const presets: Readonly<Record<PresetName, IntentConfig>>;
 /**
  * Where each preset's numbers come from. Read it before trusting a preset: a tuned one carries its

package/dist/presets.js

@@ -45,13 +45,20 @@ var churn = {
   outcome: "account.cancelled",
   reveal: { threshold: 0.5, z: 1.64 }
 };
-var presets = {
+function freeze(value) {
+  if (typeof value === "object" && value !== null) {
+    for (const inner of Object.values(value)) freeze(inner);
+    Object.freeze(value);
+  }
+  return value;
+}
+var presets = freeze({
   willBuy,
   upgrade,
   stuck,
   churn
-};
-var presetSources = {
+});
+var presetSources = freeze({
   willBuy: {
     kind: "tuned",
     note: "oracular tune on a public e-commerce clickstream: one shop, May to September 2015, 2.7 million events, 4.8% of sessions ending with an order; fitted October 2026, the fitted 0.0477 and 2.32 rounded",
@@ -76,7 +83,7 @@ var presetSources = {
     episodes: null,
     installs: null
   }
-};
+});
 
 export { presetSources, presets };
 //# sourceMappingURL=presets.js.map

package/dist/presets.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/units.ts","../src/presets.ts"],"names":[],"mappings":"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","file":"presets.js","sourcesContent":["/** The units of {@link ms}: each takes a count and returns milliseconds. */\nexport interface Units {\n  /** `n` seconds in milliseconds: `n × 1000`. */\n  readonly seconds: (n: number) => number;\n  /** `n` minutes in milliseconds: `n × 60 000`. */\n  readonly minutes: (n: number) => number;\n  /** `n` hours in milliseconds: `n × 3 600 000`. */\n  readonly hours: (n: number) => number;\n  /** `n` days in milliseconds: `n × 86 400 000`. */\n  readonly days: (n: number) => number;\n  /** `n` weeks in milliseconds: `n × 604 800 000`. */\n  readonly weeks: (n: number) => number;\n}\n\n/**\n * Durations in milliseconds, the unit of `Date.now()`: `ms.days(7)` is `604800000`. Plain\n * multiplications and nothing else, for `halfLife`, `cooldown`, `episodeTimeout` and\n * `learning.halfLife` when your timestamps are in milliseconds. If your `at` is in another unit,\n * write durations in that unit instead: the engine only needs the two to agree.\n *\n * @example\n * ```ts\n * const config = {\n *   episodeTimeout: ms.minutes(30),\n *   intents: {\n *     upgrade: {\n *       prior: 0.05,\n *       priorStrength: 10,\n *       halfLife: ms.days(7),\n *       signals: { 'pricing.viewed': 3 },\n *       reveal: { cooldown: ms.weeks(2) },\n *     },\n *   },\n * };\n * ```\n */\nexport const ms: Units = {\n  seconds: (n) => n * 1_000,\n  minutes: (n) => n * 60_000,\n  hours: (n) => n * 3_600_000,\n  days: (n) => n * 86_400_000,\n  weeks: (n) => n * 604_800_000,\n};\n","import type { IntentConfig, PresetName, PresetSource } from './types';\nimport { ms } from './units';\n\nexport type { PresetName, PresetSource } from './types';\n\n/**\n * A visitor about to buy. Tuned on a public e-commerce clickstream of 2.7 million events (see the\n * case study in the guide): one shop, one summer (May to September 2015), 181,080 sessions from\n * 93,537 visitors, 8,628 of them ending with an order, a session conversion of 4.8%; scored on as\n * many visitors the fit never saw. A measured starting point, not a universal number: a shop that\n * converts 1% or 20% of its sessions has a different prior and most likely a different weight.\n * Start here, run in shadow mode, and let `tune` replace these with your own numbers.\n *\n * - `prior` 0.048: the share of sessions that end with an order (fitted 0.0477).\n * - `priorStrength` 4: visitors differ a lot in how often they buy, so one visitor's own history\n *   should outweigh the population after a handful of sessions.\n * - `halfLife` one hour: the best point of the grid; buying intent within a visit is a matter of\n *   minutes, and tomorrow's visit starts over.\n * - `cart.added` 2.3: its measured lift (fitted 2.32). 58% of sessions with a cart add end with an\n *   order, against 0.8% of those without. There is no weight for viewing a product: on that data a\n *   view is in 99% of sessions and says nothing about buying. Add one only if your data disagrees.\n * - `cooldown` one day: after an order, or after acting on the intent, stay quiet for a day; the\n *   half-life would otherwise make the default cooldown an hour.\n *\n * Rename `cart.added` and `checkout.completed` to your events by spreading.\n */\nconst willBuy: IntentConfig = {\n  prior: 0.048,\n  priorStrength: 4,\n  halfLife: ms.hours(1),\n  signals: { 'cart.added': 2.3 },\n  outcome: 'checkout.completed',\n  reveal: { cooldown: ms.days(1) },\n};\n\n/**\n * A user about to upgrade: the quickstart config, hand-written. Interest in a paid plan builds over\n * days, so the half-life is a week; the prior is a guess at the share of users who upgrade in a\n * week; `priorStrength` 10 means about six full-weight signals across sessions open the default\n * gate; the weights rank the signals by how directly they point at paying. Nobody has measured\n * these against a log.\n */\nconst upgrade: IntentConfig = {\n  prior: 0.05,\n  priorStrength: 10,\n  halfLife: ms.days(7),\n  signals: { 'pricing.viewed': 3, 'limit.hit': 2, 'export.clicked': 1 },\n  outcome: 'upgrade.completed',\n};\n\n/**\n * A user stuck on a task, hand-written. Being stuck is a state of the current session, so the\n * half-life is ten minutes and the cooldown an hour; `saturate: false` because here repetition is\n * the evidence (the fifth undo in a row says more than the first); `task.completed` is strong\n * evidence against; the gate is raised to 0.6 because an unwanted tip is an interruption. Nobody\n * has measured these against a log.\n */\nconst stuck: IntentConfig = {\n  prior: 0.1,\n  priorStrength: 5,\n  halfLife: ms.minutes(10),\n  signals: { 'editor.undo': 1, 'search.empty': 2, 'help.opened': 3, 'task.completed': -4 },\n  outcome: 'help.article.read',\n  saturate: false,\n  reveal: { threshold: 0.6, cooldown: ms.hours(1) },\n};\n\n/**\n * A user about to leave, hand-written. Churn builds over weeks, so the half-life is two weeks and\n * the prior strength 20: it should take a lot to call someone a churn risk. Exporting all their\n * data is the strongest signal; using a new feature counts against. `z` 1.64 asks for a one-sided\n * 95% bound before a save offer, because a discount has a real cost. Nobody has measured these\n * against a log.\n */\nconst churn: IntentConfig = {\n  prior: 0.08,\n  priorStrength: 20,\n  halfLife: ms.days(14),\n  signals: {\n    'session.short': 1,\n    'notifications.disabled': 3,\n    'export.all': 4,\n    'feature.new.used': -2,\n  },\n  outcome: 'account.cancelled',\n  reveal: { threshold: 0.5, z: 1.64 },\n};\n\n/**\n * Starting points for four common intents, as plain config objects. Spread one into your config,\n * rename its events to yours, override what you know better; see {@link presetSources} for where\n * each preset's numbers come from.\n *\n * @example\n * ```ts\n * import { presets } from 'oracular/presets';\n *\n * const config = {\n *   episodeTimeout: 30 * 60 * 1000,\n *   intents: {\n *     buy: { ...presets.willBuy, outcome: 'order.placed' },\n *   },\n * };\n * ```\n */\nexport const presets: Readonly<Record<PresetName, IntentConfig>> = {\n  willBuy,\n  upgrade,\n  stuck,\n  churn,\n};\n\n/**\n * Where each preset's numbers come from. Read it before trusting a preset: a tuned one carries its\n * sample size, a hand-written one carries nothing but reasoning.\n *\n * @example\n * ```ts\n * import { presetSources } from 'oracular/presets';\n * presetSources.willBuy.kind; // 'tuned'\n * ```\n */\nexport const presetSources: Readonly<Record<PresetName, PresetSource>> = {\n  willBuy: {\n    kind: 'tuned',\n    note: 'oracular tune on a public e-commerce clickstream: one shop, May to September 2015, 2.7 million events, 4.8% of sessions ending with an order; fitted October 2026, the fitted 0.0477 and 2.32 rounded',\n    episodes: 181_080,\n    installs: 93_537,\n  },\n  upgrade: {\n    kind: 'hand-written',\n    note: 'the quickstart config from the documentation; no log behind it',\n    episodes: null,\n    installs: null,\n  },\n  stuck: {\n    kind: 'hand-written',\n    note: 'the onboarding-tip example from the documentation; no log behind it',\n    episodes: null,\n    installs: null,\n  },\n  churn: {\n    kind: 'hand-written',\n    note: 'the churn-save example from the documentation; no log behind it',\n    episodes: null,\n    installs: null,\n  },\n};\n"]}
+{"version":3,"sources":["../src/units.ts","../src/presets.ts"],"names":[],"mappings":"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","file":"presets.js","sourcesContent":["/** The units of {@link ms}: each takes a count and returns milliseconds. */\nexport interface Units {\n  /** `n` seconds in milliseconds: `n × 1000`. */\n  readonly seconds: (n: number) => number;\n  /** `n` minutes in milliseconds: `n × 60 000`. */\n  readonly minutes: (n: number) => number;\n  /** `n` hours in milliseconds: `n × 3 600 000`. */\n  readonly hours: (n: number) => number;\n  /** `n` days in milliseconds: `n × 86 400 000`. */\n  readonly days: (n: number) => number;\n  /** `n` weeks in milliseconds: `n × 604 800 000`. */\n  readonly weeks: (n: number) => number;\n}\n\n/**\n * Durations in milliseconds, the unit of `Date.now()`: `ms.days(7)` is `604800000`. Plain\n * multiplications and nothing else, for `halfLife`, `cooldown`, `episodeTimeout` and\n * `learning.halfLife` when your timestamps are in milliseconds. If your `at` is in another unit,\n * write durations in that unit instead: the engine only needs the two to agree.\n *\n * @example\n * ```ts\n * const config = {\n *   episodeTimeout: ms.minutes(30),\n *   intents: {\n *     upgrade: {\n *       prior: 0.05,\n *       priorStrength: 10,\n *       halfLife: ms.days(7),\n *       signals: { 'pricing.viewed': 3 },\n *       reveal: { cooldown: ms.weeks(2) },\n *     },\n *   },\n * };\n * ```\n */\nexport const ms: Units = {\n  seconds: (n) => n * 1_000,\n  minutes: (n) => n * 60_000,\n  hours: (n) => n * 3_600_000,\n  days: (n) => n * 86_400_000,\n  weeks: (n) => n * 604_800_000,\n};\n","import type { IntentConfig, PresetName, PresetSource } from './types';\nimport { ms } from './units';\n\nexport type { PresetName, PresetSource } from './types';\n\n/**\n * A visitor about to buy. Tuned on a public e-commerce clickstream of 2.7 million events (see the\n * case study in the guide): one shop, one summer (May to September 2015), 181,080 sessions from\n * 93,537 visitors, 8,628 of them ending with an order, a session conversion of 4.8%; scored on as\n * many visitors the fit never saw. A measured starting point, not a universal number: a shop that\n * converts 1% or 20% of its sessions has a different prior and most likely a different weight.\n * Start here, run in shadow mode, and let `tune` replace these with your own numbers.\n *\n * - `prior` 0.048: the share of sessions that end with an order (fitted 0.0477).\n * - `priorStrength` 4: visitors differ a lot in how often they buy, so one visitor's own history\n *   should outweigh the population after a handful of sessions.\n * - `halfLife` one hour: the best point of the grid; buying intent within a visit is a matter of\n *   minutes, and tomorrow's visit starts over.\n * - `cart.added` 2.3: its measured lift (fitted 2.32). 58% of sessions with a cart add end with an\n *   order, against 0.8% of those without. There is no weight for viewing a product: on that data a\n *   view is in 99% of sessions and says nothing about buying. Add one only if your data disagrees.\n * - `cooldown` one day: after an order, or after acting on the intent, stay quiet for a day; the\n *   half-life would otherwise make the default cooldown an hour.\n *\n * Rename `cart.added` and `checkout.completed` to your events by spreading.\n */\nconst willBuy: IntentConfig = {\n  prior: 0.048,\n  priorStrength: 4,\n  halfLife: ms.hours(1),\n  signals: { 'cart.added': 2.3 },\n  outcome: 'checkout.completed',\n  reveal: { cooldown: ms.days(1) },\n};\n\n/**\n * A user about to upgrade: the quickstart config, hand-written. Interest in a paid plan builds over\n * days, so the half-life is a week; the prior is a guess at the share of users who upgrade in a\n * week; `priorStrength` 10 means about six full-weight signals across sessions open the default\n * gate; the weights rank the signals by how directly they point at paying. Nobody has measured\n * these against a log.\n */\nconst upgrade: IntentConfig = {\n  prior: 0.05,\n  priorStrength: 10,\n  halfLife: ms.days(7),\n  signals: { 'pricing.viewed': 3, 'limit.hit': 2, 'export.clicked': 1 },\n  outcome: 'upgrade.completed',\n};\n\n/**\n * A user stuck on a task, hand-written. Being stuck is a state of the current session, so the\n * half-life is ten minutes and the cooldown an hour; `saturate: false` because here repetition is\n * the evidence (the fifth undo in a row says more than the first); `task.completed` is strong\n * evidence against; the gate is raised to 0.6 because an unwanted tip is an interruption. Nobody\n * has measured these against a log.\n */\nconst stuck: IntentConfig = {\n  prior: 0.1,\n  priorStrength: 5,\n  halfLife: ms.minutes(10),\n  signals: { 'editor.undo': 1, 'search.empty': 2, 'help.opened': 3, 'task.completed': -4 },\n  outcome: 'help.article.read',\n  saturate: false,\n  reveal: { threshold: 0.6, cooldown: ms.hours(1) },\n};\n\n/**\n * A user about to leave, hand-written. Churn builds over weeks, so the half-life is two weeks and\n * the prior strength 20: it should take a lot to call someone a churn risk. Exporting all their\n * data is the strongest signal; using a new feature counts against. `z` 1.64 asks for a one-sided\n * 95% bound before a save offer, because a discount has a real cost. Nobody has measured these\n * against a log.\n */\nconst churn: IntentConfig = {\n  prior: 0.08,\n  priorStrength: 20,\n  halfLife: ms.days(14),\n  signals: {\n    'session.short': 1,\n    'notifications.disabled': 3,\n    'export.all': 4,\n    'feature.new.used': -2,\n  },\n  outcome: 'account.cancelled',\n  reveal: { threshold: 0.5, z: 1.64 },\n};\n\n/**\n * Starting points for four common intents, as plain config objects. Spread one into your config,\n * rename its events to yours, override what you know better; see {@link presetSources} for where\n * each preset's numbers come from.\n *\n * @example\n * ```ts\n * import { presets } from 'oracular/presets';\n *\n * const config = {\n *   episodeTimeout: 30 * 60 * 1000,\n *   intents: {\n *     buy: { ...presets.willBuy, outcome: 'order.placed' },\n *   },\n * };\n * ```\n */\n/** Frozen through and through: a preset is shared, so a change by one caller would reach every other. */\nfunction freeze<T>(value: T): T {\n  if (typeof value === 'object' && value !== null) {\n    for (const inner of Object.values(value)) freeze(inner);\n    Object.freeze(value);\n  }\n  return value;\n}\n\nexport const presets: Readonly<Record<PresetName, IntentConfig>> = freeze({\n  willBuy,\n  upgrade,\n  stuck,\n  churn,\n});\n\n/**\n * Where each preset's numbers come from. Read it before trusting a preset: a tuned one carries its\n * sample size, a hand-written one carries nothing but reasoning.\n *\n * @example\n * ```ts\n * import { presetSources } from 'oracular/presets';\n * presetSources.willBuy.kind; // 'tuned'\n * ```\n */\nexport const presetSources: Readonly<Record<PresetName, PresetSource>> = freeze({\n  willBuy: {\n    kind: 'tuned',\n    note: 'oracular tune on a public e-commerce clickstream: one shop, May to September 2015, 2.7 million events, 4.8% of sessions ending with an order; fitted October 2026, the fitted 0.0477 and 2.32 rounded',\n    episodes: 181_080,\n    installs: 93_537,\n  },\n  upgrade: {\n    kind: 'hand-written',\n    note: 'the quickstart config from the documentation; no log behind it',\n    episodes: null,\n    installs: null,\n  },\n  stuck: {\n    kind: 'hand-written',\n    note: 'the onboarding-tip example from the documentation; no log behind it',\n    episodes: null,\n    installs: null,\n  },\n  churn: {\n    kind: 'hand-written',\n    note: 'the churn-save example from the documentation; no log behind it',\n    episodes: null,\n    installs: null,\n  },\n});\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oracular",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "On-device intent engine. Your app learns when the user is ready. Nothing leaves the device.",
   "keywords": [
     "oracular",
@@ -89,8 +89,12 @@
   },
   "workspaces": [
     ".",
-    "packages/*"
+    "packages/*",
+    "examples/react-vite"
   ],
+  "overrides": {
+    "@types/react": "^19.3.0"
+  },
   "scripts": {
     "build": "tsup && tsup --config tsup.presets.config.ts && tsup --config tsup.inspect.config.ts",
     "test": "vitest run",
@@ -102,12 +106,13 @@
     "size": "size-limit",
     "pack:check": "node scripts/pack-check.mjs",
     "check:core": "npm run lint && npm run typecheck && npm test && npm run build && npm run smoke && npm run size && npm run pack:check",
-    "check": "npm run check:core",
+    "check": "npm run check:core && npm run check -w packages/react && npm run build -w examples/react-vite",
     "prepublishOnly": "npm run check:core",
     "docs:api": "typedoc",
     "docs:dev": "npm run docs:api && vitepress dev docs",
     "docs:build": "npm run docs:api && vitepress build docs",
     "docs:preview": "vitepress preview docs",
+    "docs:gif": "node scripts/record-inspector.mjs",
     "changeset": "changeset",
     "release:version": "changeset version && npm install --package-lock-only --ignore-scripts",
     "release": "node scripts/release.mjs"
@@ -120,6 +125,8 @@
     "@size-limit/preset-small-lib": "^12.1.0",
     "@types/node": "^22.20.5",
     "fast-check": "^4.10.2",
+    "gifenc": "1.0.3",
+    "playwright-core": "1.64.1",
     "publint": "^0.3.25",
     "size-limit": "^12.1.0",
     "tsup": "^8.5.1",

package/schema/config.schema.json

@@ -107,13 +107,14 @@
       "properties": {
         "threshold": {
           "type": "number",
-          "minimum": 0,
-          "maximum": 1,
-          "description": "Probability the intent must reach. Default 0.5."
+          "exclusiveMinimum": 0,
+          "exclusiveMaximum": 1,
+          "description": "Probability the intent must reach, strictly between 0 and 1. Default 0.5."
         },
         "z": {
           "type": "number",
           "minimum": 0,
+          "maximum": 10,
           "description": "How many standard deviations below p must still clear the threshold. Default 1.28."
         },
         "cooldown": {
@@ -138,11 +139,24 @@
         },
         "gain": {
           "$ref": "#/$defs/bounded",
-          "description": "A perfectly predictive signal converges to gain × |initial weight|. Default 2."
+          "description": "Caps learned magnitude at gain × |initial weight| for every lift option. Default 2."
         },
         "priorEpisodes": {
           "$ref": "#/$defs/bounded",
           "description": "Pseudo-count behind the developer's initial weight: how many observed episodes it takes to weigh as much as the prior. Default 10."
+        },
+        "lift": {
+          "type": "string",
+          "enum": [
+            "absolute-difference",
+            "relative-lift",
+            "risk-ratio",
+            "log-lift",
+            "odds-ratio",
+            "normalized-difference",
+            "association-rule"
+          ],
+          "description": "Association measure, converted to an evidence score in [-1, 1], neutral at zero. Ratios use (R - 1)/(R + 1), relative/log lift use x/(1 + abs(x)), and absolute/normalized differences keep their scale. Default normalized-difference preserves existing behavior. Association-rule compares with the overall outcome rate."
         }
       }
     }