{"_id":"@buzzr/entertainment-engine","_rev":"3-51bb03f2d402a1eca0171d0fb3217860","name":"@buzzr/entertainment-engine","dist-tags":{"latest":"5.0.0"},"versions":{"0.1.0":{"name":"@buzzr/entertainment-engine","version":"0.1.0","keywords":["sports","entertainment-score","prediction","machine-learning","buzzr","rankings"],"author":{"name":"Sarvesh Chidambaram"},"license":"MIT","_id":"@buzzr/entertainment-engine@0.1.0","maintainers":[{"name":"sarveshsea","email":"sarveshjax@gmail.com"}],"dist":{"shasum":"9e28220bf7dfa406ad6fa3fc4232d374617d0ae9","tarball":"https://registry.npmjs.org/@buzzr/entertainment-engine/-/entertainment-engine-0.1.0.tgz","fileCount":9,"integrity":"sha512-6kkUewkHiF3sGPM65LE3s63oX1ZJp+Ja0FNdEBWQbm+G/O+jEbVzeDlfq2OYinMxsIKSZz2n5RoBkj4vbiaMkg==","signatures":[{"sig":"MEUCIGMWm8g32KTYtXIgcjERWWGFW3/x0cIF52FLL3HzEPG2AiEAhESEfY87xNHR0FgsJi4yar8IcApPrgN2mUT9qB6oTXw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":262390},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"9c1446a04671cb318a80101f6ebc14ef022245f0","scripts":{"test":"vitest run","build":"tsup","prepare":"npm run build","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run typecheck && npm test && npm run build"},"_npmUser":{"name":"sarveshsea","email":"sarveshjax@gmail.com"},"_npmVersion":"10.9.2","description":"Transparent sports entertainment scoring and hybrid ML prediction engine for Buzzr.","directories":{},"_nodeVersion":"22.17.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.6","typescript":"^5.9.3","@types/node":"^22.19.18"},"_npmOperationalInternal":{"tmp":"tmp/entertainment-engine_0.1.0_1778645032102_0.7839568642139854","host":"s3://npm-registry-packages-npm-production"}},"5.0.0":{"name":"@buzzr/entertainment-engine","version":"5.0.0","description":"Transparent sports entertainment scoring, hybrid ML prediction, and personalized game recommendations for Buzzr.","license":"MIT","author":{"name":"Sarvesh Chidambaram"},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts --sourcemap --clean --treeshake --target es2022","typecheck":"tsc --noEmit","test":"vitest run","lint":"eslint src tests","format":"prettier --write src tests","format:check":"prettier --check src tests"},"keywords":["sports","entertainment-score","prediction","machine-learning","recommendations","buzzr","sports-analytics","game-recommendations","watchability","excitement-score","win-probability","sports-data"],"engines":{"node":">=22"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buzzr-app/dfs-engine.git","directory":"packages/entertainment-engine"},"homepage":"https://github.com/Buzzr-app/dfs-engine/tree/main/packages/entertainment-engine","bugs":{"url":"https://github.com/Buzzr-app/dfs-engine/issues"},"_id":"@buzzr/entertainment-engine@5.0.0","gitHead":"b727ec77a02352d6e3a5b21265889c41daedb4f4","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-zVNLeDQGNi301d7W6twgKPezApmvJIMTEOHIZBfuGx1e9thyVGzJemUnehMHiqhB4YvFtIj0BTEYjZdN3hCetQ==","shasum":"34134202e50062f203e864f8180c119b9315a30f","tarball":"https://registry.npmjs.org/@buzzr/entertainment-engine/-/entertainment-engine-5.0.0.tgz","fileCount":9,"unpackedSize":497231,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC/OtI2pUD/w1NMEecjTqvKwKZGfXw/vh+TuBF/pGOYegIhAKUBp/FLEQQFmxq/hUNIiH3qq6MrvWS1BErHn5gzS9UG"}]},"_npmUser":{"name":"sarveshsea","email":"sarveshjax@gmail.com"},"directories":{},"maintainers":[{"name":"sarveshsea","email":"sarveshjax@gmail.com"},{"name":"gangisettyrushil8","email":"gangisettyrushil@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/entertainment-engine_5.0.0_1783385534992_0.5443028449510297"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-13T04:03:51.977Z","modified":"2026-07-07T00:52:15.297Z","0.1.0":"2026-05-13T04:03:52.286Z","5.0.0":"2026-07-07T00:52:15.137Z"},"author":{"name":"Sarvesh Chidambaram"},"license":"MIT","keywords":["sports","entertainment-score","prediction","machine-learning","recommendations","buzzr","sports-analytics","game-recommendations","watchability","excitement-score","win-probability","sports-data"],"description":"Transparent sports entertainment scoring, hybrid ML prediction, and personalized game recommendations for Buzzr.","maintainers":[{"name":"sarveshsea","email":"sarveshjax@gmail.com"},{"name":"gangisettyrushil8","email":"gangisettyrushil@gmail.com"}],"readme":"# @buzzr/entertainment-engine\n\nTransparent sports entertainment scoring, hybrid ML prediction, and\npersonalized game recommendations for Buzzr.\n\nThe package is intentionally pure: it does not import React Native, Expo,\nSupabase, AsyncStorage, or app services — and it has zero runtime\ndependencies. Apps and jobs provide data through plain objects, then persist\nresults however they choose.\n\n## Core API\n\n```ts\nimport {\n  resolveBuzzScores,\n  enrichGameRowWithBuzzScores,\n  predictGameWithDiagnostics,\n} from '@buzzr/entertainment-engine';\n\nconst resolved = resolveBuzzScores({\n  league: 'NBA',\n  status: 'scheduled',\n  startsAt: '2026-06-12T01:00:00Z',\n  homeTeam: 'Boston Celtics',\n  awayTeam: 'Los Angeles Lakers',\n}, { upcomingLike: true });\n\nconst prediction = predictGameWithDiagnostics({\n  league: 'NBA',\n  status: 'scheduled',\n  startsAt: '2026-06-12T01:00:00Z',\n  homeTeam: 'Boston Celtics',\n  awayTeam: 'Los Angeles Lakers',\n}, {\n  odds: { spread: -1.5, overUnder: 226.5 },\n  teamPower: { home: 9.2, away: 8.7 },\n});\n```\n\n## New in v5\n\n### Injectable clock\n\nEvery time-sensitive entry point accepts an optional `now` (epoch millis or a\n`Date`). It defaults to `Date.now()`, so existing callers are unaffected, but\njobs and tests can pin the clock for full determinism:\n\n```ts\nresolveBuzzScores(game, { upcomingLike: true, now: Date.UTC(2026, 4, 1) });\nenrichGameRowWithBuzzScores(row, { now: Date.UTC(2026, 4, 1) });\npredictGameWithDiagnostics(game, { now: Date.UTC(2026, 4, 1) });\n```\n\n### Timezone-safe primetime detection\n\nPrimetime and weekend detection no longer depend on the host machine's\ntimezone. Game inputs may carry an explicit `venueUtcOffsetMinutes` or\n`localStartHour` (also `venue_utc_offset_minutes` / `local_start_hour` on DB\nrows). When absent, the engine derives US Eastern local time with a proper\nDST calculation (second Sunday in March through first Sunday in November).\n`easternUtcOffsetMinutes(utcMs)` is exported for reuse.\n\n### Team-name normalization\n\nAll rivalry, marquee, and shared-city lookups run through one exported\n`normalizeTeamName` helper: lowercase, trimmed, whitespace-collapsed, and\ndiacritic-insensitive (`'Los Ángeles Lakers'` matches\n`'los angeles lakers'`). The NFL rivalry table now includes modern rivalries\nsuch as Bills–Bengals, Ravens–Steelers, Chiefs–Raiders, Bills–Chiefs, and\nCowboys–49ers.\n\n### ML v5 (`ml-v5`)\n\nThe feature vector grew from 20 to 22 with two appended optional features:\n\n- `searchHeat` — from `context.searchHeat: { home?, away? }`, each in\n  `[-1, 1]`, normalized to `[0, 1]` (absent → neutral `0.5`).\n- `starPower` — from `context.starPower` in `[0, 1]` (absent → `0.5`).\n\nOld 20-length v1 weight arrays remain fully supported: the appended features\nare skipped for them, so v1 predictions are bit-identical to prior releases.\n\n`trainSGD(examples, opts)` upgrades (defaults preserve pre-v5 behavior):\n\n- Feature standardization (on by default) — per-feature mean/std captured\n  during training, stored as `featureMeans`/`featureStds` in the weights and\n  applied automatically at prediction time.\n- `momentum` — classical momentum coefficient (default `0`, plain SGD).\n- `validationSplit` — chronological tail held out for validation, with\n  `earlyStopping: true` and `patience` stopping on validation MAE plateau.\n- `shuffle: true` with `seed` — deterministic per-epoch shuffling via an\n  embedded mulberry32 PRNG.\n- Calibrated confidence — when a validation split exists, piecewise-linear\n  calibration bins built from validation residuals are stored in\n  `confidenceCalibration` and applied by `predictGameWithDiagnostics`\n  (also exported directly as `applyConfidenceCalibration`).\n\nFreshly trained weights carry `modelVersion: 'ml-v5'`\n(`ML_MODEL_VERSION_V5`), and `buildModelRunReport` carries the trained\nmodel's version through to the report.\n\n### Recommendations\n\n```ts\nimport { rankGamesForUser, explainRecommendation } from '@buzzr/entertainment-engine';\n\nconst ranked = rankGamesForUser(\n  [\n    { id: 'game-1', game: celticsLakers, baseScore: 8.1 },\n    { id: 'game-2', game: kingsJazz }, // base score estimated transparently\n  ],\n  {\n    favoriteTeams: ['Boston Celtics'],\n    favoriteLeagues: ['NBA'],\n    teamAffinity: { 'utah jazz': -0.4 },\n    leagueAffinity: { NHL: 0.6 },\n    socialSignal: { 'game-2': 0.8 }, // fire-ratio in [-1, 1] keyed by game id\n  },\n  { now: Date.UTC(2026, 4, 1), limit: 20 },\n);\n\nconst breakdown = explainRecommendation(ranked[0]);\n// { baseScore, personalAdjustment, socialAdjustment, totalScore, factors }\n```\n\nScoring is the base entertainment score (provided `baseScore`, else a\ntransparent estimate) plus a bounded personal-affinity adjustment (±1.5,\n`MAX_AFFINITY_ADJUSTMENT`) and a bounded social adjustment (±0.75,\n`MAX_SOCIAL_ADJUSTMENT`). Ordering is deterministic: ties break by earliest\nstart time, then id. `explainRecommendation` returns the factor list the\napp's BuzzBreakdownSheet renders — base score, personal adjustment, social\nadjustment, and individual signed factor deltas.\n\n## Design\n\n- `resolveBuzzScores` is deterministic and explainable.\n- `predictGameWithDiagnostics` layers trained weights over transparent\n  features and returns factor impacts, input coverage, confidence, and model\n  version metadata.\n- Training helpers accept already-built examples; Supabase extraction belongs\n  in the consuming app or job.\n- `ENGINE_PACKAGE_VERSION` reports the package version (`5.0.0`).\n","readmeFilename":"README.md","homepage":"https://github.com/Buzzr-app/dfs-engine/tree/main/packages/entertainment-engine","repository":{"type":"git","url":"git+https://github.com/Buzzr-app/dfs-engine.git","directory":"packages/entertainment-engine"},"bugs":{"url":"https://github.com/Buzzr-app/dfs-engine/issues"}}