simulo 0.6.0__tar.gz → 0.7.0__tar.gz

simulo-0.7.0/PKG-INFO

@@ -0,0 +1,190 @@
+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.

simulo-0.7.0/README.md

@@ -0,0 +1,158 @@
+# 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.

simulo-0.7.0/pyproject.toml

@@ -0,0 +1,107 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simulo"
+version = "0.7.0"
+description = "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."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "BSD-3-Clause" }
+authors = [{ name = "Simulo Team", email = "team@simulo.ai" }]
+keywords = ["robotics", "simulation", "reinforcement-learning", "thin-client", "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. The thin client orchestrates packaging + discovery
+# and depends ONLY on the contract layer; NO torch, NO simulo-backend. Heavy
+# imports live inside the user's `runtime.imports()` guard (resolved in the
+# cloud / by the backend runner), never in this distribution.
+dependencies = ["simulo-interfaces>=0.1,<0.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"]
+# Mirrors simulo-backend's [release] extra. `dev` above carries build/twine
+# but deliberately NOT commitizen — the release skill (.claude/skills/release/
+# SKILL.md) installs THIS extra specifically so `cz` is available without
+# also pulling in a second copy of build/twine.
+release = ["commitizen>=3.27", "build>=1.2", "twine>=5.1"]
+
+[project.scripts]
+simulo = "simulo._client.cli:main"
+
+[project.urls]
+Homepage = "https://simulo.ai"
+Source = "https://github.com/simulo-org/simulo-platform"
+
+# The thin client is the ONE distribution that ships `src/simulo/__init__.py`.
+# That __init__ calls pkgutil.extend_path so the PEP 420 namespace portions
+# shipped by simulo-backend (simulo.core/backend/recording) and simulo-interfaces
+# (simulo.interfaces) union into the same `simulo` package. `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 ------------------------------------------------------------
+# Path B release flow (see `.claude/skills/release/SKILL.md`): `cz bump` here
+# creates the bump commit + tag locally; `.github/workflows/release.yml`
+# 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) cannot come from `cz bump` — 0.1.0 -> 0.7.0 is not
+# a conventional-commit increment, and cz's first-run changelog would sweep
+# in repo-wide history that predates this distribution's split from
+# simulo-backend. It is a hand-written bump commit per the release skill's
+# First-release appendix. 0.7.0 (not 0.2.0) is deliberate: it must exceed the
+# legacy thick-client `simulo` package's last version (0.6.0) already
+# published to PyPI under this same project name, so `pip install simulo`
+# resolves to the new thin client, never the old thick client.
+[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/src/simulo/__init__.py

@@ -0,0 +1,154 @@
+"""Simulo thin client — the user-facing, torch-free SDK surface.
+
+This is the ONE Simulo distribution that ships ``simulo/__init__.py``. The
+``extend_path`` call below unions every ``simulo/`` directory on ``sys.path`` into
+this package's ``__path__`` so the PEP 420 namespace portions shipped by sibling
+distributions (``simulo.core`` / ``simulo.backend`` / ``simulo.recording`` from
+``simulo-backend``; ``simulo.interfaces`` from ``simulo-interfaces``) resolve
+alongside the clean top-level ``simulo.App`` re-exported here.
+
+It MUST run before the re-exports below, because importing ``simulo._client.app``
+pulls in ``simulo.interfaces`` (a sibling distribution).
+
+Two kinds of name live on ``simulo``:
+
+* **Platform** names — ``App / Runtime / Volume / Asset / callbacks`` — are **real,
+  eager** attributes bound below. They are always torch-free.
+* **Learning** names — ``Task / Scene / Robot / LearningEnv / RLTrainer / …`` — are
+  resolved **lazily and mode-aware** through the PEP 562 ``__getattr__`` below,
+  which delegates to :mod:`simulo._client.learning`. At submit (discovery mode)
+  they resolve to lean stand-ins so the user app imports without the heavy runtime;
+  only the backend runner (execution mode) resolves them to ``simulo.core``. Because
+  the platform names are real attributes, ``__getattr__`` fires *only* for the
+  learning names.
+"""
+
+import pkgutil as _pkgutil
+from typing import TYPE_CHECKING
+
+__path__ = _pkgutil.extend_path(__path__, __name__)
+
+from simulo import callbacks
+from simulo._client.app import App
+from simulo._client.asset import Asset
+from simulo._client.learning import LEARNING_NAMES as _LEARNING_NAMES
+from simulo._client.learning import resolve as _resolve_learning
+from simulo._client.runtime import Runtime
+from simulo._client.volume import Volume
+
+# Public surface = eager platform exports (real attributes; ``__getattr__`` never
+# fires for these) + the lazily-resolved learning names. Kept a static literal so
+# tooling recognises the re-exports; a test guards it against ``LEARNING_NAMES`` drift.
+__all__ = [
+    # platform (eager, real)
+    "App",
+    "Runtime",
+    "Volume",
+    "Asset",
+    "callbacks",
+    # learning (lazy, mode-aware)
+    "Entity",
+    "LearningEnv",
+    "Light",
+    "Material",
+    "ObservationComponent",
+    "Physics",
+    "Player",
+    "Policy",
+    "Pose",
+    "RLPlayer",
+    "RLTrainer",
+    "RecordConfig",
+    "RewardComponent",
+    "Robot",
+    "Scenario",
+    "Scene",
+    "Task",
+    "Terrain",
+    "TerminationCondition",
+    "Trainer",
+    "Visual",
+]
+
+
+def __getattr__(name: str) -> object:
+    """PEP 562 hook: lazily resolve the mode-aware learning names.
+
+    Fires only for attributes missing from the module dict — i.e. never for the
+    real platform exports above. Delegates the learning names to
+    :func:`simulo._client.learning.resolve` (discovery stand-in vs. real
+    ``simulo.core`` class, by mode); everything else is a genuine ``AttributeError``.
+    """
+    if name in _LEARNING_NAMES:
+        return _resolve_learning(name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Expose only the public surface to ``dir(simulo)``.
+
+    That is ``__all__`` (eager platform exports + learning names) unioned with
+    :data:`LEARNING_NAMES`. Private module globals (``_pkgutil``,
+    ``_resolve_learning``, ``_LEARNING_NAMES``, the ``TYPE_CHECKING`` import, …)
+    are deliberately filtered out so tab-completion shows the user-facing API only.
+    """
+    return sorted(set(__all__) | set(_LEARNING_NAMES))
+
+
+if TYPE_CHECKING:
+    # Static aliases so a type checker sees the learning names with precise types
+    # (PEP 562 ``__getattr__`` would otherwise type them as ``Any``). The rule that
+    # this block MUST follow — and that the mypy positive test in
+    # ``tests/test_learning_typing.py`` locks — is:
+    #
+    # * **Subclassable** names (used as ``class X(simulo.Task)``) alias their
+    #   ``interfaces.runtime`` Protocol, so the subclass is checked against the
+    #   contract (e.g. ``TaskProtocol``).
+    # * **Instantiated / value-config** names (used as ``simulo.LearningEnv(task=...)``,
+    #   ``simulo.RLTrainer(env=...)``, ``simulo.Scene(...)``) alias ``Any``. Their
+    #   concrete type is the heavy ``simulo.core`` class, available only on the
+    #   worker — aliasing them to a Protocol would make mypy reject instantiation
+    #   ("Cannot instantiate protocol class").
+    from typing import Any
+
+    from simulo.interfaces.runtime import (
+        ObservationComponentProtocol,
+        PlayerProtocol,
+        PolicyProtocol,
+        RewardComponentProtocol,
+        ScenarioProtocol,
+        TaskProtocol,
+        TerminationConditionProtocol,
+    )
+
+    # Subclassable names alias their Protocol so ``class X(simulo.Task)`` is checked
+    # against ``TaskProtocol``.
+    Task = TaskProtocol
+    Scenario = ScenarioProtocol
+    Policy = PolicyProtocol
+    Player = PlayerProtocol
+    ObservationComponent = ObservationComponentProtocol
+    RewardComponent = RewardComponentProtocol
+    TerminationCondition = TerminationConditionProtocol
+    # Instantiated / value-config names: concrete type is the heavy ``simulo.core``
+    # (or ``simulo.recording``, for ``RecordConfig``) class, available only on the
+    # worker; alias ``Any`` so mypy accepts ``simulo.Name(...)``.
+    # ``LearningEnv`` is here — ``simulo.LearningEnv(task=...)`` is instantiated, so
+    # it must NOT alias ``LearningEnvProtocol`` (mypy would reject the call).
+    # ``RLPlayer``/``RecordConfig`` are instantiated too (``simulo.RLPlayer(env=...)``,
+    # ``simulo.RecordConfig(output_path=...)``), so they alias ``Any`` — only the
+    # subclassable ``Player`` base aliases ``PlayerProtocol``.
+    LearningEnv = Any
+    Scene = Any
+    Robot = Any
+    RLTrainer = Any
+    Trainer = Any
+    RLPlayer = Any
+    RecordConfig = Any
+    Pose = Any
+    Terrain = Any
+    Light = Any
+    Entity = Any
+    Material = Any
+    Physics = Any
+    Visual = Any

simulo-0.7.0/src/simulo/_client/__init__.py

@@ -0,0 +1,6 @@
+"""Internal implementation package for the Simulo thin client.
+
+Nothing here is part of the public API. Users import from the top-level
+``simulo`` namespace (``simulo.App`` / ``simulo.Runtime`` / ``simulo.callbacks``);
+these modules are the private machinery behind those re-exports.
+"""