@logg/signals 0.3.0 → 0.4.0

package/README.md

@@ -522,9 +522,30 @@ Methods shared by both engines: `prime()`, `engage()`, `recommend()`,
 `setOwned()`, `clearSeen()`, `reset()`, `seenCount()`. The dual engine adds
 `setSampleSize(k)` to tune explore vs. exploit.
 
+### Weighted scoring (dual engine) — `0.4.0`
+
+By default `DualBucketRecommender` ranks candidates by the sum of raw slot
+powers, which ignores each feature's schema `weight` and lets a
+low-cardinality feature (e.g. one dominant `category`) outweigh a
+high-cardinality one (e.g. `brand`) purely by accumulated mass. Pass
+`weightedScoring: true` to instead weight each feature by its schema `weight`
+and normalize a value's power to its share of the bucket (an ε-floored share,
+the same scheme the v1 engine uses):
+
+```typescript
+const reco = new DualBucketRecommender(catalog, { schema, weightedScoring: true });
+```
+
+This makes schema weights authoritative and removes the cardinality bias. It
+is **off by default** to preserve existing v2 ranking. Note the scale change:
+with the flag on, `net` / `diagnostics.bestNet` move from unbounded raw power
+to roughly `[−Σweight, +Σweight]` (≈ `[−1, 1]` when weights sum to 1), so any
+consumer comparing `bestNet` against a raw-power threshold must rescale.
+
 Advanced primitives (slot tables, interest state, bucket admission, the
-weighted sampler, and `seededRng` for deterministic tests) are exported from
-the same entry for callers building custom pipelines or CLIs on top.
+weighted sampler, the dual-bucket `bucketContribution`, and `seededRng` for
+deterministic tests) are exported from the same entry for callers building
+custom pipelines or CLIs on top.
 
 ## License
 

package/dist/reco.d.mts

