Skip to content

Quickstart

This page shows the core plug&play path: bring donor scores over warm items, fit one transfer method, and predict scores for cold-start items. It does not use warmtransfer.bench.

Install

uv sync

python -m pip install warm-transfer

Run the example

The full runnable script lives in the repository and is included here directly, so the docs cannot drift away from the checked example.

Note

The examples/ directory is only available when you clone the repository; it is not shipped in the pip wheel. If you installed via pip, copy the snippet below into a local file and run it directly.

"""Minimal plug&play warmtransfer example without warmtransfer.bench.

The user brings warm scores from an already trained donor and content for warm/cold items.
LinMap learns a mapping "content -> vector of per-user scores" and predicts
scores for new items.
"""

from __future__ import annotations

import numpy as np
import pandas as pd

from warmtransfer.columns import Columns as C
from warmtransfer.methods import LinMap
from warmtransfer.types import ItemFeatures, TransferInputs

warm_features = ItemFeatures(
    item_ids=np.array([10, 11]),
    matrix=np.array([[1.0, 0.0], [0.0, 1.0]]),
    feature_names=["genre_action", "genre_drama"],
)
cold_features = ItemFeatures(
    item_ids=np.array([20]),
    matrix=np.array([[1.0, 0.0]]),
    feature_names=["genre_action", "genre_drama"],
)

donor_scores = pd.DataFrame(
    {
        C.User: [1, 1, 2, 2],
        C.Item: [10, 11, 10, 11],
        C.Score: [5.0, 1.0, 1.0, 5.0],
    }
)

inputs = TransferInputs(
    donor_scores=donor_scores,
    warm_features=warm_features,
    cold_features=cold_features,
)

reco = LinMap(alpha=1.0).fit(inputs, seed=42).predict(
    user_ids=np.array([1, 2]),
    cold_item_ids=np.array([20]),
)

if __name__ == "__main__":
    print(reco.to_string(index=False))

Expected output:

 user_id  item_id  score
       1       20    4.0
       2       20    2.0

What happened

  1. donor_scores is a long-format table [user_id, item_id, score] over warm items only.
  2. warm_features and cold_features align item ids with content vectors.
  3. LinMap.fit(inputs, seed=42) learns a linear map from item content to a vector of donor scores.
  4. predict(user_ids, cold_item_ids) returns long-format scores for all requested user-item pairs.

Next steps