simulo-interfaces 0.25.0__tar.gz → 0.26.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/PKG-INFO +2 -2
  2. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/pyproject.toml +2 -2
  3. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/visual.py +16 -1
  4. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/__init__.py +8 -0
  5. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/app.py +6 -0
  6. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/asset_catalog.py +2 -1
  7. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/enums.py +8 -8
  8. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/evaluation.py +7 -0
  9. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/outputs.py +5 -4
  10. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/preview.py +5 -2
  11. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/runs.py +26 -2
  12. simulo_interfaces-0.26.0/src/simulo/interfaces/platform/runtimes.py +19 -0
  13. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/submit.py +32 -2
  14. simulo_interfaces-0.26.0/src/simulo/interfaces/platform/system_tiers.py +101 -0
  15. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/systems.py +5 -3
  16. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/runtime/task.py +13 -0
  17. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo_interfaces.egg-info/PKG-INFO +2 -2
  18. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo_interfaces.egg-info/SOURCES.txt +2 -0
  19. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo_interfaces.egg-info/requires.txt +1 -1
  20. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/MANIFEST.in +0 -0
  21. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/PYPI.md +0 -0
  22. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/setup.cfg +0 -0
  23. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/__init__.py +0 -0
  24. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/__init__.py +0 -0
  25. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/action_channel.py +0 -0
  26. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/actuator.py +0 -0
  27. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/asset.py +0 -0
  28. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/checkpoint.py +0 -0
  29. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/entity.py +0 -0
  30. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/light.py +0 -0
  31. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/materials.py +0 -0
  32. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/physics.py +0 -0
  33. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/policy_inputs.py +0 -0
  34. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/pose.py +0 -0
  35. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/primitives.py +0 -0
  36. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/prop.py +0 -0
  37. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/properties.py +0 -0
  38. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/record.py +0 -0
  39. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/robot.py +0 -0
  40. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/robot_config.py +0 -0
  41. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/scene.py +0 -0
  42. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/sensor.py +0 -0
  43. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/terrain.py +0 -0
  44. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/variants.py +0 -0
  45. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/authoring/world.py +0 -0
  46. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/exceptions.py +0 -0
  47. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/ids.py +0 -0
  48. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/_payload.py +0 -0
  49. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/asset.py +0 -0
  50. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/callbacks.py +0 -0
  51. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/debug.py +0 -0
  52. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/domain.py +0 -0
  53. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/job_events.py +0 -0
  54. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/manifest.py +0 -0
  55. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/onnx_bundle.py +0 -0
  56. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/policy_checkpoint.py +0 -0
  57. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/runtime.py +0 -0
  58. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/platform/volume.py +0 -0
  59. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/py.typed +0 -0
  60. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/runtime/__init__.py +0 -0
  61. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/runtime/anomaly.py +0 -0
  62. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/runtime/components.py +0 -0
  63. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/runtime/env.py +0 -0
  64. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/runtime/player.py +0 -0
  65. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/runtime/policy.py +0 -0
  66. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/runtime/policy_frames.py +0 -0
  67. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/runtime/tensors.py +0 -0
  68. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo/interfaces/runtime/trainer.py +0 -0
  69. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo_interfaces.egg-info/dependency_links.txt +0 -0
  70. {simulo_interfaces-0.25.0 → simulo_interfaces-0.26.0}/src/simulo_interfaces.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: simulo-interfaces
3
- Version: 0.25.0
3
+ Version: 0.26.0
4
4
  Summary: Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime.
5
5
  Author-email: Simulo Team <team@simulo.ai>
6
6
  License: BSD-3-Clause
@@ -28,7 +28,7 @@ Classifier: Typing :: Typed
28
28
  Requires-Python: >=3.11
29
29
  Description-Content-Type: text/markdown
30
30
  Provides-Extra: dev
31
- Requires-Dist: black==26.5.1; extra == "dev"
31
+ Requires-Dist: black==26.10.1; extra == "dev"
32
32
  Requires-Dist: isort==8.0.1; extra == "dev"
33
33
  Requires-Dist: ruff==0.15.21; extra == "dev"
34
34
  Requires-Dist: mypy==2.3.0; extra == "dev"
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "simulo-interfaces"
7
- version = "0.25.0"
7
+ version = "0.26.0"
8
8
  description = "Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime."
