01 mixed hybrid model

[UrteUrbonaviciute]

Summary

Adds a Mixed Hybrid recommender that combines the ranked top-10 lists of three different kinds of model:

Model	Kind
ItemKNN	neighbourhood collaborative filtering
BPR	matrix factorisation
ContentBased	content similarity (DistilBERT embeddings of title + genres)

It is separate from the Logistic Regression weighted hybrid. It does not combine scores, because the three models' scores are on different scales. It mixes their ranked lists instead.

How it works

• Per-model shares: in each round, the hybrid takes a set number of movies from each model's list, e.g. ItemKNN=4 BPR=4 ContentBased=2, and repeats until each user has 10 movies. A plain round-robin (one movie per model per round) is included as a baseline.
• No duplicates: removed per user. If a model's next movie is already in the list, the hybrid takes that model's next one instead. A model that runs out of movies is skipped.
• Seen movies: the lists come from run_model.py, which already hides training movies (validation) and training + validation movies (test). The hybrid uses the same split and ground truth as every other model.
• Deterministic: ties are broken by item_id.

Changes

• mixed_hybrid.py: the mixing and evaluation code. The evaluation gives the same numbers as RecBole for ItemKNN and BPR, so comparisons are fair.
• tune_mixed_hybrid.py: tries round-robin and 9 share splits on validation, picks the best by NDCG@10, and saves it to configs/mixed_hybrid_best.yaml.
• run_mixed_hybrid.py: runs that saved split once on test and compares it with each model on its own.
• configs/models/ContentBased.yaml: runs the existing CB model unchanged through run_model.py. No changes to the CB model code or to common.py.
• tests/test_mixed_hybrid.py: tests for duplicates, shares, keeping users separate, missing models, top-k and determinism.
• README.md: how to reproduce the results, plus the results.

Results (ML-100K, seed 2020, ratings ≥ 3)

Validation, a selection of the 10 options tried:

Configuration	NDCG@10
RoundRobin	0.2076
ItemKNN=5 BPR=3 CB=2	0.2223
ItemKNN=4 BPR=4 CB=2	0.2226
ItemKNN=4 BPR=3 CB=3	0.2133
ItemKNN=2 BPR=3 CB=5	0.1909

Test, evaluated once with the selected split:

Model	Recall@10	MRR@10	NDCG@10	Hit@10	Precision@10
ItemKNN	0.2266	0.3966	0.2389	0.6903	0.1524
BPR	0.2434	0.4277	0.2578	0.7190	0.1628
ContentBased	0.0280	0.0651	0.0291	0.1866	0.0223
Mixed Hybrid (4:4:2)	0.2168	0.3966	0.2356	0.6797	0.1468

The hybrid does not beat BPR on its own. ContentBased is roughly 8x weaker than the collaborative models, so every slot it gets mostly replaces a correct movie from ItemKNN or BPR. On validation, scores drop each time ContentBased gets more slots.

How to reproduce

cd project
python run_model.py ItemKNN BPR ContentBased
python tune_mixed_hybrid.py
python run_mixed_hybrid.py
python -m pytest tests