Core API

Datasets

class compresso_recsys.SplitBundle(train, val, test)[source]
Parameters:

  • train (DataFrame)

  • val (DataFrame)

  • test (DataFrame)

class compresso_recsys.RecSysDataset(data_dir='data')[source]

Thin base class for interaction datasets used in example pipelines.

Canonical interactions schema: - user_id: str - item_id: str - value: float - timestamp: int | float | None

Parameters:

data_dir (str | Path)

static preprocess_interactions_for_recsys(df, *, min_value_to_keep=4.0, user_min_support=5, item_min_support=1, set_all_values_to=1.0, max_steps=0)[source]

Paper-style preprocessing: threshold, binarize, iterative pruning, categorical cleanup.

Return type:

DataFrame

Parameters:

  • df (DataFrame)

  • min_value_to_keep (float | None)

  • user_min_support (int)

  • item_min_support (int)

  • set_all_values_to (float | None)

  • max_steps (int)

to_hf_dataset(df=None)[source]

Convert interactions to HuggingFace Dataset.

Import is optional so core library does not hard-depend on datasets.

Parameters:

df (DataFrame | None)

static to_sparse_matrix(df)[source]

Return (X, user_ids, item_ids) where X is user x item CSR.

Parameters:

df (DataFrame)

class compresso_recsys.Goodbooks(data_dir='data', *, metadata_text_fields=None, min_entity_text_words=0)[source]
Parameters:

  • data_dir (str)

  • metadata_text_fields (Iterable[str] | None)

  • min_entity_text_words (int)

class compresso_recsys.MovieLens1M(data_dir='data', *, metadata_text_fields=None, min_entity_text_words=0)[source]
Parameters:

  • data_dir (str)

  • metadata_text_fields (Iterable[str] | None)

  • min_entity_text_words (int)

class compresso_recsys.MovieLens20M(data_dir='data', *, metadata_text_fields=None, min_entity_text_words=0)[source]
Parameters:

  • data_dir (str)

  • metadata_text_fields (Iterable[str] | None)

  • min_entity_text_words (int)

class compresso_recsys.AmazonReviews2023(data_dir='data', *, category='Toys_and_Games', metadata_text_fields=('title', 'features', 'description', 'categories'), min_entity_text_words=0, include_image_urls=False, show_progress=True)[source]

Amazon Reviews 2023 category dataset loaded from McAuley’s files.

The recommender pipeline only needs compact rating-only interactions plus item metadata. Reviews are intentionally not downloaded.

Parameters:

  • data_dir (str)

  • category (str)

  • metadata_text_fields (Iterable[str])

  • min_entity_text_words (int)

  • include_image_urls (bool)

  • show_progress (bool)

load_source_dataframe(config, *, split='full')

Load a McAuley Amazon 2023 config into a DataFrame.

Kept under its historical name for compatibility with tests and subclasses, but this no longer uses Hugging Face datasets. Recent datasets releases reject repositories that still expose loading scripts, so we read direct Hugging Face/McAuley data files instead.

Return type:

DataFrame

Parameters:

  • config (str)

  • split (str)

load_timestamp_splits_with_history()[source]

Load McAuley’s timestamp split with per-row history fields.

Return type:

dict[str, DataFrame]

Checkpoint Helpers

compresso_recsys.build_recsys_checkpoint(*, dataset, data_dir='data', checkpoint_path=None, seed=None, val_users=None, test_users=None, min_user_support=None, item_min_support=None, min_value_to_keep=None, set_all_values_to=None, eval_fold=0, split_mode='user_split', val_items=None, test_items=None, item_val_frac=0.05, item_test_frac=0.1, temporal_test_frac=0.1, min_source_items=1, min_target_items=1, amazon_category='Toys_and_Games', metadata_text_fields=None, min_entity_text_words=30, include_image_urls=False, annotation_source='genres', annotation_min_count=100, show_progress=True)[source]

Build a recommender-system split checkpoint and return its path.

Return type:

Path

