Metadata-Version: 2.4
Name: NEExT
Version: 0.3.6
Summary: Network Embedding Experimentation Toolkit - A powerful framework for graph analysis, embedding computation, and machine learning on graph-structured data
Project-URL: Homepage, https://github.com/ashdehghan/NEExT
Project-URL: Documentation, https://www.neext.app/docs
Project-URL: Repository, https://github.com/ashdehghan/NEExT
Project-URL: Issues, https://github.com/ashdehghan/NEExT/issues
Project-URL: Paper, https://arxiv.org/abs/2503.15853
Author-email: Ash Dehghan <ash.dehghan@gmail.com>
Maintainer-email: Ash Dehghan <ash.dehghan@gmail.com>
License: MIT
License-File: LICENSE
Keywords: embedding,graph,graph-ml,machine-learning,network,network-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: <3.13,>=3.9
Requires-Dist: cairocffi>=1.3.0
Requires-Dist: imbalanced-learn<0.13,>=0.11.0
Requires-Dist: joblib>=1.3.0
Requires-Dist: llvmlite>=0.41.0
Requires-Dist: networkx<4,>=3.0
Requires-Dist: numba>=0.58.0
Requires-Dist: numpy<2.0,>=1.24.0
Requires-Dist: pandas<3,>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-igraph>=0.10.0
Requires-Dist: requests>=2.25.0
Requires-Dist: scikit-learn<1.5,>=1.3.0
Requires-Dist: scipy>=1.13.0
Requires-Dist: tqdm>=4.64.0
Requires-Dist: vectorizers<0.3,>=0.2
Requires-Dist: xgboost>=1.7.0
Provides-Extra: advanced
Requires-Dist: matplotlib>=3.5.0; extra == 'advanced'
Requires-Dist: optuna>=3.0.0; extra == 'advanced'
Requires-Dist: plotly>=5.0.0; extra == 'advanced'
Requires-Dist: seaborn>=0.12.0; extra == 'advanced'
Requires-Dist: umap-learn!=0.5.9.post2,>=0.5.7; extra == 'advanced'
Provides-Extra: all
Requires-Dist: black>=23.0.0; extra == 'all'
Requires-Dist: fastapi<1.0,>=0.111.0; extra == 'all'
Requires-Dist: httpx>=0.27.0; extra == 'all'
Requires-Dist: ipykernel>=6.0.0; extra == 'all'
Requires-Dist: isort>=5.12.0; extra == 'all'
Requires-Dist: jupyter>=1.0.0; extra == 'all'
Requires-Dist: matplotlib>=3.5.0; extra == 'all'
Requires-Dist: mypy>=1.0.0; extra == 'all'
Requires-Dist: notebook>=7.0.0; extra == 'all'
Requires-Dist: optuna>=3.0.0; extra == 'all'
Requires-Dist: plotly>=5.0.0; extra == 'all'
Requires-Dist: pre-commit>=3.0.0; extra == 'all'
Requires-Dist: pyarrow>=14.0.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0.0; extra == 'all'
Requires-Dist: pytest-mock>=3.10.0; extra == 'all'
Requires-Dist: pytest>=7.0.0; extra == 'all'
Requires-Dist: ruff>=0.1.0; extra == 'all'
Requires-Dist: seaborn>=0.12.0; extra == 'all'
Requires-Dist: torch<3.0,>=2.0.0; extra == 'all'
Requires-Dist: umap-learn!=0.5.9.post2,>=0.5.7; extra == 'all'
Requires-Dist: uvicorn[standard]<1.0,>=0.30.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: experiments
Requires-Dist: ipykernel>=6.0.0; extra == 'experiments'
Requires-Dist: jupyter>=1.0.0; extra == 'experiments'
Requires-Dist: notebook>=7.0.0; extra == 'experiments'
Provides-Extra: gnn
Requires-Dist: torch<3.0,>=2.0.0; extra == 'gnn'
Provides-Extra: workbench
Requires-Dist: fastapi<1.0,>=0.111.0; extra == 'workbench'
Requires-Dist: httpx>=0.27.0; extra == 'workbench'
Requires-Dist: pyarrow>=14.0.0; extra == 'workbench'
Requires-Dist: torch<3.0,>=2.0.0; extra == 'workbench'
Requires-Dist: umap-learn!=0.5.9.post2,>=0.5.7; extra == 'workbench'
Requires-Dist: uvicorn[standard]<1.0,>=0.30.0; extra == 'workbench'
Provides-Extra: workbench-mcp
Requires-Dist: fastapi<1.0,>=0.111.0; extra == 'workbench-mcp'
Requires-Dist: httpx>=0.27.0; extra == 'workbench-mcp'
Requires-Dist: mcp<2,>=1.27; (python_version >= '3.10') and extra == 'workbench-mcp'
Requires-Dist: pyarrow>=14.0.0; extra == 'workbench-mcp'
Requires-Dist: torch<3.0,>=2.0.0; extra == 'workbench-mcp'
Requires-Dist: umap-learn!=0.5.9.post2,>=0.5.7; extra == 'workbench-mcp'
Requires-Dist: uvicorn[standard]<1.0,>=0.30.0; extra == 'workbench-mcp'
Description-Content-Type: text/markdown

