hopwise 0.9.0

_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 apporaches, hopwise supports both recommendation and link prediction tasks with a focus on interpretability and self-explanation.

🚀 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

• PLM-Rec
• PEARLM
• KGGLM
• PGPR
• CAFE
• TPRec

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

• TransE
• TransH
• TransD
• TransR
• TorusE
• RotatE

📌 Tensor/Matrix Factorization Models

• ComplEx
• Analogy
• TuckER
• RESCAL
• DistMult
• HolE

📌 Convolution-Based Models

• ConvE
• ConvKB

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
• ✅ uv package 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:

the paper is under revision

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.