feat: add Python SDK for model spec types and validation

.gitignore

@@ -10,6 +10,13 @@
 
 # Dependency directories (remove the comment below to include it)
 vendor/
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+.pytest_cache/
 .idea
 .vscode
 .cache

specs-python/modelpack/v1/__init__.py

@@ -0,0 +1,91 @@
+#     Copyright 2025 The CNCF ModelPack Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""ModelPack Python SDK - CNCF standard for packaging and distributing AI models."""
+
+from modelpack.v1.config import (
+    Model,
+    ModelCapabilities,
+    ModelConfig,
+    ModelDescriptor,
+    ModelFS,
+    Modality,
+)
+from modelpack.v1.annotations import (
+    ANNOTATION_FILEPATH,
+    ANNOTATION_FILE_METADATA,
+    ANNOTATION_MEDIA_TYPE_UNTESTED,
+    FileMetadata,
+)
+from modelpack.v1.mediatype import (
+    ARTIFACT_TYPE_MODEL_MANIFEST,
+    MEDIA_TYPE_MODEL_CONFIG,
+    MEDIA_TYPE_MODEL_WEIGHT_RAW,
+    MEDIA_TYPE_MODEL_WEIGHT,
+    MEDIA_TYPE_MODEL_WEIGHT_GZIP,
+    MEDIA_TYPE_MODEL_WEIGHT_ZSTD,
+    MEDIA_TYPE_MODEL_WEIGHT_CONFIG_RAW,
+    MEDIA_TYPE_MODEL_WEIGHT_CONFIG,
+    MEDIA_TYPE_MODEL_WEIGHT_CONFIG_GZIP,
+    MEDIA_TYPE_MODEL_WEIGHT_CONFIG_ZSTD,
+    MEDIA_TYPE_MODEL_DOC_RAW,
+    MEDIA_TYPE_MODEL_DOC,
+    MEDIA_TYPE_MODEL_DOC_GZIP,
+    MEDIA_TYPE_MODEL_DOC_ZSTD,
+    MEDIA_TYPE_MODEL_CODE_RAW,
+    MEDIA_TYPE_MODEL_CODE,
+    MEDIA_TYPE_MODEL_CODE_GZIP,
+    MEDIA_TYPE_MODEL_CODE_ZSTD,
+    MEDIA_TYPE_MODEL_DATASET_RAW,
+    MEDIA_TYPE_MODEL_DATASET,
+    MEDIA_TYPE_MODEL_DATASET_GZIP,
+    MEDIA_TYPE_MODEL_DATASET_ZSTD,
+)
+from modelpack.v1.validator import validate_config
+
+__all__ = [
+    "Model",
+    "ModelCapabilities",
+    "ModelConfig",
+    "ModelDescriptor",
+    "ModelFS",
+    "Modality",
+    "FileMetadata",
+    "ANNOTATION_FILEPATH",
+    "ANNOTATION_FILE_METADATA",
+    "ANNOTATION_MEDIA_TYPE_UNTESTED",
+    "ARTIFACT_TYPE_MODEL_MANIFEST",
+    "MEDIA_TYPE_MODEL_CONFIG",
+    "MEDIA_TYPE_MODEL_WEIGHT_RAW",
+    "MEDIA_TYPE_MODEL_WEIGHT",
+    "MEDIA_TYPE_MODEL_WEIGHT_GZIP",
+    "MEDIA_TYPE_MODEL_WEIGHT_ZSTD",
+    "MEDIA_TYPE_MODEL_WEIGHT_CONFIG_RAW",
+    "MEDIA_TYPE_MODEL_WEIGHT_CONFIG",
+    "MEDIA_TYPE_MODEL_WEIGHT_CONFIG_GZIP",
+    "MEDIA_TYPE_MODEL_WEIGHT_CONFIG_ZSTD",
+    "MEDIA_TYPE_MODEL_DOC_RAW",
+    "MEDIA_TYPE_MODEL_DOC",
+    "MEDIA_TYPE_MODEL_DOC_GZIP",
+    "MEDIA_TYPE_MODEL_DOC_ZSTD",
+    "MEDIA_TYPE_MODEL_CODE_RAW",
+    "MEDIA_TYPE_MODEL_CODE",
+    "MEDIA_TYPE_MODEL_CODE_GZIP",
+    "MEDIA_TYPE_MODEL_CODE_ZSTD",
+    "MEDIA_TYPE_MODEL_DATASET_RAW",
+    "MEDIA_TYPE_MODEL_DATASET",
+    "MEDIA_TYPE_MODEL_DATASET_GZIP",
+    "MEDIA_TYPE_MODEL_DATASET_ZSTD",
+    "validate_config",
+]