9
9
  readme = "PYPI.md"
10
10
  requires-python = ">=3.11"
@@ -51,7 +51,7 @@ dependencies = []
51
51
  # Keep in lockstep with `.github/workflows/simulo-interfaces-ci.yml`'s
52
52
  # `ruff`/`black`/`isort`/`mypy` steps, which resolve their versions from THIS extra
53
53
  # (`pip install -e ".[dev]"`).
54
- dev = ["black==26.5.1", "isort==8.0.1", "ruff==0.15.21", "mypy==2.3.0", "pytest>=8.2", "build>=1.2",
54
+ dev = ["black==26.10.1", "isort==8.0.1", "ruff==0.15.21", "mypy==2.3.0", "pytest>=8.2", "build>=1.2",
55
55
  "twine>=5.1", "packaging>=23"]
56
56
  # `packaging` is a direct test dependency, not incidental: the consumer-pin guard parses
57
57
  # PEP 508 requirements with it. It arrives transitively via pytest today, which is exactly
@@ -159,11 +159,17 @@ class LineMarker(VisualMarkerBase):
159
159
  these points.
160
160
  width: Line width in meters
161
161
  color: Line color as RGB or RGBA tuple
162
+ static: ``True`` for a line that never changes, such as a track edge
163
+ or a zone boundary. ``points`` are then in each copy's own frame
164
+ and every copy draws the same line. The scene sends it once and
165
+ the viewer builds it once, so it costs nothing per step or per
166
+ frame. ``set_points`` raises on a static line.
162
167
  """
163
168
 
164
169
  points: Any = None
165
170
  width: float = 0.01
166
171
  color: Color = (0.0, 0.8, 1.0) # Cyan by default
172
+ static: bool = False
167
173
  _num_points: int = field(default=0, init=False, repr=False)
168
174
 
169
175
  def __post_init__(self) -> None:
@@ -185,7 +191,12 @@ class LineMarker(VisualMarkerBase):
185
191
  world coordinates. Pass float32 tensors on the simulation
186
192
  device; other inputs (lists, CPU or float64 tensors) may
187
193
  allocate or synchronize the host.
194
+
195
+ Raises:
196
+ TypeError: The line is ``static``.
188
197
  """
198
+ if self.static:
199
+ raise TypeError(f"line marker {self.name!r} is static; its points never change")
189
200
  if self._backend_handle is None:
190
201
  return
191
202
 
@@ -362,15 +373,18 @@ class Visual:
362
373
  width: float = 0.01,
363
374
  color: Color = (0.0, 0.8, 1.0),
364
375
  num_instances: int = 1,
376
+ static: bool = False,
365
377
  ) -> LineMarker:
