simulo 0.25.0__tar.gz → 0.27.0__tar.gz

{simulo-0.25.0/src/simulo.egg-info → simulo-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.25.0
+Version: 0.27.0
 Summary: Simulo SDK and CLI — define robotics simulation and training apps in Python and run them on the Simulo cloud.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: simulo-interfaces<0.19,>=0.18.0
+Requires-Dist: simulo-interfaces<0.20,>=0.19.0
 Requires-Dist: mcap<2,>=1.3
 Requires-Dist: defusedxml>=0.7.1
 Requires-Dist: usd-core<27,>=26.5
@@ -75,6 +75,19 @@ To download a curated collection of runnable projects, use `simulo install sampl
 It creates `./simulo-samples` as a normal Git clone, so `cd simulo-samples` and
 `cat README.md` open the sample index.
 
+Choose a destination with `--directory` and a Git branch, tag, or commit with
+`--ref`. You can use either option on its own or combine them:
+
+```bash
+simulo install samples --directory robotics-examples --ref main
+cd robotics-examples
+```
+
+The destination must not exist, and its parent directory must already exist.
+The directory appears only after the clone and requested checkout succeed.
+Use a tag or full commit ID instead of `main` to select a fixed revision.
+With `--ref`, the checkout is detached at the selected commit.
+
 ### Or write an app by hand
 
 ```python

{simulo-0.25.0 → simulo-0.27.0}/PYPI.md

@@ -35,6 +35,19 @@ To download a curated collection of runnable projects, use `simulo install sampl
 It creates `./simulo-samples` as a normal Git clone, so `cd simulo-samples` and
 `cat README.md` open the sample index.
 
+Choose a destination with `--directory` and a Git branch, tag, or commit with
+`--ref`. You can use either option on its own or combine them:
+
+```bash
+simulo install samples --directory robotics-examples --ref main
+cd robotics-examples
+```
+
+The destination must not exist, and its parent directory must already exist.
+The directory appears only after the clone and requested checkout succeed.
+Use a tag or full commit ID instead of `main` to select a fixed revision.
+With `--ref`, the checkout is detached at the selected commit.
+
 ### Or write an app by hand
 
 ```python

{simulo-0.25.0 → simulo-0.27.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.25.0"
+version = "0.27.0"
 description = "Simulo SDK and CLI — define robotics simulation and training apps in Python and run them on the Simulo cloud."
 readme = "PYPI.md"
 requires-python = ">=3.11"
@@ -26,7 +26,7 @@ classifiers = [
 # mcap: used by `simulo recordings` to read back a downloaded recording and
 # verify it (message count) — MIT-licensed, deps only lz4+zstandard.
 dependencies = [
-    "simulo-interfaces>=0.18.0,<0.19",
+    "simulo-interfaces>=0.19.0,<0.20",
     "mcap>=1.3,<2",
     # Hardened XML parsing for URDF ingestion (USD Asset Catalogs, PR-12 fix
     # loop 2, security NIT): stdlib xml.etree.ElementTree relies on

{simulo-0.25.0 → simulo-0.27.0}/src/simulo/__init__.py

@@ -29,10 +29,10 @@ missed that way before the rule replaced it.
 Three kinds of name live on ``simulo``:
 
 * **Platform** names — ``App / Runtime / Volume / Asset / Output /
-  OutputKind / callbacks`` — are **real, eager** attributes bound below.
-  They are always torch-free (``Output`` is the ``simulo-interfaces``
-  contract dataclass, ``OutputKind`` its wire-stable ``StrEnum``, both
-  re-exported).
+  OutputKind / SystemType / callbacks`` — are **real, eager** attributes bound
+  below. They are always torch-free (``Output`` is the ``simulo-interfaces``
+  contract dataclass, ``OutputKind`` and ``SystemType`` its wire-stable
+  ``StrEnum``\\ s, all three re-exported).
 * **Contract vocabulary** — the shared error hierarchy (``SimuloError`` and its
   subclasses), the ``NewType`` identifier aliases (``JobId``, ``ProjectId``, …),
   and the authoring value types that are not already carried by the lazy
@@ -152,7 +152,7 @@ from simulo.interfaces.authoring import (
     USDWorld,
     VisualMarkerBase,
 )
-from simulo.interfaces.platform import Output, OutputKind
+from simulo.interfaces.platform import Output, OutputKind, SystemType
 
 # Public surface = eager platform exports (real attributes; ``__getattr__`` never
 # fires for these) + the lazily-resolved learning names. Kept a static literal so
@@ -162,6 +162,7 @@ __all__ = [
     "App",
     "Output",
     "OutputKind",
+    "SystemType",
     "Runtime",
     "Volume",
     "Asset",

{simulo-0.25.0 → simulo-0.27.0}/src/simulo/_client/app.py

@@ -41,7 +41,8 @@ from simulo._client.runtime import DEFAULT_RUNTIME
 from simulo.interfaces.ids import JobId, parse_job_public_id
 from simulo.interfaces.platform import JobCallbackProtocol
 from simulo.interfaces.platform.app import Mount
-from simulo.interfaces.platform.enums import ResumePolicy
+from simulo.interfaces.platform.enums import ResumePolicy, SystemType
+from simulo.interfaces.platform.systems import SYSTEM_SPECS
 
 if TYPE_CHECKING:  # typing-only; avoids a module-scope dependency on the HTTP client
     from simulo._client.preflight_api import PreflightOutcome
@@ -427,6 +428,14 @@ def _spawn_cloud(
     content-addressed identity must never change based on whether this
     particular execution asked for a live stream.
 
+    The requested GPU system tier (system-tier-catalog-1362, M50-persistence)
+    is NOT a parameter here — it is read from the already-parsed manifest's
+    ``jobs[job_name]["resources"]["system"]`` (the wire value
+    ``@app.job(system=...)`` already validated and recorded at decoration
+    time) and forwarded to ``create_job`` below as an optional top-level
+    sibling of ``args``, for the identical package-hash-invariance reason as
+    ``viewstream``.
+
     ``seed_from`` (``simulo run --from``, explicit-run-intent plan) follows
     the identical rule: the seed reference is a SUBMIT-time job property,
     never a package property — it rides the job-create call only, verbatim
@@ -496,6 +505,15 @@ def _spawn_cloud(
     package_id = str(package_id)
     source_digest = str(manifest.get("source_digest", ""))
     args = dict(manifest.get("args") or {})
+    # The requested GPU system tier (system-tier-catalog-1362, M50-persistence)
+    # — already validated at `@app.job(system=...)` decoration time and
+    # recorded on THIS job's own manifest entry as `resources["system"]`
+    # (the tier's wire value, e.g. "tier1"; see `decorate()`'s
+    # `resources["system"] = system.value`). Read from the already-parsed
+    # manifest rather than threaded in as a new parameter, since the value
+    # already lives there, keyed by this same `job_name`.
+    job_entry = manifest.get("jobs", {}).get(job_name) or {}
+    system = (job_entry.get("resources") or {}).get("system")
 
     tar_path = ensure_tar(package_path)
     archive_bytes = tar_path.read_bytes()
@@ -549,6 +567,7 @@ def _spawn_cloud(
         seed_from_job_id=seed_from,
         assets=asset_pins,
         app_name=app_name,
+        system=system,
     )
 
     raw_public_id = record.get("public_id")
@@ -970,7 +989,7 @@ class App:
 
         app = simulo.App("cartpole")
 
-        @app.job(gpu="A10G")
+        @app.job(system=simulo.SystemType.TIER_1)
         def train(iterations: int = 1000):
             ...
 
@@ -1044,7 +1063,7 @@ class App:
         *,
         callbacks: Sequence[JobCallbackProtocol] = ...,
         resume: ResumePolicy = ...,
-        gpu: Optional[str] = ...,
+        system: Optional[SystemType] = ...,
         timeout: Optional[int] = ...,
         retries: int = ...,
         **extra: Any,
@@ -1056,14 +1075,15 @@ class App:
         *,
         callbacks: Sequence[JobCallbackProtocol] = (),
         resume: ResumePolicy = ResumePolicy.AUTO,
-        gpu: Optional[str] = None,
+        system: Optional[SystemType] = None,
         timeout: Optional[int] = None,
         retries: int = 0,
         **extra: Any,
     ) -> Union[JobFunction, Callable[[F], JobFunction]]:
         """Register a function as a job of this app. Records metadata; never runs the body.
 
-        Usable bare (``@app.job``) or with options (``@app.job(gpu="A10G")``).
+        Usable bare (``@app.job``) or with options
+        (``@app.job(system=simulo.SystemType.TIER_1)``).
         Returns a :class:`JobFunction` wrapping the original function — calling
         it still runs the body in-process; ``.spawn()`` / ``.submit()`` submit it
         to the platform instead.
@@ -1077,8 +1097,17 @@ class App:
             resume: How the job resumes from a discovered checkpoint
                 (:class:`~simulo.interfaces.platform.enums.ResumePolicy`,
                 default ``AUTO``).
-            gpu: GPU resource request (e.g. ``"A10G"``), recorded in the job's
-                resource spec.
+            system: The GPU system tier to request, as a
+                :class:`simulo.SystemType` member (e.g.
+                ``simulo.SystemType.TIER_1``), recorded in the job's resource
+                spec as ``resources["system"]`` (the tier's wire value, e.g.
+                ``"tier1"``). Validated HERE, at decoration time, against the
+                published catalog: a value that is not a ``SystemType`` member
+                (a raw string such as ``"tier1"`` included) raises
+                ``TypeError``, and a tier the platform cannot provision yet
+                raises ``ValueError``. ``simulo systems`` lists every tier and
+                which are available today. The selection is recorded on the
+                job; it does not yet choose hardware.
             timeout: Wall-clock limit for one managed execution, in seconds
                 (a positive integer; validated HERE, at decoration time — a
                 zero, negative, or non-integer value raises ``ValueError``
@@ -1094,13 +1123,15 @@ class App:
             retries: Automatic re-attempts after a failure (default 0). All
                 attempts share one ``timeout`` budget.
             **extra: Additional resource requests, recorded verbatim in the
-                job's resource spec. Two names are RESERVED and rejected —
-                ``produces`` and ``consumes`` (see Raises below); everything
-                else passes through to the resource spec unchanged.
+                job's resource spec. Three names are RESERVED and rejected —
+                ``produces``, ``consumes`` and ``gpu`` (see Raises below);
+                everything else passes through to the resource spec unchanged.
 
         Raises:
             ValueError: ``timeout`` is not ``None`` and is not a positive
                 integer. ``True`` and ``False`` are not accepted as timeouts.
+                Also raised when ``system`` names a tier the platform cannot
+                provision yet (``SYSTEM_SPECS[system].available`` is false).
             TypeError: ``produces=`` or ``consumes=`` was passed. Outputs are
                 not declared on the decorator. Callbacks such as
                 ``ResumableCheckpoint`` already declare their supported
@@ -1108,6 +1139,11 @@ class App:
                 volume for files another job needs. ``consumes=`` is reserved;
                 continue from a checkpoint with
                 ``simulo run --from <job>[:latest|:best]`` instead.
+                Also raised for ``gpu=`` (the free-text GPU request this
+                parameter replaced; it would otherwise fall through
+                ``**extra`` into the resource spec unvalidated) and for a
+                ``system`` value that is not a :class:`simulo.SystemType`
+                member.
         """
         if timeout is not None and (isinstance(timeout, bool) or not isinstance(timeout, int) or timeout < 1):
             raise ValueError(
@@ -1127,11 +1163,44 @@ class App:
                 "today. To chain jobs, run with `simulo run --from <job>[:latest|:best]`. Remove "
                 "consumes=."
             )
+        # ``gpu`` was a real named parameter until the system-tier catalog
+        # replaced it (#1362). Removing it from the signature alone does NOT
+        # reject ``gpu="L4"``: CPython routes the unknown keyword into
+        # ``**extra`` and it would land in the resource spec exactly as before,
+        # unvalidated. This guard is what makes the rename a rejection.
+        if "gpu" in extra:
+            raise TypeError(
+                "@app.job(gpu=...) is no longer supported. Request a GPU system tier instead: "
+                "@app.job(system=simulo.SystemType.TIER_1). Run `simulo systems` to list the "
+                "tiers and which are available today. Remove gpu=."
+            )
+        if system is not None:
+            # Static lookups against the published catalog — no fleet state
+            # is consulted. A raw string is refused even when it spells a
+            # valid wire value, so the one accepted spelling is the enum.
+            if not isinstance(system, SystemType):
+                raise TypeError(
+                    "@app.job(system=...) must be a simulo.SystemType member, e.g. "
+                    f"system=simulo.SystemType.TIER_1; got {system!r}. Run `simulo systems` to "
+                    "list the tiers."
+                )
+            spec = SYSTEM_SPECS[system]
+            if not spec.available:
+                available = ", ".join(
+                    f"SystemType.{tier.name} ({entry.gpu_model})"
+                    for tier, entry in SYSTEM_SPECS.items()
+                    if entry.available
+                )
+                raise ValueError(
+                    f"@app.job(system=SystemType.{system.name}) ({spec.gpu_model}) is not available on "
+                    f"the platform yet. Available today: {available}. Run `simulo systems` for the "
+                    "full catalog."
+                )
 
         def decorate(func: F) -> JobFunction:
             resources: dict[str, Any] = {}
-            if gpu is not None:
-                resources["gpu"] = gpu
+            if system is not None:
+                resources["system"] = system.value
             resources.update(extra)
             spec = JobSpec(
                 name=func.__name__,

{simulo-0.25.0 → simulo-0.27.0}/src/simulo/_client/cli.py

@@ -57,6 +57,14 @@ wheel's own bundled resources.
 ``./simulo-samples`` with normal Git history. It uses neither client settings nor
 saved sign-in state; a failed clone is removed before it can appear at that path.
 
+``simulo systems [--json]`` lists the published GPU system tiers (``SystemType`` /
+``SYSTEM_SPECS`` from ``simulo-interfaces``) that ``@app.job(system=...)`` accepts —
+table or ``--json``. This reads only that static, in-package catalog: no client
+construction, no credential resolution, no network call. Today's fleet is one shared
+machine, so the listing is descriptive rather than a live capability check — the
+tier a job requests is recorded on the job, not scheduled against, and the table's
+own footer says so.
+
 **Auth** (``simulo login`` / ``logout`` / ``whoami``) drives the OAuth 2.0 +
 PKCE loopback flow and manages
 ``~/.simulo/credentials``.
@@ -123,6 +131,7 @@ import json
 import math
 import os
 import re
+import shlex
 import shutil
 import socket
 import sys
@@ -186,7 +195,12 @@ from simulo._client.discovery import discover, import_app_module
 from simulo._client.export_api import DEFAULT_EXPORT_FORMAT, ExportApiClient, ExportApiError
 from simulo._client.export_bundle import PolicyBundleError, extract_policy_bundle
 from simulo._client.identity_api import IdentityApiClient, IdentityApiError
-from simulo._client.install_samples import InstallSamplesError, InstallSamplesUsageError, install_samples
+from simulo._client.install_samples import (
+    DEFAULT_SAMPLES_DIRECTORY_NAME,
+    InstallSamplesError,
+    InstallSamplesUsageError,
+    install_samples,
+)
 from simulo._client.jobs_api import JobsApiClient, JobsApiError, JobsApiHTTPError, JobsApiUnavailable
 from simulo._client.login import LoginError, perform_login
 from simulo._client.mode import DISCOVERY
@@ -214,6 +228,7 @@ from simulo.interfaces.ids import (
     parse_output_public_id,
     parse_recording_public_id,
 )
+from simulo.interfaces.platform import SYSTEM_SPECS, SystemType
 from simulo.interfaces.platform.asset_catalog import (
     ASSET_ARCHIVE_TOO_LARGE_CODE,
     ASSET_KINDS,
@@ -6982,6 +6997,77 @@ def _print_table(headers: tuple[str, ...], rows: Sequence[tuple[str, ...]]) -> N
         print("  ".join(cell.ljust(width) for cell, width in zip(line, widths)).rstrip())
 
 
+#: One line, plain language, no jargon: forecloses the exact misreading issue
+#: #1512 documents in the wild (the samples repository's "no GPU requested"
+#: silently being read as "schedules faster" — untrue on a single-fleet
+#: platform). A numbered tier ladder invites the identical misreading in the
+#: other direction — "higher tier, faster/better scheduling" — for
+#: ``system=SystemType.TIER_4``, so this explicitly rules out BOTH readings,
+#: not just states the record-only fact and hopes the reader draws the right
+#: conclusion. Printed by the table view only: ``--json`` is a machine
+#: contract and never carries prose.
+_SYSTEMS_FOOTER = (
+    "Your `system=` choice is recorded on the job. It does not select your hardware today: "
+    "no tier schedules faster or trains better than another, and neither does leaving "
+    "`system=` out entirely."
+)
+
+
+def _system_tier_label(system: SystemType) -> str:
+    """The human-facing tier label for the table view, e.g. ``SystemType.TIER_1`` ->
+    ``"Tier 1 (tier1)"``. The parenthesized wire value is the exact string
+    ``system=`` accepts (what ``--json`` prints under the ``"system"`` key);
+    the table would otherwise show a reader nothing they could type."""
+    return f"{system.name.replace('_', ' ').title()} ({system.value})"
+
+
+def _cmd_systems(args: argparse.Namespace) -> int:
+    """``simulo systems [--json]`` — list the published GPU system tiers.
+
+    Reads only the static, in-package ``SYSTEM_SPECS`` catalog from
+    ``simulo-interfaces``: no client construction, no credential resolution,
+    no network call of any kind. Always lists all four tiers, including the
+    two not yet available — the point is to show what exists and what the
+    fleet can provision TODAY, not to hide the rest.
+
+    The raw AWS SKU behind a tier never appears in either output — the whole
+    reason this catalog names abstract tiers instead of a hardware SKU (see
+    ``SystemSpec``'s own docstring for the field that stays off every
+    user-facing surface, including this one).
+    """
+    if args.json:
+        records = [
+            {
+                "system": system.value,
+                "gpu_model": spec.gpu_model,
+                "vram_gb": spec.vram_gb,
+                "vcpu": spec.vcpu,
+                "memory_gb": spec.memory_gb,
+                "max_parallel_envs": spec.max_parallel_envs,
+                "available": spec.available,
+            }
+            for system, spec in SYSTEM_SPECS.items()
+        ]
+        print(json.dumps(records, indent=2))
+        return 0
+
+    rows = [
+        (
+            _system_tier_label(system),
+            spec.gpu_model,
+            f"{spec.vram_gb} GB",
+            str(spec.vcpu),
+            f"{spec.memory_gb} GB",
+            str(spec.max_parallel_envs) if spec.max_parallel_envs is not None else "not yet measured",
+            "available" if spec.available else "not yet available",
+        )
+        for system, spec in SYSTEM_SPECS.items()
+    ]
+    _print_table(("TIER", "GPU MODEL", "VRAM", "VCPU", "MEMORY", "MAX PARALLEL ENVS", "STATUS"), rows)
+    print(_SYSTEMS_FOOTER)
+    return 0
+
+
 #: The frozen local-development cache root for ``simulo asset get``:
 #: ``~/.simulo/assets/<org>/<kind>/<name>/v<N>/`` — colon-free segments,
 #: NTFS-safe. Mirrors ``credentials.CREDENTIALS_PATH``'s
@@ -8013,7 +8099,7 @@ def _build_parser() -> argparse.ArgumentParser:
         prog="simulo",
         description=(
             "Simulo thin client — submit an app to the Simulo cloud and observe its runs "
-            "(simulo jobs / logs / result / recordings / models / outputs / export / view / cancel)."
+            "(simulo systems / jobs / logs / result / recordings / models / outputs / export / view / cancel)."
         ),
     )
     # ``action="version"`` fires (prints + exits 0) while argparse is still
@@ -8269,14 +8355,33 @@ def _build_parser() -> argparse.ArgumentParser:
     install_sub = install.add_subparsers(dest="install_command", required=True)
     samples = install_sub.add_parser(
         "samples",
-        help="Clone the sample collection into ./simulo-samples with full Git history.",
+        help="Clone the sample collection into ./simulo-samples by default with full Git history.",
+    )
+    samples.add_argument(
+        "--directory",
+        metavar="PATH",
+        type=Path,
+        help="Install into PATH instead of ./simulo-samples. PATH's parent directory must already exist.",
+    )
+    samples.add_argument(
+        "--ref",
+        metavar="REF",
+        help="Check out Git branch, tag, or commit REF after cloning.",
     )
 
     def _handle_install_samples(args: argparse.Namespace, extras: Sequence[str]) -> int:
         if extras:
             samples.error(f"unrecognized arguments: {' '.join(extras)}")
+        directory = args.directory
+        if directory is None:
+            parent_directory = Path.cwd()
+            directory_name = DEFAULT_SAMPLES_DIRECTORY_NAME
+        else:
+            target = directory if directory.is_absolute() else Path.cwd() / directory
+            parent_directory = target.parent
+            directory_name = target.name
         try:
-            installed = install_samples(Path.cwd())
+            installed = install_samples(parent_directory, directory_name=directory_name, ref=args.ref)
         except InstallSamplesUsageError as exc:
             print(f"error: {exc}", file=sys.stderr)
             print("Nothing was installed.", file=sys.stderr)
@@ -8285,12 +8390,21 @@ def _build_parser() -> argparse.ArgumentParser:
             print(f"error: {exc}", file=sys.stderr)
             print("Nothing was installed.", file=sys.stderr)
             return 1
-        print(
-            f"Installed the Simulo samples in {installed.path} "
-            "(a normal Git clone: history, branches, and git pull all work)."
-        )
+        if args.ref is None:
+            print(
+                f"Installed the Simulo samples in {installed.path} "
+                "(a normal Git clone: history, branches, and git pull all work)."
+            )
+        else:
+            print(
+                f"Installed the Simulo samples in {installed.path} "
+                f"(a normal Git clone pinned to {args.ref!r}; the checkout is detached)."
+            )
         print("Next steps:")
-        print("  cd simulo-samples")
+        if directory is None:
+            print("  cd simulo-samples")
+        else:
+            print(f"  cd {shlex.quote(str(installed.path))}")
         print("  cat README.md")
         print("README.md is the sample index; each sample folder has its own app.py to run with simulo run.")
         return 0
@@ -8757,6 +8871,20 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     models.set_defaults(func=_observe_handler(models, _cmd_models))
 
+    systems = sub.add_parser(
+        "systems",
+        help=(
+            "List the published GPU system tiers `@app.job(system=...)` accepts — table or "
+            "--json. Reads only the in-package catalog: no network call."
+        ),
+    )
+    systems.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the tier catalog as a JSON array instead of a table (automation-friendly).",
+    )
+    systems.set_defaults(func=_observe_handler(systems, _cmd_systems))
+
     # `simulo export` — one command, no arguments, on the happy path. Every
     # option below overrides a default that was already correct (#654): the
     # latest job, its best checkpoint, ONNX, download, unpack. A new REQUIRED

{simulo-0.25.0 → simulo-0.27.0}/src/simulo/_client/http.py

@@ -48,7 +48,7 @@ class HttpError(RuntimeError):
 
 
 class HttpUnavailable(HttpError):
-    """The endpoint cannot be reached at all (nothing listening / DNS failure)."""
+    """The endpoint is unreachable or its response times out."""
 
 
 class HttpHTTPError(HttpError):
@@ -373,6 +373,8 @@ def request_bytes(
         raise _structured_http_error(exc) from exc
     except urllib.error.URLError as exc:
         raise HttpUnavailable(_unavailable_message(url, unavailable_hint, exc.reason)) from exc
+    except TimeoutError as exc:
+        raise HttpUnavailable(_unavailable_message(url, unavailable_hint, exc)) from exc
 
 
 def request_json(

{simulo-0.25.0 → simulo-0.27.0}/src/simulo/_client/install_samples.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import os
+import re
 import shutil
 import subprocess
 import sys
@@ -134,6 +135,8 @@ def _remove_staging_directory(staging: Path, identity: tuple[int, int]) -> None:
         print(f"warning: partial samples install path no longer belongs to this invocation: {staging}", file=sys.stderr)
         return
     try:
+        if not os.path.islink(staging):
+            os.chmod(staging, 0o700)
         shutil.rmtree(staging, onerror=_remove_read_only_path)
     except OSError:
         print(f"warning: could not remove partial samples install at {staging}", file=sys.stderr)
@@ -160,6 +163,11 @@ def _target_exists_error(target: Path) -> InstallSamplesUsageError:
     return InstallSamplesUsageError(f"{target} already exists.")
 
 
+def _path_exists(path: Path) -> bool:
+    """Return whether *path* exists, including a dangling symbolic link."""
+    return os.path.lexists(path)
+
+
 def _git_is_reachable_through_working_directory(
     named_git_path: Path, git_executable: Path, working_directory: Path
 ) -> bool:
@@ -190,11 +198,14 @@ def install_samples(
     *,
     repository_url: str = SAMPLES_REPOSITORY_URL,
     directory_name: str = DEFAULT_SAMPLES_DIRECTORY_NAME,
+    ref: str | None = None,
     timeout_s: int = CLONE_TIMEOUT_S,
 ) -> InstalledSamples:
     """Clone samples into *parent_directory* and reveal them atomically."""
     target = parent_directory / directory_name
-    if target.exists():
+    if not parent_directory.is_dir():
+        raise InstallSamplesUsageError(f"Parent directory {parent_directory} does not exist or is not a directory.")
+    if _path_exists(target):
         raise _target_exists_error(target)
 
     git_path = shutil.which("git")
@@ -223,7 +234,10 @@ def install_samples(
     staging_identity = _directory_identity(staging)
 
     print("Cloning the samples with full history; this can take a minute.", file=sys.stderr)
-    argv = [str(git_executable), "clone", "--", repository_url, str(staging)]
+    argv = [str(git_executable), "clone"]
+    if ref is not None:
+        argv.append("--no-checkout")
+    argv.extend(["--", repository_url, str(staging)])
     try:
         completed = _run_git(argv, timeout_s=timeout_s, env=_git_environment())
     except subprocess.TimeoutExpired as exc:
@@ -249,11 +263,131 @@ def install_samples(
             explain_public_repository=True,
         )
 
-    if not _clone_has_sample_files(staging):
+    if ref is None and not _clone_has_sample_files(staging):
         _remove_staging_directory(staging, staging_identity)
         raise _clone_failure("Git clone produced an empty working tree.", completed.stderr)
 
-    if target.exists():
+    if ref is not None:
+        try:
+            resolved = _run_git(
+                [
+                    str(git_executable),
+                    "-C",
+                    str(staging),
+                    "rev-parse",
+                    "--verify",
+                    "--end-of-options",
+                    f"{ref}^{{commit}}",
+                ],
+                timeout_s=timeout_s,
+                env=_git_environment(),
+            )
+        except subprocess.TimeoutExpired as exc:
+            _remove_staging_directory(staging, staging_identity)
+            raise _clone_failure(f"Git could not resolve samples reference {ref!r}: timed out.", exc.stderr) from None
+        except KeyboardInterrupt:
+            _remove_staging_directory(staging, staging_identity)
+            raise
+        except OSError as exc:
+            _remove_staging_directory(staging, staging_identity)
+            reason = exc.strerror or str(exc)
+            raise InstallSamplesError(f"Could not resolve samples reference {ref!r}: {reason}.") from None
+        if resolved.returncode != 0:
+            try:
+                resolved = _run_git(
+                    [
+                        str(git_executable),
+                        "-C",
+                        str(staging),
+                        "rev-parse",
+                        "--verify",
+                        "--end-of-options",
+                        f"refs/remotes/origin/{ref}^{{commit}}",
+                    ],
+                    timeout_s=timeout_s,
+                    env=_git_environment(),
+                )
+            except subprocess.TimeoutExpired as exc:
+                _remove_staging_directory(staging, staging_identity)
+                raise _clone_failure(
+                    f"Git could not resolve samples reference {ref!r}: timed out.", exc.stderr
+                ) from None
+            except KeyboardInterrupt:
+                _remove_staging_directory(staging, staging_identity)
+                raise
+            except OSError as exc:
+                _remove_staging_directory(staging, staging_identity)
+                reason = exc.strerror or str(exc)
+                raise InstallSamplesError(f"Could not resolve samples reference {ref!r}: {reason}.") from None
+            if resolved.returncode != 0:
+                _remove_staging_directory(staging, staging_identity)
+                raise _clone_failure(f"Git could not resolve samples reference {ref!r}.", resolved.stderr)
+        commit = resolved.stdout.strip()
+        if re.fullmatch(r"[0-9a-fA-F]{40,64}", commit) is None:
+            _remove_staging_directory(staging, staging_identity)
+            raise InstallSamplesError(f"Git could not resolve samples reference {ref!r} to a commit.")
+
+        try:
+            checked_out = _run_git(
+                [str(git_executable), "-C", str(staging), "checkout", "--detach", commit],
+                timeout_s=timeout_s,
+                env=_git_environment(),
+            )
+        except subprocess.TimeoutExpired as exc:
+            _remove_staging_directory(staging, staging_identity)
+            raise _clone_failure(f"Git could not check out samples reference {ref!r}: timed out.", exc.stderr) from None
+        except KeyboardInterrupt:
+            _remove_staging_directory(staging, staging_identity)
+            raise
+        except OSError as exc:
+            _remove_staging_directory(staging, staging_identity)
+            reason = exc.strerror or str(exc)
+            raise InstallSamplesError(f"Could not check out samples reference {ref!r}: {reason}.") from None
+        if checked_out.returncode != 0:
+            _remove_staging_directory(staging, staging_identity)
+            raise _clone_failure(f"Git could not check out samples reference {ref!r}.", checked_out.stderr)
+        if not _clone_has_sample_files(staging):
+            _remove_staging_directory(staging, staging_identity)
+            raise _clone_failure("Git checkout produced an empty working tree.", checked_out.stderr)
+
+        try:
+            head = _run_git(
+                [str(git_executable), "-C", str(staging), "rev-parse", "--verify", "HEAD"],
+                timeout_s=timeout_s,
+                env=_git_environment(),
+            )
+            worktree = _run_git(
+                [
+                    str(git_executable),
+                    "-C",
+                    str(staging),
+                    "diff",
+                    "--quiet",
+                    commit,
+                    "--",
+                ],
+                timeout_s=timeout_s,
+                env=_git_environment(),
+            )
+        except subprocess.TimeoutExpired as exc:
+            _remove_staging_directory(staging, staging_identity)
+            raise _clone_failure(f"Git could not verify samples reference {ref!r}: timed out.", exc.stderr) from None
+        except KeyboardInterrupt:
+            _remove_staging_directory(staging, staging_identity)
+            raise
+        except OSError as exc:
+            _remove_staging_directory(staging, staging_identity)
+            reason = exc.strerror or str(exc)
+            raise InstallSamplesError(f"Could not verify samples reference {ref!r}: {reason}.") from None
+        if head.returncode != 0 or worktree.returncode not in (0, 1):
+            _remove_staging_directory(staging, staging_identity)
+            stderr = head.stderr if head.returncode != 0 else worktree.stderr
+            raise _clone_failure(f"Git could not verify samples reference {ref!r}.", stderr)
+        if head.stdout.strip().lower() != commit.lower() or worktree.returncode != 0:
+            _remove_staging_directory(staging, staging_identity)
+            raise InstallSamplesError("Git checkout did not leave the requested samples revision clean.")
+
+    if _path_exists(target):
         _remove_staging_directory(staging, staging_identity)
         raise _target_exists_error(target)
 

{simulo-0.25.0 → simulo-0.27.0}/src/simulo/_client/preflight_api.py

@@ -17,18 +17,10 @@ always returns a :class:`PreflightOutcome`, either a genuine
 for the CLI to print verbatim before proceeding. Only a genuinely
 well-formed 200 response can carry a ``blocking`` finding.
 
-The final ``except Exception`` in :meth:`PreflightApiClient.evaluate` is
-deliberate, not sloppy: measured against this codebase's own ``http.py``,
-``urllib.request.urlopen``'s connect/send-phase failures surface as
-``urllib.error.URLError`` (wrapped here as the thin client's ``HttpUnavailable``),
-but a peer that accepts the connection and then simply never answers (this
-PR's own connection-timeout test reproduces it) times out INSIDE
-``http.client.HTTPConnection.getresponse()`` — a call site ``http.py``'s
-existing ``except urllib.error.URLError`` does not wrap, so a bare
-``socket.timeout``/``TimeoutError`` can reach this call site unwrapped. The
-broad catch is the safety net for exactly that gap (and for anything else
-unanticipated) — preflight must not add a second instance of this failure class to the
-submit path.
+The shared HTTP helper wraps connection failures and response timeouts as
+``HttpUnavailable``. The final ``except Exception`` in
+:meth:`PreflightApiClient.evaluate` preserves the fail-open contract for other
+unexpected errors: only a well-formed findings response may block submission.
 """
 
 from __future__ import annotations

{simulo-0.25.0 → simulo-0.27.0}/src/simulo/_client/submit_api.py

@@ -420,6 +420,7 @@ class SubmitApiClient:
         seed_from_job_id: Optional[str] = None,
         assets: Optional[list[dict[str, str]]] = None,
         app_name: Optional[str] = None,
+        system: Optional[str] = None,
     ) -> dict[str, Any]:
         """``POST /v1/jobs`` — create the job that executes *package_id*.
 
@@ -441,6 +442,14 @@ class SubmitApiClient:
         predates the live-visualization plan's ``JobSubmitRequest`` field
         simply ignores an absent key, same as it ignores any unknown field.
 
+        ``system`` (system-tier-catalog-1362, M50-persistence) is the
+        already-validated tier wire value (e.g. ``"tier1"``) from the job's
+        own manifest ``resources["system"]`` — an OPTIONAL top-level sibling
+        of ``args`` for the same package-hash-invariance reason as
+        ``viewstream`` above. Sent only when truthy: a control plane that
+        predates this field ignores the extra key, and the run proceeds
+        exactly as it did before ``system=`` existed.
+
         ``seed_from_job_id`` (``simulo run --from``, explicit-run-intent
         plan) follows the exact same sibling-of-``args`` rule for the exact
         same package-hash reason — a seed is a property of THIS submission,
@@ -500,6 +509,8 @@ class SubmitApiClient:
             body["app_name"] = app_name
         if viewstream:
             body["viewstream"] = True
+        if system:
+            body["system"] = system
         if seed_from_job_id is not None:
             body[_SEED_FROM_JOB_ID_FIELD] = seed_from_job_id
         if assets:

{simulo-0.25.0 → simulo-0.27.0}/src/simulo/_client/templates/inference/app.py.tmpl

@@ -209,8 +209,9 @@ def _make_env(num_envs: int) -> Any:
     )
 
 
+# system= picks a GPU tier from the published catalog; run `simulo systems` to see them.
 @app.job(
-    gpu="L4",
+    system=simulo.SystemType.TIER_1,
     timeout=8 * 60 * 60,
     retries=2,
     callbacks=[simulo.callbacks.ResumableCheckpoint(every=50)],
@@ -239,7 +240,7 @@ def train(num_envs: int = 512, max_iterations: int = 20) -> dict[str, Any]:
     return {"checkpoint": checkpoint, "policy": policy_path, "num_envs": num_envs, **stats}
 
 
-@app.job(gpu="L4", timeout=2 * 60 * 60)
+@app.job(system=simulo.SystemType.TIER_1, timeout=2 * 60 * 60)
 def evaluate(num_episodes: int = 10, num_rounds: int = 5) -> dict[str, Any]:
     """Evaluate the saved checkpoint over several rounds; aggregate with numpy."""
     import json
@@ -283,7 +284,7 @@ def evaluate(num_episodes: int = 10, num_rounds: int = 5) -> dict[str, Any]:
     return {"report": report_path, **report}
 
 
-@app.job(gpu="L4", timeout=1 * 60 * 60)
+@app.job(system=simulo.SystemType.TIER_1, timeout=1 * 60 * 60)
 def rollout(num_steps: int = 200) -> dict[str, Any]:
     """Inference path: play the exported TorchScript policy and record it to MCAP.
 

{simulo-0.25.0 → simulo-0.27.0}/src/simulo/_client/templates/scenario/app.py.tmpl

@@ -64,7 +64,8 @@ class {{APP_NAME}}Scenario(simulo.Scenario):  # -> ScenarioProtocol at submit, r
 app = simulo.App("{{APP_NAME}}")
 
 
-@app.job(gpu="L4", timeout=30 * 60)
+# system= picks a GPU tier from the published catalog; run `simulo systems` to see them.
+@app.job(system=simulo.SystemType.TIER_1, timeout=30 * 60)
 def simulate(num_steps: int = 1000, num_envs: int = 4) -> dict[str, Any]:
     """Run the scenario headless on the worker. EDIT: device / step count / env count.
 

{simulo-0.25.0 → simulo-0.27.0}/src/simulo/_client/templates/training/app.py.tmpl

@@ -193,8 +193,9 @@ class {{APP_NAME}}Task(simulo.Task):
 # Retries are safe: ResumableCheckpoint declares periodic checkpoints (every 50
 # iterations) and resume defaults to "auto", so a retried / preempted run resumes
 # from the latest checkpoint instead of restarting.
+# system= picks a GPU tier from the published catalog; run `simulo systems` to see them.
 @app.job(
-    gpu="L4",
+    system=simulo.SystemType.TIER_1,
     timeout=8 * 60 * 60,
     retries=2,
     callbacks=[simulo.callbacks.ResumableCheckpoint(every=50)],

{simulo-0.25.0 → simulo-0.27.0/src/simulo.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.25.0
+Version: 0.27.0
 Summary: Simulo SDK and CLI — define robotics simulation and training apps in Python and run them on the Simulo cloud.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: simulo-interfaces<0.19,>=0.18.0
+Requires-Dist: simulo-interfaces<0.20,>=0.19.0
 Requires-Dist: mcap<2,>=1.3
 Requires-Dist: defusedxml>=0.7.1
 Requires-Dist: usd-core<27,>=26.5
@@ -75,6 +75,19 @@ To download a curated collection of runnable projects, use `simulo install sampl
 It creates `./simulo-samples` as a normal Git clone, so `cd simulo-samples` and
 `cat README.md` open the sample index.
 
+Choose a destination with `--directory` and a Git branch, tag, or commit with
+`--ref`. You can use either option on its own or combine them:
+
+```bash
+simulo install samples --directory robotics-examples --ref main
+cd robotics-examples
+```
+
+The destination must not exist, and its parent directory must already exist.
+The directory appears only after the clone and requested checkout succeed.
+Use a tag or full commit ID instead of `main` to select a fixed revision.
+With `--ref`, the checkout is detached at the selected commit.
+
 ### Or write an app by hand
 
 ```python

{simulo-0.25.0 → simulo-0.27.0}/src/simulo.egg-info/requires.txt

@@ -1,4 +1,4 @@
-simulo-interfaces<0.19,>=0.18.0
+simulo-interfaces<0.20,>=0.19.0
 mcap<2,>=1.3
 defusedxml>=0.7.1
 usd-core<27,>=26.5