specs-python/modelpack/v1/annotations.py

@@ -0,0 +1,77 @@
+#     Copyright 2025 The CNCF ModelPack Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Annotation constants and types matching specs-go/v1/annotations.go."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+# Annotation key for the file path of the layer.
+ANNOTATION_FILEPATH = "org.cncf.model.filepath"
+
+# Annotation key for the file metadata of the layer.
+ANNOTATION_FILE_METADATA = "org.cncf.model.file.metadata+json"
+
+# Annotation key for file media type untested flag of the layer.
+ANNOTATION_MEDIA_TYPE_UNTESTED = "org.cncf.model.file.mediatype.untested"
+
+
+@dataclass
+class FileMetadata:
+    """Represents the metadata of a file.
+
+    Mirrors the Go FileMetadata struct in specs-go/v1/annotations.go.
+    """
+
+    name: str = ""
+    mode: int = 0
+    uid: int = 0
+    gid: int = 0
+    size: int = 0
+    mod_time: datetime | None = None
+    typeflag: int = 0
+
+    def to_dict(self) -> dict:
+        """Serialize to a dict matching the JSON field names."""
+        d: dict = {
+            "name": self.name,
+            "mode": self.mode,
+            "uid": self.uid,
+            "gid": self.gid,
+            "size": self.size,
+            "typeflag": self.typeflag,
+        }
+        if self.mod_time is not None:
+            d["mtime"] = self.mod_time.isoformat()
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict) -> FileMetadata:
+        """Deserialize from a dict with JSON field names."""
+        mod_time = None
+        if "mtime" in data:
+            mod_time = datetime.fromisoformat(
+                data["mtime"].replace("Z", "+00:00")
+            )
+        return cls(
+            name=data.get("name", ""),
+            mode=data.get("mode", 0),
+            uid=data.get("uid", 0),
+            gid=data.get("gid", 0),
+            size=data.get("size", 0),
+            mod_time=mod_time,
+            typeflag=data.get("typeflag", 0),
+        )

specs-python/modelpack/v1/config-schema.json

@@ -0,0 +1,168 @@
+{
+    "description": "Model Artifact Configuration Schema",
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "$id": "https://github.com/modelpack/model-spec/config",
+    "type": "object",
+    "properties": {
+      "descriptor": {
+        "$ref": "#/$defs/ModelDescriptor"
+      },
+      "modelfs": {
+        "$ref": "#/$defs/ModelFS"
+      },
+      "config": {
+        "$ref": "#/$defs/ModelConfig"
+      }
+    },
+    "additionalProperties": false,
+    "required": [
+      "descriptor",
+      "config",
+      "modelfs"
+    ],
+    "$defs": {
+      "ModelConfig": {
+        "type": "object",
+        "properties": {
+          "architecture": {
+            "type": "string"
+          },
+          "format": {
+            "type": "string"
+          },
+          "paramSize": {
+            "type": "string"
+          },
+          "precision": {
+            "type": "string"
+          },
+          "quantization": {
+            "type": "string"
+          },
+          "capabilities": {
+            "$ref": "#/$defs/ModelCapabilities"
+          }
+        },
+        "additionalProperties": false
+      },
+      "ModelDescriptor": {
+        "type": "object",
+        "properties": {
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "authors": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "family": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "docURL": {
+            "type": "string"
+          },
+          "sourceURL": {
+            "type": "string"
+          },
+          "datasetsURL": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "version": {
+            "type": "string"
+          },
+          "revision": {
+            "type": "string"
+          },
+          "vendor": {
+            "type": "string"
+          },
+          "licenses": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "title": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      },
+      "ModelFS": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["layers"]
+          },
+          "diffIds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1
+          }
+        },
+        "additionalProperties": false,
+        "required": [
+          "type",
+          "diffIds"
+        ]
+      },
+      "ModelCapabilities": {
+        "type": "object",
+        "properties": {
+          "inputTypes": {
+            "type": "array",
+            "items": {
+               "$ref": "#/$defs/Modality"
+            }
+          },
+          "outputTypes": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/Modality"
+            }
+          },
+          "knowledgeCutoff": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "reasoning": {
+            "type": "boolean"
+          },
+          "toolUsage": {
+            "type": "boolean"
+          },
+          "reward": {
+            "type": "boolean"
+          },
+          "languages": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z]{2}$"
+            }
+          }
+        },
+        "additionalProperties": false
+      },
+      "Modality": {
+        "type": "string",
+        "enum": ["text", "image", "audio", "video", "embedding", "other"]
+      }
+  }
+}