Metadata-Version: 2.4
Name: compresso-recsys
Version: 0.1.0
Summary: Recommender-system experiments and checkpoint pipelines for Compresso
Author: Vojtech Vancura, Giacomo Medda, Martin Spisak, Ladislav Peska
Maintainer: Vojtech Vancura, Giacomo Medda, Martin Spisak, Ladislav Peska
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/zombak79/compresso-recsys
Project-URL: Documentation, https://zombak79.github.io/compresso-recsys/
Project-URL: Repository, https://github.com/zombak79/compresso-recsys
Project-URL: Issues, https://github.com/zombak79/compresso-recsys/issues
Keywords: recommender-systems,recommendation,retrieval,collaborative-filtering,cold-start,datasets,sparse-representations,machine-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: compresso-pytorch>=0.1.0
Requires-Dist: torch>=2.1
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.11
Requires-Dist: pyarrow>=14.0
Provides-Extra: datasets
Requires-Dist: datasets>=2.19; extra == "datasets"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=8.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=3.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == "docs"
Requires-Dist: myst-parser>=4.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# Compresso Recsys

[![PyPI](https://img.shields.io/pypi/v/compresso-recsys.svg)](https://pypi.org/project/compresso-recsys/)
[![Python](https://img.shields.io/pypi/pyversions/compresso-recsys.svg)](https://pypi.org/project/compresso-recsys/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://zombak79.github.io/compresso-recsys/)

`compresso-recsys` is the recommender-system companion package for
[Compresso](https://github.com/zombak79/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:

```python
import compresso_recsys as cr
```

## Install

Install from PyPI:

```bash
pip install compresso-recsys
```

Install optional dataset export support:

```bash
pip install "compresso-recsys[datasets]"
```

For local development:

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

## Quickstart

Build a MovieLens 1M checkpoint from Python:

```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:

```bash
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:

```bash
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.
- Retrieval metrics for Recall and nDCG at common cutoffs including 20, 50,
  and 100.
- A checkpoint-building console command:
  `compresso-recsys-build-checkpoint`.

## Documentation

Release documentation is available at:

```text
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](https://zombak79.github.io/compresso-recsys/cli-reference.html).

Build the docs locally:

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

## License

Apache License 2.0. See [LICENSE](LICENSE).
