agentenv-framework 0.9.1254__py3-none-any.whl

agent_env/artifact/artifacts/environment.py

@@ -0,0 +1,89 @@
+"""Environment artifact for wrapping a FileArtifact with environment identity."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Literal, Optional
+
+from pydantic import ConfigDict, Field, model_serializer
+
+from agent_env.artifact.artifact import Artifact
+from agent_env.artifact.ref import ArtifactRef
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from agent_env.artifact.artifacts.file import FileArtifact
+
+
+class EnvironmentArtifact(Artifact):
+    """A FileArtifact wrapped with the name of the environment it seeds."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    type: Literal["environment"] = "environment"
+    environment_name: str = Field(alias="service_name", description="Name of the environment this artifact belongs to")
+    file_artifact_ref: Optional[ArtifactRef] = Field(
+        default=None,
+        description="Pinned (id, version) ref to the wrapped FileArtifact",
+    )
+    # Pre-pinning docs only; alias keeps the on-disk key as `file_artifact_id`.
+    legacy_file_artifact_id: Optional[str] = Field(
+        default=None,
+        alias="file_artifact_id",
+        description="Legacy unpinned wrapped-FileArtifact id",
+    )
+
+    @model_serializer(mode="wrap")
+    def _serialize(self, handler: Any) -> dict[str, Any]:
+        # `@model_serializer(mode="wrap")` is the only hook invoked by both
+        # `model_dump` and the Rust-implemented `model_dump_json`.
+        data = handler(self)
+        if "legacy_file_artifact_id" in data:
+            data["file_artifact_id"] = data.pop("legacy_file_artifact_id")
+        if self.file_artifact_ref is not None:  # new doc
+            data.pop("file_artifact_id", None)
+        # Dual-write. Sourced from the attribute, not from `data`,
+        # because `alias=` emits exactly one spelling and which one depends on the
+        # caller's `by_alias` — the store persists with by_alias=True
+        # (artifact/store.py), while in-process callers dump either way.
+        data["service_name"] = self.environment_name
+        data["environment_name"] = self.environment_name
+        return data
+
+    @classmethod
+    def put(
+        cls,
+        id: str,
+        *,
+        environment_name: Optional[str] = None,
+        file_artifact: FileArtifact,
+    ) -> EnvironmentArtifact:
+        from agent_env.artifact.store import get_artifact_store
+
+        if not environment_name:
+            raise ValueError("environment_name cannot be empty")
+        instance = cls(
+            id=id,
+            environment_name=environment_name,
+            file_artifact_ref=file_artifact.as_ref(),
+        )
+        return get_artifact_store().put_document(instance)
+
+    def get_file_artifact(self) -> FileArtifact:
+        from agent_env.artifact.artifacts.file import FileArtifact
+
+        if self.file_artifact_ref is not None:
+            return FileArtifact.get(
+                self.file_artifact_ref.id, version=self.file_artifact_ref.version
+            )
+        if self.legacy_file_artifact_id is not None:
+            logger.warning(
+                "EnvironmentArtifact %s v%s has unpinned file_artifact_id; falling back to latest. Republish to pin.",
+                self.id, self.version,
+            )
+            return FileArtifact.get(self.legacy_file_artifact_id)
+        raise ValueError(
+            f"malformed EnvironmentArtifact {self.id} v{self.version}: "
+            "neither file_artifact_ref nor file_artifact_id present"
+        )

agent_env/artifact/artifacts/environment_universe.py

