hopwise: A Python Library for Explainable Recommendation based on Path Reasoning over Knowledge Graphs

Motivation

Personalized recommender systems have become essential in helping users navigate complex decision spaces, from media consumption to food choices and educational pathways. As these systems influence several aspects of daily life, the demand for transparency and accountability has grown significantly.

Knowledge graphs (KGs) have emerged as a powerful foundation for enhancing recommender systems with structured, semantic connections between users and items. Path-based reasoning over KGs enables generating human-interpretable explanations that trace the reasoning from user to recommended item.

The hopwise Framework

hopwise is an open-source library that supports the full life-cycle of explainable path reasoning recommendation methods over knowledge graphs. Rather than building from scratch, it extends the widely adopted RecBole ecosystem to ensure compatibility and promote adoption.

Key Components

• Data and Configuration Management: Dataset preprocessing, checkpointing, and hyperparameter search integration with Optuna, Ray, and Hyperopt
• Graph Path Sampling: Utilities for sampling and validating explanation paths from knowledge graphs
• Model Interface: Support for general, sequential, knowledge-aware, context-aware, and path reasoning recommenders
• Evaluation Pipeline: Unified evaluation of utility, beyond-accuracy goals, and path quality metrics
• Explanation Visualization: Tools for visualizing and analyzing generated explanation paths

Supported Models

hopwise supports a comprehensive suite of models for both link prediction and recommendation tasks:

• Knowledge Graph Embeddings: TransE, TransH, TransR, DistMult, ComplEx, RotatE, TuckER, ConvE, HolE, AnalogE, RESCAL
• Path Reasoning Models: PLM, KGAT, PGPR, CAFE, and other path-based methods
• Explainability Interface: Each path-based model implements an explain() function to generate {user, item, score, path} quadruples

Evaluation Metrics

hopwise extends RecBole's evaluation with novel beyond-utility metrics focused on explanation quality:

Perceived Usefulness

• Serendipity (SER): Level of unexpectedness and relevance of recommendations
• Novelty (NOV): Inverse popularity of recommended items

Consumer Fairness

• Utility Disparity (ΔS): Absolute difference in utility between consumer groups

Explanation Path Quality

• Fidelity (FID): Percentage of recommended items that can be explained
• Linking Interaction Recency (LIR): Recency of past interactions in explanation paths
• Linking Interaction Diversity (LID): Diversity of past interactions in paths
• Shared Entity Popularity (SEP): Popularity of shared entities in paths
• Shared Entity Diversity (SED): Diversity of shared entities in paths
• Path Type Diversity (PTD): Percentage of distinct path types within explanations
• Path Type Concentration (PTC): Balance in representation of distinct path types

Supported Datasets

Key Contributions

• Unified Framework: First comprehensive library supporting the full life-cycle of explainable path reasoning recommendation
• RecBole Integration: Built on top of the widely adopted RecBole ecosystem for compatibility and ease of adoption
• Path Quality Metrics: Novel evaluation standards for assessing explanation path utility, coverage, and diversity
• Standardized Interface: Clean API for implementing new path-based models with explanation generation
• Reproducibility: Checkpointing, data split saving, and configuration management for reproducible experiments

Comparison with Existing Libraries

hopwise fills a gap in the recommendation library landscape by combining:

• Link prediction task support
• Beyond-utility metrics
• Path-based explainability
• Path quality metrics
• Full usability features (checkpoints, data loaders, config management)

Unlike XRecSys, the only other library with path-based techniques, hopwise offers a modular design that enables extensibility and includes features like saving data splits and resuming from checkpoints.

Getting Started

Install hopwise and start building explainable recommender systems:

pip install hopwise
# or clone from GitHub
git clone https://github.com/tail-unica/hopwise

Check the GitHub repository for documentation, examples, and tutorials.