oracular 0.5.2 → 0.7.0

package/dist/index.js

@@ -47,6 +47,86 @@ function mapRecord(record2, fn) {
   return out;
 }
 
+// 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 nWith = record2.hits + record2.misses;
+  const qWith = laplace(record2.hits, nWith);
+  const totalEpisodes = state.episodes.hits + state.episodes.misses;
+  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 nEff = nWith + nWithout === 0 ? 0 : nWith * nWithout / (nWith + nWithout);
+  const k = learning.priorEpisodes;
+  const effective = (k * initial + nEff * learned) / (k + nEff);
+  return { initial, learned, effective, hits: record2.hits, misses: record2.misses };
+}
+function recordEpisode(state, signals, credit) {
+  const miss = 1 - credit;
+  const learned = { ...state.learned };
+  for (const signal of signals) {
+    const r = getOwn(learned, signal) ?? NONE;
+    learned[signal] = { hits: r.hits + credit, misses: r.misses + miss };
+  }
+  const episodes = { hits: state.episodes.hits + credit, misses: state.episodes.misses + miss };
+  return { ...state, learned, episodes };
+}
+
+// src/attribution.ts
+var MAX_PENDING = 32;
+function expiry(episode, intent) {
+  return episode.endedAt + (intent.attribution ?? 0);
+}
+function settlePending(state, intent, learning, at) {
+  let is = state;
+  let settled = 0;
+  for (const episode of state.pending) {
+    const end = expiry(episode, intent);
+    if (!(end < at)) break;
+    is = recordEpisode(decayLearned(is, learning, end), episode.seen, 0);
+    settled++;
+  }
+  if (settled > 0) is = { ...is, pending: state.pending.slice(settled) };
+  return decayLearned(is, learning, at);
+}
+function deferEpisode(state, seen, endedAt) {
+  const pending = insert(state.pending, { endedAt, seen: [...seen] });
+  if (pending.length <= MAX_PENDING) return { ...state, pending };
+  const [oldest, ...rest] = pending;
+  return { ...recordEpisode(state, oldest.seen, 0), pending: rest };
+}
+function insert(pending, episode) {
+  let i = pending.length;
+  while (i > 0 && pending[i - 1].endedAt > episode.endedAt) i--;
+  return [...pending.slice(0, i), episode, ...pending.slice(i)];
+}
+function creditPending(state, intent, at) {
+  if (state.pending.length === 0) return state;
+  let is = state;
+  for (const episode of state.pending) {
+    is = recordEpisode(is, episode.seen, decayFactor(at - episode.endedAt, intent.halfLife));
+  }
+  return { ...is, pending: [] };
+}
+
 // src/intent.ts
 function priorCounts(intent) {
   return {
@@ -63,6 +143,7 @@ function initIntent(intent) {
     contributions: {},
     learned: {},
     episodes: { hits: 0, misses: 0 },
+    pending: [],
     learnedAt: null,
     lastRevealedAt: null,
     lastOutcomeAt: null,
@@ -99,48 +180,6 @@ 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 nWith = record2.hits + record2.misses;
-  const qWith = laplace(record2.hits, nWith);
-  const totalEpisodes = state.episodes.hits + state.episodes.misses;
-  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 nEff = nWith + nWithout === 0 ? 0 : nWith * nWithout / (nWith + nWithout);
-  const k = learning.priorEpisodes;
-  const effective = (k * initial + nEff * learned) / (k + nEff);
-  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;
@@ -156,6 +195,7 @@ var INTENT_KEYS = [
   "outcome",
   "resetOnOutcome",
   "saturate",
+  "attribution",
   "reveal"
 ];
 var REVEAL_KEYS = ["threshold", "z", "cooldown"];
@@ -285,6 +325,9 @@ function normalizeIntentConfig(value, path) {
     if (typeof record2.saturate !== "boolean") typeError(`${path}.saturate`, "must be a boolean");
     out.saturate = record2.saturate;
   }
+  if (record2.attribution !== void 0) {
+    out.attribution = expectPositive(record2.attribution, `${path}.attribution`);
+  }
   if (record2.reveal !== void 0)
     out.reveal = normalizeRevealOptions(record2.reveal, `${path}.reveal`);
   return out;
@@ -407,7 +450,7 @@ function markResolved(episode, intent) {
 }
 
 // src/version.ts
-var STATE_VERSION = 2;
+var STATE_VERSION = 3;
 var RECORD_VERSION = 1;
 
 // src/state.ts
@@ -438,7 +481,8 @@ function getIntentState(state, name, intent) {
 
 // src/assess.ts
 function assessIntent(state, name, intent, learning, at) {
-  return decayLearned(decayIntent(getIntentState(state, name, intent), intent, at), learning, at);
+  const is = decayIntent(getIntentState(state, name, intent), intent, at);
+  return settlePending(is, intent, learning, at);
 }
 function cooldownEnd(since, cooldown, at) {
   if (since === null) return null;
@@ -511,6 +555,14 @@ function evaluate(state, intent, at, opts) {
     explanation: buildExplanation(is, config, learning, split.explain)
   };
 }
+function inspect(state, at, opts) {
+  const s = requireState(state);
+  const intents = Object.keys(s.config.intents).map((intent) => ({
+    intent,
+    ...evaluate(s, intent, at, opts)
+  }));
+  return { at, intents };
+}
 
 // src/evidence.ts
 function evidenceToReveal(intent, opts) {
@@ -565,7 +617,7 @@ function observe(state, event) {
     if (!isSignal && !isOutcome) continue;
     let is = getIntentState(s, intentName, intent);
     is = decayIntent(is, intent, at);
-    is = decayLearned(is, learning, at);
+    is = settlePending(is, intent, learning, at);
     if (isSignal) {
       const { effective } = signalWeights(is, intent, learning, name);
       const n = occurrences(episode, intentName, name) + 1;
@@ -575,7 +627,8 @@ function observe(state, event) {
       if (!isOutcome) episode = markSeen(episode, intentName, name);
     }
     if (isOutcome) {
-      is = recordEpisode(is, episodeRecord(episode, intentName).seen, true);
+      is = recordEpisode(is, episodeRecord(episode, intentName).seen, 1);
+      is = creditPending(is, intent, at);
       episode = markResolved(episode, intentName);
       is = { ...is, lastOutcomeAt: at };
       if (intent.resetOnOutcome ?? true) is = resetToPrior(is, intent);
@@ -598,8 +651,8 @@ function closeEpisode(state, at) {
     const record2 = episodeRecord(state.episode, intentName);
     if (record2.resolved) continue;
     let is = getIntentState(state, intentName, intent);
-    is = decayLearned(is, learning, at);
-    is = recordEpisode(is, record2.seen, false);
+    is = settlePending(is, intent, learning, at);
+    is = intent.attribution === void 0 ? recordEpisode(is, record2.seen, 0) : deferEpisode(is, record2.seen, at);
     intents[intentName] = is;
   }
   return { ...state, intents, episode: emptyEpisode() };
@@ -707,7 +760,8 @@ function createEndRecord(at, opts) {
 
 // src/migrate.ts
 var MIGRATIONS = {
-  1: fromV1
+  1: fromV1,
+  2: fromV2
 };
 function canMigrate(version) {
   return hasOwn(MIGRATIONS, String(version));
@@ -738,6 +792,16 @@ function fromV1(stored) {
   }
   return { ...stored, version: 2, episode: { ...episode, intents } };
 }
+function fromV2(stored) {
+  if (!isRecord(stored.intents)) return { ...stored, version: 3 };
+  const intents = {};
+  for (const key of Object.keys(stored.intents)) {
+    if (key === "__proto__") continue;
+    const intent = stored.intents[key];
+    intents[key] = isRecord(intent) ? { ...intent, pending: [] } : intent;
+  }
+  return { ...stored, version: 3, intents };
+}
 
 // src/serialize.ts
 function serialize(state) {
@@ -769,9 +833,11 @@ function deserialize(json, opts = {}) {
   if (parsed.version !== STATE_VERSION) {
     if (canMigrate(parsed.version)) {
       stored = migrateStored(parsed);
+    } else if (parsed.version === STATE_VERSION + 1) {
+      stored = { ...parsed, version: STATE_VERSION };
     } else if (opts.migrate === void 0) {
       throw new RangeError(
-        `oracular: stored state is version ${parsed.version} but this library reads versions 1 to ${STATE_VERSION}; pass a migrate function`
+        `oracular: stored state is version ${parsed.version} but this library reads versions 1 to ${STATE_VERSION + 1}; pass a migrate function`
       );
     } else {
       stored = opts.migrate(parsed, parsed.version);
@@ -824,6 +890,19 @@ function mapOwn(value, path, fn) {
   }
   return out;
 }
+function pendingEpisodes(value, path) {
+  if (!Array.isArray(value)) typeError2(path, "must be an array");
+  if (value.length > MAX_PENDING) {
+    throw new RangeError(`oracular: ${path} must hold at most ${MAX_PENDING} episodes`);
+  }
+  return value.map((item, i) => {
+    const r = record(item, `${path}[${i}]`);
+    if (!Array.isArray(r.seen) || !r.seen.every((s) => typeof s === "string")) {
+      typeError2(`${path}[${i}].seen`, "must be an array of strings");
+    }
+    return { endedAt: finite(r.endedAt, `${path}[${i}].endedAt`), seen: r.seen };
+  });
+}
 function intentState(value, path) {
   const r = record(value, path);
   const revealCount = finite(r.revealCount, `${path}.revealCount`);
@@ -837,6 +916,7 @@ function intentState(value, path) {
     contributions: mapOwn(r.contributions, `${path}.contributions`, contribution),
     learned: mapOwn(r.learned, `${path}.learned`, signalRecord),
     episodes: signalRecord(r.episodes, `${path}.episodes`),
+    pending: pendingEpisodes(r.pending, `${path}.pending`),
     learnedAt: nullOrFinite(r.learnedAt, `${path}.learnedAt`),
     lastRevealedAt: nullOrFinite(r.lastRevealedAt, `${path}.lastRevealedAt`),
     lastOutcomeAt: nullOrFinite(r.lastOutcomeAt, `${path}.lastOutcomeAt`),
@@ -905,6 +985,12 @@ function keep(source, declared) {
   }
   return out;
 }
+function keepPending(pending, signals) {
+  return pending.map((episode) => ({
+    endedAt: episode.endedAt,
+    seen: episode.seen.filter((s, i) => hasOwn(signals, s) && episode.seen.indexOf(s) === i)
+  })).sort((a, b) => a.endedAt - b.endedAt);
+}
 function reconcile(raw, config) {
   const intents = {};
   const episodeIntents = {};
@@ -914,7 +1000,11 @@ function reconcile(raw, config) {
       intents[name] = initIntent(intent);
     } else {
       intents[name] = withContributions(
-        { ...stored, learned: keep(stored.learned, intent.signals) },
+        {
+          ...stored,
+          learned: keep(stored.learned, intent.signals),
+          pending: keepPending(stored.pending, intent.signals)
+        },
         intent,
         keep(stored.contributions, intent.signals)
       );
@@ -955,6 +1045,6 @@ function validateConfig(config) {
   return normalizeConfig(config);
 }
 
-export { RECORD_VERSION, STATE_VERSION, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };
+export { RECORD_VERSION, STATE_VERSION, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, inspect, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map