simulo 0.8.0__tar.gz → 0.10.0__tar.gz

{simulo-0.8.0/src/simulo.egg-info → simulo-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.8.0
+Version: 0.10.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.2,>=0.1
+Requires-Dist: simulo-interfaces<0.4,>=0.3
 Requires-Dist: mcap<2,>=1.3
 Provides-Extra: dev
 Requires-Dist: black>=24.0; extra == "dev"

{simulo-0.8.0 → simulo-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.8.0"
+version = "0.10.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"
@@ -25,7 +25,7 @@ classifiers = [
 # 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"]
+dependencies = ["simulo-interfaces>=0.3,<0.4", "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"]

{simulo-0.8.0 → simulo-0.10.0}/src/simulo/_client/app.py

@@ -70,6 +70,33 @@ def spawn_recorder() -> Iterator[list["JobHandle"]]:
         _SPAWN_RECORDER = previous
 
 
+# ---------------------------------------------------------------------------
+# Viewstream ambient signal — `simulo run --viewstream` scopes this for the
+# duration of one submit so a cloud `spawn()` deep inside the user's
+# @app.local_entrypoint (which `simulo run` does not call directly) can
+# attach it to the job-create call. Deliberately NOT a `spawn()`/`submit()`
+# kwarg: those kwargs feed the job's `args`, whose canonical form is the
+# `package_id` sha256 — a streaming flag must never change the package hash
+# (the live-visualization plan's wire-contract rule). Mirrors the
+# `spawn_recorder` pattern above for the same "can't thread a return value
+# through arbitrary user code" reason.
+# ---------------------------------------------------------------------------
+
+_VIEWSTREAM_REQUESTED = False
+
+
+@contextlib.contextmanager
+def viewstream_requested(enabled: bool) -> Iterator[None]:
+    """Scope ``--viewstream`` for one ``simulo run`` submit call."""
+    global _VIEWSTREAM_REQUESTED
+    previous = _VIEWSTREAM_REQUESTED
+    _VIEWSTREAM_REQUESTED = enabled
+    try:
+        yield
+    finally:
+        _VIEWSTREAM_REQUESTED = previous
+
+
 @dataclass
 class JobSpec:
     """Recorded metadata for one ``@app.job``-decorated function."""
@@ -125,8 +152,17 @@ def _spawn_local(job_name: str, package_path: Path) -> JobHandle:
     return JobHandle(job_id, package_path, job_name)
 
 
-def _spawn_cloud(job_name: str, package_path: Path, creds: Optional[dict[str, Any]]) -> JobHandle:
-    """Tar the bundle, upload it, create the job, and return a cloud JobHandle."""
+def _spawn_cloud(
+    job_name: str, package_path: Path, creds: Optional[dict[str, Any]], *, viewstream: bool = False
+) -> JobHandle:
+    """Tar the bundle, upload it, create the job, and return a cloud JobHandle.
+
+    ``viewstream`` rides ONLY the job-create call, as an optional top-level
+    body field (never inside ``args``, which feeds the ``package_id`` sha256
+    — see the live-visualization plan's wire-contract rule): a package's
+    content-addressed identity must never change based on whether this
+    particular execution asked for a live stream.
+    """
     from simulo._client.packaging import MANIFEST_FILENAME, ensure_tar
     from simulo._client.submit_api import SubmitApiClient
 
@@ -151,7 +187,7 @@ def _spawn_cloud(job_name: str, package_path: Path, creds: Optional[dict[str, An
         archive_size=len(archive_bytes),
     )
     client.upload_archive(package_id, archive_bytes)
-    record = client.create_job(package_id=package_id, job_name=job_name, args=args)
+    record = client.create_job(package_id=package_id, job_name=job_name, args=args, viewstream=viewstream)
 
     return JobHandle(JobId(str(record["job_id"])), package_path, job_name, cloud=True, base_url=base_url, token=token)
 
@@ -210,7 +246,7 @@ class JobFunction:
         else:
             creds = credentials.try_get_valid_credentials()
             if _cloud_mode_active(creds):
-                handle = _spawn_cloud(self._spec.name, package_path, creds)
+                handle = _spawn_cloud(self._spec.name, package_path, creds, viewstream=_VIEWSTREAM_REQUESTED)
             else:
                 handle = _spawn_local(self._spec.name, package_path)
         _record_spawn(handle)

simulo-0.10.0/src/simulo/_client/cancel_api.py

@@ -0,0 +1,105 @@
+"""HTTP client for the job cancel endpoint (stdlib only, torch-free).
+
+Wire contract (job-cancel-and-demo-apps plan — see
+``context/implementation-plans/job-cancel-and-demo-apps-plan.md``; the control
+plane's half of this route is built by a parallel PR, so this client codes
+directly against the plan's PINNED contract rather than waiting on it):
+``POST /v1/jobs/{job_id}/cancel`` (Cognito bearer, org-scoped).
+
+* 200 ``{"job_id": ..., "status": "cancelled"}`` — a QUEUED job is cancelled
+  immediately (it can never be claimed by a worker after this).
+* 202 ``{"job_id": ..., "status": "running", "cancel_requested": true}`` — a
+  RUNNING job has cancellation requested; the worker confirms termination
+  within one heartbeat interval. Idempotent — a repeat cancel of an
+  already-cancel-requested running job returns the same 202 shape again.
+* 409 ``job_not_running`` — the job is already in a terminal state
+  (completed/failed/cancelled); the response message carries the actual
+  status, but the caller (``simulo._client.cli``) does not surface it
+  verbatim — it reuses the same friendly "has ended" copy ``simulo view``
+  uses for the identical situation.
+* 404 ``job_not_found`` — unknown or cross-org job id (anti-enumeration;
+  never 403). This is the cancel route's ONLY pinned 404 code — mirrors
+  ``view_session_api.py``'s contract, and the caller relies on that the same
+  way: any OTHER 404 code means the ``/cancel`` route itself isn't deployed
+  in this environment (e.g. prod before this feature ships there), not that
+  the job is missing — see ``cli._CANCEL_UNAVAILABLE_MESSAGE``.
+
+Error responses use the standard ``{"error": {"code", "message", "request_id"}}``
+envelope, parsed by ``http.py`` exactly like every other client in this
+package.
+
+The route path is a LOCAL constant here rather than imported from
+``simulo.interfaces.platform.runs`` — deliberately, the same reconciliation
+call ``view_session_api.py`` made: the control-plane cancel route is being
+built by a parallel PR and may land independently of this one, so this client
+codes directly against the plan's pinned path/response shape rather than
+sharing a file with that PR (avoiding a merge conflict). Reconcile into a
+shared ``simulo.interfaces.platform`` constant in a follow-up once that PR has
+merged, if a shared module materializes for it.
+
+Shares request plumbing (structured-error parsing, the https-when-token
+guard, the foreign-host bearer rule) with ``jobs_api.py``/``view_session_api.py``
+via ``http.py`` — one request path, not reimplemented a fourth time.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from simulo._client import http
+
+#: ``POST`` — request cancellation of a queued or running job. ``.format(job_id=...)``.
+CANCEL_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/cancel"
+
+_REQUEST_TIMEOUT_S = 10.0  # every outbound call has an explicit timeout (NFR)
+_UNAVAILABLE_HINT = "Check SIMULO_API_URL / SIMULO_ENV, and that you are logged in (`simulo login`)."
+
+#: Required fields of a well-formed cancel response (see module docstring).
+_REQUIRED_FIELDS = ("job_id", "status")
+
+# Backward-compatible-style aliases — same convention as jobs_api.py /
+# view_session_api.py: these are literally ``http.HttpError``/``http.HttpHTTPError``
+# (not new subclasses), so callers that already catch ``JobsApiError`` (also
+# ``http.HttpError``) catch these too without any extra wiring.
+CancelApiError = http.HttpError
+CancelApiHTTPError = http.HttpHTTPError
+
+
+class CancelApiClient:
+    """Client for ``POST /v1/jobs/{job_id}/cancel``."""
+
+    def __init__(self, base_url: str, *, token: Optional[str] = None) -> None:
+        if not base_url.startswith(("http://", "https://")):
+            raise CancelApiError(f"API base URL must be an http(s) URL, got {base_url!r}.")
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def cancel_job(self, job_id: str) -> dict[str, Any]:
+        """Request cancellation of *job_id*; returns the parsed 200/202 body.
+
+        Raises :class:`CancelApiHTTPError` on any non-2xx response — the
+        caller (``simulo._client.cli``) classifies by ``exc.code``, never by
+        ``exc.status`` alone (both ``job_not_running`` and the route-missing
+        degradation share statuses with other codes, exactly like
+        ``ViewSessionApiClient.create_view_session``'s callers already do).
+        """
+        path = CANCEL_ROUTE_TEMPLATE.format(job_id=http.quote_path_segment(job_id))
+        payload = http.request_json(
+            "POST",
+            self._base_url + path,
+            token=self._token,
+            api_base_url=self._base_url,
+            json_body={},
+            timeout=_REQUEST_TIMEOUT_S,
+            unavailable_hint=_UNAVAILABLE_HINT,
+        )
+        if not isinstance(payload, dict):
+            raise CancelApiError(f"Malformed cancel response for job {job_id!r}: expected a JSON object.")
+        missing = [field for field in _REQUIRED_FIELDS if field not in payload]
+        if missing:
+            raise CancelApiError(f"Malformed cancel response for job {job_id!r}: missing field(s) {missing}.")
+        return payload