Compresso Recsys

compresso-recsys is the recommender-system companion package for Compresso. It provides dataset loaders, checkpoint builders, checkpoint read/write helpers, and retrieval metrics for sparse representation learning experiments.

The package distribution name is compresso-recsys; the Python import is:

import compresso_recsys as cr

Install

Install from PyPI:

pip install compresso-recsys

Install optional dataset export support:

pip install "compresso-recsys[datasets]"

For local development:

pip install -e ../compresso
pip install -e ".[dev,datasets]"

Quickstart

Build a MovieLens 1M checkpoint from Python:

import compresso_recsys as cr

checkpoint_path = cr.build_recsys_checkpoint(
    dataset="ml1m",
    checkpoint_path="artifacts/ml1m/exp001.zip",
    annotation_source="genres",
)

with cr.read_checkpoint(checkpoint_path) as root:
    split = cr.load_recsys_split(root)

print(split["x_train"].shape)

Build the same kind of checkpoint from the command line:

compresso-recsys-build-checkpoint \
  --dataset ml1m \
  --checkpoint_path artifacts/ml1m/exp001.zip \
  --annotation_source genres

Amazon Reviews 2023 checkpoints can use item metadata for cold-item retrieval experiments:

compresso-recsys-build-checkpoint \
  --dataset amazon2023 \
  --amazon_category Toys_and_Games \
  --checkpoint_path artifacts/amazon_toys/temporal_exp001.zip \
  --split_mode temporal \
  --metadata_text_fields title,features,description,categories \
  --min_entity_text_words 30 \
  --annotation_source none

What Is Included

Dataset utilities for GoodBooks, MovieLens 1M, MovieLens 20M, and Amazon Reviews 2023.
ZIP checkpoint format for source/target splits, embeddings, sparse embeddings, metrics, and Compresso cluster-graph stages.
Calibrated Recall and nDCG defaults, with optional standard Recall, Precision, Hit Rate, MRR, and MAP at configurable cutoffs.
Batched EASE, dense ELSA, and lottery-ticket compressed ELSA models with streaming evaluation.
A checkpoint-building console command: compresso-recsys-build-checkpoint.

Documentation

Release documentation is available at:

https://zombak79.github.io/compresso-recsys/

The full CLI parameter table, checkpoint split schema, and supported Amazon Reviews 2023 categories are maintained in the Checkpoint CLI Reference. Academic references and copy-ready BibTeX for EASE, ELSA, large-scale ELSA, and compressed ELSA are available in the citation guide.

Build the docs locally:

pip install -e ".[docs]"
sphinx-build -b html docs/source docs/build/html

License

Apache License 2.0. See LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

compresso_recsys-0.1.1.tar.gz (61.7 kB view details)

Uploaded Jul 29, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

compresso_recsys-0.1.1-py3-none-any.whl (55.4 kB view details)

Uploaded Jul 29, 2026 Python 3

File details

Details for the file compresso_recsys-0.1.1.tar.gz.

File metadata

Download URL: compresso_recsys-0.1.1.tar.gz
Upload date: Jul 29, 2026
Size: 61.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for compresso_recsys-0.1.1.tar.gz
Algorithm	Hash digest
SHA256	`f0afb0f6b47f81ec57ae4e18b7259fe2cfaa9b76dfe9fd0651f2cb65fc5481f9`
MD5	`614e4525f430ffdf29fbe7f0d0cfe7f6`
BLAKE2b-256	`e7dd82661f6d0d382b83e6198ab4f92de3a3a1674ca33972da37579a4dab6868`

See more details on using hashes here.

Provenance

The following attestation bundles were made for compresso_recsys-0.1.1.tar.gz:

Publisher: publish.yml on zombak79/compresso-recsys

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: compresso_recsys-0.1.1.tar.gz
- Subject digest: f0afb0f6b47f81ec57ae4e18b7259fe2cfaa9b76dfe9fd0651f2cb65fc5481f9
- Sigstore transparency entry: 2281262957
- Sigstore integration time: Jul 29, 2026
Source repository:
- Permalink: zombak79/compresso-recsys@c18a7969859495148c5b0923445c839d7502c7aa
- Branch / Tag: refs/tags/v0.1.1
- Owner: https://github.com/zombak79
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@c18a7969859495148c5b0923445c839d7502c7aa
- Trigger Event: push