dyff-schema 0.24.0__py3-none-any.whl → 0.25.0__py3-none-any.whl

dyff/schema/commands.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2024 UL Research Institutes
+# SPDX-License-Identifier: Apache-2.0
+
+from .v0.r1.commands import *

dyff/schema/v0/r1/base.py

@@ -577,6 +577,9 @@ class DyffBaseModel(pydantic.BaseModel):
     class Config:
         extra = pydantic.Extra.forbid
 
+    # TODO: (DYFF-223) I think that exclude_unset=True should be the default
+    # for all schema objects, but I'm unsure of the consequences of making
+    # this change and we'll defer it until v1.
     def dict(self, *, by_alias: bool = True, **kwargs) -> _ModelAsDict:
         return super().dict(by_alias=by_alias, **kwargs)
 

dyff/schema/v0/r1/commands.py

@@ -0,0 +1,201 @@
+# SPDX-FileCopyrightText: 2024 UL Research Institutes
+# SPDX-License-Identifier: Apache-2.0
+"""The command schemas describe the API for the command model.
+
+These are used internally by the platform and users typically won't encounter them.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Union
+
+import pydantic
+
+from .base import DyffSchemaBaseModel
+from .platform import (
+    Documented,
+    DyffEntityType,
+    EntityKindLiteral,
+    FamilyMembers,
+    Labeled,
+    Status,
+)
+
+# ----------------------------------------------------------------------------
+
+
+# mypy gets confused because 'dict' is the name of a method in DyffBaseModel
+_ModelAsDict = dict[str, Any]
+
+
+class EntityIdentifier(DyffSchemaBaseModel):
+    """Identifies a single entity."""
+
+    @staticmethod
+    def of(entity: DyffEntityType) -> EntityIdentifier:
+        """Create an identifier that identifies the given entity."""
+        return EntityIdentifier(kind=entity.kind, id=entity.id)
+
+    kind: EntityKindLiteral = pydantic.Field(description="The .kind of the entity.")
+    id: str = pydantic.Field(description="The .id of the entity.")
+
+
+class FamilyIdentifier(EntityIdentifier):
+    """Identifies a single Family entity."""
+
+    kind: Literal["Family"] = "Family"
+
+
+class Command(DyffSchemaBaseModel):
+    """Base class for Command messages.
+
+    Commands define the API of the "command model" in our CQRS architecture.
+    """
+
+    command: Literal[
+        "AppendRevisionToHistory",
+        "CreateEntity",
+        "EditEntityDocumentation",
+        "EditEntityLabels",
+        "EditFamilyMembers",
+        "ForgetEntity",
+        "UpdateEntityStatus",
+    ]
+
+    # TODO: (DYFF-223) I think that exclude_unset=True should be the default
+    # for all schema objects, but I'm unsure of the consequences of making
+    # this change and we'll defer it until v1.
+    def dict(
+        self, *, by_alias: bool = True, exclude_unset=True, **kwargs
+    ) -> _ModelAsDict:
+        return super().dict(by_alias=by_alias, exclude_unset=exclude_unset, **kwargs)
+
+    def json(self, *, by_alias: bool = True, exclude_unset=True, **kwargs) -> str:
+        return super().json(by_alias=by_alias, exclude_unset=exclude_unset, **kwargs)
+
+
+# ----------------------------------------------------------------------------
+
+
+class CreateEntity(Command):
+    """Create a new entity."""
+
+    command: Literal["CreateEntity"] = "CreateEntity"
+
+    data: DyffEntityType = pydantic.Field(
+        description="The full spec of the entity to create."
+    )
+
+
+# ----------------------------------------------------------------------------
+
+
+class EditEntityDocumentationData(Documented, EntityIdentifier):
+    """Payload data for the EditEntityDocumentation command."""
+
+
+class EditEntityDocumentation(Command):
+    """Edit the documentation associated with an entity.
+
+    Setting a documentation field to null/None deletes the corresponding value. To
+    preserve the existing value, leave the field *unset*.
+    """
+
+    command: Literal["EditEntityDocumentation"] = "EditEntityDocumentation"
+
+    data: EditEntityDocumentationData = pydantic.Field(description="The edit data.")
+
+
+# ----------------------------------------------------------------------------
+
+
+class EditEntityLabelsData(Labeled, EntityIdentifier):
+    """Payload data for the EditEntityLabels command."""
+
+
+class EditEntityLabels(Command):
+    """Edit the labels associated with an entity.
+
+    Setting a label field to null/None deletes the corresponding value. To preserve the
+    existing value, leave the field *unset*.
+    """
+
+    command: Literal["EditEntityLabels"] = "EditEntityLabels"
+
+    data: EditEntityLabelsData = pydantic.Field(description="The edit data.")
+
+
+# ----------------------------------------------------------------------------
+
+
+class EditFamilyMembersData(FamilyMembers, FamilyIdentifier):
+    """Payload data for the EditFamilyMembers command."""
+
+
+class EditFamilyMembers(Command):
+    """Edit the labels associated with an entity.
+
+    Setting a tag value to null/None deletes the corresponding value. To preserve the
+    existing value, leave the field *unset*.
+    """
+
+    command: Literal["EditFamilyMembers"] = "EditFamilyMembers"
+
+    data: EditFamilyMembersData = pydantic.Field(description="The edit data.")
+
+
+# ----------------------------------------------------------------------------
+
+
+class ForgetEntity(Command):
+    """Forget (permanently delete) an entity."""
+
+    command: Literal["ForgetEntity"] = "ForgetEntity"
+
+    data: EntityIdentifier = pydantic.Field(description="The entity to forget.")
+
+
+# ----------------------------------------------------------------------------
+
+
+class UpdateEntityStatusData(Status, EntityIdentifier):
+    """Payload data for the UpdateEntityStatus command."""
+
+
+class UpdateEntityStatus(Command):
+    """Update the status fields of an entity."""
+
+    command: Literal["UpdateEntityStatus"] = "UpdateEntityStatus"
+
+    data: UpdateEntityStatusData = pydantic.Field(description="The status update data.")
+
+
+# ----------------------------------------------------------------------------
+
+
+DyffCommandType = Union[
+    CreateEntity,
+    EditEntityDocumentation,
+    EditEntityLabels,
+    EditFamilyMembers,
+    ForgetEntity,
+    UpdateEntityStatus,
+]
+
+
+__all__ = [
+    "Command",
+    "CreateEntity",
+    "DyffCommandType",
+    "EditEntityDocumentation",
+    "EditEntityDocumentationData",
+    "EditEntityLabels",
+    "EditEntityLabelsData",
+    "EditFamilyMembers",
+    "EditFamilyMembersData",
+    "EntityIdentifier",
+    "FamilyIdentifier",
+    "ForgetEntity",
+    "UpdateEntityStatus",
+    "UpdateEntityStatusData",
+]

dyff/schema/v0/r1/platform.py

@@ -260,6 +260,29 @@ class Resources(str, enum.Enum):
             raise ValueError(f"No Resources for Entity kind: {kind}")
 
 
+EntityKindLiteral = Literal[
+    "Analysis",
+    "Audit",
+    "AuditProcedure",
+    "DataSource",
+    "Dataset",
+    "Evaluation",
+    "Family",
+    "Hazard",
+    "History",
+    "InferenceService",
+    "InferenceSession",
+    "Measurement",
+    "Method",
+    "Model",
+    "Module",
+    "Report",
+    "Revision",
+    "SafetyCase",
+    "UseCase",
+]
+
+
 EntityID: TypeAlias = pydantic.constr(regex=entity_id_regex())  # type: ignore
 
 
@@ -412,6 +435,13 @@ class Mutable(DyffSchemaBaseModel):
     lastModificationTime: datetime
 
 
+class DyffEntityMetadata(DyffSchemaBaseModel):
+    revision: Optional[str] = pydantic.Field(
+        default=None,
+        description="Unique identifier of the current revision of the entity.",
+    )
+
+
 class DyffEntity(Status, Labeled, SchemaVersion, DyffModelWithID):
     kind: Literal[
         "Analysis",
@@ -435,6 +465,11 @@ class DyffEntity(Status, Labeled, SchemaVersion, DyffModelWithID):
         "UseCase",
     ]
 
+    metadata: DyffEntityMetadata = pydantic.Field(
+        default_factory=DyffEntityMetadata,
+        description="Entity metadata",
+    )
+
     annotations: list[Annotation] = pydantic.Field(
         default_factory=list,
         description="A set of key-value annotations for the resource. Used to"
@@ -684,7 +719,17 @@ class Family(DyffEntity, FamilyBase, FamilyMembers):
 
 
 class RevisionMetadata(DyffSchemaBaseModel):
-    creationTime: datetime = pydantic.Field("The time when the Revision was created")
+    previousRevision: Optional[str] = pydantic.Field(
+        description="The ID of the revision from which this revision was derived."
+        "If None, then this is the first revision of the entity."
+    )
+    creationTime: datetime = pydantic.Field(
+        description="The time when the Revision was created"
+    )
+
+
+class ForeignRevision(RevisionMetadata):
+    id: str = pydantic.Field(description="Unique identifier of the entity")
 
 
 # Note: The 'Revision' class itself is defined all the way at the end of this
@@ -695,9 +740,13 @@ class RevisionMetadata(DyffSchemaBaseModel):
 class History(DyffEntity):
     kind: Literal["History"] = "History"
 
-    latest: str = pydantic.Field(description="The ID of the latest Revision")
-    revisions: dict[str, RevisionMetadata] = pydantic.Field(
-        description="The set of known Revisions"
+    historyOf: str = pydantic.Field(
+        description="The ID of the entity described by this History."
+    )
+
+    latest: ForeignRevision = pydantic.Field(description="The latest Revision")
+    revisions: list[ForeignRevision] = pydantic.Field(
+        description="The list of known Revisions, in chronological order (newest last)."
     )
 
 
@@ -1381,6 +1430,7 @@ class EvaluationClientConfiguration(DyffSchemaBaseModel):
 
     transientErrorRetryLimit: int = pydantic.Field(
         default=120,
+        ge=0,
         description="How many times to retry transient errors before the"
         " evaluation fails. The count is reset after a successful inference."
         " Note that transient errors often occur during inference service"
@@ -1390,6 +1440,7 @@ class EvaluationClientConfiguration(DyffSchemaBaseModel):
 
     transientErrorRetryDelaySeconds: int = pydantic.Field(
         default=30,
+        ge=1,
         description="How long to wait before retrying a transient error."
         " Note that transient errors often occur during inference service"
         " startup. The maximum time that the evaluation will wait for a"
@@ -1413,6 +1464,10 @@ class EvaluationClientConfiguration(DyffSchemaBaseModel):
         " Error (default): the evaluation fails. Ignore: no error.",
     )
 
+    requestTimeoutSeconds: int = pydantic.Field(
+        default=30, ge=0, description="The timeout delay for requests."
+    )
+
 
 class EvaluationBase(DyffSchemaBaseModel):
     dataset: str = pydantic.Field(description="The Dataset to evaluate on.")
@@ -2276,7 +2331,7 @@ def entity_class(kind: Entities):
     return _ENTITY_CLASS[kind]
 
 
-DyffEntityTypeExceptRevision = Union[
+_DyffEntityTypeRevisable = Union[
     Audit,
     AuditProcedure,
     DataSource,
@@ -2284,7 +2339,6 @@ DyffEntityTypeExceptRevision = Union[
     Evaluation,
     Family,
     Hazard,
-    History,
     InferenceService,
     InferenceSession,
     Measurement,
@@ -2297,6 +2351,18 @@ DyffEntityTypeExceptRevision = Union[
 ]
 
 
+class RevisionBody(DyffSchemaBaseModel):
+    format: Literal["Snapshot", "JsonMergePatch"]
+    snapshot: Optional[_DyffEntityTypeRevisable] = pydantic.Field(
+        default=None, description="A full snapshot of the entity."
+    )
+    jsonMergePatch: Optional[str] = pydantic.Field(
+        default=None,
+        description="A JsonMergePatch, serialized as a string, that will"
+        " transform the *current* revision into the *previous* revision.",
+    )
+
+
 # Note: This class is defined here because OpenAPI generation doesn't work
 # with the Python < 3.10 "ForwardDeclaration" syntax. You get an error like:
 #
@@ -2318,12 +2384,16 @@ DyffEntityTypeExceptRevision = Union[
 class Revision(DyffEntity, RevisionMetadata):
     kind: Literal["Revision"] = "Revision"
 
-    entity: DyffEntityTypeExceptRevision = pydantic.Field(
-        description="The associated entity data",
+    revisionOf: str = pydantic.Field(
+        description="The ID of the entity that this is a revision of"
+    )
+
+    body: RevisionBody = pydantic.Field(
+        description="The associated entity revision data",
     )
 
 
-DyffEntityType = Union[DyffEntityTypeExceptRevision, Revision]
+DyffEntityType = Union[_DyffEntityTypeRevisable, History, Revision]
 
 
 __all__ = [
@@ -2369,8 +2439,10 @@ __all__ = [
     "DyffSchemaBaseModel",
     "Entities",
     "EntityID",
+    "EntityKindLiteral",
     "Evaluation",
     "EvaluationBase",
+    "EvaluationClientConfiguration",
     "ExtractorStep",
     "Family",
     "FamilyBase",
@@ -2381,6 +2453,7 @@ __all__ = [
     "ForeignInferenceService",
     "ForeignMethod",
     "ForeignModel",
+    "ForeignRevision",
     "Frameworks",
     "Hazard",
     "History",
@@ -2439,6 +2512,7 @@ __all__ = [
     "ReportBase",
     "Resources",
     "Revision",
+    "RevisionBody",
     "RevisionMetadata",
     "Role",
     "SafetyCase",

{dyff_schema-0.24.0.dist-info → dyff_schema-0.25.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: dyff-schema
-Version: 0.24.0
+Version: 0.25.0
 Summary: Data models for the Dyff AI auditing platform.
 Author-email: Digital Safety Research Institute <contact@dsri.org>
 License: Apache-2.0

{dyff_schema-0.24.0.dist-info → dyff_schema-0.25.0.dist-info}/RECORD

@@ -2,6 +2,7 @@ dyff/schema/__init__.py,sha256=JcpxaRHNYgLjJWLjVayLlqacb2GX49Pazpwb8m-BctM,1031
 dyff/schema/adapters.py,sha256=YMTHv_2VlLGFp-Kqwa6H51hjffHmk8gXjZilHysIF5Q,123
 dyff/schema/annotations.py,sha256=nE6Jk1PLqlShj8uqjE_EzZC9zYnTDW5AVtQcjysiK8M,10018
 dyff/schema/base.py,sha256=jvaNtsSZyFfsdUZTcY_U-yfLY5_GyrMxSXhON2R9XR0,119
+dyff/schema/commands.py,sha256=hlqMJ99ZF_ElnGF6vQO_T872WM7aClFoFKkAXA66boI,123
 dyff/schema/copydoc.py,sha256=B4ZRpQmbFxi-3l9LCHvaJiVKb9VxADgC5vey804Febc,1075
 dyff/schema/errors.py,sha256=ow3yiucU4wGkeLmapUURp3eyaebwGUwDaVTXpPcrA7M,1542
 dyff/schema/ids.py,sha256=M3kdGRYGPCMnFkRRo0nzHlntdJtBrRwGJ_9R7LlN0bI,2085
@@ -23,8 +24,9 @@ dyff/schema/io/vllm.py,sha256=2q05M_-lTzq9oywKXHPPpCFCSDVCSsRQqtmERzWTtio,123
 dyff/schema/v0/__init__.py,sha256=L5y8UhRnojerPYHumsxQJRcHCNz8Hj9NM8b47mewMNs,92
 dyff/schema/v0/r1/__init__.py,sha256=L5y8UhRnojerPYHumsxQJRcHCNz8Hj9NM8b47mewMNs,92
 dyff/schema/v0/r1/adapters.py,sha256=dmQS2ecgDX4ZvTMOW-6NzV_Oq_UpaiyFd7QnSNoOnK8,33057
-dyff/schema/v0/r1/base.py,sha256=IpvlYDr6JjYo6tn8XW4C1Fpgd_uqzZGZsG_cuEn_gQs,19441
-dyff/schema/v0/r1/platform.py,sha256=GCVzHkFl7EZLDEpMxCy71HHfwU8191dxCemnqG4-kzw,78259
+dyff/schema/v0/r1/base.py,sha256=9tzgWKeQrSlLq2HERViDzaNYW6X5m5V6Uf9t8uky_FI,19640
+dyff/schema/v0/r1/commands.py,sha256=8Ixr-NpC1FHrkdyzZMCYLi7CoJNfFfadYPO1D9kfaq0,5653
+dyff/schema/v0/r1/platform.py,sha256=V7ezBMWkbGoDoWAElm-RcvX_5XBQ-BHXN23N3Kab8Rk,80273
 dyff/schema/v0/r1/requests.py,sha256=4TM1IKG9IP4MyprIy9E9XA_JqvkuwKAuY1ao1BbVLI0,15676
 dyff/schema/v0/r1/test.py,sha256=X6dUyVd5svcPCI-PBMOAqEfK9jv3bRDvkQTJzwS96c0,10720
 dyff/schema/v0/r1/version.py,sha256=isKAGuGxsdru8vDaYmI4YiZdJOu_wNxXK7u6QzD6FE4,392
@@ -37,9 +39,9 @@ dyff/schema/v0/r1/dataset/text.py,sha256=nLIn91Zlt0tNdXUklSgjJ-kEDxoPX32ISLkiv2D
 dyff/schema/v0/r1/dataset/vision.py,sha256=aIe0fbfM_g3DsrDTdg2K803YKLjZBpurM_VJcJFuZLc,369
 dyff/schema/v0/r1/io/__init__.py,sha256=L5y8UhRnojerPYHumsxQJRcHCNz8Hj9NM8b47mewMNs,92
 dyff/schema/v0/r1/io/vllm.py,sha256=CUE9y8KthtUI7sD49S875rDmPvKotSXVIRaBS79aBZs,5320
-dyff_schema-0.24.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-dyff_schema-0.24.0.dist-info/METADATA,sha256=ysTXvjZNSeDrJXjK1EYy8iYpxOqJ7PD1J8-bnNkHm_g,3482
-dyff_schema-0.24.0.dist-info/NOTICE,sha256=YONACu0s_Ui6jNi-wtEsVQbTU1JIkh8wvLH6d1-Ni_w,43
-dyff_schema-0.24.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-dyff_schema-0.24.0.dist-info/top_level.txt,sha256=9e3VVdeX73t_sUJOPQPCcGtYO1JhoErhHIi3WoWGcFI,5
-dyff_schema-0.24.0.dist-info/RECORD,,
+dyff_schema-0.25.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+dyff_schema-0.25.0.dist-info/METADATA,sha256=_d_BL3jZLaYU3uknTZDiRpBd1AMSGyY8ZrqPeMeqogs,3482
+dyff_schema-0.25.0.dist-info/NOTICE,sha256=YONACu0s_Ui6jNi-wtEsVQbTU1JIkh8wvLH6d1-Ni_w,43
+dyff_schema-0.25.0.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
+dyff_schema-0.25.0.dist-info/top_level.txt,sha256=9e3VVdeX73t_sUJOPQPCcGtYO1JhoErhHIi3WoWGcFI,5
+dyff_schema-0.25.0.dist-info/RECORD,,

{dyff_schema-0.24.0.dist-info → dyff_schema-0.25.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.0)
+Generator: setuptools (75.8.2)
 Root-Is-Purelib: true
 Tag: py3-none-any