lenskit.basic#

Basic and baseline pipeline components.

class lenskit.basic.BiasModel(damping, global_bias, items=None, item_biases=None, users=None, user_biases=None)#

Bases: object

User-item bias models learned from rating data. The BiasScorer class uses this model to score items in a pipeline; the model is reusable in other components that need user-item bias models.

This implements the following model:

\[b_{ui} = b_g + b_i + b_u\]

where \(b_g\) is the global bias (global mean rating), \(b_i\) is item bias, and \(b_u\) is the user bias. With the provided damping values \(\beta_{\mathrm{u}}\) and \(\beta_{\mathrm{i}}\), they are computed as follows:

\[\begin{align*} b_g & = \frac{\sum_{r_{ui} \in R} r_{ui}}{|R|} & b_i & = \frac{\sum_{r_{ui} \in R_i} (r_{ui} - b_g)}{|R_i| + \beta_{\mathrm{i}}} & b_u & = \frac{\sum_{r_{ui} \in R_u} (r_{ui} - b_g - b_i)}{|R_u| + \beta_{\mathrm{u}}} \end{align*}\]

The damping values can be interpreted as the number of default (mean) ratings to assume a priori for each user or item, damping low-information users and items towards a mean instead of permitting them to take on extreme values based on few ratings.

Stability:
Caller (see Stability Levels).
Parameters:
compute_for_items(items, user_id=None, user_items=None, *, bias=None)#

Compute the personalized biases for a set of itemsm and optionally a user. The user can be specified either by their identifier or by a list of ratings.

Parameters:

  • items (ItemList) – The items to score.

  • user – The user identifier.

  • user_items (ItemList | None) – The user’s items, with ratings (takes precedence over user if both are supplied). If the supplied list does not have a rating field, it is ignored.

  • bias (float | None) – A pre-computed user bias.

  • user_id (int | str | bytes | integer[Any] | str_ | bytes_ | object_ | None)

Returns:

A tuple of the overall bias scores for the specified items and user, and the user’s bias (needed to de-normalize scores efficiently later). If a user bias is provided instead of user information, only the composite bias scores are returned.

item_biases: ndarray[tuple[int], dtype[float32]] | None = None#

The item offsets (\(b_i\) values).

items: Vocabulary | None = None#

Vocabulary of items.

classmethod learn(data, damping=0.0, *, entities=frozenset({'item', 'user'}))#

Learn a bias model and its parameters from a dataset.

Parameters:

  • data (Dataset) – The dataset from which to learn the bias model.

  • damping (float | dict[Literal['user', 'item'], float] | tuple[float, float]) – Bayesian damping to apply to computed biases. Either a number, to damp both user and item biases the same amount, or a (user,item) tuple providing separate damping values.

  • items – Whether to compute item biases

  • users – Whether to compute user biases

  • entities (Container[Literal['user', 'item']])

Return type:

Self

transform_matrix(matrix)#

Transform a sparse ratings matrix by subtracting biases.

Parameters:

matrix (Tensor | coo_array) – The matrix to transform.

user_biases: ndarray[tuple[int], dtype[float32]] | None = None#

The user offsets (\(b_u\) values).

users: Vocabulary | None = None#

Vocabulary of users.

damping: float | dict[Literal['user', 'item'], float]#

The mean damping terms.

global_bias: float#

The global bias term.

class lenskit.basic.BiasConfig(*, entities={'item', 'user'}, damping=0.0)#

Bases: BaseModel

Configuration for BiasScorer.

Parameters:

  • entities (Annotated[set[Literal['user', 'item']], ~pydantic.functional_serializers.PlainSerializer(func=~lenskit.basic.bias.<lambda>, return_type=list[str], when_used=always)])

  • damping (Annotated[float, Ge(ge=0)] | dict[Literal['user', 'item'], ~typing.Annotated[float, ~annotated_types.Ge(ge=0)]])

entity_damping(entity)#

Look up the damping for a particular entity type.

Parameters:

entity (Literal['user', 'item'])

Return type:

float

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

entities: Annotated[set[Literal['user', 'item']], PlainSerializer(lambda s: sorted(s), return_type=list[str])]#

The entities to compute biases for, in addition to global bais. Defaults to users and items.

class lenskit.basic.BiasScorer(config=None, **kwargs)#

Bases: Component[ItemList, …], Trainable

A user-item bias rating prediction model. This component uses BiasModel to predict ratings for users and items.

Parameters:

  • config (BiasConfig) – The component configuration.

  • kwargs (Any)

Stability:
Caller (see Stability Levels).
train(data, options=TrainingOptions(retrain=True, device=None, rng=None))#

Train the bias model on some rating data.

Parameters:
Returns:

The trained bias object.

class lenskit.basic.PopConfig(*, score='quantile')#

Bases: BaseModel

Configuration for popularity scoring.

Parameters:

score (Literal['quantile', 'rank', 'count'])

model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

score: Literal['quantile', 'rank', 'count']#

The method for computing popularity scores. For all methods, higher scores represent more popular items.

class lenskit.basic.PopScorer(config=None, **kwargs)#

Bases: Component[ItemList, …], Trainable

