CAGE-EnvEASE

CAGE-EnvEASE is a research implementation for cross-city site recommendation on OpenSiteRec. It extends Optimal Transport enhanced Cross-city recommendation (OTC) with confidence-aware transfer, adaptive source-city weighting, and an environment-aware EASE specialist.

Highlights

• MF and LightGCN backbones trained independently for each city.
• Brand- and region-level cross-city transport with optional Gromov-Wasserstein alignment.
• City-pair similarity based on category, business-area, brand-overlap, sparsity, and embedding statistics.
• Transport confidence estimated from entropy, top-k mass concentration, and source-city density.
• CAGE adaptive transfer and optional reranking variants.
• EnvEASE environment-aware region scoring with validation-selected blending.
• Recall@20, nDCG@20, sparse-brand, dense-brand, and long-tail-region metrics.
• Transfer diagnostics and brand-level explanations.

Repository Layout

.
|-- sc_otc/              # Models, transfer modules, and experiment entry points
|-- tests/               # Self-contained unit tests
|-- pyproject.toml       # Package and dependency configuration
`-- requirements.txt     # Minimal runtime dependencies

OpenSiteRec data and third-party baseline repositories are intentionally not included.

Installation

Python 3.10 or newer is required.

git clone https://github.com/HestiaSky/OpenSiteRec.git external/OpenSiteRec
python -m venv .venv
python -m pip install --upgrade pip
python -m pip install -e ".[gw,test]"

The gw extra installs POT for Gromov-Wasserstein transport. Without POT, use descriptor transport or leave --transport-method auto enabled so the scalable fallback can be selected.

Data Layout

Point --data-root to an OpenSiteRec checkout containing one directory per city:

external/OpenSiteRec/
|-- Chicago/
|-- NYC/
|-- Singapore/
`-- Tokyo/

Each city directory must contain the corresponding *_KG_plus.csv file. Brand and region metadata files are loaded when present.

Run an Experiment

Full CAGE-EnvEASE configuration:

python -m sc_otc.experiment \
  --data-root external/OpenSiteRec \
  --output-dir outputs/cage_envease \
  --model LightGCN \
  --epochs 80 \
  --transport-method auto \
  --enable-cage \
  --enable-envease

Quick CPU smoke test:

python -m sc_otc.experiment \
  --data-root external/OpenSiteRec \
  --output-dir outputs/smoke \
  --cities Chicago NYC \
  --model MF \
  --epochs 1 \
  --dim 16 \
  --batch-size 512 \
  --transport-method descriptor

PowerShell users can replace each trailing \\ with a backtick.

Outputs

• metrics.csv: backbone, OTC, SC-OTC, CAGE, and EnvEASE metrics enabled by the selected configuration.
• transfer_diagnostics.csv: source-target similarity, transport confidence, and transport method.
• explanations.json: source-brand matches for selected target brands.
• run_config.json: arguments and runtime metadata.

Testing

python -m pytest -q
python -m sc_otc.experiment --help

Reproducibility Notes

• Use --seed to control model training and deterministic data splitting.
• Report the OpenSiteRec commit, Python environment, transport method, and full command with every result.
• Generated outputs and datasets are excluded from version control by default.

Acknowledgements

This project uses the OpenSiteRec dataset and builds on the OTC cross-city site recommendation formulation. Please cite the original dataset and method papers when using this implementation in academic work.

License

This project is released under the MIT License.