Merge branch 'main' into mlm-candidate

Author: rbavery

.dockerignore

@@ -22,12 +22,12 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v5.2.0
+      uses: actions/setup-python@v5.3.0
       with:
         python-version: "3.10"
-    - name: Install poetry
-      run: make poetry-install
+    - name: Install uv
+      run: make setup
     - name: Publish stac-model to PyPI
       run: |
-       poetry build
-       poetry publish --username __token__ --password ${{ secrets.PYPI_SECRET }}
+       uv build
+       uv publish --username __token__ --password ${{ secrets.PYPI_SECRET }}

.github/workflows/publish.yaml

@@ -12,18 +12,18 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5.2.0
+      uses: actions/setup-python@v5.3.0
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: Install poetry
-      run: make poetry-install
+    - name: Install uv
+      run: make setup
 
     - name: Set up cache
-      uses: actions/cache@v4.0.2
+      uses: actions/cache@v4.2.0
       with:
         path: .venv
-        key: venv-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}-${{ hashFiles('poetry.lock') }}
+        key: venv-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}-${{ hashFiles('uv.lock') }}
     - name: Install dependencies
       run: make install-dev
 

.github/workflows/stac-model.yml

@@ -11,4 +11,5 @@ jobs:
       - uses: actions/checkout@v4
       - run: |
           npm install
+          npm list
           npm test

.github/workflows/test.yaml

@@ -1,3 +1,5 @@
+requirements*.txt
+
 ### ArchLinuxPackages ###
 *.tar
 *.tar.*

.gitignore

@@ -1,8 +1,7 @@
 default_language_version:
-  python: python3.10
+  python: python3
 
 default_stages: [commit, push]
-
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.5.0

.pre-commit-config.yaml

