hoploy: a Plugin-Based Inference Layer for Path-Based Explainable Recommendation over Knowledge Graphs

Motivation

Personalized recommender systems influence decisions in domains such as media, education, and e-commerce, raising the need for transparent and accountable recommendations. Knowledge graphs (KGs) provide a natural basis for explainable recommendation because they represent users, items, and domain concepts through typed entities and relations. Among KG-based approaches, path-based methods — which construct sequences of entity–relation triples linking users to items — are among the most promising paradigms for explainable recommendation.

Recent path-based approaches include reinforcement-learning agents that navigate a KG under path constraints and autoregressive models that generate reasoning paths token by token. These methods support faithful and interpretable explanations, but existing implementations mainly target offline training and evaluation. Frameworks such as hopwise have improved reproducibility by providing path sampling utilities, path-based models, and path quality metrics — yet deploying these models in interactive applications remains difficult.

The hoploy Framework

hoploy is an open-source inference and explanation layer for pre-trained path-reasoning models from the hopwise library. It does not introduce a new recommendation algorithm; instead, it provides the infrastructure needed to expose existing path-based models in stateless, API-based settings. hoploy separates a reusable inference pipeline from application- and model-specific components, letting developers define API schemas, configuration, KG grounding logic, decoding controls, and explanation rendering without modifying the core framework.

Positioning

General serving systems expose models through APIs, and recommender frameworks provide training, inference, evaluation, or deployment support. However, none natively cover the full path-based explainable recommendation (XRec) serving workflow: request-time KG grounding, KG-aware decoding, and explanation rendering. Conversely, hopwise provides the path-based modeling and evaluation layer, but not an API-oriented serving layer for interactive applications.

Architecture

hoploy separates a reusable inference workflow from plugin-defined application logic. The core framework handles configuration loading, API construction, component validation, model execution, and request orchestration. Plugins provide the application-specific elements: request and response schemas, preference mapping, decoding controls, and explanation rendering.

Configuration and API Binding

A hoploy application is defined by two configuration levels: a framework configuration specifying generic inference behavior, and a plugin configuration declaring the components and endpoints required by a target application. The API layer is generated from the plugin specification rather than hard-coded — a plugin declares the request/response schemas for each endpoint together with the component that handles it, and hoploy binds each endpoint to the initialized pipeline. The core framework exposes only infrastructure-level endpoints, keeping the API domain-specific while preserving a shared inference workflow.

Extension Components

• Wrapper (mandatory): The central component that bridges the application-level API and the model-level representation used by hopwise. It maps incoming requests to model-ready inputs, configures request-specific inference parameters (e.g., path diversity), and expands generated outputs into the application response, including recommended items and human-readable explanations.
• Logits processors (optional): Customize decoding while paths are generated, adjusting candidate-token scores at each step. Following the constrained-decoding paradigm, they enforce request-dependent constraints, promote or penalize entities, or guide generation toward predefined relation patterns. Defaults include graph-valid traversal constraints, masking of previously recommended items, entity restrictions, and relation-pattern forcing.
• Sequence processor (optional): Operates on complete generated paths after candidate paths are produced, enabling operations easier to express over full paths, such as duplicate removal, invalid-sequence filtering, or re-ranking.
• Catalog service (shared): A support service used by wrappers and processors to resolve application-level identifiers into hopwise model tokens, centralizing access to KG and item metadata for both preference mapping and path rendering.

Request Lifecycle

At startup, hoploy resolves the configured plugins, instantiates their components by role, and validates each implementation against its role-specific interface. This fail-fast initialization keeps loaded models, KG mappings, and catalog metadata available across requests. For each recommendation request, hoploy executes four steps:

1. Input distillation: The wrapper maps the request payload to model-compatible inputs, resolving selected items through the catalog into the representation expected by the hopwise model.
2. Request-specific configuration: The wrapper and optional processors derive inference parameters from the request, such as the number of recommendations, the diversity level, or entity restrictions.
3. Path generation: The framework runs the underlying hopwise model to produce candidate reasoning paths, while plugin-defined logits and sequence processors can influence decoding or post-process the generated paths.
4. Output expansion: The wrapper converts the generated paths back into KG triples, enriches them with catalog metadata, and renders the response — recommendations plus human-readable explanations.

Reference Plugins

hoploy is demonstrated through two reference plugins that follow the same development workflow but differ in schemas, domain metadata, preference mapping, decoding constraints, and explanation rendering.

• POI Recommendation: Targets scenarios where users provide preferred places and sensory aversion levels during an interaction, building on prior work on sensory-aware POI recommendation. After conversion to the hopwise format, the dataset contains 524 entities, ~50k triples, and ~7k interactions between 149 users and 243 POIs. The wrapper resolves place names through the catalog, maps sensory aversions to KG constraints, and renders paths via predefined templates.
• Food Recommendation: Applies the same workflow to recipe recommendation, using the HUMMUS KG enriched with GreenFoodLens sustainability labels. The converted resource contains ~227k entities, ~1.6M triples, and ~630k interactions between ~23k users and ~66k recipes. Requests include liked food items plus hard and soft restrictions; the wrapper resolves food names and enriches outputs with metadata, while decoding processors exclude or penalize restricted items (e.g., "tomato" as a hard restriction filters out recipes containing that ingredient).

Resource Validation

The evaluation assesses whether hoploy can be instantiated with limited plugin-specific code and served with a practical deployment footprint — not whether it improves recommendation quality. Both plugins are implemented with a compact amount of code (excluding the core framework), with most effort concentrated in schemas and wrappers, confirming hoploy's role as a lightweight adaptation layer.

After initialization, both plugins serve requests suitable for interactive prototypes and user-study settings. The food plugin's longer initialization, higher latency, and larger memory footprint reflect its substantially larger KG and richer metadata, identifying it as the primary target for future serving optimizations.

Key Contributions

• Inference & explanation layer: An open-source layer that exposes pre-trained path-reasoning models from hopwise through stateless, configurable APIs.
• Plugin abstraction: A lightweight design that decouples application schemas, KG grounding, decoding controls, and explanation rendering from the core inference workflow.
• Repeatable instantiation: POI and food recommendation plugins that demonstrate the same workflow across domains, with reported KG statistics, plugin-specific implementation effort, and serving footprint.
• Bridge to human evaluation: By exposing path-based explanations through stateless endpoints, hoploy lets researchers embed trained models into surveys and prototypes, collect human feedback, and test whether explanations are meaningful in new domains — complementing the offline evaluation supported by hopwise.

Getting Started

hoploy and its released POI and food plugins provide executable starting points for extending path-based explainable recommendation to new domains. Full execution traces and request–response examples for both plugins are provided in the repository.

Check the GitHub repository for documentation, examples, and extension guides.