Retrieval API

Holdout Builders

compresso_recsys.retrieval.build_eval_holdout(*, train_item_ids, eval_interactions, min_user_support=5, random_state=42, eval_fold=0)

Build fixed eval holdout (source/target) using compressed_elsa fold protocol.

Return type:

dict[str, object]

Parameters:

• train_item_ids (Index | ndarray)

• eval_interactions (DataFrame)

• min_user_support (int)

• random_state (int)

• eval_fold (int)

eval_fold:

• 0: stacked 5-fold behavior (paper default in compressed_elsa)

• 1: single fold

compresso_recsys.retrieval.build_item_cold_holdout(*, item_ids, interactions, source_item_ids, target_item_ids, min_source_items=1, min_target_items=1)

Build source=train-item and target=cold-item holdout for overlapping users.

Return type:

dict[str, object]

Parameters:

• item_ids (Index | ndarray)

• interactions (DataFrame)

• source_item_ids (set[str] | list[str] | ndarray)

• target_item_ids (set[str] | list[str] | ndarray)

• min_source_items (int)

• min_target_items (int)

compresso_recsys.retrieval.build_leave_last_out_holdout(*, item_ids, interactions, min_source_items=1, min_target_items=1)

Build per-user source/target by holding out each user’s latest interaction.

Return type:

dict[str, object]

Parameters:

• item_ids (Index | ndarray)

• interactions (DataFrame)

• min_source_items (int)

• min_target_items (int)

compresso_recsys.retrieval.build_temporal_holdout(*, item_ids, interactions, test_frac=0.1, min_source_items=1, min_target_items=1)

Build source/target using a global timestamp cutoff.

Return type:

dict[str, object]

Parameters:

• item_ids (Index | ndarray)

• interactions (DataFrame)

• test_frac (float)

• min_source_items (int)

• min_target_items (int)

Embedding Evaluation

compresso_recsys.retrieval.evaluate_item_embeddings(*, train_item_ids, item_embeddings, eval_interactions, k=100, holdout_frac=0.2, min_items_per_user=2, min_user_support=5, random_state=42, eval_fold=0, score_batch_size=512, debug=False, debug_users=5, show_progress=False)

Evaluate item embeddings with torch top-k retrieval.

• User profile: sum of source-item embeddings.

• Scores: dot(profile, item_embedding).

• Seen source items are masked.

Return type:

dict[str, float]

Parameters:

• train_item_ids (Index)

• item_embeddings (ndarray)

• eval_interactions (DataFrame)

• k (int)

• holdout_frac (float)

• min_items_per_user (int)

• min_user_support (int)

• random_state (int)

• eval_fold (int)

• score_batch_size (int)

• debug (bool)

• debug_users (int)

• show_progress (bool)

compresso_recsys.retrieval.evaluate_item_embeddings_with_holdout(*, item_embeddings, source_indices, target_indices, k=100, score_batch_size=512, debug=False, debug_users=5, show_progress=False)

Return type:

dict[str, float]

Parameters:

• item_embeddings (ndarray)

• source_indices (list[ndarray])

• target_indices (list[ndarray])

• k (int)

• score_batch_size (int)

• debug (bool)

• debug_users (int)

• show_progress (bool)