hopwise
🚀 hopwise
RecBole extension with a focus on Knowledge Graphs (KGs) and explainability.
✨ Overview
hopwise is an advanced extension of the RecBole library, designed to enhance recommendation systems with the power of knowledge graphs. By integrating knowledge embedding models, path-based reasoning methods, and path language modeling approaches, hopwise supports both recommendation and link prediction tasks with a focus on explainability.
Our framework: new functionalities, datasets utilities, abstraction layers, environment utils, metrics type, models
🆕 What’s New?
🆕 Path Reasoning Models
We also added KGLRR although the final explanation is not based on a predicted path in a Knowledge Graph.
🆕 Knowledge Graph Embedding Models
📌 Translational Models
📌 Tensor/Matrix Factorization Models
📌 Convolution-Based Models
We relied for most of the Knowledge Graph Embeddings methods to: TorchKGE due to its popularity, published at a KDD workshop in 2020.
🆕 Explanation Path Quality Metrics
- LIR (Linking Interaction Recency)
- SEP (Shared Entity Popularity)
- LID (Linking Interaction Diversity)
- LITD (Linked Interaction Type Diversity)
- SED (Shared Entity Diversity)
- SETD (Shared Entities Type Diversity)
- PTC (Path Type Concentration)
- PPT (Path Pattern Type)
- PTD/PPC (Path Type Diversity)
- Model Fidelity
🆕 New Datasets
- MovieLens-1M Small: used in the papers PEARLM and KGGLM
- Last.FM-1M Small: used in the papers PEARLM and KGGLM
- Yelp 2018: used in the paper KGAT
- Alibaba Fashion: used in the paper KGRec
All the datasets are available as zip archives on Google Drive.
[!IMPORTANT] Check the paper for the other changes.
⚡ Installation
To install the project, you need to use uv. Follow the steps below to set up the environment and install the necessary dependencies.
🔹 Prerequisites
- ✅ Python 3.9, 3.10, or 3.11
- ✅
uvpackage manager
🔹 Steps (from PyPI or from Source)
1️⃣ Install **uv and create a virtual environment.**
We suggest installing uv as a standalone application instead of using pip to avoid issues and let uv create a dedicated virtual environment.
Once installed, create the virtual environment
uv venv --python PYTHON_VERSION --prompt hopwise
PYTHON_VERSION must be one of 3.9, 3.10, 3.11, while --prompt hopwise customizes the virtual environment name that appears on the shell.
2️⃣ Install via PyPI
uv pip install hopwise
Some models require extra dependencies.
In particular, language models for KG path reasoning require extra dependencies to be installed.
You can install them by specifying the extra pathlm in the command line as follows:
uv pip install hopwise[pathlm]
Other models can be installed with a similar process. For instance, to install NNCF:
uv pip install hopwise[nncf]
Please check the PyPI page for the complete list of extra dependencies and the documentation for more details on how to install hopwise with specific dependencies.
🎉 Done 🎉
2️⃣ Install from source: Clone the repository
git clone https://github.com/tail-unica/hopwise.git
cd hopwise
3️⃣ Install project dependencies
📌 make sure to have uv updated to the latest version
uv sync
📢 Windows: For proper DGL installation, please follow the official DGL installation guide. Windows builds may encounter DLL linking issues with standard installation methods. Pre-built packages from the official source are recommended. Otherwise, using the Windows Subsystem for Linux (WSL) might be feasible as a solution.
🎉 Done 🎉
🚀 Usage
In any chosen setup, a .yaml file must be created containing the configuration to be used. An example:
gpu_id: 0
topk: [10,20,50,...]
data_path: *your_datasets_folder*
metrics: ['NDCG', 'MRR', 'Hit', 'Precision', 'Recall',...]
valid_metric: ndcg@10
eval_batch_size: 1
epochs: 1
eval_step: 1
📍 Training
Run the project with the following command:
hopwise train \
--model MODEL \
--dataset DATASET \
--config_files CONF_FILE_1.yaml CONF_FILE_2.yaml
Override config parameters directly from the CLI using =:
hopwise train --epochs=20
📍 Evaluating from Checkpoint
hopwise evaluate --dataset DATASET --model MODEL \
--config-files CONFIG_FILES --checkpoint CHECKPOINT.pth
📍 Hyperparameters Tuning
In addition to the configuration file, a params file with the extension .hyper the range of hyperparameters to be tested must also be set in this configuration
learning_rate uniform 0.0001, 0.1
embedding_size choice [64, 100, 200]
hopwise tune \
--params-file hopwise/properties/hyper/PARAMS_FILE.hyper \
--config-files CONFIG_FILE.yaml \
--study-name STUDY_NAME
ℹ️ Contributing
Please let us know if you encounter a bug or have any suggestions by filing an issue.
We welcome all contributions from bug fixes to new features and extensions. 🚀
We expect all contributions discussed in the issue tracker and going through PRs. 📌
📜 Cite
If you find hopwise useful for your research or development, please cite with:
@inproceedings{10.1145/3746252.3761641,
author = {Boratto, Ludovico and Fenu, Gianni and Marras, Mirko and Medda, Giacomo and Soccol, Alessandro},
title = {hopwise: A Python Library for Explainable Recommendation based on Path Reasoning over Knowledge Graphs},
year = {2025},
isbn = {9798400720406},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/3746252.3761641},
doi = {10.1145/3746252.3761641},
abstract = {Explainability is becoming central to the development of responsible recommender systems, especially as path reasoning over knowledge graphs saw increased adoption for extracting structured, semantic user-item connections. However, reproducible research in such field remains limited due to fragmented implementations, missing utilities, and the lack of standardized evaluation pipelines. In this paper, we propose hopwise, an open-source library that supports the full life-cycle of explainable path reasoning recommendation methods over knowledge graphs, from knowledge graph preparation to explanation path delivery and evaluation. Rather than creating a new library from scratch, hopwise builds upon the modular and widely adopted RecBole ecosystem, enriching it with more knowledge graphs, path sampling utilities, path reasoning methods, and metrics for evaluating explanation path utility, coverage, and diversity. We show the framework's utility by means of a benchmark including two knowledge graphs and several recommendation methods. Code and Data: https://github.com/tail-unica/hopwise.},
booktitle = {Proceedings of the 34th ACM International Conference on Information and Knowledge Management},
pages = {6328–6333},
numpages = {6},
keywords = {language model, path reasoning, reproducibility, transparency},
location = {Seoul, Republic of Korea},
series = {CIKM '25}
}
The Team
Ludovico Boratto, Gianni Fenu, Mirko Marras, Giacomo Medda, Alessandro Soccol
License
This project is licensed under the MIT License. See the LICENSE file for details.
Acknowledgments
This project was supported by the project PHaSE - Promoting Healthy and Sustainable Eating through Interactive and Explainable AI Methods, funded by MUR under the PRIN 2022 program (CUP H53D23003530006).