oracular 0.8.1 → 0.9.0

package/dist/index.d.cts

@@ -62,6 +62,8 @@ interface RevealOptions {
      */
     bound?: 'normal' | 'exact';
 }
+/** The association measure converted to a signed, bounded score when learning signal weights. */
+type LiftType = 'absolute-difference' | 'relative-lift' | 'risk-ratio' | 'log-lift' | 'odds-ratio' | 'normalized-difference' | 'association-rule';
 /**
  * How the engine learns from the user's own outcomes.
  *
@@ -74,9 +76,17 @@ interface RevealOptions {
  * ```
  */
 interface LearningConfig {
+    /**
+     * Optional association measure. Every choice is converted to a score in [−1, 1], neutral at
+     * zero, before learning: ratios use (R − 1)/(R + 1), relative/log lift use x/(1 + |x|), and
+     * absolute/normalized differences keep their scale. Omit to preserve the existing normalized
+     * difference exactly. 'association-rule' uses the overall outcome rate as its baseline; the
+     * others use episodes without the signal. Raw ratios are reporting metrics, never weights.
+     */
+    lift?: LiftType;
     /** Half-life of learned hit/miss counts, in the same unit as `at`. Omit for no forgetting. */
     halfLife?: number;
-    /** A perfectly predictive signal converges to `gain × |initial weight|`. Default 2; at most 1e6. */
+    /** Caps learned magnitude at `gain × |initial weight|` for every lift option. Default 2; at most 1e6. */
     gain?: number;
     /** Pseudo-count behind the developer's initial weight: how many observed episodes it takes to weigh as much as the prior. Default 10; at most 1e6. */
     priorEpisodes?: number;
@@ -847,7 +857,8 @@ declare function deserialize(json: string, opts?: DeserializeOptions): EngineSta
  * Builds a fresh engine state from a config. Every intent starts at its prior and no episode is
  * open. The config is validated and a normalized copy is stored inside the state, so a persisted
  * state remembers the weights it was built with; pass your current config to {@link deserialize}
- * when loading.
+ * when loading. `config.learning.lift` selects the lift formula; omitting it preserves the
+ * normalized difference used by existing configs and states.
  *
  * @param config - Intents with their priors and signals, plus engine-wide options. Validated
  *   strictly: unknown keys, non-finite numbers and out-of-range values throw.
@@ -932,4 +943,4 @@ declare const ms: Units;
  */
 declare function validateConfig(config: unknown): EngineConfig;
 
-export { type DeserializeOptions, type EndRecord, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type EvaluateOptions, type Evaluation, type EventRecord, type ExplainOptions, type IntentConfig, type IntentEvent, type IntentSnapshot, type IntentState, type LearningConfig, type Migrate, type PendingEpisode, type Prediction, type PresetName, type PresetSource, RECORD_VERSION, type RecordMode, type RecordOptions, type RecordedDecision, type RecorderRecord, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, type Snapshot, type Units, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, inspect, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };
+export { type DeserializeOptions, type EndRecord, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type EvaluateOptions, type Evaluation, type EventRecord, type ExplainOptions, type IntentConfig, type IntentEvent, type IntentSnapshot, type IntentState, type LearningConfig, type LiftType, type Migrate, type PendingEpisode, type Prediction, type PresetName, type PresetSource, RECORD_VERSION, type RecordMode, type RecordOptions, type RecordedDecision, type RecorderRecord, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, type Snapshot, type Units, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, inspect, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };

package/dist/index.d.ts

@@ -62,6 +62,8 @@ interface RevealOptions {
      */
     bound?: 'normal' | 'exact';
 }
+/** The association measure converted to a signed, bounded score when learning signal weights. */
+type LiftType = 'absolute-difference' | 'relative-lift' | 'risk-ratio' | 'log-lift' | 'odds-ratio' | 'normalized-difference' | 'association-rule';
 /**
  * How the engine learns from the user's own outcomes.
  *
@@ -74,9 +76,17 @@ interface RevealOptions {
  * ```
  */
 interface LearningConfig {
+    /**
+     * Optional association measure. Every choice is converted to a score in [−1, 1], neutral at
+     * zero, before learning: ratios use (R − 1)/(R + 1), relative/log lift use x/(1 + |x|), and
+     * absolute/normalized differences keep their scale. Omit to preserve the existing normalized
+     * difference exactly. 'association-rule' uses the overall outcome rate as its baseline; the
+     * others use episodes without the signal. Raw ratios are reporting metrics, never weights.
+     */
+    lift?: LiftType;
     /** Half-life of learned hit/miss counts, in the same unit as `at`. Omit for no forgetting. */
     halfLife?: number;
-    /** A perfectly predictive signal converges to `gain × |initial weight|`. Default 2; at most 1e6. */
+    /** Caps learned magnitude at `gain × |initial weight|` for every lift option. Default 2; at most 1e6. */
     gain?: number;
     /** Pseudo-count behind the developer's initial weight: how many observed episodes it takes to weigh as much as the prior. Default 10; at most 1e6. */
     priorEpisodes?: number;
@@ -847,7 +857,8 @@ declare function deserialize(json: string, opts?: DeserializeOptions): EngineSta
  * Builds a fresh engine state from a config. Every intent starts at its prior and no episode is
  * open. The config is validated and a normalized copy is stored inside the state, so a persisted
  * state remembers the weights it was built with; pass your current config to {@link deserialize}
- * when loading.
+ * when loading. `config.learning.lift` selects the lift formula; omitting it preserves the
+ * normalized difference used by existing configs and states.
  *
  * @param config - Intents with their priors and signals, plus engine-wide options. Validated
  *   strictly: unknown keys, non-finite numbers and out-of-range values throw.
@@ -932,4 +943,4 @@ declare const ms: Units;
  */
 declare function validateConfig(config: unknown): EngineConfig;
 
-export { type DeserializeOptions, type EndRecord, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type EvaluateOptions, type Evaluation, type EventRecord, type ExplainOptions, type IntentConfig, type IntentEvent, type IntentSnapshot, type IntentState, type LearningConfig, type Migrate, type PendingEpisode, type Prediction, type PresetName, type PresetSource, RECORD_VERSION, type RecordMode, type RecordOptions, type RecordedDecision, type RecorderRecord, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, type Snapshot, type Units, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, inspect, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };
+export { type DeserializeOptions, type EndRecord, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type EvaluateOptions, type Evaluation, type EventRecord, type ExplainOptions, type IntentConfig, type IntentEvent, type IntentSnapshot, type IntentState, type LearningConfig, type LiftType, type Migrate, type PendingEpisode, type Prediction, type PresetName, type PresetSource, RECORD_VERSION, type RecordMode, type RecordOptions, type RecordedDecision, type RecorderRecord, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, type Snapshot, type Units, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, inspect, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };

package/dist/index.js

@@ -80,10 +80,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) {
@@ -129,7 +158,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);
@@ -255,7 +286,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}`);
@@ -340,6 +380,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`);
@@ -460,6 +506,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