Imported from sathariels/SageRec (scripts/AGENTS.md). Install upstream with npx skills add sathariels/SageRec --skill scripts. Copyright stays with the author.

Workflow Script Agent Guide

Scripts are thin, reproducible entry points rather than homes for business logic.

• Fail fast and propagate nonzero exit codes.
• Resolve paths from the repository or explicit arguments, never a developer home path.
• Accept configuration, seed, dataset path, output path, and device explicitly.
• Print the effective command/config and versions needed for provenance.
• Delegate implementation to tested native or Python modules.
• Avoid implicit destructive cleanup and environment mutation.
• Document each supported script in the root README.

Opened Phase 2/3 scripts (MovieLens 100K only):

• download_movielens_100k.py — fetch the official zip, verify MD5, extract u.data.
• prepare_movielens_100k.py — ADR-003 on-disk prep from a local u.data path.
• run_mf_movielens_100k.py — seeded implicit MF on prepared artifacts.

Opened Phase 4 GraphSAGE synthetic smoke:

• run_graphsage_synthetic_smoke.py — tiny ADR-003 GraphSAGE protocol smoke using native sagerec_minibatch. Prints labeled protocol-smoke metrics; do not write MovieLens 100K GNN result files.

Opened Phase 5 100K GraphSAGE + comparison:

• run_graphsage_movielens_100k.py — download/prep if needed, train GraphSAGE on the native mini-batch harness (seed 7) with PyG SAGEConv, evaluate with shared PairScorer metrics, write results/graphsage_movielens_100k.json. Do not retcon stored Phase 5 numbers without a measured rerun.
• write_gnn_vs_mf_comparison.py — read stored MF + GraphSAGE JSONs and write comparison JSON, markdown table, and SVG chart. Does not invent metrics.

Opened Phase 7 multi-seed leaderboard (ADR-007):

• run_multiseed_gnn_vs_mf.py — download/prep if needed, train implicit MF and native-backed GraphSAGE (PyG SAGEConv) across seeds 7, 11, 13, 17, 19, write results/multiseed_gnn_vs_mf_movielens_100k.{json,md,svg}. Does not overwrite Phase 5 single-seed files. Do not run this 100K job in default CI.

Opened Phase 2 sampler timing:

• run_sampler_timing.py — verify native/reference sample_neighbors parity, then time both on the same ADR-005 workload. Writes results/sampler_timing.json, .md, and .svg. Default source is a deterministic synthetic graph. --source movielens-100k uses existing train-only processed/ artifacts and never downloads.

Do not add MovieLens 1M scripts. The Phase 4 mini-batch helper lives in python/sagerec_minibatch.py. GraphSAGE training lives in python/sagerec_graphsage.py (Phase 6: PyG SAGEConv, native neighborhoods). Sampler timing logic lives in python/sagerec_sampler_benchmark.py.