oracular 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.17.0
+
+### Minor Changes
+
+- [#75](https://github.com/Yuribenjamin/oracular/pull/75) [`bdce2bd`](https://github.com/Yuribenjamin/oracular/commit/bdce2bdcffceab6465b08cf1ae1361ec47b8a1bf) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **Six lift measures are deprecated.** 0.9 added `learning.lift` with seven association measures. A sweep of all seven on the clickstream case study found none that beats the default, `'normalized-difference'`, on either split, and 1.0 commits every value in the schema for the whole of 1.x. So `'absolute-difference'`, `'relative-lift'`, `'risk-ratio'`, `'log-lift'`, `'odds-ratio'` and `'association-rule'` are marked `@deprecated` in `LiftType`, named in the JSON Schema's description, and removed in 1.0. Nothing changes in this release: every value keeps working exactly as it did, a config that sets one keeps loading, and the type checker shows the mark. `learning.lift` itself stays, accepting the default, so that a measure can come back as a minor when a real integration shows it should.
+
 ## 0.16.0
 
 ### Minor Changes

package/README.md

@@ -204,15 +204,13 @@ effective = (k × w₀ + nEff × learned) / (k + nEff)            k = priorEpiso
 
 `w₀` is your initial weight, `gain` (default 2) caps the learned magnitude at `gain × |w₀|` for every lift option, and `priorEpisodes` (default 10) is how much contrast it takes for the user's own history to count as much as your guess. A signal's strength and your confidence in it are separate knobs. A signal is judged against the sessions in which it did *not* appear, so for an outcome that happens in 3% of sessions, a signal followed by it 30% of the time is strong evidence, not weak. And learning needs contrast: a signal that has never been absent has no counterfactual, so its weight stands until there are sessions without it. Nothing drifts after a single outcome.
 
-The formula above is the default **normalized difference**. `learning.lift` is an optional
-setting for advanced users who want to choose the learning scale. Choose another at construction with
-`createState({ intents, learning: { lift: 'relative-lift' } })`. Omit `learning.lift` to keep the
-current behavior, including when loading older saved states. The available names and formulas
-are listed in [Episodes & learning](https://yuribenjamin.github.io/oracular/guide/concepts/episodes-and-learning#choosing-a-lift-formula).
-Every choice produces a signed evidence score in [−1, 1], with independence at zero. Ratios use
-`(R − 1) / (R + 1)`, relative/log lift use `x / (1 + |x|)`, and absolute/normalized differences
-keep their scale. Learning uses `gain × |w₀| × score`; `oracular tune` uses the same score for
-weights and intervals and reports raw lift separately when it differs from the score.
+The formula above is the default **normalized difference**. `learning.lift` can name another
+association measure (`'relative-lift'`, `'risk-ratio'`, `'log-lift'`, `'odds-ratio'`,
+`'absolute-difference'`, `'association-rule'`), each converted to a signed evidence score in
+[−1, 1] with independence at zero, as [Episodes & learning](https://yuribenjamin.github.io/oracular/guide/concepts/episodes-and-learning#choosing-a-lift-formula)
+lists. **Those six are deprecated and removed in 1.0:** a sweep of all seven on the clickstream
+case study found none that beats the default on either split. They keep working until then; omit
+`learning.lift`, or set the default, and nothing changes.
 
 Learned counts never decay unless you set `learning.halfLife`.
 

package/dist/index.d.cts

@@ -69,8 +69,25 @@ 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';
+/**
+ * The association measure converted to a signed, bounded score when learning signal weights.
+ * Every value but the default, `'normalized-difference'`, is deprecated: a sweep of all seven on
+ * the clickstream case study found none that beats the default on either split, so the six are
+ * removed in 1.0. They keep working, unchanged, until then; `learning.lift` itself stays.
+ */
+type LiftType = 
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+'absolute-difference'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'relative-lift'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'risk-ratio'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'log-lift'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'odds-ratio' | 'normalized-difference'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'association-rule';
 /**
  * How the engine learns from the user's own outcomes.
  *
@@ -89,6 +106,7 @@ interface LearningConfig {
      * 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.
+     * Every value but the default is deprecated and removed in 1.0 (see {@link LiftType}).
      */
     lift?: LiftType;
     /** Half-life of learned hit/miss counts, in the same unit as `at`. Omit for no forgetting. */

package/dist/index.d.ts

@@ -69,8 +69,25 @@ 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';
+/**
+ * The association measure converted to a signed, bounded score when learning signal weights.
+ * Every value but the default, `'normalized-difference'`, is deprecated: a sweep of all seven on
+ * the clickstream case study found none that beats the default on either split, so the six are
+ * removed in 1.0. They keep working, unchanged, until then; `learning.lift` itself stays.
+ */
+type LiftType = 
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+'absolute-difference'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'relative-lift'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'risk-ratio'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'log-lift'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'odds-ratio' | 'normalized-difference'
+/** @deprecated Removed in 1.0: use the default, `'normalized-difference'`. */
+ | 'association-rule';
 /**
  * How the engine learns from the user's own outcomes.
  *
@@ -89,6 +106,7 @@ interface LearningConfig {
      * 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.
+     * Every value but the default is deprecated and removed in 1.0 (see {@link LiftType}).
      */
     lift?: LiftType;
     /** Half-life of learned hit/miss counts, in the same unit as `at`. Omit for no forgetting. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oracular",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "On-device intent engine. Your app learns when the user is ready. Nothing leaves the device.",
   "keywords": [
     "oracular",

package/schema/config.schema.json

@@ -165,7 +165,7 @@
             "normalized-difference",
             "association-rule"
           ],
-          "description": "Association measure, converted to an evidence score in [-1, 1], neutral at zero. Ratios use (R - 1)/(R + 1), relative/log lift use x/(1 + abs(x)), and absolute/normalized differences keep their scale. Default normalized-difference preserves existing behavior. Association-rule compares with the overall outcome rate."
+          "description": "Association measure, converted to an evidence score in [-1, 1], neutral at zero. Ratios use (R - 1)/(R + 1), relative/log lift use x/(1 + abs(x)), and absolute/normalized differences keep their scale. Default normalized-difference preserves existing behavior. Association-rule compares with the overall outcome rate. Every value but normalized-difference is deprecated and removed in 1.0: a sweep of all seven on the clickstream case study found none that beats the default on either split."
         }
       }
     }