Перейти к содержанию

Контракты и типы

warm-transfer намеренно держит границы маленькими. Большинство extension points — это один интерфейс и один registry decorator. Полные autogenerated signatures живут в API reference на английском; здесь описано, как контракты связаны между собой.

Columns

Все публичные DataFrame используют имена из warmtransfer.columns.Columns: user_id, item_id, weight, datetime, score и rank. Так direct usage, benchmark adapters и metrics остаются совместимыми.

ColdStartMethod

ColdStartMethod — главный extension point для 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]

Поле requires проверяется до _fit, поэтому отсутствие donor_scores, content, similarity, embeddings, train_interactions, item_meta или val падает рано.

TransferInputs

API: warmtransfer.types.TransferInputs

Минимальный bundle при прямом использовании обычно состоит из:

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

Supervised meta-methods дополнительно требуют validation-cold fold (val_interactions, val_cold_features и, когда нужно, val_similarity).

Dataset и ItemFeatures

  • API: warmtransfer.types.Dataset
  • API: warmtransfer.types.ItemFeatures

Dataset хранит interactions и optional item content. ItemFeatures гарантирует row alignment: matrix[i] относится к item_ids[i], а subset(ids) сохраняет запрошенный порядок.

ModelAdapter

ModelAdapter — donor contract, который используется только в 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 для [EMB] methods.

Adapters живут в warmtransfer.bench, потому что сторонние recommender engines optional. Core library потребляет скоры, а не внутренности модели.

DatasetLoader и Splitter

  • API: warmtransfer.bench.datasets.base.DatasetLoader
  • API: warmtransfer.bench.splitters.base.Splitter
  • Registries: datasets and splitters

DatasetLoader.load() нормализует raw data в Dataset. Splitter.split() создаёт warm, validation-cold и test-cold folds и должен сохранять anti-leakage invariant.