GraphNexus 🌌

Agnostic framework that transforms any tabular dataset (CSV/JSON) into a formal graph structure (Nodes/Edges), ready for network analytics and interactive 3D visualization. Uses Leiden (--community-algo leiden, requires leidenalg) or Louvain (--community-algo louvain, default) for community detection.

✨ Features

• Agnostic Ingestion: Accepts any CSV or JSON file. You define the node, target, and attribute columns.
• Strict Validation: Powered by Pydantic to ensure data integrity between Python and the frontend.
• Community Detection: Automatic Louvain clustering to identify hidden groups and ecosystems.
• Interactive 3D Visualization: Zero-config WebGL dashboard (3d-force-graph) with real-time filtering, role-based coloring, and critical path highlighting.
• Structural Intelligence: Automatic classification of Global Brokers, Local Hubs, Super-Spreaders, and Peripheral nodes via Betweenness/Closeness/Closeness centrality.
• Pathfinding Engine: Shortest-path tracing (--pathfinding) for tracing critical routes between entities.
• Metrics Export: Download node-level metrics (CSV) from the visual dashboard.
• Local-First & Secure: No external API calls. All processing happens on your machine.

🚀 Quick Start

Option 1: Install from PyPI (Recommended)

pip install graphnexus-core

# Run the CLI tool directly
graphnexus --input examples/web_stack.csv --node-id repo_name --target co_contributor --attributes "stars,language"

# Then open `python3 -m http.server 8080 --directory web` and navigate to `localhost:8080`
# User docs: `docs/USER_GUIDE.md` explains roles, centrality metrics, and visual interpretation

Option 2: Install from Source

git clone https://github.com/amurlaniakea/graphnexus-core.git
cd graphnexus-core
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

graphnexus --input examples/web_stack.csv --node-id repo_name --target co_contributor --attributes "stars,language"

🌍 Universal Use Cases

1. Open-Source Web Stack Intelligence — Map software ecosystems, cluster communities with Louvain, and identify strategic infrastructure nodes.
2. Global Supply Chain Strangling — Model logistics flows, detect chokepoints via community isolation, and expose sovereignty vulnerabilities.
3. Financial Anti-Fraud Operations — Build transaction entity graphs, highlight circular flows, and isolate suspicious clusters using real-time filters.

🛠️ Development

pip install -e ".[dev]"
pre-commit run --all-files
pytest tests/ -v

📄 License

AGPL-3.0-or-later — see LICENSE.

Author: Pedro Sordo Martínez — amurlaniakea@gmail.com