Metadata-Version: 2.4
Name: ml-validate
Version: 0.1.0
Summary: Offline-first ML dataset metadata validator for NFDI schemas (Croissant, ML-Schema, XDM, Chemotion, and more)
Author: NFDI Data Registry
License: MIT
Project-URL: Repository, https://github.com/your-org/nfdi-data-registry
Project-URL: Documentation, https://github.com/your-org/nfdi-data-registry/tree/main/ml_validate
Keywords: nfdi,validation,croissant,ml,schema,metadata,fair
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: jsonschema>=4.17
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.0
Provides-Extra: fetch
Requires-Dist: httpx>=0.25; extra == "fetch"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: httpx>=0.25; extra == "dev"

# ml-validate

Offline-first Python validator for NFDI and ML metadata schemas.

## Features

- Bundled schema registry (no network required for schemas)
- Python API via `Validator` and `Profiler`
- CLI for CI/CD pipelines
- Supports Croissant, ML-Schema, JSON Schema-based formats, and repository schemas

## Install

```bash
pip install ml-validate
```

For URL validation support:

```bash
pip install "ml-validate[fetch]"
```

## Quickstart

```python
from ml_validate import Validator

validator = Validator()
result = validator.validate("dataset.json", "croissant-1.0")
print(result.passed, result.score)
```

```bash
ml-validate validate dataset.json --schema croissant-1.0
```

## Example Data (Chemotion JSON-LD)

This repository now includes reusable example files in `examples/` derived from:

- `../example_datasets/JSON-LD_Analysis_874350-20260219122553.json`

Included examples:

- `examples/chemotion_jsonld_sample.json`: curated, realistic JSON-LD sample
- `examples/chemotion_jsonld_incomplete.json`: intentionally incomplete sample for failure demos

The sample keeps the metadata structure and key fields used by the validators while avoiding large personal-author blocks.

## CLI Examples

Validate a realistic Chemotion-style JSON-LD example with Croissant heuristics:

```bash
ml-validate validate examples/chemotion_jsonld_sample.json --schema croissant-1.0
```

Run a profile across two schemas and get machine-readable output:

```bash
ml-validate profile examples/chemotion_jsonld_sample.json --schemas croissant-1.0,w3c-ml-2.0 --output json
```

Show a failing validation case:

```bash
ml-validate validate examples/chemotion_jsonld_incomplete.json --schema croissant-1.0
```

## Python API Examples

```python
from pathlib import Path
from ml_validate import Profiler, Validator

payload = Path("examples/chemotion_jsonld_sample.json").read_text(encoding="utf-8")

validator = Validator()
single = validator.validate(payload, "croissant-1.0", source_type="json")
print(single.passed, single.score)

profiler = Profiler()
results = profiler.profile(payload, schema_ids=["croissant-1.0", "w3c-ml-2.0"], source_type="json")
for schema_id, result in results.items():
    print(schema_id, result.status, result.score)
```

## CI/CD Example (GitHub Actions)

You can validate metadata files automatically in pull requests and fail the build when rules are not met.

### PR validation workflow

Create `.github/workflows/metadata-validation.yml`:

```yaml
name: Metadata Validation

on:
  pull_request:
    paths:
      - "datasets/**/*.json"
      - ".github/workflows/metadata-validation.yml"

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install validator
        run: pip install ml-validate

      - name: Validate a dataset (strict)
        run: |
          ml-validate validate datasets/metadata.json \
            --schema croissant-1.0 \
            --fail-under 90
```

### Multi-schema profile gate

Use profiling if your pipeline must satisfy more than one schema:

```yaml
- name: Profile against multiple schemas
  run: |
    ml-validate profile datasets/metadata.json \
      --schemas croissant-1.0,w3c-ml-2.0 \
      --fail-under 80
```

### Publish workflow note

If you publish this package from GitHub Actions, see:

- `.github/workflows/publish.yml`

That workflow builds on tag push (for example `v0.1.0`) and uploads distributions to PyPI.