366
378
  """Create a line or polyline marker.
367
379
 
368
380
  Args:
369
381
  name: Unique marker name
370
- points: Initial ``(P, 3)`` points, at least two, in world coordinates
382
+ points: Initial ``(P, 3)`` points, at least two, in world coordinates,
383
+ or in each copy's own frame when ``static`` is ``True``
371
384
  width: Line width in meters
372
385
  color: RGB or RGBA color tuple
373
386
  num_instances: Number of instances for multi-env
387
+ static: ``True`` for a line that never changes (see ``LineMarker``)
374
388
 
375
389
  Returns:
376
390
  LineMarker instance
@@ -388,4 +402,5 @@ class Visual:
388
402
  width=width,
389
403
  color=color,
390
404
  num_instances=num_instances,
405
+ static=static,
391
406
  )
@@ -303,6 +303,11 @@ from simulo.interfaces.platform.runs import (
303
303
  normalize_job_tags,
304
304
  )
305
305
  from simulo.interfaces.platform.runtime import RuntimeProtocol
306
+ from simulo.interfaces.platform.runtimes import (
307
+ ENGINE_RUNTIME_ID,
308
+ LEGACY_ISAAC_RUNTIME_ID,
309
+ RUNTIME_ID_BY_ASSET_RUNTIME,
310
+ )
306
311
  from simulo.interfaces.platform.submit import (
307
312
  CHECKPOINT_IS_INPUT_CODE,
308
313
  CHECKPOINT_KINDS,
@@ -564,6 +569,9 @@ __all__ = [
564
569
  "MAX_ASSET_REF_CHARS",
565
570
  "MAX_ASSETS_RESOLVE_BATCH",
566
571
  "DEFAULT_ASSET_RUNTIME",
572
+ "LEGACY_ISAAC_RUNTIME_ID",
573
+ "ENGINE_RUNTIME_ID",
574
+ "RUNTIME_ID_BY_ASSET_RUNTIME",
567
575
  "ASSET_UPLOAD_PART_BYTES",
568
576
  "ASSET_FACTS_SCHEMA_VERSION",
569
577
  "ASSET_NOT_EXPORTABLE_CODE",
@@ -83,6 +83,8 @@ class AppProtocol(Protocol):
83
83
  type: Union[JobType, str],
84
84
  callbacks: Sequence[JobCallbackProtocol] = ...,
85
85
  system: Optional[SystemType] = ...,
86
+ gpus: Optional[int] = ...,
87
+ gpus_per_node: Optional[int] = ...,
86
88
  timeout: Optional[int] = ...,
87
89
  retries: int = ...,
88
90
  **extra: Any,
@@ -95,6 +97,8 @@ class AppProtocol(Protocol):
95
97
  type: Union[JobType, str],
96
98
  callbacks: Sequence[JobCallbackProtocol] = ...,
97
99
  system: Optional[SystemType] = ...,
100
+ gpus: Optional[int] = ...,
101
+ gpus_per_node: Optional[int] = ...,
98
102
  timeout: Optional[int] = ...,
99
103
  retries: int = ...,
100
104
  **extra: Any,
@@ -106,6 +110,8 @@ class AppProtocol(Protocol):
106
110
  type: Optional[Union[JobType, str]] = None,
107
111
  callbacks: Sequence[JobCallbackProtocol] = (),
108
112
  system: Optional[SystemType] = None,
113
+ gpus: Optional[int] = None,
114
+ gpus_per_node: Optional[int] = None,
109
115
  timeout: Optional[int] = None,
110
116
  retries: int = 0,
111
117
  **extra: Any,
@@ -611,6 +611,7 @@ MAX_ASSETS_RESOLVE_BATCH = 64
611
611
  #: VALIDATOR's finalize call to send the IDENTICAL string — one shared constant is the
612
612
  #: only way to prevent string drift.
613
613
  DEFAULT_ASSET_RUNTIME = "isaac"
614
+ """The catalog label used by the legacy validation default."""
614
615
 
615
616
  # --------------------------------------------------------------------------
616
617
  # Publish options envelope
@@ -1059,7 +1060,7 @@ class WorkerAssetInfo:
1059
1060
  """The pinned asset ref in the wire canonical form (module docstring's
1060
1061
  "Canonical form (wire)" note) — publisher always explicit, version always
1061
1062
  pinned, e.g. ``acme-robotics/world/warehouse:v2`` for an org asset or
1062
- ``simulo/world/warehouse:v2`` for a global one. Same form as
1063
+ ``simulo/world/warehouse:v3`` for a global one. Same form as
1063
1064
  :attr:`ResolvedAssetPin.canonical_ref`."""
1064
1065
 
1065
1066
  kind: str
@@ -78,23 +78,23 @@ class JobStatus(StrEnum):
78
78
  class SystemType(StrEnum):
79
79
  """An abstract GPU system tier.
80
80
 
