README.md

---
license: mit
library_name: pytorch
pipeline_tag: graph-ml
datasets:
- wzehui/Yelp-Multimodal-Recommendation
language:
- en
tags:
- POI
- recommendation
- recommender-system
- GNN
- graph-neural-network
- LightGCN
- contrastive-learning
- yelp
- arxiv:2608.16407
---

# LLM-MGCL: Checkpoints

Trained checkpoints for **LLM-MGCL**, from the paper
[*POI Recommendation with LLM-Augmented Multi-Graph Learning and Contrastive Alignment*](https://arxiv.org/abs/2608.16407)
(Tamer, Höpken, Wang, 2026).

Code: **[GitHub](https://github.com/wwebpy/LLM-MGCL)**

## Model

LLM-MGCL extends LightGCN with two item-item views and aligns them with contrastive learning:

| Graph | Edges | Edge weight |
|---|---|---|
| **G_UI** | user-item training interactions | star rating `(stars − 1) / 4`, clamped at 0.1 |
| **G_SEM** | top-10 most similar items within 50 km | cosine similarity of LLM-generated photo summaries (`all-MiniLM-L6-v2`) |
| **G_GEO** | top-10 nearest items within 50 km | `1 / (1 + distance_km)` (Haversine) |

The three graphs are propagated in parallel with LightGCN (3 / 2 / 2 layers) from shared
64-dimensional ego embeddings, and the item views are fused additively. Training uses BPR,
L2 regularisation (1e-3) and a bidirectional InfoNCE loss between the collaborative view and the
semantic and geographic views (λ = 0.05, τ = 0.2).

## Contents

All models were trained with seeds **42, 123 and 2024**, so there are 3 checkpoints per run.

| Run | Description |
|---|---|
| LLM-MGCL | full model |
| LLM-MGCL w/o CL | ablation: λ = 0 |
| LLM-MGCL w/o G_SEM | ablation: semantic view removed |
| LLM-MGCL w/o G_GEO | ablation: geographic view removed |
| LightGCN, SGL, NGCF, GC-MC, NeuMF, MF-BPR | baselines |

ItemKNN and UserKNN have no weights. The code computes them deterministically.

Each `.pt` file is a dict containing `model_state` (a PyTorch `state_dict`), `model_config` and
`seed`. These are raw PyTorch weights, not a `transformers` model. Load them with the model
classes from the GitHub repository.



## Usage

The checkpoints only work with the graphs and id mappings produced by the repository's
preprocessing, because user and item indices must match. Build them first, then download the
checkpoints and evaluate:

```bash
git clone <GITHUB-URL> && cd llm-mgcl
pip install -e .
python scripts/build_graphs.py                       # split, id mapping, G_UI / G_SEM / G_GEO

huggingface-cli download bbbur/LLM-MGCL --local-dir hf_checkpoints
python scripts/import_colab_checkpoints.py --src hf_checkpoints

python scripts/compare_models.py                     # Table 1, ablation, significance tests
python scripts/cold_start.py                         # cold-start analysis
```

Loading a single model in Python:

```python
from huggingface_hub import hf_hub_download
import torch
from llm_mgcl.models import build_model
from llm_mgcl.pipeline import load_dataset
from llm_mgcl.utils import load_config, get_device

cfg, device = load_config("configs/default.yaml"), get_device()
ds = load_dataset(cfg, device)

path = hf_hub_download("bbbur/LLM-MGCL", "<path/to/llm_mgcl_geo_seed42.pt>")
model = build_model("llm_mgcl", ds.data.n_users, ds.data.n_items, cfg).to(device)
model.load_state_dict(torch.load(path, map_location=device, weights_only=False)["model_state"])
model.eval()

scores = model.scorer(ds.graphs)(torch.tensor([0], device=device))   # [1, n_items]
```

## Training data

[wzehui/Yelp-Multimodal-Recommendation](https://huggingface.co/datasets/wzehui/Yelp-Multimodal-Recommendation).
Users with fewer than 3 reviews are removed. Each user's interactions are split 80 / 10 / 10 into
train / validation / test (`random_state=42`). The models were trained with Adam (lr 1e-3),
StepLR (step 20, γ 0.5) and batch size 2048 for up to 100 epochs. Early stopping is based on
validation Recall@20 (evaluated every 2 epochs, patience 8 evaluations).

## Limitations

* The models are transductive. They only score users and items seen during training, with the
  exact id mapping of the preprocessing.
* They were trained and evaluated on Yelp only, and results may not transfer to other cities,
  platforms or domains.


## Citation

```bibtex
@article{tamer2026llmmgcl,
  title         = {POI Recommendation with LLM-Augmented Multi-Graph Learning and Contrastive Alignment},
  author        = {Tamer, Burak and H{\"o}pken, Wolfram and Wang, Zehui},
  journal       = {arXiv preprint arXiv:2608.16407},
  year          = {2026},
  eprint        = {2608.16407},
  archivePrefix = {arXiv},
  primaryClass  = {cs.IR},
  url           = {https://arxiv.org/abs/2608.16407}
}
```

## License

MIT. Use of the Yelp data is subject to Yelp's dataset terms.