bioimageio.spec.generic.v0_3

  1from __future__ import annotations
  2
  3import string
  4from functools import partial
  5from typing import (
  6    TYPE_CHECKING,
  7    Any,
  8    ClassVar,
  9    Dict,
 10    List,
 11    Literal,
 12    Optional,
 13    Sequence,
 14    Type,
 15    TypeVar,
 16    Union,
 17)
 18
 19import annotated_types
 20from annotated_types import Len, LowerCase, MaxLen, MinLen
 21from pydantic import Field, RootModel, ValidationInfo, field_validator, model_validator
 22from typing_extensions import Annotated
 23
 24from .._internal.common_nodes import Node, ResourceDescrBase
 25from .._internal.constants import TAG_CATEGORIES
 26from .._internal.field_validation import validate_gh_user
 27from .._internal.field_warning import as_warning, warn
 28from .._internal.io import (
 29    BioimageioYamlContent,
 30    FileDescr,
 31    V_suffix,
 32    include_in_package_serializer,
 33    is_yaml_value,
 34    validate_suffix,
 35)
 36from .._internal.io_basics import AbsoluteFilePath, Sha256
 37from .._internal.license_id import DeprecatedLicenseId, LicenseId
 38from .._internal.node_converter import Converter
 39from .._internal.types import ImportantFileSource, NotEmpty, RelativeFilePath
 40from .._internal.url import HttpUrl
 41from .._internal.validated_string import ValidatedString
 42from .._internal.validator_annotations import (
 43    AfterValidator,
 44    Predicate,
 45    RestrictCharacters,
 46)
 47from .._internal.version_type import Version
 48from .._internal.warning_levels import ALERT, INFO
 49from ._v0_3_converter import convert_from_older_format
 50from .v0_2 import Author as _Author_v0_2
 51from .v0_2 import BadgeDescr, CoverImageSource, Doi, OrcidId, Uploader
 52from .v0_2 import Maintainer as _Maintainer_v0_2
 53
 54__all__ = [
 55    "Author",
 56    "BadgeDescr",
 57    "CiteEntry",
 58    "DeprecatedLicenseId",
 59    "Doi",
 60    "FileDescr",
 61    "GenericDescr",
 62    "HttpUrl",
 63    "KNOWN_SPECIFIC_RESOURCE_TYPES",
 64    "LicenseId",
 65    "LinkedResource",
 66    "Maintainer",
 67    "OrcidId",
 68    "RelativeFilePath",
 69    "ResourceId",
 70    "Sha256",
 71    "Uploader",
 72    "VALID_COVER_IMAGE_EXTENSIONS",
 73    "Version",
 74]
 75
 76KNOWN_SPECIFIC_RESOURCE_TYPES = (
 77    "application",
 78    "collection",
 79    "dataset",
 80    "model",
 81    "notebook",
 82)
 83VALID_COVER_IMAGE_EXTENSIONS = (
 84    ".gif",
 85    ".jpeg",
 86    ".jpg",
 87    ".png",
 88    ".svg",
 89)
 90
 91
 92class ResourceId(ValidatedString):
 93    root_model: ClassVar[Type[RootModel[Any]]] = RootModel[
 94        Annotated[
 95            NotEmpty[str],
 96            RestrictCharacters(string.ascii_lowercase + string.digits + "_-/."),
 97            annotated_types.Predicate(
 98                lambda s: not (s.startswith("/") or s.endswith("/"))
 99            ),
100        ]
101    ]
102
103
104def _validate_md_suffix(value: V_suffix) -> V_suffix:
105    return validate_suffix(value, suffix=".md", case_sensitive=True)
106
107
108DocumentationSource = Annotated[
109    Union[AbsoluteFilePath, RelativeFilePath, HttpUrl],
110    Field(union_mode="left_to_right"),
111    AfterValidator(_validate_md_suffix),
112    include_in_package_serializer,
113]
114
115
116def _has_no_slash(s: str) -> bool:
117    return "/" not in s and "\\" not in s
118
119
120class Author(_Author_v0_2):
121    name: Annotated[str, Predicate(_has_no_slash)]
122    github_user: Optional[str] = None
123
124    @field_validator("github_user", mode="after")
125    def _validate_gh_user(cls, value: Optional[str]):
126        if value is None:
127            return None
128        else:
129            return validate_gh_user(value)
130
131
132class _AuthorConv(Converter[_Author_v0_2, Author]):
133    def _convert(
134        self, src: _Author_v0_2, tgt: "type[Author] | type[dict[str, Any]]"
135    ) -> "Author | dict[str, Any]":
136        return tgt(
137            name=src.name,
138            github_user=src.github_user,
139            affiliation=src.affiliation,
140            email=src.email,
141            orcid=src.orcid,
142        )
143
144
145_author_conv = _AuthorConv(_Author_v0_2, Author)
146
147
148class Maintainer(_Maintainer_v0_2):
149    name: Optional[Annotated[str, Predicate(_has_no_slash)]] = None
150    github_user: str
151
152    @field_validator("github_user", mode="after")
153    def validate_gh_user(cls, value: str):
154        return validate_gh_user(value)
155
156
157class _MaintainerConv(Converter[_Maintainer_v0_2, Maintainer]):
158    def _convert(
159        self, src: _Maintainer_v0_2, tgt: "type[Maintainer | dict[str, Any]]"
160    ) -> "Maintainer | dict[str, Any]":
161        return tgt(
162            name=src.name,
163            github_user=src.github_user,
164            affiliation=src.affiliation,
165            email=src.email,
166            orcid=src.orcid,
167        )
168
169
170_maintainer_conv = _MaintainerConv(_Maintainer_v0_2, Maintainer)
171
172
173class CiteEntry(Node):
174    """A citation that should be referenced in work using this resource."""
175
176    text: str
177    """free text description"""
178
179    doi: Optional[Doi] = None
180    """A digital object identifier (DOI) is the prefered citation reference.
181    See https://www.doi.org/ for details.
182    Note:
183        Either **doi** or **url** have to be specified.
184    """
185
186    url: Optional[HttpUrl] = None
187    """URL to cite (preferably specify a **doi** instead/also).
188    Note:
189        Either **doi** or **url** have to be specified.
190    """
191
192    @model_validator(mode="after")
193    def _check_doi_or_url(self):
194        if not self.doi and not self.url:
195            raise ValueError("Either 'doi' or 'url' is required")
196
197        return self
198
199
200class LinkedResourceBase(Node):
201
202    @model_validator(mode="before")
203    def _remove_version_number(  # pyright: ignore[reportUnknownParameterType]
204        cls, value: Union[Any, Dict[Any, Any]]
205    ):
206        if isinstance(value, dict):
207            vn: Any = value.pop("version_number", None)
208            if vn is not None and value.get("version") is None:
209                value["version"] = vn
210
211        return value  # pyright: ignore[reportUnknownVariableType]
212
213    version: Optional[Version] = None
214    """The version of the linked resource following SemVer 2.0."""
215
216
217class LinkedResource(LinkedResourceBase):
218    """Reference to a bioimage.io resource"""
219
220    id: ResourceId
221    """A valid resource `id` from the official bioimage.io collection."""
222
223
224class BioimageioConfig(Node, extra="allow"):
225    """bioimage.io internal metadata."""
226
227
228class Config(Node, extra="allow"):
229    """A place to store additional metadata (often tool specific).
230
231    Such additional metadata is typically set programmatically by the respective tool
232    or by people with specific insights into the tool.
233    If you want to store additional metadata that does not match any of the other
234    fields, think of a key unlikely to collide with anyone elses use-case/tool and save
235    it here.
236
237    Please consider creating [an issue in the bioimageio.spec repository](https://github.com/bioimage-io/spec-bioimage-io/issues/new?template=Blank+issue)
238    if you are not sure if an existing field could cover your use case
239    or if you think such a field should exist.
240    """
241
242    bioimageio: BioimageioConfig = Field(default_factory=BioimageioConfig)
243    """bioimage.io internal metadata."""
244
245    @model_validator(mode="after")
246    def _validate_extra_fields(self):
247        if self.model_extra:
248            for k, v in self.model_extra.items():
249                if not isinstance(v, Node) and not is_yaml_value(v):
250                    raise ValueError(
251                        f"config.{k} is not a valid YAML value or `Node` instance"
252                    )
253
254        return self
255
256
257class GenericModelDescrBase(ResourceDescrBase):
258    """Base for all resource descriptions including of model descriptions"""
259
260    name: Annotated[
261        Annotated[
262            str, RestrictCharacters(string.ascii_letters + string.digits + "_+- ()")
263        ],
264        MinLen(5),
265        MaxLen(128),
266        warn(MaxLen(64), "Name longer than 64 characters.", INFO),
267    ]
268    name: Annotated[NotEmpty[str], MaxLen(128)]
269    """A human-friendly name of the resource description.
270    May only contains letters, digits, underscore, minus, parentheses and spaces."""
271
272    description: Annotated[
273        str, MaxLen(1024), warn(MaxLen(512), "Description longer than 512 characters.")
274    ]
275    """A string containing a brief description."""
276
277    covers: Annotated[
278        List[CoverImageSource],
279        Field(
280            examples=[],
281            description=(
282                "Cover images. Please use an image smaller than 500KB and an aspect"
283                " ratio width to height of 2:1 or 1:1.\nThe supported image formats"
284                f" are: {VALID_COVER_IMAGE_EXTENSIONS}"
285            ),
286        ),
287    ] = Field(default_factory=list)
288    """∈📦 Cover images."""
289
290    id_emoji: Optional[
291        Annotated[str, Len(min_length=1, max_length=2), Field(examples=["🦈", "🦥"])]
292    ] = None
293    """UTF-8 emoji for display alongside the `id`."""
294
295    authors: NotEmpty[List[Author]]
296    """The authors are the creators of this resource description and the primary points of contact."""
297
298    attachments: List[FileDescr] = Field(default_factory=list)
299    """file attachments"""
300
301    cite: NotEmpty[List[CiteEntry]]
302    """citations"""
303
304    license: Annotated[
305        Annotated[
306            Union[LicenseId, DeprecatedLicenseId], Field(union_mode="left_to_right")
307        ],
308        warn(
309            LicenseId,
310            "{value} is deprecated, see https://spdx.org/licenses/{value}.html",
311        ),
312        Field(examples=["CC0-1.0", "MIT", "BSD-2-Clause"]),
313    ]
314    """A [SPDX license identifier](https://spdx.org/licenses/).
315    We do not support custom license beyond the SPDX license list, if you need that please
316    [open a GitHub issue](https://github.com/bioimage-io/spec-bioimage-io/issues/new/choose)
317    to discuss your intentions with the community."""
318
319    git_repo: Annotated[
320        Optional[HttpUrl],
321        Field(
322            examples=[
323                "https://github.com/bioimage-io/spec-bioimage-io/tree/main/example_descriptions/models/unet2d_nuclei_broad"
324            ],
325        ),
326    ] = None
327    """A URL to the Git repository where the resource is being developed."""
328
329    icon: Union[
330        Annotated[str, Len(min_length=1, max_length=2)], ImportantFileSource, None
331    ] = None
332    """An icon for illustration, e.g. on bioimage.io"""
333
334    links: Annotated[
335        List[str],
336        Field(
337            examples=[
338                (
339                    "ilastik/ilastik",
340                    "deepimagej/deepimagej",
341                    "zero/notebook_u-net_3d_zerocostdl4mic",
342                )
343            ],
344        ),
345    ] = Field(default_factory=list)
346    """IDs of other bioimage.io resources"""
347
348    uploader: Optional[Uploader] = None
349    """The person who uploaded the model (e.g. to bioimage.io)"""
350
351    maintainers: List[Maintainer] = Field(default_factory=list)
352    """Maintainers of this resource.
353    If not specified, `authors` are maintainers and at least some of them has to specify their `github_user` name"""
354
355    @partial(as_warning, severity=ALERT)
356    @field_validator("maintainers", mode="after")
357    @classmethod
358    def check_maintainers_exist(
359        cls, maintainers: List[Maintainer], info: ValidationInfo
360    ) -> List[Maintainer]:
361        if not maintainers and "authors" in info.data:
362            authors: List[Author] = info.data["authors"]
363            if all(a.github_user is None for a in authors):
364                raise ValueError(
365                    "Missing `maintainers` or any author in `authors` with a specified"
366                    + " `github_user` name."
367                )
368
369        return maintainers
370
371    tags: Annotated[
372        List[str],
373        Field(examples=[("unet2d", "pytorch", "nucleus", "segmentation", "dsb2018")]),
374    ] = Field(default_factory=list)
375    """Associated tags"""
376
377    @as_warning
378    @field_validator("tags")
379    @classmethod
380    def warn_about_tag_categories(
381        cls, value: List[str], info: ValidationInfo
382    ) -> List[str]:
383        categories = TAG_CATEGORIES.get(info.data["type"], {})
384        missing_categories: List[Dict[str, Sequence[str]]] = []
385        for cat, entries in categories.items():
386            if not any(e in value for e in entries):
387                missing_categories.append({cat: entries})
388
389        if missing_categories:
390            raise ValueError(
391                f"Missing tags from bioimage.io categories: {missing_categories}"
392            )
393
394        return value
395
396    version: Optional[Version] = None
397    """The version of the resource following SemVer 2.0."""
398
399    @model_validator(mode="before")
400    def _remove_version_number(  # pyright: ignore[reportUnknownParameterType]
401        cls, value: Union[Any, Dict[Any, Any]]
402    ):
403        if isinstance(value, dict):
404            vn: Any = value.pop("version_number", None)
405            if vn is not None and value.get("version") is None:
406                value["version"] = vn
407
408        return value  # pyright: ignore[reportUnknownVariableType]
409
410
411class GenericDescrBase(GenericModelDescrBase):
412    """Base for all resource descriptions except for the model descriptions"""
413
414    implemented_format_version: ClassVar[Literal["0.3.0"]] = "0.3.0"
415    if TYPE_CHECKING:
416        format_version: Literal["0.3.0"] = "0.3.0"
417    else:
418        format_version: Literal["0.3.0"]
419        """The **format** version of this resource specification"""
420
421    @model_validator(mode="before")
422    @classmethod
423    def _convert_from_older_format(
424        cls, data: BioimageioYamlContent, /
425    ) -> BioimageioYamlContent:
426        cls.convert_from_old_format_wo_validation(data)
427        return data
428
429    @classmethod
430    def convert_from_old_format_wo_validation(cls, data: BioimageioYamlContent) -> None:
431        """Convert metadata following an older format version to this classes' format
432        without validating the result.
433        """
434        convert_from_older_format(data)
435
436    documentation: Annotated[
437        Optional[DocumentationSource],
438        Field(
439            examples=[
440                "https://raw.githubusercontent.com/bioimage-io/spec-bioimage-io/main/example_descriptions/models/unet2d_nuclei_broad/README.md",
441                "README.md",
442            ],
443        ),
444    ] = None
445    """∈📦 URL or relative path to a markdown file encoded in UTF-8 with additional documentation.
446    The recommended documentation file name is `README.md`. An `.md` suffix is mandatory."""
447
448    badges: List[BadgeDescr] = Field(default_factory=list)
449    """badges associated with this resource"""
450
451    config: Config = Field(default_factory=Config)
452    """A field for custom configuration that can contain any keys not present in the RDF spec.
453    This means you should not store, for example, a GitHub repo URL in `config` since there is a `git_repo` field.
454    Keys in `config` may be very specific to a tool or consumer software. To avoid conflicting definitions,
455    it is recommended to wrap added configuration into a sub-field named with the specific domain or tool name,
456    for example:
457    ```yaml
458    config:
459        giraffe_neckometer:  # here is the domain name
460            length: 3837283
461            address:
462                home: zoo
463        imagej:              # config specific to ImageJ
464            macro_dir: path/to/macro/file
465    ```
466    If possible, please use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) for keys in `config`.
467    You may want to list linked files additionally under `attachments` to include them when packaging a resource.
468    (Packaging a resource means downloading/copying important linked files and creating a ZIP archive that contains
469    an altered rdf.yaml file with local references to the downloaded files.)"""
470
471
472ResourceDescrType = TypeVar("ResourceDescrType", bound=GenericDescrBase)
473
474
475class GenericDescr(GenericDescrBase, extra="ignore"):
476    """Specification of the fields used in a generic bioimage.io-compliant resource description file (RDF).
477
478    An RDF is a YAML file that describes a resource such as a model, a dataset, or a notebook.
479    Note that those resources are described with a type-specific RDF.
480    Use this generic resource description, if none of the known specific types matches your resource.
481    """
482
483    type: Annotated[str, LowerCase] = Field("generic", frozen=True)
484    """The resource type assigns a broad category to the resource."""
485
486    id: Optional[
487        Annotated[ResourceId, Field(examples=["affable-shark", "ambitious-sloth"])]
488    ] = None
489    """bioimage.io-wide unique resource identifier
490    assigned by bioimage.io; version **un**specific."""
491
492    parent: Optional[ResourceId] = None
493    """The description from which this one is derived"""
494
495    source: Optional[HttpUrl] = None
496    """The primary source of the resource"""
497
498    @field_validator("type", mode="after")
499    @classmethod
500    def check_specific_types(cls, value: str) -> str:
501        if value in KNOWN_SPECIFIC_RESOURCE_TYPES:
502            raise ValueError(
503                f"Use the {value} description instead of this generic description for"
504                + f" your '{value}' resource."
505            )
506
507        return value