simulo 0.6.0rc1__tar.gz → 0.7.1__tar.gz

simulo-0.7.1/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.7.1/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: simulo
+Version: 0.7.1
+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
+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.7.1/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.7.1/pyproject.toml

@@ -0,0 +1,98 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simulo"
+version = "0.7.1"
+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. Heavy
+# imports (e.g. torch) belong inside the user's `runtime.imports()` guard,
+# resolved only at job-execution time — 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"]
+# `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.1/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.1/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.
+"""

simulo-0.7.1/src/simulo/_client/_entrypoint.py

@@ -0,0 +1,104 @@
+"""Run a ``@app.local_entrypoint`` from command-line arguments.
+
+The local entrypoint is invoked by ``simulo run app.py`` — the canonical (and
+only) submit command — which maps ``--flag value`` arguments onto the
+entrypoint's parameters and ends at exactly one submit. (A direct ``python
+app.py`` never reaches this module: :meth:`App.local_entrypoint` prints the
+exact equivalent ``simulo run`` command to stderr and exits 2.)
+
+An argument parser is built from the entrypoint's signature: each parameter
+``foo_bar`` becomes ``--foo-bar`` (dash for underscore), coerced from the
+parameter's default type, then its annotation. A parameter without a default is
+required. This keeps authoring frictionless — ``def main(num_envs: int = 4096)``
+just works as ``--num-envs 4096`` — with no argparse boilerplate in the app file.
+"""
+
+from __future__ import annotations
+
+import argparse
+import inspect
+from typing import Any, Callable, Mapping, Sequence
+
+_STR_TO_TYPE: Mapping[str, type] = {"int": int, "float": float, "bool": bool, "str": str}
+
+_SKIP_KINDS = (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD)
+
+
+def _param_type(param: inspect.Parameter) -> type:
+    """Best-effort scalar type for a parameter: default's type, then annotation.
+
+    A concrete (non-``None``) default is the most reliable signal — ``= 4096``
+    means ``int``. Otherwise fall back to the annotation (a real type, or a PEP
+    563 string like ``"int"``). Defaults to ``str`` when nothing is conclusive.
+    """
+    default = param.default
+    if default is not inspect.Parameter.empty and default is not None:
+        return type(default)
+    ann = param.annotation
+    if isinstance(ann, type):
+        return ann
+    if isinstance(ann, str):
+        return _STR_TO_TYPE.get(ann, str)
+    return str
+
+
+def _str_to_bool(raw: str) -> bool:
+    """Parse a CLI ``--flag value`` boolean (``true``/``1``/``yes`` → ``True``)."""
+    lowered = raw.strip().lower()
+    if lowered in ("true", "1", "yes", "y", "on"):
+        return True
+    if lowered in ("false", "0", "no", "n", "off"):
+        return False
+    raise argparse.ArgumentTypeError(f"expected a boolean (true/false), got {raw!r}")
+
+
+def build_parser(fn: Callable[..., object]) -> argparse.ArgumentParser:
+    """Build an ``argparse`` parser from a local-entrypoint's signature."""
+    sig = inspect.signature(fn)
+    doc = (inspect.getdoc(fn) or "").strip().splitlines()
+    parser = argparse.ArgumentParser(
+        prog=getattr(fn, "__name__", "entrypoint"),
+        description=doc[0] if doc else None,
+    )
+    for name, param in sig.parameters.items():
+        if param.kind in _SKIP_KINDS:
+            continue
+        flag = "--" + name.replace("_", "-")
+        required = param.default is inspect.Parameter.empty
+        typ = _param_type(param)
+        if typ is bool:
+            parser.add_argument(
+                flag,
+                dest=name,
+                type=_str_to_bool,
+                required=required,
+                default=None if required else param.default,
+                metavar="BOOL",
+            )
+        else:
+            parser.add_argument(
+                flag,
+                dest=name,
+                type=typ,
+                required=required,
+                default=None if required else param.default,
+            )
+    return parser
+
+
+def parse_args(fn: Callable[..., object], argv: Sequence[str]) -> dict[str, Any]:
+    """Parse ``argv`` against ``fn``'s signature into a keyword-argument dict."""
+    parser = build_parser(fn)
+    namespace = parser.parse_args(list(argv))
+    sig = inspect.signature(fn)
+    kwargs: dict[str, Any] = {}
+    for name, param in sig.parameters.items():
+        if param.kind in _SKIP_KINDS:
+            continue
+        kwargs[name] = getattr(namespace, name)
+    return kwargs
+
+
+def run_entrypoint(fn: Callable[..., object], argv: Sequence[str]) -> object:
+    """Parse ``argv`` for ``fn`` and invoke it (the single submit happens inside)."""
+    return fn(**parse_args(fn, argv))

simulo-0.7.1/src/simulo/_client/_mounts.py

@@ -0,0 +1,25 @@
+"""Shared naming convention for mount environment variables.
+
+The backend runner (follow-up PR) exports one env var per mount before invoking
+a job body; ``Volume.path`` / ``Asset.path`` read them back. Centralising the
+key derivation here keeps the producer and consumer in lock-step.
+"""
+
+import re
+
+_NON_ALNUM = re.compile(r"[^A-Za-z0-9]+")
+
+
+def _sanitize(segment: str) -> str:
+    """Upper-case, collapse runs of non-alphanumerics to ``_``, strip edges."""
+    return _NON_ALNUM.sub("_", segment).strip("_").upper()
+
+
+def volume_env_key(name: str) -> str:
+    """Env var the runner sets to a volume's local mount path."""
+    return f"SIMULO_VOLUME_{_sanitize(name)}"
+
+
+def asset_env_key(uri: str) -> str:
+    """Env var the runner sets to an asset's local (read-only) mount path."""
+    return f"SIMULO_ASSET_{_sanitize(uri)}"