<div align="center">

# NEExT

**Network Embedding Experimentation Toolkit**

An open-source Python framework for network science and graph machine learning.

[![PyPI version](https://img.shields.io/pypi/v/NEExT?color=1062a2)](https://pypi.org/project/NEExT/)
[![Python versions](https://img.shields.io/pypi/pyversions/NEExT?color=1062a2)](https://pypi.org/project/NEExT/)
[![License: MIT](https://img.shields.io/pypi/l/NEExT?color=1062a2)](https://github.com/ashdehghan/NEExT/blob/main/LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/NEExT?color=1062a2)](https://pypi.org/project/NEExT/)
[![Docs](https://img.shields.io/badge/docs-neext.app-c0541d)](https://www.neext.app/docs)

[**Documentation**](https://www.neext.app/docs) · [**Website**](https://www.neext.app) · [**Issues**](https://github.com/ashdehghan/NEExT/issues)

![NEExT Workbench](https://www.neext.app/readme/workbench.png)

</div>

## What is NEExT?

NEExT is an experimentation framework for graph and network data. It takes you from a
collection of graphs to predictive and scientific results through one pipeline you can
inspect and reproduce at every step:

> **Graphs → Features → Embeddings → Evidence**

Load graphs from CSV, pandas, or NetworkX into a unified `GraphCollection`; compute
structural node features (or write your own in plain Python); turn them into graph-level
embeddings with Wasserstein/Sinkhorn optimal transport or a GNN; then train classifiers
or regressors and read feature importance to see which structure drives the result. It's
built on the standard scientific Python stack — NumPy, pandas, scikit-learn, XGBoost,
NetworkX, iGraph — and works the same in a script, a notebook, or the Workbench.

There are two ways to use NEExT:

- **The Library** — a lightweight Python package for scripting and notebook workflows.
- **The Workbench** — a local, desktop-style GUI over the same NEExT workflows, with
  versioned artifacts and job tracking. It runs entirely on your machine (`127.0.0.1`,
  no accounts, no uploads) and is **MCP-native**, so an agent like Claude can drive it.

## Installation

```bash
pip install NEExT
```

Optional extras:

```bash
pip install "NEExT[gnn]"            # Graph Neural Network embeddings (pure PyTorch)
pip install "NEExT[workbench-mcp]"  # local Workbench + MCP integration
```

See the [docs](https://www.neext.app/docs) for the full list of extras.

## Quick start

```python
from NEExT import NEExT

nxt = NEExT()

# Load a collection of graphs from CSV
graph_collection = nxt.read_from_csv(
    edges_path="edges.csv",
    node_graph_mapping_path="node_graph_mapping.csv",
    graph_label_path="graph_labels.csv",
)

# Features → Embeddings → Evidence
features = nxt.compute_node_features(graph_collection, feature_list=["all"])
embeddings = nxt.compute_graph_embeddings(
    graph_collection, features, embedding_algorithm="approx_wasserstein"
)
results = nxt.train_ml_model(graph_collection, embeddings, model_type="classifier")
```

Custom features, GNN embeddings, large-graph sampling, feature importance, and the full
API are covered in the [documentation](https://www.neext.app/docs).

## The Workbench

The NEExT Workbench is a local, single-user FastAPI + React application that exposes
the NEExT workflows — datasets, features, embeddings, models, and analysis — as a
desktop-style UI. Everything stays on your machine, and it speaks MCP, so you can drive
the whole pipeline from an MCP client.

```bash
neext-workbench          # installed package
make neext-workbench     # from a development checkout
```

Then open **http://127.0.0.1:8765**. Projects are stored under `~/NEExT-Workbench` by
default (override with `NEEXT_WORKBENCH_HOME` or `neext-workbench --workspace <path>`).
The full Workbench tour, including MCP client setup, lives in the
[documentation](https://www.neext.app/docs).

## Learn more

- 📚 **Documentation** — guides, API reference, and the Workbench tour: [neext.app/docs](https://www.neext.app/docs)
- 🌐 **Website** — [neext.app](https://www.neext.app)
- 🐛 **Issues & support** — [github.com/ashdehghan/NEExT/issues](https://github.com/ashdehghan/NEExT/issues)

## Supporting NEExT

NEExT is free and open source, and stays that way. If it's useful to your work, the best
support is free: star the repo, [cite the paper](#citing-neext), and tell colleagues. You
can also [contribute](CONTRIBUTING.md) or help fund maintenance — see
[neext.app/support](https://www.neext.app/support). Universities and organizations can
also invite a talk or workshop there.

## Citing NEExT

If you use NEExT in your research, please cite it. The primary, open-access reference is
the arXiv paper:

```bibtex
@article{dehghan2025neext,
  title   = {Network Embedding Exploration Tool (NEExT)},
  author  = {Dehghan, Ashkan and Pra{\l}at, Pawe{\l} and Th{\'e}berge, Fran{\c{c}}ois},
  journal = {arXiv preprint arXiv:2503.15853},
  year    = {2025},
  url     = {https://arxiv.org/abs/2503.15853}
}
```

A peer-reviewed version appeared at the 19th Workshop on Algorithms and Models for the
Web Graph (WAW 2024):

```bibtex
@inproceedings{dehghan2024neext,
  title     = {Network Embedding Exploration Tool (NEExT)},
  author    = {Dehghan, Ashkan and Pra{\l}at, Pawe{\l} and Th{\'e}berge, Fran{\c{c}}ois},
  booktitle = {Modelling and Mining Networks (WAW 2024)},
  series    = {Lecture Notes in Computer Science},
  pages     = {65--79},
  year      = {2024},
  publisher = {Springer},
  doi       = {10.1007/978-3-031-59205-8_5}
}
```

- 📄 arXiv (open access): [arxiv.org/abs/2503.15853](https://arxiv.org/abs/2503.15853)
- 📄 Springer (peer-reviewed): [doi.org/10.1007/978-3-031-59205-8_5](https://doi.org/10.1007/978-3-031-59205-8_5)

## Acknowledgements

NEExT is created, maintained, and owned by
[Ash Dehghan](mailto:ash.dehghan@gmail.com). The NEExT paper is co-authored with
Paweł Prałat and François Théberge. Thanks to the contributors who have helped build
NEExT, including Kamil Kulesza and Lourens Touwen.

The community-aware βstar feature is based on Kamiński, Prałat, Théberge, and Zając,
*"Predicting Properties of Nodes via Community-Aware Features"*
([arXiv:2311.04730](https://arxiv.org/abs/2311.04730),
[doi:10.1007/s13278-024-01281-2](https://doi.org/10.1007/s13278-024-01281-2)).

## License

NEExT is released under the [MIT License](LICENSE). Created and maintained by
[Ash Dehghan](mailto:ash.dehghan@gmail.com).