81
- Each tier's hardware profile and fleet-provisioning state lives in
82
- :data:`simulo.interfaces.platform.systems.SYSTEM_SPECS`, keyed by these
83
- members. The AWS instance type behind a tier is never part of this name —
84
- see :class:`simulo.interfaces.platform.systems.SystemSpec`'s own docstring.
81
+ Memory classes and enabled layouts live in
82
+ :data:`simulo.interfaces.platform.system_tiers.SYSTEM_TIERS`.
83
+ Hardware can change within a class. The older ``systems.SYSTEM_SPECS``
84
+ remains a compatibility snapshot for consumers awaiting adoption.
85
85
  """
86
86
 
87
87
  TIER_1 = "tier1"
88
- """Entry tier — always available."""
88
+ """16 GB per accelerator; enabled on staging."""
89
89
 
90
90
  TIER_2 = "tier2"
91
- """Mid tier — always available."""
91
+ """24 GB per accelerator; enabled on staging."""
92
92
 
93
93
  TIER_3 = "tier3"
94
- """High tier — not yet available on the deployable fleet."""
94
+ """48 GB per accelerator; no enabled staging hardware."""
95
95
 
96
96
  TIER_4 = "tier4"
97
- """Top tier — not yet available on the deployable fleet."""
97
+ """96 GB per accelerator; no enabled staging hardware."""
98
98
 
99
99
 
100
100
  class ResourceKind(StrEnum):
@@ -432,6 +432,13 @@ class ReplayTrace(TypedDict):
432
432
  Filming translates world-frame poses from this origin into its destination
433
433
  environment.
434
434
  """
435
+ variant_options: NotRequired[dict[str, int]]
436
+ """Selected option index for each variant prop, keyed by its scene path.
437
+
438
+ The evaluator captures these values from the recorded environment copy.
439
+ Filming uses them to build that copy's prop geometry before it restores
440
+ recorded poses. The field is absent when the scene has no variants.
441
+ """
435
442
  frames: list[ReplayFrame]
436
443
  """The first frame is the episode's starting state, ``time_s == 0``."""
437
444
 
@@ -134,10 +134,11 @@ and the narrow ``job_artifacts`` table (everything registered via
134
134
  ``save_output``). No data moves, and a row appears in the union **exactly
135
135
  once**. The projection reuses the
136
136
  platform-standard paginated envelope (``items``/``total``/``page``/``limit``/
137
- ``pages``; default ``limit=20``, max 100, out-of-range → 422) and the standard
138
- error shape — see :mod:`simulo.interfaces.platform.runs` for the full
139
- contract, including the ``pages >= 1`` invariant that holds even for
140
- ``total == 0``.
137
+ ``pages``; default ``limit=20``, max 100) and the standard error shape.
138
+ ``page < 1``, ``limit < 1``, or ``limit > 100`` returns 422. A page beyond the
139
+ last returns 200 with empty items and ``page > pages``. See
140
+ :mod:`simulo.interfaces.platform.runs` for the full contract, including the
141
+ ``pages >= 1`` invariant that holds even for ``total == 0``.
141
142
  """
142
143
 
143
144
  import re
@@ -21,6 +21,9 @@ PREVIEW_REPORT_SCHEMA_VERSION_V2: Final = "simulo.preview_report.v2"
21
21
  PREVIEW_REPORT_SCHEMA_VERSIONS: Final = frozenset({PREVIEW_REPORT_SCHEMA_VERSION, PREVIEW_REPORT_SCHEMA_VERSION_V2})
22
22
  """Every preview report version consumers must accept during the Engine cutover."""
23
23
 
24
+ JSONValue: TypeAlias = str | bool | int | float | None | list["JSONValue"] | dict[str, "JSONValue"]
25
+ """A JSON value; numeric values in reports must be finite."""
26
+
24
27
  ENGINE_SETUP_SCHEMA_VERSION: Final = "simulo.engine_setup.v1"
25
28
  LIMITS_REPORT_SCHEMA_VERSION: Final = "simulo.limits_report.v1"
26
29
 
@@ -114,10 +117,10 @@ class EngineSetupValue(TypedDict):
114
117
 
115
118
 
116
119
  class EngineSetupMotorSpec(TypedDict):
117
- """The applied motor fields for one joint, with their provenance."""
120
+ """The applied JSON-valued motor fields for one joint, with their provenance."""
118
121
 
119
122
  joint: str
120
- fields: dict[str, float | None]
123
+ fields: dict[str, JSONValue]
121
124
  sources: dict[str, str]
122
125
  estimated_fields: list[str]
123
126
  overridden_fields: list[str]
@@ -22,7 +22,9 @@ HTTP API shape (all responses JSON; all timestamps ISO 8601 UTC, e.g.
22
22
 
23
23
  {"items": [<JobRecord>, ...], "total": 3, "page": 1, "limit": 20, "pages": 1}
24
24
 
25
- ``limit`` defaults to 20, maximum 100; out-of-range ``page``/``limit`` → 422.
25
+ ``limit`` defaults to 20, maximum 100. ``page < 1``, ``limit < 1``, or
26
+ ``limit > 100`` returns 422. A page beyond the last returns 200 with empty
27
+ items and ``page > pages``.
26
28
 
27
29
  **``pages`` is always >= 1**, including for an empty list (``total: 0`` →
28
30
  ``pages: 1``, not ``0``). Clients treat ``page > pages`` as "this page is out
@@ -192,7 +194,7 @@ from typing import Any, Literal, Optional
192
194
 
193
195
  from simulo.interfaces.ids import JobId, JobPublicId, PackageId, parse_job_public_id
194
196
  from simulo.interfaces.platform._payload import known_payload_fields
195
- from simulo.interfaces.platform.enums import JobStatus, JobType
197
+ from simulo.interfaces.platform.enums import JobStatus, JobType, SystemType
196
198
  from simulo.interfaces.platform.evaluation import EvaluationHeadline
197
199
  from simulo.interfaces.platform.outputs import JobOutputsSummary, OutputFlag
198
200
 
@@ -404,6 +406,15 @@ class JobRecord:
404
406
  attempts: int = 0
405
407
  """Number of execution attempts started so far (retries make this > 1)."""
406
408
 
409
+ runtime_budget_s: Optional[int] = None
410
+ """Effective maximum runtime for this submitted job, in seconds.
411
+
412
+ The control plane resolves this from the organization's policy and any
413
+ shorter ``@app.job(timeout=...)`` declaration when it accepts the
414
+ submission. ``None`` means this response did not serve a resolved value;
415
+ consumers must not substitute a client-side default.
416
+ """
417
+
407
418
  viewstream: bool = False
408
419
  """Whether this run requested an interactive live view. Additive and
