oracular 0.5.2 → 0.7.0

package/dist/inspect.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+// src/inspect.ts
+var escapeHtml = (text) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+var BOX = "font:12px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace;color:#1f2328;background:#fff;border:1px solid #d0d7de;border-radius:6px;padding:10px 12px;max-width:100%;overflow:auto";
+var TABLE = "border-collapse:collapse;margin:6px 0 10px";
+var CELL = "padding:2px 10px 2px 0;text-align:right;white-space:nowrap";
+var HEAD = `${CELL};color:#656d76;font-weight:normal;border-bottom:1px solid #d8dee4`;
+var NAME = "padding:2px 10px 2px 0;text-align:left;white-space:nowrap";
+function renderInspector(snapshot, opts = {}) {
+  const digits = opts.digits ?? 3;
+  const n = (x) => x.toFixed(digits);
+  const time = (t) => t === null ? "\u2013" : new Date(t).toISOString();
+  const title = escapeHtml(opts.title ?? "oracular");
+  const parts = [
+    `<div style="${BOX}">`,
+    `<div><strong>${title}</strong> <span style="color:#656d76">at ${time(snapshot.at)}</span></div>`
+  ];
+  for (const { intent, prediction, reveal, explanation } of snapshot.intents) {
+    const gate = reveal ? '<span style="color:#1a7f37;font-weight:bold">reveal</span>' : prediction.suppressedUntil !== null ? `<span style="color:#9a6700">suppressed until ${time(prediction.suppressedUntil)}</span>` : '<span style="color:#656d76">no reveal</span>';
+    parts.push(
+      `<div style="margin-top:8px"><strong>${escapeHtml(intent)}</strong> p ${n(prediction.p)} \xB7 lower ${n(prediction.lower)} \xB7 sd ${n(prediction.sd)} \xB7 evidence ${n(prediction.evidence)} \xB7 ${gate}</div>`
+    );
+    if (explanation.length === 0) {
+      parts.push('<div style="color:#656d76">no signals declared</div>');
+      continue;
+    }
+    parts.push(`<table style="${TABLE}"><thead><tr>`);
+    parts.push(`<th style="${HEAD};text-align:left">signal</th>`);
+    for (const h of ["holds", "impact on p", "initial", "learned", "effective", "hits / misses"]) {
+      parts.push(`<th style="${HEAD}">${h}</th>`);
+    }
+    parts.push("</tr></thead><tbody>");
+    for (const row of explanation) {
+      const dim = row.contribution === 0 ? ";color:#8c959f" : "";
+      parts.push(
+        `<tr><td style="${NAME}${dim}">${escapeHtml(row.signal)}</td>`,
+        `<td style="${CELL}${dim}">${n(row.contribution)}</td>`,
+        `<td style="${CELL}${dim}">${row.impact >= 0 ? "+" : ""}${n(row.impact)}</td>`,
+        `<td style="${CELL}${dim}">${n(row.initialWeight)}</td>`,
+        `<td style="${CELL}${dim}">${n(row.learnedWeight)}</td>`,
+        `<td style="${CELL}${dim}">${n(row.effectiveWeight)}</td>`,
+        `<td style="${CELL}${dim}">${n(row.hits)} / ${n(row.misses)}</td></tr>`
+      );
+    }
+    parts.push("</tbody></table>");
+  }
+  parts.push("</div>");
+  return parts.join("");
+}
+function mountInspector(container, read, opts = {}) {
+  const update = () => {
+    container.innerHTML = renderInspector(read(), opts);
+  };
+  update();
+  return {
+    update,
+    unmount: () => {
+      container.innerHTML = "";
+    }
+  };
+}
+
+exports.mountInspector = mountInspector;
+exports.renderInspector = renderInspector;
+//# sourceMappingURL=inspect.cjs.map
+//# sourceMappingURL=inspect.cjs.map

