oracular 0.8.1 → 0.10.0

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 // src/math.ts
 function decayFactor(elapsed, halfLife) {
-  if (!(elapsed > 0) || !Number.isFinite(elapsed)) return 1;
+  if (!(elapsed > 0)) return 1;
   return 2 ** (-elapsed / halfLife);
 }
 function betaMean(alpha, beta) {
@@ -82,10 +82,39 @@ function repeatFactor(n) {
 function laplace(successes, total) {
   return (successes + 1) / (total + 2);
 }
-function lift(q, b) {
+function lift(q, b, type = "normalized-difference") {
+  if (type === "absolute-difference") return q - b;
+  if (type !== "normalized-difference") {
+    const rate = Math.max(Number.EPSILON, Math.min(1 - Number.EPSILON, q));
+    const base = Math.max(Number.EPSILON, Math.min(1 - Number.EPSILON, b));
+    switch (type) {
+      case "relative-lift":
+        return (rate - base) / base;
+      case "log-lift":
+        return Math.log(rate / base);
+      case "odds-ratio":
+        return rate / (1 - rate) / (base / (1 - base));
+      case "risk-ratio":
+      case "association-rule":
+        return rate / base;
+    }
+  }
   if (q >= b) return b >= 1 ? 0 : (q - b) / (1 - b);
   return b <= 0 ? 0 : (q - b) / b;
 }
+function learningScore(value, type = "normalized-difference") {
+  switch (type) {
+    case "risk-ratio":
+    case "odds-ratio":
+    case "association-rule":
+      return (value - 1) / (value + 1);
+    case "relative-lift":
+    case "log-lift":
+      return value / (1 + Math.abs(value));
+    default:
+      return value;
+  }
+}
 
 // src/util.ts
 function isRecord(value) {
@@ -109,12 +138,11 @@ function mapRecord(record2, fn) {
 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 };
+  if (d === 1) return at === state.learnedAt ? state : { ...state, learnedAt: at };
   return {
     ...state,
-    learnedAt,
+    learnedAt: at,
     learned: mapRecord(state.learned, (r) => ({ hits: r.hits * d, misses: r.misses * d })),
     episodes: { hits: state.episodes.hits * d, misses: state.episodes.misses * d }
   };
@@ -131,7 +159,9 @@ function signalWeights(state, intent, learning, signal) {
   const nWithout = Math.max(0, totalEpisodes - nWith);
   const outcomesWithout = Math.min(nWithout, Math.max(0, state.episodes.hits - record2.hits));
   const qWithout = laplace(outcomesWithout, nWithout);
-  const learned = nWith === 0 ? 0 : learning.gain * Math.abs(initial) * lift(qWith, qWithout);
+  const baseline = learning.lift === "association-rule" ? (record2.hits + outcomesWithout + 2) / (nWith + nWithout + 4) : qWithout;
+  const score = learningScore(lift(qWith, baseline, learning.lift), learning.lift);
+  const learned = nWith === 0 ? 0 : learning.gain * Math.abs(initial) * score;
   const nEff = nWith + nWithout === 0 ? 0 : nWith * nWithout / (nWith + nWithout);
   const k = learning.priorEpisodes;
   const effective = (k * initial + nEff * learned) / (k + nEff);
@@ -221,13 +251,12 @@ function withContributions(state, intent, 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 };
+  if (d === 1) return at === state.updatedAt ? state : { ...state, updatedAt: at };
   const contributions = mapRecord(state.contributions, (c) => ({
     alpha: c.alpha * d,
     beta: c.beta * d
   }));
-  return withContributions({ ...state, updatedAt }, intent, contributions);
+  return withContributions({ ...state, updatedAt: at }, intent, contributions);
 }
 function applySignal(state, intent, signal, weight) {
   const prev = getOwn(state.contributions, signal) ?? { alpha: 0, beta: 0 };
@@ -244,6 +273,7 @@ var DEFAULT_Z = 1.28;
 var DEFAULT_GAIN = 2;
 var DEFAULT_PRIOR_EPISODES = 10;
 var MAX_MAGNITUDE = 1e6;
+var MAX_Z = 10;
 var CONFIG_KEYS = ["intents", "episodeTimeout", "learning", "reveal"];
 var INTENT_KEYS = [
   "prior",
@@ -257,7 +287,16 @@ var INTENT_KEYS = [
   "reveal"
 ];
 var REVEAL_KEYS = ["threshold", "z", "cooldown", "bound"];
-var LEARNING_KEYS = ["halfLife", "gain", "priorEpisodes"];
+var LEARNING_KEYS = ["halfLife", "gain", "priorEpisodes", "lift"];
+var LIFT_TYPES = [
+  "absolute-difference",
+  "relative-lift",
+  "risk-ratio",
+  "log-lift",
+  "odds-ratio",
+  "normalized-difference",
+  "association-rule"
+];
 var EXPLAIN_KEYS = ["nonZero", "limit"];
 function typeError(path, message) {
   throw new TypeError(`oracular: ${path} ${message}`);
@@ -319,14 +358,17 @@ function expectKeyName(name, path) {
   if (name === "__proto__") typeError(path, 'must not use the reserved name "__proto__"');
   return name;
 }
-function normalizeRevealOptions(value, path) {
+function normalizeRevealOptions(value, path, strict = true) {
   const record2 = expectRecord(value, path);
   expectKeys(record2, REVEAL_KEYS, path);
   const out = {};
   if (record2.threshold !== void 0) {
-    out.threshold = expectClosedUnit(record2.threshold, `${path}.threshold`);
+    out.threshold = strict ? expectOpenUnit(record2.threshold, `${path}.threshold`) : expectClosedUnit(record2.threshold, `${path}.threshold`);
+  }
+  if (record2.z !== void 0) {
+    out.z = expectNonNegative(record2.z, `${path}.z`);
+    if (strict && out.z > MAX_Z) rangeError(`${path}.z`, `must be at most ${MAX_Z}`);
   }
-  if (record2.z !== void 0) out.z = expectNonNegative(record2.z, `${path}.z`);
   if (record2.cooldown !== void 0) {
     out.cooldown = expectNonNegative(record2.cooldown, `${path}.cooldown`);
   }
@@ -342,6 +384,12 @@ function normalizeLearning(value, path) {
   const record2 = expectRecord(value, path);
   expectKeys(record2, LEARNING_KEYS, path);
   const out = {};
+  if (record2.lift !== void 0) {
+    if (!LIFT_TYPES.includes(record2.lift)) {
+      typeError(`${path}.lift`, `must be one of: ${LIFT_TYPES.join(", ")}`);
+    }
+    out.lift = record2.lift;
+  }
   if (record2.halfLife !== void 0)
     out.halfLife = expectPositive(record2.halfLife, `${path}.halfLife`);
   if (record2.gain !== void 0) out.gain = expectBoundedPositive(record2.gain, `${path}.gain`);
@@ -350,7 +398,7 @@ function normalizeLearning(value, path) {
   }
   return out;
 }
-function normalizeIntentConfig(value, path) {
+function normalizeIntentConfig(value, path, strict = true) {
   const record2 = expectRecord(value, path);
   expectKeys(record2, INTENT_KEYS, path);
   const signalsRecord = expectRecord(record2.signals, `${path}.signals`);
@@ -392,11 +440,18 @@ function normalizeIntentConfig(value, path) {
   if (record2.attribution !== void 0) {
     out.attribution = expectPositive(record2.attribution, `${path}.attribution`);
   }
-  if (record2.reveal !== void 0)
-    out.reveal = normalizeRevealOptions(record2.reveal, `${path}.reveal`);
+  if (record2.reveal !== void 0) {
+    out.reveal = normalizeRevealOptions(record2.reveal, `${path}.reveal`, strict);
+  }
+  if (strict && out.outcome !== void 0 && hasOwn(signals, out.outcome) && out.resetOnOutcome !== false) {
+    typeError(
+      `${path}.outcome`,
+      "is also one of its signals: the reset on outcome would wipe what it adds; set resetOnOutcome: false to keep it"
+    );
+  }
   return out;
 }
-function normalizeConfig(value) {
+function normalizeConfig(value, strict = true) {
   const record2 = expectRecord(value, "config");
   expectKeys(record2, CONFIG_KEYS, "config");
   const intentsRecord = expectRecord(record2.intents, "config.intents");
@@ -407,7 +462,8 @@ function normalizeConfig(value) {
     expectKeyName(name, "config.intents");
     intents[name] = normalizeIntentConfig(
       intentsRecord[name],
-      `config.intents[${JSON.stringify(name)}]`
+      `config.intents[${JSON.stringify(name)}]`,
+      strict
     );
   }
   const out = { intents };
@@ -416,8 +472,9 @@ function normalizeConfig(value) {
   }
   if (record2.learning !== void 0)
     out.learning = normalizeLearning(record2.learning, "config.learning");
-  if (record2.reveal !== void 0)
-    out.reveal = normalizeRevealOptions(record2.reveal, "config.reveal");
+  if (record2.reveal !== void 0) {
+    out.reveal = normalizeRevealOptions(record2.reveal, "config.reveal", strict);
+  }
   return out;
 }
 function normalizeExplainOptions(value, path) {
@@ -447,12 +504,12 @@ function splitEvaluateOptions(value, path) {
     else explain2[key] = v;
   }
   return {
-    reveal: normalizeRevealOptions(reveal, path),
+    reveal: normalizeRevealOptions(reveal, path, false),
     explain: normalizeExplainOptions(explain2, path)
   };
 }
 function resolveReveal(config, intent, opts, normalized = false) {
-  const o = opts === void 0 ? {} : normalized ? opts : normalizeRevealOptions(opts, "options");
+  const o = opts === void 0 ? {} : normalized ? opts : normalizeRevealOptions(opts, "options", false);
   return {
     threshold: o.threshold ?? intent.reveal?.threshold ?? config?.reveal?.threshold ?? DEFAULT_THRESHOLD,
     z: o.z ?? intent.reveal?.z ?? config?.reveal?.z ?? DEFAULT_Z,
@@ -462,6 +519,7 @@ function resolveReveal(config, intent, opts, normalized = false) {
 }
 function resolveLearning(config) {
   return {
+    lift: config.learning?.lift ?? "normalized-difference",
     halfLife: config.learning?.halfLife ?? null,
     gain: config.learning?.gain ?? DEFAULT_GAIN,
     priorEpisodes: config.learning?.priorEpisodes ?? DEFAULT_PRIOR_EPISODES
@@ -489,11 +547,7 @@ function timedOutAt(episode, timeout, at) {
   return at - episode.lastEventAt > timeout ? episode.lastEventAt + timeout : null;
 }
 function extendEpisode(episode, at) {
-  return {
-    startedAt: episode.startedAt ?? at,
-    lastEventAt: episode.lastEventAt === null ? at : Math.max(episode.lastEventAt, at),
-    intents: episode.intents
-  };
+  return { startedAt: episode.startedAt ?? at, lastEventAt: at, intents: episode.intents };
 }
 function episodeRecord(episode, intent) {
   return getOwn(episode.intents, intent) ?? { seen: [], counts: {}, resolved: false };
@@ -551,7 +605,7 @@ function assessIntent(state, name, intent, learning, at) {
 }
 function cooldownEnd(since, cooldown, at) {
   if (since === null) return null;
-  const end = since + cooldown;
+  const end = Math.min(since, at) + cooldown;
   return at < end ? end : null;
 }
 function buildPrediction(is, name, reveal, at) {
@@ -679,6 +733,7 @@ function observe(state, event) {
     let is = getIntentState(s, intentName, intent);
     is = decayIntent(is, intent, at);
     is = settlePending(is, intent, learning, at);
+    is = pinAnchors(is, at);
     if (isSignal) {
       const { effective } = signalWeights(is, intent, learning, name);
       const n = occurrences(episode, intentName, name) + 1;
@@ -688,7 +743,8 @@ function observe(state, event) {
       if (!isOutcome) episode = markSeen(episode, intentName, name);
     }
     if (isOutcome) {
-      is = recordEpisode(is, episodeRecord(episode, intentName).seen, 1);
+      const record2 = episodeRecord(episode, intentName);
+      if (!record2.resolved || record2.seen.length > 0) is = recordEpisode(is, record2.seen, 1);
       is = creditPending(is, intent, at);
       episode = markResolved(episode, intentName);
       is = { ...is, lastOutcomeAt: at };
@@ -698,6 +754,16 @@ function observe(state, event) {
   }
   return { ...s, intents, episode };
 }
+function pinAnchors(is, at) {
+  const reveal = is.lastRevealedAt !== null && is.lastRevealedAt > at;
+  const outcome = is.lastOutcomeAt !== null && is.lastOutcomeAt > at;
+  if (!reveal && !outcome) return is;
+  return {
+    ...is,
+    lastRevealedAt: reveal ? at : is.lastRevealedAt,
+    lastOutcomeAt: outcome ? at : is.lastOutcomeAt
+  };
+}
 function endEpisode(state, at) {
   const s = requireState(state);
   const t = expectTimestamp(at, "at");
@@ -1015,7 +1081,9 @@ function parseState(value) {
   }
   return {
     version: STATE_VERSION,
-    config: normalizeConfig(r.config),
+    // Without the strict checks: a config this release would refuse at createState still loads
+    // when it is only stored, and the config passed in replaces it anyway.
+    config: normalizeConfig(r.config, false),
     intents: mapOwn(r.intents, "state.intents", intentState),
     episode: episodeState(r.episode, "state.episode")
   };