@@ -0,0 +1,156 @@
+"""Environment universe artifact for bundling related environment artifacts together."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Literal, Optional
+
+from pydantic import AliasChoices, ConfigDict, Field, model_serializer
+
+from agent_env.artifact.ref import ArtifactRef
+from agent_env.artifact.universe import Universe
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from agent_env.artifact.artifacts.file import FileArtifact
+    from agent_env.artifact.artifacts.environment import EnvironmentArtifact
+
+
+class EnvironmentUniverseArtifact(Universe):
+    """A universe artifact that bundles EnvironmentArtifacts together."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    type: Literal["environment_universe"] = "environment_universe"
+    # serialization_alias pins the emitted key: the attribute is renamed, the document is not.
+    environment_artifact_refs: Optional[list[ArtifactRef]] = Field(
+        default=None,
+        serialization_alias="service_artifact_refs",
+        validation_alias=AliasChoices("service_artifact_refs", "environment_artifact_refs"),
+        description="List of pinned (id, version) refs to EnvironmentArtifacts",
+    )
+    metadata_refs: Optional[dict[str, ArtifactRef]] = Field(
+        default=None,
+        description="Optional pinned (id, version) refs to metadata FileArtifacts",
+    )
+    # Pre-pinning docs only; aliases keep on-disk keys as `service_artifact_ids` / `metadata`.
+    legacy_environment_artifact_ids: Optional[list[str]] = Field(
+        default=None,
+        alias="service_artifact_ids",
+        description="Legacy unpinned EnvironmentArtifact ids",
+    )
+    legacy_metadata: Optional[dict[str, str]] = Field(
+        default=None,
+        alias="metadata",
+        description="Legacy unpinned metadata FileArtifact ids",
+    )
+
+    @model_serializer(mode="wrap")
+    def _serialize(self, handler: Any) -> dict[str, Any]:
+        # `@model_serializer(mode="wrap")` is the only hook invoked by both
+        # `model_dump` and the Rust-implemented `model_dump_json`.
+        data = handler(self)
+        if "legacy_environment_artifact_ids" in data:
+            data["service_artifact_ids"] = data.pop("legacy_environment_artifact_ids")
+        if "legacy_metadata" in data:
+            data["metadata"] = data.pop("legacy_metadata")
+        if self.environment_artifact_refs is not None:  # new doc
+            data.pop("service_artifact_ids", None)
+            data.pop("metadata", None)
+            # Dual-write: the pinned refs get a twin, and only them.
+            # The scope line also asked for a `service_artifact_ids` twin on these
+            # modern docs — declined. That key means "unpinned, resolve at latest"
+            # to every reader, and v0.9.1 (pinned permanently by
+            # synthetic-artifacts-pipeline) acts on it, so writing it onto a doc
+            # that IS pinned tells that worker to ignore the pins. Nothing legacy
+            # is dropped here: unpinned docs never reach this branch and still
+            # round-trip `service_artifact_ids` / `metadata` above, and
+            # get_environment_artifacts still falls back to them.
+            # `by_alias=False` dumps under the field name, `by_alias=True` under the
+            # serialization alias; emit both keys either way, as this always has.
+            refs = data.pop("environment_artifact_refs", None)
+            if refs is None:
+                refs = data["service_artifact_refs"]
+            data["service_artifact_refs"] = refs
+            data["environment_artifact_refs"] = refs
+        return data
+
+    @classmethod
+    def put(
+        cls,
+        id: str,
+        *,
+        environment_artifacts: list[EnvironmentArtifact],
+        metadata: Optional[dict[str, FileArtifact]] = None,
+    ) -> EnvironmentUniverseArtifact:
+        from agent_env.artifact.store import get_artifact_store
+
+        if not environment_artifacts:
+            raise ValueError("environment_artifacts must be non-empty")
+        instance = cls(
+            id=id,
+            environment_artifact_refs=[ea.as_ref() for ea in environment_artifacts],
+            metadata_refs=(
+                {k: fa.as_ref() for k, fa in metadata.items()} if metadata else None
+            ),
+        )
+        return get_artifact_store().put_document(instance)
+
+    def get_environment_artifacts(self) -> list[EnvironmentArtifact]:
+        from agent_env.artifact.artifacts.environment import EnvironmentArtifact
+
+        if self.environment_artifact_refs is not None:
+            return [
+                EnvironmentArtifact.get(ref.id, version=ref.version)
+                for ref in self.environment_artifact_refs
+            ]
+        if self.legacy_environment_artifact_ids:
+            logger.warning(
+                "EnvironmentUniverseArtifact %s v%s has unpinned service_artifact_ids; falling back to latest. Republish to pin.",
+                self.id, self.version,
+            )
+            return [
+                EnvironmentArtifact.get(sa_id) for sa_id in self.legacy_environment_artifact_ids
+            ]
+        raise ValueError(
+            f"malformed EnvironmentUniverseArtifact {self.id} v{self.version}: "
+            "neither service_artifact_refs nor service_artifact_ids present"
+        )
+
+    def get_file_artifacts(self) -> dict[str, FileArtifact]:
+        """``{relative filename: FileArtifact}`` — a plain-file view of this universe.
+
+        Matching ``FileArtifactUniverse.get_file_artifacts()`` is what lets the same
+        loaders stage a service universe as a file tree (grading a frozen snapshot)
+        rather than restoring it into an env. Returns the pinned artifacts as-is —
+        nothing is copied or re-registered.
+        """
+        out: dict[str, FileArtifact] = {}
+        for sa in self.get_environment_artifacts():
+            fa = sa.get_file_artifact()
+            name = f"{sa.environment_name}/{fa.filename}"
+            if name in out:
+                raise ValueError(
+                    f"EnvironmentUniverseArtifact {self.id} v{self.version} has duplicate "
+                    f"environment '{sa.environment_name}'; cannot stage it as a file tree"
+                )
+            out[name] = fa
+        return out
+
+    def get_metadata(self) -> dict[str, FileArtifact]:
+        from agent_env.artifact.artifacts.file import FileArtifact
+
+        if self.metadata_refs:
+            return {
+                k: FileArtifact.get(ref.id, version=ref.version)
+                for k, ref in self.metadata_refs.items()
+            }
+        if self.legacy_metadata:
+            logger.warning(
+                "EnvironmentUniverseArtifact %s v%s has unpinned metadata; falling back to latest. Republish to pin.",
+                self.id, self.version,
+            )
+            return {k: FileArtifact.get(fa_id) for k, fa_id in self.legacy_metadata.items()}
+        # Metadata is optional; absence is not a malformed doc (unlike service refs).
+        return {}

