Add Python graph analytics system for KYB/AML shell company detection

[Copilot]

Implements a NetworkX-based graph analytics library to detect shell companies and hidden ownership structures, covering community detection (Louvain), centrality measures (PageRank, Betweenness), and fuzzy entity resolution.

Modules

• graph_builder.py — Directed ownership graph construction; bulk entity/edge loading; cycle detection; ownership chain and subsidiary traversal
• centrality.py — PageRank (UBO/influential entity identification) and Betweenness Centrality (structural bridge detection); in/out-degree centrality; ranked top_nodes() helper
• community_detection.py — Louvain community detection over undirected projection of ownership graph; modularity scoring; flags communities with no traceable individual UBO
• entity_resolution.py — Token-sort-ratio fuzzy matching (LCS-based, no ML deps) with union-find grouping; merges duplicate/alias nodes and redirects their edges to the canonical node
• shell_company_detector.py — Composite 0–1 risk scorer combining all signals with weighted factors:

Risk Factor	Weight
Circular ownership cycle	0.40
High betweenness centrality	0.20
Suspicious community (no UBO)	0.20
Elevated PageRank	0.15
Deep ownership chain (≥ 3 layers)	0.15
Possible duplicate/alias entity	0.15

Example

from kyb_graph_analytics import GraphBuilder, ShellCompanyDetector

gb = GraphBuilder()
gb.add_entities([
    {"id": "alice", "entity_type": "individual", "name": "Alice Smith"},
    {"id": "shell_a", "entity_type": "company", "name": "Shell Alpha Ltd"},
    {"id": "shell_b", "entity_type": "company", "name": "Shell Beta Ltd"},
])
gb.add_relationships([
    {"source": "shell_a", "target": "shell_b"},
    {"source": "shell_b", "target": "shell_a"},  # circular ownership
])

detector = ShellCompanyDetector(gb)
print(detector.summary_report())
# {"high_risk": 2, "cycle_count": 1, "top_risks": [...], ...}

for entity in detector.high_risk_entities():
    print(entity["entity_id"], entity["risk_score"], entity["flags"])
# shell_a  0.6  ['Participates in circular ownership cycle', ...]

Dependencies

networkx>=3.0, python-louvain>=0.16, numpy>=1.24, scipy>=1.10 (required by networkx 3.x for PageRank sparse computation).

Original prompt

Build a Python-based graph analytics system to detect shell companies and hidden ownership structures using NetworkX. Include community detection (Louvain), centrality measures (PageRank, Betweenness), and entity resolution for KYB/AML use cases.