409
420
  tolerant: older producers omit it and consumers see ``False``."""
@@ -545,6 +556,17 @@ class JobRecord:
545
556
  ``None`` and ``False`` use the fast path. This is execution intent, not
546
557
  a promise of bitwise-identical policy outcomes across devices."""
547
558
 
559
+ requested_system: SystemType | None = None
560
+ """Recorded tier. Historical requests without a tier keep request fields null."""
561
+ requested_gpus: int | None = None
562
+ """Requested total GPUs. Old tiered rows may contain the database default of one."""
563
+ requested_gpus_per_node: int | None = None
564
+ """Requested GPUs on one machine, normalized to the total when omitted."""
565
+ actual_gpus_per_node: int | None = None
566
+ """Actual total GPUs on one machine. Null until recorded at claim time."""
567
+ actual_gpu_model: str | None = None
568
+ """Display-only, curated GPU label. Null when unknown. No provider host type."""
569
+
548
570
  @classmethod
549
571
  def from_payload(cls, payload: Mapping[str, Any]) -> "JobRecord":
550
572
  """Build from a response mapping while ignoring additive unknown fields."""
@@ -554,6 +576,8 @@ class JobRecord:
554
576
  values["status"] = JobStatus(values["status"])
555
577
  if "job_type" in values:
556
578
  values["job_type"] = JobType(values["job_type"])
579
+ if values.get("requested_system") is not None:
580
+ values["requested_system"] = SystemType(values["requested_system"])
557
581
  if "tags" in values:
558
582
  tags = values["tags"]
559
583
  if not isinstance(tags, (list, tuple)):