agent_env/artifact/artifacts/file.py

@@ -0,0 +1,214 @@
+"""Generic file artifact for storing arbitrary files in S3."""
+
+from __future__ import annotations
+
+import mimetypes
+import os
+from typing import TYPE_CHECKING, ClassVar, Literal, Self
+
+from pydantic import Field
+
+from agent_env.artifact.artifact import Artifact
+from agent_env.config import get_config
+
+if TYPE_CHECKING:
+    from agent_env.bundle.authoring import AuthoringContext
+
+
+class FileArtifact(Artifact):
+    """A generic file artifact that stores any file in S3.
+
+    Clients define their own schemas and upload files (JSON, images, etc.).
+    When loaded, returns raw bytes for the client to parse as needed.
+
+    Example:
+        # Create a file artifact
+        artifact = FileArtifact.put(
+            id="customer_data",
+            description="Customer email data in JSON format",
+            file_path="/path/to/emails.json",
+        )
+
+        # Load the file bytes
+        data = artifact.load()
+        emails = json.loads(data)  # Client parses as needed
+    """
+
+    toml_keys: ClassVar[dict[str, type]] = {"description": str}  # what an artifact.toml may set
+    type: Literal["file"] = "file"
+    description: str = Field(description="Human-readable description of the artifact contents")
+    filename: str = Field(description="Original filename (preserved for reference)")
+    content_type: str = Field(description="MIME type of the file")
+    object_url: str = Field(alias="s3_url", description="Object-store locator where the file is stored")
+
+    @classmethod
+    def put(
+        cls,
+        id: str,
+        *,
+        description: str,
+        file_path: str,
+    ) -> Self:
+        from agent_env.artifact.store import get_artifact_store
+
+        store = get_artifact_store()
+
+        filename = os.path.basename(file_path)
+        content_type, _ = mimetypes.guess_type(file_path)
+        if content_type is None:
+            content_type = "application/octet-stream"
+
+        version = store.next_version(id)
+
+        # Use put_object_file (boto3 managed multipart upload) instead of
+        # put_object (s3.put_object — hard 5 GB single-object limit). Streams
+        # directly from disk so large files don't get loaded into RAM either.
+        s3_url = store.put_object_file(
+            artifact_type="file",
+            id=id,
+            version=version,
+            object_name=filename,
+            file_path=file_path,
+            content_type=content_type,
+        )
+
+        # Store artifact document in MongoDB
+        instance = cls(
+            id=id,
+            version=version,
+            description=description,
+            filename=filename,
+            content_type=content_type,
+            s3_url=s3_url,
+        )
+        return store.put_document(instance)
+
+    @classmethod
+    def put_bytes(
+        cls,
+        id: str,
+        *,
+        description: str,
+        filename: str,
+        content: bytes,
+        content_type: str = "application/octet-stream",
+    ) -> Self:
+        """Like ``put``, but takes raw bytes instead of a file path."""
+        from agent_env.artifact.store import get_artifact_store
+
+        store = get_artifact_store()
+        version = store.next_version(id)
+
+        s3_url = store.put_object(
+            artifact_type="file",
+            id=id,
+            version=version,
+            object_name=filename,
+            data=content,
+            content_type=content_type,
+        )
+
+        instance = cls(
+            id=id,
+            version=version,
+            description=description,
+            filename=filename,
+            content_type=content_type,
+            s3_url=s3_url,
+        )
+        return store.put_document(instance)
+
+    @classmethod
+    def from_toml(cls, data: dict, ctx: AuthoringContext) -> Self:
+        """Write the folder's one file under a prefix of its own (``ArtifactStore.attempt_prefix``);
+        ``description`` defaults to the file's name."""
+        from agent_env.artifact.store import get_artifact_store
+
+        fields = ctx.accept(data, **cls.toml_keys)
+        filename, path = ctx.file()
+        prefix = get_artifact_store().attempt_prefix(cls.model_fields["type"].default, ctx.id)
+        return cls.put_at(ctx.id, description=fields.get("description", filename), file_path=str(path),
+                          object_url=prefix + filename, filename=filename)
+
+    def load(self) -> bytes:
+        from agent_env.artifact.store import get_artifact_store
+
+        return get_artifact_store().get_object(self.object_url)
+
+    def get_file_artifacts(self) -> dict[str, "FileArtifact"]:
+        return {self.filename: self}
+
+    @classmethod
+    def put_at(
+        cls,
+        id: str,
+        *,
+        description: str,
+        file_path: str,
+        object_url: str,
+        filename: str | None = None,
+    ) -> Self:
+        """Upload ``file_path`` to an explicit object_url (write-once) and register it."""
+        from agent_env.artifact.store import get_artifact_store
+
+        store = get_config().get_object_store_to_write(object_url, id)
+
+        if filename is None:
+            filename = os.path.basename(file_path)
+        content_type, _ = mimetypes.guess_type(file_path)
+        if content_type is None:
+            content_type = "application/octet-stream"
+
+        artifact_store = get_artifact_store()
+        version = artifact_store.next_version(id)
+        stored_url = store.put_file_at(object_url, file_path, content_type)
+        instance = cls(
+            id=id,
+            version=version,
+            description=description,
+            filename=filename,
+            content_type=content_type,
+            s3_url=stored_url,
+        )
+        return artifact_store.put_document(instance)
+
+    @classmethod
+    def put_existing(
+        cls,
+        id: str,
+        *,
+        description: str,
+        object_url: str,
+    ) -> Self:
+        """Register an already-uploaded object as a FileArtifact.
+
+        Unlike ``put`` and ``put_at``, this does NOT upload bytes; it asserts
+        the object exists and records artifact metadata. Use when the file was
+        already written by some other process (e.g. an agent's snapshot
+        extension) and you want to wrap it without round-tripping through disk.
+        """
+        from agent_env.artifact.store import get_artifact_store
+
+        store = get_config().get_object_store_to_write(object_url, id)
+        location = object_url.partition("://")[2] or object_url
+        if "/" not in location or location.endswith("/"):
+            raise ValueError(f"object_url must point at an object, not a prefix: {object_url!r}")
+        metadata = store.get_object_metadata_at(object_url)
+        if metadata is None:
+            raise ValueError(f"Object does not exist at {object_url!r}")
+
+        # The last segment, not urlparse's path, which ends at a "#" or "?" that keys may hold.
+        filename = object_url.rsplit("/", 1)[-1]
+        content_type = metadata.content_type or mimetypes.guess_type(filename)[0] or "application/octet-stream"
+
+        artifact_store = get_artifact_store()
+        version = artifact_store.next_version(id)
+        instance = cls(
+            id=id,
+            version=version,
+            description=description,
+            filename=filename,
+            content_type=content_type,
+            s3_url=object_url,
+        )
+        return artifact_store.put_document(instance)

