Home

Awesome

Cornac

Cornac is a comparative framework for multimodal recommender systems. It focuses on making it convenient to work with models leveraging auxiliary data (e.g., item descriptive text and image, social network, etc). Cornac enables fast experiments and straightforward implementations of new models. It is highly compatible with existing machine learning libraries (e.g., TensorFlow, PyTorch).

Cornac is one of the frameworks recommended by ACM RecSys 2023 for the evaluation and reproducibility of recommendation algorithms.

Quick Links

Website | Documentation | Tutorials | Examples | Models | Datasets | Paper | Preferred.AI

.github/workflows/python-package.yml CircleCI AppVeyor Codecov Docs <br /> Release PyPI Conda Conda Recipe Downloads <br /> Python Conda Platforms License

Installation

Currently, we are supporting Python 3. There are several ways to install Cornac:

Note:

Additional dependencies required by models are listed here.

Some algorithm implementations use OpenMP to support multi-threading. For Mac OS users, in order to run those algorithms efficiently, you might need to install gcc from Homebrew to have an OpenMP compiler:

brew install gcc | brew link gcc

Getting started: your first Cornac experiment

<p align="center"><i>Flow of an Experiment in Cornac</i></p>
import cornac
from cornac.eval_methods import RatioSplit
from cornac.models import MF, PMF, BPR
from cornac.metrics import MAE, RMSE, Precision, Recall, NDCG, AUC, MAP

# load the built-in MovieLens 100K and split the data based on ratio
ml_100k = cornac.datasets.movielens.load_feedback()
rs = RatioSplit(data=ml_100k, test_size=0.2, rating_threshold=4.0, seed=123)

# initialize models, here we are comparing: Biased MF, PMF, and BPR
mf = MF(k=10, max_iter=25, learning_rate=0.01, lambda_reg=0.02, use_bias=True, seed=123)
pmf = PMF(k=10, max_iter=100, learning_rate=0.001, lambda_reg=0.001, seed=123)
bpr = BPR(k=10, max_iter=200, learning_rate=0.001, lambda_reg=0.01, seed=123)
models = [mf, pmf, bpr]

# define metrics to evaluate the models
metrics = [MAE(), RMSE(), Precision(k=10), Recall(k=10), NDCG(k=10), AUC(), MAP()]

# put it together in an experiment, voilà!
cornac.Experiment(eval_method=rs, models=models, metrics=metrics, user_based=True).run()

Output:

MAERMSEAUCMAPNDCG@10Precision@10Recall@10Train (s)Test (s)
MF0.74300.89980.74450.05480.07610.06750.04630.131.57
PMF0.75340.91380.77440.06710.09690.08130.06392.181.64
BPRN/AN/A0.86950.10420.15000.11100.11953.741.49

Model serving

Here, we provide a simple way to serve a Cornac model by launching a standalone web service with Flask. It is very handy for testing or creating a demo application. First, we install the dependency:

$ pip3 install Flask

Supposed that we want to serve the trained BPR model from previous example, we need to save it:

bpr.save("save_dir", save_trainset=True)

After that, the model can be deployed easily by running Cornac serving app as follows:

$ FLASK_APP='cornac.serving.app' \
  MODEL_PATH='save_dir/BPR' \
  MODEL_CLASS='cornac.models.BPR' \
  flask run --host localhost --port 8080

# Running on http://localhost:8080

Here we go, our model service is now ready. Let's get top-5 item recommendations for the user "63":

$ 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 server for model deployment in production. Please refer to this guide for more details.

Model A/B testing

Cornac-AB is an extension of Cornac using the Cornac Serving API. Easily create and manage A/B testing experiments to further understand your model performance with online users.

User Interaction SolutionRecommendations DashboardFeedback Dashboard
<img src="assets/demo.png" alt="demo" width="250"/><img src="assets/recommendation-dashboard.png" alt="recommendations" width="250"/><img src="assets/feedback-dashboard.png" alt="feedback" width="250"/>

Efficient retrieval with ANN search

One important aspect of deploying recommender model is efficient retrieval via Approximate Nearest Neighbor (ANN) search in vector space. Cornac integrates several vector similarity search frameworks for the ease of deployment. This example demonstrates how ANN search will work seamlessly with any recommender models supporting it (e.g., matrix factorization).

Supported FrameworkCornac WrapperExample
spotify/annoyAnnoyANNquick-start, deep-dive
meta/faissFaissANNquick-start, deep-dive
nmslib/hnswlibHNSWLibANNquick-start, hnsw-lib, deep-dive
google/scannScaNNANNquick-start, deep-dive

Models

The table below lists the recommendation models/algorithms featured in Cornac. Examples are provided as quick-start showcasing an easy to run script, or as deep-dive explaining the math and intuition behind each model. Why don't you join us to lengthen the list?

