oracular 0.6.0 → 0.7.0

package/dist/presets.d.cts

@@ -0,0 +1,129 @@
+/**
+ * Options that decide when `shouldReveal` fires and how long cooldowns last. Resolved per call →
+ * intent → engine → defaults.
+ *
+ * @example
+ * ```ts
+ * shouldReveal(state, 'upgrade', Date.now(), { threshold: 0.7, z: 1.64 });
+ * ```
+ */
+interface RevealOptions {
+    /** Probability the intent must reach, in [0, 1]. Default 0.5. */
+    threshold?: number;
+    /** How many standard deviations below p must still clear the threshold. Default 1.28 (one-sided 90%). */
+    z?: number;
+    /** How long after `markRevealed` the intent stays revealed and `shouldReveal` is false. Default: the intent's `halfLife`. */
+    cooldown?: number;
+}
+/**
+ * One thing the user might be about to do, tracked as a Beta(α, β) distribution with
+ * α₀ = prior × priorStrength and β₀ = (1 − prior) × priorStrength.
+ *
+ * @example
+ * ```ts
+ * const churn: IntentConfig = {
+ *   prior: 0.08,
+ *   priorStrength: 20,
+ *   halfLife: 14 * 24 * 60 * 60 * 1000,
+ *   signals: { 'session.short': 1, 'notifications.disabled': 3, 'feature.new.used': -2 },
+ *   outcome: 'account.cancelled',
+ *   reveal: { threshold: 0.5, z: 1.64 },
+ * };
+ * ```
+ */
+interface IntentConfig {
+    /** Prior probability, strictly between 0 and 1. */
+    prior: number;
+    /** Strength of the prior as a pseudo-count, greater than 0 and at most 1e6. */
+    priorStrength: number;
+    /** Half-life of evidence, in the same unit as `at`. Evidence decays back toward the prior. */
+    halfLife: number;
+    /** Event name → initial weight. Positive is evidence for the intent, negative against. Non-zero, between −1e6 and 1e6. */
+    signals: Record<string, number>;
+    /** Event name that confirms the intent happened, e.g. `'checkout.completed'`. */
+    outcome?: string;
+    /** Reset α, β and contributions to the prior when the outcome arrives. Default true. */
+    resetOnOutcome?: boolean;
+    /**
+     * Repeats of a signal within one episode add less: the n-th occurrence adds
+     * `w × log2(1 + 1/n)`, so ten occurrences add 3.46 weights, not ten. The count restarts when
+     * the episode ends or this intent's outcome arrives. Default: true when `episodeTimeout` is
+     * set, false otherwise, because without an idle timeout episodes end only when the app calls
+     * `endEpisode`, and if it never does the count would never restart. Set true to saturate
+     * anyway (your app ends every episode itself), or false for intents where the repetition
+     * itself is the evidence (a user stuck on the same step), so every occurrence adds its full
+     * weight.
+     */
+    saturate?: 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
+     * counted. When the outcome arrives inside the window, each held episode gets a share
+     * `2^(−age / halfLife)` of a hit and the rest of a miss, with `age` measured from the episode's
+     * close: the sessions that built up to the outcome are credited by how much of their evidence
+     * still stands. When the window passes, the episode is a miss, recorded at the moment the window
+     * ended. Unset: an episode that ends without the outcome is a miss at once. A natural first value
+     * is the intent's `halfLife`, where the smallest share inside the window is one half.
+     */
+    attribution?: number;
+    /** Reveal defaults for this intent. */
+    reveal?: RevealOptions;
+}
+/**
+ * The intents `oracular/presets` ships. Each is a plain {@link IntentConfig} to spread into your
+ * config and override; `presetSources` there says where its numbers come from.
+ */
+type PresetName = 'willBuy' | 'upgrade' | 'stuck' | 'churn';
+/**
+ * Where a preset's numbers come from, as `presetSources` in `oracular/presets` reports it. A tuned
+ * preset was fitted by `oracular tune` on a real log and carries the sample behind it; a
+ * hand-written one is a careful guess nobody has measured. Either is a starting point: run in
+ * shadow mode and let `tune` replace it with your own numbers.
+ *
+ * @example
+ * ```ts
+ * import { presetSources } from 'oracular/presets';
+ * presetSources.willBuy.kind; // 'tuned'
+ * ```
+ */
+interface PresetSource {
+    kind: 'tuned' | 'hand-written';
+    /** What the numbers were fitted on, or where the guess comes from. */
+    note: string;
+    /** Counted episodes behind a tuned preset; null for a hand-written one. */
+    episodes: number | null;
+    /** Installs those episodes came from; null for a hand-written one. */
+    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
+ * sample size, a hand-written one carries nothing but reasoning.
+ *
+ * @example
+ * ```ts
+ * import { presetSources } from 'oracular/presets';
+ * presetSources.willBuy.kind; // 'tuned'
+ * ```
+ */
+declare const presetSources: Readonly<Record<PresetName, PresetSource>>;
+
+export { type PresetName, type PresetSource, presetSources, presets };

package/dist/presets.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Options that decide when `shouldReveal` fires and how long cooldowns last. Resolved per call →
+ * intent → engine → defaults.
+ *
+ * @example
+ * ```ts
+ * shouldReveal(state, 'upgrade', Date.now(), { threshold: 0.7, z: 1.64 });
+ * ```
+ */
+interface RevealOptions {
+    /** Probability the intent must reach, in [0, 1]. Default 0.5. */
+    threshold?: number;
+    /** How many standard deviations below p must still clear the threshold. Default 1.28 (one-sided 90%). */
+    z?: number;
+    /** How long after `markRevealed` the intent stays revealed and `shouldReveal` is false. Default: the intent's `halfLife`. */
+    cooldown?: number;
+}
+/**
+ * One thing the user might be about to do, tracked as a Beta(α, β) distribution with
+ * α₀ = prior × priorStrength and β₀ = (1 − prior) × priorStrength.
+ *
+ * @example
+ * ```ts
+ * const churn: IntentConfig = {
+ *   prior: 0.08,
+ *   priorStrength: 20,
+ *   halfLife: 14 * 24 * 60 * 60 * 1000,
+ *   signals: { 'session.short': 1, 'notifications.disabled': 3, 'feature.new.used': -2 },
+ *   outcome: 'account.cancelled',
+ *   reveal: { threshold: 0.5, z: 1.64 },
+ * };
+ * ```
+ */
+interface IntentConfig {
+    /** Prior probability, strictly between 0 and 1. */
+    prior: number;
+    /** Strength of the prior as a pseudo-count, greater than 0 and at most 1e6. */
+    priorStrength: number;
+    /** Half-life of evidence, in the same unit as `at`. Evidence decays back toward the prior. */
+    halfLife: number;
+    /** Event name → initial weight. Positive is evidence for the intent, negative against. Non-zero, between −1e6 and 1e6. */
+    signals: Record<string, number>;
+    /** Event name that confirms the intent happened, e.g. `'checkout.completed'`. */
+    outcome?: string;
+    /** Reset α, β and contributions to the prior when the outcome arrives. Default true. */
+    resetOnOutcome?: boolean;
+    /**
+     * Repeats of a signal within one episode add less: the n-th occurrence adds
+     * `w × log2(1 + 1/n)`, so ten occurrences add 3.46 weights, not ten. The count restarts when
+     * the episode ends or this intent's outcome arrives. Default: true when `episodeTimeout` is
+     * set, false otherwise, because without an idle timeout episodes end only when the app calls
+     * `endEpisode`, and if it never does the count would never restart. Set true to saturate
+     * anyway (your app ends every episode itself), or false for intents where the repetition
+     * itself is the evidence (a user stuck on the same step), so every occurrence adds its full
+     * weight.
+     */
+    saturate?: 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
+     * counted. When the outcome arrives inside the window, each held episode gets a share
+     * `2^(−age / halfLife)` of a hit and the rest of a miss, with `age` measured from the episode's
+     * close: the sessions that built up to the outcome are credited by how much of their evidence
+     * still stands. When the window passes, the episode is a miss, recorded at the moment the window
+     * ended. Unset: an episode that ends without the outcome is a miss at once. A natural first value
+     * is the intent's `halfLife`, where the smallest share inside the window is one half.
+     */
+    attribution?: number;
+    /** Reveal defaults for this intent. */
+    reveal?: RevealOptions;
+}
+/**
+ * The intents `oracular/presets` ships. Each is a plain {@link IntentConfig} to spread into your
+ * config and override; `presetSources` there says where its numbers come from.
+ */
+type PresetName = 'willBuy' | 'upgrade' | 'stuck' | 'churn';
+/**
+ * Where a preset's numbers come from, as `presetSources` in `oracular/presets` reports it. A tuned
+ * preset was fitted by `oracular tune` on a real log and carries the sample behind it; a
+ * hand-written one is a careful guess nobody has measured. Either is a starting point: run in
+ * shadow mode and let `tune` replace it with your own numbers.
+ *
+ * @example
+ * ```ts
+ * import { presetSources } from 'oracular/presets';
+ * presetSources.willBuy.kind; // 'tuned'
+ * ```
+ */
+interface PresetSource {
+    kind: 'tuned' | 'hand-written';
+    /** What the numbers were fitted on, or where the guess comes from. */
+    note: string;
+    /** Counted episodes behind a tuned preset; null for a hand-written one. */
+    episodes: number | null;
+    /** Installs those episodes came from; null for a hand-written one. */
+    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
+ * sample size, a hand-written one carries nothing but reasoning.
+ *
+ * @example
+ * ```ts
+ * import { presetSources } from 'oracular/presets';
+ * presetSources.willBuy.kind; // 'tuned'
+ * ```
+ */
+declare const presetSources: Readonly<Record<PresetName, PresetSource>>;
+
+export { type PresetName, type PresetSource, presetSources, presets };

package/dist/presets.js

@@ -0,0 +1,83 @@
+// src/units.ts
+var ms = {
+  seconds: (n) => n * 1e3,
+  minutes: (n) => n * 6e4,
+  hours: (n) => n * 36e5,
+  days: (n) => n * 864e5,
+  weeks: (n) => n * 6048e5
+};
+
+// src/presets.ts
+var willBuy = {
+  prior: 0.048,
+  priorStrength: 4,
+  halfLife: ms.hours(1),
+  signals: { "cart.added": 2.3 },
+  outcome: "checkout.completed",
+  reveal: { cooldown: ms.days(1) }
+};
+var upgrade = {
+  prior: 0.05,
+  priorStrength: 10,
+  halfLife: ms.days(7),
+  signals: { "pricing.viewed": 3, "limit.hit": 2, "export.clicked": 1 },
+  outcome: "upgrade.completed"
+};
+var stuck = {
+  prior: 0.1,
+  priorStrength: 5,
+  halfLife: ms.minutes(10),
+  signals: { "editor.undo": 1, "search.empty": 2, "help.opened": 3, "task.completed": -4 },
+  outcome: "help.article.read",
+  saturate: false,
+  reveal: { threshold: 0.6, cooldown: ms.hours(1) }
+};
+var churn = {
+  prior: 0.08,
+  priorStrength: 20,
+  halfLife: ms.days(14),
+  signals: {
+    "session.short": 1,
+    "notifications.disabled": 3,
+    "export.all": 4,
+    "feature.new.used": -2
+  },
+  outcome: "account.cancelled",
+  reveal: { threshold: 0.5, z: 1.64 }
+};
+var presets = {
+  willBuy,
+  upgrade,
+  stuck,
+  churn
+};
+var presetSources = {
+  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",
+    episodes: 181080,
+    installs: 93537
+  },
+  upgrade: {
+    kind: "hand-written",
+    note: "the quickstart config from the documentation; no log behind it",
+    episodes: null,
+    installs: null
+  },
+  stuck: {
+    kind: "hand-written",
+    note: "the onboarding-tip example from the documentation; no log behind it",
+    episodes: null,
+    installs: null
+  },
+  churn: {
+    kind: "hand-written",
+    note: "the churn-save example from the documentation; no log behind it",
+    episodes: null,
+    installs: null
+  }
+};
+
+export { presetSources, presets };
+//# sourceMappingURL=presets.js.map
+//# sourceMappingURL=presets.js.map

package/dist/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/units.ts","../src/presets.ts"],"names":[],"mappings":";AAoCO,IAAM,EAAA,GAAY;AAAA,EACvB,OAAA,EAAS,CAAC,CAAA,KAAM,CAAA,GAAI,GAAA;AAAA,EACpB,OAAA,EAAS,CAAC,CAAA,KAAM,CAAA,GAAI,GAAA;AAAA,EACpB,KAAA,EAAO,CAAC,CAAA,KAAM,CAAA,GAAI,IAAA;AAAA,EAClB,IAAA,EAAM,CAAC,CAAA,KAAM,CAAA,GAAI,KAAA;AAAA,EACjB,KAAA,EAAO,CAAC,CAAA,KAAM,CAAA,GAAI;AACpB,CAAA;;;AChBA,IAAM,OAAA,GAAwB;AAAA,EAC5B,KAAA,EAAO,KAAA;AAAA,EACP,aAAA,EAAe,CAAA;AAAA,EACf,QAAA,EAAU,EAAA,CAAG,KAAA,CAAM,CAAC,CAAA;AAAA,EACpB,OAAA,EAAS,EAAE,YAAA,EAAc,GAAA,EAAI;AAAA,EAC7B,OAAA,EAAS,oBAAA;AAAA,EACT,QAAQ,EAAE,QAAA,EAAU,EAAA,CAAG,IAAA,CAAK,CAAC,CAAA;AAC/B,CAAA;AASA,IAAM,OAAA,GAAwB;AAAA,EAC5B,KAAA,EAAO,IAAA;AAAA,EACP,aAAA,EAAe,EAAA;AAAA,EACf,QAAA,EAAU,EAAA,CAAG,IAAA,CAAK,CAAC,CAAA;AAAA,EACnB,SAAS,EAAE,gBAAA,EAAkB,GAAG,WAAA,EAAa,CAAA,EAAG,kBAAkB,CAAA,EAAE;AAAA,EACpE,OAAA,EAAS;AACX,CAAA;AASA,IAAM,KAAA,GAAsB;AAAA,EAC1B,KAAA,EAAO,GAAA;AAAA,EACP,aAAA,EAAe,CAAA;AAAA,EACf,QAAA,EAAU,EAAA,CAAG,OAAA,CAAQ,EAAE,CAAA;AAAA,EACvB,OAAA,EAAS,EAAE,aAAA,EAAe,CAAA,EAAG,gBAAgB,CAAA,EAAG,aAAA,EAAe,CAAA,EAAG,gBAAA,EAAkB,EAAA,EAAG;AAAA,EACvF,OAAA,EAAS,mBAAA;AAAA,EACT,QAAA,EAAU,KAAA;AAAA,EACV,MAAA,EAAQ,EAAE,SAAA,EAAW,GAAA,EAAK,UAAU,EAAA,CAAG,KAAA,CAAM,CAAC,CAAA;AAChD,CAAA;AASA,IAAM,KAAA,GAAsB;AAAA,EAC1B,KAAA,EAAO,IAAA;AAAA,EACP,aAAA,EAAe,EAAA;AAAA,EACf,QAAA,EAAU,EAAA,CAAG,IAAA,CAAK,EAAE,CAAA;AAAA,EACpB,OAAA,EAAS;AAAA,IACP,eAAA,EAAiB,CAAA;AAAA,IACjB,wBAAA,EAA0B,CAAA;AAAA,IAC1B,YAAA,EAAc,CAAA;AAAA,IACd,kBAAA,EAAoB;AAAA,GACtB;AAAA,EACA,OAAA,EAAS,mBAAA;AAAA,EACT,MAAA,EAAQ,EAAE,SAAA,EAAW,GAAA,EAAK,GAAG,IAAA;AAC/B,CAAA;AAmBO,IAAM,OAAA,GAAsD;AAAA,EACjE,OAAA;AAAA,EACA,OAAA;AAAA,EACA,KAAA;AAAA,EACA;AACF;AAYO,IAAM,aAAA,GAA4D;AAAA,EACvE,OAAA,EAAS;AAAA,IACP,IAAA,EAAM,OAAA;AAAA,IACN,IAAA,EAAM,uMAAA;AAAA,IACN,QAAA,EAAU,MAAA;AAAA,IACV,QAAA,EAAU;AAAA,GACZ;AAAA,EACA,OAAA,EAAS;AAAA,IACP,IAAA,EAAM,cAAA;AAAA,IACN,IAAA,EAAM,gEAAA;AAAA,IACN,QAAA,EAAU,IAAA;AAAA,IACV,QAAA,EAAU;AAAA,GACZ;AAAA,EACA,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,cAAA;AAAA,IACN,IAAA,EAAM,qEAAA;AAAA,IACN,QAAA,EAAU,IAAA;AAAA,IACV,QAAA,EAAU;AAAA,GACZ;AAAA,EACA,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,cAAA;AAAA,IACN,IAAA,EAAM,iEAAA;AAAA,IACN,QAAA,EAAU,IAAA;AAAA,IACV,QAAA,EAAU;AAAA;AAEd","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"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oracular",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "On-device intent engine. Your app learns when the user is ready. Nothing leaves the device.",
   "keywords": [
     "oracular",
@@ -42,9 +42,41 @@
       },
       "default": "./dist/index.cjs"
     },
+    "./presets": {
+      "import": {
+        "types": "./dist/presets.d.ts",
+        "default": "./dist/presets.js"
+      },
+      "require": {
+        "types": "./dist/presets.d.cts",
+        "default": "./dist/presets.cjs"
+      },
+      "default": "./dist/presets.cjs"
+    },
+    "./inspect": {
+      "import": {
+        "types": "./dist/inspect.d.ts",
+        "default": "./dist/inspect.js"
+      },
+      "require": {
+        "types": "./dist/inspect.d.cts",
+        "default": "./dist/inspect.cjs"
+      },
+      "default": "./dist/inspect.cjs"
+    },
     "./config.schema.json": "./schema/config.schema.json",
     "./package.json": "./package.json"
   },
+  "typesVersions": {
+    "*": {
+      "presets": [
+        "./dist/presets.d.ts"
+      ],
+      "inspect": [
+        "./dist/inspect.d.ts"
+      ]
+    }
+  },
   "files": [
     "dist",
     "schema",