package/dist/inspect.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/inspect.ts"],"names":[],"mappings":"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","file":"inspect.cjs","sourcesContent":["import type { Snapshot } from './types';\n\nexport type { IntentSnapshot, Snapshot } from './types';\n\n/** Options for {@link renderInspector}. */\nexport interface RenderOptions {\n  /** Heading above the tables. Default \"oracular\". */\n  title?: string;\n  /** Decimal places for probabilities and weights. Default 3. */\n  digits?: number;\n}\n\nconst escapeHtml = (text: string): string =>\n  text.replace(/[&<>\"']/g, (c) => `&#${c.charCodeAt(0)};`);\n\nconst BOX =\n  'font:12px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace;color:#1f2328;background:#fff;border:1px solid #d0d7de;border-radius:6px;padding:10px 12px;max-width:100%;overflow:auto';\nconst TABLE = 'border-collapse:collapse;margin:6px 0 10px';\nconst CELL = 'padding:2px 10px 2px 0;text-align:right;white-space:nowrap';\nconst HEAD = `${CELL};color:#656d76;font-weight:normal;border-bottom:1px solid #d8dee4`;\nconst NAME = 'padding:2px 10px 2px 0;text-align:left;white-space:nowrap';\n\n/**\n * A snapshot as an HTML fragment: for each intent, its prediction and its gate in one line, then\n * one row per signal with the contribution it holds, its impact on p, the initial, learned and\n * effective weights, and the hit/miss record. Inline styles, no script, every string escaped, so\n * the fragment can go into any element's `innerHTML` or into a file. Pure.\n *\n * @param snapshot - From {@link inspect}.\n * @param opts - `title` and `digits`.\n * @returns An HTML string.\n * @example\n * ```ts\n * panel.innerHTML = renderInspector(inspect(state, Date.now()));\n * ```\n */\nexport function renderInspector(snapshot: Snapshot, opts: RenderOptions = {}): string {\n  const digits = opts.digits ?? 3;\n  const n = (x: number) => x.toFixed(digits);\n  const time = (t: number | null) => (t === null ? '–' : new Date(t).toISOString());\n  const title = escapeHtml(opts.title ?? 'oracular');\n  const parts: string[] = [\n    `<div style=\"${BOX}\">`,\n    `<div><strong>${title}</strong> <span style=\"color:#656d76\">at ${time(snapshot.at)}</span></div>`,\n  ];\n  for (const { intent, prediction, reveal, explanation } of snapshot.intents) {\n    const gate = reveal\n      ? '<span style=\"color:#1a7f37;font-weight:bold\">reveal</span>'\n      : prediction.suppressedUntil !== null\n        ? `<span style=\"color:#9a6700\">suppressed until ${time(prediction.suppressedUntil)}</span>`\n        : '<span style=\"color:#656d76\">no reveal</span>';\n    parts.push(\n      `<div style=\"margin-top:8px\"><strong>${escapeHtml(intent)}</strong> p ${n(prediction.p)} · lower ${n(prediction.lower)} · sd ${n(prediction.sd)} · evidence ${n(prediction.evidence)} · ${gate}</div>`,\n    );\n    if (explanation.length === 0) {\n      parts.push('<div style=\"color:#656d76\">no signals declared</div>');\n      continue;\n    }\n    parts.push(`<table style=\"${TABLE}\"><thead><tr>`);\n    parts.push(`<th style=\"${HEAD};text-align:left\">signal</th>`);\n    for (const h of ['holds', 'impact on p', 'initial', 'learned', 'effective', 'hits / misses']) {\n      parts.push(`<th style=\"${HEAD}\">${h}</th>`);\n    }\n    parts.push('</tr></thead><tbody>');\n    for (const row of explanation) {\n      const dim = row.contribution === 0 ? ';color:#8c959f' : '';\n      parts.push(\n        `<tr><td style=\"${NAME}${dim}\">${escapeHtml(row.signal)}</td>`,\n        `<td style=\"${CELL}${dim}\">${n(row.contribution)}</td>`,\n        `<td style=\"${CELL}${dim}\">${row.impact >= 0 ? '+' : ''}${n(row.impact)}</td>`,\n        `<td style=\"${CELL}${dim}\">${n(row.initialWeight)}</td>`,\n        `<td style=\"${CELL}${dim}\">${n(row.learnedWeight)}</td>`,\n        `<td style=\"${CELL}${dim}\">${n(row.effectiveWeight)}</td>`,\n        `<td style=\"${CELL}${dim}\">${n(row.hits)} / ${n(row.misses)}</td></tr>`,\n      );\n    }\n    parts.push('</tbody></table>');\n  }\n  parts.push('</div>');\n  return parts.join('');\n}\n\n/** What {@link mountInspector} returns. */\nexport interface MountedInspector {\n  /** Re-reads the snapshot and re-renders. Call it after every `observe`, or from a timer you own. */\n  update: () => void;\n  /** Empties the container. */\n  unmount: () => void;\n}\n\n/**\n * Renders a live inspector into a container and keeps it current on demand. The container is\n * anything with an `innerHTML` property, so a DOM element; the library itself touches no DOM API\n * and sets no timer. Your app decides when to refresh: after each `observe`, or on an interval.\n *\n * @param container - The element to render into. Only its `innerHTML` is written.\n * @param read - Returns the snapshot to show, typically `() => inspect(state, Date.now())`.\n * @param opts - Passed to {@link renderInspector}.\n * @returns `update` to re-render and `unmount` to clear the container. The first render happens\n *   at once.\n * @example\n * ```ts\n * const panel = mountInspector(document.querySelector('#oracular')!, () => inspect(state, Date.now()));\n * state = observe(state, event);\n * panel.update();\n * ```\n */\nexport function mountInspector(\n  container: { innerHTML: string },\n  read: () => Snapshot,\n  opts: RenderOptions = {},\n): MountedInspector {\n  const update = () => {\n    container.innerHTML = renderInspector(read(), opts);\n  };\n  update();\n  return {\n    update,\n    unmount: () => {\n      container.innerHTML = '';\n    },\n  };\n}\n"]}

