Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
name: docs

on:
push:
branches: [ master ]
pull_request:
branches: [ master ]

jobs:
listings:
name: Check docs listings
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: "3.12"

- name: Check that models, dataset loaders and examples are listed
run: python docs/check_listings.py
10 changes: 6 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Cornac is an open-source project and we welcome contributions of all kinds.
We welcome pull requests for new features such as models, datasets, metrics
and anything that could make Cornac a better tool for all.

This page sums up what we check when we review a pull request. The [Contributors Guide](https://cornac.readthedocs.io/en/stable/developer/index.html) walks you through forking the repository and opening a pull request, and the tutorials show how to [add a model](https://github.com/PreferredAI/cornac/blob/master/tutorials/add_model.md) and [add a metric](https://github.com/PreferredAI/cornac/blob/master/tutorials/add_metric.md).
This page sums up what we check when we review a pull request. The [Contributors Guide](https://cornac.readthedocs.io/en/stable/developer/contributing.html) walks you through forking the repository and opening a pull request, and the tutorials show how to [add a model](https://github.com/PreferredAI/cornac/blob/master/tutorials/add_model.md) and [add a metric](https://github.com/PreferredAI/cornac/blob/master/tutorials/add_metric.md).

## Development Setup

Expand Down Expand Up @@ -34,7 +34,7 @@ ruff format path/to/new_file.py

Many existing files are not formatted with Ruff yet, so running `ruff format` on a whole existing file or folder would rewrite code you did not touch. In an existing file, format only the lines you changed, for example lines 120 to 135 with `ruff format --range=120-135 path/to/file.py`, and keep formatting changes out of functional changes, so that reviewers can see what your change does.

Docstrings follow the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) style, with `Parameters` and `Returns` sections, because the API reference is generated from them. New source files start with the Apache-2.0 license header; copy it from an existing file.
Include concise documentation with your change: docstrings, comments, and updates to the documentation in `docs/source/` when needed. Docstrings follow the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) style, with `Parameters` and `Returns` sections, because the API reference is generated from them. New source files start with the Apache-2.0 license header; copy it from an existing file.

## Optional Dependencies

