# tail-unica/hopwise architecture

> Architecture diagram of the GitHub repository tail-unica/hopwise, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tail-unica/hopwise
- Repository: https://github.com/tail-unica/hopwise

## Overview

##### Project Type and Purpose
- hopwise is a Python library—an extension of the RecBole recommender-system framework—focused on knowledge-graph-enhanced recommendation and explainability. It exposes a CLI entry point (`run_hopwise.py`) and example scripts, but its core is a modular, plugin-based library for data loading, model definition, training, and evaluation.

##### Main Architectural Components
a. CLI & Configuration
- `run_hopwise.py` (and related scripts) invoke the system.
- `hopwise/config/configurator.py` reads YAML config files (from `properties/`) and merges CLI overrides.
b. Data Layer
- Abstract interfaces: `hopwise/data/dataloader/abstract_dataloader.py`.
- Concrete loaders: general, KG, user, knowledge loaders.
- Dataset classes in `hopwise/data/dataset/` wrap raw data into PyTorch/DGL-friendly objects.
- Utility modules for transform, interaction, sampling.
c. Sampler
- `hopwise/sampler/sampler.py` produces batches or KG paths.
d. Model Registry & Implementations
- Base interface: `hopwise/model/abstract_recommender.py`.
- Subpackages for each family:
– context_aware_recommender
– general_recommender
– knowledge_aware_recommender
– knowledge_graph_embedding_recommender
– path_language_modeling_recommender
– sequential_recommender
- Each model class implements `.forward()`, `.predict()`, etc.
e. Trainer & Hyper-Tuning
- `hopwise/trainer/trainer.py` orchestrates the training loop (data → model → loss → optimizer → sampler).
- `hopwise/trainer/hf_path_trainer.py` for HuggingFace-style modeling.
- `hyper_tuning.py` for grid/random search over config space.
f. Evaluator
- `hopwise/evaluator/evaluator.py`, metrics (ranking, loss, top-K) and collector.
g. Utilities & Logging
- `hopwise/utils/logger.py` sets up logging.
- `wandblogger.py` for optional Weights & Biases integration.
h. Quick-Start & Examples
- Scripts in `hopwise/quick_start/` and `run_example/` illustrate common workflows.

##### Component Interactions & Data Flow
1) User calls CLI → Configurator loads CLI + YAML.
2) Configurator instantiates DataLoader → Dataset → Sampler.
3) Trainer receives model class from registry using config → initializes model, optimizer, loss.
4) Training loop: Sampler yields batches → Model forward pass → Loss → Backprop → Optimizer step.
5) At epoch end: Evaluator computes metrics → Logger/W&B logs.
6) Upon completion: artifacts (checkpoints, metrics) are saved.

##### Architectural Patterns & Design Principles
- Plugin architecture: abstract base classes for DataLoader, Recommender, Sampler, allowing easy extension.
- Layered design: separation of concerns between config, data ingestion, modeling, training, and evaluation.
- Configuration-driven: behavior entirely controlled by YAML + CLI args, with no hard-coded paths.