@@ -5,22 +5,49 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased](https://github.com/stac-extensions/mlm/tree/main)
+## [v1.4.0](https://github.com/stac-extensions/mlm/tree/v1.4.0)
 
 ### Added
-- n/a
+- Add better descriptions about required and recommended *MLM Asset Roles* and
+  their implications (fixes
+  [#54](https://github.com/stac-extensions/mlm/issues/54)).
+- Add explicit check of `value_scaling` sub-fields `minimum`, `maximum`, `mean`, `stddev`, etc. for
+  corresponding `type` values `min-max` and `z-score` that depend on it.
+- Allow different `value_scaling` operations per band/channel/dimension as needed by the model.
+- Allow a `processing:expression` for a band/channel/dimension-specific `value_scaling` operation,
+  granting more flexibility in the definition of input preparation in contrast to having it applied
+  for the entire input (but still possible).
+- Add optional `mlm:compile_method` field at the Asset level with options `aot`
+  for Ahead of Time Compilation, `jit` for Just-In Time Compilation.
 
 ### Changed
-- n/a
+- Explicitly disallow `mlm:name`, `mlm:input`, `mlm:output` and `mlm:hyperparameters` at the Asset level.
+  These fields describe the model as a whole and should therefore be defined in Item properties.
+- Moved `norm_type` to `value_scaling` object to better reflect the expected operation, which could be another
+  operation than what is typically known as "normalization" or "standardization" techniques in machine learning.
+- Moved `statistics` to `value_scaling` object to better reflect their mutual `type` and additional
+  properties dependencies.
+- moved `mlm:artifact_type` field value descriptions that are framework specific to best-practices section.
+- expanded suggested `mlm:artifact_type` values to include Tensorflow/Keras.
 
 ### Deprecated
 - n/a
 
 ### Removed
-- n/a
+- Removed `norm_type` enum values that were ambiguous regarding their expected result.
+  Instead, a `processing:expression` should be employed to explicitly define the calculation they represent.
+- Removed `norm_clip` property. It is now represented under `value_scaling` objects with a
+  corresponding `type` definition.
+- Removed `norm_by_channel` from `mlm:input` objects. If rescaling (previously normalization in the documentation)
+  is a single value, broadcasting to the relevant bands should be performed implicitly.
+  Otherwise, the amount of `value_scaling` objects should match the number of bands or channels involved in the input.
 
 ### Fixed
-- n/a
+- Fix missing `mlm:artifact_type` property check for a Model Asset definition
+  (fixes <https://github.com/stac-extensions/mlm/issues/42>).
+  The `mlm:artifact_type` is now mutually and exclusively required by the corresponding Asset with `mlm:model` role.
+- Fix check of disallowed unknown/undefined `mlm:`-prefixed fields
+  (fixes [#41](https://github.com/stac-extensions/mlm/issues/41)).
 
 ## [v1.3.0](https://github.com/stac-extensions/mlm/tree/v1.3.0)
 
@@ -118,7 +145,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   [Asset Object](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#asset-object)
   to refer to model asset and source code.
 - use `classification:classes` in Model Output
-- add `scene-classification` to the Enum Tasks to allow disambiguation between pixel-wise and patch-based classification
+- add `scene-classification` to the Enum Tasks to allow disambiguation between
+  pixel-wise and patch-based classification
 
 ### Changed
 - `disk_size` replaced by `file:size` (see [Best Practices - File Extension](best-practices.md#file-extension))

CHANGELOG.md

@@ -2,23 +2,26 @@
 
 ## Project setup
 
-1. If you don't have `Poetry` installed run:
+1. If you don't have `uv` installed run:
 
 ```bash
-make poetry-install
+make setup
 ```
 
-> This installs Poetry as a [standalone application][poetry-install]. <br>
-> For more details, see also the [Poetry Documentation][poetry-docs]. <br>
-> If you prefer, you can simply install it inside your virtual environment.
+> This installs `uv` as a [standalone application][uv-install]. <br>
+> For more details, see also the [`uv` documentation][uv-docs]. <br>
 
-2. Initialize project dependencies with poetry and install `pre-commit` hooks:
+2. Initialize project dependencies with `uv` and install `pre-commit` hooks:
 
 ```bash
 make install-dev
 make pre-commit-install
 ```
 
+This will install project dependencies into the currently active environment. If you would like to
+use uv's default behavior of managing a project-scoped environment, use `uv` commands directly to
+install dependencies. `uv sync` will install dependencies and dev dependencies in `.venv` and update the `uv.lock`.
+
 ## PR submission
 
 Before submitting your code please do the following steps:
@@ -85,7 +88,7 @@ git push -u origin your-branch
 ### Building a new version of `stac-model`
 
 - Apply any relevant changes and `CHANGELOG.md` entries in a PR that modifies `stac-model`.
-- Bump the version with `poetry version <version>`.
+- Bump the version with `bumpversion bump <version>`.
   - You can pass the new version explicitly, or a rule such as `major`, `minor`, or `patch`. <br>
     For more details, refer to the [Semantic Versions][semver] standard;
 - Once CI validation succeeded, merge the corresponding PR branch.
@@ -110,6 +113,6 @@ You can also share how the ML Model extension does or does
 not serve your needs with us in the GitHub Discussions or raise
 Issues for bugs.
 
-[poetry-install]: https://github.com/python-poetry/install.python-poetry.org
-[poetry-docs]: https://python-poetry.org/docs/
+[uv-install]: https://docs.astral.sh/uv/getting-started/installation/
+[uv-docs]: https://docs.astral.sh/uv/
 [semver]: https://semver.org/

CONTRIBUTING.md

@@ -1,58 +1,60 @@
 #* Variables
 SHELL ?= /usr/bin/env bash
-PYTHON ?= python
-PYTHONPATH := `pwd`
-POETRY ?= poetry
 
-#* Poetry
-.PHONY: poetry-install
-poetry-install:
-	curl -sSL https://install.python-poetry.org | $(PYTHON) -
-
-.PHONY: poetry-remove
-poetry-remove:
-	curl -sSL https://install.python-poetry.org | $(PYTHON) - --uninstall
-
-.PHONY: poetry-plugins
-poetry-plugins:
-	$(POETRY) self add poetry-plugin-up
-
-.PHONY: poetry-env
-poetry-env:
-	$(POETRY) config virtualenvs.in-project true
+# use the directory rather than the python binary to allow auto-discovery, which is more cross-platform compatible
+PYTHON_PATH := $(shell which python)
+PYTHON_ROOT := $(shell dirname $(dir $(PYTHON_PATH)))
+UV_PYTHON_ROOT ?= $(PYTHON_ROOT)
+
+# to actually reuse an existing virtual/conda environment, the 'UV_PROJECT_ENVIRONMENT' variable must be set to it
+# use this command:
+#	UV_PROJECT_ENVIRONMENT=/path/to/env make [target]
+# consider exporting this variable in '/path/to/env/etc/conda/activate.d/env.sh' to enable it by default when
+# activating a conda environment, and reset it in '/path/to/env/etc/conda/deactivate.d/env.sh'
+UV_PROJECT_ENVIRONMENT ?=
+# make sure every uv command employs the specified environment path
+ifeq (${UV_PROJECT_ENVIRONMENT},)
+  UV_COMMAND := uv
+else
+  UV_COMMAND := UV_PROJECT_ENVIRONMENT="${UV_PROJECT_ENVIRONMENT}" uv
+endif
+
+#* UV
+.PHONY: setup
+setup:
+	which uv >/dev/null || (curl -LsSf https://astral.sh/uv/install.sh | sh)
 
 .PHONY: publish
 publish:
-	$(POETRY) publish --build
+	$(UV_COMMAND) publish --build
 
 #* Installation
 .PHONY: install
-install: poetry-env
-	$(POETRY) lock -n && poetry export --without-hashes > requirements-lock.txt
-	$(POETRY) install -n
-	-poetry run mypy --install-types --non-interactive ./
+install: setup
+	$(UV_COMMAND) export --format requirements-txt -o requirements.txt --no-dev
+	$(UV_COMMAND) pip install --python "$(UV_PYTHON_ROOT)" -r requirements.txt
 
 .PHONY: install-dev
-install-dev: poetry-env install
-	$(POETRY) install -n --with dev
+install-dev: setup
+	$(UV_COMMAND) export --format requirements-txt -o requirements-dev.txt
+	$(UV_COMMAND) pip install --python "$(UV_PYTHON_ROOT)" -r requirements-dev.txt
 
 .PHONY: pre-commit-install
-pre-commit-install:
-	$(POETRY) run pre-commit install
-
+pre-commit-install: setup
+	$(UV_COMMAND) run --python "$(UV_PYTHON_ROOT)" pre-commit install
 
 #* Formatters
 .PHONY: codestyle
-codestyle:
-	$(POETRY) run ruff format --config=pyproject.toml stac_model tests
+codestyle: setup
+	$(UV_COMMAND) run --python "$(UV_PYTHON_ROOT)" ruff format --config=pyproject.toml stac_model tests
 
 .PHONY: format
 format: codestyle
 
 #* Linting
 .PHONY: test
-test:
-	PYTHONPATH=$(PYTHONPATH) poetry run pytest -c pyproject.toml --cov-report=html --cov=stac_model tests/
+test: setup
+	$(UV_COMMAND) run --python "$(UV_PYTHON_ROOT)" pytest -c pyproject.toml --cov-report=html --cov=stac_model tests/
 
 .PHONY: check
 check: check-examples check-markdown check-lint check-mypy check-safety check-citation
@@ -61,37 +63,28 @@ check: check-examples check-markdown check-lint check-mypy check-safety check-ci
 check-all: check
 
 .PHONY: mypy
-mypy:
-	$(POETRY) run mypy --config-file pyproject.toml ./
+mypy: setup
+	$(UV_COMMAND) run --python "$(UV_PYTHON_ROOT)" mypy --config-file pyproject.toml ./
 
 .PHONY: check-mypy
 check-mypy: mypy
 
-# NOTE:
-#  purposely running with docker rather than python package due to conflicting dependencies
-#  see https://github.com/citation-file-format/cffconvert/issues/292
-.PHONY: check-citation
-check-citation:
-	docker run --rm -v $(PYTHONPATH)/CITATION.cff:/app/CITATION.cff citationcff/cffconvert --validate
-
 .PHONY: check-safety
-check-safety:
-	$(POETRY) check
-	$(POETRY) run safety check --full-report
-	$(POETRY) run bandit -ll --recursive stac_model tests
+check-safety: setup
+	$(UV_COMMAND) run --python "$(UV_PYTHON_ROOT)" safety check --full-report
+	$(UV_COMMAND) run --python "$(UV_PYTHON_ROOT)" bandit -ll --recursive stac_model tests
 
 .PHONY: lint
-lint:
-	$(POETRY) run ruff --config=pyproject.toml ./
-	$(POETRY) run pydocstyle --count --config=pyproject.toml ./
-	$(POETRY) run pydoclint --config=pyproject.toml ./
+lint: setup
+	$(UV_COMMAND) run --python "$(UV_PYTHON_ROOT)" ruff check --fix --config=pyproject.toml ./
 
 .PHONY: check-lint
 check-lint: lint
+	$(UV_COMMAND) run --python "$(UV_PYTHON_ROOT)" ruff check --config=pyproject.toml ./
 
 .PHONY: format-lint
-format-lint:
-	$(POETRY) run ruff --config=pyproject.toml --fix ./
+format-lint: lint
+	ruff format --config=pyproject.toml ./
 
 .PHONY: install-npm
 install-npm:
@@ -120,8 +113,9 @@ $(addprefix fix-, $(FORMATTERS)): fix-%: format-%
 lint-all: lint mypy check-safety check-markdown
 
 .PHONY: update-dev-deps
-update-dev-deps:
-	$(POETRY) up --only=dev-dependencies --latest
+update-dev-deps: setup
+	$(UV_COMMAND) export --only-dev --format requirements-txt -o requirements-only-dev.txt
+	$(UV_COMMAND) pip install --python "$(UV_PYTHON_ROOT)" -r requirements-only-dev.txt
 
 #* Cleaning
 .PHONY: pycache-remove