oracular 0.0.1 → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,476 @@
+/**
+ * Version of the serialized state shape, stored in every state as `state.version`.
+ * {@link deserialize} compares it with the stored value and calls your `migrate` function when
+ * they differ. Bumped only when `EngineState` changes incompatibly.
+ *
+ * @example
+ * ```ts
+ * import { STATE_VERSION, deserialize } from 'oracular';
+ *
+ * const state = deserialize(saved, {
+ *   migrate: (stored, version) => {
+ *     if (version === 0) return upgradeFromV0(stored);
+ *     throw new Error(`cannot migrate version ${version} to ${STATE_VERSION}`);
+ *   },
+ * });
+ * ```
+ */
+declare const STATE_VERSION: 1;
+
+/**
+ * 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;
+}
+/**
+ * How the engine learns from the user's own outcomes.
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   intents,
+ *   learning: { priorEpisodes: 5, gain: 1.5, halfLife: 90 * 24 * 60 * 60 * 1000 },
+ * };
+ * ```
+ */
+interface LearningConfig {
+    /** Half-life of learned hit/miss counts, in the same unit as `at`. Omit for no forgetting. */
+    halfLife?: number;
+    /** A perfectly predictive signal converges to `gain × |initial weight|`. Default 2. */
+    gain?: number;
+    /** Pseudo-count behind the developer's initial weight: how many observed episodes it takes to weigh as much as the prior. Default 10. */
+    priorEpisodes?: 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. */
+    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. */
+    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;
+    /** Reveal defaults for this intent. */
+    reveal?: RevealOptions;
+}
+/**
+ * Everything `createState` needs. A normalized copy is stored in the state; pass the current
+ * config to `deserialize` on load.
+ *
+ * @example
+ * ```ts
+ * const config: EngineConfig = {
+ *   episodeTimeout: 30 * 60 * 1000,
+ *   intents: { upgrade, churn },
+ *   reveal: { z: 1.28 },
+ * };
+ * ```
+ */
+interface EngineConfig {
+    intents: Record<string, IntentConfig>;
+    /** Idle gap after which the current episode ends on its own, in the same unit as `at`. Omit to end episodes only via `endEpisode`. */
+    episodeTimeout?: number;
+    learning?: LearningConfig;
+    /** Reveal defaults for every intent. */
+    reveal?: RevealOptions;
+}
+/** Pseudo-counts a single signal has added to an intent: `alpha` for, `beta` against. Decays with the intent. */
+interface SignalContribution {
+    alpha: number;
+    beta: number;
+}
+/** What this user's history says about one signal. Decays with `learning.halfLife`. */
+interface SignalRecord {
+    /** Episodes in which the signal was followed by the outcome. */
+    hits: number;
+    /** Episodes in which it was not. */
+    misses: number;
+}
+/**
+ * Everything the engine knows about one intent for this user. Plain data; read it for debugging
+ * or dashboards, but change it only through the engine's functions.
+ */
+interface IntentState {
+    /** Beta α. Always equals prior α plus the sum of `contributions[*].alpha`. */
+    alpha: number;
+    /** Beta β. Always equals prior β plus the sum of `contributions[*].beta`. */
+    beta: number;
+    /** Time α, β and contributions were last decayed to. */
+    updatedAt: number | null;
+    contributions: Record<string, SignalContribution>;
+    learned: Record<string, SignalRecord>;
+    /** Episodes that ended with (`hits`) or without (`misses`) the outcome: the base rate. */
+    episodes: SignalRecord;
+    /** Time `learned` and `episodes` were last decayed to. */
+    learnedAt: number | null;
+    lastRevealedAt: number | null;
+    /** Time the intent's outcome event last arrived. `shouldReveal` stays false for the cooldown after it. */
+    lastOutcomeAt: number | null;
+    revealCount: number;
+}
+/** What one intent has seen in the current episode. */
+interface EpisodeIntentRecord {
+    /** Signals seen since the episode started (or since this intent's last outcome). */
+    seen: string[];
+    /** Whether the outcome arrived in this episode. */
+    resolved: boolean;
+}
+/** The current episode (session). One episode is open at a time, shared by all intents. */
+interface EpisodeState {
+    startedAt: number | null;
+    lastEventAt: number | null;
+    intents: Record<string, EpisodeIntentRecord>;
+}
+/**
+ * The whole engine state: plain JSON with no functions, class instances or hidden fields.
+ * Persist it with `serialize`, restore it with `deserialize`.
+ *
+ * @example
+ * ```ts
+ * const state = createState(config);
+ * state.intents.upgrade.alpha; // 0.5 for prior 0.05 × priorStrength 10
+ * JSON.stringify(state) === serialize(state); // true
+ * ```
+ */
+interface EngineState {
+    version: typeof STATE_VERSION;
+    /** Snapshot of the config this state was built with. Pass your current config to `deserialize` on load. */
+    config: EngineConfig;
+    intents: Record<string, IntentState>;
+    episode: EpisodeState;
+}
+/**
+ * What the app feeds to `observe`. Any event name is accepted; only names that appear in some
+ * intent's `signals` or as its `outcome` change evidence, every event extends the episode.
+ *
+ * @example
+ * ```ts
+ * observe(state, { name: 'pricing.viewed', at: Date.now(), props: { plan: 'pro' } });
+ * ```
+ */
+interface IntentEvent {
+    name: string;
+    /** Timestamp. Every duration in the config uses the same unit (milliseconds recommended). */
+    at: number;
+    /** Accepted and ignored in 0.1; never stored. */
+    props?: Record<string, unknown>;
+}
+/**
+ * What `predict` returns for one intent at one moment.
+ *
+ * @example
+ * ```ts
+ * const { p, lower, confidence, revealed, suppressedUntil } = predict(state, 'upgrade', now);
+ * ```
+ */
+interface Prediction {
+    intent: string;
+    /** Mean of the Beta distribution: α / (α + β). */
+    p: number;
+    /** Standard deviation of the Beta distribution. */
+    sd: number;
+    /** p − z·sd, clamped to [0, 1]. This is what `shouldReveal` compares to the threshold. */
+    lower: number;
+    /** 1 − 2·sd, clamped to [0, 1]. A heuristic: 1 when the estimate is sharp, 0 when it is as vague as possible. */
+    confidence: number;
+    /** α + β: total pseudo-observations, prior strength included. */
+    evidence: number;
+    /** True while inside the cooldown that follows `markRevealed`. */
+    revealed: boolean;
+    revealedAt: number | null;
+    /**
+     * When the current suppression ends: the later of the reveal cooldown (after `markRevealed`)
+     * and the outcome cooldown (after the outcome event) still running at `at`, or null when
+     * neither is. `shouldReveal` is false while this is non-null.
+     */
+    suppressedUntil: number | null;
+}
+/**
+ * One row of `explain`: what a single signal is doing to an intent right now, and what has been
+ * learned about it.
+ *
+ * @example
+ * ```ts
+ * const [strongest] = explain(state, 'upgrade', now);
+ * strongest?.signal; // the signal with the largest |impact|
+ * ```
+ */
+interface SignalExplanation {
+    signal: string;
+    /** Signed pseudo-counts this signal currently holds: positive in α, negative in β, after decay. */
+    contribution: number;
+    /** p minus what p would be without this signal's contribution. */
+    impact: number;
+    /** The developer's weight. */
+    initialWeight: number;
+    /** What this user's history alone says the weight should be. */
+    learnedWeight: number;
+    /** The blend the next occurrence of the signal will actually add. */
+    effectiveWeight: number;
+    hits: number;
+    misses: number;
+}
+/**
+ * Turns a stored state of an older version into a current `EngineState`. Receives the parsed
+ * JSON as-is and the version it declares.
+ *
+ * @example
+ * ```ts
+ * const migrate: Migrate = (stored, version) => {
+ *   if (version === 0) return { ...(stored as object), version: 1 } as EngineState;
+ *   throw new Error(`unknown state version ${version}`);
+ * };
+ * ```
+ */
+type Migrate = (stored: unknown, version: number) => EngineState;
+/**
+ * Options for `deserialize`.
+ *
+ * @example
+ * ```ts
+ * deserialize(saved, { config: currentConfig, migrate });
+ * ```
+ */
+interface DeserializeOptions {
+    /** The app's current config. Validated, swapped in, and used to prune signals and intents no longer declared. */
+    config?: EngineConfig;
+    /** Called when the stored version differs from `STATE_VERSION`. */
+    migrate?: Migrate;
+}
+
+/**
+ * Why the intent's p is what it is at time `at`: one entry per declared signal, the ones that
+ * matter most first. `contribution` is the signed pseudo-count the signal currently holds after
+ * decay, `impact` is how much p would change if that contribution were removed, and the three
+ * weights show what the developer said, what this user's history says, and what the next
+ * occurrence will actually add. Read-only.
+ *
+ * @param state - The current state. Not mutated.
+ * @param intent - Name of an intent declared in the config.
+ * @param at - The time to evaluate at; contributions and learned counts are decayed to it.
+ * @returns One {@link SignalExplanation} per declared signal, sorted by |impact| descending,
+ *   then by name. Empty for an intent that declares no signals.
+ * @throws `RangeError` when `intent` is not declared in the config.
+ * @throws `TypeError` when `state` is not an engine state or `at` is not finite.
+ * @example
+ * ```ts
+ * for (const row of explain(state, 'upgrade', Date.now())) {
+ *   console.log(row.signal, row.impact.toFixed(2), row.effectiveWeight.toFixed(2));
+ * }
+ * ```
+ */
+declare function explain(state: EngineState, intent: string, at: number): SignalExplanation[];
+
+/**
+ * Feeds one event to the engine.
+ *
+ * For every intent the event is a signal of: decay its evidence to `event.at`, then add the
+ * signal's effective weight to α (positive) or β (negative) and remember the signal for this
+ * episode. For every intent the event is the outcome of: give the remembered signals a hit,
+ * count the episode toward the base rate, record `lastOutcomeAt`, and (by default) reset the
+ * evidence to the prior. Any event opens or extends the current episode; an idle gap longer
+ * than `config.episodeTimeout` closes the previous episode first.
+ *
+ * @param state - The current state. Not mutated.
+ * @param event - `name` is matched against every intent's signals and outcome; `at` is the
+ *   event's timestamp, in the same unit as your durations; `props` are accepted and ignored,
+ *   and never stored.
+ * @returns The next state. Intents the event does not touch keep their stored numbers; their
+ *   decay is applied when they are next read or updated.
+ * @throws `TypeError` when `state` is not an engine state, or the event has no non-empty
+ *   `name`, no finite `at`, or a `props` that is not a plain object.
+ * @example
+ * ```ts
+ * let state = createState(config);
+ * state = observe(state, { name: 'pricing.viewed', at: Date.now() });
+ * state = observe(state, { name: 'upgrade.completed', at: Date.now() }); // outcome
+ * ```
+ */
+declare function observe(state: EngineState, event: IntentEvent): EngineState;
+/**
+ * Ends the current episode at `at`. Every intent whose outcome did not arrive gives a miss to
+ * each signal seen this episode and counts the episode toward its base rate. Call it when a
+ * session ends: tab closed, app backgrounded, user signed out.
+ *
+ * @param state - The current state. Not mutated.
+ * @param at - When the episode ended. If it had already timed out under
+ *   `config.episodeTimeout`, it is closed at the moment it timed out instead.
+ * @returns The next state with no open episode, or the very same state object when no episode
+ *   was open.
+ * @throws `TypeError` when `state` is not an engine state or `at` is not a finite number.
+ * @example
+ * ```ts
+ * window.addEventListener('pagehide', () => {
+ *   state = endEpisode(state, Date.now());
+ *   localStorage.setItem('oracular', serialize(state));
+ * });
+ * ```
+ */
+declare function endEpisode(state: EngineState, at: number): EngineState;
+
+/**
+ * The intent's current estimate at time `at`: the Beta mean p, its standard deviation, the
+ * lower confidence bound that {@link shouldReveal} tests, and the cooldown status. Read-only:
+ * the stored state is decayed to `at` for the reading but not changed.
+ *
+ * @param state - The current state. Not mutated.
+ * @param intent - Name of an intent declared in the config.
+ * @param at - The time to evaluate at, in the same unit as your durations.
+ * @param opts - Overrides for `threshold`, `z` and `cooldown`, resolved as call → intent →
+ *   engine → defaults. `z` sets `lower`; `cooldown` sets `revealed` and `suppressedUntil`;
+ *   `threshold` only matters to {@link shouldReveal}.
+ * @returns The prediction. `p`, `sd`, `lower` and `confidence` are in [0, 1]; `evidence` is
+ *   α + β.
+ * @throws `RangeError` when `intent` is not declared in the config.
+ * @throws `TypeError` when `state` is not an engine state, `at` is not finite, or `opts` is
+ *   malformed.
+ * @example
+ * ```ts
+ * const { p, lower, suppressedUntil } = predict(state, 'upgrade', Date.now());
+ * if (suppressedUntil !== null) scheduleNextCheck(suppressedUntil);
+ * ```
+ */
+declare function predict(state: EngineState, intent: string, at: number, opts?: RevealOptions): Prediction;
+/**
+ * Whether to act on the intent now. True when p ≥ `threshold`, the lower confidence bound
+ * p − z·sd also clears `threshold`, and no cooldown is running: neither the one started by
+ * {@link markRevealed} nor the one started by the intent's outcome event.
+ *
+ * @param state - The current state. Not mutated.
+ * @param intent - Name of an intent declared in the config.
+ * @param at - The time to evaluate at.
+ * @param opts - Overrides for `threshold` (default 0.5), `z` (default 1.28, a one-sided 90%
+ *   bound) and `cooldown` (default: the intent's `halfLife`).
+ * @returns True when the app should show, offer or reveal whatever this intent gates.
+ * @throws `RangeError` when `intent` is not declared in the config.
+ * @throws `TypeError` when `state` is not an engine state, `at` is not finite, or `opts` is
+ *   malformed.
+ * @example
+ * ```ts
+ * if (shouldReveal(state, 'upgrade', Date.now())) {
+ *   showUpgradeOffer();
+ *   state = markRevealed(state, 'upgrade', Date.now());
+ * }
+ * ```
+ */
+declare function shouldReveal(state: EngineState, intent: string, at: number, opts?: RevealOptions): boolean;
+/**
+ * Records that the app acted on the intent at `at`. Starts the reveal cooldown, during which
+ * `predict().revealed` is true and {@link shouldReveal} is false, and increments
+ * `revealCount`. Evidence and learned data are untouched.
+ *
+ * @param state - The current state. Not mutated.
+ * @param intent - Name of an intent declared in the config.
+ * @param at - When the reveal happened.
+ * @returns The next state.
+ * @throws `RangeError` when `intent` is not declared in the config.
+ * @throws `TypeError` when `state` is not an engine state or `at` is not finite.
+ * @example
+ * ```ts
+ * state = markRevealed(state, 'upgrade', Date.now());
+ * predict(state, 'upgrade', Date.now()).revealed; // true until the cooldown ends
+ * ```
+ */
+declare function markRevealed(state: EngineState, intent: string, at: number): EngineState;
+
+/**
+ * The state as a JSON string, for the host app to persist wherever it likes. The state is plain
+ * data, so this is `JSON.stringify` after a shape check. The output never contains event props.
+ *
+ * @param state - The state to persist.
+ * @returns A JSON string that {@link deserialize} restores losslessly.
+ * @throws `TypeError` when `state` is not an engine state.
+ * @example
+ * ```ts
+ * localStorage.setItem('oracular', serialize(state));
+ * ```
+ */
+declare function serialize(state: EngineState): string;
+/**
+ * Restores a state saved with {@link serialize}.
+ *
+ * Always pass the app's current `config`: it is validated and replaces the stored snapshot,
+ * intents and signals no longer declared are dropped (α and β are recomputed from the kept
+ * contributions), and newly declared intents start at their prior. Pass `migrate` to upgrade a
+ * state saved by an older version of this library.
+ *
+ * @param json - A string produced by {@link serialize}.
+ * @param opts - `config`: the app's current config. `migrate`: called as
+ *   `migrate(stored, version)` when the stored version differs from {@link STATE_VERSION};
+ *   it must return a state of the current version.
+ * @returns A validated state that satisfies the engine's invariants.
+ * @throws `SyntaxError` when `json` is not valid JSON.
+ * @throws `TypeError` when the stored data, the result of `migrate`, `opts` or `opts.config`
+ *   has the wrong shape.
+ * @throws `RangeError` when the stored version differs and no `migrate` is given, when
+ *   `migrate` does not return the current version, or when a stored number is out of range.
+ * @example
+ * ```ts
+ * const saved = localStorage.getItem('oracular');
+ * let state = saved ? deserialize(saved, { config }) : createState(config);
+ * ```
+ */
+declare function deserialize(json: string, opts?: DeserializeOptions): EngineState;
+
+/**
+ * Builds a fresh engine state from a config. Every intent starts at its prior and no episode is
+ * open. The config is validated and a normalized copy is stored inside the state, so a persisted
+ * state remembers the weights it was built with; pass your current config to {@link deserialize}
+ * when loading.
+ *
+ * @param config - Intents with their priors and signals, plus engine-wide options. Validated
+ *   strictly: unknown keys, non-finite numbers and out-of-range values throw.
+ * @returns A new, JSON-serializable state. `config` is not mutated.
+ * @throws `TypeError` when a value has the wrong type or a key is not recognised.
+ * @throws `RangeError` when a number is out of range, for example a `prior` outside (0, 1) or a
+ *   signal weight of 0.
+ * @example
+ * ```ts
+ * const state = createState({
+ *   intents: {
+ *     upgrade: {
+ *       prior: 0.05,
+ *       priorStrength: 10,
+ *       halfLife: 7 * 24 * 60 * 60 * 1000,
+ *       signals: { 'pricing.viewed': 3, 'limit.hit': 2, 'plan.downgraded': -4 },
+ *       outcome: 'upgrade.completed',
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function createState(config: EngineConfig): EngineState;
+
+export { type DeserializeOptions, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type IntentConfig, type IntentEvent, type IntentState, type LearningConfig, type Migrate, type Prediction, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, createState, deserialize, endEpisode, explain, markRevealed, observe, predict, serialize, shouldReveal };