@recoengine/modifiers

Standard score modifiers for @recoengine/core: fatigue, novelty, boosts and penalties.

npm i @recoengine/modifiers @recoengine/core

Already using recoengine? These are re-exported from it — no separate install needed.

What it is

A strategy answers "how well does this fit"; a modifier corrects the finished score — "is it appropriate to show this now". The split matters: fatigue and novelty multiply (so a subtractive penalty can't leave a 0.98 item stubbornly on top), boosts add. Each is a factory returning a ScoreModifier you register with .use(...).

Modifiers read only the interaction history (ctx.history) and the clock (ctx.now) — not your payload, not a profile — which is why they work in any domain.

| Factory | Effect | | --- | --- | | fatigueModifier | multiplicatively damps items the user has seen a lot; recovers over time | | noveltyModifier | multiplicatively boosts unfamiliar items, scaled by profile saturation | | boostModifier | additively boosts (or, with a negative amount, penalises) chosen items — not a filter |

Also exported: saturationOf(history), the domain-neutral measure of how uneven a user's history is, used by the modifiers and available on its own.

Usage

import { createEngine } from '@recoengine/core'
import { fatigueModifier, boostModifier } from '@recoengine/modifiers'

const engine = createEngine<Track>()
  .use(myProvider)
  .use(myStrategies)
  .use(fatigueModifier({ threshold: 2, halfLife: 3 })) // seen >2 times → damp; recover over ~3 days
  .use(boostModifier({ items: [pinnedId], amount: 0.3 }))
  .configure({ limits: { maxCandidates: 5_000, maxLimit: 100, timeoutMs: 200 } })
  .build()

Options (FatigueModifierOptions, NoveltyModifierOptions, BoostModifierOptions) tune the thresholds, half-lives, and targets.

Links

• Repository & full docs: https://github.com/waleron07/recommendationEngine

MIT