Parameters:

  • dataset (str)

  • data_dir (str)

  • checkpoint_path (str | None)

  • seed (int | None)

  • val_users (int | None)

  • test_users (int | None)

  • min_user_support (int | None)

  • item_min_support (int | None)

  • min_value_to_keep (float | None)

  • set_all_values_to (float | None)

  • eval_fold (int)

  • split_mode (str)

  • val_items (int | None)

  • test_items (int | None)

  • item_val_frac (float)

  • item_test_frac (float)

  • temporal_test_frac (float)

  • min_source_items (int)

  • min_target_items (int)

  • amazon_category (str)

  • metadata_text_fields (str | list[str] | tuple[str, ...] | None)

  • min_entity_text_words (int)

  • include_image_urls (bool)

  • annotation_source (str)

  • annotation_min_count (int)

  • show_progress (bool)

compresso_recsys.update_checkpoint(path)[source]

Extract a zip checkpoint to a temp dir, let caller edit it, then rewrite it.

Return type:

Iterator[Path]

Parameters:

path (str | Path)

compresso_recsys.read_checkpoint(path)[source]

Extract a zip checkpoint to a read-only temp workspace.

Return type:

Iterator[Path]

Parameters:

path (str | Path)

compresso_recsys.load_manifest(root)[source]
Return type:

dict[str, Any]

Parameters:

root (str | Path)

compresso_recsys.save_manifest(root, manifest)[source]
Return type:

None

Parameters:

  • root (str | Path)

  • manifest (dict[str, Any])

compresso_recsys.update_stage_manifest(root, stage, metadata)[source]
Return type:

None

Parameters:

  • root (str | Path)

  • stage (str)

  • metadata (dict[str, Any])

compresso_recsys.save_json(root, relpath, data)[source]
Return type:

Path

Parameters:

  • root (str | Path)

  • relpath (str)

  • data (dict[str, Any])

compresso_recsys.load_json(root, relpath)[source]
Return type:

dict[str, Any]

Parameters:

  • root (str | Path)

  • relpath (str)

compresso_recsys.save_recsys_split(root, *, item_ids, x_train, val_source_indices, val_target_indices, test_source_indices, test_target_indices, train_source_matrix=None, train_target_matrix=None, val_source_matrix=None, val_target_matrix=None, test_source_matrix=None, test_target_matrix=None, train_user_ids=None, val_user_ids=None, test_user_ids=None, val_eval_user_ids=None, test_eval_user_ids=None, train_item_indices=None, val_item_indices=None, test_item_indices=None, entity_tag_matrix=None, tag_names=None, entity_metadata=None, metadata=None)[source]
Return type:

None

Parameters:

  • root (str | Path)

  • item_ids (ndarray)

  • x_train (csr_matrix)

  • val_source_indices (list[ndarray])

  • val_target_indices (list[ndarray])

  • test_source_indices (list[ndarray])

  • test_target_indices (list[ndarray])

  • train_source_matrix (csr_matrix | None)

  • train_target_matrix (csr_matrix | None)

  • val_source_matrix (csr_matrix | None)

  • val_target_matrix (csr_matrix | None)

  • test_source_matrix (csr_matrix | None)

  • test_target_matrix (csr_matrix | None)

  • train_user_ids (ndarray | list[str] | None)

  • val_user_ids (ndarray | list[str] | None)

  • test_user_ids (ndarray | list[str] | None)

  • val_eval_user_ids (ndarray | list[str] | None)

  • test_eval_user_ids (ndarray | list[str] | None)

  • train_item_indices (ndarray | None)

  • val_item_indices (ndarray | None)

  • test_item_indices (ndarray | None)

  • entity_tag_matrix (csr_matrix | None)

  • tag_names (ndarray | list[str] | None)

  • entity_metadata (DataFrame | None)

  • metadata (dict[str, Any] | None)

compresso_recsys.load_recsys_split(root)[source]
Return type:

dict[str, Any]

Parameters:

root (str | Path)

compresso_recsys.save_cluster_graph_stage(root, graph, *, stage_dir='clustering', metadata=None)[source]
Return type:

Path

Parameters:

  • root (str | Path)

  • graph (SparseClusterSet)

  • stage_dir (str)

  • metadata (dict[str, Any] | None)

compresso_recsys.load_cluster_graph_stage(root, *, stage_dir='clustering')[source]
Return type:

SparseClusterSet

Parameters:

  • root (str | Path)

  • stage_dir (str)

Retrieval API

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

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)[source]

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)[source]

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)[source]

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)

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)[source]

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)[source]
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)