Score items by their popularity. Use with TopN to get a most-popular-items recommender.

Stability:
Caller (see Stability Levels).
Parameters:
item_pop_#

Item popularity scores.

train(data, options=TrainingOptions(retrain=True, device=None, rng=None))#

Train the model to learn its parameters from a training dataset.

Parameters:
class lenskit.basic.TopNConfig(*, n=None)#

Bases: BaseModel

Configuration for top-N ranking.

Parameters:

n (int | None)

model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n: int | None#

The number of items to return. -1 or None to return all scored items.

class lenskit.basic.TopNRanker(config=None, **kwargs)#

Bases: Component[ItemList, …]

Rank scored items by their score and take the top N. The ranking length can be passed either at runtime or at component instantiation time, with the latter taking precedence.

Stability:
Caller (see Stability Levels).
Parameters:
class lenskit.basic.RandomSelector(config=None, **kwargs)#

Bases: Component[ItemList, …]

Randomly select items from a candidate list.

Stability:
Caller (see Stability Levels).
Parameters:

  • n – The number of items to select, or -1 to randomly permute the items.

  • rng – The random number generator or specification (see Random Seeds). This class supports derivable RNGs.

  • config (RandomConfig)

class lenskit.basic.SoftmaxRanker(config=None, **kwargs)#

Bases: Component[ItemList, …]

Stochastic top-N ranking with softmax sampling.

This uses the “softmax” sampling method, a more efficient approximation of Plackett-Luce sampling than even the Gumbell trick, as documented by `Tim Vieira`_. It expects a scored list of input items, and samples n items, with selection probabilities proportional to their scores.

Warning

This ranker does not actually compute a softmax

Deprecated since version 2025.3: This ranker has been replaced with the lenskit.stochastic.StochasticTopNRanker. It will be removed in LensKit 2026.

Note

Negative scores are clamped to (approximately) zero.

Stability:
Caller (see Stability Levels).
Parameters:

  • n – The number of items to return (-1 to return unlimited).

  • rng – The random number generator or specification (see Random Seeds). This class supports derivable RNGs.

  • config (RandomConfig)

class lenskit.basic.UserTrainingHistoryLookup(config=None, **kwargs)#

Bases: Component[ItemList, …], Trainable

Look up a user’s history from the training data.

Stability:
Caller (see Stability Levels).
Parameters:
train(data, options=TrainingOptions(retrain=True, device=None, rng=None))#

Train the model to learn its parameters from a training dataset.

Parameters:
class lenskit.basic.TrainingItemsCandidateConfig(exclude='query')#

Bases: object

Configuration for TrainingItemsCandidateSelector.

Parameters:

exclude (None | Literal['query', 'all', 'history', 'session', 'context'] | ~collections.abc.Sequence[~typing.Literal['history', 'session', 'context']])

exclude: None | Literal['query', 'all', 'history', 'session', 'context'] | Sequence[Literal['history', 'session', 'context']] = 'query'#

Specify the items from the query to exclude from the candidates.

None

Exclude no items from the request.

"query"

Excludes the query items (RecQuery.query_items) from the request. This is the default.

"all"

Exclude all mentioned items from the request.

"history", "session", "context"

Exclude the specified items from the request.

class lenskit.basic.TrainingItemsCandidateSelector(config=None, **kwargs)#

Bases: TrainingCandidateSelectorBase

Candidate selector that selects all known items from the training data, optionally excluding certain items from the query (i.e., the request user’s history).

In order to look up the user’s history in the training data, this needs to be combined with a component like UserTrainingHistoryLookup.

Stability:
Caller (see Stability Levels).
Parameters:
class lenskit.basic.UnratedTrainingItemsCandidateSelector(config=None, **kwargs)#

Bases: TrainingCandidateSelectorBase

Candidate selector that selects all known items from the training data that do not appear in the request user’s history (RecQuery.history_items). If no item history is available, then all training items are returned.

In order to look up the user’s history in the training data, this needs to be combined with a component like UserTrainingHistoryLookup.

Deprecated since version 2025.6: Use TrainingItemsCandidateSelector with default settings or the "history" option for TrainingItemsCandidateConfig.exclude instead.

Stability:
Caller (see Stability Levels).
Parameters:

  • config (None)

  • kwargs (Any)

class lenskit.basic.AllTrainingItemsCandidateSelector(config=None, **kwargs)#

Bases: TrainingCandidateSelectorBase

Candidate selector that selects all known items from the training data.

Deprecated since version 2025.6: Use TrainingItemsCandidateSelector with None for TrainingItemsCandidateConfig.exclude instead.

Stability:
Caller (see Stability Levels).
Parameters:

  • config (None)

  • kwargs (Any)

class lenskit.basic.FallbackScorer(config=None, **kwargs)#

Bases: Component[ItemList, …]

Scoring component that fills in missing scores using a fallback.

Stability:
Caller (see Stability Levels).
Parameters:

  • config (None)

  • kwargs (Any)

Modules

bias

Bias scoring model.

candidates

composite

history

Components that look up user history from the training data.

popularity

random

topn

Basic Top-N ranking.