@@ -39,7 +39,7 @@ interface SlotTableState {
 declare function emptyState(): SlotTableState;
 declare function observe(state: SlotTableState, value: string, weight: number, config?: SlotTableConfig): void;
 declare function decay(state: SlotTableState, factor: number): void;
-declare function contribution(state: SlotTableState, value: string | null, config?: SlotTableConfig): number;
+declare function contribution$1(state: SlotTableState, value: string | null, config?: SlotTableConfig): number;
 declare function isEmpty$1(state: SlotTableState): boolean;
 
 interface InterestConfig<T extends BaseItem> {
@@ -125,10 +125,12 @@ interface BucketConfig {
 declare function emptyBucket(): BucketState;
 declare function admit(state: BucketState, value: string, score: number, config?: BucketConfig): void;
 declare function powerOf(state: BucketState, value: string | null): number;
+declare function contribution(state: BucketState, value: string | null, epsilon: number): number;
 declare function isEmpty(state: BucketState): boolean;
 
 interface DualInterestConfig<T extends BaseItem> {
     schema: Schema<T>;
+    weightedScoring?: boolean;
 }
 interface DualBucketState {
     liked: Record<string, BucketState>;
@@ -160,6 +162,7 @@ interface DualRecommenderConfig<T extends BaseItem> {
     schema: Schema<T>;
     sampleSize?: number;
     shuffleThreshold?: number;
+    weightedScoring?: boolean;
     rng?: RNG;
 }
 interface ResolvedConfig<T extends BaseItem> {
@@ -213,4 +216,4 @@ declare class DualBucketRecommender<T extends BaseItem> {
 declare function logDecadeBucket(value: number | null, multiplier?: number, prefix?: string): string | null;
 declare function yearBucket(year: number | null, bandSize?: number): string | null;
 
-export { type BaseItem, type BucketConfig, type BucketState, DEFAULT_CAPACITY, DEFAULT_DECREMENT_CAP, DEFAULT_EPSILON, DEFAULT_INTEREST_CONFIG, DEFAULT_SLOT_CONFIG, DualBucketRecommender, type DualBucketState, type DualInterestConfig, type ItemScore as DualItemScore, type DualRecommendDiagnostics, type DualRecommendResult, type DualRecommenderConfig, type FeatureConfig, type InterestConfig, type InterestState, type RNG, type RecommendDiagnostics, type RecommendResult, Recommender, type RecommenderConfig, SIGNALS, type Schema, type SignalName, type Slot, type SlotTableConfig, type SlotTableState, admit, applyEvent, contribution, decay, defaultRng, describe$1 as describe, describe as describeDual, emptyBucket, emptyDualState, emptyInterest, emptyState, engageNegative, engagePositive, isCold$1 as isCold, isCold as isColdDual, isEmpty$1 as isEmpty, isEmpty as isEmptyBucket, logDecadeBucket, observe, powerOf, scoreItem$1 as scoreItem, scoreItem as scoreItemDual, seededRng, weightedSampleWithoutReplacement, yearBucket };
+export { type BaseItem, type BucketConfig, type BucketState, DEFAULT_CAPACITY, DEFAULT_DECREMENT_CAP, DEFAULT_EPSILON, DEFAULT_INTEREST_CONFIG, DEFAULT_SLOT_CONFIG, DualBucketRecommender, type DualBucketState, type DualInterestConfig, type ItemScore as DualItemScore, type DualRecommendDiagnostics, type DualRecommendResult, type DualRecommenderConfig, type FeatureConfig, type InterestConfig, type InterestState, type RNG, type RecommendDiagnostics, type RecommendResult, Recommender, type RecommenderConfig, SIGNALS, type Schema, type SignalName, type Slot, type SlotTableConfig, type SlotTableState, admit, applyEvent, contribution as bucketContribution, contribution$1 as contribution, decay, defaultRng, describe$1 as describe, describe as describeDual, emptyBucket, emptyDualState, emptyInterest, emptyState, engageNegative, engagePositive, isCold$1 as isCold, isCold as isColdDual, isEmpty$1 as isEmpty, isEmpty as isEmptyBucket, logDecadeBucket, observe, powerOf, scoreItem$1 as scoreItem, scoreItem as scoreItemDual, seededRng, weightedSampleWithoutReplacement, yearBucket };

package/dist/reco.d.ts

@@ -39,7 +39,7 @@ interface SlotTableState {
 declare function emptyState(): SlotTableState;
 declare function observe(state: SlotTableState, value: string, weight: number, config?: SlotTableConfig): void;
 declare function decay(state: SlotTableState, factor: number): void;
-declare function contribution(state: SlotTableState, value: string | null, config?: SlotTableConfig): number;
+declare function contribution$1(state: SlotTableState, value: string | null, config?: SlotTableConfig): number;
 declare function isEmpty$1(state: SlotTableState): boolean;
 
 interface InterestConfig<T extends BaseItem> {
@@ -125,10 +125,12 @@ interface BucketConfig {
 declare function emptyBucket(): BucketState;
 declare function admit(state: BucketState, value: string, score: number, config?: BucketConfig): void;
 declare function powerOf(state: BucketState, value: string | null): number;
+declare function contribution(state: BucketState, value: string | null, epsilon: number): number;
 declare function isEmpty(state: BucketState): boolean;
 
 interface DualInterestConfig<T extends BaseItem> {
     schema: Schema<T>;
+    weightedScoring?: boolean;
 }
 interface DualBucketState {
     liked: Record<string, BucketState>;
@@ -160,6 +162,7 @@ interface DualRecommenderConfig<T extends BaseItem> {
     schema: Schema<T>;
     sampleSize?: number;
     shuffleThreshold?: number;
+    weightedScoring?: boolean;
     rng?: RNG;
 }
 interface ResolvedConfig<T extends BaseItem> {
@@ -213,4 +216,4 @@ declare class DualBucketRecommender<T extends BaseItem> {
 declare function logDecadeBucket(value: number | null, multiplier?: number, prefix?: string): string | null;
 declare function yearBucket(year: number | null, bandSize?: number): string | null;
 
-export { type BaseItem, type BucketConfig, type BucketState, DEFAULT_CAPACITY, DEFAULT_DECREMENT_CAP, DEFAULT_EPSILON, DEFAULT_INTEREST_CONFIG, DEFAULT_SLOT_CONFIG, DualBucketRecommender, type DualBucketState, type DualInterestConfig, type ItemScore as DualItemScore, type DualRecommendDiagnostics, type DualRecommendResult, type DualRecommenderConfig, type FeatureConfig, type InterestConfig, type InterestState, type RNG, type RecommendDiagnostics, type RecommendResult, Recommender, type RecommenderConfig, SIGNALS, type Schema, type SignalName, type Slot, type SlotTableConfig, type SlotTableState, admit, applyEvent, contribution, decay, defaultRng, describe$1 as describe, describe as describeDual, emptyBucket, emptyDualState, emptyInterest, emptyState, engageNegative, engagePositive, isCold$1 as isCold, isCold as isColdDual, isEmpty$1 as isEmpty, isEmpty as isEmptyBucket, logDecadeBucket, observe, powerOf, scoreItem$1 as scoreItem, scoreItem as scoreItemDual, seededRng, weightedSampleWithoutReplacement, yearBucket };
+export { type BaseItem, type BucketConfig, type BucketState, DEFAULT_CAPACITY, DEFAULT_DECREMENT_CAP, DEFAULT_EPSILON, DEFAULT_INTEREST_CONFIG, DEFAULT_SLOT_CONFIG, DualBucketRecommender, type DualBucketState, type DualInterestConfig, type ItemScore as DualItemScore, type DualRecommendDiagnostics, type DualRecommendResult, type DualRecommenderConfig, type FeatureConfig, type InterestConfig, type InterestState, type RNG, type RecommendDiagnostics, type RecommendResult, Recommender, type RecommenderConfig, SIGNALS, type Schema, type SignalName, type Slot, type SlotTableConfig, type SlotTableState, admit, applyEvent, contribution as bucketContribution, contribution$1 as contribution, decay, defaultRng, describe$1 as describe, describe as describeDual, emptyBucket, emptyDualState, emptyInterest, emptyState, engageNegative, engagePositive, isCold$1 as isCold, isCold as isColdDual, isEmpty$1 as isEmpty, isEmpty as isEmptyBucket, logDecadeBucket, observe, powerOf, scoreItem$1 as scoreItem, scoreItem as scoreItemDual, seededRng, weightedSampleWithoutReplacement, yearBucket };

package/dist/reco.js

@@ -30,6 +30,7 @@ __export(reco_exports, {
   SIGNALS: () => SIGNALS,
   admit: () => admit,
   applyEvent: () => applyEvent,
+  bucketContribution: () => contribution2,
   contribution: () => contribution,
   decay: () => decay,
   defaultRng: () => defaultRng,
@@ -406,6 +407,14 @@ function powerOf(state, value) {
   const slot = state.slots.find((s) => s.value === value);
   return slot ? slot.power : 0;
 }
+function contribution2(state, value, epsilon) {
+  if (!value) return epsilon;
+  const slot = state.slots.find((s) => s.value === value);
+  if (!slot) return epsilon;
+  const total = state.slots.reduce((sum, s) => sum + s.power, 0);
+  if (total <= 0) return epsilon;
+  return epsilon + (1 - epsilon) * (slot.power / total);
+}
 function isEmpty2(state) {
   return state.slots.length === 0;
 }
@@ -445,14 +454,31 @@ function engageNegative(state, item, magnitude, config) {
   if (!Number.isFinite(magnitude) || magnitude <= 0) return;
   admitAcrossFeatures(state, "disliked", item, magnitude, config.schema);
 }
+function featureWeight2(fc, featureCount) {
+  if (typeof fc.weight === "number") return fc.weight;
+  return featureCount > 0 ? 1 / featureCount : 0;
+}
+function epsilonOf(fc) {
+  return fc.epsilon ?? DEFAULT_EPSILON;
+}
 function scoreItem2(state, item, config) {
   let liked = 0;
   let disliked = 0;
   const byFeature = [];
-  for (const [key, fc] of Object.entries(config.schema)) {
+  const entries = Object.entries(config.schema);
+  for (const [key, fc] of entries) {
     const value = fc.extract(item);
-    const l = powerOf(state.liked[key], value);
-    const d = powerOf(state.disliked[key], value);
+    let l;
+    let d;
+    if (config.weightedScoring) {
+      const w = featureWeight2(fc, entries.length);
+      const eps = epsilonOf(fc);
+      l = w * contribution2(state.liked[key], value, eps);
+      d = w * contribution2(state.disliked[key], value, eps);
+    } else {
+      l = powerOf(state.liked[key], value);
+      d = powerOf(state.disliked[key], value);
+    }
     liked += l;
     disliked += d;
     byFeature.push({ key, value, liked: l, disliked: d });
@@ -479,7 +505,7 @@ function describe2(state, top = 4) {
 // src/reco/dual-bucket/recommender.ts
 function resolve2(input) {
   return {
-    interest: { schema: input.schema },
+    interest: { schema: input.schema, weightedScoring: input.weightedScoring ?? false },
     // 100 is a heavy exploit setting; drop to 20–30 if exploration feels
     // weak. Live-tunable via setSampleSize().
     sampleSize: input.sampleSize ?? 100,
@@ -633,6 +659,7 @@ function yearBucket(year, bandSize = 5) {
   SIGNALS,
   admit,
   applyEvent,
+  bucketContribution,
   contribution,
   decay,
   defaultRng,

package/dist/reco.mjs

@@ -350,6 +350,14 @@ function powerOf(state, value) {
   const slot = state.slots.find((s) => s.value === value);
   return slot ? slot.power : 0;
 }
+function contribution2(state, value, epsilon) {
+  if (!value) return epsilon;
+  const slot = state.slots.find((s) => s.value === value);
+  if (!slot) return epsilon;
+  const total = state.slots.reduce((sum, s) => sum + s.power, 0);
+  if (total <= 0) return epsilon;
+  return epsilon + (1 - epsilon) * (slot.power / total);
+}
 function isEmpty2(state) {
   return state.slots.length === 0;
 }
@@ -389,14 +397,31 @@ function engageNegative(state, item, magnitude, config) {
   if (!Number.isFinite(magnitude) || magnitude <= 0) return;
   admitAcrossFeatures(state, "disliked", item, magnitude, config.schema);
 }
+function featureWeight2(fc, featureCount) {
+  if (typeof fc.weight === "number") return fc.weight;
+  return featureCount > 0 ? 1 / featureCount : 0;
+}
+function epsilonOf(fc) {
+  return fc.epsilon ?? DEFAULT_EPSILON;
+}
 function scoreItem2(state, item, config) {
   let liked = 0;
   let disliked = 0;
   const byFeature = [];
-  for (const [key, fc] of Object.entries(config.schema)) {
+  const entries = Object.entries(config.schema);
+  for (const [key, fc] of entries) {
     const value = fc.extract(item);
-    const l = powerOf(state.liked[key], value);
-    const d = powerOf(state.disliked[key], value);
+    let l;
+    let d;
+    if (config.weightedScoring) {
+      const w = featureWeight2(fc, entries.length);
+      const eps = epsilonOf(fc);
+      l = w * contribution2(state.liked[key], value, eps);
+      d = w * contribution2(state.disliked[key], value, eps);
+    } else {
+      l = powerOf(state.liked[key], value);
+      d = powerOf(state.disliked[key], value);
+    }
     liked += l;
     disliked += d;
     byFeature.push({ key, value, liked: l, disliked: d });
@@ -423,7 +448,7 @@ function describe2(state, top = 4) {
 // src/reco/dual-bucket/recommender.ts
 function resolve2(input) {
   return {
-    interest: { schema: input.schema },
+    interest: { schema: input.schema, weightedScoring: input.weightedScoring ?? false },
     // 100 is a heavy exploit setting; drop to 20–30 if exploration feels
     // weak. Live-tunable via setSampleSize().
     sampleSize: input.sampleSize ?? 100,
@@ -576,6 +601,7 @@ export {
   SIGNALS,
   admit,
   applyEvent,
+  contribution2 as bucketContribution,
   contribution,
   decay,
   defaultRng,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logg/signals",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Universal event tracking SDK for Logg Signals, with an embeddable on-device recommender",
   "main": "dist/index.js",
   "module": "dist/index.mjs",