simulo 0.7.0__tar.gz → 0.8.0__tar.gz

simulo-0.8.0/MANIFEST.in

@@ -0,0 +1,9 @@
+# Public-metadata discretion boundary (see release.yml Guard 5): the sdist is
+# PUBLIC on PyPI's "Download files" page just like the wheel, but setuptools'
+# sdist command auto-includes README.md and any top-level tests/ directory
+# regardless of the `readme = "PYPI.md"` pyproject setting. Exclude the
+# internal docs and test suite explicitly so only PYPI.md ships as prose.
+exclude README.md
+exclude CLAUDE.md
+exclude CHANGELOG.md
+prune tests

simulo-0.8.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: simulo
+Version: 0.8.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
+Project-URL: Homepage, https://simulo.ai
+Keywords: robotics,simulation,reinforcement-learning,simulo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: simulo-interfaces<0.2,>=0.1
+Requires-Dist: mcap<2,>=1.3
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: isort>=5.13; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Provides-Extra: release
+Requires-Dist: commitizen>=3.27; extra == "release"
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=5.1; extra == "release"
+
+# simulo
+
+The Simulo SDK and CLI — define robotics simulation and training apps in Python,
+submit them to the Simulo cloud, monitor jobs, and retrieve trained models.
+
+Simulo is a cloud-first robotics simulation and training platform. Write your app
+against a small, stable Python API; Simulo handles running it.
+
+## Install
+
+```bash
+pip install simulo
+```
+
+Requires Python 3.11+.
+
+## Quickstart
+
+Log in once to submit to the Simulo cloud:
+
+```bash
+simulo login
+```
+
+Write an app:
+
+```python
+# app.py
+import simulo
+
+runtime = simulo.Runtime.from_registry("simulo/python-cpu:3.11")
+app = simulo.App("hello", runtime=runtime)
+
+
+@app.job(timeout=5 * 60)
+def hello(name: str = "world", repeat: int = 3) -> dict:
+    for i in range(repeat):
+        print(f"[hello] {i + 1}/{repeat}: hello, {name}!")
+    return {"greeting": f"hello, {name}", "repeat": repeat}
+
+
+@app.local_entrypoint
+def main(name: str = "world", repeat: int = 3) -> None:
+    handle = hello.spawn(name=name, repeat=repeat)
+    print(f"Submitted job: {handle.job_name}")
+```
+
+Run it:
+
+```bash
+simulo run app.py --name robot --repeat 5
+```
+
+Without logging in, `simulo run` packages the app locally without submitting it.
+
+Learn more at [simulo.ai](https://simulo.ai).

simulo-0.8.0/PYPI.md

@@ -0,0 +1,56 @@
+# simulo
+
+The Simulo SDK and CLI — define robotics simulation and training apps in Python,
+submit them to the Simulo cloud, monitor jobs, and retrieve trained models.
+
+Simulo is a cloud-first robotics simulation and training platform. Write your app
+against a small, stable Python API; Simulo handles running it.
+
+## Install
+
+```bash
+pip install simulo
+```
+
+Requires Python 3.11+.
+
+## Quickstart
+
+Log in once to submit to the Simulo cloud:
+
+```bash
+simulo login
+```
+
+Write an app:
+
+```python
+# app.py
+import simulo
+
+runtime = simulo.Runtime.from_registry("simulo/python-cpu:3.11")
+app = simulo.App("hello", runtime=runtime)
+
+
+@app.job(timeout=5 * 60)
+def hello(name: str = "world", repeat: int = 3) -> dict:
+    for i in range(repeat):
+        print(f"[hello] {i + 1}/{repeat}: hello, {name}!")
+    return {"greeting": f"hello, {name}", "repeat": repeat}
+
+
+@app.local_entrypoint
+def main(name: str = "world", repeat: int = 3) -> None:
+    handle = hello.spawn(name=name, repeat=repeat)
+    print(f"Submitted job: {handle.job_name}")
+```
+
+Run it:
+
+```bash
+simulo run app.py --name robot --repeat 5
+```
+
+Without logging in, `simulo run` packages the app locally without submitting it.
+
+Learn more at [simulo.ai](https://simulo.ai).

simulo-0.8.0/pyproject.toml

@@ -0,0 +1,100 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simulo"
+version = "0.8.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"
+license = { text = "BSD-3-Clause" }
+authors = [{ name = "Simulo Team", email = "team@simulo.ai" }]
+keywords = ["robotics", "simulation", "reinforcement-learning", "simulo"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+# Torch-free by construction: depends only on the contract layer and mcap.
+# Heavy imports (e.g. torch) belong inside the user's `runtime.imports()`
+# guard, resolved only at job-execution time — never in this distribution.
+# 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.1,<0.2", "mcap>=1.3,<2"]
+
+[project.optional-dependencies]
+dev = ["black>=24.0", "isort>=5.13", "ruff>=0.5", "mypy>=1.10", "pytest>=8.2", "build>=1.2", "twine>=5.1"]
+# `dev` carries build/twine but deliberately not commitizen; `release` below
+# adds commitizen for cutting version bumps without a second build/twine copy.
+release = ["commitizen>=3.27", "build>=1.2", "twine>=5.1"]
+
+[project.scripts]
+simulo = "simulo._client.cli:main"
+
+[project.urls]
+Homepage = "https://simulo.ai"
+
+# Namespace packaging: this is the only distribution that ships
+# `src/simulo/__init__.py`, so sibling `simulo.*` distributions can share the
+# top-level `simulo` name — do not add another top-level __init__.py to a
+# sibling distribution. `namespaces = true` keeps setuptools from choking on
+# the shared top-level name.
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+[tool.setuptools.package-data]
+"simulo" = ["py.typed"]
+
+[tool.mypy]
+python_version = "3.11"
+mypy_path = ["src"]
+namespace_packages = true
+explicit_package_bases = true
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--import-mode=importlib"
+markers = [
+    "isaac: requires NVIDIA Isaac Sim / IsaacLab (skipped on dev machines and in PR CI)",
+    "gpu: requires a CUDA GPU (skipped on dev machines and in PR CI)",
+]
+
+[tool.isort]
+profile = "black"
+line_length = 120
+known_first_party = ["simulo"]
+
+[tool.ruff]
+line-length = 120
+src = ["src"]
+
+[tool.black]
+line-length = 120
+target-version = ["py311"]
+
+# --- Commitizen ------------------------------------------------------------
+# `cz bump` creates the version-bump commit + tag locally; CI publishes to
+# PyPI on tag push. version_provider = "pep621" reads/writes [project].version
+# directly; there is no in-tree __version__ mirror to keep in sync
+# (version_files = []).
+#
+# The FIRST release (0.7.0) was a hand-written bump commit, not `cz bump` —
+# 0.1.0 -> 0.7.0 is not a conventional-commit increment. 0.7.0 (not 0.2.0) is
+# deliberate: it intentionally exceeds a version already published under this
+# same PyPI project name, so `pip install simulo` resolves to this package.
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "pep621"
+version_files = []
+tag_format = "simulo-v$version"
+update_changelog_on_bump = true
+changelog_incremental = true
+major_version_zero = true
+bump_message = "chore(release): bump simulo to v$new_version"

{simulo-0.7.0 → simulo-0.8.0}/src/simulo/_client/cli.py

@@ -450,8 +450,36 @@ def _recording_name(record: dict[str, Any]) -> str:
     return str(name) if name else f"{record.get('recording_id', 'recording')}.mcap"
 
 
+def _verify_recording(dest: Path) -> None:
+    """Read *dest* back with the ``mcap`` reader and print a one-line summary.
+
+    This is the genuine use of the bundled ``mcap`` dependency (pyproject
+    dependencies): it replaces the manual ``python -c "from mcap.reader
+    import ..."`` check a user previously had to run by hand after `simulo
+    recordings` finished. The import is LAZY (inside this function, not at
+    module scope) so a plain `import simulo` — and every other CLI command
+    that never touches recordings — stays fast/torch-free; `mcap` is light,
+    but lazy is still the right default for a CLI-only code path.
+
+    Non-fatal by design: a corrupt or truncated download must not turn an
+    otherwise-successful fetch (the bytes are already on disk) into a crash.
+    Any failure — a genuinely corrupt file, or an mcap-library edge case —
+    prints a WARNING to stderr and returns; the file is kept and the caller's
+    exit code is unaffected.
+    """
+    try:
+        from mcap.reader import make_reader
+
+        with open(dest, "rb") as f:
+            reader = make_reader(f)
+            message_count = sum(1 for _ in reader.iter_messages())
+        print(f"verified {dest.name} — {message_count} messages", file=sys.stderr)
+    except Exception as exc:  # noqa: BLE001 — best-effort verification only; must never crash a successful download
+        print(f"WARNING: could not verify {dest.name} as a valid MCAP file: {exc}", file=sys.stderr)
+
+
 def _download_and_report(client: SubmitApiClient, job_id: str, record: dict[str, Any], dest: Path) -> bool:
-    """Download one recording to *dest*; print the Lichtblick hint on success.
+    """Download one recording to *dest*; verify + print the Lichtblick hint on success.
 
     ``dest`` must already be a caller-vetted destination — either the
     user's own ``-o PATH`` or ``out_dir / _safe_download_filename(...)``
@@ -467,12 +495,17 @@ def _download_and_report(client: SubmitApiClient, job_id: str, record: dict[str,
     — raises bare ``ValueError`` from the filesystem call, and it deserves
     the same clean one-liner (server-supplied names can no longer get here;
     ``_safe_download_filename`` rejects NULs outright).
+
+    A successful download is read back and verified (``_verify_recording``,
+    non-fatal) before the Lichtblick hint prints — a corrupt download is
+    still reported as a WARNING, never a crash.
     """
     try:
         resolved = client.download_recording(job_id, str(record["recording_id"]), dest)
     except (OSError, ValueError) as exc:
         print(f"Could not write recording to {dest}: {exc}", file=sys.stderr)
         return False
+    _verify_recording(resolved)
     print(f"Open in Lichtblick: {resolved.resolve()}")
     return True
 

simulo-0.8.0/src/simulo.egg-info/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: simulo
+Version: 0.8.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
+Project-URL: Homepage, https://simulo.ai
+Keywords: robotics,simulation,reinforcement-learning,simulo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: simulo-interfaces<0.2,>=0.1
+Requires-Dist: mcap<2,>=1.3
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: isort>=5.13; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Provides-Extra: release
+Requires-Dist: commitizen>=3.27; extra == "release"
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=5.1; extra == "release"
+
+# simulo
+
+The Simulo SDK and CLI — define robotics simulation and training apps in Python,
+submit them to the Simulo cloud, monitor jobs, and retrieve trained models.
+
+Simulo is a cloud-first robotics simulation and training platform. Write your app
+against a small, stable Python API; Simulo handles running it.
+
+## Install
+
+```bash
+pip install simulo
+```
+
+Requires Python 3.11+.
+
+## Quickstart
+
+Log in once to submit to the Simulo cloud:
+
+```bash
+simulo login
+```
+
+Write an app:
+
+```python
+# app.py
+import simulo
+
+runtime = simulo.Runtime.from_registry("simulo/python-cpu:3.11")
+app = simulo.App("hello", runtime=runtime)
+
+
+@app.job(timeout=5 * 60)
+def hello(name: str = "world", repeat: int = 3) -> dict:
+    for i in range(repeat):
+        print(f"[hello] {i + 1}/{repeat}: hello, {name}!")
+    return {"greeting": f"hello, {name}", "repeat": repeat}
+
+
+@app.local_entrypoint
+def main(name: str = "world", repeat: int = 3) -> None:
+    handle = hello.spawn(name=name, repeat=repeat)
+    print(f"Submitted job: {handle.job_name}")
+```
+
+Run it:
+
+```bash
+simulo run app.py --name robot --repeat 5
+```
+
+Without logging in, `simulo run` packages the app locally without submitting it.
+
+Learn more at [simulo.ai](https://simulo.ai).

simulo-0.8.0/src/simulo.egg-info/SOURCES.txt

@@ -0,0 +1,35 @@
+MANIFEST.in
+PYPI.md
+pyproject.toml
+src/simulo/__init__.py
+src/simulo/callbacks.py
+src/simulo/py.typed
+src/simulo.egg-info/PKG-INFO
+src/simulo.egg-info/SOURCES.txt
+src/simulo.egg-info/dependency_links.txt
+src/simulo.egg-info/entry_points.txt
+src/simulo.egg-info/requires.txt
+src/simulo.egg-info/top_level.txt
+src/simulo/_client/__init__.py
+src/simulo/_client/_entrypoint.py
+src/simulo/_client/_mounts.py
+src/simulo/_client/_runner.py
+src/simulo/_client/app.py
+src/simulo/_client/asset.py
+src/simulo/_client/bundle.py
+src/simulo/_client/cli.py
+src/simulo/_client/config.py
+src/simulo/_client/credentials.py
+src/simulo/_client/discovery.py
+src/simulo/_client/http.py
+src/simulo/_client/jobs_api.py
+src/simulo/_client/learning.py
+src/simulo/_client/login.py
+src/simulo/_client/manifest.py
+src/simulo/_client/mode.py
+src/simulo/_client/packaging.py
+src/simulo/_client/registry.py
+src/simulo/_client/runtime.py
+src/simulo/_client/stub.py
+src/simulo/_client/submit_api.py
+src/simulo/_client/volume.py

{simulo-0.7.0 → simulo-0.8.0}/src/simulo.egg-info/requires.txt

@@ -1,4 +1,5 @@
 simulo-interfaces<0.2,>=0.1
+mcap<2,>=1.3
 
 [dev]
 black>=24.0

simulo-0.7.0/PKG-INFO

@@ -1,190 +0,0 @@
-Metadata-Version: 2.4
-Name: simulo
-Version: 0.7.0
-Summary: Simulo thin client — the Modal-inspired, torch-free user-facing SDK. Provides simulo.App / Runtime / Volume / Asset, @app.job, the source packager, and the `simulo` CLI. Depends only on simulo-interfaces.
-Author-email: Simulo Team <team@simulo.ai>
-License: BSD-3-Clause
-Project-URL: Homepage, https://simulo.ai
-Project-URL: Source, https://github.com/simulo-org/simulo-platform
-Keywords: robotics,simulation,reinforcement-learning,thin-client,simulo
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: BSD License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-Requires-Dist: simulo-interfaces<0.2,>=0.1
-Provides-Extra: dev
-Requires-Dist: black>=24.0; extra == "dev"
-Requires-Dist: isort>=5.13; extra == "dev"
-Requires-Dist: ruff>=0.5; extra == "dev"
-Requires-Dist: mypy>=1.10; extra == "dev"
-Requires-Dist: pytest>=8.2; extra == "dev"
-Requires-Dist: build>=1.2; extra == "dev"
-Requires-Dist: twine>=5.1; extra == "dev"
-Provides-Extra: release
-Requires-Dist: commitizen>=3.27; extra == "release"
-Requires-Dist: build>=1.2; extra == "release"
-Requires-Dist: twine>=5.1; extra == "release"
-
-# simulo
-
-The Simulo **thin client** — the Modal-inspired, user-facing SDK you install with
-`pip install simulo`.
-
-This distribution is **platform-only and torch-free**. It provides the cloud/packaging
-surface and depends only on [`simulo-interfaces`](../simulo-interfaces):
-
-- `simulo.App`, `simulo.Runtime`, `simulo.Volume`, `simulo.Asset`
-- `@app.job` and `@app.local_entrypoint`
-- `simulo.callbacks` (`ResumableCheckpoint`, `CommitVolume`, `DebugOnAnomaly`)
-- the source **packager** and the `simulo run` CLI (submit)
-
-Heavy imports (`torch`, Isaac, …) never live in this package. They are written inside the
-user's `runtime.imports()` guard and resolved only during **execution** — by the
-`simulo-backend` runner today (the local-simulation stand-in for the cloud worker), and by
-the cloud worker eventually.
-
-## Submit vs. execute
-
-Submit and execute are cleanly separated:
-
-| Step | Who | What it does |
-|------|-----|--------------|
-| **Submit** | the user (`simulo run app.py`) | runs `@app.local_entrypoint` in discovery mode (torch-free) → `spawn()`/`submit()` **write the package** (manifest + `source/`) to disk — and, in cloud mode, upload it + create a job on the control plane. NEVER trains, NEVER invokes the backend. |
-| **Execute** | `simulo-backend run-package` (worker/system launcher; the **sole executor**) | imports the packaged source in execution mode and calls the `@app.job` — the real training. Invoked directly for the local simulation, and by `simulo-backend worker` in the cloud. |
-
-## Offline vs. cloud mode
-
-The SAME `simulo run` serves both; the presence of a cloud target selects the mode:
-
-| Mode | When | What `spawn()` does |
-|------|------|---------------------|
-| **Offline (local disk)** | no credentials, no `SIMULO_API_URL`/`SIMULO_ENV` — or `SIMULO_SUBMIT=local` forces it | writes the package to disk; you execute it yourself with `simulo-backend run-package` |
-| **Cloud** | logged in (`simulo login`), or `SIMULO_API_URL`/`SIMULO_ENV` names a target | ALSO tars + uploads the package (`POST /v1/packages` + archive PUT) and creates a job (`POST /v1/jobs`); `simulo run` then follows the job's logs to completion by default (`--detach` to skip), and `JobHandle.get()` polls the platform for the real result |
-
-Cloud quickstart (staging):
-
-```bash
-SIMULO_ENV=staging simulo login        # OAuth PKCE via browser loopback -> ~/.simulo/credentials (0600)
-simulo run examples/hello/app.py       # uploads, creates the job, follows its logs
-simulo result                          # the job's result JSON
-```
-
-A worker must be polling the control plane to execute cloud jobs — on a GPU box:
-
-```bash
-SIMULO_API_URL=https://api.staging.simulo.ai SIMULO_WORKER_TOKEN=<token> \
-  simulo-backend worker                # claim -> download -> run-package -> stream logs -> complete
-```
-
-The full demo script (staging AND the zero-AWS local stack) is
-`context/verification-steps/cloud-submit-demo-runbook.md`; the automated full-stack
-proof is `tests/integration/` at the repo root (markers `cp_integration` / `cloud_e2e`).
-
-This mirrors Modal: the runtime imports the module and calls the function; it does **not**
-run `python app.py`. The job body the author wrote runs unchanged (source-preserving).
-
-## Namespace
-
-`simulo` is a **hybrid namespace**. The thin client is the only distribution that ships
-`simulo/__init__.py`; it calls `pkgutil.extend_path` so the PEP 420 namespace portions
-shipped by `simulo-backend` (`simulo.core`, `simulo.backend`, `simulo.recording`) and
-`simulo-interfaces` (`simulo.interfaces`) coexist under the same top-level `simulo`.
-
-## Modes
-
-A single mode-aware package, driven by `SIMULO_MODE`:
-
-| Mode | `runtime.imports()` |
-|------|---------------------|
-| `discovery` (default) | installs a stub import finder, records deferred top-level imports, runs no job body — the torch-free **submit** path |
-| `execution` | `contextlib.nullcontext()` — real imports; set explicitly by the `simulo-backend` runner when it **executes** a package |
-
-Discovery is the default so any bare `import` of a user app stays torch-free; `simulo
-run` submits on that default. Execution is only ever set by the sole executor
-(`simulo-backend run-package`).
-
-## One user command — submit
-
-`simulo run` is the canonical — and only — submit command:
-
-```bash
-simulo run app.py --num-envs 4096 --max-iterations 200
-```
-
-It runs the `@app.local_entrypoint` in discovery mode (torch-free). Its `spawn()` /
-`submit()` calls **write the package** — a content-addressed `<digest>/source/` tree plus
-`<digest>/simulo.manifest.json` — and print where it landed. The manifest records the
-entrypoint, runtime image + env, jobs (resources/timeout/retries/resume), volumes, the
-submitted `args`, and the deferred `remote_imports` (e.g. `["torch"]`). `spawn()` returns
-a `JobHandle` exposing `.package_path` / `.job_id`; it does **not** return a result —
-submit never trains.
-
-`simulo run` imports the file as a non-`__main__` module and invokes the registered
-entrypoint explicitly (argparse is built from its signature; `--num-envs` maps to the
-`num_envs` parameter). A direct `python app.py` does **not** submit:
-`@app.local_entrypoint` detects the `__main__` run, prints the exact equivalent
-`simulo run` command to stderr, and exits 2 — so a script wrapping the `python` form
-fails loudly instead of silently not submitting.
-
-## Execute (the sole executor)
-
-Submit does not train. Executing a package is a separate step owned entirely by the
-`simulo-backend` runner — a worker/system launcher surfaced as a CLI today only for the
-local simulation:
-
-```bash
-simulo-backend run-package <package> --job train
-```
-
-It imports the same packaged source in execution mode and calls the `@app.job` body —
-resolving the real `torch` / Isaac imports there. (Eventually the cloud worker invokes it
-and `JobHandle.get()` streams the result back; today `get()` raises a friendly
-`JobResultUnavailable` pointing at the package + the execute command.) Executing locally
-therefore needs the GPU runtime installed (`pip install simulo-backend`). See
-[`examples/cartpole`](examples/cartpole/) for a full, GPU-proven submit → execute walkthrough.
-
-## Observe — `simulo jobs` / `simulo logs` / `simulo result`
-
-Once a package executes, the thin client observes it **over HTTP only** — it never reads
-the executor's run store from disk. Submit/observe and execute behave as if on **two
-separate machines**: eventually a cloud event triggers execution and the client streams
-from the real control plane; locally, *you* are that cloud event, and a deliberately-thin
-stdlib server stands in for the control plane. The wire contract (job-record schema, the
-four `GET /v1/jobs*` endpoints, byte-offset log semantics) is the durable piece — it
-lives in `simulo.interfaces.platform.runs` and survives the move to the real cloud.
-
-The two-terminal story on one box:
-
-```bash
-# Terminal B — the "pretend cloud" (needs simulo-backend installed):
-simulo-backend serve                       # local stand-in for the cloud jobs API (127.0.0.1)
-simulo-backend run-package <package> --job train   # you are the cloud event; prints SIMULO_JOB_ID=<id> first
-
-# Terminal A — the user's machine (torch-free thin client, HTTP only):
-simulo run app.py --num-envs 64            # submit: writes the package (never executes)
-simulo logs <job-id> --follow              # stream live training output; exits 0/1 with the job
-simulo result <job-id>                     # the job's result JSON (404->error until success)
-simulo jobs                                # table of runs: id, job, status, started, exit
-```
-
-Notes:
-
-- The **job id is printed by `run-package` at execution** (first line,
-  `SIMULO_JOB_ID=...`), not at submit — a run only exists once execution starts.
-- `simulo logs <id> --follow` on a job that does not exist *yet* waits for it to appear,
-  so you can arm the tail in terminal A before triggering `run-package` in terminal B.
-- Reconnecting is just re-reading: log chunks are addressed by **byte offset**, so a new
-  `simulo logs <id>` replays the full stream from 0.
-- `SIMULO_API_URL` points the client at a different API (default
-  `http://127.0.0.1:8765`); `SIMULO_API_TOKEN`, when set, is sent as a bearer token.
-  With credentials saved by `simulo login`, their token + recorded `api_base_url`
-  are used instead. Bearer over plaintext `http://` is refused for any
-  non-loopback host (the https-when-token guard).
-- `simulo recordings <job-id> [name|--all] [-o PATH]` downloads a job's MCAP
-  recording(s) via a presigned URL (`GET /v1/jobs/{id}/recordings`) — open them in
-  Lichtblick or read them with the `mcap` library.