##### Technologies & Frameworks
- Python 3.9–3.11
- RecBole (as base)
- PyTorch, DGL (for GNN models)
- uv (dependency manager & CLI runner)
- YAML for config (`hopwise/properties/`)
- Optional: LightGBM, XGBoost backends; HuggingFace trainer; Weights & Biases.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Configuration
    subgraph "CLI & Configuration"
        CLI["run_hopwise.py"]:::core
        Configurator["Configurator\n«reads YAML & CLI»"]:::core
        CLI -->|invokes| Configurator
    end

    %% Configuration Files
    subgraph "Configuration Files"
        Properties["hopwise/properties/\n(dataset/, model/, quick_start_config/, overall.yaml)"]:::data
        Properties --> Configurator
    end

    %% Data Layer
    subgraph "Data Layer"
        ADL["«abstract» DataLoader\nabstract_dataloader.py"]:::data
        GD["GeneralDataLoader"]:::data
        KD["KnowledgeDataLoader"]:::data
        UD["UserDataLoader"]:::data
        ADL -->|implements| GD
        ADL -->|implements| KD
        ADL -->|implements| UD

        subgraph "Datasets"
            DS1["dataset.py"]:::data
            DS2["customized_dataset.py"]:::data
            DS3["decisiontree_dataset.py"]:::data
            DS4["kg_dataset.py"]:::data
            DS5["kg_path_dataset.py"]:::data
            DS6["kg_seq_dataset.py"]:::data
            DS7["sequential_dataset.py"]:::data
        end
        GD --> DS1
        GD --> DS2
        KD --> DS4
        KD --> DS5
        KD --> DS6
        UD --> DS7

        subgraph "Data Utilities"
            Transform["transform.py"]:::data
            Interaction["interaction.py"]:::data
            UtilsData["utils.py"]:::data
        end
        DS1 --> Transform
        DS1 --> Interaction
        DS1 --> UtilsData

        ADL --> DatasetGroup((Dataset))
        DatasetGroup --> Sampler
    end

    %% Sampler
    Sampler["Sampler\nsampler.py"]:::data

    %% Model Registry & Implementations
    subgraph "Model Layer"
        MRI["«abstract» Recommender\nabstract_recommender.py"]:::model
        MRI --> ContextAware
        MRI --> GeneralRec
        MRI --> KnowledgeAware
        MRI --> KGEmbedding
        MRI --> PathLM
        MRI --> SequentialRec

        subgraph "Families"
            ContextAware["context_aware_recommender/"]:::model
            GeneralRec["general_recommender/"]:::model
            KnowledgeAware["knowledge_aware_recommender/"]:::model
            KGEmbedding["knowledge_graph_embedding_recommender/"]:::model
            PathLM["path_language_modeling_recommender/"]:::model
            SequentialRec["sequential_recommender/"]:::model
        end

        Layers["layers.py"]:::model
        Loss["loss.py"]:::model
        Layers --> MRI
        Loss --> MRI
    end

    %% Trainer & Hyper-Tuning
    subgraph "Training Pipeline"
        Trainer["Trainer\ntrainer.py"]:::train
        HFTrainer["HFPathTrainer\nhf_path_trainer.py"]:::train
        HyperTuning["HyperTuning\nhyper_tuning.py"]:::train
        Configurator --> Trainer
        Sampler --> Trainer
        Tracker((Model Registry)):::model --> Trainer
        Trainer --> HFTrainer
        Trainer --> HyperTuning
    end

    %% Evaluator
    subgraph "Evaluation Pipeline"
        Evaluator["Evaluator\nevaluator.py"]:::train
        Metrics["metrics.py"]:::train
        BaseMetric["base_metric.py"]:::train
        Collector["collector.py"]:::train
        EvalUtils["utils.py"]:::train
        Register["register.py"]:::train
        Evaluator --> Metrics
        Evaluator --> BaseMetric
        Evaluator --> Collector
        Evaluator --> EvalUtils
        Evaluator --> Register
        Trainer --> Evaluator
    end

    %% Utilities & Logging
    subgraph "Utilities & Logging"
        Logger["logger.py"]:::core
        WandB["wandblogger.py"]:::external
        ArgList["argument_list.py"]:::core
        UtilsCore["utils.py"]:::core
        URL["url.py"]:::core
        CaseStudy["case_study.py"]:::core
        EnumType["enum_type.py"]:::core
        Trainer --> Logger
        Evaluator --> Logger
        Logger --> WandB
    end

    %% Examples & Quick-Start
    subgraph "Examples & Quick-Start"
        QuickStart["quick_start.py"]:::core
        RunExample["run_example/"]:::core
        CLI --> QuickStart
        QuickStart --> RunExample
    end

    %% External Dependencies
    subgraph "External Dependencies"
        PyTorch(("PyTorch")):::external
        DGL(("DGL")):::external
        RecBole(("RecBole")):::external
        WnB(("Weights & Biases")):::external
        PyTorch -.-> Trainer
        DGL -.-> Trainer
        RecBole -.-> MRI
        WandB -.-> WnB
    end

    %% Legend
    subgraph Legend
        C1["Blue: Core Modules"]:::core
        C2["Green: Data Components"]:::data
        C3["Orange: Model Components"]:::model
        C4["Purple: Training/Eval"]:::train
        C5["Gray: External"]:::external
    end

    %% Click Events
    click CLI "https://github.com/tail-unica/hopwise/blob/main/run_hopwise.py"
    click Configurator "https://github.com/tail-unica/hopwise/blob/main/hopwise/config/configurator.py"
    click ADL "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/dataloader/abstract_dataloader.py"
    click GD "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/dataloader/general_dataloader.py"
    click KD "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/dataloader/knowledge_dataloader.py"
    click UD "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/dataloader/user_dataloader.py"
    click DS1 "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/dataset/dataset.py"
    click DS2 "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/dataset/customized_dataset.py"
    click DS3 "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/dataset/decisiontree_dataset.py"
    click DS4 "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/dataset/kg_dataset.py"
    click DS5 "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/dataset/kg_path_dataset.py"
    click DS6 "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/dataset/kg_seq_dataset.py"
    click DS7 "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/dataset/sequential_dataset.py"
    click Transform "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/transform.py"
    click Interaction "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/interaction.py"
    click UtilsData "https://github.com/tail-unica/hopwise/blob/main/hopwise/data/utils.py"
    click Sampler "https://github.com/tail-unica/hopwise/blob/main/hopwise/sampler/sampler.py"
    click MRI "https://github.com/tail-unica/hopwise/blob/main/hopwise/model/abstract_recommender.py"
    click ContextAware "https://github.com/tail-unica/hopwise/tree/main/hopwise/model/context_aware_recommender/"
    click GeneralRec "https://github.com/tail-unica/hopwise/tree/main/hopwise/model/general_recommender/"
    click KnowledgeAware "https://github.com/tail-unica/hopwise/tree/main/hopwise/model/knowledge_aware_recommender/"
    click KGEmbedding "https://github.com/tail-unica/hopwise/tree/main/hopwise/model/knowledge_graph_embedding_recommender/"
    click PathLM "https://github.com/tail-unica/hopwise/tree/main/hopwise/model/path_language_modeling_recommender/"
    click SequentialRec "https://github.com/tail-unica/hopwise/tree/main/hopwise/model/sequential_recommender/"
    click Layers "https://github.com/tail-unica/hopwise/blob/main/hopwise/model/layers.py"
    click Loss "https://github.com/tail-unica/hopwise/blob/main/hopwise/model/loss.py"
    click Trainer "https://github.com/tail-unica/hopwise/blob/main/hopwise/trainer/trainer.py"
    click HFTrainer "https://github.com/tail-unica/hopwise/blob/main/hopwise/trainer/hf_path_trainer.py"
    click HyperTuning "https://github.com/tail-unica/hopwise/blob/main/hopwise/trainer/hyper_tuning.py"
    click Evaluator "https://github.com/tail-unica/hopwise/blob/main/hopwise/evaluator/evaluator.py"
    click BaseMetric "https://github.com/tail-unica/hopwise/blob/main/hopwise/evaluator/base_metric.py"
    click Metrics "https://github.com/tail-unica/hopwise/blob/main/hopwise/evaluator/metrics.py"
    click Collector "https://github.com/tail-unica/hopwise/blob/main/hopwise/evaluator/collector.py"
    click EvalUtils "https://github.com/tail-unica/hopwise/blob/main/hopwise/evaluator/utils.py"
    click Register "https://github.com/tail-unica/hopwise/blob/main/hopwise/evaluator/register.py"
    click Logger "https://github.com/tail-unica/hopwise/blob/main/hopwise/utils/logger.py"
    click WandB "https://github.com/tail-unica/hopwise/blob/main/hopwise/utils/wandblogger.py"
    click ArgList "https://github.com/tail-unica/hopwise/blob/main/hopwise/utils/argument_list.py"
    click UtilsCore "https://github.com/tail-unica/hopwise/blob/main/hopwise/utils/utils.py"
    click URL "https://github.com/tail-unica/hopwise/blob/main/hopwise/utils/url.py"
    click CaseStudy "https://github.com/tail-unica/hopwise/blob/main/hopwise/utils/case_study.py"
    click EnumType "https://github.com/tail-unica/hopwise/blob/main/hopwise/utils/enum_type.py"
    click QuickStart "https://github.com/tail-unica/hopwise/blob/main/hopwise/quick_start/quick_start.py"
    click RunExample "https://github.com/tail-unica/hopwise/tree/main/run_example/"
    click Properties "https://github.com/tail-unica/hopwise/tree/main/hopwise/properties/"
    
    %% Styles
    classDef core fill:#D6E9F8,stroke:#2C6CAB,color:#0F3057
    classDef data fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10
    classDef model fill:#FEEFB3,stroke:#9F6000,color:#9F6000
    classDef train fill:#F3E2FF,stroke:#8A2BE2,color:#8A2BE2
    classDef external fill:#E0E0E0,stroke:#888888,color:#333333
    classDef Legend fill:#FFFFFF,stroke:#000000,color:#000000,stroke-dasharray: 2 2
```
