simulo-interfaces 0.21.0__tar.gz → 0.22.0__tar.gz

{simulo_interfaces-0.21.0/src/simulo_interfaces.egg-info → simulo_interfaces-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.21.0
+Version: 0.22.0
 Summary: Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause

{simulo_interfaces-0.21.0 → simulo_interfaces-0.22.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.21.0"
+version = "0.22.0"
 description = "Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime."
 readme = "PYPI.md"
 requires-python = ">=3.11"

{simulo_interfaces-0.21.0 → simulo_interfaces-0.22.0}/src/simulo/interfaces/__init__.py

@@ -19,6 +19,7 @@ namespace that ``simulo-backend`` also contributes to; it ships NO
 """
 
 from simulo.interfaces import platform, runtime
+from simulo.interfaces.authoring import PolicyCheckpoint
 from simulo.interfaces.exceptions import (
     ContractViolationError,
     ImportResolutionError,
@@ -50,12 +51,15 @@ from simulo.interfaces.ids import (
     policy_id_for_job,
 )
 from simulo.interfaces.platform.enums import JobType
+from simulo.interfaces.runtime import PolicyNetworkProtocol
 
 __all__ = [
     # subpackages
     "platform",
     "runtime",
     "JobType",
+    "PolicyCheckpoint",
+    "PolicyNetworkProtocol",
     # exception hierarchy
     "SimuloError",
     "ContractViolationError",

{simulo_interfaces-0.21.0 → simulo_interfaces-0.22.0}/src/simulo/interfaces/authoring/__init__.py

@@ -41,13 +41,14 @@ waves add the remaining RELOCATE-classified types and MIRROR Protocols.
 **R-C3 is the hard constraint on everything that lands here:** no module in
 this package — or anywhere else in ``simulo-interfaces`` — may import
 ``simulo.core``, ``simulo.backend``, or the thin client's private internal
-package, at import time or at call time (the ``Scene`` trap: zero torch
-imports, but call-time imports of torch-coupled ``core`` modules deep inside a
-method body). Guarded by ``tests/test_no_core_dependency.py`` in this package —
-both a static import-statement guard and a runtime ``sys.modules`` check that
-imports every submodule AND instantiates/calls the relocated API, because the
-static guard alone cannot see ``from simulo import core``, dynamic access, or a
-call-time-only import buried in a method body.
+package at import time. Calls must remain dependency-free too (the ``Scene``
+trap), with one explicit execution-only bridge: ``PolicyCheckpoint.load()``
+lazily imports ``simulo.core.policy.load_policy_network`` inside a job and
+raises the documented submit-time error when the backend is absent. Guarded by
+``tests/test_no_core_dependency.py`` in this package — both a static
+import-statement guard and isolated runtime checks that exercise the relocated
+API, prove ordinary imports remain backend-free, and prove the loader fails
+clearly in a submit-only installation.
 
 Two relocation mechanisms select which types land here and how (see the derived
 plan for the full worked example and rejected alternatives):
@@ -87,6 +88,7 @@ docstring, is the source of truth for what lands here and when.
 
 from simulo.interfaces.authoring.actuator import ActuatorProtocol
 from simulo.interfaces.authoring.asset import AssetSource, URDFAsset, USDAsset
+from simulo.interfaces.authoring.checkpoint import PolicyCheckpoint
 from simulo.interfaces.authoring.entity import AssetEntity, Entity
 from simulo.interfaces.authoring.light import DistantLight, DomeLight, Light, LightConfig
 from simulo.interfaces.authoring.materials import Material, SurfaceMaterial
@@ -171,6 +173,8 @@ __all__ = [
     # record (RELOCATED Wave C4 — the MCAP recording config; its helper
     # functions stay importable from ``simulo.interfaces.authoring.record``)
     "RecordConfig",
+    # injected policy input (dependency-free; loading is deferred to execution)
+    "PolicyCheckpoint",
     # visual
     "VisualMarkerBase",
     "AxesMarker",

simulo_interfaces-0.22.0/src/simulo/interfaces/authoring/checkpoint.py

@@ -0,0 +1,84 @@
+"""Dependency-free handle for a policy checkpoint injected into a job."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from importlib import import_module
+from pathlib import Path
+from typing import Any, cast
+
+from simulo.interfaces.runtime.policy import PolicyNetworkProtocol
+
+
+@dataclass(frozen=True)
+class PolicyCheckpoint:
+    """A resolved policy checkpoint supplied to a play or evaluation job.
+
+    The contract contains only standard-library values. Loading the policy is
+    deliberately deferred until execution, where ``simulo-backend`` provides
+    the concrete policy-network loader.
+    """
+
+    checkpoint: str
+    policy_id: str
+    kind: str
+    path: Path
+    meta: Mapping[str, Any]
+
+    @property
+    def iteration(self) -> int:
+        """Training iteration stored in the checkpoint sidecar."""
+
+        return cast(int, self.meta["completed_iterations"])
+
+    @property
+    def max_iterations(self) -> int:
+        """Configured training limit stored in the checkpoint sidecar."""
+
+        return cast(int, self.meta["max_iterations"])
+
+    @property
+    def reward(self) -> float | None:
+        """Best-checkpoint reward, or ``None`` when the sidecar has none."""
+
+        return cast(float | None, self.meta.get("reward"))
+
+    @property
+    def obs_dim(self) -> int:
+        """Observation width used to train the checkpoint."""
+
+        return cast(int, self.meta["obs_dim"])
+
+    @property
+    def act_dim(self) -> int:
+        """Action width produced by the checkpoint."""
+
+        return cast(int, self.meta["act_dim"])
+
+    @property
+    def task_name(self) -> str:
+        """Name of the task class used for training, if the sidecar has it."""
+
+        return cast(str, self.meta.get("task_name", "unknown"))
+
+    @property
+    def task_digest(self) -> str:
+        """Digest of the file that defined the training task, if available."""
+
+        return cast(str, self.meta.get("task_digest", "unknown"))
+
+    def load(self, device: str = "cuda") -> PolicyNetworkProtocol:
+        """Load the checkpoint as a policy network inside a Simulo job."""
+
+        try:
+            policy_module = import_module("simulo.core.policy")
+        except ImportError as exc:
+            raise RuntimeError(
+                "PolicyCheckpoint.load() runs inside a job on Simulo; it is not available at submit."
+            ) from exc
+        loader = getattr(policy_module, "load_policy_network")
+        return cast(PolicyNetworkProtocol, loader(self, device=device))
+
+
+__all__ = ["PolicyCheckpoint"]

{simulo_interfaces-0.21.0 → simulo_interfaces-0.22.0}/src/simulo/interfaces/authoring/record.py

@@ -194,7 +194,7 @@ class RecordConfig:
     mitigation depends on the tri-state.
     """
 
-    output_path: Union[str, "os.PathLike[str]", Path]
+    output_path: Optional[Union[str, "os.PathLike[str]", Path]] = None
 
     # Identity
     run_id: Optional[str] = None

{simulo_interfaces-0.21.0 → simulo_interfaces-0.22.0}/src/simulo/interfaces/platform/__init__.py

@@ -71,6 +71,8 @@ from simulo.interfaces.platform.callbacks import JobCallbackProtocol
 from simulo.interfaces.platform.debug import DebugSessionProtocol, ReplaySessionProtocol, VisualizationSessionProtocol
 from simulo.interfaces.platform.domain import Checkpoint, Job, Package, Project, Resource, Tag
 from simulo.interfaces.platform.enums import (
+    INPUT_CHECKPOINT_JOB_TYPES,
+    INPUT_CHECKPOINT_REQUIRED_JOB_TYPES,
     UNAVAILABLE_JOB_TYPES,
     USER_SUBMITTABLE_JOB_TYPES,
     JobType,
@@ -117,50 +119,29 @@ from simulo.interfaces.platform.manifest import (
     PreflightResponse,
     RuntimeManifest,
 )
-from simulo.interfaces.platform.outputs import (
-    DECLARED_OUTPUT_MISSING_CODE,
-    JOB_OUTPUT_DOWNLOAD_ROUTE_TEMPLATE,
-    JOB_OUTPUTS_ROUTE_TEMPLATE,
-    MAX_OUTPUT_FLAG_CODE_CHARS,
-    MAX_OUTPUT_FLAG_DETAIL_CHARS,
-    MAX_OUTPUT_NAME_BYTES,
-    MAX_OUTPUT_PATH_BYTES,
-    MAX_OUTPUTS_BYTES,
-    OUTPUT_DROPPED_DETAILS,
-    OUTPUT_FLAG_ANOMALY,
-    OUTPUT_FLAG_OUTPUT_DROPPED,
-    OUTPUTS_UNDELIVERED_CODE,
-    WORKER_JOB_ARTIFACTS_PRESIGN_ROUTE_TEMPLATE,
-    WORKER_JOB_ARTIFACTS_ROUTE_TEMPLATE,
-    JobOutputsSummary,
-    Output,
-    OutputDeclaration,
-    OutputFlag,
-    OutputRecord,
-)
-from simulo.interfaces.platform.policy_bundle import (
+from simulo.interfaces.platform.onnx_bundle import (
     EXPORT_JOB_TYPE,
     EXPORT_VALIDATION_JOB_TYPE,
     JOB_EXPORTS_ROUTE_TEMPLATE,
-    MAX_POLICY_BUNDLE_UNCOMPRESSED_BYTES,
+    MAX_ONNX_BUNDLE_UNCOMPRESSED_BYTES,
     MAX_POLICY_NAME_TOKEN_CHARS,
-    POLICY_BUNDLE_ACTION_SCHEMA_FILE,
-    POLICY_BUNDLE_ARCHIVE_NAME_TEMPLATE,
-    POLICY_BUNDLE_FILES,
-    POLICY_BUNDLE_MANIFEST_FILE,
-    POLICY_BUNDLE_MODEL_ONNX_FILE,
-    POLICY_BUNDLE_MODEL_PT_FILE,
-    POLICY_BUNDLE_NORMALIZATION_FILE,
-    POLICY_BUNDLE_OBSERVATION_SCHEMA_FILE,
-    POLICY_BUNDLE_OPTIONAL_FILES,
-    POLICY_BUNDLE_OUTPUT_KIND,
-    POLICY_BUNDLE_README_FILE,
-    POLICY_BUNDLE_REQUIRED_FILES,
-    POLICY_BUNDLE_REQUIREMENTS_FILE,
-    POLICY_BUNDLE_ROOT_DIR_TEMPLATE,
-    POLICY_BUNDLE_SCHEMA_VERSION,
-    POLICY_BUNDLE_TEST_VECTORS_FILE,
-    POLICY_BUNDLE_VERIFY_FILE,
+    ONNX_BUNDLE_ACTION_SCHEMA_FILE,
+    ONNX_BUNDLE_ARCHIVE_NAME_TEMPLATE,
+    ONNX_BUNDLE_FILES,
+    ONNX_BUNDLE_MANIFEST_FILE,
+    ONNX_BUNDLE_MODEL_ONNX_FILE,
+    ONNX_BUNDLE_MODEL_PT_FILE,
+    ONNX_BUNDLE_NORMALIZATION_FILE,
+    ONNX_BUNDLE_OBSERVATION_SCHEMA_FILE,
+    ONNX_BUNDLE_OPTIONAL_FILES,
+    ONNX_BUNDLE_OUTPUT_KIND,
+    ONNX_BUNDLE_README_FILE,
+    ONNX_BUNDLE_REQUIRED_FILES,
+    ONNX_BUNDLE_REQUIREMENTS_FILE,
+    ONNX_BUNDLE_ROOT_DIR_TEMPLATE,
+    ONNX_BUNDLE_SCHEMA_VERSION,
+    ONNX_BUNDLE_TEST_VECTORS_FILE,
+    ONNX_BUNDLE_VERIFY_FILE,
     POLICY_EQUIVALENCE_ABS_TOLERANCE,
     POLICY_EQUIVALENCE_REL_TOLERANCE,
     POLICY_GOLDEN_VECTOR_COUNT,
@@ -168,12 +149,12 @@ from simulo.interfaces.platform.policy_bundle import (
     POLICY_TENSOR_DTYPES,
     POLICY_TEST_VECTOR_EXPECTED_OUTPUTS_KEY,
     POLICY_TEST_VECTOR_INPUTS_KEY,
-    SUPPORTED_POLICY_BUNDLE_SCHEMA_MAJORS,
+    SUPPORTED_ONNX_BUNDLE_SCHEMA_MAJORS,
     UNKNOWN,
+    OnnxBundleManifest,
     PolicyActionComponent,
     PolicyActionSchema,
     PolicyBounds,
-    PolicyBundleManifest,
     PolicyEquivalenceSpec,
     PolicyExportFailureReason,
     PolicyExportFormat,
@@ -186,12 +167,34 @@ from simulo.interfaces.platform.policy_bundle import (
     PolicySourceSpec,
     PolicyTensorSpec,
     Unknown,
-    is_supported_policy_bundle_schema,
-    policy_bundle_archive_name,
-    policy_bundle_root_dir,
-    policy_bundle_schema_major,
+    is_supported_onnx_bundle_schema,
+    onnx_bundle_archive_name,
+    onnx_bundle_root_dir,
+    onnx_bundle_schema_major,
     policy_name_token,
-    validate_policy_bundle,
+    validate_onnx_bundle,
+)
+from simulo.interfaces.platform.outputs import (
+    DECLARED_OUTPUT_MISSING_CODE,
+    JOB_OUTPUT_DOWNLOAD_ROUTE_TEMPLATE,
+    JOB_OUTPUTS_ROUTE_TEMPLATE,
+    MAX_OUTPUT_FLAG_CODE_CHARS,
+    MAX_OUTPUT_FLAG_DETAIL_CHARS,
+    MAX_OUTPUT_NAME_BYTES,
+    MAX_OUTPUT_PATH_BYTES,
+    MAX_OUTPUTS_BYTES,
+    OUTPUT_DROPPED_DETAILS,
+    OUTPUT_FLAG_ANOMALY,
+    OUTPUT_FLAG_OUTPUT_DROPPED,
+    OUTPUTS_UNDELIVERED_CODE,
+    WORKER_JOB_ARTIFACTS_PRESIGN_ROUTE_TEMPLATE,
+    WORKER_JOB_ARTIFACTS_ROUTE_TEMPLATE,
+    JobOutputsSummary,
+    Output,
+    OutputDeclaration,
+    OutputFlag,
+    OutputRecord,
+    tier0_declarations,
 )
 from simulo.interfaces.platform.preview import (
     PREVIEW_CHECKS,
@@ -289,6 +292,8 @@ __all__ = [
     "JobType",
     "USER_SUBMITTABLE_JOB_TYPES",
     "UNAVAILABLE_JOB_TYPES",
+    "INPUT_CHECKPOINT_JOB_TYPES",
+    "INPUT_CHECKPOINT_REQUIRED_JOB_TYPES",
     "OutputKind",
     "SystemType",
     # systems (GPU system-tier catalog, issue #1362)
@@ -343,6 +348,7 @@ __all__ = [
     # registration, projection row, completion announcement, routes, caps,
     # pinned wire codes
     "OutputDeclaration",
+    "tier0_declarations",
     "Output",
     "OutputRecord",
     "OutputFlag",
@@ -507,34 +513,34 @@ __all__ = [
     # bundle layout, naming rule, export routes/job type, equivalence
     # defaults, enums, explicit-unknown marker, manifest dataclasses, the
     # export-validation result, and the cross-file coherence check
-    "POLICY_BUNDLE_SCHEMA_VERSION",
-    "SUPPORTED_POLICY_BUNDLE_SCHEMA_MAJORS",
-    "policy_bundle_schema_major",
-    "is_supported_policy_bundle_schema",
-    "POLICY_BUNDLE_MODEL_ONNX_FILE",
-    "POLICY_BUNDLE_MODEL_PT_FILE",
-    "POLICY_BUNDLE_MANIFEST_FILE",
-    "POLICY_BUNDLE_OBSERVATION_SCHEMA_FILE",
-    "POLICY_BUNDLE_ACTION_SCHEMA_FILE",
-    "POLICY_BUNDLE_NORMALIZATION_FILE",
-    "POLICY_BUNDLE_TEST_VECTORS_FILE",
-    "POLICY_BUNDLE_VERIFY_FILE",
-    "POLICY_BUNDLE_REQUIREMENTS_FILE",
-    "POLICY_BUNDLE_README_FILE",
-    "POLICY_BUNDLE_FILES",
-    "POLICY_BUNDLE_REQUIRED_FILES",
-    "POLICY_BUNDLE_OPTIONAL_FILES",
-    "MAX_POLICY_BUNDLE_UNCOMPRESSED_BYTES",
+    "ONNX_BUNDLE_SCHEMA_VERSION",
+    "SUPPORTED_ONNX_BUNDLE_SCHEMA_MAJORS",
+    "onnx_bundle_schema_major",
+    "is_supported_onnx_bundle_schema",
+    "ONNX_BUNDLE_MODEL_ONNX_FILE",
+    "ONNX_BUNDLE_MODEL_PT_FILE",
+    "ONNX_BUNDLE_MANIFEST_FILE",
+    "ONNX_BUNDLE_OBSERVATION_SCHEMA_FILE",
+    "ONNX_BUNDLE_ACTION_SCHEMA_FILE",
+    "ONNX_BUNDLE_NORMALIZATION_FILE",
+    "ONNX_BUNDLE_TEST_VECTORS_FILE",
+    "ONNX_BUNDLE_VERIFY_FILE",
+    "ONNX_BUNDLE_REQUIREMENTS_FILE",
+    "ONNX_BUNDLE_README_FILE",
+    "ONNX_BUNDLE_FILES",
+    "ONNX_BUNDLE_REQUIRED_FILES",
+    "ONNX_BUNDLE_OPTIONAL_FILES",
+    "MAX_ONNX_BUNDLE_UNCOMPRESSED_BYTES",
     "POLICY_TEST_VECTOR_INPUTS_KEY",
     "POLICY_TEST_VECTOR_EXPECTED_OUTPUTS_KEY",
-    "POLICY_BUNDLE_OUTPUT_KIND",
-    "POLICY_BUNDLE_ROOT_DIR_TEMPLATE",
-    "POLICY_BUNDLE_ARCHIVE_NAME_TEMPLATE",
+    "ONNX_BUNDLE_OUTPUT_KIND",
+    "ONNX_BUNDLE_ROOT_DIR_TEMPLATE",
+    "ONNX_BUNDLE_ARCHIVE_NAME_TEMPLATE",
     "MAX_POLICY_NAME_TOKEN_CHARS",
     "POLICY_NAME_TOKEN_FALLBACK",
     "policy_name_token",
-    "policy_bundle_root_dir",
-    "policy_bundle_archive_name",
+    "onnx_bundle_root_dir",
+    "onnx_bundle_archive_name",
     "JOB_EXPORTS_ROUTE_TEMPLATE",
     "EXPORT_JOB_TYPE",
     "EXPORT_VALIDATION_JOB_TYPE",
@@ -555,11 +561,11 @@ __all__ = [
     "PolicyEquivalenceSpec",
     "PolicyObservationComponent",
     "PolicyActionComponent",
-    "PolicyBundleManifest",
+    "OnnxBundleManifest",
     "PolicyObservationSchema",
     "PolicyActionSchema",
     "PolicyNormalization",
-    "validate_policy_bundle",
+    "validate_onnx_bundle",
     # preview report wire contract — schema version, check names, and the
     # row/stage/report shapes the preview job returns
     "PREVIEW_REPORT_SCHEMA_VERSION",

{simulo_interfaces-0.21.0 → simulo_interfaces-0.22.0}/src/simulo/interfaces/platform/enums.py

@@ -19,10 +19,16 @@ class JobType(StrEnum):
 
 
 #: Types a user can submit today. Platform-owned jobs use the remaining types.
-USER_SUBMITTABLE_JOB_TYPES = frozenset({JobType.TRAIN})
+USER_SUBMITTABLE_JOB_TYPES = frozenset({JobType.PREVIEW, JobType.TRAIN, JobType.PLAY})
 
 #: Declared job types whose user-submission workflows are not available yet.
-UNAVAILABLE_JOB_TYPES = frozenset({JobType.PREVIEW, JobType.EVAL, JobType.PLAY})
+UNAVAILABLE_JOB_TYPES = frozenset({JobType.EVAL})
+
+#: Job types whose submission may carry an input policy checkpoint.
+INPUT_CHECKPOINT_JOB_TYPES = frozenset({JobType.TRAIN, JobType.PLAY, JobType.EVAL})
+
+#: Job types that cannot run without an input policy checkpoint.
+INPUT_CHECKPOINT_REQUIRED_JOB_TYPES = frozenset({JobType.PLAY, JobType.EVAL})
 
 
 class JobStatus(StrEnum):
@@ -143,7 +149,7 @@ class OutputKind(StrEnum):
     Training jobs publish this output through the policy checkpoint pipeline."""
 
     ONNX_BUNDLE = "onnx_bundle"
-    """A standalone ONNX policy bundle produced by an export job."""
+    """A standalone ONNX bundle produced by an export job."""
 
     LOG = "log"
     """The job's captured log stream."""