@@ -0,0 +1,19 @@
1
+ """Shared job-runtime identifiers and catalog-label mapping."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping
6
+ from types import MappingProxyType
7
+ from typing import Final
8
+
9
+ #: Legacy Isaac jobs continue to use this runtime during cutover.
10
+ LEGACY_ISAAC_RUNTIME_ID: Final = "simulo/gpu-rl:2026.06"
11
+ #: Simulo Engine jobs use this runtime identifier during cutover.
12
+ ENGINE_RUNTIME_ID: Final = "simulo/simulo-engine:2026.10"
13
+ #: Catalog validation labels mapped to the job runtime identifiers they support.
14
+ RUNTIME_ID_BY_ASSET_RUNTIME: Final[Mapping[str, str]] = MappingProxyType(
15
+ {
16
+ "isaac": LEGACY_ISAAC_RUNTIME_ID,
17
+ "simulo-engine": ENGINE_RUNTIME_ID,
18
+ }
19
+ )
@@ -81,7 +81,8 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
81
81
  module docstring above). Request body::
82
82
 
83
83
  {"job_type": "train", "package_id": "...",
84
- "job_name": "train_cartpole", "args": {...}, "tags": []}
84
+ "job_name": "train_cartpole", "args": {...}, "tags": [],
85
+ "runtime_id": "simulo/simulo-engine:2026.10"}
85
86
 
86
87
  Response ``201`` — a :class:`~simulo.interfaces.platform.runs.JobRecord`
87
88
  with ``status`` :attr:`~simulo.interfaces.platform.enums.JobStatus.QUEUED`.
@@ -90,6 +91,16 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
90
91
  with the *existing* record rather than creating a second job — a client
91
92
  retry (e.g. after a dropped response) must not double-submit.
92
93
 
94
+ ``runtime_id`` is an optional top-level execution
95
+ field. It names the submitted manifest's supported runtime. When it is
96
+ missing, the control plane inspects the bounded, uncompressed package
97
+ manifest before selecting the legacy Isaac runtime. An Engine manifest
98
+ without this field returns ``422 client_runtime_required`` with an
99
+ instruction to run ``pip install -U simulo``. Explicit runtime values
100
+ avoid archive inspection. The selected value is stored and returned inside
101
+ the worker-only ``job`` record below; the worker compares it with the
102
+ downloaded package manifest before launch.
103
+
93
104
  A training submission may carry ``input_checkpoint`` as a top-level sibling
94
105
  of ``args``::
95
106
 
@@ -182,7 +193,18 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
182
193
  envelope with ``409 capacity_loop_disabled`` and ``409 worker_busy``,
183
194
  respectively.
184
195
 
185
- * :data:`WORKER_CLAIM_ROUTE` (``POST``) — request body carries no worker
196
+ * :data:`WORKER_CLAIM_ROUTE` (``POST``) — request body carries
197
+ ``runtime_image_digests``, a map with at most eight configured runtime IDs
198
+ to exact ``sha256:<64 lowercase hex>`` image digests. The worker reports a
199
+ key only after a local ``docker image inspect`` proves its configured image
200
+ exists. The control plane claims only a job whose selected runtime digest
201
+ exactly matches its armed expected digest. Missing, unknown, unarmed, or
202
+ mismatched entries claim no work for that runtime. The frozen Isaac worker
203
+ omits this map and can claim only Isaac jobs. Host boot starts ECS after the
204
+ first job image is ready, which may be Engine. A frozen worker can then claim
205
+ Isaac work before its image arrives; the pre-launch image check fails that
206
+ job without running it. New workers always send the map, even
207
+ when empty. The map carries no worker
186
208
  identity field: the claiming worker is whoever the ``Authorization``
187
209
  bearer (above) verifies to, never a caller-asserted value — a
188
210
  pre-cutover claim body's ``{"worker_id": "..."}`` was trusted outright,
@@ -194,6 +216,10 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
194
216
  "lease_seconds": 300,
195
217
  "lease_id": "5e0c4a4e-..."}
196
218
 
219
+ ``job.runtime_id`` is the control plane's selected runtime. A worker must
220
+ reject a claim if it differs from the downloaded package manifest's
221
+ ``runtime_id``.
222
+
197
223
  ``organization_id`` is always present and is the claimed job owner's UUID
198
224
  string. Workers use it to scope organization-owned host state without
199
225
  deriving tenancy from job arguments.
@@ -869,6 +895,10 @@ RESERVED_RUNTIME_ENV_KEYS = frozenset(
869
895
  "PYTHONPATH",
870
896
  "HOME",
871
897
  "SIMULO_JOB_ID",
898
+ # The launcher resolves this selected runtime's image, log routing,
899
+ # and watchdog before it starts the job. A manifest must not override
900
+ # that execution identity.
901
+ "SIMULO_JOB_RUNTIME_ID",
872
902
  "SIMULO_JOB_TYPE",
873
903
  "SIMULO_PACKAGE_ID",
874
904
  "SIMULO_API_URL",
@@ -0,0 +1,101 @@
1
+ """Memory-class tier contract and the repository's enabled staging layouts.
2
+
3
+ This is admission policy data, not a live fleet probe. Callers must supply their
4
+ environment's enabled catalog when it differs from staging, and verify that its
5
+ fleets exist and can scale. Product jobs currently use exactly one machine.
6
+ """
7
+
8
+ from collections.abc import Mapping
9
+ from dataclasses import dataclass
10
+ from types import MappingProxyType
11
+
12
+ from simulo.interfaces.platform.enums import SystemType
13
+
14
+
15
+ @dataclass(frozen=True, slots=True, kw_only=True)
16
+ class EnabledHardware:
17
+ """Hardware and allowed per-job GPU allocations on one machine.
18
+
19
+ Provider machine names are internal provisioning data. GPU model and host
20
+ selection can change without changing a tier's memory class or wire value.
21
+ """
22
+
23
+ gpu_model: str
24
+ machine_types: tuple[str, ...]
25
+ gpus_per_node: tuple[int, ...]
26
+
27
+
28
+ @dataclass(frozen=True, slots=True, kw_only=True)
29
+ class SystemTier:
30
+ """Memory in GB per accelerator, plus enabled hardware/layout choices."""
31
+
32
+ accelerator_memory_gb: int
33
+ enabled_hardware: tuple[EnabledHardware, ...] = ()
34
+
35
+
36
+ SYSTEM_TIERS: Mapping[SystemType, SystemTier] = MappingProxyType(
37
+ {
38
+ SystemType.TIER_1: SystemTier(
39
+ accelerator_memory_gb=16,
40
+ enabled_hardware=(
41
+ EnabledHardware(
42
+ gpu_model="T4",
43
+ machine_types=("g4dn.xlarge", "g4dn.2xlarge"),
44
+ gpus_per_node=(1,),
45
+ ),
46
+ ),
47
+ ),
48
+ SystemType.TIER_2: SystemTier(
49
+ accelerator_memory_gb=24,
50
+ enabled_hardware=(
51
+ EnabledHardware(
52
+ gpu_model="A10G",
53
+ machine_types=("g5.xlarge", "g5.2xlarge"),
54
+ gpus_per_node=(1,),
55
+ ),
56
+ ),
57
+ ),
58
+ SystemType.TIER_3: SystemTier(accelerator_memory_gb=48),
59
+ SystemType.TIER_4: SystemTier(accelerator_memory_gb=96),
60
+ }
61
+ )
62
+
63
+
64
+ def _positive_gpu_count(name: str, value: int) -> None:
65
+ if type(value) is not int or value < 1:
66
+ raise ValueError(f"{name} must be a positive integer; got {value!r}.")
67
+
68
+
69
+ def validate_system_request(
70
+ system: SystemType | None = None,
71
+ *,
72
+ gpus: int = 1,
73
+ gpus_per_node: int | None = None,
74
+ tiers: Mapping[SystemType, SystemTier] = SYSTEM_TIERS,
75
+ ) -> SystemType:
76
+ """Return the selected tier or raise ValueError with a refusal reason.
77
+
78
+ ``gpus`` is the total allocation. ``gpus_per_node`` constrains layout; it
79
+ never multiplies that total. One job selects one tier for every machine.
80
+ Only one-machine product jobs are enabled in this phase. An empty catalog
81
+ refuses every request, including an omitted system (always Tier 1).
82
+ This helper does not submit, queue, provision, or check live capacity.
83
+ """
84
+ selected = SystemType.TIER_1 if system is None else system
85
+ if not isinstance(selected, SystemType):
86
+ raise ValueError(f"system must be a SystemType member; got {system!r}.")
87
+ _positive_gpu_count("gpus", gpus)
88
+ if gpus_per_node is not None:
89
+ _positive_gpu_count("gpus_per_node", gpus_per_node)
90
+ tier = tiers.get(selected)
91
+ if tier is None or not tier.enabled_hardware:
92
+ raise ValueError(f"{selected.value} has no enabled hardware in this environment.")
93
+ counts = sorted({count for hardware in tier.enabled_hardware for count in hardware.gpus_per_node})
94
+ if gpus not in counts:
95
+ raise ValueError(f"{selected.value} cannot serve gpus={gpus}; enabled single-machine GPU counts: {counts}.")
96
+ if gpus_per_node is not None and gpus_per_node != gpus:
97
+ raise ValueError(
98
+ f"{selected.value} cannot serve gpus={gpus}, gpus_per_node={gpus_per_node}; "
99
+ "only single-machine layouts are enabled."
100
+ )
101
+ return selected
@@ -1,7 +1,9 @@
1
- """GPU system-tier catalog — the closed hardware contract behind `SystemType`.
1
+ """Compatibility hardware snapshot for existing system-tier consumers.
2
2
 
3
- `SYSTEM_SPECS` is the single published source of truth for what each tier
4
- means: the marketing GPU name, its VRAM, the host's vCPU/memory, whether the
3
+ The approved memory classes and enabled layouts live in ``system_tiers``.
4
+ These records retain existing behavior until consumers adopt that contract;
5
+ in particular, these Tier 3/4 hardware rows do not define their memory classes.
6
+ `SYSTEM_SPECS` records the marketing GPU name, its VRAM, the host's vCPU/memory, whether the
5
7
  tier is provisionable on the deployable fleet today, and (internal-only) the
6
8
  AWS instance type behind it. Nothing *here* schedules anything — this module
7
9
  is a catalog — but the tier a job names is scheduled against: the control
@@ -45,6 +45,8 @@ class TaskProtocol(Protocol):
45
45
  physics, then calls ``on_post_physics_step()`` before collecting dones,
46
46
  rewards, observations, and a pre-reset recording snapshot. It resets
47
47
  environments whose episodes ended after that snapshot.
48
+ On a step where a copy resets, ``get_observations()`` can run twice, before
49
+ and after reset; it must have no side effects or be idempotent.
48
50
  """