package/dist/inspect.d.cts

@@ -0,0 +1,143 @@
+/**
+ * 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 of initial and learned weight: what the signal adds the first time it occurs in an
+     * episode. Repeats within the episode add less (see {@link IntentConfig.saturate}).
+     */
+    effectiveWeight: number;
+    hits: number;
+    misses: number;
+}
+/**
+ * What `evaluate` returns: the same values `predict`, `shouldReveal` and `explain` would give
+ * for the same inputs, computed from a single decay pass.
+ *
+ * @example
+ * ```ts
+ * const { prediction, reveal, explanation } = evaluate(state, 'upgrade', Date.now());
+ * ```
+ */
+interface Evaluation {
+    prediction: Prediction;
+    reveal: boolean;
+    explanation: SignalExplanation[];
+}
+/** One intent in a {@link Snapshot}: its name and what {@link evaluate} says about it. */
+interface IntentSnapshot extends Evaluation {
+    intent: string;
+}
+/**
+ * Every intent's prediction, gate and explanation at one moment, as {@link inspect} returns it:
+ * what a debug panel shows, what a test asserts on, what `console.table` prints.
+ *
+ * @example
+ * ```ts
+ * const { intents } = inspect(state, Date.now());
+ * console.table(intents.map((i) => ({ intent: i.intent, p: i.prediction.p, reveal: i.reveal })));
+ * ```
+ */
+interface Snapshot {
+    at: number;
+    /** In config order. */
+    intents: IntentSnapshot[];
+}
+
+/** Options for {@link renderInspector}. */
+interface RenderOptions {
+    /** Heading above the tables. Default "oracular". */
+    title?: string;
+    /** Decimal places for probabilities and weights. Default 3. */
+    digits?: number;
+}
+/**
+ * A snapshot as an HTML fragment: for each intent, its prediction and its gate in one line, then
+ * one row per signal with the contribution it holds, its impact on p, the initial, learned and
+ * effective weights, and the hit/miss record. Inline styles, no script, every string escaped, so
+ * the fragment can go into any element's `innerHTML` or into a file. Pure.
+ *
+ * @param snapshot - From {@link inspect}.
+ * @param opts - `title` and `digits`.
+ * @returns An HTML string.
+ * @example
+ * ```ts
+ * panel.innerHTML = renderInspector(inspect(state, Date.now()));
+ * ```
+ */
+declare function renderInspector(snapshot: Snapshot, opts?: RenderOptions): string;
+/** What {@link mountInspector} returns. */
+interface MountedInspector {
+    /** Re-reads the snapshot and re-renders. Call it after every `observe`, or from a timer you own. */
+    update: () => void;
+    /** Empties the container. */
+    unmount: () => void;
+}
+/**
+ * Renders a live inspector into a container and keeps it current on demand. The container is
+ * anything with an `innerHTML` property, so a DOM element; the library itself touches no DOM API
+ * and sets no timer. Your app decides when to refresh: after each `observe`, or on an interval.
+ *
+ * @param container - The element to render into. Only its `innerHTML` is written.
+ * @param read - Returns the snapshot to show, typically `() => inspect(state, Date.now())`.
+ * @param opts - Passed to {@link renderInspector}.
+ * @returns `update` to re-render and `unmount` to clear the container. The first render happens
+ *   at once.
+ * @example
+ * ```ts
+ * const panel = mountInspector(document.querySelector('#oracular')!, () => inspect(state, Date.now()));
+ * state = observe(state, event);
+ * panel.update();
+ * ```
+ */
+declare function mountInspector(container: {
+    innerHTML: string;
+}, read: () => Snapshot, opts?: RenderOptions): MountedInspector;
+
+export { type IntentSnapshot, type MountedInspector, type RenderOptions, type Snapshot, mountInspector, renderInspector };

