oracular 0.2.1 → 0.4.0

package/dist/index.cjs

@@ -20,6 +20,9 @@ function clamp01(x) {
   if (x > 1) return 1;
   return x;
 }
+function repeatFactor(n) {
+  return Math.log1p(1 / n) / Math.LN2;
+}
 function laplace(successes, total) {
   return (successes + 1) / (total + 2);
 }
@@ -145,6 +148,7 @@ var DEFAULT_THRESHOLD = 0.5;
 var DEFAULT_Z = 1.28;
 var DEFAULT_GAIN = 2;
 var DEFAULT_PRIOR_EPISODES = 10;
+var MAX_MAGNITUDE = 1e6;
 var CONFIG_KEYS = ["intents", "episodeTimeout", "learning", "reveal"];
 var INTENT_KEYS = [
   "prior",
@@ -153,6 +157,7 @@ var INTENT_KEYS = [
   "signals",
   "outcome",
   "resetOnOutcome",
+  "saturate",
   "reveal"
 ];
 var REVEAL_KEYS = ["threshold", "z", "cooldown"];
@@ -188,6 +193,11 @@ function expectPositive(value, path) {
   if (n <= 0) rangeError(path, "must be greater than 0");
   return n;
 }
+function expectBoundedPositive(value, path) {
+  const n = expectPositive(value, path);
+  if (n > MAX_MAGNITUDE) rangeError(path, `must be at most ${MAX_MAGNITUDE}`);
+  return n;
+}
 function expectNonNegative(value, path) {
   const n = expectNumber(value, path);
   if (n < 0) rangeError(path, "must be 0 or greater");
@@ -232,9 +242,9 @@ function normalizeLearning(value, path) {
   const out = {};
   if (record2.halfLife !== void 0)
     out.halfLife = expectPositive(record2.halfLife, `${path}.halfLife`);
-  if (record2.gain !== void 0) out.gain = expectPositive(record2.gain, `${path}.gain`);
+  if (record2.gain !== void 0) out.gain = expectBoundedPositive(record2.gain, `${path}.gain`);
   if (record2.priorEpisodes !== void 0) {
-    out.priorEpisodes = expectPositive(record2.priorEpisodes, `${path}.priorEpisodes`);
+    out.priorEpisodes = expectBoundedPositive(record2.priorEpisodes, `${path}.priorEpisodes`);
   }
   return out;
 }
@@ -252,11 +262,17 @@ function normalizeIntentConfig(value, path) {
         "must be non-zero (positive is evidence for the intent, negative is evidence against)"
       );
     }
+    if (Math.abs(w) > MAX_MAGNITUDE) {
+      rangeError(
+        `${path}.signals[${JSON.stringify(name)}]`,
+        `must be between -${MAX_MAGNITUDE} and ${MAX_MAGNITUDE}`
+      );
+    }
     signals[name] = w;
   }
   const out = {
     prior: expectOpenUnit(record2.prior, `${path}.prior`),
-    priorStrength: expectPositive(record2.priorStrength, `${path}.priorStrength`),
+    priorStrength: expectBoundedPositive(record2.priorStrength, `${path}.priorStrength`),
     halfLife: expectPositive(record2.halfLife, `${path}.halfLife`),
     signals
   };
@@ -267,6 +283,10 @@ function normalizeIntentConfig(value, path) {
     }
     out.resetOnOutcome = record2.resetOnOutcome;
   }
+  if (record2.saturate !== void 0) {
+    if (typeof record2.saturate !== "boolean") typeError(`${path}.saturate`, "must be a boolean");
+    out.saturate = record2.saturate;
+  }
   if (record2.reveal !== void 0)
     out.reveal = normalizeRevealOptions(record2.reveal, `${path}.reveal`);
   return out;
@@ -370,22 +390,27 @@ function extendEpisode(episode, at) {
   };
 }
 function episodeRecord(episode, intent) {
-  return getOwn(episode.intents, intent) ?? { seen: [], resolved: false };
+  return getOwn(episode.intents, intent) ?? { seen: [], counts: {}, resolved: false };
+}
+function occurrences(episode, intent, signal) {
+  return getOwn(episodeRecord(episode, intent).counts, signal) ?? 0;
 }
 function markSeen(episode, intent, signal) {
   const record2 = episodeRecord(episode, intent);
-  if (record2.seen.includes(signal)) return episode;
+  const seen = record2.seen.includes(signal) ? record2.seen : [...record2.seen, signal];
+  const counts = { ...record2.counts, [signal]: (getOwn(record2.counts, signal) ?? 0) + 1 };
+  return { ...episode, intents: { ...episode.intents, [intent]: { ...record2, seen, counts } } };
+}
+function markResolved(episode, intent) {
   return {
     ...episode,
-    intents: { ...episode.intents, [intent]: { ...record2, seen: [...record2.seen, signal] } }
+    intents: { ...episode.intents, [intent]: { seen: [], counts: {}, resolved: true } }
   };
 }
