Metadata-Version: 2.4
Name: simready-retrieve
Version: 2026.10.0
Summary: SimReady Asset Retrieval (OmniStorage + HuggingFace + S3) & Optimization
Author: NVIDIA Corporation
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.nvidia.com
Keywords: nvidia,simready,retrieve
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: simready.package>=2026.10.0-rc1
Requires-Dist: simready.derive>=2026.10.0-rc0
Requires-Dist: simready.validate>=2026.10.0-rc0
Requires-Dist: usd-validation-nvidia>=1.23.0
Requires-Dist: huggingface_hub>=0.23
Requires-Dist: omniverseclient
Requires-Dist: usd-ingest<0.3.0,>=0.2.1
Requires-Dist: boto3<1.40.62,>=1.40.46
Provides-Extra: usd
Requires-Dist: usd-core>=22.11; extra == "usd"
Provides-Extra: deps
Requires-Dist: usd-ingest[deps]<0.3.0,>=0.2.1; extra == "deps"
Dynamic: license-file

# 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.

```bash
pip install simready-retrieve
```

<!-- AUTOREMOVE: BEGIN -->
> 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`.
<!-- AUTOREMOVE: END -->

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.

```python
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.

```python
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

```bash
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.
