Metadata-Version: 2.4
Name: matgraph-cli
Version: 0.2.1
Summary: A modern CLI and GraphQL API tool for Material Science DL Pipelines
Author-email: Himan <himan@trinetralabs.ai>
Requires-Python: >=3.9
Requires-Dist: fastapi>=0.103.0
Requires-Dist: mp-api>=0.37.0
Requires-Dist: pymatgen>=2023.10.11
Requires-Dist: rich>=13.0.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: strawberry-graphql>=0.210.0
Requires-Dist: torch>=2.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: uvicorn>=0.23.0
Description-Content-Type: text/markdown

<div align="center">
  <h1>🔬 MatGraph</h1>
  <p><strong>The modern, end-to-end Material Science Deep Learning Pipeline & GraphQL API</strong></p>
  
  [![PyPI - Version](https://img.shields.io/pypi/v/matgraph-cli?color=blue)](https://pypi.org/project/matgraph-cli/)
  [![Python Versions](https://img.shields.io/pypi/pyversions/matgraph-cli)](https://pypi.org/project/matgraph-cli/)
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
</div>

---

**MatGraph** abstracts away the complexity of deep learning for material properties. Designed for both Material Science researchers and ML engineers, it provides a seamless interface to fetch, featurize, predict, and export crystal structures—all powered by modern technologies like **PyTorch**, **GraphQL**, and **uv**.

## ✨ Key Features (v0.2.0 Update)
*   🧠 **PyTorch CGCNN Integrated:** Leverages a custom PyTorch architecture inspired by Crystal Graph Convolutional Neural Networks (CGCNN) for advanced property predictions.
*   ⚡ **Ultra-Fast Engine:** Built on top of Astral's `uv` for lightning-fast environment management.
*   📊 **Advanced Filtering & Export:** Filter structures by Band Gap and Crystal System, and instantly export feature-rich datasets to CSV or JSON.
*   🌐 **Modern Async GraphQL API:** Fully asynchronous resolvers via `Strawberry` & `FastAPI`, providing rich schemas and nested model metrics.
*   💻 **Sleek CLI:** Beautiful, table-formatted terminal outputs powered by `Typer` and `Rich`.

---

## 🚀 Installation

We recommend using [**uv**](https://github.com/astral-sh/uv) for the fastest installation experience.

```bash
# Install via uv (Recommended)
uv tool install matgraph-cli

# Or via standard pip
pip install matgraph-cli
```

### Authentication Setup
To fetch high-fidelity data, you need a free API key from the [Materials Project](https://materialsproject.org/).
```bash
export MP_API_KEY="your_api_key_here"
```
*Tip: You can verify your setup anytime by running `matgraph setup <YOUR_KEY>`.*

---

## 🛠️ Usage: The Productive CLI

MatGraph's CLI is designed to be highly intuitive. 

**Basic Prediction Pipeline**
Run the end-to-end pipeline (Fetch → Featurize → CGCNN Predict) for a specific chemical formula:
```bash
matgraph predict LiFePO4
```

**Advanced Search & Filtering**
Filter materials based on physical constraints:
```bash
matgraph predict LiFePO4 --min-gap 1.5 --crystal-system Cubic
```

**Dataset Export for ML Engineers**
Save extracted structural features and predictions directly into a dataset for offline training:
```bash
matgraph predict LiFePO4 --min-gap 2.0 --save dataset.csv --format csv
```

---

## 🌐 Usage: The Modern GraphQL API

Integrate MatGraph into your own web applications seamlessly using our robust, async GraphQL engine.

**Start the Server:**
```bash
matgraph serve --port 8000
```
Navigate to `http://localhost:8000/graphql` to explore the interactive GraphiQL playground.

**Example Query:**
```graphql
query {
  predictMaterial(formula: "NaCl", minGap: 1.0, limit: 3) {
    materialId
    formula
    crystalSystem
    trueBandGap
    predictedBandGap
    features {
      density
      numElements
      volume
    }
    metrics {
      modelName
      confidenceScore
    }
  }
}
```

---

## 📦 Releases & Changelog

### **v0.2.x (Current - Advanced ML Update)**
*   **Feature:** Integrated PyTorch architecture (`CrystalGraphConvNet`) replacing legacy dummy models.
*   **Feature:** Advanced CLI filtering (`--min-gap`, `--max-gap`, `--crystal-system`).
*   **Feature:** One-command dataset exporting (`--save`, `--format`).
*   **Improvement:** GraphQL schema modernized with detailed `ModelMetrics` and GraphQL pagination filters.

### **v0.1.x (Initial Release)**
*   Initial end-to-end pipeline with MP-API fetching and basic feature extraction.
*   GraphQL Server & basic Typer CLI introduced.
*   Project migrated to `uv` build backend for maximum efficiency.

---

## 🤝 Contributing & Architecture
MatGraph is built on a robust, modern Python stack:
*   **ML & Science:** PyTorch, PyMatGen, Scikit-Learn, MP-API
*   **API & CLI:** FastAPI, Strawberry GraphQL, Typer, Rich
*   **Packaging:** uv (Hatchling)

We welcome contributions! To set up for local development:
```bash
git clone https://github.com/Himan-D/matgraph-cli.git
cd matgraph-cli
uv sync
uv run pytest
```
Please open an issue before submitting major pull requests.