-function markResolved(episode, intent) {
-  return { ...episode, intents: { ...episode.intents, [intent]: { seen: [], resolved: true } } };
-}
 
 // src/version.ts
-var STATE_VERSION = 1;
+var STATE_VERSION = 2;
+var RECORD_VERSION = 1;
 
 // src/state.ts
 function createState(config) {
@@ -545,7 +570,10 @@ function observe(state, event) {
     is = decayLearned(is, learning, at);
     if (isSignal) {
       const { effective } = signalWeights(is, intent, learning, name);
-      is = applySignal(is, intent, name, effective);
+      const n = occurrences(episode, intentName, name) + 1;
+      const saturate = intent.saturate ?? s.config.episodeTimeout !== void 0;
+      const factor = saturate ? repeatFactor(n) : 1;
+      is = applySignal(is, intent, name, effective * factor);
       if (!isOutcome) episode = markSeen(episode, intentName, name);
     }
     if (isOutcome) {
@@ -616,6 +644,103 @@ function markRevealed(state, intent, at) {
   };
 }
 
+// src/recorder.ts
+var RECORD_KEYS = ["installId", "mode", "top"];
+var DEFAULT_TOP = 3;
+function normalizeRecordOptions(value) {
+  if (!isRecord(value)) {
+    throw new TypeError("oracular: options must be an object like { installId, mode }");
+  }
+  for (const key of Object.keys(value)) {
+    if (!RECORD_KEYS.includes(key)) {
+      throw new TypeError(
+        `oracular: options.${key} is not a recognised option (expected one of: ${RECORD_KEYS.join(", ")})`
+      );
+    }
+  }
+  const installId = expectName(value.installId, "options.installId");
+  const mode = value.mode;
+  if (mode !== "shadow" && mode !== "live") {
+    throw new TypeError('oracular: options.mode must be "shadow" or "live"');
+  }
+  let top = DEFAULT_TOP;
+  if (value.top !== void 0) {
+    if (typeof value.top !== "number" || !Number.isFinite(value.top)) {
+      throw new TypeError("oracular: options.top must be a finite number");
+    }
+    if (!Number.isInteger(value.top) || value.top < 0) {
+      throw new RangeError("oracular: options.top must be a non-negative integer");
+    }
+    top = value.top;
+  }
+  return { installId, mode, top };
+}
+function createRecord(state, event, opts) {
+  const s = requireState(state);
+  const { name, at } = validateEvent(event);
+  const { installId, mode, top } = normalizeRecordOptions(opts);
+  const learning = resolveLearning(s.config);
+  const decisions = {};
+  for (const [intentName, intent] of Object.entries(s.config.intents)) {
+    const reveal = resolveReveal(s.config, intent, void 0);
+    const is = assessIntent(s, intentName, intent, learning, at);
+    const prediction = buildPrediction(is, intentName, reveal, at);
+    const rows = buildExplanation(is, intent, learning, {});
+    const weights = {};
+    for (const signal of Object.keys(intent.signals)) {
+      weights[signal] = rows.find((row) => row.signal === signal).effectiveWeight;
+    }
+    decisions[intentName] = {
+      p: prediction.p,
+      lower: prediction.lower,
+      shouldReveal: decideReveal(prediction, reveal),
+      suppressedUntil: prediction.suppressedUntil,
+      top: rows.filter((row) => row.contribution !== 0).slice(0, top).map((row) => ({ signal: row.signal, impact: row.impact })),
+      weights
+    };
+  }
+  return { v: RECORD_VERSION, kind: "event", installId, mode, event: { name, at }, decisions };
+}
+function createEndRecord(at, opts) {
+  const t = expectTimestamp(at, "at");
+  const { installId, mode } = normalizeRecordOptions(opts);
+  return { v: RECORD_VERSION, kind: "end", installId, mode, at: t };
+}
+
+// src/migrate.ts
+var MIGRATIONS = {
+  1: fromV1
+};
+function canMigrate(version) {
+  return hasOwn(MIGRATIONS, String(version));
+}
+function migrateStored(stored) {
+  let current = stored;
+  while (typeof current.version === "number" && canMigrate(current.version)) {
+    current = MIGRATIONS[current.version](current);
+  }
+  return current;
+}
+function fromV1(stored) {
+  const episode = stored.episode;
+  if (!isRecord(episode) || !isRecord(episode.intents)) return { ...stored, version: 2 };
+  const intents = {};
+  for (const key of Object.keys(episode.intents)) {
+    if (key === "__proto__") continue;
+    const record2 = episode.intents[key];
+    if (isRecord(record2) && Array.isArray(record2.seen)) {
+      const counts = {};
+      for (const signal of record2.seen) {
+        if (typeof signal === "string" && signal !== "__proto__") counts[signal] = 1;
+      }
+      intents[key] = { ...record2, counts };
+    } else {
+      intents[key] = record2;
+    }
+  }
+  return { ...stored, version: 2, episode: { ...episode, intents } };
+}
+
 // src/serialize.ts
 function serialize(state) {
   return JSON.stringify(requireState(state));
@@ -644,16 +769,19 @@ function deserialize(json, opts = {}) {
   }
   let stored = parsed;
   if (parsed.version !== STATE_VERSION) {
-    if (opts.migrate === void 0) {
+    if (canMigrate(parsed.version)) {
+      stored = migrateStored(parsed);
+    } else if (opts.migrate === void 0) {
       throw new RangeError(
-        `oracular: stored state is version ${parsed.version} but this library reads version ${STATE_VERSION}; pass a migrate function`
+        `oracular: stored state is version ${parsed.version} but this library reads versions 1 to ${STATE_VERSION}; pass a migrate function`
       );
+    } else {
+      stored = opts.migrate(parsed, parsed.version);
     }
-    stored = opts.migrate(parsed, parsed.version);
   }
   const raw = parseState(stored);
   const config = opts.config === void 0 ? raw.config : normalizeConfig(opts.config);
-  return reconcile(raw, config);
+  return requireComputable(reconcile(raw, config));
 }
 function typeError2(path, message) {
   throw new TypeError(`oracular: ${path} ${message}`);
@@ -717,13 +845,21 @@ function intentState(value, path) {
     revealCount
   };
 }
+function occurrenceCount(value, path) {
+  const n = finite(value, path);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new RangeError(`oracular: ${path} must be a positive integer`);
+  }
+  return n;
+}
 function episodeIntent(value, path) {
   const r = record(value, path);
   if (!Array.isArray(r.seen) || !r.seen.every((s) => typeof s === "string")) {
     typeError2(`${path}.seen`, "must be an array of strings");
   }
+  const counts = mapOwn(r.counts, `${path}.counts`, occurrenceCount);
   if (typeof r.resolved !== "boolean") typeError2(`${path}.resolved`, "must be a boolean");
-  return { seen: r.seen, resolved: r.resolved };
+  return { seen: r.seen, counts, resolved: r.resolved };
 }
 function episodeState(value, path) {
   const r = record(value, path);
@@ -745,6 +881,25 @@ function parseState(value) {
     episode: episodeState(r.episode, "state.episode")
   };
 }
+function requireComputable(state) {
+  const learning = resolveLearning(state.config);
+  for (const [name, intent] of Object.entries(state.config.intents)) {
+    const is = state.intents[name];
+    const path = `state.intents[${JSON.stringify(name)}]`;
+    if (!Number.isFinite(is.alpha + is.beta) || !Number.isFinite(is.alpha * is.beta)) {
+      throw new RangeError(`oracular: ${path} holds more evidence than can be computed with`);
+    }
+    for (const signal of Object.keys(intent.signals)) {
+      const w = signalWeights(is, intent, learning, signal);
+      if (!Number.isFinite(w.learned) || !Number.isFinite(w.effective)) {
+        throw new RangeError(
+          `oracular: ${path} holds learned counts for ${JSON.stringify(signal)} too large to compute with`
+        );
+      }
+    }
+  }
+  return state;
+}
 function keep(source, declared) {
   const out = {};
   for (const [key, value] of Object.entries(source)) {
@@ -771,7 +926,9 @@ function reconcile(raw, config) {
       const seen = episode.seen.filter(
         (s, i) => hasOwn(intent.signals, s) && episode.seen.indexOf(s) === i
       );
-      episodeIntents[name] = { seen, resolved: episode.resolved };
+      const counts = {};
+      for (const s of seen) counts[s] = getOwn(episode.counts, s) ?? 1;
+      episodeIntents[name] = { seen, counts, resolved: episode.resolved };
     }
   }
   return {
@@ -786,7 +943,24 @@ function reconcile(raw, config) {
   };
 }
 
+// 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/validate.ts
+function validateConfig(config) {
+  return normalizeConfig(config);
+}
+
+exports.RECORD_VERSION = RECORD_VERSION;
 exports.STATE_VERSION = STATE_VERSION;
+exports.createEndRecord = createEndRecord;
+exports.createRecord = createRecord;
 exports.createState = createState;
 exports.deserialize = deserialize;
 exports.endEpisode = endEpisode;
@@ -795,9 +969,11 @@ exports.evaluate = evaluate;
 exports.evidenceToReveal = evidenceToReveal;
 exports.explain = explain;
 exports.markRevealed = markRevealed;
+exports.ms = ms;
 exports.observe = observe;
 exports.predict = predict;
 exports.serialize = serialize;
 exports.shouldReveal = shouldReveal;
+exports.validateConfig = validateConfig;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map