oracular 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.2
+
+### Patch Changes
+
+- [#6](https://github.com/Yuribenjamin/oracular/pull/6) [`57d121f`](https://github.com/Yuribenjamin/oracular/commit/57d121f107f4ed92f2e59bf354cc6e19f705de1b) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - Docs corrections from the first production integration; new evaluate(), evidenceToReveal(), episodeClosed() and explain() filtering; default export condition.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -223,7 +223,10 @@ endEpisode(state, at: number): EngineState
 predict(state, intent: string, at: number, opts?: RevealOptions): Prediction
 shouldReveal(state, intent: string, at: number, opts?: RevealOptions): boolean
 markRevealed(state, intent: string, at: number): EngineState
-explain(state, intent: string, at: number): SignalExplanation[]
+explain(state, intent: string, at: number, opts?: { nonZero?: boolean; limit?: number }): SignalExplanation[]
+evaluate(state, intent: string, at: number, opts?): { prediction, reveal, explanation }  // all three, one decay pass
+evidenceToReveal(intentConfig, opts?): number   // pseudo-counts at which shouldReveal first becomes true
+episodeClosed(prev, next): boolean               // did an episode close between two states?
 serialize(state): string
 deserialize(json: string, opts?: { config?: EngineConfig; migrate?: Migrate }): EngineState
 STATE_VERSION // 1

package/dist/index.cjs

@@ -1,5 +1,33 @@
 'use strict';
 
+// src/math.ts
+function decayFactor(elapsed, halfLife) {
+  if (!(elapsed > 0) || !Number.isFinite(elapsed)) return 1;
+  return 2 ** (-elapsed / halfLife);
+}
+function betaMean(alpha, beta) {
+  return alpha / (alpha + beta);
+}
+function betaVariance(alpha, beta) {
+  const n = alpha + beta;
+  return alpha * beta / (n * n * (n + 1));
+}
+function betaSd(alpha, beta) {
+  return Math.sqrt(betaVariance(alpha, beta));
+}
+function clamp01(x) {
+  if (x < 0) return 0;
+  if (x > 1) return 1;
+  return x;
+}
+function laplace(successes, total) {
+  return (successes + 1) / (total + 2);
+}
+function lift(q, b) {
+  if (q >= b) return b >= 1 ? 0 : (q - b) / (1 - b);
+  return b <= 0 ? 0 : (q - b) / b;
+}
+
 // src/util.ts
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -18,6 +46,96 @@ function mapRecord(record2, fn) {
   return out;
 }
 
+// src/intent.ts
+function priorCounts(intent) {
+  return {
+    alpha0: intent.prior * intent.priorStrength,
+    beta0: (1 - intent.prior) * intent.priorStrength
+  };
+}
+function initIntent(intent) {
+  const { alpha0, beta0 } = priorCounts(intent);
+  return {
+    alpha: alpha0,
+    beta: beta0,
+    updatedAt: null,
+    contributions: {},
+    learned: {},
+    episodes: { hits: 0, misses: 0 },
+    learnedAt: null,
+    lastRevealedAt: null,
+    lastOutcomeAt: null,
+    revealCount: 0
+  };
+}
+function withContributions(state, intent, contributions) {
+  const { alpha0, beta0 } = priorCounts(intent);
+  let alpha = alpha0;
+  let beta = beta0;
+  for (const c of Object.values(contributions)) {
+    alpha += c.alpha;
+    beta += c.beta;
+  }
+  return { ...state, alpha, beta, contributions };
+}
+function decayIntent(state, intent, at) {
+  if (state.updatedAt === null) return { ...state, updatedAt: at };
+  const d = decayFactor(at - state.updatedAt, intent.halfLife);
+  const updatedAt = Math.max(state.updatedAt, at);
+  if (d === 1) return updatedAt === state.updatedAt ? state : { ...state, updatedAt };
+  const contributions = mapRecord(state.contributions, (c) => ({
+    alpha: c.alpha * d,
+    beta: c.beta * d
+  }));
+  return withContributions({ ...state, updatedAt }, intent, contributions);
+}
+function applySignal(state, intent, signal, weight) {
+  const prev = getOwn(state.contributions, signal) ?? { alpha: 0, beta: 0 };
+  const next = weight >= 0 ? { alpha: prev.alpha + weight, beta: prev.beta } : { alpha: prev.alpha, beta: prev.beta - weight };
+  return withContributions(state, intent, { ...state.contributions, [signal]: next });
+}
+function resetToPrior(state, intent) {
+  return withContributions(state, intent, {});
+}
+
+// src/learning.ts
+var NONE = { hits: 0, misses: 0 };
+function decayLearned(state, learning, at) {
+  if (state.learnedAt === null) return { ...state, learnedAt: at };
+  const learnedAt = Math.max(state.learnedAt, at);
+  const d = learning.halfLife === null ? 1 : decayFactor(at - state.learnedAt, learning.halfLife);
+  if (d === 1) return learnedAt === state.learnedAt ? state : { ...state, learnedAt };
+  return {
+    ...state,
+    learnedAt,
+    learned: mapRecord(state.learned, (r) => ({ hits: r.hits * d, misses: r.misses * d })),
+    episodes: { hits: state.episodes.hits * d, misses: state.episodes.misses * d }
+  };
+}
+function signalWeights(state, intent, learning, signal) {
+  const initial = getOwn(intent.signals, signal);
+  if (initial === void 0) {
+    throw new RangeError(`oracular: ${JSON.stringify(signal)} is not a signal of this intent`);
+  }
+  const record2 = getOwn(state.learned, signal) ?? NONE;
+  const n = record2.hits + record2.misses;
+  const q = laplace(record2.hits, n);
+  const b = laplace(state.episodes.hits, state.episodes.hits + state.episodes.misses);
+  const learned = n === 0 ? 0 : learning.gain * Math.abs(initial) * lift(q, b);
+  const k = learning.priorEpisodes;
+  const effective = (k * initial + n * learned) / (k + n);
+  return { initial, learned, effective, hits: record2.hits, misses: record2.misses };
+}
+function recordEpisode(state, signals, outcome) {
+  const learned = { ...state.learned };
+  for (const signal of signals) {
+    const r = getOwn(learned, signal) ?? NONE;
+    learned[signal] = outcome ? { hits: r.hits + 1, misses: r.misses } : { hits: r.hits, misses: r.misses + 1 };
+  }
+  const episodes = outcome ? { hits: state.episodes.hits + 1, misses: state.episodes.misses } : { hits: state.episodes.hits, misses: state.episodes.misses + 1 };
+  return { ...state, learned, episodes };
+}
+
 // src/config.ts
 var DEFAULT_THRESHOLD = 0.5;
 var DEFAULT_Z = 1.28;
@@ -35,6 +153,7 @@ var INTENT_KEYS = [
 ];
 var REVEAL_KEYS = ["threshold", "z", "cooldown"];
 var LEARNING_KEYS = ["halfLife", "gain", "priorEpisodes"];
+var EXPLAIN_KEYS = ["nonZero", "limit"];
 function typeError(path, message) {
   throw new TypeError(`oracular: ${path} ${message}`);
 }
@@ -115,7 +234,7 @@ function normalizeLearning(value, path) {
   }
   return out;
 }