package/dist/inspect.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 of initial and learned weight: what the signal adds the first time it occurs in an
+     * episode. Repeats within the episode add less (see {@link IntentConfig.saturate}).
+     */
+    effectiveWeight: number;
+    hits: number;
+    misses: number;
+}
+/**
+ * What `evaluate` returns: the same values `predict`, `shouldReveal` and `explain` would give
+ * for the same inputs, computed from a single decay pass.
+ *
+ * @example
+ * ```ts
+ * const { prediction, reveal, explanation } = evaluate(state, 'upgrade', Date.now());
+ * ```
+ */
+interface Evaluation {
+    prediction: Prediction;
+    reveal: boolean;
+    explanation: SignalExplanation[];
+}
+/** One intent in a {@link Snapshot}: its name and what {@link evaluate} says about it. */
+interface IntentSnapshot extends Evaluation {
+    intent: string;
+}
+/**
+ * Every intent's prediction, gate and explanation at one moment, as {@link inspect} returns it:
+ * what a debug panel shows, what a test asserts on, what `console.table` prints.
+ *
+ * @example
+ * ```ts
+ * const { intents } = inspect(state, Date.now());
+ * console.table(intents.map((i) => ({ intent: i.intent, p: i.prediction.p, reveal: i.reveal })));
+ * ```
+ */
+interface Snapshot {
+    at: number;
+    /** In config order. */
+    intents: IntentSnapshot[];
+}
+
+/** Options for {@link renderInspector}. */
+interface RenderOptions {
+    /** Heading above the tables. Default "oracular". */
+    title?: string;
+    /** Decimal places for probabilities and weights. Default 3. */
+    digits?: number;
+}
+/**
+ * A snapshot as an HTML fragment: for each intent, its prediction and its gate in one line, then
+ * one row per signal with the contribution it holds, its impact on p, the initial, learned and
+ * effective weights, and the hit/miss record. Inline styles, no script, every string escaped, so
+ * the fragment can go into any element's `innerHTML` or into a file. Pure.
+ *
+ * @param snapshot - From {@link inspect}.
+ * @param opts - `title` and `digits`.
+ * @returns An HTML string.
+ * @example
+ * ```ts
+ * panel.innerHTML = renderInspector(inspect(state, Date.now()));
+ * ```
+ */
+declare function renderInspector(snapshot: Snapshot, opts?: RenderOptions): string;
+/** What {@link mountInspector} returns. */
+interface MountedInspector {
+    /** Re-reads the snapshot and re-renders. Call it after every `observe`, or from a timer you own. */
+    update: () => void;
+    /** Empties the container. */
+    unmount: () => void;
+}
+/**
+ * Renders a live inspector into a container and keeps it current on demand. The container is
+ * anything with an `innerHTML` property, so a DOM element; the library itself touches no DOM API
+ * and sets no timer. Your app decides when to refresh: after each `observe`, or on an interval.
+ *
+ * @param container - The element to render into. Only its `innerHTML` is written.
+ * @param read - Returns the snapshot to show, typically `() => inspect(state, Date.now())`.
+ * @param opts - Passed to {@link renderInspector}.
+ * @returns `update` to re-render and `unmount` to clear the container. The first render happens
+ *   at once.
+ * @example
+ * ```ts
+ * const panel = mountInspector(document.querySelector('#oracular')!, () => inspect(state, Date.now()));
+ * state = observe(state, event);
+ * panel.update();
+ * ```
+ */
+declare function mountInspector(container: {
+    innerHTML: string;
+}, read: () => Snapshot, opts?: RenderOptions): MountedInspector;
+
+export { type IntentSnapshot, type MountedInspector, type RenderOptions, type Snapshot, mountInspector, renderInspector };

