@dloizides/taste-engine 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- `AXES` - the canonical 26-axis list (18 genre, 8 structure-and-feel) plus `AxisKey`,
+  `AxisVector`, `zeroAxisVector`, `l2Norm`, `dot`, `cosine`.
+- `buildTasteVector` - log-scaled hours, recency doubling, 0.15 weight for owned-but-unplayed,
+  quiz-verdict modulation, L2-normalised output.
+- `axisConfidence` - per-axis evidence saturating to 0..1.
+- `selectQuizCards` - picks cards that reduce uncertainty on the least-known axes and never
+  returns an owned title.
+- `scoreCatalog` - cosine x platform gate x novelty x quality x mood, with an exact per-axis
+  decomposition in `terms`.
+- `diversify` - greedy genre-cluster cap over the ranked list.
+- `explain` - top axes derived from the real scoring terms, nearest owned title, platform gap.
+- 34 tests, including a 2,100-title scoring run held under 100ms.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dloizides
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# @dloizides/taste-engine
+
+Weighted-vector taste modelling over a fixed 26-axis space. Pure TypeScript: no I/O, no
+React, no network, no clock. Everything runs in the browser against a catalogue the caller
+already has in memory.
+
+Built for NextGame (recommend console games from a Steam library), but nothing in it knows
+what a game is - it is 26 named axes, a library of weighted items, and a catalogue to rank.
+
+## The axes
+
+18 genre axes, then 8 structure-and-feel axes. Order is part of the contract: `diversify`
+clusters on the first 18.
+
+```
+shooter action rpg jrpg strategy simulation racing sports platformer puzzle horror
+adventure roguelike fighting metroidvania soulslike mmo survival
+sessionLength difficulty narrative coop competitive relaxing replayability artForward
+```
+
+## API
+
+```ts
+buildTasteVector(owned: OwnedTitle[], answers?: QuizAnswer[]): AxisVector
+axisConfidence(owned: OwnedTitle[]): Record<AxisKey, number>
+selectQuizCards(catalog, conf, count, ownedIds?): string[]
+scoreCatalog(taste, catalog, opts: ScoreOptions): ScoredTitle[]
+diversify(scored, limit, maxPerCluster): ScoredTitle[]
+explain(taste, title, owned): Explanation
+```
+
+## How the numbers are chosen
+
+**`buildTasteVector`** - per-title weight is `log1p(hours) * recency * ownership`, where
+recency is `2.0` for a title played recently and `1.0` otherwise, and ownership is `1.0`
+above 0.5 hours and `0.15` below it. Logarithmic hours stop a single 900-hour habit from
+flattening the rest of the library: 900h carries `log1p(900) = 6.80` against 40h at `3.71`,
+not 22 times as much. For an unplayed title `log1p(0)` is 0 and would erase it entirely, so
+the log term is replaced by 1 and only the `0.15` ownership weight survives - an unbought
+opinion, not a played one. The result is L2-normalised, so downstream cosine is a pure
+direction comparison.
+
+A `QuizAnswer` modulates the weight of the owned title it names: `loved` x2, `liked` x1.25,
+`bounced` x0.25, `never` x0. An answer naming a title outside the library is ignored - it
+carries no axes to add.
+
+**`axisConfidence`** - `1 - exp(-evidence / 4)` per axis. Zero evidence gives exactly zero
+confidence, which is what `selectQuizCards` hunts for.
+
+**`selectQuizCards`** - ranks candidates by how much of their axis mass lands on
+low-confidence axes. `ownedIds` is a parameter rather than a pre-filter so a caller cannot
+forget it and quiz someone on a game they already own.
+
+**`scoreCatalog`** - `cosine * platformGate * novelty * quality * mood`.
+- `platformGate` is 0 or 1. An owned id and a title on no allowed platform both score
+  exactly `0`, not merely a low number.
+- `quality` maps a critic score onto `0.6..1.0`; a `null` critic score is `0.8`. Absence of
+  a score is neutral, never a penalty - most console back-catalogue has no score at all.
+- `novelty` discounts a title whose axis mass sits on one axis.
+- `mood` lifts by up to 50% for a title matching the requested mood axes.
+
+`terms` is the per-axis decomposition of the product, so the terms sum to the score exactly.
+That is what makes `explain` honest.
+
+**`explain`** - runs the title back through `scoreCatalog` and sorts the real terms. It does
+not recompute a lookalike heuristic, so an explanation cannot disagree with the ranking it
+explains. `gapPlatform` names the platform of a single-platform title: the one case where
+owning a platform is the only thing between the user and the game.
+
+## Performance
+
+`score.perf.test.ts` scores 2,100 synthetic titles and fails above 100ms. The claim is a
+test, not a hope.
+
+## NOT COVERED by the test suite
+
+The tests prove the arithmetic. They say nothing about whether the axis values assigned to
+any given title are *right*. A title tagged `difficulty: 0.9` that is actually easy passes
+every check here. Catalogue accuracy is a human spot-check, not a unit test.
+
+## Install
+
+```bash
+npm install @dloizides/taste-engine
+```
+
+MIT.

package/dist/index.d.mts

