Metadata-Version: 2.4
Name: mlgraphs
Version: 0.2.0
Summary: A Python-native property-graph and graph-ML toolkit for fraud detection, segmentation, and recommendation use cases -- no database server required.
Author: Ismail Hossain Polas
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx>=3.0
Requires-Dist: python-louvain>=0.16
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Provides-Extra: gnn
Requires-Dist: torch>=2.0; extra == "gnn"
Requires-Dist: torch_geometric>=2.5; extra == "gnn"
Provides-Extra: embeddings
Requires-Dist: gensim>=4.3; extra == "embeddings"
Provides-Extra: neo4j
Requires-Dist: neo4j>=5.0; extra == "neo4j"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: scikit-learn>=1.3; extra == "dev"
Provides-Extra: notebooks
Requires-Dist: jupyter>=1.0; extra == "notebooks"
Requires-Dist: matplotlib>=3.8; extra == "notebooks"
Requires-Dist: scikit-learn>=1.3; extra == "notebooks"
Dynamic: license-file

# 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

```bash
pip install mlgraphs
```

From a local checkout (with optional extras):

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

```python
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

```python
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`](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`](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](https://archive.ics.uci.edu/dataset/502/online+retail+ii)
  dataset (UCI Machine Learning Repository).
- [`notebooks/02_recommendation_segmentation_movielens.ipynb`](notebooks/02_recommendation_segmentation_movielens.ipynb) —
  recommendation and segmentation on the real
  [MovieLens `ml-latest-small`](https://grouplens.org/datasets/movielens/) 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

```bash
pytest tests/
```

## License

MIT — see [LICENSE](LICENSE).