package/dist/inspect.js

@@ -0,0 +1,64 @@
+// src/inspect.ts
+var escapeHtml = (text) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+var BOX = "font:12px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace;color:#1f2328;background:#fff;border:1px solid #d0d7de;border-radius:6px;padding:10px 12px;max-width:100%;overflow:auto";
+var TABLE = "border-collapse:collapse;margin:6px 0 10px";
+var CELL = "padding:2px 10px 2px 0;text-align:right;white-space:nowrap";
+var HEAD = `${CELL};color:#656d76;font-weight:normal;border-bottom:1px solid #d8dee4`;
+var NAME = "padding:2px 10px 2px 0;text-align:left;white-space:nowrap";
+function renderInspector(snapshot, opts = {}) {
+  const digits = opts.digits ?? 3;
+  const n = (x) => x.toFixed(digits);
+  const time = (t) => t === null ? "\u2013" : new Date(t).toISOString();
+  const title = escapeHtml(opts.title ?? "oracular");
+  const parts = [
+    `<div style="${BOX}">`,
+    `<div><strong>${title}</strong> <span style="color:#656d76">at ${time(snapshot.at)}</span></div>`
+  ];
+  for (const { intent, prediction, reveal, explanation } of snapshot.intents) {
+    const gate = reveal ? '<span style="color:#1a7f37;font-weight:bold">reveal</span>' : prediction.suppressedUntil !== null ? `<span style="color:#9a6700">suppressed until ${time(prediction.suppressedUntil)}</span>` : '<span style="color:#656d76">no reveal</span>';
+    parts.push(
+      `<div style="margin-top:8px"><strong>${escapeHtml(intent)}</strong> p ${n(prediction.p)} \xB7 lower ${n(prediction.lower)} \xB7 sd ${n(prediction.sd)} \xB7 evidence ${n(prediction.evidence)} \xB7 ${gate}</div>`
+    );
+    if (explanation.length === 0) {
+      parts.push('<div style="color:#656d76">no signals declared</div>');
+      continue;
+    }
+    parts.push(`<table style="${TABLE}"><thead><tr>`);
+    parts.push(`<th style="${HEAD};text-align:left">signal</th>`);
+    for (const h of ["holds", "impact on p", "initial", "learned", "effective", "hits / misses"]) {
+      parts.push(`<th style="${HEAD}">${h}</th>`);
+    }
+    parts.push("</tr></thead><tbody>");
+    for (const row of explanation) {
+      const dim = row.contribution === 0 ? ";color:#8c959f" : "";
+      parts.push(
+        `<tr><td style="${NAME}${dim}">${escapeHtml(row.signal)}</td>`,
+        `<td style="${CELL}${dim}">${n(row.contribution)}</td>`,
+        `<td style="${CELL}${dim}">${row.impact >= 0 ? "+" : ""}${n(row.impact)}</td>`,
+        `<td style="${CELL}${dim}">${n(row.initialWeight)}</td>`,
+        `<td style="${CELL}${dim}">${n(row.learnedWeight)}</td>`,
+        `<td style="${CELL}${dim}">${n(row.effectiveWeight)}</td>`,
+        `<td style="${CELL}${dim}">${n(row.hits)} / ${n(row.misses)}</td></tr>`
+      );
+    }
+    parts.push("</tbody></table>");
+  }
+  parts.push("</div>");
+  return parts.join("");
+}
+function mountInspector(container, read, opts = {}) {
+  const update = () => {
+    container.innerHTML = renderInspector(read(), opts);
+  };
+  update();
+  return {
+    update,
+    unmount: () => {
+      container.innerHTML = "";
+    }
+  };
+}
+
+export { mountInspector, renderInspector };
+//# sourceMappingURL=inspect.js.map
+//# sourceMappingURL=inspect.js.map