@@ -0,0 +1,108 @@
+/**
+ * The canonical axis list. 18 genre axes followed by 8 structure-and-feel axes.
+ * The ORDER is part of the contract: everything downstream that talks about
+ * "genre clusters" means the first GENRE_AXIS_COUNT entries of this array.
+ */
+declare const AXES: readonly ["shooter", "action", "rpg", "jrpg", "strategy", "simulation", "racing", "sports", "platformer", "puzzle", "horror", "adventure", "roguelike", "fighting", "metroidvania", "soulslike", "mmo", "survival", "sessionLength", "difficulty", "narrative", "coop", "competitive", "relaxing", "replayability", "artForward"];
+type AxisKey = typeof AXES[number];
+/** Every value is 0..1. */
+type AxisVector = Record<AxisKey, number>;
+declare const GENRE_AXIS_COUNT = 18;
+/** The genre half of AXES - what `diversify` clusters on. */
+declare const GENRE_AXES: readonly AxisKey[];
+declare function zeroAxisVector(): AxisVector;
+declare function l2Norm(vector: AxisVector): number;
+declare function dot(left: AxisVector, right: AxisVector): number;
+/** Cosine similarity, defined as 0 (not NaN) when either side has no magnitude. */
+declare function cosine(left: AxisVector, right: AxisVector): number;
+
+interface OwnedTitle {
+    id: string;
+    hours: number;
+    playedRecently: boolean;
+    axes: AxisVector;
+}
+interface CatalogTitle {
+    id: string;
+    axes: AxisVector;
+    platforms: string[];
+    /** null means "no critic score exists", which scores as neutral - never as zero quality. */
+    criticScore: number | null;
+}
+interface QuizAnswer {
+    titleId: string;
+    verdict: 'loved' | 'liked' | 'bounced' | 'never';
+}
+interface ScoreOptions {
+    ownedIds: Set<string>;
+    allowedPlatforms: string[];
+    mood?: Partial<AxisVector>;
+}
+interface ScoredTitle {
+    id: string;
+    score: number;
+    /** Per-axis decomposition of `score`. The terms sum to `score` exactly. */
+    terms: Record<AxisKey, number>;
+}
+interface Explanation {
+    topAxes: AxisKey[];
+    nearestOwnedId: string | null;
+    gapPlatform: string | null;
+}
+
+/**
+ * weight = log1p(hours) * recency * ownership.
+ *
+ * recency is 2.0 when the title was played recently, else 1.0.
+ * ownership is 1.0 when hours > 0.5, else 0.15.
+ * For an unplayed title log1p(hours) is 0, which would erase the title entirely,
+ * so the log term is replaced by UNPLAYED_BASE and only the 0.15 ownership weight remains.
+ */
+declare function titleWeight(title: OwnedTitle): number;
+/**
+ * Quiz answers modulate the weight of the OWNED title they name. An answer whose
+ * titleId is not in the library is ignored - the vector is built from what the user
+ * actually has, and a verdict on something they do not own carries no axes to add.
+ */
+declare function buildTasteVector(owned: OwnedTitle[], answers?: QuizAnswer[]): AxisVector;
+
+/**
+ * How much the library actually tells us about each axis, 0..1.
+ * An axis no owned title expresses has zero evidence and therefore zero confidence -
+ * which is what `selectQuizCards` targets.
+ */
+declare function axisConfidence(owned: OwnedTitle[]): Record<AxisKey, number>;
+
+/**
+ * `ownedIds` is optional and defaults to empty. It is a parameter rather than a
+ * pre-filter on `catalog` so a caller cannot forget it and quiz the user on games
+ * they already have.
+ */
+declare function selectQuizCards(catalog: CatalogTitle[], conf: Record<AxisKey, number>, count: number, ownedIds?: ReadonlySet<string>): string[];
+
+/**
+ * score = cosine(taste, title) * platformGate * novelty * quality * mood.
+ * `terms` is the per-axis decomposition of that product, so the terms sum to the score.
+ * Rows come back sorted by score, descending.
+ */
+declare function scoreCatalog(taste: AxisVector, catalog: CatalogTitle[], opts: ScoreOptions): ScoredTitle[];
+
+/** The genre axis carrying the largest share of a row's score. */
+declare function clusterOf(terms: Record<AxisKey, number>): AxisKey;
+/**
+ * Greedy re-rank over the incoming order: keep the highest-scoring rows but never let
+ * one genre cluster take more than `maxPerCluster` slots. Relative order is preserved.
+ */
+declare function diversify(scored: ScoredTitle[], limit: number, maxPerCluster: number): ScoredTitle[];
+
+/**
+ * The axes come from the REAL scoring terms: `explain` runs the title back through
+ * `scoreCatalog` rather than recomputing a lookalike heuristic, so an explanation can
+ * never disagree with the ranking it explains.
+ *
+ * `gapPlatform` names the platform of a title that exists on exactly one - the case
+ * where owning that platform is the thing standing between the user and the game.
+ */
+declare function explain(taste: AxisVector, title: CatalogTitle, owned: OwnedTitle[]): Explanation;
+
+export { AXES, type AxisKey, type AxisVector, type CatalogTitle, type Explanation, GENRE_AXES, GENRE_AXIS_COUNT, type OwnedTitle, type QuizAnswer, type ScoreOptions, type ScoredTitle, axisConfidence, buildTasteVector, clusterOf, cosine, diversify, dot, explain, l2Norm, scoreCatalog, selectQuizCards, titleWeight, zeroAxisVector };

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The canonical axis list. 18 genre axes followed by 8 structure-and-feel axes.
+ * The ORDER is part of the contract: everything downstream that talks about
+ * "genre clusters" means the first GENRE_AXIS_COUNT entries of this array.
+ */
+declare const AXES: readonly ["shooter", "action", "rpg", "jrpg", "strategy", "simulation", "racing", "sports", "platformer", "puzzle", "horror", "adventure", "roguelike", "fighting", "metroidvania", "soulslike", "mmo", "survival", "sessionLength", "difficulty", "narrative", "coop", "competitive", "relaxing", "replayability", "artForward"];
+type AxisKey = typeof AXES[number];
+/** Every value is 0..1. */
+type AxisVector = Record<AxisKey, number>;
+declare const GENRE_AXIS_COUNT = 18;
+/** The genre half of AXES - what `diversify` clusters on. */
+declare const GENRE_AXES: readonly AxisKey[];
+declare function zeroAxisVector(): AxisVector;
+declare function l2Norm(vector: AxisVector): number;
+declare function dot(left: AxisVector, right: AxisVector): number;
+/** Cosine similarity, defined as 0 (not NaN) when either side has no magnitude. */
+declare function cosine(left: AxisVector, right: AxisVector): number;
+
+interface OwnedTitle {
+    id: string;
+    hours: number;
+    playedRecently: boolean;
+    axes: AxisVector;
+}
+interface CatalogTitle {
+    id: string;
+    axes: AxisVector;
+    platforms: string[];
+    /** null means "no critic score exists", which scores as neutral - never as zero quality. */
+    criticScore: number | null;
+}
+interface QuizAnswer {
+    titleId: string;
+    verdict: 'loved' | 'liked' | 'bounced' | 'never';
+}
+interface ScoreOptions {
+    ownedIds: Set<string>;
+    allowedPlatforms: string[];
+    mood?: Partial<AxisVector>;
+}
+interface ScoredTitle {
+    id: string;
+    score: number;
+    /** Per-axis decomposition of `score`. The terms sum to `score` exactly. */
+    terms: Record<AxisKey, number>;
+}
+interface Explanation {
+    topAxes: AxisKey[];
+    nearestOwnedId: string | null;
+    gapPlatform: string | null;
+}
+
+/**
+ * weight = log1p(hours) * recency * ownership.
+ *
+ * recency is 2.0 when the title was played recently, else 1.0.
+ * ownership is 1.0 when hours > 0.5, else 0.15.
+ * For an unplayed title log1p(hours) is 0, which would erase the title entirely,
+ * so the log term is replaced by UNPLAYED_BASE and only the 0.15 ownership weight remains.
+ */
+declare function titleWeight(title: OwnedTitle): number;
+/**
+ * Quiz answers modulate the weight of the OWNED title they name. An answer whose
+ * titleId is not in the library is ignored - the vector is built from what the user
+ * actually has, and a verdict on something they do not own carries no axes to add.
+ */
+declare function buildTasteVector(owned: OwnedTitle[], answers?: QuizAnswer[]): AxisVector;
+
+/**
+ * How much the library actually tells us about each axis, 0..1.
+ * An axis no owned title expresses has zero evidence and therefore zero confidence -
+ * which is what `selectQuizCards` targets.
+ */
+declare function axisConfidence(owned: OwnedTitle[]): Record<AxisKey, number>;
+
+/**
+ * `ownedIds` is optional and defaults to empty. It is a parameter rather than a
+ * pre-filter on `catalog` so a caller cannot forget it and quiz the user on games
+ * they already have.
+ */
+declare function selectQuizCards(catalog: CatalogTitle[], conf: Record<AxisKey, number>, count: number, ownedIds?: ReadonlySet<string>): string[];
+
+/**
+ * score = cosine(taste, title) * platformGate * novelty * quality * mood.
+ * `terms` is the per-axis decomposition of that product, so the terms sum to the score.
+ * Rows come back sorted by score, descending.
+ */
+declare function scoreCatalog(taste: AxisVector, catalog: CatalogTitle[], opts: ScoreOptions): ScoredTitle[];
+
+/** The genre axis carrying the largest share of a row's score. */
+declare function clusterOf(terms: Record<AxisKey, number>): AxisKey;
+/**
+ * Greedy re-rank over the incoming order: keep the highest-scoring rows but never let
+ * one genre cluster take more than `maxPerCluster` slots. Relative order is preserved.
+ */
+declare function diversify(scored: ScoredTitle[], limit: number, maxPerCluster: number): ScoredTitle[];
+
+/**
+ * The axes come from the REAL scoring terms: `explain` runs the title back through
+ * `scoreCatalog` rather than recomputing a lookalike heuristic, so an explanation can
+ * never disagree with the ranking it explains.
+ *
+ * `gapPlatform` names the platform of a title that exists on exactly one - the case
+ * where owning that platform is the thing standing between the user and the game.
+ */
+declare function explain(taste: AxisVector, title: CatalogTitle, owned: OwnedTitle[]): Explanation;
+
+export { AXES, type AxisKey, type AxisVector, type CatalogTitle, type Explanation, GENRE_AXES, GENRE_AXIS_COUNT, type OwnedTitle, type QuizAnswer, type ScoreOptions, type ScoredTitle, axisConfidence, buildTasteVector, clusterOf, cosine, diversify, dot, explain, l2Norm, scoreCatalog, selectQuizCards, titleWeight, zeroAxisVector };

package/dist/index.js

