Metadata-Version: 2.4
Name: mattergraph-connectors
Version: 0.1.0
Summary: Connectors to public materials databases for MatterGraph.
Project-URL: Homepage, https://github.com/cyrusmo/MatterGraph
Project-URL: Repository, https://github.com/cyrusmo/MatterGraph
Project-URL: Issues, https://github.com/cyrusmo/MatterGraph/issues
Project-URL: Changelog, https://github.com/cyrusmo/MatterGraph/blob/main/CHANGELOG.md
Author: MatterGraph contributors
License-Expression: Apache-2.0
Keywords: jarvis,lematerial,materials-project,materials-science,nomad
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mattergraph-core~=0.1.0
Requires-Dist: pandas>=2.0
Requires-Dist: pydantic>=2.5
Requires-Dist: pymatgen>=2024.1.1
Provides-Extra: all
Requires-Dist: jarvis-tools>=2024.1.1; extra == 'all'
Requires-Dist: mp-api>=0.40.0; extra == 'all'
Provides-Extra: jarvis
Requires-Dist: jarvis-tools>=2024.1.1; extra == 'jarvis'
Provides-Extra: mp
Requires-Dist: mp-api>=0.40.0; extra == 'mp'
Description-Content-Type: text/markdown

# mattergraph-connectors

Connectors to public materials databases for [MatterGraph](https://github.com/cyrusmo/MatterGraph).

Each connector returns normalized `Material` records from `mattergraph-core`, so downstream filtering, graph export, and scoring work identically regardless of source.

## Sources

| Connector | Status |
|---|---|
| Materials Project (`mp-api`) | Supported — requires `MP_API_KEY` |
| JARVIS-DFT (`jarvis-tools`) | Supported |
| NOMAD | Public metadata reads, no API key needed. Metadata-only in v0.1 — does not fetch archives or derived scalar properties. |
| LeMat-Bulk | Companion adapter (records, parquet, or Hugging Face `datasets`) |
| Local CSV | Supported |
| OQMD | Stub — preserves the API surface, returns no records |

Heavy source SDKs are imported lazily, so importing the package stays cheap and a missing optional dependency produces a readable install hint rather than an `ImportError` traceback.

## Install

```bash
pip install mattergraph-connectors
```

## Example

```python
import json
from pathlib import Path

from mattergraph_connectors import LeMatBulk

artifact = json.loads(Path("data/demo/spc_real_snapshot.json").read_text())
dataset = LeMatBulk.from_records(artifact["records"], subset="compatible_pbe")

candidates = (
    dataset
    .filter_elements(include=["Ti", "Al", "N"])
    .filter_complexity(max_nsites=16, max_nelements=3)
    .create_slice("spc_tialn_candidates_v1", target="energy_above_hull")
)
print(candidates.report())
```

## License

Apache-2.0
