simulo 0.24.1__tar.gz → 0.26.0__tar.gz

{simulo-0.24.1/src/simulo.egg-info → simulo-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.24.1
+Version: 0.26.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
@@ -71,6 +71,10 @@ required — `simulo create` only writes files to your local folder. Edit
 `app.py` for your own robot and task, then see "Log in and submit" below to
 run it.
 
+To download a curated collection of runnable projects, use `simulo install samples`.
+It creates `./simulo-samples` as a normal Git clone, so `cd simulo-samples` and
+`cat README.md` open the sample index.
+
 ### Or write an app by hand
 
 ```python

{simulo-0.24.1 → simulo-0.26.0}/PYPI.md

@@ -31,6 +31,10 @@ required — `simulo create` only writes files to your local folder. Edit
 `app.py` for your own robot and task, then see "Log in and submit" below to
 run it.
 
+To download a curated collection of runnable projects, use `simulo install samples`.
+It creates `./simulo-samples` as a normal Git clone, so `cd simulo-samples` and
+`cat README.md` open the sample index.
+
 ### Or write an app by hand
 
 ```python

{simulo-0.24.1 → simulo-0.26.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.24.1"
+version = "0.26.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.24.1 → simulo-0.26.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.24.1 → simulo-0.26.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.24.1 → simulo-0.26.0}/src/simulo/_client/cli.py

@@ -53,6 +53,18 @@ the packaged ``src/`` layout and never reaches a real ``pip install simulo``
 user. No network call, no auth — this only touches the local filesystem and the
 wheel's own bundled resources.
 
+``simulo install samples`` clones the public sample collection into
+``./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``.
@@ -182,6 +194,7 @@ 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.jobs_api import JobsApiClient, JobsApiError, JobsApiHTTPError, JobsApiUnavailable
 from simulo._client.login import LoginError, perform_login
 from simulo._client.mode import DISCOVERY
@@ -209,6 +222,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,
@@ -6977,6 +6991,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
@@ -8008,7 +8093,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
@@ -8260,6 +8345,38 @@ def _build_parser() -> argparse.ArgumentParser:
 
     create.set_defaults(func=_handle_create)
 
+    install = sub.add_parser("install", help="Install a curated local collection of Simulo samples.")
+    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.",
+    )
+
+    def _handle_install_samples(args: argparse.Namespace, extras: Sequence[str]) -> int:
+        if extras:
+            samples.error(f"unrecognized arguments: {' '.join(extras)}")
+        try:
+            installed = install_samples(Path.cwd())
+        except InstallSamplesUsageError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            print("Nothing was installed.", file=sys.stderr)
+            return 2
+        except InstallSamplesError as exc:
+            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)."
+        )
+        print("Next steps:")
+        print("  cd simulo-samples")
+        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
+
+    samples.set_defaults(func=_handle_install_samples)
+
     # -- simulo asset (the FIRST nested subcommand group in this CLI) --------
     asset = sub.add_parser(
         "asset",
@@ -8720,6 +8837,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.26.0/src/simulo/_client/install_samples.py

@@ -0,0 +1,267 @@
+"""Install the public Simulo sample collection with a normal Git clone."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+SAMPLES_REPOSITORY_URL = "https://github.com/simulo-org/simulo-samples.git"
+DEFAULT_SAMPLES_DIRECTORY_NAME = "simulo-samples"
+CLONE_TIMEOUT_S = 300
+_MAX_GIT_STDERR_INPUT_BYTES = 4096
+_MAX_GIT_STDERR_RENDERED_BYTES = 4096
+_GIT_OUTPUT_PREFIX = "  | git: "
+_GIT_PROGRESS_PREFIXES = (
+    "Cloning into ",
+    "Receiving objects:",
+    "Resolving deltas:",
+    "remote: Enumerating objects:",
+    "remote: Counting objects:",
+    "remote: Compressing objects:",
+    "remote: Total ",
+)
+
+
+class InstallSamplesError(RuntimeError):
+    """Raised when the samples cannot be installed."""
+
+
+class InstallSamplesUsageError(ValueError):
+    """Raised when the requested install destination is unsafe to use."""
+
+
+@dataclass(frozen=True)
+class InstalledSamples:
+    """The local sample collection created by :func:`install_samples`."""
+
+    path: Path
+
+
+def _git_environment() -> dict[str, str]:
+    """Return a non-interactive environment for a public clone."""
+    environment = dict(os.environ)
+    for key in tuple(environment):
+        if any(fragment in key.upper() for fragment in ("TOKEN", "SECRET", "CREDENTIAL")):
+            environment.pop(key)
+    environment.pop("GIT_CONFIG_PARAMETERS", None)
+    environment.update(
+        {
+            "GIT_TERMINAL_PROMPT": "0",
+            "GIT_ASKPASS": "",
+            "GCM_INTERACTIVE": "never",
+            "GIT_CONFIG_COUNT": "1",
+            "GIT_CONFIG_KEY_0": "credential.helper",
+            "GIT_CONFIG_VALUE_0": "",
+        }
+    )
+    return environment
+
+
+def _run_git(argv: list[str], *, timeout_s: int, env: dict[str, str]) -> subprocess.CompletedProcess[str]:
+    """Run Git through the one seam tests replace."""
+    return subprocess.run(argv, capture_output=True, check=False, env=env, text=True, timeout=timeout_s)
+
+
+def _stderr_tail(stderr: str | bytes | None) -> str:
+    if isinstance(stderr, bytes):
+        stderr = stderr.decode(errors="replace")
+    if not stderr:
+        return ""
+    encoded = stderr.encode("utf-8", errors="replace")
+    bounded_bytes = encoded[-_MAX_GIT_STDERR_INPUT_BYTES:]
+    was_truncated = len(bounded_bytes) < len(encoded)
+    bounded = bounded_bytes.decode("utf-8", errors="replace")
+    lines = bounded.splitlines()
+    starts_mid_line = was_truncated and encoded[-_MAX_GIT_STDERR_INPUT_BYTES - 1] not in (ord("\n"), ord("\r"))
+    if starts_mid_line and len(lines) > 1:
+        lines = lines[1:]
+    non_progress_lines = [line for line in lines if not line.startswith(_GIT_PROGRESS_PREFIXES)]
+    return _quote_git_output(non_progress_lines[-10:])
+
+
+def _quote_git_output(lines: list[str]) -> str:
+    """Prefix Git output without exceeding the CLI's rendered stderr bound."""
+    output: list[str] = []
+    output_bytes = 0
+    prefix_bytes = len(_GIT_OUTPUT_PREFIX.encode("utf-8"))
+    for line in reversed(lines):
+        printable_line = "".join(character for character in line if character.isprintable())
+        quoted_line = f"{_GIT_OUTPUT_PREFIX}{printable_line}"
+        quoted_line_bytes = len(quoted_line.encode("utf-8", errors="replace"))
+        separator_bytes = 1 if output else 0
+        if output_bytes + separator_bytes + quoted_line_bytes <= _MAX_GIT_STDERR_RENDERED_BYTES:
+            output.insert(0, quoted_line)
+            output_bytes += separator_bytes + quoted_line_bytes
+        elif not output:
+            available_line_bytes = _MAX_GIT_STDERR_RENDERED_BYTES - prefix_bytes
+            output.append(
+                _GIT_OUTPUT_PREFIX
+                + printable_line.encode("utf-8", errors="replace")[-available_line_bytes:].decode(errors="ignore")
+            )
+            break
+        else:
+            break
+    return "\n".join(output)
+
+
+def _remove_read_only_path(function: object, path: str, _exc_info: object) -> None:
+    """Make Windows Git object files writable, then retry rmtree's operation."""
+    # Known and owned Windows residual: this misses directory junctions, which Python 3.11 rmtree can follow; staging
+    # access follows inherited ACLs.
+    if not os.path.islink(path):
+        os.chmod(path, 0o700)
+    function(path)  # type: ignore[operator]
+
+
+def _directory_identity(path: Path) -> tuple[int, int]:
+    status = path.stat()
+    return status.st_dev, status.st_ino
+
+
+def _remove_staging_directory(staging: Path, identity: tuple[int, int]) -> None:
+    try:
+        current_identity = _directory_identity(staging)
+    except FileNotFoundError:
+        return
+    except OSError:
+        print(f"warning: could not inspect partial samples install at {staging}", file=sys.stderr)
+        return
+    if current_identity != identity:
+        print(f"warning: partial samples install path no longer belongs to this invocation: {staging}", file=sys.stderr)
+        return
+    try:
+        shutil.rmtree(staging, onerror=_remove_read_only_path)
+    except OSError:
+        print(f"warning: could not remove partial samples install at {staging}", file=sys.stderr)
+
+
+def _clone_failure(
+    reason: str, stderr: str | bytes | None, *, explain_public_repository: bool = False
+) -> InstallSamplesError:
+    tail = _stderr_tail(stderr)
+    explanation = (
+        "The samples repository is public and this command does not sign in.\n"
+        "An authentication error means Git could not reach the repository or its host, not that there is a problem "
+        "with your account."
+    )
+    message = f"{reason}\n{tail}" if tail else reason
+    if explain_public_repository:
+        message = f"{message}\n{explanation}"
+    return InstallSamplesError(message)
+
+
+def _target_exists_error(target: Path) -> InstallSamplesUsageError:
+    if not target.is_dir():
+        return InstallSamplesUsageError(f"{target} exists and is not a directory.")
+    return InstallSamplesUsageError(f"{target} already exists.")
+
+
+def _git_is_reachable_through_working_directory(
+    named_git_path: Path, git_executable: Path, working_directory: Path
+) -> bool:
+    """Return whether resolving Git depends on the current working directory."""
+    return not named_git_path.is_absolute() or working_directory in {
+        named_git_path.parent,
+        named_git_path.parent.resolve(),
+        git_executable.parent,
+    }
+
+
+def _clone_has_sample_files(staging: Path) -> bool:
+    """Return whether a successful clone produced a user-visible worktree entry.
+
+    An unreadable staging directory counts as no sample files. This is the only
+    filesystem read on the success path, and letting an OSError escape here would
+    abandon the staging directory and break the promise that a failed install
+    leaves nothing behind.
+    """
+    try:
+        return any(entry.name != ".git" for entry in staging.iterdir())
+    except OSError:
+        return False
+
+
+def install_samples(
+    parent_directory: Path,
+    *,
+    repository_url: str = SAMPLES_REPOSITORY_URL,
+    directory_name: str = DEFAULT_SAMPLES_DIRECTORY_NAME,
+    timeout_s: int = CLONE_TIMEOUT_S,
+) -> InstalledSamples:
+    """Clone samples into *parent_directory* and reveal them atomically."""
+    target = parent_directory / directory_name
+    if target.exists():
+        raise _target_exists_error(target)
+
+    git_path = shutil.which("git")
+    if git_path is None:
+        raise InstallSamplesError(
+            "Git is required to install samples. Get it from https://git-scm.com/downloads and try again."
+        )
+    named_git_path = Path(git_path)
+    working_directory = Path.cwd().resolve()
+    git_executable = named_git_path.resolve()
+    if _git_is_reachable_through_working_directory(named_git_path, git_executable, working_directory):
+        raise InstallSamplesError(
+            f"Refusing resolved Git executable {git_executable}: its PATH entry is relative to or resolves through "
+            "the current working directory. Run this command from a different directory, or use a Git executable "
+            "outside the working directory."
+        )
+
+    staging = parent_directory / f".{directory_name}.partial-{os.getpid()}"
+    try:
+        staging.mkdir()
+    except FileExistsError:
+        raise InstallSamplesError(f"Partial samples install path already exists: {staging}.") from None
+    except OSError as exc:
+        reason = exc.strerror or str(exc)
+        raise InstallSamplesError(f"Could not prepare samples install at {staging}: {reason}.") from None
+    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)]
+    try:
+        completed = _run_git(argv, timeout_s=timeout_s, env=_git_environment())
+    except subprocess.TimeoutExpired as exc:
+        _remove_staging_directory(staging, staging_identity)
+        raise _clone_failure(
+            f"Git clone timed out after {timeout_s} seconds. "
+            f"If your connection needs longer, clone it by hand with git clone {repository_url}.",
+            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 start Git clone: {reason}.") from None
+
+    if completed.returncode != 0:
+        _remove_staging_directory(staging, staging_identity)
+        raise _clone_failure(
+            f"Git clone failed with exit code {completed.returncode}.",
+            completed.stderr,
+            explain_public_repository=True,
+        )
+
+    if 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():
+        _remove_staging_directory(staging, staging_identity)
+        raise _target_exists_error(target)
+
+    try:
+        os.rename(staging, target)
+    except OSError as exc:
+        _remove_staging_directory(staging, staging_identity)
+        reason = exc.strerror or str(exc)
+        raise InstallSamplesError(f"Could not finish installing samples: {reason}.") from None
+
+    return InstalledSamples(path=target.resolve())

{simulo-0.24.1 → simulo-0.26.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.24.1 → simulo-0.26.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.24.1 → simulo-0.26.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.24.1 → simulo-0.26.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.24.1 → simulo-0.26.0/src/simulo.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.24.1
+Version: 0.26.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
@@ -71,6 +71,10 @@ required — `simulo create` only writes files to your local folder. Edit
 `app.py` for your own robot and task, then see "Log in and submit" below to
 run it.
 
+To download a curated collection of runnable projects, use `simulo install samples`.
+It creates `./simulo-samples` as a normal Git clone, so `cd simulo-samples` and
+`cat README.md` open the sample index.
+
 ### Or write an app by hand
 
 ```python

{simulo-0.24.1 → simulo-0.26.0}/src/simulo.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ src/simulo/_client/export_bundle.py
 src/simulo/_client/facades.py
 src/simulo/_client/http.py
 src/simulo/_client/identity_api.py
+src/simulo/_client/install_samples.py
 src/simulo/_client/jobs_api.py
 src/simulo/_client/learning.py
 src/simulo/_client/login.py

{simulo-0.24.1 → simulo-0.26.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