{"id":37070465,"url":"https://github.com/tail-unica/hopwise","last_synced_at":"2026-01-14T08:13:38.083Z","repository":{"id":280521920,"uuid":"883664949","full_name":"tail-unica/hopwise","owner":"tail-unica","description":"hopwise: A Python Library for Explainable Recommendation based on Path Reasoning over Knowledge Graphs, ACM CIKM '25","archived":false,"fork":false,"pushed_at":"2025-12-21T11:03:45.000Z","size":20478,"stargazers_count":10,"open_issues_count":29,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-12-21T19:33:27.044Z","etag":null,"topics":["interpretability-and-explainability","knowledge-graph-embeddings","link-prediction","path-reasoning","recommender-systems"],"latest_commit_sha":null,"homepage":"http://tail-unica.github.io/hopwise/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tail-unica.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-05T11:13:48.000Z","updated_at":"2025-12-21T11:03:49.000Z","dependencies_parsed_at":"2025-03-20T13:54:17.383Z","dependency_job_id":"4db664aa-216c-4fc7-9a5a-2adda088eae1","html_url":"https://github.com/tail-unica/hopwise","commit_stats":null,"previous_names":["tail-unica/hopwise"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/tail-unica/hopwise","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tail-unica%2Fhopwise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tail-unica%2Fhopwise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tail-unica%2Fhopwise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tail-unica%2Fhopwise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tail-unica","download_url":"https://codeload.github.com/tail-unica/hopwise/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tail-unica%2Fhopwise/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28413671,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["interpretability-and-explainability","knowledge-graph-embeddings","link-prediction","path-reasoning","recommender-systems"],"created_at":"2026-01-14T08:13:37.390Z","updated_at":"2026-01-14T08:13:38.069Z","avatar_url":"https://github.com/tail-unica.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n\u003ch1 align=\"center\"\u003e🚀 hopwise\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eRecBole extension with a focus on Knowledge Graphs (KGs) and explainability.\u003c/b\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"http://tail-unica.github.io/hopwise/\"\u003e\u003cimg alt=\"Static Badge\" src=\"https://img.shields.io/badge/docs-hopwise-purple?logo=sphinx\u0026link=http%3A%2F%2Ftail-unica.github.io%2Fhopwise%2F\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-3.9%7C3.10%7C3.11-green\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/tail-unica/hopwise\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/repo-size/tail-unica/hopwise\"\u003e\n  \u003ca href=\"https://github.com/tail-unica/hopwise/network\"\u003e\u003cimg alt=\"GitHub forks\" src=\"https://img.shields.io/github/forks/tail-unica/hopwise\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/tail-unica/hopwise/stargazers\"\u003e\u003cimg alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/tail-unica/hopwise\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n---\n\n## ✨ Overview\n\n**hopwise** is an advanced extension of the RecBole library, designed to enhance recommendation systems with the power of **knowledge graphs**.\nBy 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**.\n\n---\n\n![hopwise pipeline](https://github.com/tail-unica/hopwise/blob/main/assets/hopwise.png)\n\n**Our framework: \u003cspan style=\"color:rgb(247, 206, 204)\"\u003enew functionalities\u003c/span\u003e, \u003cspan style=\"color:rgb(213, 232, 212)\"\u003edatasets utilities\u003c/span\u003e, \u003cspan style=\"color:rgb(218, 232, 249)\"\u003eabstraction layers\u003c/span\u003e, \u003cspan style=\"color:rgb(255, 242, 205)\"\u003eenvironment utils\u003c/span\u003e, \u003cspan style=\"color:rgb(255, 230, 205)\"\u003emetrics type\u003c/span\u003e, \u003cspan style=\"color:rgb(208,206,226)\"\u003emodels\u003c/span\u003e**\n\n## 🆕 What's New?\n\n🆕 **Path Reasoning Models**\n- **[PLM-Rec](https://dl.acm.org/doi/10.1145/3485447.3511937)**\n- **[PEARLM](https://arxiv.org/pdf/2310.16452)**\n- **[KGGLM](https://dl.acm.org/doi/10.1145/3640457.3691703)**\n- **[PGPR](https://dl.acm.org/doi/10.1145/3331184.3331203)**\n- **[CAFE](https://dl.acm.org/doi/10.1145/3340531.3412038)**\n- **[TPRec](https://dl.acm.org/doi/10.1145/3531267)**\n\n*We also added [KGLRR](https://link.springer.com/article/10.1007/s10994-024-06646-4) although the final explanation is not based on a predicted path in a Knowledge Graph.*\n\n🆕 **Knowledge Graph Embedding Models**\n\n**📌 Translational Models**\n\n- **[TransE](https://proceedings.neurips.cc/paper_files/paper/2013/file/1cecc7a77928ca8133fa24680a88d2f9-Paper.pdf)**\n- **[TransH](https://ojs.aaai.org/index.php/AAAI/article/view/8870)**\n- **[TransD](https://aclanthology.org/P15-1067/)**\n- **[TransR](https://linyankai.github.io/publications/aaai2015_transr.pdf)**\n- **[TorusE](https://cdn.aaai.org/ojs/11538/11538-13-15066-1-2-20201228.pdf)**\n- **[RotatE](https://arxiv.org/abs/1902.10197)**\n\n**📌 Tensor/Matrix Factorization Models**\n\n\n- **[ComplEx](https://arxiv.org/abs/1606.06357)**\n- **[Analogy](https://proceedings.mlr.press/v70/liu17d/liu17d.pdf)**\n- **[TuckER](https://arxiv.org/abs/1901.09590)**\n- **[RESCAL](https://icml.cc/2011/papers/438_icmlpaper.pdf)**\n- **[DistMult](https://arxiv.org/abs/1412.6575)**\n- **[HolE](https://arxiv.org/abs/1510.04935)**\n\n**📌 Convolution-Based Models**\n\n- **[ConvE](https://arxiv.org/abs/1707.01476)**\n- **[ConvKB](https://aclanthology.org/N18-2053/)**\n\n*We relied for most of the Knowledge Graph Embeddings methods to: [TorchKGE](https://torchkge.readthedocs.io/en/latest/) due to its popularity, published at a KDD workshop in 2020.*\n\n🆕 **Explanation Path Quality Metrics**\n\n- **LIR (Linking Interaction Recency)**\n- **SEP (Shared Entity Popularity)**\n- **LID (Linking Interaction Diversity)**\n- **LITD (Linked Interaction Type Diversity)**\n- **SED (Shared Entity Diversity)**\n- **SETD (Shared Entities Type Diversity)**\n- **PTC (Path Type Concentration)**\n- **PPT (Path Pattern Type)**\n- **PTD/PPC (Path Type Diversity)**\n- **Model Fidelity**\n\n🆕 **New Datasets**\n- **MovieLens-1M Small**: used in the papers [PEARLM](https://arxiv.org/abs/2310.16452) and [KGGLM](https://dl.acm.org/doi/10.1145/3640457.3691703)\n- **Last.FM-1M Small**: used in the papers [PEARLM](https://arxiv.org/abs/2310.16452) and [KGGLM](https://dl.acm.org/doi/10.1145/3640457.3691703)\n- **Yelp 2018**: used in the paper [KGAT](https://dl.acm.org/doi/10.1145/3292500.3330989)\n- **Alibaba Fashion**: used in the paper [KGRec](https://dl.acm.org/doi/10.1145/3580305.3599400)\n\nAll the datasets are available as zip archives on [Google Drive](https://drive.google.com/drive/folders/1Zv57Xfo3mC2DemQbHf5XkYKBluRALQNm?usp=drive_link).\n\n\u003e [!IMPORTANT]\n\u003e **Check the paper for the other changes.**\n\n## ⚡ Installation\n\nTo install the project, you need to use `uv`. Follow the steps below to set up the environment and install the necessary dependencies.\n\n## 🔹 Prerequisites\n- ✅ Python **3.9**, **3.10**, or **3.11**\n- ✅ [`uv`](https://github.com/astral-sh/uv) package manager\n\n---\n\n### 🔹 Steps (from PyPI or from Source)\n\n\n1️⃣ **Install **uv** and create a virtual environment.**\u003cbr\u003e\n\nWe suggest installing **uv** as a [standalone application](https://docs.astral.sh/uv/getting-started/installation/#standalone-installer) instead of using pip to avoid issues and let **uv** create a dedicated virtual environment.\u003cbr\u003e\nOnce installed, create the virtual environment\n\n```sh\nuv venv --python PYTHON_VERSION --prompt hopwise\n```\n`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.\n\n2️⃣ **Install via PyPI**\n\n```sh\nuv pip install hopwise\n```\n\nSome models require extra dependencies.\nIn particular, language models for KG path reasoning require extra dependencies to be installed.\nYou can install them by specifying the extra `pathlm` in the command line as follows:\n```sh\nuv pip install hopwise[pathlm]\n```\n\nOther models can be installed with a similar process. For instance, to install NNCF:\n```sh\nuv pip install hopwise[nncf]\n```\n\nPlease check the [PyPI page](https://pypi.org/project/hopwise/) for the complete list of extra dependencies and the [documentation](https://hopwise.readthedocs.io/en/latest/installation.html#extra-dependencies) for more details on how to install hopwise with specific dependencies.\n\n**🎉 Done 🎉**\n\n---\n\n2️⃣ **Install from source: Clone the repository**\n```sh\ngit clone https://github.com/tail-unica/hopwise.git\ncd hopwise\n```\n\n\n3️⃣ Install project dependencies\n\n*📌 make sure to have uv updated to the latest version*\n\n```sh\nuv sync\n```\n\n\u003e 📢 **Windows:** For proper DGL installation, please follow the [official DGL installation guide](https://www.dgl.ai/pages/start.html). 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.\n\n**🎉 Done 🎉**\n\n## 🚀 Usage\nIn any chosen setup, a .yaml file must be created containing the configuration to be used. An example:\n```yaml\ngpu_id: 0\ntopk: [10,20,50,...]\ndata_path: *your_datasets_folder*\nmetrics: ['NDCG', 'MRR', 'Hit', 'Precision', 'Recall',...]\nvalid_metric: ndcg@10\neval_batch_size: 1\nepochs: 1\neval_step: 1\n```\n\n### 📍 Training\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"#readme\"\u003e\n        \u003cimg alt=\"traintest\" src=\"https://github.com/tail-unica/hopwise/blob/main/assets/trainpgprclip.gif\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\nRun the project with the following command:\n```sh\nhopwise train \\\n    --model MODEL \\\n    --dataset DATASET \\\n    --config_files CONF_FILE_1.yaml CONF_FILE_2.yaml\n```\n\nOverride config parameters directly from the CLI using =:\n```sh\nhopwise train --epochs=20\n```\n\n### 📍 Evaluating from Checkpoint\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"#readme\"\u003e\n        \u003cimg alt=\"pgprevaltest\" src=\"https://github.com/tail-unica/hopwise/blob/main/assets/pgprevaluation.gif\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n```sh\nhopwise evaluate --dataset DATASET --model MODEL \\\n--config-files CONFIG_FILES --checkpoint CHECKPOINT.pth\n```\n\n### 📍 Hyperparameters Tuning\n\nIn 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\n\n```yaml\nlearning_rate uniform 0.0001, 0.1\nembedding_size choice [64, 100, 200]\n```\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"#readme\"\u003e\n        \u003cimg alt=\"hypertuningtest\" src=\"https://github.com/tail-unica/hopwise/blob/main/assets/hypertuningbpr.gif\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n```sh\nhopwise tune \\\n    --params-file hopwise/properties/hyper/PARAMS_FILE.hyper \\\n    --config-files CONFIG_FILE.yaml \\\n    --study-name STUDY_NAME\n```\n\n## ℹ️ Contributing\nPlease let us know if you encounter a bug or have any suggestions by filing an issue.\n\nWe welcome all contributions from bug fixes to new features and extensions. 🚀\n\nWe expect all contributions discussed in the issue tracker and going through PRs. 📌\n\n## 📜 Cite\nIf you find **hopwise** useful for your research or development, please cite with:\n\n```bibtex\n\n@inproceedings{10.1145/3746252.3761641,\n  author = {Boratto, Ludovico and Fenu, Gianni and Marras, Mirko and Medda, Giacomo and Soccol, Alessandro},\n  title = {hopwise: A Python Library for Explainable Recommendation based on Path Reasoning over Knowledge Graphs},\n  year = {2025},\n  isbn = {9798400720406},\n  publisher = {Association for Computing Machinery},\n  address = {New York, NY, USA},\n  url = {https://doi.org/10.1145/3746252.3761641},\n  doi = {10.1145/3746252.3761641},\n  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.},\n  booktitle = {Proceedings of the 34th ACM International Conference on Information and Knowledge Management},\n  pages = {6328–6333},\n  numpages = {6},\n  keywords = {language model, path reasoning, reproducibility, transparency},\n  location = {Seoul, Republic of Korea},\n  series = {CIKM '25}\n  }\n\n```\n\n## The Team\n\n[Ludovico Boratto](https://www.ludovicoboratto.com/), [Gianni Fenu](https://web.unica.it/unica/it/ateneo_s07_ss01.page?contentId=SHD30371), [Mirko Marras](https://www.mirkomarras.com/), [Giacomo Medda](https://jackmedda.github.io/), [Alessandro Soccol](https://alessandrosocc.github.io)\n\n\n\n\n## License\nThis project is licensed under the MIT License. See the LICENSE file for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftail-unica%2Fhopwise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftail-unica%2Fhopwise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftail-unica%2Fhopwise/lists"}