YearModel and PaperTypeEnvironmentExample
2024Comparative Aspects and Opinions Ranking for Recommendation Explanations (Companion), docs, paperHybrid / Sentiment / ExplainableCPUquick-start
Hypergraphs with Attention on Reviews (HypAR), docs, paperHybrid / Sentiment / Explainablerequirements, CPU / GPUquick-start
2022Disentangled Multimodal Representation Learning for Recommendation (DMRL), docs, paperContent-Based / Text & Imagerequirements, CPU / GPUquick-start
2021Bilateral Variational Autoencoder for Collaborative Filtering (BiVAECF), docs, paperCollaborative Filtering / Content-Basedrequirements, CPU / GPUquick-start, deep-dive
Causal Inference for Visual Debiasing in Visually-Aware Recommendation (CausalRec), docs, paperContent-Based / Imagerequirements, CPU / GPUquick-start
Explainable Recommendation with Comparative Constraints on Product Aspects (ComparER), docs, paperExplainableCPUquick-start
2020Adversarial Multimedia Recommendation (AMR), docs, paperContent-Based / Imagerequirements, CPU / GPUquick-start
Hybrid Deep Representation Learning of Ratings and Reviews (HRDR), docs, paperContent-Based / Textrequirements, CPU / GPUquick-start
LightGCN: Simplifying and Powering Graph Convolution Network, docs, paperCollaborative Filteringrequirements, CPU / GPUquick-start
Predicting Temporal Sets with Deep Neural Networks (DNNTSP), docs, paperNext-Basketrequirements, CPU / GPUquick-start
Recency Aware Collaborative Filtering (UPCF), docs, paperNext-Basketrequirements, CPUquick-start
Temporal-Item-Frequency-based User-KNN (TIFUKNN), docs, paperNext-BasketCPUquick-start
Variational Autoencoder for Top-N Recommendations (RecVAE), docs, paperCollaborative Filteringrequirements, CPU / GPUquick-start
2019Correlation-Sensitive Next-Basket Recommendation (Beacon), docs, paperNext-Basketrequirements, CPU / GPUquick-start
Embarrassingly Shallow Autoencoders for Sparse Data (EASEᴿ), docs, paperCollaborative FilteringCPUquick-start
Neural Graph Collaborative Filtering (NGCF), docs, paperCollaborative Filteringrequirements, CPU / GPUquick-start
2018Collaborative Context Poisson Factorization (C2PF), docs, paperContent-Based / GraphCPUquick-start
Graph Convolutional Matrix Completion (GCMC), docs, paperCollaborative Filteringrequirements, CPU / GPUquick-start
Multi-Task Explainable Recommendation (MTER), docs, paperExplainableCPUquick-start, deep-dive
Neural Attention Rating Regression with Review-level Explanations (NARRE), docs, paperExplainable / Content-Basedrequirements, CPU / GPUquick-start
Probabilistic Collaborative Representation Learning (PCRL), docs, paperContent-Based / Graphrequirements, CPU / GPUquick-start
Variational Autoencoder for Collaborative Filtering (VAECF), docs, paperCollaborative Filteringrequirements, CPU / GPUquick-start, param-search, deep-dive
2017Collaborative Variational Autoencoder (CVAE), docs, paperContent-Based / Textrequirements, CPU / GPUquick-start
Conditional Variational Autoencoder for Collaborative Filtering (CVAECF), docs, paperContent-Based / Textrequirements, CPU / GPUquick-start
Generalized Matrix Factorization (GMF), docs, paperCollaborative Filteringrequirements, CPU / GPUquick-start, deep-dive
Indexable Bayesian Personalized Ranking (IBPR), docs, paperCollaborative Filteringrequirements, CPU / GPUquick-start, deep-dive
Matrix Co-Factorization (MCF), docs, paperContent-Based / GraphCPUquick-start, cross-modality
Multi-Layer Perceptron (MLP), docs, paperCollaborative Filteringrequirements, CPU / GPUquick-start, deep-dive
Neural Matrix Factorization (NeuMF) / Neural Collaborative Filtering (NCF), docs, paperCollaborative Filteringrequirements, CPU / GPUquick-start, deep-dive
Online Indexable Bayesian Personalized Ranking (Online IBPR), docs, paperCollaborative Filteringrequirements, CPU / GPUquick-start, deep-dive
Visual Matrix Factorization (VMF), docs, paperContent-Based / Imagerequirements, CPU / GPUquick-start
2016Collaborative Deep Ranking (CDR), docs, paperContent-Based / Textrequirements, CPU / GPUquick-start
Collaborative Ordinal Embedding (COE), docs, paperCollaborative Filteringrequirements, CPU / GPU
Convolutional Matrix Factorization (ConvMF), docs, paperContent-Based / Textrequirements, CPU / GPUquick-start, deep-dive
Learning to Rank Features for Recommendation over Multiple Categories (LRPPM), docs, paperExplainableCPUquick-start
Session-based Recommendations With Recurrent Neural Networks (GRU4Rec), docs, paperNext-Itemrequirements, CPU / GPUquick-start
Spherical K-means (SKM), docs, paperCollaborative FilteringCPUquick-start
Visual Bayesian Personalized Ranking (VBPR), docs, paperContent-Based / Imagerequirements, CPU / GPUquick-start, cross-modality, deep-dive
2015Collaborative Deep Learning (CDL), docs, paperContent-Based / Textrequirements, CPU / GPUquick-start, deep-dive
Hierarchical Poisson Factorization (HPF), docs, paperCollaborative FilteringCPUquick-start
TriRank: Review-aware Explainable Recommendation by Modeling Aspects, docs, paperExplainableCPUquick-start
2014Explicit Factor Model (EFM), docs, paperExplainableCPUquick-start, deep-dive
Social Bayesian Personalized Ranking (SBPR), docs, paperContent-Based / SocialCPUquick-start
2013Hidden Factors and Hidden Topics (HFT), docs, paperContent-Based / TextCPUquick-start
2012Weighted Bayesian Personalized Ranking (WBPR), docs, paperCollaborative FilteringCPUquick-start
2011Collaborative Topic Regression (CTR), docs, paperContent-Based / TextCPUquick-start, deep-dive
EarlierBaseline Only, docs, paperBaselineCPUquick-start
Bayesian Personalized Ranking (BPR), docs paperCollaborative FilteringCPUquick-start, deep-dive
Factorization Machines (FM), docs, paperCollaborative Filtering / Content-BasedLinux, CPUquick-start, deep-dive
Global Average (GlobalAvg), docs, paperBaselineCPUquick-start
Global Personalized Top Frequent (GPTop), paperNext-BasketCPUquick-start
Item K-Nearest-Neighbors (ItemKNN), docs, paperNeighborhood-BasedCPUquick-start, deep-dive
Matrix Factorization (MF), docs, paperCollaborative FilteringCPU / GPUquick-start, pre-split-data, deep-dive
Maximum Margin Matrix Factorization (MMMF), docs, paperCollaborative FilteringCPUquick-start
Most Popular (MostPop), docs, paperBaselineCPUquick-start
Non-negative Matrix Factorization (NMF), docs, paperCollaborative FilteringCPUquick-start, deep-dive
Probabilistic Matrix Factorization (PMF), docs, paperCollaborative FilteringCPUquick-start
Session Popular (SPop), docs, paperNext-Item / BaselineCPUquick-start
Singular Value Decomposition (SVD), docs, paperCollaborative FilteringCPUquick-start, deep-dive
Social Recommendation using PMF (SoRec), docs, paperContent-Based / SocialCPUquick-start, deep-dive
User K-Nearest-Neighbors (UserKNN), docs, paperNeighborhood-BasedCPUquick-start, deep-dive
Weighted Matrix Factorization (WMF), docs, paperCollaborative Filteringrequirements, CPU / GPUquick-start, deep-dive

