Storage — bulk upload & download

pip install "minerva-sdk[storage]"

from minerva import Minerva

mc = Minerva()  # MINERVA_API_KEY from env

# Upload — defaults to Incoming/
mc.storage.upload("data/customers.csv")
# → Incoming/customers.csv

mc.storage.upload("data/customers.csv", remote_name="batch-001.csv")
# → Incoming/batch-001.csv

mc.storage.upload("data/customers.csv", subdir="2026-06-29")
# → Incoming/2026-06-29/customers.csv

# Download — defaults to Outgoing/
mc.storage.download("results.csv")
# → ./results.csv

mc.storage.download("sub/inner.csv", local_path="out/inner.csv")
# → ./out/inner.csv  (creates parent dirs)

# Delete — defaults to Outgoing/. Pass direction="incoming" to clean up your own uploads.
mc.storage.delete("results.csv")
mc.storage.delete("batch-001.csv", direction="incoming")

for obj in mc.storage.list():           # Outgoing/ by default
    print(obj.key, obj.size, obj.last_modified)

for obj in mc.storage.list(subdir="2026-06"):
    ...

# Many files at once
mc.storage.upload_many(["a.csv", "b.csv", "c.csv"])

# Whole directory tree, relative paths preserved
mc.storage.upload_directory("./batch-2026-06-29")
# Sends ./batch-2026-06-29/x.csv     → Incoming/x.csv
# Sends ./batch-2026-06-29/sub/y.csv → Incoming/sub/y.csv

mc.storage.upload_directory("./day", subdir="2026-06-29")
# → Incoming/2026-06-29/...

# Pull a batch by keys (typically the output of list())
mc.storage.download_many(
    ["results-1.csv", "sub/inner.csv"],
    local_dir="./out",
)

# List, then download everything — single call
mc.storage.download_all(local_dir="./out")

creds = mc.storage.get_credentials()
print(creds.bucket_name, creds.prefix, creds.aws_session_expiration)
# Secrets (aws_secret_access_key, aws_session_token) are hidden from repr
# but accessible by attribute.

from minerva import (
    MinervaStorageError,
    MinervaStorageObjectNotFoundError,
    MinervaStorageAccessDeniedError,
    MinervaStorageTransferError,
)

try:
    mc.storage.download("missing.csv")
except MinervaStorageObjectNotFoundError as e:
    print(f"no such key: {e.key}")
except MinervaStorageError:
    raise