agent_env/artifact/artifacts/file_artifact_universe.py

@@ -0,0 +1,206 @@
+"""FileArtifactUniverse — bundles FileArtifacts produced by collect_artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar, Literal, Optional
+
+from pydantic import Field
+
+from agent_env.artifact.ref import ArtifactRef
+from agent_env.artifact.universe import Universe
+from agent_env.config import get_config
+from agent_env.store.ids import derive_id
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from agent_env.artifact.artifacts.file import FileArtifact
+    from agent_env.bundle.authoring import AuthoringContext
+
+
+class FileArtifactUniverse(Universe):
+    """A universe that bundles FileArtifacts together.
+
+    Typically auto-created by the ``collect_artifacts`` task step, which
+    turns each collected file into a ``FileArtifact`` and wraps them in one
+    of these universes. The universe preserves the original filename of
+    each file so downstream browsers can display them without needing to
+    load every ``FileArtifact`` document.
+    """
+
+    toml_keys: ClassVar[dict[str, type]] = {}  # what an artifact.toml may set
+    type: Literal["file_artifact_universe"] = "file_artifact_universe"
+    file_artifact_refs: Optional[dict[str, ArtifactRef]] = Field(
+        default=None,
+        description=(
+            "Mapping of original filename -> pinned (id, version) ref to its "
+            "FileArtifact. Preferred over file_artifact_ids on read; absence "
+            "means a pre-pinning doc that resolves to latest."
+        ),
+    )
+    # Kept alongside file_artifact_refs (additive) so raw-doc readers and CLI
+    # attribute access keep working; new docs carry both keys.
+    file_artifact_ids: dict[str, str] = Field(
+        default_factory=dict,
+        description=(
+            "Mapping of original filename -> FileArtifact id. The filename "
+            "is a denormalized convenience for fast catalog rendering "
+            "(avoiding N FileArtifact lookups per card); canonical file "
+            "metadata lives on the referenced FileArtifact document."
+        ),
+    )
+    bundle_object_url: str | None = Field(
+        default=None,
+        alias="bundle_s3_url",
+        description=(
+            "Optional object-store prefix under which all bundled files "
+            "reside. Set when the universe represents a contiguous directory "
+            "(e.g. an agent snapshot). Consumers can use this directly without "
+            "resolving individual FileArtifact documents."
+        ),
+    )
+
+    @classmethod
+    def put(
+        cls,
+        id: str,
+        *,
+        file_artifacts: dict[str, "FileArtifact"],
+        bundle_s3_url: str | None = None,
+    ) -> "FileArtifactUniverse":
+        from agent_env.artifact.store import get_artifact_store
+
+        if not file_artifacts:
+            raise ValueError("file_artifacts must be non-empty")
+        if bundle_s3_url:
+            get_config().check_object_url(id, bundle_s3_url)
+
+        store = get_artifact_store()
+        version = store.next_version(id)
+        instance = cls(
+            id=id,
+            version=version,
+            file_artifact_refs={
+                fname: fa.as_ref() for fname, fa in file_artifacts.items()
+            },
+            file_artifact_ids={fname: fa.id for fname, fa in file_artifacts.items()},
+            bundle_s3_url=bundle_s3_url,
+        )
+        return store.put_document(instance)
+
+    def get_file_artifacts(self) -> dict[str, "FileArtifact"]:
+        """Resolve each referenced FileArtifact. Returns {filename: FileArtifact}."""
+        from agent_env.artifact.artifacts.file import FileArtifact
+
+        # Truthiness (not `is not None`): a degenerate empty-`{}` refs dict
+        # (never produced by put(), only by a hand-crafted/migrated doc) falls
+        # through to the ids fallback instead of silently returning zero files.
+        # Also keeps this consistent with the hub download branch, which guards
+        # on `doc.get("file_artifact_refs")`.
+        if self.file_artifact_refs:
+            return {
+                fname: FileArtifact.get(ref.id, version=ref.version)
+                for fname, ref in self.file_artifact_refs.items()
+            }
+        if self.file_artifact_ids:
+            logger.warning(
+                "FileArtifactUniverse %s v%s has unpinned file_artifact_ids; "
+                "falling back to latest. Republish to pin.",
+                self.id,
+                self.version,
+            )
+            return {
+                fname: FileArtifact.get(fa_id)
+                for fname, fa_id in self.file_artifact_ids.items()
+            }
+        raise ValueError(
+            f"malformed FileArtifactUniverse {self.id} v{self.version}: "
+            "neither file_artifact_refs nor file_artifact_ids present"
+        )
+
+    @classmethod
+    def put_bundled(
+        cls,
+        id: str,
+        *,
+        files: dict[str, Path],
+        s3_url: str | None = None,
+    ) -> "FileArtifactUniverse":
+        """Upload ``files`` (bundle key -> local path) under ``s3_url`` and register them as one universe.
+        Without ``s3_url``, each call writes under a prefix of its own (``ArtifactStore.attempt_prefix``)."""
+        from agent_env.artifact.artifacts.file import FileArtifact
+        from agent_env.artifact.store import get_artifact_store
+
+        if not files:
+            raise ValueError("files must be non-empty")
+        if s3_url is None:
+            s3_url = get_artifact_store().attempt_prefix(cls.model_fields["type"].default, id)
+        if not s3_url.endswith("/"):
+            s3_url += "/"
+
+        file_artifacts: dict[str, FileArtifact] = {}
+        for rel_path, local_path in files.items():
+            if rel_path.startswith("/"):
+                raise ValueError(f"Bundle key {rel_path!r} must be a relative path")
+            if ".." in rel_path.split("/"):
+                raise ValueError(f"Bundle key {rel_path!r} must not contain '..' segments")
+            path_hash = hashlib.sha256(rel_path.encode("utf-8")).hexdigest()[:16]
+            fa = FileArtifact.put_at(
+                id=derive_id(id, path_hash),
+                description=f"Bundled file '{rel_path}' of FileArtifactUniverse '{id}'",
+                file_path=str(local_path),
+                object_url=s3_url + rel_path,
+                filename=rel_path.rsplit("/", 1)[-1],
+            )
+            file_artifacts[rel_path] = fa
+
+        return cls.put(id=id, file_artifacts=file_artifacts, bundle_s3_url=s3_url)
+
+    @classmethod
+    def from_toml(cls, data: dict, ctx: AuthoringContext) -> "FileArtifactUniverse":
+        """Write the folder's files, each a file artifact keyed by its path in the folder."""
+        ctx.accept(data, **cls.toml_keys)
+        return cls.put_bundled(ctx.id, files=ctx.files())
+
+    @classmethod
+    def put_existing(
+        cls,
+        id: str,
+        *,
+        s3_url: str,
+    ) -> "FileArtifactUniverse":
+        """Wrap files that already exist under an object-store prefix as a universe.
+
+        Unlike ``put_bundled`` (which uploads local files), this lists the
+        objects already present under *s3_url* and registers each one as a
+        ``FileArtifact`` via ``FileArtifact.put_existing``. No bytes are
+        downloaded or re-uploaded. Useful when another process (e.g. an
+        agent's snapshot extension) has already written the files.
+        """
+        from agent_env.artifact.artifacts.file import FileArtifact
+
+        if not s3_url.endswith("/"):
+            s3_url += "/"
+
+        store = get_config().get_object_store_at(s3_url)
+
+        file_artifacts: dict[str, FileArtifact] = {}
+        for object_url in store.list_at(s3_url):
+            rel_path = object_url[len(s3_url):]
+            if not rel_path:
+                continue
+            path_hash = hashlib.sha256(rel_path.encode("utf-8")).hexdigest()[:16]
+            fa = FileArtifact.put_existing(
+                id=derive_id(id, path_hash),
+                description=f"Bundled file '{rel_path}' of FileArtifactUniverse '{id}'",
+                object_url=object_url,
+            )
+            file_artifacts[rel_path] = fa
+
+        if not file_artifacts:
+            raise ValueError(f"No files found under prefix {s3_url!r}")
+
+        return cls.put(id=id, file_artifacts=file_artifacts, bundle_s3_url=s3_url)