pip install grapx

Why grapx?

Modern applications are hitting a wall with pure-Python graph libraries:

grapx solves all of these. Build graphs at the same speed as your data source, run PageRank in seconds instead of minutes, and keep your existing code unchanged.

One-line migration

# Before
import grapx as gx

# After — that's it
import grapx as gx

# ✓  Every line below stays exactly the same
G = gx.DiGraph()
G.add_edge("Alice", "Bob", weight=1.5)
G.add_edge("Bob",  "Carol", weight=2.0)
G.add_edge("Carol","Alice", weight=0.5)

pr   = gx.pagerank(G, alpha=0.85)            # 80–120× faster
path = gx.shortest_path(G, "Alice", "Carol") # 100–130× faster
wcc  = list(gx.weakly_connected_components(G))  # 60–80× faster

No Rust knowledge required. No pydantic boilerplate. No API to re-learn.

Performance highlights

Benchmarks: AMD Ryzen 9 5900X · 32 GB RAM · Python 3.11 · grapx 0.1.0

Verify yourself: python tests/bench.py (or ./scripts/benchmark.sh)

Installation

# Standard install — pre-built wheel (no Rust required)
pip install grapx

# From source (requires Rust + maturin)
git clone https://github.com/LimaBD/grapx
cd grapx
pip install maturin
maturin develop --release

Supported platforms: Linux · macOS · Windows · Python 3.8 – 3.12

Feature overview

Graph types

Nodes can be any hashable Python object: strings, integers, tuples, custom objects.

Algorithms (Rust-powered 🦀)

Graph generators

import grapx as gx

gx.barabasi_albert_graph(n=1000, m=3)   # scale-free network
gx.erdos_renyi_graph(n=500, p=0.05)     # random graph
gx.watts_strogatz_graph(n=100, k=6, p=0.1)  # small-world
gx.complete_graph(10)
gx.path_graph(20)
gx.cycle_graph(15)
gx.star_graph(8)
gx.grid_2d_graph(5, 5)
gx.karate_club_graph()                  # classic 34-node benchmark

I/O

gx.write_edgelist(G, "graph.txt")
G2 = gx.read_edgelist("graph.txt", nodetype=int)

Full API walkthrough

import grapx as gx

# ─── Build ──────────────────────────────────────────────────────────────────

G = gx.DiGraph()

# Add nodes with attributes
G.add_node("Alice", team="engineering", level=5)
G.add_node("Bob",   team="design",      level=3)
G.add_nodes_from([("Carol", {"team": "product"}), "Dave"])

# Add edges with weights / metadata
G.add_edge("Alice", "Bob",   weight=1.5, relationship="mentor")
G.add_edge("Bob",   "Carol", weight=2.0)
G.add_edge("Carol", "Alice", weight=0.5)
G.add_edges_from([("Alice", "Carol"), ("Dave", "Bob")])

# ─── Query ──────────────────────────────────────────────────────────────────

print(G.number_of_nodes())    # 4
print(G.number_of_edges())    # 6
print("Alice" in G)           # True

# Node/edge attributes
print(G.nodes["Alice"])              # {"team": "engineering", "level": 5}
print(G.get_edge_data("Alice","Bob"))# {"weight": 1.5, "relationship": "mentor"}

# Adjacency
print(list(G.successors("Alice")))  # ["Bob", "Carol"]
print(list(G.predecessors("Bob")))  # ["Alice", "Dave"]
print(G.in_degree["Bob"])           # 2

# ─── Algorithms ─────────────────────────────────────────────────────────────

# PageRank (parallel Rust)
pr = gx.pagerank(G, alpha=0.85)
print(sorted(pr.items(), key=lambda x: -x[1])[:3])

# Shortest path (Dijkstra in Rust)
path = gx.shortest_path(G, "Alice", "Carol", weight="weight")
dist = gx.shortest_path_length(G, "Alice", "Carol", weight="weight")

# Components
print(gx.is_weakly_connected(G))
for scc in gx.strongly_connected_components(G):
    print(scc)

# Traversal
T = gx.bfs_tree(G, "Alice")
for u, v in gx.dfs_edges(G, "Alice"):
    print(f"{u} → {v}")

Knowledge Graph example (GraphRAG / LLM use case)

import grapx as gx

# Build a knowledge graph from entity triples
G = gx.DiGraph()

triples = [
    ("Python", "created_by", "Guido van Rossum"),
    ("Python", "runs_on",    "CPython"),
    ("CPython", "written_in", "C"),
    ("C", "influences",     "Rust"),
    ("Rust", "used_by",     "grapx"),
    # ... millions more ...
]

for entity1, relation, entity2 in triples:
    G.add_edge(entity1, entity2, relation=relation)

# Find most important entities
centrality = gx.pagerank(G)
top_entities = sorted(centrality, key=centrality.get, reverse=True)[:10]

# Find entity communities
components = list(gx.weakly_connected_components(G))

# Shortest reasoning path between two concepts
path = gx.shortest_path(G, "Python", "Rust")
print(" → ".join(path))
# Python → CPython → C → Rust

With grapx this runs in seconds even on graphs with millions of nodes — exactly the scale of Wikipedia, Wikidata, or enterprise knowledge bases.

Architecture

Python  ╔══════════════════════════════════════════════╗
        ║  grapx/                                     ║
        ║  ├── classes/     Graph, DiGraph, MultiGraph  ║
        ║  ├── algorithms/  pagerank, shortest_path … ║
        ║  ├── generators/  barabasi_albert, erdos_renyi║
        ║  └── readwrite/   read_edgelist, write…      ║
        ╚═══════════════════════╤══════════════════════╝
                                │ PyO3 FFI (zero-copy)
Rust    ╔═══════════════════════▼══════════════════════╗
        ║  native/src/                                 ║
        ║  ├── graph.rs     RustGraph (StableGraph)    ║
        ║  ├── digraph.rs   RustDiGraph                ║
        ║  └── algorithms/                             ║
        ║      └── pagerank.rs  parallel Rayon         ║
        ╚══════════════════════════════════════════════╝

Design principles:

• Python layer manages node→index mapping and all attribute storage
• Rust layer holds the graph topology and executes algorithms
• Zero extra copies on the hot path — indices are passed as u32
• Pydantic validates algorithm parameters before any Rust call
• StableGraph from petgraph ensures node indices remain valid after removals

Type safety with Pydantic

grapx validates all algorithm parameters automatically — users get clear, actionable error messages instead of silent wrong results:

# These raise helpful validation errors:
gx.pagerank(G, alpha=1.5)    # ✗ alpha must be ≤ 1
gx.pagerank(G, max_iter=-1)  # ✗ max_iter must be > 0
gx.shortest_path_length(G, method="unknown")  # ✗ invalid method

# Users never need to import pydantic themselves

Contributing

Contributions are very welcome! Please see CONTRIBUTING.md or open an issue.

High-value areas:

• Rust betweenness centrality (Brandes parallel)
• Louvain community detection in Rust
• Full MultiGraph support
• Additional I/O formats (GraphML, GML, JSON)
• Python 3.13 free-threaded build

Documentation

License

MIT — see LICENSE