wandb 0.22.2__py3-none-macosx_12_0_arm64.whl → 0.22.3__py3-none-macosx_12_0_arm64.whl

wandb/sdk/artifacts/_gqlutils.py

@@ -1,10 +1,30 @@
 from __future__ import annotations
 
+from contextlib import suppress
+from dataclasses import dataclass
 from functools import lru_cache
+from typing import TYPE_CHECKING
 
-from wandb_gql import Client, gql
+from wandb_gql import gql
 
-from ._generated import TYPE_INFO_GQL, TypeInfo, TypeInfoFragment
+from wandb._iterutils import one
+from wandb.errors import UnsupportedError
+from wandb.proto.wandb_internal_pb2 import ServerFeature
+from wandb.sdk.artifacts._generated.fetch_org_info_from_entity import (
+    FetchOrgInfoFromEntityEntity,
+)
+from wandb.sdk.internal._generated import SERVER_FEATURES_QUERY_GQL, ServerFeaturesQuery
+
+from ._generated import (
+    FETCH_ORG_INFO_FROM_ENTITY_GQL,
+    TYPE_INFO_GQL,
+    FetchOrgInfoFromEntity,
+    TypeInfo,
+    TypeInfoFragment,
+)
+
+if TYPE_CHECKING:
+    from wandb.apis.public import RetryingClient
 
 OMITTABLE_ARTIFACT_FIELDS = frozenset(
     {
@@ -18,13 +38,58 @@ OMITTABLE_ARTIFACT_FIELDS = frozenset(
 
 
 @lru_cache(maxsize=16)
-def type_info(client: Client, typename: str) -> TypeInfoFragment | None:
+def type_info(client: RetryingClient, typename: str) -> TypeInfoFragment | None:
     """Returns the type info for a given GraphQL type."""
     data = client.execute(gql(TYPE_INFO_GQL), variable_values={"name": typename})
     return TypeInfo.model_validate(data).type
 
 
-def supports_enable_tracking_var(client: Client) -> bool:
+@lru_cache(maxsize=16)
+def org_info_from_entity(
+    client: RetryingClient, entity: str
+) -> FetchOrgInfoFromEntityEntity | None:
+    """Returns the organization info for a given entity."""
+    gql_op = gql(FETCH_ORG_INFO_FROM_ENTITY_GQL)
+    data = client.execute(gql_op, variable_values={"entity": entity})
+    return FetchOrgInfoFromEntity.model_validate(data).entity
+
+
+@lru_cache(maxsize=16)
+def server_features(client: RetryingClient) -> dict[str, bool]:
+    """Returns a mapping of `{server_feature_name (str) -> is_enabled (bool)}`.
+
+    Results are cached per client instance.
+    """
+    try:
+        response = client.execute(gql(SERVER_FEATURES_QUERY_GQL))
+    except Exception as e:
+        # Unfortunately we currently have to match on the text of the error message,
+        # as the `gql` client raises `Exception` rather than a more specific error.
+        if 'Cannot query field "features" on type "ServerInfo".' in str(e):
+            return {}
+        raise
+
+    result = ServerFeaturesQuery.model_validate(response)
+    if (server_info := result.server_info) and (features := server_info.features):
+        return {feat.name: feat.is_enabled for feat in features if feat}
+    return {}
+
+
+def server_supports(client: RetryingClient, feature: str | int) -> bool:
+    """Return whether the current server supports the given feature.
+
+    Good to use for features that have a fallback mechanism for older servers.
+    """
+    # If we're given the protobuf enum value, convert to a string name.
+    # NOTE: We deliberately use names (str) instead of enum values (int)
+    # as the keys here, since:
+    # - the server identifies features by their name, rather than (client-side) enum value
+    # - the defined list of client-side flags may be behind the server-side list of flags
+    feature_name = ServerFeature.Name(feature) if isinstance(feature, int) else feature
+    return server_features(client).get(feature_name) or False
+
+
+def supports_enable_tracking_var(client: RetryingClient) -> bool:
     """Returns True if the server supports the `enableTracking` variable for the `Project.artifact(...)` field."""
     typ = type_info(client, "Project")
     if (
@@ -36,12 +101,111 @@ def supports_enable_tracking_var(client: Client) -> bool:
     return False
 
 
-def allowed_fields(client: Client, typename: str) -> set[str]:
+def allowed_fields(client: RetryingClient, typename: str) -> set[str]:
     """Returns the allowed field names for a given GraphQL type."""
     typ = type_info(client, typename)
     return {f.name for f in typ.fields} if (typ and typ.fields) else set()
 
 
-def omit_artifact_fields(client: Client) -> set[str]:
+def omit_artifact_fields(client: RetryingClient) -> set[str]:
     """Return names of Artifact fields to remove from GraphQL requests (for server compatibility)."""
     return set(OMITTABLE_ARTIFACT_FIELDS) - allowed_fields(client, "Artifact")
+
+
+@dataclass(frozen=True)
+class OrgInfo:
+    org_name: str
+    entity_name: str
+
+    def __contains__(self, other: str) -> bool:
+        return other in {self.org_name, self.entity_name}
+
+
+def resolve_org_entity_name(
+    client: RetryingClient,
+    non_org_entity: str,
+    org_or_entity: str | None = None,
+) -> str:
+    # resolveOrgEntityName fetches the portfolio's org entity's name.
+    #
+    # The org_or_org_entity parameter may be empty, an org's display name, or an org entity name.
+    #
+    # If the server doesn't support fetching the org name of a portfolio, then this returns
+    # the org_or_org_entity parameter, or an error if it is empty. Otherwise, this returns the
+    # fetched value after validating that the given organization, if not empty, matches
+    # either the org's display or entity name.
+    if not non_org_entity:
+        raise ValueError("Entity name is required to resolve org entity name.")
+
+    if "orgEntity" not in allowed_fields(client, "Organization"):
+        if org_or_entity:
+            # Server doesn't support fetching orgEntity to match against,
+            # so assume orgEntity as provided is already correct.
+            return org_or_entity
+
+        raise UnsupportedError(
+            "Fetching Registry artifacts without inputting an organization "
+            "is unavailable for your server version. "
+            "Please upgrade your server to 0.50.0 or later."
+        )
+
+    # Otherwise, fetch candidate orgs to verify/identify the correct orgEntity name, if possible.
+    entity = org_info_from_entity(client, non_org_entity)
+
+    # Parse possible organization(s) from the response
+
+    # ----------------------------------------------------------------------------
+    # If a team entity was provided, there should be a single organization under team/org entity type.
+    if entity and (org := entity.organization) and (org_entity := org.org_entity):
+        # Make sure the org_or_org_entity name, if given, matches the org or org entity name before returning the org entity.
+        org_info = OrgInfo(org_name=org.name, entity_name=org_entity.name)
+        if (not org_or_entity) or (org_or_entity in org_info):
+            return org_entity.name
+
+    # ----------------------------------------------------------------------------
+    # If a personal entity was provided, there may be multiple organizations that the user belongs to
+    if entity and (user := entity.user) and (orgs := user.organizations):
+        org_infos = [
+            OrgInfo(org_name=org.name, entity_name=org_entity.name)
+            for org in orgs
+            if (org_entity := org.org_entity)
+        ]
+        if org_or_entity:
+            with suppress(StopIteration):
+                return next(
+                    info.entity_name for info in org_infos if (org_or_entity in info)
+                )
+
+            if len(org_infos) == 1:
+                raise ValueError(
+                    f"Expecting the organization name or entity name to match {org_infos[0].org_name!r} "
+                    f"and cannot be linked/fetched with {org_or_entity!r}. "
+                    "Please update the target path with the correct organization name."
+                )
+            else:
+                raise ValueError(
+                    "Personal entity belongs to multiple organizations "
+                    f"and cannot be linked/fetched with {org_or_entity!r}. "
+                    "Please update the target path with the correct organization name "
+                    "or use a team entity in the entity settings."
+                )
+
+        else:
+            # If no input organization provided, error if entity belongs to:
+            # - multiple orgs, because we cannot determine which one to use.
+            # - no orgs, because there's nothing to use.
+            return one(
+                (org.entity_name for org in org_infos),
+                too_short=ValueError(
+                    f"Unable to resolve an organization associated with personal entity: {non_org_entity!r}. "
+                    "This could be because its a personal entity that doesn't belong to any organizations. "
+                    "Please specify the organization in the Registry path or use a team entity in the entity settings."
+                ),
+                too_long=ValueError(
+                    f"Personal entity {non_org_entity!r} belongs to multiple organizations "
+                    "and cannot be used without specifying the organization name. "
+                    "Please specify the organization in the Registry path or use a team entity in the entity settings."
+                ),
+            )
+
+    raise ValueError(f"Unable to find organization for entity {non_org_entity!r}.")

wandb/sdk/artifacts/_models/__init__.py

@@ -2,3 +2,12 @@
 
 Excludes GraphQL-generated classes.
 """
+
+__all__ = [
+    "ArtifactsBase",
+    "RegistryData",
+    "ArtifactCollectionData",
+]
+from .artifact_collection import ArtifactCollectionData
+from .base_model import ArtifactsBase
+from .registry import RegistryData

wandb/sdk/artifacts/_models/artifact_collection.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional, Tuple
+
+from pydantic import ConfigDict, Field
+from typing_extensions import Self
+
+from wandb._pydantic import field_validator
+from wandb.sdk.artifacts._generated import ArtifactCollectionFragment
+from wandb.sdk.artifacts._validators import (
+    SOURCE_COLLECTION_TYPENAME,
+    validate_artifact_name,
+    validate_tags,
+)
+
+from .base_model import ArtifactsBase
+
+
+class ArtifactCollectionData(ArtifactsBase):
+    """Transport-free model for local `ArtifactCollection` data.
+
+    For now, this is separated from the public `ArtifactCollection` model
+    to more easily ensure continuity in the public `ArtifactCollection` API.
+
+    Note:
+        In a future change, consider making _this_ the public `ArtifactCollection` instead, i.e.:
+        - Replace the _existing_ `ArtifactCollection` class with this one
+        - Rename _this_ class to `ArtifactCollection`
+        Note that this would be a breaking change.
+    """
+
+    model_config = ConfigDict(
+        str_min_length=1,  # Strings cannot be empty
+    )
+
+    typename__: str = Field(alias="__typename", frozen=True, repr=False)
+    """The GraphQL `__typename` for this object."""
+
+    id: str = Field(frozen=True, repr=False)
+    """The encoded GraphQL ID for this object."""
+
+    name: str
+    """The name of this collection."""
+
+    type: str
+    """The artifact type of this collection."""
+
+    description: Optional[str] = None
+    """The description, if any, for this collection."""
+
+    created_at: str = Field(frozen=True)
+    """When this collection was created."""
+
+    project: str = Field(frozen=True)
+    """The name of this collection's project."""
+
+    entity: str = Field(frozen=True)
+    """The name of the entity that owns this collection's project."""
+
+    aliases: Optional[Tuple[str, ...]] = Field(default=None, frozen=True)
+    """All aliases assigned to artifact versions within this collection.
+
+    Note:
+        `None` should signal that aliases haven't been (or couldn't be) fetched and parsed yet,
+        for any reason, NOT the actual absence of aliases in this collection.
+    """
+
+    tags: List[str] = Field(default_factory=list)
+    """The tags assigned to this collection.
+
+    Note that this is distinct from any tags assigned to individual artifact versions within this collection.
+    """
+
+    @field_validator("name", mode="plain")
+    def _validate_name(cls, v: str) -> str:
+        return validate_artifact_name(v)
+
+    @field_validator("tags", mode="plain")
+    def _validate_tags(cls, v: Any) -> list[str]:
+        """Ensure tags is a validated, deduped list of (str) tag names."""
+        return validate_tags(v)
+
+    @property
+    def is_sequence(self) -> bool:
+        """Returns True if the artifact collection is an ArtifactSequence (source collection)."""
+        return self.typename__ == SOURCE_COLLECTION_TYPENAME
+
+    @classmethod
+    def from_fragment(cls, obj: ArtifactCollectionFragment) -> Self:
+        """Instantiate this type from a GraphQL fragment."""
+        if obj.project is None:
+            raise ValueError(f"Missing project info in {type(obj)!r} data")
+
+        return cls(
+            typename__=obj.typename__,
+            id=obj.id,
+            name=obj.name,
+            type=obj.type.name,
+            description=obj.description,
+            created_at=obj.created_at,
+            project=obj.project.name,
+            entity=obj.project.entity.name,
+            tags=[e.node.name for e in obj.tags.edges if e.node],
+            aliases=(
+                [e.node.alias for e in obj.aliases.edges if e.node]
+                if obj.aliases
+                else []
+            ),
+        )

wandb/sdk/artifacts/_models/manifest.py

@@ -0,0 +1,26 @@
+from typing import Any, Dict, Literal, final
+
+from wandb._pydantic import field_validator, to_camel
+from wandb.sdk.artifacts.artifact_manifest_entry import ArtifactManifestEntry
+
+from .base_model import ArtifactsBase
+
+
+@final
+class ArtifactManifestV1Data(ArtifactsBase, alias_generator=to_camel):
+    """Data model for the v1 artifact manifest."""
+
+    version: Literal[1]
+
+    contents: Dict[str, ArtifactManifestEntry]
+
+    storage_policy: str
+    storage_policy_config: Dict[str, Any]
+
+    @field_validator("contents", mode="before")
+    def _validate_entries(cls, v: Any) -> Any:
+        # The dict keys should be the `entry.path` values, but they've
+        # historically been dropped from the JSON objects. This restores
+        # them on instantiation.
+        # Pydantic will handle converting dicts -> ArtifactManifestEntries.
+        return {path: {**dict(entry), "path": path} for path, entry in v.items()}

wandb/sdk/artifacts/_models/pagination.py

@@ -0,0 +1,26 @@
+"""Artifacts-specific data models for handling paginated results from GraphQL queries."""
+
+from wandb._pydantic import Connection, ConnectionWithTotal
+
+from .._generated.fragments import (
+    ArtifactCollectionFragment,
+    ArtifactFragment,
+    ArtifactMembershipFragment,
+    ArtifactTypeFragment,
+    FileFragment,
+    FileWithUrlFragment,
+    RegistryCollectionFragment,
+    RegistryFragment,
+)
+
+ArtifactTypeConnection = Connection[ArtifactTypeFragment]
+ArtifactCollectionConnection = ConnectionWithTotal[ArtifactCollectionFragment]
+ArtifactMembershipConnection = Connection[ArtifactMembershipFragment]
+
+FileWithUrlConnection = Connection[FileWithUrlFragment]
+ArtifactFileConnection = Connection[FileFragment]
+
+RunArtifactConnection = ConnectionWithTotal[ArtifactFragment]
+
+RegistryConnection = Connection[RegistryFragment]
+RegistryCollectionConnection = ConnectionWithTotal[RegistryCollectionFragment]

wandb/sdk/artifacts/_models/registry.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import ConfigDict, Field
+from typing_extensions import Self
+
+from wandb._pydantic import GQLId, field_validator
+from wandb._strutils import nameof
+from wandb.apis.public.registries._freezable_list import AddOnlyArtifactTypesList
+from wandb.apis.public.registries._utils import Visibility
+from wandb.sdk.artifacts._generated import RegistryFragment
+from wandb.sdk.artifacts._generated.fragments import RegistryFragmentArtifactTypes
+from wandb.sdk.artifacts._validators import REGISTRY_PREFIX, remove_registry_prefix
+
+from .base_model import ArtifactsBase
+
+
+class RegistryData(ArtifactsBase):
+    """Transport-free model for local `Registry` data.
+
+    For now, this is separated from the public `Registry` class
+    to more easily ensure continuity in the public `Registry` API.
+    """
+
+    model_config = ConfigDict(
+        str_min_length=1,  # Strings cannot be empty
+    )
+
+    id: GQLId = Field(frozen=True)
+    """The unique, encoded ID for this registry."""
+
+    created_at: str = Field(frozen=True)
+    """When this registry was created."""
+
+    updated_at: Optional[str] = Field(frozen=True)
+    """When this registry was last updated."""
+
+    organization: str = Field(frozen=True)
+    """The organization of the registry."""
+
+    entity: str = Field(frozen=True)
+    """The organization entity of the registry."""
+
+    name: str
+    """The name of the registry without the `wandb-registry-` project prefix."""
+
+    description: Optional[str] = None
+    """The description, if any, of the registry."""
+
+    allow_all_artifact_types: bool
+    """Whether all artifact types are allowed in the registry."""
+
+    artifact_types: AddOnlyArtifactTypesList = Field(
+        default_factory=AddOnlyArtifactTypesList
+    )
+    """The artifact types allowed in the registry.
+
+    The meaning of this list depends on the value of `allow_all_artifact_types`:
+    - If True: `artifact_types` are the previously-saved or currently-used types in the registry.
+    - If False: `artifact_types` are the only allowed artifact types in the registry.
+    """
+
+    visibility: Visibility = Field(alias="access")
+    """The visibility of the registry."""
+
+    @property
+    def full_name(self) -> str:
+        """The full project name of the registry, including the expected `wandb-registry-` prefix."""
+        return f"{REGISTRY_PREFIX}{self.name}"
+
+    @field_validator("artifact_types", mode="plain")
+    def _validate_artifact_types(cls, v: Any) -> AddOnlyArtifactTypesList:
+        """Coerce `artifact_types` to an AddOnlyArtifactTypesList."""
+        if isinstance(v, RegistryFragmentArtifactTypes):
+            # This is a GQL connection object, so we need to extract the node names
+            return AddOnlyArtifactTypesList(e.node.name for e in v.edges if e.node)
+
+        # By default, assume we were passed an iterable of strings
+        return AddOnlyArtifactTypesList(v)
+
+    @classmethod
+    def from_fragment(cls, obj: RegistryFragment) -> Self:
+        if not obj.entity.organization:
+            raise ValueError(
+                f"Unable to parse registry organization from {nameof(type(obj))!r} object"
+            )
+
+        return cls(
+            id=obj.id,
+            created_at=obj.created_at,
+            updated_at=obj.updated_at,
+            organization=obj.entity.organization.name,
+            entity=obj.entity.name,
+            name=remove_registry_prefix(obj.name),
+            description=obj.description,
+            allow_all_artifact_types=obj.allow_all_artifact_types,
+            artifact_types=obj.artifact_types,
+            visibility=obj.access,
+        )

wandb/sdk/artifacts/_validators.py

@@ -6,7 +6,17 @@ import json
 import re
 from dataclasses import dataclass, field, replace
 from functools import wraps
-from typing import TYPE_CHECKING, Any, Callable, Dict, Literal, Optional, TypeVar, cast
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    Literal,
+    Optional,
+    TypeVar,
+    cast,
+)
 
 from pydantic.dataclasses import dataclass as pydantic_dataclass
 from typing_extensions import Concatenate, ParamSpec, Self
@@ -35,8 +45,8 @@ MAX_ARTIFACT_METADATA_KEYS: Final[int] = 100
 ARTIFACT_NAME_MAXLEN: Final[int] = 128
 ARTIFACT_NAME_INVALID_CHARS: Final[frozenset[str]] = frozenset({"/"})
 
-LINKED_ARTIFACT_COLLECTION_TYPE: Final[str] = gql_typename(ArtifactPortfolioTypeFields)
-SOURCE_ARTIFACT_COLLECTION_TYPE: Final[str] = gql_typename(ArtifactSequenceTypeFields)
+LINKED_COLLECTION_TYPENAME: Final[str] = gql_typename(ArtifactPortfolioTypeFields)
+SOURCE_COLLECTION_TYPENAME: Final[str] = gql_typename(ArtifactSequenceTypeFields)
 
 
 @dataclass
@@ -85,11 +95,14 @@ def validate_artifact_name(name: str) -> str:
     return name
 
 
-INVALID_URL_CHARACTERS = ("/", "\\", "#", "?", "%", ":", "\r", "\n")
+INVALID_URL_CHARACTERS: Final[frozenset[str]] = frozenset("/\\#?%:\r\n")
 
+PROJECT_NAME_MAXLEN: Final[int] = 128
+REGISTRY_NAME_MAXLEN: Final[int] = PROJECT_NAME_MAXLEN - len(REGISTRY_PREFIX)
 
-def validate_project_name(name: str) -> None:
-    """Validates a project name according to W&B rules.
+
+def validate_project_name(name: str) -> str:
+    """Validates a project name according to W&B rules, returning the original name if successful.
 
     Args:
         name: The project name string.
@@ -97,18 +110,16 @@ def validate_project_name(name: str) -> None:
     Raises:
         ValueError: If the name is invalid (too long or contains invalid characters).
     """
-    max_len = 128
-
     if not name:
         raise ValueError("Project name cannot be empty")
     if not (registry_name := removeprefix(name, REGISTRY_PREFIX)):
         raise ValueError("Registry name cannot be empty")
 
-    if len(name) > max_len:
+    if len(name) > PROJECT_NAME_MAXLEN:
         if registry_name != name:
-            msg = f"Invalid registry name {registry_name!r}, must be {max_len - len(REGISTRY_PREFIX)} characters or less"
+            msg = f"Invalid registry name {registry_name!r}, must be {REGISTRY_NAME_MAXLEN} characters or less"
         else:
-            msg = f"Invalid project name {name!r}, must be {max_len} characters or less"
+            msg = f"Invalid project name {name!r}, must be {PROJECT_NAME_MAXLEN} characters or less"
         raise ValueError(msg)
 
     # Find the first occurrence of any invalid character
@@ -118,6 +129,10 @@ def validate_project_name(name: str) -> None:
         raise ValueError(
             f"Invalid project/registry name {error_name!r}, cannot contain characters: {invalid_chars_repr!s}"
         )
+    return name
+
+
+ALIAS_NAME_INVALID_CHARS: Final[frozenset[str]] = frozenset("/:")
 
 
 def validate_aliases(aliases: Collection[str] | str) -> list[str]:
@@ -127,36 +142,39 @@ def validate_aliases(aliases: Collection[str] | str) -> list[str]:
         ValueError: If any of the aliases contain invalid characters.
     """
     aliases_list = always_list(aliases)
-
-    invalid_chars = ("/", ":")
-    if any(char in alias for alias in aliases_list for char in invalid_chars):
+    if any(ALIAS_NAME_INVALID_CHARS.intersection(alias) for alias in aliases_list):
+        invalid_repr = ", ".join(sorted(map(repr, ALIAS_NAME_INVALID_CHARS)))
         raise ValueError(
-            f"Aliases must not contain any of the following characters: {', '.join(invalid_chars)}"
+            f"Aliases must not contain any of the following characters: {invalid_repr}"
         )
     return aliases_list
 
 
-def validate_artifact_types_list(artifact_types: list[str]) -> list[str]:
-    """Return True if the artifact types list is valid, False otherwise."""
-    artifact_types = always_list(artifact_types)
-    invalid_chars = ("/", ":")
+ARTIFACT_TYPE_NAME_MAXLEN: Final[int] = 128
+ARTIFACT_TYPE_NAME_INVALID_CHARS: Final[frozenset[str]] = frozenset("/:")
+
+
+def validate_artifact_types(artifact_types: Collection[str] | str) -> list[str]:
+    """Validate the artifact type names and return them as a list."""
+    artifact_types_list = always_list(artifact_types)
     if any(
-        char in type or len(type) > 128
-        for type in artifact_types
-        for char in invalid_chars
+        len(name) > ARTIFACT_TYPE_NAME_MAXLEN
+        or ARTIFACT_TYPE_NAME_INVALID_CHARS.intersection(name)
+        for name in artifact_types_list
     ):
+        invalid_repr = ", ".join(sorted(map(repr, ARTIFACT_TYPE_NAME_INVALID_CHARS)))
         raise ValueError(
-            f"""Artifact types must not contain any of the following characters: {", ".join(invalid_chars)}
-              and must be less than equal to 128 characters"""
+            f"Artifact types must not contain any of the following characters: {invalid_repr}"
+            f"and must be less than or equal to {ARTIFACT_TYPE_NAME_MAXLEN!r} characters"
         )
-    return artifact_types
+    return artifact_types_list
 
 
 TAG_REGEX: re.Pattern[str] = re.compile(r"^[-\w]+( +[-\w]+)*$")
 """Regex pattern for valid tag names."""
 
 
-def validate_tags(tags: Collection[str] | str) -> list[str]:
+def validate_tags(tags: Iterable[str] | str) -> list[str]:
     """Validate the artifact tag names and return them as a deduped list.
 
     In the case of duplicates, only keep the first tag, and otherwise maintain the order of appearance.
@@ -204,7 +222,7 @@ def validate_artifact_type(typ: str, name: str) -> str:
     return typ
 
 
-def validate_metadata(metadata: dict[str, Any] | None) -> dict[str, Any]:
+def validate_metadata(metadata: dict[str, Any] | str | None) -> dict[str, Any]:
     """Validate the artifact metadata and return it as a dict."""
     if metadata is None:
         return {}