Metadata-Version: 2.4
Name: mater-interface
Version: 0.1.0
Summary: Stable exchange contract for the MATER ecosystem
Author: Lauranne Sarribouette
Author-email: Lauranne Sarribouette <lauranne.sarribouette@univ-grenoble-alpes.fr>
License-Expression: LGPL-3.0-or-later
License-File: LICENSE
Requires-Dist: pydantic>=2.0,<3
Requires-Dist: pyarrow>=25.0,<26 ; extra == 'parquet'
Requires-Python: >=3.10
Provides-Extra: parquet
Description-Content-Type: text/markdown

# mater-ecosystem

[![PyPI version](https://img.shields.io/pypi/v/mater-interface.svg)](https://pypi.org/project/mater-interface/)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
![Coverage](https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-dynamic-modeling/mater-project/mater-ecosystem/badges/main/coverage.svg)
[![MATER](https://img.shields.io/badge/framework-MATER-orange.svg)](https://isterre-dynamic-modeling.gricad-pages.univ-grenoble-alpes.fr/mater-project/mater)
[![UV](https://img.shields.io/badge/managed_by-UV-blue.svg)](https://docs.astral.sh/uv/)
[![License](https://img.shields.io/badge/license-LGPLv3%2B-blue.svg)](https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-dynamic-modeling/mater-project/mater-ecosystem/-/blob/main/LICENSE)

**Shared standards, governance, and versioned data exchange contracts for the MATER ecosystem.**

`mater-ecosystem` hosts the cross-cutting documentation, architectural decisions,
governance rules, and machine-readable standards shared across MATER projects.

It also publishes `mater-interface`, the Python package defining the shared data
exchange contract between MATER producers and consumers.

## Quick Start

Add `mater-interface` to a uv-managed project:

```bash
uv add mater-interface
```

To use the optional Parquet serializer:

```bash
uv add "mater-interface[parquet]"
```

Import the public data models and validation functions:

```python
from mater_interface import (
    DatasetMetadata,
    Derivation,
    Observation,
    validate_dataset,
    validate_dataset_for_publication,
)
```

`mater-interface` provides:

- Validated models for Dataset metadata and Observations
- Dataset-level structural validation
- Client-side validation before Dataset publication
- JSON and optional Parquet serialization
- JSON Schemas and executable conformance cases

## Documentation

- **[Detailed Documentation](https://isterre-dynamic-modeling.gricad-pages.univ-grenoble-alpes.fr/mater-project/mater-ecosystem/)** — Ecosystem architecture, standards, governance, and `mater-interface` reference
- **[License](https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-dynamic-modeling/mater-project/mater-ecosystem/-/blob/main/LICENSE)** — LGPLv3-or-later

## Development

Clone the repository:

```bash
git clone https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-dynamic-modeling/mater-project/mater-ecosystem.git
cd mater-ecosystem
```

Install dependencies, including Parquet support:

```bash
uv sync --extra parquet
```

Install `just` (cross-platform via uv):

```bash
uv tool install just-bin
```

Or download the binary directly from the [official releases page](https://github.com/casey/just/releases).

> If you see a PATH warning, run `uv tool update-shell` and restart your terminal.

Run common development tasks:

```bash
just lint
just fix
just test
just schemas
```
