@logg/signals 0.1.5 → 0.3.0

package/dist/reco.js

@@ -0,0 +1,659 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/reco/index.ts
+var reco_exports = {};
+__export(reco_exports, {
+  DEFAULT_CAPACITY: () => DEFAULT_CAPACITY,
+  DEFAULT_DECREMENT_CAP: () => DEFAULT_DECREMENT_CAP,
+  DEFAULT_EPSILON: () => DEFAULT_EPSILON,
+  DEFAULT_INTEREST_CONFIG: () => DEFAULT_INTEREST_CONFIG,
+  DEFAULT_SLOT_CONFIG: () => DEFAULT_SLOT_CONFIG,
+  DualBucketRecommender: () => DualBucketRecommender,
+  Recommender: () => Recommender,
+  SIGNALS: () => SIGNALS,
+  admit: () => admit,
+  applyEvent: () => applyEvent,
+  contribution: () => contribution,
+  decay: () => decay,
+  defaultRng: () => defaultRng,
+  describe: () => describe,
+  describeDual: () => describe2,
+  emptyBucket: () => emptyBucket,
+  emptyDualState: () => emptyDualState,
+  emptyInterest: () => emptyInterest,
+  emptyState: () => emptyState,
+  engageNegative: () => engageNegative,
+  engagePositive: () => engagePositive,
+  isCold: () => isCold,
+  isColdDual: () => isCold2,
+  isEmpty: () => isEmpty,
+  isEmptyBucket: () => isEmpty2,
+  logDecadeBucket: () => logDecadeBucket,
+  observe: () => observe,
+  powerOf: () => powerOf,
+  scoreItem: () => scoreItem,
+  scoreItemDual: () => scoreItem2,
+  seededRng: () => seededRng,
+  weightedSampleWithoutReplacement: () => weightedSampleWithoutReplacement,
+  yearBucket: () => yearBucket
+});
+module.exports = __toCommonJS(reco_exports);
+
+// src/reco/types.ts
+var DEFAULT_CAPACITY = 3;
+var DEFAULT_DECREMENT_CAP = 4;
+var DEFAULT_EPSILON = 0.1;
+var SIGNALS = {
+  view: 0.5,
+  click: 2,
+  dwell: 3,
+  collect: 8,
+  skip: -1
+};
+
+// src/reco/slots.ts
+var DEFAULT_SLOT_CONFIG = {
+  capacity: DEFAULT_CAPACITY,
+  challengerCapacity: DEFAULT_CAPACITY * 2,
+  epsilon: DEFAULT_EPSILON
+};
+function emptyState() {
+  return { slots: [], challengers: [] };
+}
+function reorder(arr) {
+  arr.sort((a, b) => b.power - a.power || a.value.localeCompare(b.value));
+}
+function observe(state, value, weight, config = DEFAULT_SLOT_CONFIG) {
+  if (!value) return;
+  const slot = state.slots.find((s) => s.value === value);
+  if (slot) {
+    slot.power = Math.max(0, slot.power + weight);
+    if (slot.power === 0) {
+      state.slots = state.slots.filter((s) => s !== slot);
+    }
+    reorder(state.slots);
+    return;
+  }
+  if (weight <= 0) return;
+  const challenger = state.challengers.find((c) => c.value === value);
+  if (challenger) {
+    challenger.power += weight;
+  } else {
+    state.challengers.push({ value, power: weight });
+  }
+  reorder(state.challengers);
+  if (state.challengers.length > config.challengerCapacity) {
+    state.challengers.length = config.challengerCapacity;
+  }
+  if (state.slots.length < config.capacity) {
+    const top2 = state.challengers.shift();
+    if (top2) {
+      state.slots.push(top2);
+      reorder(state.slots);
+    }
+    return;
+  }
+  const top = state.challengers[0];
+  const weakest = state.slots[state.slots.length - 1];
+  if (top && weakest && top.power > weakest.power) {
+    state.slots[state.slots.length - 1] = top;
+    state.challengers[0] = weakest;
+    reorder(state.slots);
+    reorder(state.challengers);
+  }
+}
+function decay(state, factor) {
+  if (factor <= 0 || factor >= 1) return;
+  for (const s of state.slots) s.power *= factor;
+  for (const c of state.challengers) c.power *= factor;
+  state.slots = state.slots.filter((s) => s.power > 0.01);
+  state.challengers = state.challengers.filter((c) => c.power > 0.01);
+  reorder(state.slots);
+  reorder(state.challengers);
+}
+function contribution(state, value, config = DEFAULT_SLOT_CONFIG) {
+  if (!value) return config.epsilon;
+  const slot = state.slots.find((s) => s.value === value);
+  if (!slot) return config.epsilon;
+  const total = state.slots.reduce((sum, s) => sum + s.power, 0);
+  if (total <= 0) return config.epsilon;
+  return config.epsilon + (1 - config.epsilon) * (slot.power / total);
+}
+function isEmpty(state) {
+  return state.slots.length === 0 && state.challengers.length === 0;
+}
+
+// src/reco/interest.ts
+var DEFAULT_INTEREST_CONFIG = {
+  popularityWeight: 0.1,
+  decayFactor: 0.97,
+  decayEvery: 25
+};
+function emptyInterest(schema) {
+  const tables = {};
+  for (const k of Object.keys(schema)) tables[k] = emptyState();
+  return { tables, eventsSinceDecay: 0, totalEvents: 0 };
+}
+function tableConfig(fc) {
+  const capacity = fc.capacity ?? DEFAULT_CAPACITY;
+  return {
+    capacity,
+    challengerCapacity: fc.challengerCapacity ?? capacity * 2,
+    epsilon: fc.epsilon ?? DEFAULT_EPSILON
+  };
+}
+function featureWeight(fc, config, featureCount) {
+  if (typeof fc.weight === "number") return fc.weight;
+  const budget = Math.max(0, 1 - config.popularityWeight);
+  return featureCount > 0 ? budget / featureCount : 0;
+}
+function applyEvent(state, item, magnitude, config) {
+  if (!Number.isFinite(magnitude) || magnitude === 0) return;
+  for (const [key, fc] of Object.entries(config.schema)) {
+    const value = fc.extract(item);
+    if (!value) continue;
+    observe(state.tables[key], value, magnitude, tableConfig(fc));
+  }
+  state.totalEvents += 1;
+  state.eventsSinceDecay += 1;
+  if (state.eventsSinceDecay >= config.decayEvery) {
+    for (const key of Object.keys(config.schema)) decay(state.tables[key], config.decayFactor);
+    state.eventsSinceDecay = 0;
+  }
+}
+function scoreItem(state, item, popularityNorm, config) {
+  const entries = Object.entries(config.schema);
+  let score = config.popularityWeight * popularityNorm;
+  for (const [key, fc] of entries) {
+    const value = fc.extract(item);
+    const c = contribution(state.tables[key], value, tableConfig(fc));
+    score += featureWeight(fc, config, entries.length) * c;
+  }
+  return score;
+}
+function isCold(state) {
+  for (const t of Object.values(state.tables)) {
+    if (!isEmpty(t)) return false;
+  }
+  return true;
+}
+function describe(state, top = 3) {
+  const out = {};
+  for (const [key, t] of Object.entries(state.tables)) {
+    out[key] = t.slots.slice(0, top).map((s) => [s.value, Math.round(s.power * 100) / 100]);
+  }
+  return out;
+}
+
+// src/reco/sample.ts
+var defaultRng = Math.random;
+function weightedSampleWithoutReplacement(pool, weight, count, rng = defaultRng) {
+  if (count <= 0 || pool.length === 0) return [];
+  const heap = [];
+  const heapPush = (e) => {
+    heap.push(e);
+    let i = heap.length - 1;
+    while (i > 0) {
+      const parent = i - 1 >> 1;
+      if (heap[parent].key <= heap[i].key) break;
+      [heap[parent], heap[i]] = [heap[i], heap[parent]];
+      i = parent;
+    }
+  };
+  const heapPopMin = () => {
+    if (heap.length === 0) return void 0;
+    const min = heap[0];
+    const last = heap.pop();
+    if (heap.length > 0) {
+      heap[0] = last;
+      let i = 0;
+      while (true) {
+        const l = 2 * i + 1;
+        const r = 2 * i + 2;
+        let smallest = i;
+        if (l < heap.length && heap[l].key < heap[smallest].key) smallest = l;
+        if (r < heap.length && heap[r].key < heap[smallest].key) smallest = r;
+        if (smallest === i) break;
+        [heap[smallest], heap[i]] = [heap[i], heap[smallest]];
+        i = smallest;
+      }
+    }
+    return min;
+  };
+  for (const item of pool) {
+    const w = Math.max(weight(item), 1e-9);
+    const u = Math.max(rng(), 1e-12);
+    const key = Math.exp(Math.log(u) / w);
+    if (heap.length < count) {
+      heapPush({ item, key });
+    } else if (heap[0].key < key) {
+      heapPopMin();
+      heapPush({ item, key });
+    }
+  }
+  return heap.sort((a, b) => b.key - a.key).map((e) => e.item);
+}
+function seededRng(seed) {
+  let s = seed >>> 0;
+  return () => {
+    s = s + 1831565813 >>> 0;
+    let t = s;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+
+// src/reco/recommender.ts
+function resolve(input) {
+  return {
+    interest: {
+      schema: input.schema,
+      popularity: input.popularity,
+      popularityWeight: input.popularityWeight ?? DEFAULT_INTEREST_CONFIG.popularityWeight,
+      decayFactor: input.decayFactor ?? DEFAULT_INTEREST_CONFIG.decayFactor,
+      decayEvery: input.decayEvery ?? DEFAULT_INTEREST_CONFIG.decayEvery
+    },
+    popularity: input.popularity ?? null,
+    seenWindow: input.seenWindow ?? 300,
+    batchSize: input.batchSize ?? 20,
+    rng: input.rng ?? defaultRng
+  };
+}
+var Recommender = class {
+  constructor(catalog, config) {
+    this.ownedIds = /* @__PURE__ */ new Set();
+    this.seenOrder = [];
+    this.seen = /* @__PURE__ */ new Set();
+    this.catalog = catalog;
+    this.byId = new Map(catalog.map((i) => [i.id, i]));
+    this.config = resolve(config);
+    this.interest = emptyInterest(this.config.interest.schema);
+    if (this.config.popularity) {
+      const pop = this.config.popularity;
+      this.maxPopularity = Math.max(1, ...catalog.map((i) => pop(i)));
+    } else {
+      this.maxPopularity = 1;
+    }
+  }
+  setOwned(ids) {
+    this.ownedIds = new Set(ids);
+  }
+  /** Apply a positive prior from a list of items the user already
+   *  "loves" (their collection, recent favourites, etc.). Defaults to
+   *  `SIGNALS.collect` per item. */
+  prime(items, magnitudePerItem = SIGNALS.collect) {
+    for (const item of items) this.engage(item, magnitudePerItem);
+  }
+  engage(item, score) {
+    applyEvent(this.interest, item, score, this.config.interest);
+  }
+  recommend(count = this.config.batchSize) {
+    let excluded_seen = 0;
+    let excluded_owned = 0;
+    const candidates = [];
+    for (const item of this.catalog) {
+      if (this.ownedIds.has(item.id)) {
+        excluded_owned++;
+        continue;
+      }
+      if (this.seen.has(item.id)) {
+        excluded_seen++;
+        continue;
+      }
+      candidates.push(item);
+    }
+    const cold = isCold(this.interest);
+    const pop = this.config.popularity;
+    const popMax = this.maxPopularity;
+    const items = weightedSampleWithoutReplacement(
+      candidates,
+      (item) => {
+        const popNorm = pop ? pop(item) / popMax : 0;
+        if (cold) {
+          return Math.max(0.05, popNorm);
+        }
+        return scoreItem(this.interest, item, popNorm, this.config.interest);
+      },
+      count,
+      this.config.rng
+    );
+    const scores = items.map((item) => {
+      const popNorm = pop ? pop(item) / popMax : 0;
+      return cold ? Math.max(0.05, popNorm) : scoreItem(this.interest, item, popNorm, this.config.interest);
+    });
+    for (const item of items) this.markSeen(item.id);
+    return {
+      items,
+      scores,
+      diagnostics: { cold, candidates: candidates.length, excluded_seen, excluded_owned }
+    };
+  }
+  seenCount() {
+    return this.seenOrder.length;
+  }
+  /** Clear only the seen FIFO — interest profile + owned set survive. */
+  clearSeen() {
+    this.seen.clear();
+    this.seenOrder.length = 0;
+  }
+  markSeen(id) {
+    if (this.seen.has(id)) return;
+    this.seen.add(id);
+    this.seenOrder.push(id);
+    while (this.seenOrder.length > this.config.seenWindow) {
+      const evicted = this.seenOrder.shift();
+      if (evicted != null) this.seen.delete(evicted);
+    }
+  }
+  /** Full wipe (interest + seen). */
+  reset() {
+    const fresh = emptyInterest(this.config.interest.schema);
+    this.interest.tables = fresh.tables;
+    this.interest.eventsSinceDecay = 0;
+    this.interest.totalEvents = 0;
+    this.seen.clear();
+    this.seenOrder.length = 0;
+  }
+};
+
+// src/reco/dual-bucket/buckets.ts
+var FALLBACK_CONFIG = {
+  capacity: DEFAULT_CAPACITY,
+  decrementCap: DEFAULT_DECREMENT_CAP
+};
+function emptyBucket() {
+  return { slots: [], pointer: 0 };
+}
+function admit(state, value, score, config = FALLBACK_CONFIG) {
+  if (!value || !Number.isFinite(score) || score <= 0) return;
+  const existing = state.slots.find((s) => s.value === value);
+  if (existing) {
+    existing.power += score;
+    return;
+  }
+  if (state.slots.length < config.capacity) {
+    state.slots.push({ value, power: score });
+    return;
+  }
+  const ptr = state.pointer % state.slots.length;
+  const decrement = Math.min(score, config.decrementCap);
+  state.slots[ptr].power -= decrement;
+  if (state.slots[ptr].power <= 0) {
+    state.slots[ptr] = { value, power: score };
+  }
+  state.pointer = (ptr + 1) % state.slots.length;
+}
+function powerOf(state, value) {
+  if (!value) return 0;
+  const slot = state.slots.find((s) => s.value === value);
+  return slot ? slot.power : 0;
+}
+function isEmpty2(state) {
+  return state.slots.length === 0;
+}
+
+// src/reco/dual-bucket/interest.ts
+function emptyTables(schema) {
+  const out = {};
+  for (const k of Object.keys(schema)) out[k] = emptyBucket();
+  return out;
+}
+function emptyDualState(schema) {
+  return {
+    liked: emptyTables(schema),
+    disliked: emptyTables(schema),
+    totalEvents: 0
+  };
+}
+function bucketCfg(fc) {
+  return {
+    capacity: fc.capacity ?? DEFAULT_CAPACITY,
+    decrementCap: fc.decrementCap ?? DEFAULT_DECREMENT_CAP
+  };
+}
+function admitAcrossFeatures(state, side, item, magnitude, schema) {
+  const tables = state[side];
+  for (const [key, fc] of Object.entries(schema)) {
+    const value = fc.extract(item);
+    if (value) admit(tables[key], value, magnitude, bucketCfg(fc));
+  }
+  state.totalEvents += 1;
+}
+function engagePositive(state, item, magnitude, config) {
+  if (!Number.isFinite(magnitude) || magnitude <= 0) return;
+  admitAcrossFeatures(state, "liked", item, magnitude, config.schema);
+}
+function engageNegative(state, item, magnitude, config) {
+  if (!Number.isFinite(magnitude) || magnitude <= 0) return;
+  admitAcrossFeatures(state, "disliked", item, magnitude, config.schema);
+}
+function scoreItem2(state, item, config) {
+  let liked = 0;
+  let disliked = 0;
+  const byFeature = [];
+  for (const [key, fc] of Object.entries(config.schema)) {
+    const value = fc.extract(item);
+    const l = powerOf(state.liked[key], value);
+    const d = powerOf(state.disliked[key], value);
+    liked += l;
+    disliked += d;
+    byFeature.push({ key, value, liked: l, disliked: d });
+  }
+  return { liked, disliked, net: liked - disliked, byFeature };
+}
+function isCold2(state) {
+  if (state.totalEvents > 0) return false;
+  for (const t of Object.values(state.liked)) if (!isEmpty2(t)) return false;
+  for (const t of Object.values(state.disliked)) if (!isEmpty2(t)) return false;
+  return true;
+}
+function describe2(state, top = 4) {
+  const snap = (side) => {
+    const out = {};
+    for (const [k, t] of Object.entries(side)) {
+      out[k] = t.slots.slice().sort((a, b) => b.power - a.power).slice(0, top).map((s) => [s.value, Math.round(s.power * 100) / 100]);
+    }
+    return out;
+  };
+  return { liked: snap(state.liked), disliked: snap(state.disliked) };
+}
+
+// src/reco/dual-bucket/recommender.ts
+function resolve2(input) {
+  return {
+    interest: { schema: input.schema },
+    // 100 is a heavy exploit setting; drop to 20–30 if exploration feels
+    // weak. Live-tunable via setSampleSize().
+    sampleSize: input.sampleSize ?? 100,
+    shuffleThreshold: input.shuffleThreshold ?? 100,
+    rng: input.rng ?? defaultRng
+  };
+}
+var DualBucketRecommender = class {
+  constructor(catalog, config) {
+    this.ownedIds = /* @__PURE__ */ new Set();
+    this.seen = /* @__PURE__ */ new Set();
+    this.freshPagesIssued = 0;
+    this.catalog = catalog;
+    this.byId = new Map(catalog.map((i) => [i.id, i]));
+    this.config = resolve2(config);
+    this.interest = emptyDualState(this.config.interest.schema);
+  }
+  setOwned(ids) {
+    this.ownedIds = new Set(ids);
+  }
+  /** Live-tune the best-of-K size. */
+  setSampleSize(k) {
+    if (!Number.isFinite(k) || k < 1) return;
+    this.config.sampleSize = Math.floor(k);
+  }
+  prime(items, magnitudePerItem = SIGNALS.collect) {
+    for (const item of items) this.engage(item, magnitudePerItem);
+  }
+  engage(item, score) {
+    if (!Number.isFinite(score) || score === 0) return;
+    if (score > 0) engagePositive(this.interest, item, score, this.config.interest);
+    else engageNegative(this.interest, item, -score, this.config.interest);
+  }
+  recommend(count = 1) {
+    const items = [];
+    const scores = [];
+    let lastDiag = null;
+    for (let i = 0; i < count; i++) {
+      const result = this.pickOne();
+      if (!result) break;
+      items.push(result.item);
+      scores.push(result.diagnostics.bestNet);
+      lastDiag = result.diagnostics;
+      this.seen.add(result.item.id);
+    }
+    return {
+      items,
+      scores,
+      diagnostics: lastDiag ?? {
+        cold: isCold2(this.interest),
+        candidatesPool: 0,
+        sampleSize: 0,
+        bestNet: 0,
+        bestLiked: 0,
+        bestDisliked: 0,
+        freshPagesIssued: this.freshPagesIssued,
+        breakdown: null,
+        runnersUp: []
+      }
+    };
+  }
+  pickOne() {
+    let pool = this.candidatePool();
+    if (pool.length < this.config.shuffleThreshold) {
+      this.seen.clear();
+      this.freshPagesIssued += 1;
+      pool = this.candidatePool();
+    }
+    if (pool.length === 0) return null;
+    const k = Math.min(this.config.sampleSize, pool.length);
+    const sample = randomSample(pool, k, this.config.rng);
+    const scored = sample.map((item) => ({ item, s: scoreItem2(this.interest, item, this.config.interest) }));
+    scored.sort((a, b) => b.s.net - a.s.net);
+    let winner = scored[0];
+    if (winner.s.net < 0) {
+      const zero = scored.find((x) => x.s.net === 0);
+      if (zero) winner = zero;
+    }
+    const runnersUp = scored.filter((x) => x.item.id !== winner.item.id).map((x) => ({
+      item: x.item,
+      net: x.s.net,
+      liked: x.s.liked,
+      disliked: x.s.disliked
+    }));
+    return {
+      item: winner.item,
+      diagnostics: {
+        cold: isCold2(this.interest),
+        candidatesPool: pool.length,
+        sampleSize: k,
+        bestNet: winner.s.net,
+        bestLiked: winner.s.liked,
+        bestDisliked: winner.s.disliked,
+        freshPagesIssued: this.freshPagesIssued,
+        breakdown: winner.s.byFeature,
+        runnersUp
+      }
+    };
+  }
+  candidatePool() {
+    return this.catalog.filter((i) => !this.ownedIds.has(i.id) && !this.seen.has(i.id));
+  }
+  seenCount() {
+    return this.seen.size;
+  }
+  clearSeen() {
+    this.seen.clear();
+    this.freshPagesIssued = 0;
+  }
+  reset() {
+    const fresh = emptyDualState(this.config.interest.schema);
+    this.interest.liked = fresh.liked;
+    this.interest.disliked = fresh.disliked;
+    this.interest.totalEvents = 0;
+    this.seen.clear();
+    this.freshPagesIssued = 0;
+  }
+};
+function randomSample(pool, k, rng) {
+  if (k >= pool.length) return pool.slice();
+  const arr = pool.slice();
+  const n = arr.length;
+  const out = [];
+  for (let i = 0; i < k; i++) {
+    const j = i + Math.floor(rng() * (n - i));
+    [arr[i], arr[j]] = [arr[j], arr[i]];
+    out.push(arr[i]);
+  }
+  return out;
+}
+
+// src/reco/buckets.ts
+function logDecadeBucket(value, multiplier = 2, prefix = "lb") {
+  if (value == null || value <= 0) return null;
+  return `${prefix}${Math.floor(Math.log10(value) * multiplier)}`;
+}
+function yearBucket(year, bandSize = 5) {
+  if (year == null || year <= 0 || bandSize <= 0) return null;
+  const start = Math.floor(year / bandSize) * bandSize;
+  return `${start}-${start + bandSize - 1}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_CAPACITY,
+  DEFAULT_DECREMENT_CAP,
+  DEFAULT_EPSILON,
+  DEFAULT_INTEREST_CONFIG,
+  DEFAULT_SLOT_CONFIG,
+  DualBucketRecommender,
+  Recommender,
+  SIGNALS,
+  admit,
+  applyEvent,
+  contribution,
+  decay,
+  defaultRng,
+  describe,
+  describeDual,
+  emptyBucket,
+  emptyDualState,
+  emptyInterest,
+  emptyState,
+  engageNegative,
+  engagePositive,
+  isCold,
+  isColdDual,
+  isEmpty,
+  isEmptyBucket,
+  logDecadeBucket,
+  observe,
+  powerOf,
+  scoreItem,
+  scoreItemDual,
+  seededRng,
+  weightedSampleWithoutReplacement,
+  yearBucket
+});