# materialhub

**Repository Path**: material-virtual-design/materialhub

## Basic Information

- **Project Name**: materialhub
- **Description**: Material Model Management System - A comprehensive platform for managing datasets, ML models, and workflows for materials science research.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-11-27
- **Last Updated**: 2025-11-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MaterialHub

Material Model Management System - A comprehensive platform for managing datasets, ML models, and workflows for materials science research.

## Features

- **Data Management**: Upload, store, and query material datasets (CSV, JSON, CIF, etc.)
- **Model Management**: Store and manage trained ML models (TensorFlow, PyTorch, scikit-learn, etc.)
- **Workflow Management**: Define and execute training, validation, and prediction workflows using Prefect
- **RESTful API**: Complete API with PostOnlyResource and ReadOnlyResource patterns
- **Docker Support**: Containerized execution for models and workflows

## Prerequisites

- Python 3.10+ (tested with Python 3.12)
- `pip` or `uv` for dependency management
- Optional: MongoDB if you want to run against a live database. By default, MaterialHub uses
  [MontyDB](https://github.com/davidlatwe/montydb) via Maggma's `MontyStore`, which persists data
  to the local filesystem under the configured `storage_path`.
- Optional: Docker (required for container-based workflow execution)

## Installation

### Quick Start

```bash
# Clone the repository
git clone <repository-url>
cd materialhub

# Run installation script
bash scripts/install.sh

# Or use pip directly
pip install -r requirements.txt
pip install -e .
```

### Development Setup

```bash
# Run development setup script
bash scripts/setup_dev.sh

# Or manually
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e ".[dev,workflow,docker,security]"
```

### Using pip

```bash
# Core installation
pip install -e .

# With optional dependencies
pip install -e ".[workflow,docker,security,ml,dev]"
```

## Configuration

1. Copy environment variables template:
```bash
cp .env.example .env  # If .env.example exists
```

2. Edit `.env` with your settings (only required when using external services):
```env
DATABASE_HOST=localhost
DATABASE_PORT=27017
DATABASE_NAME=materialhub
# ... other settings
# Optional when relying on the default MontyStore:
# STORAGE_PATH=./storage
```

## Usage

### Start the API Server

```bash
# Development mode
uvicorn materialhub.main:app --reload

# Production mode
gunicorn materialhub.main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker
```

### Initialize Database

```bash
python scripts/init_database.py
```

### Run Tests

```bash
pytest tests/

# Comprehensive example verification (exercises upload/list/search APIs)
python examples/test_all_examples.py
```

### Explore Examples

The `examples/` directory contains end-to-end API walkthroughs:

- `examples/datasets_examples.md` – dataset upload/list/search/update flows
- `examples/models_examples.md` – model upload/list/predict flows
- `examples/workflows_examples.md` – workflow creation/execution flows
- `examples/test_all_examples.py` – script that runs the most common API scenarios programmatically
- `examples/sample_data/` – ready-to-use CSV and JSON data for quick experiments

## API Documentation

Once the server is running, access:
- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

## Project Structure

```
materialhub/
├── src/materialhub/     # Source code
│   ├── api/             # API resources and endpoints
│   ├── core/             # Base classes and utilities
│   ├── data/             # Data parsers and validators
│   ├── models/           # Model wrappers
│   ├── stores/           # Database stores
│   ├── workflows/        # Workflow management
│   └── utils/            # Utility functions
├── tests/                # Test suite
├── docs/                 # Documentation
├── scripts/               # Utility scripts
└── requirements.txt      # Python dependencies
```

## Dependencies

### Core
- FastAPI - Web framework
- maggma - Database abstraction
- pymongo - MongoDB driver
- pydantic - Data validation

### Optional
- Prefect - Workflow orchestration
- Docker - Container support
- pandas/numpy - Data processing

See `requirements.txt` for complete list.

## Documentation

Comprehensive documentation is available in the `docs/` directory:
- [Architecture](docs/architecture.md)
- [API Reference](docs/api_reference.md)
- [User Guide](docs/user_guide.md)
- [Deployment Guide](docs/deployment.md)

## Development

### Code Style

```bash
# Format code
black src/ tests/

# Type checking
mypy src/

# Linting
flake8 src/ tests/
```

### Running Tests

```bash
# All tests
pytest

# With coverage
pytest --cov=src/materialhub

# Specific test file
pytest tests/test_datasets.py

# Run API scenario smoke tests
python examples/test_all_examples.py
```

## License

MIT License

## Contributing

Contributions are welcome! Please see the contributing guidelines for more information.

## Support

For issues and questions, please open an issue on GitHub.