Expand All @@ -55,9 +55,11 @@ A new model lives in its own package, `cornac/models/<name>/`, with an `__init__
- add an entry to `docs/source/api_ref/models.rst`;
- add an example script under `examples/` and list it in `examples/README.md`.

A dataset loader is a module in `cornac/datasets/`. Add a test for it in `tests/cornac/datasets/`, an entry in `docs/source/api_ref/datasets.rst`, and a description in `cornac/datasets/README.md`.
A dataset loader is a module in `cornac/datasets/`, imported in `cornac/datasets/__init__.py`. Add a test for it in `tests/cornac/datasets/`, an entry in `docs/source/api_ref/datasets.rst`, and a description in `cornac/datasets/README.md`.

A metric goes in `cornac/metrics/`, with tests in `tests/cornac/metrics/` and an entry in `docs/source/api_ref/metrics.rst`.
A metric goes in `cornac/metrics/`, with an import in `cornac/metrics/__init__.py`, tests in `tests/cornac/metrics/` and an entry in `docs/source/api_ref/metrics.rst`.

Each pull request runs `python docs/check_listings.py`, which reports any model, dataset loader or example that is missing from these lists. You can run it yourself before you push.

## Tests

Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ $ curl -X GET "http://localhost:8080/recommend?uid=63&k=5&remove_seen=false"

# Response: {"recommendations": ["50", "181", "100", "258", "286"], "query": {"uid": "63", "k": 5, "remove_seen": false}}
```
If we want to remove seen items during training, we need to provide `TRAIN_SET` which has been saved with the model earlier, when starting the serving app. We can also leverage [WSGI](https://flask.palletsprojects.com/en/3.0.x/deploying/) server for model deployment in production. Please refer to [this](https://cornac.readthedocs.io/en/stable/user/iamadeveloper.html#running-an-api-service) guide for more details.
If we want to remove seen items during training, we need to provide `TRAIN_SET` which has been saved with the model earlier, when starting the serving app. We can also leverage [WSGI](https://flask.palletsprojects.com/en/3.0.x/deploying/) server for model deployment in production. Please refer to [this](https://cornac.readthedocs.io/en/latest/user/serving.html#running-an-api-service) guide for more details.

## Model A/B testing

Expand Down Expand Up @@ -189,7 +189,7 @@ The table below lists the recommendation models/algorithms featured in Cornac. E
| | [Conditional Variational Autoencoder for Collaborative Filtering (CVAECF)](cornac/models/cvaecf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.cvaecf.recom_cvaecf), [paper](https://dl.acm.org/doi/10.1145/3132847.3132972) | Content-Based / Text | [requirements](cornac/models/cvaecf/requirements.txt), CPU / GPU | [quick-start](examples/cvaecf_filmtrust.py)
| | [Generalized Matrix Factorization (GMF)](cornac/models/ncf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.ncf.recom_gmf), [paper](https://arxiv.org/pdf/1708.05031.pdf) | Collaborative Filtering | [requirements](cornac/models/ncf/requirements.txt), CPU / GPU | [quick-start](examples/ncf_example.py), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/09_deep_learning.ipynb)
| | [Indexable Bayesian Personalized Ranking (IBPR)](cornac/models/ibpr), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.ibpr.recom_ibpr), [paper](http://www.hadylauw.com/publications/cikm17a.pdf) | Collaborative Filtering | [requirements](cornac/models/ibpr/requirements.txt), CPU / GPU | [quick-start](examples/ibpr_example.py), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/08_retrieval.ipynb)
| | [Matrix Co-Factorization (MCF)](cornac/models/mcf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.mcf.recom_mcf), [paper](https://dsail.kaist.ac.kr/files/WWW17.pdf) | Content-Based / Graph | CPU | [quick-start](examples/mcf_office.py), [cross-modality](https://github.com/lgabs/cornac/blob/luan/describe-gpu-supported-models-readme/tutorials/text_to_graph.ipynb)
| | [Matrix Co-Factorization (MCF)](cornac/models/mcf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.mcf.recom_mcf), [paper](https://dsail.kaist.ac.kr/files/WWW17.pdf) | Content-Based / Graph | CPU | [quick-start](examples/mcf_office.py), [cross-modality](tutorials/text_to_graph.ipynb)
| | [Multi-Layer Perceptron (MLP)](cornac/models/ncf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.ncf.recom_mlp), [paper](https://arxiv.org/pdf/1708.05031.pdf) | Collaborative Filtering | [requirements](cornac/models/ncf/requirements.txt), CPU / GPU | [quick-start](examples/ncf_example.py), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/09_deep_learning.ipynb)
| | [Neural Matrix Factorization (NeuMF) / Neural Collaborative Filtering (NCF)](cornac/models/ncf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.ncf.recom_neumf), [paper](https://arxiv.org/pdf/1708.05031.pdf) | Collaborative Filtering | [requirements](cornac/models/ncf/requirements.txt), CPU / GPU | [quick-start](examples/ncf_example.py), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/09_deep_learning.ipynb)
| | [Online Indexable Bayesian Personalized Ranking (Online IBPR)](cornac/models/online_ibpr), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.online_ibpr.recom_online_ibpr), [paper](http://www.hadylauw.com/publications/cikm17a.pdf) | Collaborative Filtering | [requirements](cornac/models/online_ibpr/requirements.txt), CPU / GPU | [quick-start](examples/ibpr_example.py), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/08_retrieval.ipynb)
Expand All @@ -201,7 +201,7 @@ The table below lists the recommendation models/algorithms featured in Cornac. E
| | [Session-based Recommendations With Recurrent Neural Networks (GRU4Rec)](cornac/models/gru4rec), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.gru4rec.recom_gru4rec), [paper](https://arxiv.org/pdf/1511.06939.pdf) | Next-Item | [requirements](cornac/models/gru4rec/requirements.txt), CPU / GPU | [quick-start](examples/gru4rec_yoochoose.py)
| | [Spherical K-means (SKM)](cornac/models/skm), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.skm.recom_skmeans), [paper](https://www.sciencedirect.com/science/article/pii/S092523121501509X) | Collaborative Filtering | CPU | [quick-start](examples/skm_movielens.py)
| | [Visual Bayesian Personalized Ranking (VBPR)](cornac/models/vbpr), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.vbpr.recom_vbpr), [paper](https://arxiv.org/pdf/1510.01784.pdf) | Content-Based / Image | [requirements](cornac/models/vbpr/requirements.txt), CPU / GPU | [quick-start](examples/vbpr_tradesy.py), [cross-modality](tutorials/vbpr_text.ipynb), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/05_multimodality.ipynb)
| 2015 | [Collaborative Deep Learning (CDL)](cornac/models/cdl), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.cdl.recom_cdl), [paper](https://arxiv.org/pdf/1409.2944.pdf) | Content-Based / Text | [requirements](cornac/models/cdl/requirements.txt), CPU / GPU | [quick-start](examples/cdl_example.py), [deep-dive](https://github.com/lgabs/cornac/blob/luan/describe-gpu-supported-models-readme/tutorials/working_with_auxiliary_data.md)
| 2015 | [Collaborative Deep Learning (CDL)](cornac/models/cdl), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.cdl.recom_cdl), [paper](https://arxiv.org/pdf/1409.2944.pdf) | Content-Based / Text | [requirements](cornac/models/cdl/requirements.txt), CPU / GPU | [quick-start](examples/cdl_example.py), [deep-dive](tutorials/working_with_auxiliary_data.md)
| | [Hierarchical Poisson Factorization (HPF)](cornac/models/hpf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.hpf.recom_hpf), [paper](http://jakehofman.com/inprint/poisson_recs.pdf) | Collaborative Filtering | CPU | [quick-start](examples/hpf_movielens.py)
| | [TriRank: Review-aware Explainable Recommendation by Modeling Aspects](cornac/models/trirank), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.trirank.recom_trirank), [paper](https://wing.comp.nus.edu.sg/wp-content/uploads/Publications/PDF/TriRank-%20Review-aware%20Explainable%20Recommendation%20by%20Modeling%20Aspects.pdf) | Explainable | CPU | [quick-start](examples/trirank_example.py)
| 2014 | [Explicit Factor Model (EFM)](cornac/models/efm), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.efm.recom_efm), [paper](https://www.yongfeng.me/attach/efm-zhang.pdf) | Explainable | CPU | [quick-start](examples/efm_example.py), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/07_explanations.ipynb)
Expand Down Expand Up @@ -240,7 +240,7 @@ The table below lists the recommendation models/algorithms featured in Cornac. E

## Contributing

This project welcomes contributions and suggestions. Before contributing, please read [CONTRIBUTING.md](CONTRIBUTING.md) and our [contribution guidelines](https://cornac.readthedocs.io/en/stable/developer/index.html).
This project welcomes contributions and suggestions. Before contributing, please read [CONTRIBUTING.md](CONTRIBUTING.md).

## Citation

Expand Down
Loading
Loading