49
51
 
50
52
  observation_dim: int
@@ -194,3 +196,14 @@ class EngineTaskProtocol(TaskProtocol, Protocol):
194
196
  command changes.
195
197
  """
196
198
  ...
199
+
200
+ def update_markers(self) -> None:
201
+ """Write the poses or points of markers that follow the simulation.
202
+
203
+ Called only just before a live viewer or a recording reads the markers,
204
+ at their rate and never on every step, so a training run without a
205
+ viewer pays nothing for them. Read the current state; never change
206
+ state, draw random values or write an observation, reward or action
207
+ here. The default does nothing.
208
+ """
209
+ return None
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: simulo-interfaces
3
- Version: 0.25.0
3
+ Version: 0.26.0
4
4
  Summary: Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime.
5
5
  Author-email: Simulo Team <team@simulo.ai>
6
6
  License: BSD-3-Clause
@@ -28,7 +28,7 @@ Classifier: Typing :: Typed
28
28
  Requires-Python: >=3.11
29
29
  Description-Content-Type: text/markdown
30
30
  Provides-Extra: dev
31
- Requires-Dist: black==26.5.1; extra == "dev"
31
+ Requires-Dist: black==26.10.1; extra == "dev"
32
32
  Requires-Dist: isort==8.0.1; extra == "dev"
33
33
  Requires-Dist: ruff==0.15.21; extra == "dev"
34
34
  Requires-Dist: mypy==2.3.0; extra == "dev"
@@ -46,7 +46,9 @@ src/simulo/interfaces/platform/policy_checkpoint.py
46
46
  src/simulo/interfaces/platform/preview.py
47
47
  src/simulo/interfaces/platform/runs.py
48
48
  src/simulo/interfaces/platform/runtime.py
49
+ src/simulo/interfaces/platform/runtimes.py
49
50
  src/simulo/interfaces/platform/submit.py
51
+ src/simulo/interfaces/platform/system_tiers.py
50
52
  src/simulo/interfaces/platform/systems.py
51
53
  src/simulo/interfaces/platform/volume.py
52
54
  src/simulo/interfaces/runtime/__init__.py
@@ -1,6 +1,6 @@
1
1
 
2
2
  [dev]
3
- black==26.5.1
3
+ black==26.10.1
4
4
  isort==8.0.1
5
5
  ruff==0.15.21
6
6
  mypy==2.3.0