Metadata-Version: 2.4
Name: gmnspy
Version: 1.0.0b1
Summary: Python toolkit for the General Modeling Network Specification (GMNS). Fast I/O at regional scale (parquet/duckdb/zip/URL), foreign-key validation with out-of-sync awareness, geographic + network-aware scoping, data-quality checks, network editing with atomic rollback, and a CLI + notebook + programmatic API.
Project-URL: Homepage, https://e-lo.github.io/GMNSpy
Project-URL: Source, https://github.com/e-lo/GMNSpy
Project-URL: Issues, https://github.com/e-lo/GMNSpy/issues
Project-URL: Changelog, https://github.com/e-lo/GMNSpy/blob/main/CHANGELOG.md
Author: Elizabeth Sall
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: frictionless,gmns,modeling,network,transportation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.11
Requires-Dist: datagrove<2,>=1.0.0b1
Provides-Extra: all
Requires-Dist: anywidget>=0.9; extra == 'all'
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: geopandas>=1.0; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: ipywidgets>=8.1; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: numpy>=1.24; extra == 'all'
Requires-Dist: pandas>=2.0; extra == 'all'
Requires-Dist: pydantic-settings>=2.2; extra == 'all'
Requires-Dist: pyproj>=3.6; extra == 'all'
Requires-Dist: pyyaml>=6; extra == 'all'
Requires-Dist: requests>=2; extra == 'all'
Requires-Dist: scipy>=1.11; extra == 'all'
Requires-Dist: shapely>=2.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'all'
Provides-Extra: clean
Requires-Dist: geopandas>=1.0; extra == 'clean'
Requires-Dist: pyproj>=3.6; extra == 'clean'
Requires-Dist: shapely>=2.0; extra == 'clean'
Provides-Extra: dev-fixtures
Requires-Dist: duckdb>=1.0; extra == 'dev-fixtures'
Requires-Dist: osmnx>=1.9; extra == 'dev-fixtures'
Requires-Dist: pandas>=2.2; extra == 'dev-fixtures'
Requires-Dist: pyarrow>=16; extra == 'dev-fixtures'
Requires-Dist: shapely>=2.0; extra == 'dev-fixtures'
Provides-Extra: graph
Requires-Dist: numpy>=1.24; extra == 'graph'
Requires-Dist: pandas>=2.0; extra == 'graph'
Requires-Dist: scipy>=1.11; extra == 'graph'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: notebook
Requires-Dist: anywidget>=0.9; extra == 'notebook'
Requires-Dist: ipywidgets>=8.1; extra == 'notebook'
Provides-Extra: osm
Requires-Dist: pyyaml>=6; extra == 'osm'
Requires-Dist: requests>=2; extra == 'osm'
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == 'server'
Requires-Dist: httpx>=0.27; extra == 'server'
Requires-Dist: pydantic-settings>=2.2; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'server'
Description-Content-Type: text/markdown

# GMNSpy

Python toolkit for the [General Modeling Network Specification (GMNS)](https://github.com/zephyr-data-specs/GMNS) — Zephyr Foundation's open standard for routable transportation network data.

**Status:** v1.0 in development on `refactor/v1.0`. See `docs/PRD.md` for the product requirements document.

## What it provides

- **Read/write** GMNS networks from CSV, Parquet (partitioned), DuckDB, zipped CSV, or remote URLs (with credentials).
- **Validation** — schema, structural, foreign-key, sync-state (out-of-sync awareness on write), and configurable data-quality rules.
- **Network-aware scoping** — bbox, polygon, BFS / shortest-path subgraph, network-distance buffer, spatial buffer from any link/point/node.
- **Editing** (`gmnspy[clean]`) — simplify geometry, merge close nodes, snap to reference, etc., with atomic rollback + audit log.
- **Self-hostable API server** (`gmnspy[server]`) — FastAPI + auto-OpenAPI for spinning up your own GMNS data service.
- **AI accessibility** (`gmnspy[mcp]`) — MCP server entry point; Skills in the monorepo `skills/` directory.
- **CLI, notebook, and programmatic API** — same operations, three surfaces.

## Install

Pick the tool you already use — these are equivalent:

```bash
# uv (recommended — fastest, handles workspace projects + lockfiles)
uv add gmnspy

# uv pip (drop-in pip replacement, no project file needed)
uv pip install gmnspy

# pip (classic)
pip install gmnspy

# pipx (CLI-only, isolated env; gives you the `gmnspy` command without
#       polluting your project env)
pipx install gmnspy
```

`datagrove` comes along automatically — you don't install both.

### Optional extras

```bash
uv add 'gmnspy[osm]'          # build a GMNS network from OpenStreetMap (requests + pyyaml)
uv add 'gmnspy[clean]'        # network editing + cleanup (shapely + igraph + pyproj)
uv add 'gmnspy[server]'       # self-hostable HTTP server (FastAPI + uvicorn)
uv add 'gmnspy[mcp]'          # MCP server for Claude Desktop / Code
uv add 'gmnspy[notebook]'     # scope-builder Jupyter widget (ipywidgets)
uv add 'gmnspy[all]'          # everything above
```

Combine extras with commas: `uv add 'gmnspy[clean,server,mcp]'`.

> **Note:** the basic `_repr_html_` for `Network` / `ValidationReport` /
> `EditResult` works **without** `[notebook]` — that extra only adds the
> interactive scope-builder widget.

## Quickstart

```python
import gmnspy
from gmnspy.fixtures import leavenworth     # bundled example network

net = gmnspy.read(leavenworth.csv_dir())     # auto-detects format
report = gmnspy.validate(net)                # schema + FK + data-quality
print(report)                                # rich console
# report.to_html("report.html")              # writes interactive single-file HTML

# Network-aware scope: BFS subgraph + half-mile network buffer
# sub = net.scope.from_nodes([1, 2, 3], path_between=True).buffer_network("0.5mi")
# sub.write("subset.parquet")
```

## Repo

Developed in the [GMNSpy monorepo](https://github.com/e-lo/GMNSpy) under `packages/gmnspy/`.
