{"id":44350990,"url":"https://github.com/radlab-dev-group/relgat-projector","last_synced_at":"2026-02-11T15:05:59.061Z","repository":{"id":311812957,"uuid":"1044999699","full_name":"radlab-dev-group/relgat-projector","owner":"radlab-dev-group","description":"A hybrid Relational-GAT with a projection head that learns relation operators to transform embeddings, impute unseen node vectors, and expand search queries via relational paths.","archived":false,"fork":false,"pushed_at":"2025-09-16T16:32:26.000Z","size":243,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-16T19:17:57.048Z","etag":null,"topics":["link-prediction","llm","projection","relation-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/radlab-dev-group.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-26T14:05:50.000Z","updated_at":"2025-09-16T16:32:20.000Z","dependencies_parsed_at":"2025-08-27T02:33:15.570Z","dependency_job_id":"053c6d32-5ad9-46aa-ad3a-60eaa4f870a0","html_url":"https://github.com/radlab-dev-group/relgat-projector","commit_stats":null,"previous_names":["radlab-dev-group/relgat-llm","radlab-dev-group/relgat-projector"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/radlab-dev-group/relgat-projector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radlab-dev-group%2Frelgat-projector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radlab-dev-group%2Frelgat-projector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radlab-dev-group%2Frelgat-projector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radlab-dev-group%2Frelgat-projector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/radlab-dev-group","download_url":"https://codeload.github.com/radlab-dev-group/relgat-projector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radlab-dev-group%2Frelgat-projector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29336095,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T14:34:07.188Z","status":"ssl_error","status_checked_at":"2026-02-11T14:34:06.809Z","response_time":97,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["link-prediction","llm","projection","relation-learning"],"created_at":"2026-02-11T15:05:58.313Z","updated_at":"2026-02-11T15:05:59.055Z","avatar_url":"https://github.com/radlab-dev-group.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RelGAT Projector and RelGAT trainer with frozen embeddings\nThis repository provides a hybrid Relational-GAT model with a projection head back to the input embedding space, \nenabling relation-specific operators (TransE/DistMult) to be applied consistently inside and outside the graph. \nThe model supports inductive embedding imputation for nodes without vectors and relation-driven query expansion \nby composing operators along graph paths—all in the same embedding space used within retriever. \nIncludes multi-objective training (ranking + reconstruction), metrics (MRR/Hits, cosine, MSE), and utilities for inference and export.\n\n\nA lightweight trainer for Relational Graph Attention Networks (RelGAT) that learns \nrelation-aware node representations from a knowledge graph. It consumes precomputed \nnode embeddings and relation triplets, and supports multi-head attention, \nnegative sampling, LR scheduling, checkpointing, and optional Weights \u0026 Biases logging.\n\n## Installation\n- Requirements: Python 3.9+, pip, and a PyTorch-compatible environment (CPU or CUDA).\n- Binary note: torch and torch-scatter must match your PyTorch/CUDA stack.\n\n\u003e **Prerequisite**: `radlab-ml-utils`\n\u003e\n\u003e This project uses the \n\u003e [radlab-ml-utils](https://github.com/radlab-dev-group/ml-utils) \n\u003e library for machine learning utilities \n\u003e (e.g., experiment/result logging with Weights \u0026 Biases/wandb).\n\u003e Install it before working with ML-related parts:\n\u003e\n\u003e ```bash\n\u003e pip install git+https://github.com/radlab-dev-group/ml-utils.git\n\u003e ```\n\u003e\n\u003e For more options and details, see the library README: \n\u003e https://github.com/radlab-dev-group/ml-utils\n\nInstall from local source:\n```bash \npip install .\n```\n\nEditable/development install:\n```bash\npip install -e .\n````\n\nInstall directly from a Git repository (replace URL accordingly):\n```bash\npip install \"git+[https://github.com/radlab-dev-group/relgat-projector.git#egg=relgat-projector](https://github.com/radlab-dev-group/relgat-projector.git#egg=relgat-projector)\"\n````\n\nAfter installation, a console entry point is available:\n```bash\nrelgat-projector-train --help\n```\n\nIf you run into issues with torch-scatter (especially on GPU), install the \nwheel matching your PyTorch/CUDA versions as per the project’s documentation.\n\n\n## Highlights\n- Relational multi-head GAT layers\n- Flexible scorers (distmult, transe)\n- Warmup/decay LR schedulers\n- Periodic evaluation and checkpointing\n- CPU/CUDA device selection\n\n## Dataset preparation\nThis trainer expects:\n- nodes embeddings file (lexical units)\n- relations mapping (relation name → id)\n- relation triplets (from_idx, to_idx, relation_name)\n\nYou can export a compatible dataset using the plwordnet-milvus CLI\n(see its repository for details — https://github.com/radlab-dev-group/plwordnet).\nExample:\n\n````bash\nplwordnet-milvus\n    --milvus-config=resources/milvus-config.json\n    --embedder-config=resources/embedder-config.json\n    --nx-graph-dir=/path/to/nx/graphs\n    --relgat-mapping-directory=resources/aligned-dataset-identifiers/\n    --export-relgat-dataset\n    --relgat-dataset-directory=resources/aligned-dataset-identifiers/dataset\n    --log-level=\"DEBUG\"\n````\n\n## Quick start\nTrain a model with your prepared files:\n\n```bash\nrelgat-projector-train\n    --nodes-embeddings-path /path/to/nodes_embeddings.pt\n    --relations-mapping /path/to/relations_mapping.json\n    --relations-triplets /path/to/relations_triplets.tsv\n    --gat-out-dim 200\n    --gat-num-layers 2\n    --heads 4\n    --scorer distmult\n    --epochs 10\n    --batch-size 1024\n    --lr 2e-4\n    --lr-scheduler cosine\n    --device cuda:0\n    --save-dir outputs/relgat_run\n    --save-every-n-steps 5000\n    --max-checkpoints 5\n```\n\nCommon flags:\n- --train-ratio: train/eval split ratio\n- --num-neg: negative samples per positive\n- --dropout: GAT dropout\n- --warmup-steps: warmup steps (auto if omitted)\n- --weight-decay, --grad-clip-norm: regularization\n- --eval-every-n-steps: step-based evaluation (or per-epoch by default)\n- --run-name: optional W\u0026B run name\n\n## Outputs\n- Checkpoints in save-dir/checkpoint-\u003cstep\u003e (if enabled)\n- Final model in save-dir\n\n## Requirements\n- Python 3.9+\n- PyTorch\n- torch-scatter\n\nInstall torch-scatter matching your PyTorch/CUDA version as per its documentation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradlab-dev-group%2Frelgat-projector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fradlab-dev-group%2Frelgat-projector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradlab-dev-group%2Frelgat-projector/lists"}