Resources

Contributing

This project welcomes contributions and suggestions. Before contributing, please see our contribution guidelines.

Citation

If you use Cornac in a scientific publication, we would appreciate citations to the following papers:

<details> <summary><a href="http://jmlr.org/papers/v21/19-805.html">Cornac: A Comparative Framework for Multimodal Recommender Systems</a>, Salah <i>et al.</i>, Journal of Machine Learning Research, 21(95):1–5, 2020.</summary>
@article{salah2020cornac,
  title={Cornac: A Comparative Framework for Multimodal Recommender Systems},
  author={Salah, Aghiles and Truong, Quoc-Tuan and Lauw, Hady W},
  journal={Journal of Machine Learning Research},
  volume={21},
  number={95},
  pages={1--5},
  year={2020}
}
</details> <details> <summary><a href="https://ieeexplore.ieee.org/abstract/document/9354572">Exploring Cross-Modality Utilization in Recommender Systems</a>, Truong <i>et al.</i>, IEEE Internet Computing, 25(4):50–57, 2021.</summary>
@article{truong2021exploring,
  title={Exploring Cross-Modality Utilization in Recommender Systems},
  author={Truong, Quoc-Tuan and Salah, Aghiles and Tran, Thanh-Binh and Guo, Jingyao and Lauw, Hady W},
  journal={IEEE Internet Computing},
  year={2021},
  publisher={IEEE}
}
</details> <details> <summary><a href="http://jmlr.org/papers/v21/19-805.html">Multi-Modal Recommender Systems: Hands-On Exploration</a>, Truong <i>et al.</i>, ACM Conference on Recommender Systems, 2021.</summary>
@inproceedings{truong2021multi,
  title={Multi-modal recommender systems: Hands-on exploration},
  author={Truong, Quoc-Tuan and Salah, Aghiles and Lauw, Hady},
  booktitle={Fifteenth ACM Conference on Recommender Systems},
  pages={834--837},
  year={2021}
}
</details>

License

Apache License 2.0