@@ -0,0 +1,304 @@
+'use strict';
+
+// src/axes.ts
+var AXES = [
+  // genre (18)
+  "shooter",
+  "action",
+  "rpg",
+  "jrpg",
+  "strategy",
+  "simulation",
+  "racing",
+  "sports",
+  "platformer",
+  "puzzle",
+  "horror",
+  "adventure",
+  "roguelike",
+  "fighting",
+  "metroidvania",
+  "soulslike",
+  "mmo",
+  "survival",
+  // structure and feel (8)
+  "sessionLength",
+  "difficulty",
+  "narrative",
+  "coop",
+  "competitive",
+  "relaxing",
+  "replayability",
+  "artForward"
+];
+var GENRE_AXIS_COUNT = 18;
+var GENRE_AXES = AXES.slice(0, GENRE_AXIS_COUNT);
+function zeroAxisVector() {
+  const out = {};
+  for (const axis of AXES) {
+    out[axis] = 0;
+  }
+  return out;
+}
+function l2Norm(vector) {
+  let sum = 0;
+  for (const axis of AXES) {
+    sum += vector[axis] * vector[axis];
+  }
+  return Math.sqrt(sum);
+}
+function dot(left, right) {
+  let sum = 0;
+  for (const axis of AXES) {
+    sum += left[axis] * right[axis];
+  }
+  return sum;
+}
+function cosine(left, right) {
+  const denominator = l2Norm(left) * l2Norm(right);
+  if (denominator === 0) {
+    return 0;
+  }
+  return dot(left, right) / denominator;
+}
+
+// src/buildTasteVector.ts
+var RECENCY_MULTIPLIER = 2;
+var OWNERSHIP_PLAYED = 1;
+var OWNERSHIP_UNPLAYED = 0.15;
+var PLAYED_HOURS_THRESHOLD = 0.5;
+var UNPLAYED_BASE = 1;
+var VERDICT_MULTIPLIER = {
+  loved: 2,
+  liked: 1.25,
+  bounced: 0.25,
+  never: 0
+};
+function titleWeight(title) {
+  const played = title.hours > PLAYED_HOURS_THRESHOLD;
+  const base = played ? Math.log1p(title.hours) : UNPLAYED_BASE;
+  const recency = title.playedRecently ? RECENCY_MULTIPLIER : 1;
+  const ownership = played ? OWNERSHIP_PLAYED : OWNERSHIP_UNPLAYED;
+  return base * recency * ownership;
+}
+function buildTasteVector(owned, answers) {
+  const verdicts = /* @__PURE__ */ new Map();
+  for (const answer of answers ?? []) {
+    verdicts.set(answer.titleId, VERDICT_MULTIPLIER[answer.verdict]);
+  }
+  const accumulator = zeroAxisVector();
+  for (const title of owned) {
+    const weight = titleWeight(title) * (verdicts.get(title.id) ?? 1);
+    if (weight === 0) {
+      continue;
+    }
+    for (const axis of AXES) {
+      accumulator[axis] += weight * title.axes[axis];
+    }
+  }
+  const norm = l2Norm(accumulator);
+  if (norm === 0) {
+    return accumulator;
+  }
+  for (const axis of AXES) {
+    accumulator[axis] /= norm;
+  }
+  return accumulator;
+}
+
+// src/confidence.ts
+var CONFIDENCE_SCALE = 4;
+function axisConfidence(owned) {
+  const evidence = zeroAxisVector();
+  for (const title of owned) {
+    const weight = titleWeight(title);
+    for (const axis of AXES) {
+      evidence[axis] += weight * title.axes[axis];
+    }
+  }
+  const confidence = zeroAxisVector();
+  for (const axis of AXES) {
+    confidence[axis] = 1 - Math.exp(-evidence[axis] / CONFIDENCE_SCALE);
+  }
+  return confidence;
+}
+
+// src/selectQuizCards.ts
+var NO_OWNED_IDS = /* @__PURE__ */ new Set();
+function informationGain(title, confidence) {
+  let gain = 0;
+  for (const axis of AXES) {
+    gain += (1 - confidence[axis]) * title.axes[axis];
+  }
+  return gain;
+}
+function selectQuizCards(catalog, conf, count, ownedIds = NO_OWNED_IDS) {
+  if (count <= 0) {
+    return [];
+  }
+  return catalog.filter((title) => !ownedIds.has(title.id)).map((title) => ({ id: title.id, gain: informationGain(title, conf) })).sort((left, right) => right.gain - left.gain).slice(0, count).map((candidate) => candidate.id);
+}
+
+// src/score.ts
+var NEUTRAL_QUALITY = 0.8;
+var QUALITY_FLOOR = 0.6;
+var QUALITY_RANGE = 0.4;
+var CRITIC_SCORE_MAX = 100;
+var NOVELTY_STRENGTH = 0.2;
+var MOOD_STRENGTH = 0.5;
+function moodWeights(mood) {
+  if (mood === void 0) {
+    return [];
+  }
+  const weights = [];
+  for (const axis of AXES) {
+    const weight = mood[axis];
+    if (weight !== void 0 && weight > 0) {
+      weights.push({ axis, weight });
+    }
+  }
+  return weights;
+}
+function qualityTerm(criticScore) {
+  if (criticScore === null) {
+    return NEUTRAL_QUALITY;
+  }
+  const clamped = Math.min(Math.max(criticScore, 0), CRITIC_SCORE_MAX);
+  return QUALITY_FLOOR + QUALITY_RANGE * (clamped / CRITIC_SCORE_MAX);
+}
+function noveltyTerm(axes) {
+  let sum = 0;
+  let peak = 0;
+  for (const axis of AXES) {
+    sum += axes[axis];
+    peak = Math.max(peak, axes[axis]);
+  }
+  if (sum === 0) {
+    return 1;
+  }
+  return 1 - NOVELTY_STRENGTH * (peak / sum);
+}
+function moodTerm(axes, mood) {
+  if (mood.length === 0) {
+    return 1;
+  }
+  let weighted = 0;
+  let total = 0;
+  for (const entry of mood) {
+    weighted += entry.weight * axes[entry.axis];
+    total += entry.weight;
+  }
+  return 1 + MOOD_STRENGTH * (weighted / total);
+}
+function zeroRow(id) {
+  return { id, score: 0, terms: zeroAxisVector() };
+}
+function scoreOne(context, title) {
+  if (context.ownedIds.has(title.id)) {
+    return zeroRow(title.id);
+  }
+  if (!title.platforms.some((platform) => context.allowed.has(platform))) {
+    return zeroRow(title.id);
+  }
+  const denominator = context.tasteNorm * l2Norm(title.axes);
+  if (denominator === 0) {
+    return zeroRow(title.id);
+  }
+  const gain = noveltyTerm(title.axes) * qualityTerm(title.criticScore) * moodTerm(title.axes, context.mood);
+  const terms = zeroAxisVector();
+  let score = 0;
+  for (const axis of AXES) {
+    const term = context.taste[axis] * title.axes[axis] / denominator * gain;
+    terms[axis] = term;
+    score += term;
+  }
+  return { id: title.id, score, terms };
+}
+function scoreCatalog(taste, catalog, opts) {
+  const context = {
+    taste,
+    tasteNorm: l2Norm(taste),
+    ownedIds: opts.ownedIds,
+    allowed: new Set(opts.allowedPlatforms),
+    mood: moodWeights(opts.mood)
+  };
+  const rows = catalog.map((title) => scoreOne(context, title));
+  rows.sort((left, right) => right.score - left.score);
+  return rows;
+}
+
+// src/diversify.ts
+function clusterOf(terms) {
+  let best = AXES[0];
+  let bestValue = -Infinity;
+  for (const axis of GENRE_AXES) {
+    if (terms[axis] > bestValue) {
+      bestValue = terms[axis];
+      best = axis;
+    }
+  }
+  return best;
+}
+function diversify(scored, limit, maxPerCluster) {
+  const perCluster = /* @__PURE__ */ new Map();
+  const out = [];
+  for (const row of scored) {
+    if (out.length >= limit) {
+      break;
+    }
+    const cluster = clusterOf(row.terms);
+    const taken = perCluster.get(cluster) ?? 0;
+    if (taken >= maxPerCluster) {
+      continue;
+    }
+    perCluster.set(cluster, taken + 1);
+    out.push(row);
+  }
+  return out;
+}
+
+// src/explain.ts
+var TOP_AXIS_COUNT = 3;
+function nearestOwnedId(axes, owned) {
+  let best = null;
+  let bestSimilarity = -Infinity;
+  for (const title of owned) {
+    const similarity = cosine(axes, title.axes);
+    if (similarity > bestSimilarity) {
+      bestSimilarity = similarity;
+      best = title.id;
+    }
+  }
+  return best;
+}
+function explain(taste, title, owned) {
+  const rows = scoreCatalog(taste, [title], {
+    ownedIds: /* @__PURE__ */ new Set(),
+    allowedPlatforms: title.platforms
+  });
+  const terms = rows[0]?.terms ?? zeroAxisVector();
+  const topAxes = AXES.filter((axis) => terms[axis] > 0).sort((left, right) => terms[right] - terms[left]).slice(0, TOP_AXIS_COUNT);
+  return {
+    topAxes,
+    nearestOwnedId: nearestOwnedId(title.axes, owned),
+    gapPlatform: title.platforms.length === 1 ? title.platforms[0] ?? null : null
+  };
+}
+
+exports.AXES = AXES;
+exports.GENRE_AXES = GENRE_AXES;
+exports.GENRE_AXIS_COUNT = GENRE_AXIS_COUNT;
+exports.axisConfidence = axisConfidence;
+exports.buildTasteVector = buildTasteVector;
+exports.clusterOf = clusterOf;
+exports.cosine = cosine;
+exports.diversify = diversify;
+exports.dot = dot;
+exports.explain = explain;
+exports.l2Norm = l2Norm;
+exports.scoreCatalog = scoreCatalog;
+exports.selectQuizCards = selectQuizCards;
+exports.titleWeight = titleWeight;
+exports.zeroAxisVector = zeroAxisVector;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/axes.ts","../src/buildTasteVector.ts","../src/confidence.ts","../src/selectQuizCards.ts","../src/score.ts","../src/diversify.ts","../src/explain.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * The canonical axis list. 18 genre axes followed by 8 structure-and-feel axes.\n * The ORDER is part of the contract: everything downstream that talks about\n * \"genre clusters\" means the first GENRE_AXIS_COUNT entries of this array.\n */\nexport const AXES = [\n  // genre (18)\n  'shooter', 'action', 'rpg', 'jrpg', 'strategy', 'simulation', 'racing', 'sports', 'platformer',\n  'puzzle', 'horror', 'adventure', 'roguelike', 'fighting', 'metroidvania', 'soulslike', 'mmo', 'survival',\n  // structure and feel (8)\n  'sessionLength', 'difficulty', 'narrative', 'coop', 'competitive', 'relaxing', 'replayability', 'artForward',\n] as const;\n\nexport type AxisKey = typeof AXES[number];\n\n/** Every value is 0..1. */\nexport type AxisVector = Record<AxisKey, number>;\n\nexport const GENRE_AXIS_COUNT = 18;\n\n/** The genre half of AXES - what `diversify` clusters on. */\nexport const GENRE_AXES: readonly AxisKey[] = AXES.slice(0, GENRE_AXIS_COUNT);\n\nexport function zeroAxisVector(): AxisVector {\n  const out = {} as AxisVector;\n  for (const axis of AXES) {\n    out[axis] = 0;\n  }\n  return out;\n}\n\nexport function l2Norm(vector: AxisVector): number {\n  let sum = 0;\n  for (const axis of AXES) {\n    sum += vector[axis] * vector[axis];\n  }\n  return Math.sqrt(sum);\n}\n\nexport function dot(left: AxisVector, right: AxisVector): number {\n  let sum = 0;\n  for (const axis of AXES) {\n    sum += left[axis] * right[axis];\n  }\n  return sum;\n}\n\n/** Cosine similarity, defined as 0 (not NaN) when either side has no magnitude. */\nexport function cosine(left: AxisVector, right: AxisVector): number {\n  const denominator = l2Norm(left) * l2Norm(right);\n  if (denominator === 0) {\n    return 0;\n  }\n  return dot(left, right) / denominator;\n}\n","import { AXES, l2Norm, zeroAxisVector } from './axes';\nimport type { AxisVector } from './axes';\nimport type { OwnedTitle, QuizAnswer } from './types';\n\nconst RECENCY_MULTIPLIER = 2.0;\nconst OWNERSHIP_PLAYED = 1.0;\nconst OWNERSHIP_UNPLAYED = 0.15;\n/** Below this, a title counts as owned-but-unplayed; log1p would score it 0 and erase it. */\nconst PLAYED_HOURS_THRESHOLD = 0.5;\nconst UNPLAYED_BASE = 1;\n\nconst VERDICT_MULTIPLIER: Record<QuizAnswer['verdict'], number> = {\n  loved: 2,\n  liked: 1.25,\n  bounced: 0.25,\n  never: 0,\n};\n\n/**\n * weight = log1p(hours) * recency * ownership.\n *\n * recency is 2.0 when the title was played recently, else 1.0.\n * ownership is 1.0 when hours > 0.5, else 0.15.\n * For an unplayed title log1p(hours) is 0, which would erase the title entirely,\n * so the log term is replaced by UNPLAYED_BASE and only the 0.15 ownership weight remains.\n */\nexport function titleWeight(title: OwnedTitle): number {\n  const played = title.hours > PLAYED_HOURS_THRESHOLD;\n  const base = played ? Math.log1p(title.hours) : UNPLAYED_BASE;\n  const recency = title.playedRecently ? RECENCY_MULTIPLIER : 1;\n  const ownership = played ? OWNERSHIP_PLAYED : OWNERSHIP_UNPLAYED;\n  return base * recency * ownership;\n}\n\n/**\n * Quiz answers modulate the weight of the OWNED title they name. An answer whose\n * titleId is not in the library is ignored - the vector is built from what the user\n * actually has, and a verdict on something they do not own carries no axes to add.\n */\nexport function buildTasteVector(owned: OwnedTitle[], answers?: QuizAnswer[]): AxisVector {\n  const verdicts = new Map<string, number>();\n  for (const answer of answers ?? []) {\n    verdicts.set(answer.titleId, VERDICT_MULTIPLIER[answer.verdict]);\n  }\n\n  const accumulator = zeroAxisVector();\n  for (const title of owned) {\n    const weight = titleWeight(title) * (verdicts.get(title.id) ?? 1);\n    if (weight === 0) {\n      continue;\n    }\n    for (const axis of AXES) {\n      accumulator[axis] += weight * title.axes[axis];\n    }\n  }\n\n  const norm = l2Norm(accumulator);\n  if (norm === 0) {\n    return accumulator;\n  }\n  for (const axis of AXES) {\n    accumulator[axis] /= norm;\n  }\n  return accumulator;\n}\n","import { AXES, zeroAxisVector } from './axes';\nimport type { AxisKey } from './axes';\nimport { titleWeight } from './buildTasteVector';\nimport type { OwnedTitle } from './types';\n\n/** Weighted evidence at which an axis reaches ~63% confidence. */\nconst CONFIDENCE_SCALE = 4;\n\n/**\n * How much the library actually tells us about each axis, 0..1.\n * An axis no owned title expresses has zero evidence and therefore zero confidence -\n * which is what `selectQuizCards` targets.\n */\nexport function axisConfidence(owned: OwnedTitle[]): Record<AxisKey, number> {\n  const evidence = zeroAxisVector();\n  for (const title of owned) {\n    const weight = titleWeight(title);\n    for (const axis of AXES) {\n      evidence[axis] += weight * title.axes[axis];\n    }\n  }\n\n  const confidence = zeroAxisVector();\n  for (const axis of AXES) {\n    confidence[axis] = 1 - Math.exp(-evidence[axis] / CONFIDENCE_SCALE);\n  }\n  return confidence;\n}\n","import { AXES } from './axes';\nimport type { AxisKey } from './axes';\nimport type { CatalogTitle } from './types';\n\nconst NO_OWNED_IDS: ReadonlySet<string> = new Set<string>();\n\n/**\n * Information gain: how much of this title's axis mass sits on the axes we are LEAST\n * confident about. A card that only expresses axes we already understand teaches nothing.\n */\nfunction informationGain(title: CatalogTitle, confidence: Record<AxisKey, number>): number {\n  let gain = 0;\n  for (const axis of AXES) {\n    gain += (1 - confidence[axis]) * title.axes[axis];\n  }\n  return gain;\n}\n\n/**\n * `ownedIds` is optional and defaults to empty. It is a parameter rather than a\n * pre-filter on `catalog` so a caller cannot forget it and quiz the user on games\n * they already have.\n */\nexport function selectQuizCards(\n  catalog: CatalogTitle[],\n  conf: Record<AxisKey, number>,\n  count: number,\n  ownedIds: ReadonlySet<string> = NO_OWNED_IDS,\n): string[] {\n  if (count <= 0) {\n    return [];\n  }\n  return catalog\n    .filter((title) => !ownedIds.has(title.id))\n    .map((title) => ({ id: title.id, gain: informationGain(title, conf) }))\n    .sort((left, right) => right.gain - left.gain)\n    .slice(0, count)\n    .map((candidate) => candidate.id);\n}\n","import { AXES, l2Norm, zeroAxisVector } from './axes';\nimport type { AxisKey, AxisVector } from './axes';\nimport type { CatalogTitle, ScoreOptions, ScoredTitle } from './types';\n\n/** Applied when a title has no critic score at all - absence is neutral, not bad. */\nconst NEUTRAL_QUALITY = 0.8;\nconst QUALITY_FLOOR = 0.6;\nconst QUALITY_RANGE = 0.4;\nconst CRITIC_SCORE_MAX = 100;\n/** How far a one-note title is discounted against a broad one. */\nconst NOVELTY_STRENGTH = 0.2;\n/** Maximum lift a fully matched mood can apply. */\nconst MOOD_STRENGTH = 0.5;\n\ninterface MoodWeight { axis: AxisKey; weight: number }\n\ninterface ScoreContext {\n  taste: AxisVector;\n  tasteNorm: number;\n  ownedIds: Set<string>;\n  allowed: Set<string>;\n  mood: MoodWeight[];\n}\n\nfunction moodWeights(mood: Partial<AxisVector> | undefined): MoodWeight[] {\n  if (mood === undefined) {\n    return [];\n  }\n  const weights: MoodWeight[] = [];\n  for (const axis of AXES) {\n    const weight = mood[axis];\n    if (weight !== undefined && weight > 0) {\n      weights.push({ axis, weight });\n    }\n  }\n  return weights;\n}\n\nfunction qualityTerm(criticScore: number | null): number {\n  if (criticScore === null) {\n    return NEUTRAL_QUALITY;\n  }\n  const clamped = Math.min(Math.max(criticScore, 0), CRITIC_SCORE_MAX);\n  return QUALITY_FLOOR + QUALITY_RANGE * (clamped / CRITIC_SCORE_MAX);\n}\n\n/** Discounts a title whose axis mass is concentrated on a single axis. */\nfunction noveltyTerm(axes: AxisVector): number {\n  let sum = 0;\n  let peak = 0;\n  for (const axis of AXES) {\n    sum += axes[axis];\n    peak = Math.max(peak, axes[axis]);\n  }\n  if (sum === 0) {\n    return 1;\n  }\n  return 1 - NOVELTY_STRENGTH * (peak / sum);\n}\n\nfunction moodTerm(axes: AxisVector, mood: MoodWeight[]): number {\n  if (mood.length === 0) {\n    return 1;\n  }\n  let weighted = 0;\n  let total = 0;\n  for (const entry of mood) {\n    weighted += entry.weight * axes[entry.axis];\n    total += entry.weight;\n  }\n  return 1 + MOOD_STRENGTH * (weighted / total);\n}\n\nfunction zeroRow(id: string): ScoredTitle {\n  return { id, score: 0, terms: zeroAxisVector() };\n}\n\nfunction scoreOne(context: ScoreContext, title: CatalogTitle): ScoredTitle {\n  if (context.ownedIds.has(title.id)) {\n    return zeroRow(title.id);\n  }\n  if (!title.platforms.some((platform) => context.allowed.has(platform))) {\n    return zeroRow(title.id);\n  }\n  const denominator = context.tasteNorm * l2Norm(title.axes);\n  if (denominator === 0) {\n    return zeroRow(title.id);\n  }\n\n  const gain = noveltyTerm(title.axes) * qualityTerm(title.criticScore) * moodTerm(title.axes, context.mood);\n  const terms = zeroAxisVector();\n  let score = 0;\n  for (const axis of AXES) {\n    const term = (context.taste[axis] * title.axes[axis] / denominator) * gain;\n    terms[axis] = term;\n    score += term;\n  }\n  return { id: title.id, score, terms };\n}\n\n/**\n * score = cosine(taste, title) * platformGate * novelty * quality * mood.\n * `terms` is the per-axis decomposition of that product, so the terms sum to the score.\n * Rows come back sorted by score, descending.\n */\nexport function scoreCatalog(taste: AxisVector, catalog: CatalogTitle[], opts: ScoreOptions): ScoredTitle[] {\n  const context: ScoreContext = {\n    taste,\n    tasteNorm: l2Norm(taste),\n    ownedIds: opts.ownedIds,\n    allowed: new Set(opts.allowedPlatforms),\n    mood: moodWeights(opts.mood),\n  };\n  const rows = catalog.map((title) => scoreOne(context, title));\n  rows.sort((left, right) => right.score - left.score);\n  return rows;\n}\n","import { AXES, GENRE_AXES } from './axes';\nimport type { AxisKey } from './axes';\nimport type { ScoredTitle } from './types';\n\n/** The genre axis carrying the largest share of a row's score. */\nexport function clusterOf(terms: Record<AxisKey, number>): AxisKey {\n  let best: AxisKey = AXES[0];\n  let bestValue = -Infinity;\n  for (const axis of GENRE_AXES) {\n    if (terms[axis] > bestValue) {\n      bestValue = terms[axis];\n      best = axis;\n    }\n  }\n  return best;\n}\n\n/**\n * Greedy re-rank over the incoming order: keep the highest-scoring rows but never let\n * one genre cluster take more than `maxPerCluster` slots. Relative order is preserved.\n */\nexport function diversify(scored: ScoredTitle[], limit: number, maxPerCluster: number): ScoredTitle[] {\n  const perCluster = new Map<AxisKey, number>();\n  const out: ScoredTitle[] = [];\n  for (const row of scored) {\n    if (out.length >= limit) {\n      break;\n    }\n    const cluster = clusterOf(row.terms);\n    const taken = perCluster.get(cluster) ?? 0;\n    if (taken >= maxPerCluster) {\n      continue;\n    }\n    perCluster.set(cluster, taken + 1);\n    out.push(row);\n  }\n  return out;\n}\n","import { AXES, cosine, zeroAxisVector } from './axes';\nimport type { AxisKey, AxisVector } from './axes';\nimport { scoreCatalog } from './score';\nimport type { CatalogTitle, Explanation, OwnedTitle } from './types';\n\nconst TOP_AXIS_COUNT = 3;\n\nfunction nearestOwnedId(axes: AxisVector, owned: OwnedTitle[]): string | null {\n  let best: string | null = null;\n  let bestSimilarity = -Infinity;\n  for (const title of owned) {\n    const similarity = cosine(axes, title.axes);\n    if (similarity > bestSimilarity) {\n      bestSimilarity = similarity;\n      best = title.id;\n    }\n  }\n  return best;\n}\n\n/**\n * The axes come from the REAL scoring terms: `explain` runs the title back through\n * `scoreCatalog` rather than recomputing a lookalike heuristic, so an explanation can\n * never disagree with the ranking it explains.\n *\n * `gapPlatform` names the platform of a title that exists on exactly one - the case\n * where owning that platform is the thing standing between the user and the game.\n */\nexport function explain(taste: AxisVector, title: CatalogTitle, owned: OwnedTitle[]): Explanation {\n  const rows = scoreCatalog(taste, [title], {\n    ownedIds: new Set<string>(),\n    allowedPlatforms: title.platforms,\n  });\n  const terms: Record<AxisKey, number> = rows[0]?.terms ?? zeroAxisVector();\n  const topAxes = AXES.filter((axis) => terms[axis] > 0)\n    .sort((left, right) => terms[right] - terms[left])\n    .slice(0, TOP_AXIS_COUNT);\n\n  return {\n    topAxes,\n    nearestOwnedId: nearestOwnedId(title.axes, owned),\n    gapPlatform: title.platforms.length === 1 ? title.platforms[0] ?? null : null,\n  };\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,288 @@
+// src/axes.ts
+var AXES = [
+  // genre (18)
+  "shooter",
+  "action",
+  "rpg",
+  "jrpg",
+  "strategy",
+  "simulation",
+  "racing",
+  "sports",
+  "platformer",
+  "puzzle",
+  "horror",
+  "adventure",
+  "roguelike",
+  "fighting",
+  "metroidvania",
+  "soulslike",
+  "mmo",
+  "survival",
+  // structure and feel (8)
+  "sessionLength",
+  "difficulty",
+  "narrative",
+  "coop",
+  "competitive",
+  "relaxing",
+  "replayability",
+  "artForward"
+];
+var GENRE_AXIS_COUNT = 18;
+var GENRE_AXES = AXES.slice(0, GENRE_AXIS_COUNT);
+function zeroAxisVector() {
+  const out = {};
+  for (const axis of AXES) {
+    out[axis] = 0;
+  }
+  return out;
+}
+function l2Norm(vector) {
+  let sum = 0;
+  for (const axis of AXES) {
+    sum += vector[axis] * vector[axis];
+  }
+  return Math.sqrt(sum);
+}
+function dot(left, right) {
+  let sum = 0;
+  for (const axis of AXES) {
+    sum += left[axis] * right[axis];
+  }
+  return sum;
+}
+function cosine(left, right) {
+  const denominator = l2Norm(left) * l2Norm(right);
+  if (denominator === 0) {
+    return 0;
+  }
+  return dot(left, right) / denominator;
+}
+
+// src/buildTasteVector.ts
+var RECENCY_MULTIPLIER = 2;
+var OWNERSHIP_PLAYED = 1;
+var OWNERSHIP_UNPLAYED = 0.15;
+var PLAYED_HOURS_THRESHOLD = 0.5;
+var UNPLAYED_BASE = 1;
+var VERDICT_MULTIPLIER = {
+  loved: 2,
+  liked: 1.25,
+  bounced: 0.25,
+  never: 0
+};
+function titleWeight(title) {
+  const played = title.hours > PLAYED_HOURS_THRESHOLD;
+  const base = played ? Math.log1p(title.hours) : UNPLAYED_BASE;
+  const recency = title.playedRecently ? RECENCY_MULTIPLIER : 1;
+  const ownership = played ? OWNERSHIP_PLAYED : OWNERSHIP_UNPLAYED;
+  return base * recency * ownership;
+}
+function buildTasteVector(owned, answers) {
+  const verdicts = /* @__PURE__ */ new Map();
+  for (const answer of answers ?? []) {
+    verdicts.set(answer.titleId, VERDICT_MULTIPLIER[answer.verdict]);
+  }
+  const accumulator = zeroAxisVector();
+  for (const title of owned) {
+    const weight = titleWeight(title) * (verdicts.get(title.id) ?? 1);
+    if (weight === 0) {
+      continue;
+    }
+    for (const axis of AXES) {
+      accumulator[axis] += weight * title.axes[axis];
+    }
+  }
+  const norm = l2Norm(accumulator);
+  if (norm === 0) {
+    return accumulator;
+  }
+  for (const axis of AXES) {
+    accumulator[axis] /= norm;
+  }
+  return accumulator;
+}
+
+// src/confidence.ts
+var CONFIDENCE_SCALE = 4;
+function axisConfidence(owned) {
+  const evidence = zeroAxisVector();
+  for (const title of owned) {
+    const weight = titleWeight(title);
+    for (const axis of AXES) {
+      evidence[axis] += weight * title.axes[axis];
+    }
+  }
+  const confidence = zeroAxisVector();
+  for (const axis of AXES) {
+    confidence[axis] = 1 - Math.exp(-evidence[axis] / CONFIDENCE_SCALE);
+  }
+  return confidence;
+}
+
+// src/selectQuizCards.ts
+var NO_OWNED_IDS = /* @__PURE__ */ new Set();
+function informationGain(title, confidence) {
+  let gain = 0;
+  for (const axis of AXES) {
+    gain += (1 - confidence[axis]) * title.axes[axis];
+  }
+  return gain;
+}
+function selectQuizCards(catalog, conf, count, ownedIds = NO_OWNED_IDS) {
+  if (count <= 0) {
+    return [];
+  }
+  return catalog.filter((title) => !ownedIds.has(title.id)).map((title) => ({ id: title.id, gain: informationGain(title, conf) })).sort((left, right) => right.gain - left.gain).slice(0, count).map((candidate) => candidate.id);
+}
+
+// src/score.ts
+var NEUTRAL_QUALITY = 0.8;
+var QUALITY_FLOOR = 0.6;
+var QUALITY_RANGE = 0.4;
+var CRITIC_SCORE_MAX = 100;
+var NOVELTY_STRENGTH = 0.2;
+var MOOD_STRENGTH = 0.5;
+function moodWeights(mood) {
+  if (mood === void 0) {
+    return [];
+  }
+  const weights = [];
+  for (const axis of AXES) {
+    const weight = mood[axis];
+    if (weight !== void 0 && weight > 0) {
+      weights.push({ axis, weight });
+    }
+  }
+  return weights;
+}
+function qualityTerm(criticScore) {
+  if (criticScore === null) {
+    return NEUTRAL_QUALITY;
+  }
+  const clamped = Math.min(Math.max(criticScore, 0), CRITIC_SCORE_MAX);
+  return QUALITY_FLOOR + QUALITY_RANGE * (clamped / CRITIC_SCORE_MAX);
+}
+function noveltyTerm(axes) {
+  let sum = 0;
+  let peak = 0;
+  for (const axis of AXES) {
+    sum += axes[axis];
+    peak = Math.max(peak, axes[axis]);
+  }
+  if (sum === 0) {
+    return 1;
+  }
+  return 1 - NOVELTY_STRENGTH * (peak / sum);
+}
+function moodTerm(axes, mood) {
+  if (mood.length === 0) {
+    return 1;
+  }
+  let weighted = 0;
+  let total = 0;
+  for (const entry of mood) {
+    weighted += entry.weight * axes[entry.axis];
+    total += entry.weight;
+  }
+  return 1 + MOOD_STRENGTH * (weighted / total);
+}
+function zeroRow(id) {
+  return { id, score: 0, terms: zeroAxisVector() };
+}
+function scoreOne(context, title) {
+  if (context.ownedIds.has(title.id)) {
+    return zeroRow(title.id);
+  }
+  if (!title.platforms.some((platform) => context.allowed.has(platform))) {
+    return zeroRow(title.id);
+  }
+  const denominator = context.tasteNorm * l2Norm(title.axes);
+  if (denominator === 0) {
+    return zeroRow(title.id);
+  }
+  const gain = noveltyTerm(title.axes) * qualityTerm(title.criticScore) * moodTerm(title.axes, context.mood);
+  const terms = zeroAxisVector();
+  let score = 0;
+  for (const axis of AXES) {
+    const term = context.taste[axis] * title.axes[axis] / denominator * gain;
+    terms[axis] = term;
+    score += term;
+  }
+  return { id: title.id, score, terms };
+}
+function scoreCatalog(taste, catalog, opts) {
+  const context = {
+    taste,
+    tasteNorm: l2Norm(taste),
+    ownedIds: opts.ownedIds,
+    allowed: new Set(opts.allowedPlatforms),
+    mood: moodWeights(opts.mood)
+  };
+  const rows = catalog.map((title) => scoreOne(context, title));
+  rows.sort((left, right) => right.score - left.score);
+  return rows;
+}
+
+// src/diversify.ts
+function clusterOf(terms) {
+  let best = AXES[0];
+  let bestValue = -Infinity;
+  for (const axis of GENRE_AXES) {
+    if (terms[axis] > bestValue) {
+      bestValue = terms[axis];
+      best = axis;
+    }
+  }
+  return best;
+}
+function diversify(scored, limit, maxPerCluster) {
+  const perCluster = /* @__PURE__ */ new Map();
+  const out = [];
+  for (const row of scored) {
+    if (out.length >= limit) {
+      break;
+    }
+    const cluster = clusterOf(row.terms);
+    const taken = perCluster.get(cluster) ?? 0;
+    if (taken >= maxPerCluster) {
+      continue;
+    }
+    perCluster.set(cluster, taken + 1);
+    out.push(row);
+  }
+  return out;
+}
+
+// src/explain.ts
+var TOP_AXIS_COUNT = 3;
+function nearestOwnedId(axes, owned) {
+  let best = null;
+  let bestSimilarity = -Infinity;
+  for (const title of owned) {
+    const similarity = cosine(axes, title.axes);
+    if (similarity > bestSimilarity) {
+      bestSimilarity = similarity;
+      best = title.id;
+    }
+  }
+  return best;
+}
+function explain(taste, title, owned) {
+  const rows = scoreCatalog(taste, [title], {
+    ownedIds: /* @__PURE__ */ new Set(),
+    allowedPlatforms: title.platforms
+  });
+  const terms = rows[0]?.terms ?? zeroAxisVector();
+  const topAxes = AXES.filter((axis) => terms[axis] > 0).sort((left, right) => terms[right] - terms[left]).slice(0, TOP_AXIS_COUNT);
+  return {
+    topAxes,
+    nearestOwnedId: nearestOwnedId(title.axes, owned),
+    gapPlatform: title.platforms.length === 1 ? title.platforms[0] ?? null : null
+  };
+}
+
+export { AXES, GENRE_AXES, GENRE_AXIS_COUNT, axisConfidence, buildTasteVector, clusterOf, cosine, diversify, dot, explain, l2Norm, scoreCatalog, selectQuizCards, titleWeight, zeroAxisVector };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/axes.ts","../src/buildTasteVector.ts","../src/confidence.ts","../src/selectQuizCards.ts","../src/score.ts","../src/diversify.ts","../src/explain.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * The canonical axis list. 18 genre axes followed by 8 structure-and-feel axes.\n * The ORDER is part of the contract: everything downstream that talks about\n * \"genre clusters\" means the first GENRE_AXIS_COUNT entries of this array.\n */\nexport const AXES = [\n  // genre (18)\n  'shooter', 'action', 'rpg', 'jrpg', 'strategy', 'simulation', 'racing', 'sports', 'platformer',\n  'puzzle', 'horror', 'adventure', 'roguelike', 'fighting', 'metroidvania', 'soulslike', 'mmo', 'survival',\n  // structure and feel (8)\n  'sessionLength', 'difficulty', 'narrative', 'coop', 'competitive', 'relaxing', 'replayability', 'artForward',\n] as const;\n\nexport type AxisKey = typeof AXES[number];\n\n/** Every value is 0..1. */\nexport type AxisVector = Record<AxisKey, number>;\n\nexport const GENRE_AXIS_COUNT = 18;\n\n/** The genre half of AXES - what `diversify` clusters on. */\nexport const GENRE_AXES: readonly AxisKey[] = AXES.slice(0, GENRE_AXIS_COUNT);\n\nexport function zeroAxisVector(): AxisVector {\n  const out = {} as AxisVector;\n  for (const axis of AXES) {\n    out[axis] = 0;\n  }\n  return out;\n}\n\nexport function l2Norm(vector: AxisVector): number {\n  let sum = 0;\n  for (const axis of AXES) {\n    sum += vector[axis] * vector[axis];\n  }\n  return Math.sqrt(sum);\n}\n\nexport function dot(left: AxisVector, right: AxisVector): number {\n  let sum = 0;\n  for (const axis of AXES) {\n    sum += left[axis] * right[axis];\n  }\n  return sum;\n}\n\n/** Cosine similarity, defined as 0 (not NaN) when either side has no magnitude. */\nexport function cosine(left: AxisVector, right: AxisVector): number {\n  const denominator = l2Norm(left) * l2Norm(right);\n  if (denominator === 0) {\n    return 0;\n  }\n  return dot(left, right) / denominator;\n}\n","import { AXES, l2Norm, zeroAxisVector } from './axes';\nimport type { AxisVector } from './axes';\nimport type { OwnedTitle, QuizAnswer } from './types';\n\nconst RECENCY_MULTIPLIER = 2.0;\nconst OWNERSHIP_PLAYED = 1.0;\nconst OWNERSHIP_UNPLAYED = 0.15;\n/** Below this, a title counts as owned-but-unplayed; log1p would score it 0 and erase it. */\nconst PLAYED_HOURS_THRESHOLD = 0.5;\nconst UNPLAYED_BASE = 1;\n\nconst VERDICT_MULTIPLIER: Record<QuizAnswer['verdict'], number> = {\n  loved: 2,\n  liked: 1.25,\n  bounced: 0.25,\n  never: 0,\n};\n\n/**\n * weight = log1p(hours) * recency * ownership.\n *\n * recency is 2.0 when the title was played recently, else 1.0.\n * ownership is 1.0 when hours > 0.5, else 0.15.\n * For an unplayed title log1p(hours) is 0, which would erase the title entirely,\n * so the log term is replaced by UNPLAYED_BASE and only the 0.15 ownership weight remains.\n */\nexport function titleWeight(title: OwnedTitle): number {\n  const played = title.hours > PLAYED_HOURS_THRESHOLD;\n  const base = played ? Math.log1p(title.hours) : UNPLAYED_BASE;\n  const recency = title.playedRecently ? RECENCY_MULTIPLIER : 1;\n  const ownership = played ? OWNERSHIP_PLAYED : OWNERSHIP_UNPLAYED;\n  return base * recency * ownership;\n}\n\n/**\n * Quiz answers modulate the weight of the OWNED title they name. An answer whose\n * titleId is not in the library is ignored - the vector is built from what the user\n * actually has, and a verdict on something they do not own carries no axes to add.\n */\nexport function buildTasteVector(owned: OwnedTitle[], answers?: QuizAnswer[]): AxisVector {\n  const verdicts = new Map<string, number>();\n  for (const answer of answers ?? []) {\n    verdicts.set(answer.titleId, VERDICT_MULTIPLIER[answer.verdict]);\n  }\n\n  const accumulator = zeroAxisVector();\n  for (const title of owned) {\n    const weight = titleWeight(title) * (verdicts.get(title.id) ?? 1);\n    if (weight === 0) {\n      continue;\n    }\n    for (const axis of AXES) {\n      accumulator[axis] += weight * title.axes[axis];\n    }\n  }\n\n  const norm = l2Norm(accumulator);\n  if (norm === 0) {\n    return accumulator;\n  }\n  for (const axis of AXES) {\n    accumulator[axis] /= norm;\n  }\n  return accumulator;\n}\n","import { AXES, zeroAxisVector } from './axes';\nimport type { AxisKey } from './axes';\nimport { titleWeight } from './buildTasteVector';\nimport type { OwnedTitle } from './types';\n\n/** Weighted evidence at which an axis reaches ~63% confidence. */\nconst CONFIDENCE_SCALE = 4;\n\n/**\n * How much the library actually tells us about each axis, 0..1.\n * An axis no owned title expresses has zero evidence and therefore zero confidence -\n * which is what `selectQuizCards` targets.\n */\nexport function axisConfidence(owned: OwnedTitle[]): Record<AxisKey, number> {\n  const evidence = zeroAxisVector();\n  for (const title of owned) {\n    const weight = titleWeight(title);\n    for (const axis of AXES) {\n      evidence[axis] += weight * title.axes[axis];\n    }\n  }\n\n  const confidence = zeroAxisVector();\n  for (const axis of AXES) {\n    confidence[axis] = 1 - Math.exp(-evidence[axis] / CONFIDENCE_SCALE);\n  }\n  return confidence;\n}\n","import { AXES } from './axes';\nimport type { AxisKey } from './axes';\nimport type { CatalogTitle } from './types';\n\nconst NO_OWNED_IDS: ReadonlySet<string> = new Set<string>();\n\n/**\n * Information gain: how much of this title's axis mass sits on the axes we are LEAST\n * confident about. A card that only expresses axes we already understand teaches nothing.\n */\nfunction informationGain(title: CatalogTitle, confidence: Record<AxisKey, number>): number {\n  let gain = 0;\n  for (const axis of AXES) {\n    gain += (1 - confidence[axis]) * title.axes[axis];\n  }\n  return gain;\n}\n\n/**\n * `ownedIds` is optional and defaults to empty. It is a parameter rather than a\n * pre-filter on `catalog` so a caller cannot forget it and quiz the user on games\n * they already have.\n */\nexport function selectQuizCards(\n  catalog: CatalogTitle[],\n  conf: Record<AxisKey, number>,\n  count: number,\n  ownedIds: ReadonlySet<string> = NO_OWNED_IDS,\n): string[] {\n  if (count <= 0) {\n    return [];\n  }\n  return catalog\n    .filter((title) => !ownedIds.has(title.id))\n    .map((title) => ({ id: title.id, gain: informationGain(title, conf) }))\n    .sort((left, right) => right.gain - left.gain)\n    .slice(0, count)\n    .map((candidate) => candidate.id);\n}\n","import { AXES, l2Norm, zeroAxisVector } from './axes';\nimport type { AxisKey, AxisVector } from './axes';\nimport type { CatalogTitle, ScoreOptions, ScoredTitle } from './types';\n\n/** Applied when a title has no critic score at all - absence is neutral, not bad. */\nconst NEUTRAL_QUALITY = 0.8;\nconst QUALITY_FLOOR = 0.6;\nconst QUALITY_RANGE = 0.4;\nconst CRITIC_SCORE_MAX = 100;\n/** How far a one-note title is discounted against a broad one. */\nconst NOVELTY_STRENGTH = 0.2;\n/** Maximum lift a fully matched mood can apply. */\nconst MOOD_STRENGTH = 0.5;\n\ninterface MoodWeight { axis: AxisKey; weight: number }\n\ninterface ScoreContext {\n  taste: AxisVector;\n  tasteNorm: number;\n  ownedIds: Set<string>;\n  allowed: Set<string>;\n  mood: MoodWeight[];\n}\n\nfunction moodWeights(mood: Partial<AxisVector> | undefined): MoodWeight[] {\n  if (mood === undefined) {\n    return [];\n  }\n  const weights: MoodWeight[] = [];\n  for (const axis of AXES) {\n    const weight = mood[axis];\n    if (weight !== undefined && weight > 0) {\n      weights.push({ axis, weight });\n    }\n  }\n  return weights;\n}\n\nfunction qualityTerm(criticScore: number | null): number {\n  if (criticScore === null) {\n    return NEUTRAL_QUALITY;\n  }\n  const clamped = Math.min(Math.max(criticScore, 0), CRITIC_SCORE_MAX);\n  return QUALITY_FLOOR + QUALITY_RANGE * (clamped / CRITIC_SCORE_MAX);\n}\n\n/** Discounts a title whose axis mass is concentrated on a single axis. */\nfunction noveltyTerm(axes: AxisVector): number {\n  let sum = 0;\n  let peak = 0;\n  for (const axis of AXES) {\n    sum += axes[axis];\n    peak = Math.max(peak, axes[axis]);\n  }\n  if (sum === 0) {\n    return 1;\n  }\n  return 1 - NOVELTY_STRENGTH * (peak / sum);\n}\n\nfunction moodTerm(axes: AxisVector, mood: MoodWeight[]): number {\n  if (mood.length === 0) {\n    return 1;\n  }\n  let weighted = 0;\n  let total = 0;\n  for (const entry of mood) {\n    weighted += entry.weight * axes[entry.axis];\n    total += entry.weight;\n  }\n  return 1 + MOOD_STRENGTH * (weighted / total);\n}\n\nfunction zeroRow(id: string): ScoredTitle {\n  return { id, score: 0, terms: zeroAxisVector() };\n}\n\nfunction scoreOne(context: ScoreContext, title: CatalogTitle): ScoredTitle {\n  if (context.ownedIds.has(title.id)) {\n    return zeroRow(title.id);\n  }\n  if (!title.platforms.some((platform) => context.allowed.has(platform))) {\n    return zeroRow(title.id);\n  }\n  const denominator = context.tasteNorm * l2Norm(title.axes);\n  if (denominator === 0) {\n    return zeroRow(title.id);\n  }\n\n  const gain = noveltyTerm(title.axes) * qualityTerm(title.criticScore) * moodTerm(title.axes, context.mood);\n  const terms = zeroAxisVector();\n  let score = 0;\n  for (const axis of AXES) {\n    const term = (context.taste[axis] * title.axes[axis] / denominator) * gain;\n    terms[axis] = term;\n    score += term;\n  }\n  return { id: title.id, score, terms };\n}\n\n/**\n * score = cosine(taste, title) * platformGate * novelty * quality * mood.\n * `terms` is the per-axis decomposition of that product, so the terms sum to the score.\n * Rows come back sorted by score, descending.\n */\nexport function scoreCatalog(taste: AxisVector, catalog: CatalogTitle[], opts: ScoreOptions): ScoredTitle[] {\n  const context: ScoreContext = {\n    taste,\n    tasteNorm: l2Norm(taste),\n    ownedIds: opts.ownedIds,\n    allowed: new Set(opts.allowedPlatforms),\n    mood: moodWeights(opts.mood),\n  };\n  const rows = catalog.map((title) => scoreOne(context, title));\n  rows.sort((left, right) => right.score - left.score);\n  return rows;\n}\n","import { AXES, GENRE_AXES } from './axes';\nimport type { AxisKey } from './axes';\nimport type { ScoredTitle } from './types';\n\n/** The genre axis carrying the largest share of a row's score. */\nexport function clusterOf(terms: Record<AxisKey, number>): AxisKey {\n  let best: AxisKey = AXES[0];\n  let bestValue = -Infinity;\n  for (const axis of GENRE_AXES) {\n    if (terms[axis] > bestValue) {\n      bestValue = terms[axis];\n      best = axis;\n    }\n  }\n  return best;\n}\n\n/**\n * Greedy re-rank over the incoming order: keep the highest-scoring rows but never let\n * one genre cluster take more than `maxPerCluster` slots. Relative order is preserved.\n */\nexport function diversify(scored: ScoredTitle[], limit: number, maxPerCluster: number): ScoredTitle[] {\n  const perCluster = new Map<AxisKey, number>();\n  const out: ScoredTitle[] = [];\n  for (const row of scored) {\n    if (out.length >= limit) {\n      break;\n    }\n    const cluster = clusterOf(row.terms);\n    const taken = perCluster.get(cluster) ?? 0;\n    if (taken >= maxPerCluster) {\n      continue;\n    }\n    perCluster.set(cluster, taken + 1);\n    out.push(row);\n  }\n  return out;\n}\n","import { AXES, cosine, zeroAxisVector } from './axes';\nimport type { AxisKey, AxisVector } from './axes';\nimport { scoreCatalog } from './score';\nimport type { CatalogTitle, Explanation, OwnedTitle } from './types';\n\nconst TOP_AXIS_COUNT = 3;\n\nfunction nearestOwnedId(axes: AxisVector, owned: OwnedTitle[]): string | null {\n  let best: string | null = null;\n  let bestSimilarity = -Infinity;\n  for (const title of owned) {\n    const similarity = cosine(axes, title.axes);\n    if (similarity > bestSimilarity) {\n      bestSimilarity = similarity;\n      best = title.id;\n    }\n  }\n  return best;\n}\n\n/**\n * The axes come from the REAL scoring terms: `explain` runs the title back through\n * `scoreCatalog` rather than recomputing a lookalike heuristic, so an explanation can\n * never disagree with the ranking it explains.\n *\n * `gapPlatform` names the platform of a title that exists on exactly one - the case\n * where owning that platform is the thing standing between the user and the game.\n */\nexport function explain(taste: AxisVector, title: CatalogTitle, owned: OwnedTitle[]): Explanation {\n  const rows = scoreCatalog(taste, [title], {\n    ownedIds: new Set<string>(),\n    allowedPlatforms: title.platforms,\n  });\n  const terms: Record<AxisKey, number> = rows[0]?.terms ?? zeroAxisVector();\n  const topAxes = AXES.filter((axis) => terms[axis] > 0)\n    .sort((left, right) => terms[right] - terms[left])\n    .slice(0, TOP_AXIS_COUNT);\n\n  return {\n    topAxes,\n    nearestOwnedId: nearestOwnedId(title.axes, owned),\n    gapPlatform: title.platforms.length === 1 ? title.platforms[0] ?? null : null,\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@dloizides/taste-engine",
+  "version": "0.1.0",
+  "description": "Domain-agnostic weighted-vector taste modelling: build a normalised 26-axis taste vector from a played library, measure per-axis confidence, pick quiz cards that reduce uncertainty, score and diversify a catalogue, and explain a recommendation from its real scoring terms. Pure TypeScript, zero I/O, zero deps.",
+  "keywords": [
+    "recommender",
+    "taste-vector",
+    "cosine-similarity",
+    "scoring",
+    "diversify",
+    "games",
+    "dloizides"
+  ],
+  "author": "dloizides",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openmindednewby/taste-engine.git"
+  },
+  "homepage": "https://github.com/openmindednewby/taste-engine#readme",
+  "bugs": {
+    "url": "https://github.com/openmindednewby/taste-engine/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsup",
+    "build:watch": "tsup --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "security:audit": "npm audit --audit-level=high",
+    "prepublishOnly": "npm run clean && npm run build && npm run test"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.19.32",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "rimraf": "^5.0.0",
+    "ts-jest": "^29.1.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}