MoonGraphLearn

MoonGraphLearn 是一个 MoonBit 原生、零第三方运行时依赖的图机器学习基础库，面向图数据预处理、邻域采样、结构特征、消息传递和可复现实验。它适合教学、算法验证、轻量级服务端/边缘端原型和 WebAssembly 方向的生态探索。

仓库地址： GitHub（默认分支 main） · GitLink（默认分支 master）。两个远端的发布提交保持一致。

能力范围

lib/graph：有向/无向加权图、邻接查询、边和矩阵转换、节点特征矩阵。
lib/preprocess：对称归一化、节点/边数据集切分、诱导子图、k-hop 子图、统计指标。
lib/sampling：邻居采样、随机游走、GraphSAGE 多层采样、负采样。
lib/features：PageRank、Personalized PageRank、结构身份特征和特征拼接。
lib/msgpass：通用消息传递、GCN、GraphSAGE、GAT 和半监督标签传播。
lib/analytics：无权 BFS 最短路、非负权 Dijkstra、距离摘要、连通分量、三角形、聚类系数、k-core、割点、桥、度分布和中心性指标。
lib/application：面向交易风控、推荐系统和引文网络的可运行应用工作链，包含数据校验、固定划分、节点分类、基线对照、链路预测、风险排序和个性化推荐。
lib/demo：Zachary Karate Club 与确定性 SBM 数据生成器、端到端节点分类实验。

项目的边界是“图数据与消息传递基础层”，不包含自动求导、GPU 训练、模型参数优化器或完整深度学习框架。这一边界保证库可以保持轻量，同时让上层训练框架复用核心数据结构和算子。

快速开始

环境要求：MoonBit 0.10.7 或更新版本。

moon check --deny-warn
moon test --deny-warn
moon run cmd/main
moon fmt --check
moon info

moon run cmd/main 会运行 Karate Club、60 节点/3 社区 SBM，以及交易风控、用户-物品推荐、引文网络三个应用型场景。应用场景会依次执行数据校验、标签传播、多数类基线、留出节点分类、链路预测和排序输出，并报告 ROC-AUC、Precision@5 与留出准确率。显式 native 目标还需要本机安装 C 编译器；没有 C 编译器时，可先使用默认目标验证项目逻辑。

应用型完整工作链

lib/application 中的三个场景是可重复的业务形状夹具，不把合成数据冒充外部真实数据：

交易风控：节点表示账户/商户端点，边表示交互，标签表示正常或可疑，输出风险排序。
推荐系统：节点 0..7 表示用户、其余节点表示物品，边表示已观察交互，输出过滤已连接物品后的 Personalized PageRank 推荐。
引文网络：有向边表示论文引用，标签表示研究社区，执行社区分类和缺失边评估。

每个场景都使用固定且互不重叠的 train/validation/holdout 节点掩码；链路预测先从训练边重建评分图，再对留出正边和确定性负边评估，避免把 holdout 拓扑直接泄漏给评分器。外部生产数据接入时，应替换场景构造器并保留同一套校验与留出评估接口。

最小 API 示例

let graph = @graph.Graph::from_edge_list([(0, 1), (1, 2), (2, 0)])
let path = @analytics.shortest_path(graph, 0, 2)
let pagerank = @features.pagerank(graph)
let summary = @analytics.distance_summary(graph)

使用本地源码时，包路径来自 moon.mod 中的模块名： qyt1234567/moongraphlearn/lib/graph、.../lib/analytics 等。发布到 Mooncakes 前必须保持模块命名空间、仓库归属和发布账号一致，并在发布后从干净目录再次安装验证。

可复现实验与边界测试

当前仓库包含 47 个测试，覆盖空图、孤立点、断开图、节点不存在、单节点图、重复邻接、负权边忽略、非负权最短路、三角形/尾部结构、割点/桥、k-core、链路预测、分类混淆矩阵、PageRank、消息传递、端到端分类，以及三个应用型场景的数据对齐、掩码互斥、负采样、排序过滤、ROC-AUC/Precision@K/Recall@K 边界和 malformed 输入校验。测试数据全部在源码中确定性生成，不依赖私有数据或网络下载。

基准数据说明：Karate Club 标签依据 Zachary 1977 年社会网络数据；SBM 为固定种子生成的可控合成图。它们用于验证算法流程与边界，不代表真实业务数据上的模型泛化承诺。生产应用应使用脱敏、具备再分发许可的数据，并在 README 或数据目录中记录来源、版本和许可。

工程结构

moon.mod
lib/
  graph/       图结构与节点特征
  preprocess/  归一化、切分、子图与统计
  sampling/    邻域、随机游走和负采样
  features/    PageRank 与结构特征
  msgpass/     GCN、GraphSAGE、GAT、标签传播
  analytics/   路径、连通性、结构指标与中心性
  application/ 风控、推荐、引文网络应用型工作链
  demo/        可复现实验数据和流水线
cmd/main/      端到端命令行演示（含全部应用场景）
.github/       MoonBit check/test/格式/API/三平台 CLI CI

设计与合规说明

本项目的 MoonBit 实现为独立编写，未复制第三方源码；算法依据、论文和 Karate Club 数据来源在 ORIGINALITY_DECLARATION.md 与 CONTRIBUTING.md 中列明。项目使用 Apache License 2.0，许可证全文见根目录 LICENSE。贡献和算法约定见 CONTRIBUTING.md。

提交前请检查：

默认分支包含最新代码，且远端 CI 的 check、test、格式和 API 检查均通过；三平台矩阵还必须运行 CLI 工作链。
moon check --deny-warn、moon test --deny-warn、moon fmt --check 和 moon info 在干净目录通过。
不提交 _build、缓存、凭据、临时文件或无来源的第三方数据。
发布 Mooncakes 前核对 moon.mod 的 name、版本、README、许可证和仓库地址，并先在本地完成打包/发布前检查。

License

Apache License 2.0。