package/dist/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/inspect.ts"],"names":[],"mappings":"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","file":"inspect.js","sourcesContent":["import type { Snapshot } from './types';\n\nexport type { IntentSnapshot, Snapshot } from './types';\n\n/** Options for {@link renderInspector}. */\nexport interface RenderOptions {\n  /** Heading above the tables. Default \"oracular\". */\n  title?: string;\n  /** Decimal places for probabilities and weights. Default 3. */\n  digits?: number;\n}\n\nconst escapeHtml = (text: string): string =>\n  text.replace(/[&<>\"']/g, (c) => `&#${c.charCodeAt(0)};`);\n\nconst BOX =\n  'font:12px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace;color:#1f2328;background:#fff;border:1px solid #d0d7de;border-radius:6px;padding:10px 12px;max-width:100%;overflow:auto';\nconst TABLE = 'border-collapse:collapse;margin:6px 0 10px';\nconst CELL = 'padding:2px 10px 2px 0;text-align:right;white-space:nowrap';\nconst HEAD = `${CELL};color:#656d76;font-weight:normal;border-bottom:1px solid #d8dee4`;\nconst NAME = 'padding:2px 10px 2px 0;text-align:left;white-space:nowrap';\n\n/**\n * A snapshot as an HTML fragment: for each intent, its prediction and its gate in one line, then\n * one row per signal with the contribution it holds, its impact on p, the initial, learned and\n * effective weights, and the hit/miss record. Inline styles, no script, every string escaped, so\n * the fragment can go into any element's `innerHTML` or into a file. Pure.\n *\n * @param snapshot - From {@link inspect}.\n * @param opts - `title` and `digits`.\n * @returns An HTML string.\n * @example\n * ```ts\n * panel.innerHTML = renderInspector(inspect(state, Date.now()));\n * ```\n */\nexport function renderInspector(snapshot: Snapshot, opts: RenderOptions = {}): string {\n  const digits = opts.digits ?? 3;\n  const n = (x: number) => x.toFixed(digits);\n  const time = (t: number | null) => (t === null ? '–' : new Date(t).toISOString());\n  const title = escapeHtml(opts.title ?? 'oracular');\n  const parts: string[] = [\n    `<div style=\"${BOX}\">`,\n    `<div><strong>${title}</strong> <span style=\"color:#656d76\">at ${time(snapshot.at)}</span></div>`,\n  ];\n  for (const { intent, prediction, reveal, explanation } of snapshot.intents) {\n    const gate = reveal\n      ? '<span style=\"color:#1a7f37;font-weight:bold\">reveal</span>'\n      : prediction.suppressedUntil !== null\n        ? `<span style=\"color:#9a6700\">suppressed until ${time(prediction.suppressedUntil)}</span>`\n        : '<span style=\"color:#656d76\">no reveal</span>';\n    parts.push(\n      `<div style=\"margin-top:8px\"><strong>${escapeHtml(intent)}</strong> p ${n(prediction.p)} · lower ${n(prediction.lower)} · sd ${n(prediction.sd)} · evidence ${n(prediction.evidence)} · ${gate}</div>`,\n    );\n    if (explanation.length === 0) {\n      parts.push('<div style=\"color:#656d76\">no signals declared</div>');\n      continue;\n    }\n    parts.push(`<table style=\"${TABLE}\"><thead><tr>`);\n    parts.push(`<th style=\"${HEAD};text-align:left\">signal</th>`);\n    for (const h of ['holds', 'impact on p', 'initial', 'learned', 'effective', 'hits / misses']) {\n      parts.push(`<th style=\"${HEAD}\">${h}</th>`);\n    }\n    parts.push('</tr></thead><tbody>');\n    for (const row of explanation) {\n      const dim = row.contribution === 0 ? ';color:#8c959f' : '';\n      parts.push(\n        `<tr><td style=\"${NAME}${dim}\">${escapeHtml(row.signal)}</td>`,\n        `<td style=\"${CELL}${dim}\">${n(row.contribution)}</td>`,\n        `<td style=\"${CELL}${dim}\">${row.impact >= 0 ? '+' : ''}${n(row.impact)}</td>`,\n        `<td style=\"${CELL}${dim}\">${n(row.initialWeight)}</td>`,\n        `<td style=\"${CELL}${dim}\">${n(row.learnedWeight)}</td>`,\n        `<td style=\"${CELL}${dim}\">${n(row.effectiveWeight)}</td>`,\n        `<td style=\"${CELL}${dim}\">${n(row.hits)} / ${n(row.misses)}</td></tr>`,\n      );\n    }\n    parts.push('</tbody></table>');\n  }\n  parts.push('</div>');\n  return parts.join('');\n}\n\n/** What {@link mountInspector} returns. */\nexport interface MountedInspector {\n  /** Re-reads the snapshot and re-renders. Call it after every `observe`, or from a timer you own. */\n  update: () => void;\n  /** Empties the container. */\n  unmount: () => void;\n}\n\n/**\n * Renders a live inspector into a container and keeps it current on demand. The container is\n * anything with an `innerHTML` property, so a DOM element; the library itself touches no DOM API\n * and sets no timer. Your app decides when to refresh: after each `observe`, or on an interval.\n *\n * @param container - The element to render into. Only its `innerHTML` is written.\n * @param read - Returns the snapshot to show, typically `() => inspect(state, Date.now())`.\n * @param opts - Passed to {@link renderInspector}.\n * @returns `update` to re-render and `unmount` to clear the container. The first render happens\n *   at once.\n * @example\n * ```ts\n * const panel = mountInspector(document.querySelector('#oracular')!, () => inspect(state, Date.now()));\n * state = observe(state, event);\n * panel.update();\n * ```\n */\nexport function mountInspector(\n  container: { innerHTML: string },\n  read: () => Snapshot,\n  opts: RenderOptions = {},\n): MountedInspector {\n  const update = () => {\n    container.innerHTML = renderInspector(read(), opts);\n  };\n  update();\n  return {\n    update,\n    unmount: () => {\n      container.innerHTML = '';\n    },\n  };\n}\n"]}

package/dist/presets.cjs

@@ -0,0 +1,86 @@
+'use strict';
+
+// 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
+  }
+};
+
+exports.presetSources = presetSources;
+exports.presets = presets;
+//# sourceMappingURL=presets.cjs.map
+//# sourceMappingURL=presets.cjs.map

package/dist/presets.cjs.map

@@ -0,0 +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"]}