Skip to content

Contracts & types

warm-transfer is intentionally small at the boundaries. Most extension points are one interface plus one registry decorator. Full autogenerated signatures live in the API reference; this page explains how the contracts fit together.

Columns

All public DataFrames use names from warmtransfer.columns.Columns: user_id, item_id, weight, datetime, score and rank. This keeps direct usage, benchmark adapters and metrics aligned.

ColdStartMethod

ColdStartMethod is the core extension point for score transfer.

  • API: warmtransfer.methods.base.ColdStartMethod
  • Registry: warmtransfer.methods.methods
  • Registration: @register_method("name")
  • Fit: fit(TransferInputs, seed) -> self
  • Predict: predict(user_ids, cold_item_ids) -> DataFrame[user_id, item_id, score]
  • Input declaration: requires: frozenset[str]

The requires field is validated before _fit runs, so missing donor_scores, content, similarity, embeddings, train_interactions, item_meta or val fails early.

TransferInputs

API: warmtransfer.types.TransferInputs

The minimum direct-use bundle is usually:

  • donor_scores: warm-only donor scores in long format;
  • warm_features: content vectors aligned with warm item ids;
  • cold_features: content vectors aligned with cold item ids.

Supervised meta-methods additionally need the validation-cold fold (val_interactions, val_cold_features and, when required, val_similarity).

Dataset and ItemFeatures

Dataset holds interactions and optional item content. ItemFeatures guarantees row alignment: matrix[i] belongs to item_ids[i], and subset(ids) preserves the requested order.

ModelAdapter

ModelAdapter is the donor contract used only by warmtransfer.bench.

  • API: warmtransfer.bench.adapters.base.ModelAdapter
  • Registry: warmtransfer.bench.adapters.adapters
  • Registration: @register_adapter("name")
  • Fit: train only on warm interactions;
  • Score: return warm-item scores in long format;
  • Embeddings: optional user/item latent factors for [EMB] methods.

Adapters live in warmtransfer.bench because third-party recommender engines are optional. The core library consumes scores, not model internals.

DatasetLoader and Splitter

DatasetLoader.load() normalizes raw data into Dataset. Splitter.split() creates the warm, validation-cold and test-cold folds and must preserve the anti-leakage invariant.