-function normalizeIntent(value, path) {
+function normalizeIntentConfig(value, path) {
   const record2 = expectRecord(value, path);
   expectKeys(record2, INTENT_KEYS, path);
   const signalsRecord = expectRecord(record2.signals, `${path}.signals`);
@@ -157,7 +276,10 @@ function normalizeConfig(value) {
   const intents = {};
   for (const name of names) {
     expectKeyName(name, "config.intents");
-    intents[name] = normalizeIntent(intentsRecord[name], `config.intents[${JSON.stringify(name)}]`);
+    intents[name] = normalizeIntentConfig(
+      intentsRecord[name],
+      `config.intents[${JSON.stringify(name)}]`
+    );
   }
   const out = { intents };
   if (record2.episodeTimeout !== void 0) {
@@ -169,12 +291,43 @@ function normalizeConfig(value) {
     out.reveal = normalizeRevealOptions(record2.reveal, "config.reveal");
   return out;
 }
-function resolveReveal(config, intent, opts) {
-  const o = opts === void 0 ? {} : normalizeRevealOptions(opts, "options");
+function normalizeExplainOptions(value, path) {
+  const record2 = expectRecord(value, path);
+  expectKeys(record2, EXPLAIN_KEYS, path);
+  const out = {};
+  if (record2.nonZero !== void 0) {
+    if (typeof record2.nonZero !== "boolean") typeError(`${path}.nonZero`, "must be a boolean");
+    out.nonZero = record2.nonZero;
+  }
+  if (record2.limit !== void 0) {
+    const n = expectNumber(record2.limit, `${path}.limit`);
+    if (!Number.isInteger(n) || n < 0)
+      rangeError(`${path}.limit`, "must be a non-negative integer");
+    out.limit = n;
+  }
+  return out;
+}
+function splitEvaluateOptions(value, path) {
+  if (value === void 0) return { reveal: {}, explain: {} };
+  const record2 = expectRecord(value, path);
+  expectKeys(record2, [...REVEAL_KEYS, ...EXPLAIN_KEYS], path);
+  const reveal = {};
+  const explain2 = {};
+  for (const [key, v] of Object.entries(record2)) {
+    if (REVEAL_KEYS.includes(key)) reveal[key] = v;
+    else explain2[key] = v;
+  }
+  return {
+    reveal: normalizeRevealOptions(reveal, path),
+    explain: normalizeExplainOptions(explain2, path)
+  };
+}
+function resolveReveal(config, intent, opts, normalized = false) {
+  const o = opts === void 0 ? {} : normalized ? opts : normalizeRevealOptions(opts, "options");
   return {
-    threshold: o.threshold ?? intent.reveal?.threshold ?? config.reveal?.threshold ?? DEFAULT_THRESHOLD,
-    z: o.z ?? intent.reveal?.z ?? config.reveal?.z ?? DEFAULT_Z,
-    cooldown: o.cooldown ?? intent.reveal?.cooldown ?? config.reveal?.cooldown ?? intent.halfLife
+    threshold: o.threshold ?? intent.reveal?.threshold ?? config?.reveal?.threshold ?? DEFAULT_THRESHOLD,
+    z: o.z ?? intent.reveal?.z ?? config?.reveal?.z ?? DEFAULT_Z,
+    cooldown: o.cooldown ?? intent.reveal?.cooldown ?? config?.reveal?.cooldown ?? intent.halfLife
   };
 }
 function resolveLearning(config) {
@@ -197,124 +350,6 @@ function validateEvent(event) {
   return { name, at };
 }
 
-// src/math.ts
-function decayFactor(elapsed, halfLife) {
-  if (!(elapsed > 0) || !Number.isFinite(elapsed)) return 1;
-  return 2 ** (-elapsed / halfLife);
-}
-function betaMean(alpha, beta) {
-  return alpha / (alpha + beta);
-}
-function betaVariance(alpha, beta) {
-  const n = alpha + beta;
-  return alpha * beta / (n * n * (n + 1));
-}
-function betaSd(alpha, beta) {
-  return Math.sqrt(betaVariance(alpha, beta));
-}
-function clamp01(x) {
-  if (x < 0) return 0;
-  if (x > 1) return 1;
-  return x;
-}
-function laplace(successes, total) {
-  return (successes + 1) / (total + 2);
-}
-function lift(q, b) {
-  if (q >= b) return b >= 1 ? 0 : (q - b) / (1 - b);
-  return b <= 0 ? 0 : (q - b) / b;
-}
-
-// src/intent.ts
-function priorCounts(intent) {
-  return {
-    alpha0: intent.prior * intent.priorStrength,
-    beta0: (1 - intent.prior) * intent.priorStrength
-  };
-}
-function initIntent(intent) {
-  const { alpha0, beta0 } = priorCounts(intent);
-  return {
-    alpha: alpha0,
-    beta: beta0,
-    updatedAt: null,
-    contributions: {},
-    learned: {},
-    episodes: { hits: 0, misses: 0 },
-    learnedAt: null,
-    lastRevealedAt: null,
-    lastOutcomeAt: null,
-    revealCount: 0
-  };
-}
-function withContributions(state, intent, contributions) {
-  const { alpha0, beta0 } = priorCounts(intent);
-  let alpha = alpha0;
-  let beta = beta0;
-  for (const c of Object.values(contributions)) {
-    alpha += c.alpha;
-    beta += c.beta;
-  }
-  return { ...state, alpha, beta, contributions };
-}
-function decayIntent(state, intent, at) {
-  if (state.updatedAt === null) return { ...state, updatedAt: at };
-  const d = decayFactor(at - state.updatedAt, intent.halfLife);
-  const updatedAt = Math.max(state.updatedAt, at);
-  if (d === 1) return updatedAt === state.updatedAt ? state : { ...state, updatedAt };
-  const contributions = mapRecord(state.contributions, (c) => ({
-    alpha: c.alpha * d,
-    beta: c.beta * d
-  }));
-  return withContributions({ ...state, updatedAt }, intent, contributions);
-}
-function applySignal(state, intent, signal, weight) {
-  const prev = getOwn(state.contributions, signal) ?? { alpha: 0, beta: 0 };
-  const next = weight >= 0 ? { alpha: prev.alpha + weight, beta: prev.beta } : { alpha: prev.alpha, beta: prev.beta - weight };
-  return withContributions(state, intent, { ...state.contributions, [signal]: next });
-}
-function resetToPrior(state, intent) {
-  return withContributions(state, intent, {});
-}
-
-// src/learning.ts
-var NONE = { hits: 0, misses: 0 };
-function decayLearned(state, learning, at) {
-  if (state.learnedAt === null) return { ...state, learnedAt: at };
-  const learnedAt = Math.max(state.learnedAt, at);
-  const d = learning.halfLife === null ? 1 : decayFactor(at - state.learnedAt, learning.halfLife);
-  if (d === 1) return learnedAt === state.learnedAt ? state : { ...state, learnedAt };
-  return {
-    ...state,
-    learnedAt,
-    learned: mapRecord(state.learned, (r) => ({ hits: r.hits * d, misses: r.misses * d })),
-    episodes: { hits: state.episodes.hits * d, misses: state.episodes.misses * d }
-  };
-}
-function signalWeights(state, intent, learning, signal) {
-  const initial = getOwn(intent.signals, signal);
-  if (initial === void 0) {
-    throw new RangeError(`oracular: ${JSON.stringify(signal)} is not a signal of this intent`);
-  }
-  const record2 = getOwn(state.learned, signal) ?? NONE;
-  const n = record2.hits + record2.misses;
-  const q = laplace(record2.hits, n);
-  const b = laplace(state.episodes.hits, state.episodes.hits + state.episodes.misses);
-  const learned = n === 0 ? 0 : learning.gain * Math.abs(initial) * lift(q, b);
-  const k = learning.priorEpisodes;
-  const effective = (k * initial + n * learned) / (k + n);
-  return { initial, learned, effective, hits: record2.hits, misses: record2.misses };
-}
-function recordEpisode(state, signals, outcome) {
-  const learned = { ...state.learned };
-  for (const signal of signals) {
-    const r = getOwn(learned, signal) ?? NONE;
-    learned[signal] = outcome ? { hits: r.hits + 1, misses: r.misses } : { hits: r.hits, misses: r.misses + 1 };
-  }
-  const episodes = outcome ? { hits: state.episodes.hits + 1, misses: state.episodes.misses } : { hits: state.episodes.hits, misses: state.episodes.misses + 1 };
-  return { ...state, learned, episodes };
-}
-
 // src/episode.ts
 function emptyEpisode() {
   return { startedAt: null, lastEventAt: null, intents: {} };
@@ -374,20 +409,42 @@ function getIntentState(state, name, intent) {
   return getOwn(state.intents, name) ?? initIntent(intent);
 }
 
-// src/explain.ts
-function explain(state, intent, at) {
-  const s = requireState(state);
-  const name = expectName(intent, "intent");
-  const t = expectTimestamp(at, "at");
-  const config = requireIntentConfig(s, name);
-  const learning = resolveLearning(s.config);
-  let is = decayIntent(getIntentState(s, name, config), config, t);
-  is = decayLearned(is, learning, t);
+// src/assess.ts
+function assessIntent(state, name, intent, learning, at) {
+  return decayLearned(decayIntent(getIntentState(state, name, intent), intent, at), learning, at);
+}
+function cooldownEnd(since, cooldown, at) {
+  if (since === null) return null;
+  const end = since + cooldown;
+  return at < end ? end : null;
+}
+function buildPrediction(is, name, reveal, at) {
+  const p = betaMean(is.alpha, is.beta);
+  const sd = betaSd(is.alpha, is.beta);
+  const revealEnd = cooldownEnd(is.lastRevealedAt, reveal.cooldown, at);
+  const outcomeEnd = cooldownEnd(is.lastOutcomeAt, reveal.cooldown, at);
+  const suppressedUntil = revealEnd === null ? outcomeEnd : outcomeEnd === null ? revealEnd : Math.max(revealEnd, outcomeEnd);
+  return {
+    intent: name,
+    p,
+    sd,
+    lower: clamp01(p - reveal.z * sd),
+    confidence: clamp01(1 - 2 * sd),
+    evidence: is.alpha + is.beta,
+    revealed: revealEnd !== null,
+    revealedAt: is.lastRevealedAt,
+    suppressedUntil
+  };
+}
+function decideReveal(prediction, reveal) {
+  return prediction.suppressedUntil === null && prediction.p >= reveal.threshold && prediction.lower >= reveal.threshold;
+}
+function buildExplanation(is, intent, learning, opts) {
   const p = betaMean(is.alpha, is.beta);
   const out = [];
-  for (const signal of Object.keys(config.signals)) {
+  for (const signal of Object.keys(intent.signals)) {
     const c = getOwn(is.contributions, signal) ?? { alpha: 0, beta: 0 };
-    const w = signalWeights(is, config, learning, signal);
+    const w = signalWeights(is, intent, learning, signal);
     const without = betaMean(is.alpha - c.alpha, is.beta - c.beta);
     out.push({
       signal,
@@ -401,7 +458,8 @@ function explain(state, intent, at) {
     });
   }
   out.sort((a, b) => Math.abs(b.impact) - Math.abs(a.impact) || compare(a.signal, b.signal));
-  return out;
+  const filtered = opts.nonZero ? out.filter((row) => row.contribution !== 0) : out;
+  return opts.limit === void 0 ? filtered : filtered.slice(0, opts.limit);
 }
 function compare(a, b) {
   if (a < b) return -1;
@@ -409,6 +467,62 @@ function compare(a, b) {
   return 0;
 }
 
+// src/evaluate.ts
+function evaluate(state, intent, at, opts) {
+  const s = requireState(state);
+  const name = expectName(intent, "intent");
+  const t = expectTimestamp(at, "at");
+  const config = requireIntentConfig(s, name);
+  const split = splitEvaluateOptions(opts, "options");
+  const reveal = resolveReveal(s.config, config, split.reveal, true);
+  const learning = resolveLearning(s.config);
+  const is = assessIntent(s, name, config, learning, t);
+  const prediction = buildPrediction(is, name, reveal, t);
+  return {
+    prediction,
+    reveal: decideReveal(prediction, reveal),
+    explanation: buildExplanation(is, config, learning, split.explain)
+  };
+}
+
+// src/evidence.ts
+function evidenceToReveal(intent, opts) {
+  const config = normalizeIntentConfig(intent, "intent");
+  const { threshold, z } = resolveReveal(void 0, config, opts);
+  const { alpha0, beta0 } = priorCounts(config);
+  const open = (w) => {
+    const alpha = alpha0 + w;
+    const p = betaMean(alpha, beta0);
+    return p >= threshold && clamp01(p - z * betaSd(alpha, beta0)) >= threshold;
+  };
+  if (threshold >= 1) return Number.POSITIVE_INFINITY;
+  if (open(0)) return 0;
+  let lo = 0;
+  let hi = 1;
+  while (!open(hi)) {
+    lo = hi;
+    hi *= 2;
+    if (hi > 1e15) return Number.POSITIVE_INFINITY;
+  }
+  for (let i = 0; i < 200 && hi - lo > 1e-9; i++) {
+    const mid = (lo + hi) / 2;
+    if (open(mid)) hi = mid;
+    else lo = mid;
+  }
+  return hi;
+}
+
+// src/explain.ts
+function explain(state, intent, at, opts) {
+  const s = requireState(state);
+  const name = expectName(intent, "intent");
+  const t = expectTimestamp(at, "at");
+  const config = requireIntentConfig(s, name);
+  const filters = opts === void 0 ? {} : normalizeExplainOptions(opts, "options");
+  const learning = resolveLearning(s.config);
+  return buildExplanation(assessIntent(s, name, config, learning, t), config, learning, filters);
+}
+
 // src/observe.ts
 function observe(state, event) {
   let s = requireState(state);
@@ -460,6 +574,11 @@ function closeEpisode(state, at) {
   }
   return { ...state, intents, episode: emptyEpisode() };
 }
+function episodeClosed(prev, next) {
+  const a = requireState(prev);
+  const b = requireState(next);
+  return a.episode.startedAt !== null && b.episode.startedAt !== a.episode.startedAt;
+}
 
 // src/predict.ts
 function predict(state, intent, at, opts) {
@@ -469,35 +588,14 @@ function predict(state, intent, at, opts) {
   const config = requireIntentConfig(s, name);
   const reveal = resolveReveal(s.config, config, opts);
   const is = decayIntent(getIntentState(s, name, config), config, t);
-  const p = betaMean(is.alpha, is.beta);
-  const sd = betaSd(is.alpha, is.beta);
-  const revealEnd = cooldownEnd(is.lastRevealedAt, reveal.cooldown, t);
-  const outcomeEnd = cooldownEnd(is.lastOutcomeAt, reveal.cooldown, t);
-  const suppressedUntil = revealEnd === null ? outcomeEnd : outcomeEnd === null ? revealEnd : Math.max(revealEnd, outcomeEnd);
-  return {
-    intent: name,
-    p,
-    sd,
-    lower: clamp01(p - reveal.z * sd),
-    confidence: clamp01(1 - 2 * sd),
-    evidence: is.alpha + is.beta,
-    revealed: revealEnd !== null,
-    revealedAt: is.lastRevealedAt,
-    suppressedUntil
-  };
-}
-function cooldownEnd(since, cooldown, at) {
-  if (since === null) return null;
-  const end = since + cooldown;
-  return at < end ? end : null;
+  return buildPrediction(is, name, reveal, t);
 }
 function shouldReveal(state, intent, at, opts) {
   const s = requireState(state);
   const name = expectName(intent, "intent");
   const config = requireIntentConfig(s, name);
-  const { threshold } = resolveReveal(s.config, config, opts);
-  const prediction = predict(s, name, at, opts);
-  return prediction.suppressedUntil === null && prediction.p >= threshold && prediction.lower >= threshold;
+  const reveal = resolveReveal(s.config, config, opts);
+  return decideReveal(predict(s, name, at, opts), reveal);
 }
 function markRevealed(state, intent, at) {
   const s = requireState(state);
@@ -688,6 +786,9 @@ exports.STATE_VERSION = STATE_VERSION;
 exports.createState = createState;
 exports.deserialize = deserialize;
 exports.endEpisode = endEpisode;
+exports.episodeClosed = episodeClosed;
+exports.evaluate = evaluate;
+exports.evidenceToReveal = evidenceToReveal;
 exports.explain = explain;
 exports.markRevealed = markRevealed;
 exports.observe = observe;