mlgraphs 0.2.0

A Python-native property-graph and graph-ML toolkit for fraud detection, segmentation, and recommendation use cases -- no database server required.

mlgraphs

A pip-installable, Neo4j-flavored property-graph and graph-ML toolkit for fraud detection, customer segmentation, recommendation, and general graph-derived features — no graph database server required.

mlgraphs gives you nodes, typed relationships, and properties as first-class citizens (the same property-graph model Neo4j uses), a Cypher-like pattern DSL, and a set of use-case packs built on top of NetworkX rather than a custom storage engine.

Install

pip install mlgraphs

From a local checkout (with optional extras):

pip install -e ".[gnn,embeddings,dev,notebooks]"

from mlgraphs import PropertyGraph

(Extras are optional and independent: gnn pulls in PyTorch + PyTorch Geometric, embeddings pulls in gensim for node2vec, notebooks pulls in Jupyter/matplotlib for the example notebooks. The core install only needs NetworkX, NumPy, pandas, and python-louvain.)

Quick example

from mlgraphs import PropertyGraph, node, rel

g = PropertyGraph()
g.add_node("Person", id="alice", name="Alice")
g.add_node("Person", id="bob", name="Bob")
g.add_relationship("alice", "FRIEND_OF", "bob")

pattern = node("Person", name="Alice").as_("a") >> rel("FRIEND_OF") >> node("Person").as_("f")
for binding in g.match(pattern):
    print(binding["f"])  # "bob"

What's included

Module	What it does
mlgraphs.core	PropertyGraph — nodes, typed relationships, properties, from_dataframes()
mlgraphs.query	Cypher-style pattern matching: node(...) >> rel(...) >> node(...)
mlgraphs.algorithms	PageRank, centrality, Louvain communities, shortest path
mlgraphs.fraud	Shared-attribute ring detection, fan-in/fan-out transaction features
mlgraphs.anomaly	Z-score outliers, fan-out/fan-in hub detection, closed transaction-loop detection
mlgraphs.recommendation	Co-occurrence graphs, collaborative filtering, link-prediction features
mlgraphs.tabular	Flatten any feature pack into a pandas DataFrame for sklearn/XGBoost/LightGBM
mlgraphs.embeddings	node2vec via gensim — graph embeddings, no deep learning framework needed
mlgraphs.splits	Component-aware and temporal train/test splitting (avoids graph leakage)
mlgraphs.gnn	Bridge to PyTorch Geometric for GNN-based scoring

Examples

• examples/fraud_ring_detection.py — synthetic transactions with planted fraud rings, end to end: graph construction → ring detection → GraphSAGE scoring.
• notebooks/01_customer_analytics_online_retail.ipynb — outlier/anomaly detection, recommendation, next best action, segmentation (graph community + ML clustering), and churn prediction on the real Online Retail II dataset (UCI Machine Learning Repository).
• notebooks/02_recommendation_segmentation_movielens.ipynb — recommendation and segmentation on the real MovieLens ml-latest-small dataset (GroupLens Research).

Notebook datasets aren't committed to this repo (see .gitignore); each notebook's first cell documents where to download them from.

Testing

pytest tests/

License

MIT — see LICENSE.