Vasudev2401/BharatGraph

# BharatGraph **一个具备印度人名感知能力的实体解析与图谱欺诈检测原型。** 印度的金融欺诈通常隐藏在姓名变体记录中：“Sanjay Kumar”、“Sanjai Kumar”和“S. Kumar”可能是同一个人在多家 银行进行骗贷，但没有系统能够察觉这一点，因为标准的语音匹配 （Soundex、Double Metaphone、NYSIIS）是为西方命名模式构建的， 对于印度的辅音替换、音译 差异，或省略中间名/首字母的情况毫无应对机制。 BharatGraph 旨在测试一个小型、有针对性的、基于规则的编码器是否能填补 这一空白——并基于这一答案，使用完全合成的、带有真实标签的 数据，构建了一个端到端的欺诈检测 pipeline（本项目的任何地方都没有使用真实的个人 或财务记录）。 **完整研究报告：** [`research/writeup.md`](research/writeup.md) — 问题、方法论、结果、讨论和局限性汇总于一处。 ## 核心结果 | 算法 | Precision | Recall | F1 | |---|---|---|---| | Soundex | 1.000 | 0.610 | 0.758 | | Double Metaphone | 1.000 | 0.301 | 0.463 | | NYSIIS | 1.000 | 0.478 | 0.647 | | **本项目的编码器** | 0.977 | **0.926** | **0.951** | 这种差距几乎完全是由 `structural_change`（首字母缩写、省略 中间名）引起的——每个 baseline 算法在该项的 Recall 得分都恰好是 **0.000**； 而该编码器的得分为 **1.000**，根据报告与测量，其代价是在困难负样本（同姓的不同人）上产生 6% 的 false-positive rate。 详细分析：[`research/comparative_results.md`](research/comparative_results.md)。 ## 架构 ``` generate_entity_pool.py + generate_name_variants.py + generate_data.py │ (500 synthetic entities, 6 planted fraud scenarios hidden in noise) ▼ cleanse_datasets.py (Phase 4: normalize, flag-don't-drop missing fields) ▼ indian_phonetic_encoder.py (Phase 6: the research contribution) ▼ entity_resolution.py (Phase 8: blocking + composite scoring + Union-Find) ▼ load_graph.py (Phase 9: Neo4j -- Person/Company/BankAccount) ▼ typology_queries.py (Phase 10: loan stacking / shell rings / circular │ transfers -> explainable risk_score) ▼ streamlit_app.py (Phase 11: search, risk dashboard, research tab) ``` 每个阶段都有独立的文档记录，包括在构建过程中发现并修复的 bug ——请参阅 [`docs/progress_pitch.md`](docs/progress_pitch.md) 获取完整的演示，或查看下方的文档表格以了解特定主题。 ## 快速开始（一条命令） 需要 Docker。 ``` docker compose up -d --build ``` 首次构建需要几分钟（将 Python 依赖项安装到 镜像中）；后续启动会很快。 停止命令： ``` docker compose down ``` ## 不使用 Docker 运行 ``` python -m venv venv && source venv/bin/activate pip install -r requirements.txt docker compose up -d neo4j # just the database python setup_demo.py # loads data + computes risk scores streamlit run src/app/streamlit_app.py ``` ## 重新生成数据集 `data/raw/` 和 `data/processed/` 中的 CSV 文件已提交至 repo — `setup_demo.py` 会按原样加载它们，而不会重新生成。要从头重建 合成数据集（通过固定种子完全可复现）： ``` python src/ingestion/generate_entity_pool.py python src/ingestion/generate_data.py python src/ingestion/cleanse_datasets.py python src/resolution/entity_resolution.py python setup_demo.py ``` ## 运行测试 ``` pytest tests/ -v ``` 涵盖标准化、语音编码器和实体解析的 42 项测试。 ## 文档 | 文档 | 涵盖内容 | |---|---| | [`docs/progress_pitch.md`](docs/progress_pitch.md) | 分阶段演示，包含代码、真实数据以及发现的每一个 bug | | [`docs/fraud_typology_pitch.md`](docs/fraud_typology_pitch.md) | 三种欺诈类型的解释、现实基础，以及防御性问答（PAN/DIN/Aadhaar，“这是为谁准备的”） | | [`docs/entity_resolution_architecture.md`](docs/entity_resolution_architecture.md) | 专门深入探讨解析引擎 | | [`docs/ontology.md`](docs/ontology.md) | Neo4j 图谱 schema | | [`docs/risk_scoring.md`](docs/risk_scoring.md) | 类型检测查询、阈值校准和风险评分公式 | | [`docs/data_cleansing_policy.md`](docs/data_cleansing_policy.md) | 缺失值策略和规范化规则 | | [`research/writeup.md`](research/writeup.md) | **从这里开始** — 综合研究报告：问题、方法论、结果、讨论、局限性 | | [`research/`](research/) | 基础研究笔记 — 问题陈述、相关工作、各阶段结果文档 | ## 客观范围 本项目完全使用合成数据——在任何阶段都没有使用真实的个人、财务 或企业记录。结果是对身份匹配问题的受控 模拟，而非经过验证的真实部署。每个阶段的文档都明确说明了该方法的 有效性及局限性，包括编码器未能改善的类别，以及当前 pipeline 无法检测到的 类型（及其原因）。

标签：Kubernetes, 云计算, 反欺诈, 图算法, 实体解析, 数据合成, 规则引擎, 请求拦截, 逆向工具, 音标编码