simready-retrieve
Download a SimReady asset from cloud storage and get back the local path to its main USD file. Retrieve can also convert the asset to a target profile and validate the result before it hands the path back.
A workflow guide, a full CLI reference, and a full Python API reference ship
inside the package, under docs/.
Installation
Retrieve needs Python 3.12 or newer. On an older interpreter, pip refuses to resolve it.
pip install simready-retrieve
Internal builds are published to the NVIDIA artifactory, so append
--extra-index-url https://artifactory.nvidia.com/artifactory/api/pypi/ct-omniverse-pypi-local/simple.
To convert an asset to a profile, also install the tier package that defines
that profile, such as simready-foundation-tier-core. Retrieve resolves
profiles from the tiers you have installed.
This wheel also ships simready-derive: the simready.derive module and the
simready-derive command. Derive is not released on its own. If you already
have a standalone simready-derive wheel, uninstall it first, because both
install the same files.
Asset URIs
Retrieve picks the storage backend from the URI scheme. You never choose one.
| URI | Storage |
|---|---|
hf://<org>/<repo>/<asset>[@<commit>] |
Hugging Face |
https://huggingface.co/datasets/<org>/<repo>/... |
Hugging Face |
omniverse://<host>/<folder-or-usd> |
Nucleus |
omniverse://<host>/assets/by-name/<name> |
OmniStorage |
s3://<bucket>/<prefix> |
Public S3 bucket |
omni:// works anywhere omniverse:// does. An AWS S3 HTTPS URL works
anywhere s3:// does. Nucleus and OmniStorage need omni.client, which is
installed for you. OmniStorage also needs SIMREADY_OMNI_DISCOVERY_URL set to
your discovery endpoint.
Retrieve first looks for a bill of materials at
.metadata/com.nvidia.simready.packaging.bom.json and downloads only the files
it lists. If the asset has no BOM, Retrieve downloads the whole folder instead.
Only a confirmed missing BOM triggers that fallback: a BOM that exists but
cannot be read is an error. com.nvidia.simready.packaging.json, when present,
names the primary USD.
These two paths are exported as BOM_PATH and PACKAGING_NAME if you need to
build or inspect an asset yourself.
Quick start
fetch downloads an asset and returns the local path of its main USD file. It
is a coroutine, so await it.
import asyncio
from simready.retrieve import fetch
HF_URL = "hf://my-org/my-repo/crate_01"
async def main():
# Download only.
path = await fetch(HF_URL)
# Download, convert to a profile, and validate the result.
derived = await fetch(HF_URL, "Target-Profile@1.0.0")
# Reuse an earlier conversion when the request matches.
cached = await fetch(
HF_URL,
"Target-Profile@1.0.0",
derive_cache_path="/tmp/simready-derive-cache",
)
return path, derived, cached
asyncio.run(main())
Fetch into a workspace
fetch_into_workspace downloads the asset, then adds it to a
simready-package workspace and installs it. Use this when you are building a
pipeline instead of grabbing a single file. It needs a pinned source: either
hf://...@<commit> or a <version>.wkspc URL. A Hugging Face branch name is
resolved to its commit for you.
from simready.retrieve import fetch_into_workspace
result = await fetch_into_workspace(HF_URL, "/path/to/workspace")
result.primary_usd # local path to the main USD file
result.derived_usd # converted USD, or None if you passed no profile
result.install_path # where the package was installed
result.package_source # "workspace" if it was already there, else "network"
result.derive_status # None, "derived", "cache_hit", or "already_derived"
CLI
simready-retrieve fetch <ASSET_URI>
simready-retrieve -v fetch <ASSET_URI> \
--profile Target-Profile@1.0.0 \
--derive-cache-path /tmp/simready-derive-cache
fetch prints the resolved path to stdout and sends everything else to stderr,
so you can capture the path on its own.
| Flag | Purpose |
|---|---|
--profile PROFILE@VERSION |
Convert to an installed profile and validate it |
--derive-cache-path DIR |
Reuse earlier conversions from this directory |
--workspace DIR |
Install into a simready-package workspace |
--hf-token TOKEN |
Hugging Face token; overrides HF_TOKEN and the cached login |
--no-browser |
Print the OmniStorage sign-in URL instead of opening a browser |
-v, --verbose |
Debug logging |
Run simready-retrieve auth-clear to delete the cached OmniStorage token.
OpenUSD and Kit
Profiles need OpenUSD (pxr) in the same Python process that calls Retrieve.
That is still true when KIT_EXE is set, because Kit runs the conversion but
does not give pxr to your process. If nothing else on your system provides
OpenUSD, install simready-retrieve[usd]. Do not combine usd-core with USD
Exchange.
Conversions run in process through the usd-ingest DirectPipelineBackend. Set
KIT_EXE to a kit.sh or kit.exe to run them in Kit instead.
In-process conversions also need the usd-ingest resolver stack: usdex,
usd_optimize, and omni_usd_resolver. Install simready-retrieve[deps] to
add them. Skip that extra when KIT_EXE is set, because Kit supplies them.
Metadata
Release files for simready-retrieve 2026.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| simready_retrieve-2026.10.0-py3-none-any.whl | Python 3 | none | any | Details for simready_retrieve-2026.10.0-py3-none-any.whl |
Release files / simready_retrieve-2026.10.0-py3-none-any.whl
| Download URL | simready_retrieve-2026.10.0-py3-none-any.whl |
|---|---|
| Size | 117.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cfd33d8cd90a2e968444080022cc6ee251be754d067a2af704666d609520fddc
|
|
BLAKE2b-256 checksum How to use checksums |
aa947c113d80808a9eed8f9064e81192987d6f6ef8eeba8179a0968a7f93f107
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Security for simready-retrieve 2026.10.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.