simulo-interfaces 0.4.0__tar.gz → 0.6.0__tar.gz

{simulo_interfaces-0.4.0/src/simulo_interfaces.egg-info → simulo_interfaces-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.4.0
+Version: 0.6.0
 Summary: Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause

{simulo_interfaces-0.4.0 → simulo_interfaces-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.4.0"
+version = "0.6.0"
 description = "Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package."
 readme = "PYPI.md"
 requires-python = ">=3.11"

{simulo_interfaces-0.4.0 → simulo_interfaces-0.6.0}/src/simulo/interfaces/ids.py

@@ -19,3 +19,5 @@ ResourceUri = NewType("ResourceUri", str)  # e.g. "robot/so-arm-100:v3"
 Digest = NewType("Digest", str)  # content-addressed package source digest
 RecordingId = NewType("RecordingId", str)  # a job-produced MCAP recording (PR-0 wire contract)
 WorkerId = NewType("WorkerId", str)  # a claiming worker process (PR-0 wire contract)
+AssetId = NewType("AssetId", str)  # a catalog asset (USD Asset Catalogs wire contract, PR-1)
+AssetVersionId = NewType("AssetVersionId", str)  # one immutable asset version (PR-1)

simulo_interfaces-0.6.0/src/simulo/interfaces/platform/__init__.py

@@ -0,0 +1,277 @@
+"""Part B — platform/workspace domain contracts.
+
+Wire-stable enums, frozen domain dataclasses (Project, Package, Job, Resource,
+Checkpoint, TrainedModel, Tag), and the cloud-execution Protocols (App, Runtime,
+Asset, Volume, job callbacks, and debug/replay/visualization sessions). All
+implementation-free (Rule #11) — concrete behaviour lives in the future
+``simulo`` client and the ``simulo-backend`` SDK.
+"""
+
+from simulo.interfaces.platform.app import AppProtocol, JobFunctionProtocol, Mount
+from simulo.interfaces.platform.asset import AssetProtocol
+from simulo.interfaces.platform.asset_catalog import (
+    ADMIN_ASSET_ROUTE_TEMPLATE,
+    ADMIN_ASSET_VERSION_BY_NUMBER_ROUTE_TEMPLATE,
+    ADMIN_ASSET_VERSION_DEPRECATE_ROUTE_TEMPLATE,
+    ADMIN_ASSET_VERSION_ROUTE_TEMPLATE,
+    ADMIN_ASSET_VERSION_UPLOAD_COMPLETE_ROUTE_TEMPLATE,
+    ADMIN_ASSET_VERSION_UPLOAD_PARTS_ROUTE_TEMPLATE,
+    ADMIN_ASSET_VERSION_VALIDATE_ROUTE_TEMPLATE,
+    ADMIN_ASSET_VERSIONS_ROUTE_TEMPLATE,
+    ASSET_BASE_MODES,
+    ASSET_CORRUPT_CODE,
+    ASSET_DIGEST_MISMATCH_CODE,
+    ASSET_FACTS_SCHEMA_VERSION,
+    ASSET_KINDS,
+    ASSET_LIFECYCLE_ROLES,
+    ASSET_LIST_SCOPES,
+    ASSET_MISSING_CODE,
+    ASSET_NOT_EXPORTABLE_CODE,
+    ASSET_NOT_FOUND_CODE,
+    ASSET_ORIGIN_TYPES,
+    ASSET_PUBLISH_ROLES,
+    ASSET_RECONVERT_ROUTE_TEMPLATE,
+    ASSET_ROUTE_TEMPLATE,
+    ASSET_SLUG_PATTERN,
+    ASSET_SOURCE_FORMATS,
+    ASSET_UPLOAD_PART_BYTES,
+    ASSET_VALIDATION_VERDICTS,
+    ASSET_VERSION_BY_NUMBER_ROUTE_TEMPLATE,
+    ASSET_VERSION_DEPRECATE_ROUTE_TEMPLATE,
+    ASSET_VERSION_DOWNLOAD_ROUTE_TEMPLATE,
+    ASSET_VERSION_REPORT_ROUTE_TEMPLATE,
+    ASSET_VERSION_ROUTE_TEMPLATE,
+    ASSET_VERSION_STATUSES,
+    ASSET_VERSION_UPLOAD_COMPLETE_ROUTE_TEMPLATE,
+    ASSET_VERSION_UPLOAD_PARTS_ROUTE_TEMPLATE,
+    ASSET_VERSION_UPLOAD_ROUTE_TEMPLATE,
+    ASSET_VERSION_VALIDATE_ROUTE_TEMPLATE,
+    ASSET_VERSIONS_ROUTE_TEMPLATE,
+    ASSETS_FIELD,
+    ASSETS_RESOLVE_ROUTE,
+    ASSETS_ROUTE,
+    ASSETS_USAGE_ROUTE,
+    DEFAULT_ASSET_RUNTIME,
+    GLOBAL_ASSET_PUBLISHER,
+    MAX_ASSET_FILES,
+    MAX_ASSET_REF_CHARS,
+    MAX_ASSET_VERSION_BYTES,
+    MAX_ASSETS_RESOLVE_BATCH,
+    RESERVED_ASSET_PUBLISHERS,
+    WORKER_JOB_ASSET_VALIDATION_PRESIGN_ROUTE_TEMPLATE,
+    WORKER_JOB_ASSET_VALIDATION_ROUTE_TEMPLATE,
+    AssetPublishOptions,
+    AssetRecord,
+    AssetsResolveRequest,
+    AssetsResolveResponse,
+    AssetValidationFinalize,
+    AssetVersionRecord,
+    ConvertedArchive,
+    FileManifestEntry,
+    ParsedAssetRef,
+    ResolvedAssetPin,
+    ResolveMiss,
+    UploadPartSpec,
+    WorkerAssetInfo,
+    format_asset_ref,
+    parse_asset_ref,
+)
+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, TrainedModel
+from simulo.interfaces.platform.enums import ArtifactKind, JobStatus, ResourceKind, ResumePolicy
+from simulo.interfaces.platform.runs import (
+    JOB_CANCEL_ROUTE_TEMPLATE,
+    JOB_LOGS_ROUTE_TEMPLATE,
+    JOB_RESULT_ROUTE_TEMPLATE,
+    JOB_ROUTE_TEMPLATE,
+    JOBS_API_DEFAULT_PORT,
+    JOBS_ROUTE,
+    LOG_CHUNK_MAX_BYTES,
+    LOG_TAIL_MAX_BYTES,
+    TERMINAL_JOB_STATUSES,
+    JobRecord,
+)
+from simulo.interfaces.platform.runtime import RuntimeProtocol
+from simulo.interfaces.platform.submit import (
+    JOB_MODEL_DOWNLOAD_ROUTE_TEMPLATE,
+    JOB_MODEL_ROUTE_TEMPLATE,
+    JOB_MODELS_ROUTE_TEMPLATE,
+    JOB_RECORDING_DOWNLOAD_ROUTE_TEMPLATE,
+    JOB_RECORDINGS_ROUTE_TEMPLATE,
+    MAX_COMPLETE_MESSAGE_CHARS,
+    MAX_COMPLETE_REASON_CODE_CHARS,
+    MAX_LOG_CHUNK_BYTES,
+    MAX_LOG_TOTAL_BYTES,
+    MAX_PACKAGE_BYTES,
+    MAX_RESULT_BYTES,
+    MAX_SEED_REF_CHARS,
+    MODEL_KINDS,
+    PACKAGE_ARCHIVE_ROUTE_TEMPLATE,
+    PACKAGES_ROUTE,
+    PLATFORM_PINNED_PACKAGES,
+    RESERVED_RUNTIME_ENV_KEYS,
+    RESERVED_RUNTIME_ENV_PREFIXES,
+    SEED_JOB_REF_GRAMMAR,
+    SEED_SOURCE_CONFLICT_CODE,
+    SEED_SOURCE_FIELDS,
+    WORKER_CLAIM_ROUTE,
+    WORKER_JOB_COMPLETE_ROUTE_TEMPLATE,
+    WORKER_JOB_HEARTBEAT_ROUTE_TEMPLATE,
+    WORKER_JOB_LOGS_ROUTE_TEMPLATE,
+    WORKER_JOB_MODELS_PRESIGN_ROUTE_TEMPLATE,
+    WORKER_JOB_MODELS_ROUTE_TEMPLATE,
+    WORKER_JOB_RECORDINGS_PRESIGN_ROUTE_TEMPLATE,
+    WORKER_JOB_RECORDINGS_ROUTE_TEMPLATE,
+    WORKER_LEASE_HEADER,
+    ModelRecord,
+    RecordingRecord,
+    canonical_pypi_name,
+    is_platform_pinned,
+)
+from simulo.interfaces.platform.volume import VolumeProtocol
+
+__all__ = [
+    # enums
+    "JobStatus",
+    "ResumePolicy",
+    "ResourceKind",
+    "ArtifactKind",
+    # domain dataclasses
+    "Tag",
+    "Project",
+    "Package",
+    "Resource",
+    "Job",
+    "Checkpoint",
+    "TrainedModel",
+    # job-run contract (run record schema + jobs HTTP API shape)
+    "JobRecord",
+    "TERMINAL_JOB_STATUSES",
+    "JOBS_API_DEFAULT_PORT",
+    "JOBS_ROUTE",
+    "JOB_ROUTE_TEMPLATE",
+    "JOB_CANCEL_ROUTE_TEMPLATE",
+    "JOB_LOGS_ROUTE_TEMPLATE",
+    "JOB_RESULT_ROUTE_TEMPLATE",
+    "LOG_CHUNK_MAX_BYTES",
+    "LOG_TAIL_MAX_BYTES",
+    # submit / worker / recordings wire contract (PR-0)
+    "PACKAGES_ROUTE",
+    "PACKAGE_ARCHIVE_ROUTE_TEMPLATE",
+    "JOB_RECORDINGS_ROUTE_TEMPLATE",
+    "JOB_RECORDING_DOWNLOAD_ROUTE_TEMPLATE",
+    "JOB_MODELS_ROUTE_TEMPLATE",
+    "JOB_MODEL_ROUTE_TEMPLATE",
+    "JOB_MODEL_DOWNLOAD_ROUTE_TEMPLATE",
+    "WORKER_CLAIM_ROUTE",
+    "WORKER_JOB_LOGS_ROUTE_TEMPLATE",
+    "WORKER_JOB_HEARTBEAT_ROUTE_TEMPLATE",
+    "WORKER_JOB_COMPLETE_ROUTE_TEMPLATE",
+    "WORKER_JOB_RECORDINGS_PRESIGN_ROUTE_TEMPLATE",
+    "WORKER_JOB_RECORDINGS_ROUTE_TEMPLATE",
+    "WORKER_JOB_MODELS_PRESIGN_ROUTE_TEMPLATE",
+    "WORKER_JOB_MODELS_ROUTE_TEMPLATE",
+    "WORKER_LEASE_HEADER",
+    "MAX_PACKAGE_BYTES",
+    "MAX_LOG_CHUNK_BYTES",
+    "MAX_LOG_TOTAL_BYTES",
+    "MAX_RESULT_BYTES",
+    "MAX_COMPLETE_MESSAGE_CHARS",
+    "MAX_COMPLETE_REASON_CODE_CHARS",
+    "MODEL_KINDS",
+    "ModelRecord",
+    "RecordingRecord",
+    "RESERVED_RUNTIME_ENV_KEYS",
+    "RESERVED_RUNTIME_ENV_PREFIXES",
+    "PLATFORM_PINNED_PACKAGES",
+    "is_platform_pinned",
+    "canonical_pypi_name",
+    # explicit-run-intent plan: submit-time seed source (additive)
+    "SEED_SOURCE_FIELDS",
+    "SEED_SOURCE_CONFLICT_CODE",
+    "SEED_JOB_REF_GRAMMAR",
+    "MAX_SEED_REF_CHARS",
+    # USD Asset Catalogs wire contract (PR-1) — ref grammar
+    "parse_asset_ref",
+    "format_asset_ref",
+    "ParsedAssetRef",
+    "ASSET_KINDS",
+    "ASSET_SLUG_PATTERN",
+    "RESERVED_ASSET_PUBLISHERS",
+    "GLOBAL_ASSET_PUBLISHER",
+    # asset catalog — customer routes
+    "ASSETS_ROUTE",
+    "ASSETS_RESOLVE_ROUTE",
+    "ASSETS_USAGE_ROUTE",
+    "ASSET_ROUTE_TEMPLATE",
+    "ASSET_VERSIONS_ROUTE_TEMPLATE",
+    "ASSET_RECONVERT_ROUTE_TEMPLATE",
+    "ASSET_VERSION_DEPRECATE_ROUTE_TEMPLATE",
+    "ASSET_VERSION_BY_NUMBER_ROUTE_TEMPLATE",
+    "ASSET_VERSION_ROUTE_TEMPLATE",
+    "ASSET_VERSION_UPLOAD_PARTS_ROUTE_TEMPLATE",
+    "ASSET_VERSION_UPLOAD_ROUTE_TEMPLATE",
+    "ASSET_VERSION_UPLOAD_COMPLETE_ROUTE_TEMPLATE",
+    "ASSET_VERSION_VALIDATE_ROUTE_TEMPLATE",
+    "ASSET_VERSION_REPORT_ROUTE_TEMPLATE",
+    "ASSET_VERSION_DOWNLOAD_ROUTE_TEMPLATE",
+    # asset catalog — admin routes
+    "ADMIN_ASSET_VERSIONS_ROUTE_TEMPLATE",
+    "ADMIN_ASSET_VERSION_UPLOAD_PARTS_ROUTE_TEMPLATE",
+    "ADMIN_ASSET_VERSION_UPLOAD_COMPLETE_ROUTE_TEMPLATE",
+    "ADMIN_ASSET_VERSION_VALIDATE_ROUTE_TEMPLATE",
+    "ADMIN_ASSET_VERSION_DEPRECATE_ROUTE_TEMPLATE",
+    "ADMIN_ASSET_VERSION_BY_NUMBER_ROUTE_TEMPLATE",
+    "ADMIN_ASSET_ROUTE_TEMPLATE",
+    "ADMIN_ASSET_VERSION_ROUTE_TEMPLATE",
+    # asset catalog — worker routes
+    "WORKER_JOB_ASSET_VALIDATION_PRESIGN_ROUTE_TEMPLATE",
+    "WORKER_JOB_ASSET_VALIDATION_ROUTE_TEMPLATE",
+    # asset catalog — job-submit field, roles, domains, caps, facts, codes
+    "ASSETS_FIELD",
+    "ASSET_PUBLISH_ROLES",
+    "ASSET_LIFECYCLE_ROLES",
+    "ASSET_VERSION_STATUSES",
+    "ASSET_VALIDATION_VERDICTS",
+    "ASSET_SOURCE_FORMATS",
+    "ASSET_BASE_MODES",
+    "ASSET_ORIGIN_TYPES",
+    "ASSET_LIST_SCOPES",
+    "MAX_ASSET_VERSION_BYTES",
+    "MAX_ASSET_FILES",
+    "MAX_ASSET_REF_CHARS",
+    "MAX_ASSETS_RESOLVE_BATCH",
+    "DEFAULT_ASSET_RUNTIME",
+    "ASSET_UPLOAD_PART_BYTES",
+    "ASSET_FACTS_SCHEMA_VERSION",
+    "ASSET_NOT_EXPORTABLE_CODE",
+    "ASSET_MISSING_CODE",
+    "ASSET_DIGEST_MISMATCH_CODE",
+    "ASSET_CORRUPT_CODE",
+    "ASSET_NOT_FOUND_CODE",
+    # asset catalog — wire dataclasses
+    "FileManifestEntry",
+    "AssetRecord",
+    "AssetVersionRecord",
+    "UploadPartSpec",
+    "ResolvedAssetPin",
+    "ResolveMiss",
+    "AssetsResolveRequest",
+    "AssetsResolveResponse",
+    "WorkerAssetInfo",
+    "ConvertedArchive",
+    "AssetValidationFinalize",
+    "AssetPublishOptions",
+    # protocols
+    "RuntimeProtocol",
+    "AssetProtocol",
+    "VolumeProtocol",
+    "JobCallbackProtocol",
+    "JobFunctionProtocol",
+    "AppProtocol",
+    "Mount",
+    "DebugSessionProtocol",
+    "ReplaySessionProtocol",
+    "VisualizationSessionProtocol",
+]

simulo_interfaces-0.6.0/src/simulo/interfaces/platform/app.py

@@ -0,0 +1,76 @@
+"""User-facing job-container Protocols (Part B) — ``App`` / ``@app.job`` surface."""
+
+from typing import Callable, Mapping, Optional, Protocol, Sequence, TypeVar, Union, overload, runtime_checkable
+
+from simulo.interfaces.ids import JobId
+from simulo.interfaces.platform.asset import AssetProtocol
+from simulo.interfaces.platform.callbacks import JobCallbackProtocol
+from simulo.interfaces.platform.enums import ResumePolicy
+from simulo.interfaces.platform.runtime import RuntimeProtocol
+from simulo.interfaces.platform.volume import VolumeProtocol
+
+F = TypeVar("F", bound=Callable[..., object])
+
+Mount = Union[AssetProtocol, VolumeProtocol]
+"""What can be mounted into a job: a read-only asset or a writable volume."""
+
+
+@runtime_checkable
+class JobFunctionProtocol(Protocol):
+    """The contract of what ``@app.job`` returns: the user's original function, wrapped.
+
+    Decoration is source-preserving — calling the wrapper runs the original
+    body; ``submit()`` packages it for the platform instead.
+    """
+
+    def __call__(self, *args: object, **kwargs: object) -> object:
+        """Run the original job body in-process, exactly as if it were undecorated."""
+        ...
+
+    def submit(self, *args: object, **kwargs: object) -> JobId:
+        """Submit the job with the given keyword arguments; return the new job's id."""
+        ...
+
+
+@runtime_checkable
+class AppProtocol(Protocol):
+    """The contract of the user-facing job container: ``app = simulo.App(name, mounts={...})``.
+
+    ``runtime`` is optional at construction — an app defaults to the platform's
+    default Simulo runtime and may pick a different curated one via ``runtime=``.
+    """
+
+    @property
+    def name(self) -> str:
+        """The app's name, as passed at construction."""
+        ...
+
+    @property
+    def runtime(self) -> RuntimeProtocol:
+        """The runtime envelope every job of this app executes in."""
+        ...
+
+    @property
+    def mounts(self) -> Mapping[str, Mount]:
+        """The assets/volumes mounted into every job of this app, by name."""
+        ...
+
+    @overload
+    def job(self, fn: F) -> JobFunctionProtocol: ...
+    @overload
+    def job(
+        self, *, callbacks: Sequence[JobCallbackProtocol] = ..., resume: ResumePolicy = ...
+    ) -> Callable[[F], JobFunctionProtocol]: ...
+    def job(
+        self,
+        fn: Optional[F] = None,
+        *,
+        callbacks: Sequence[JobCallbackProtocol] = (),
+        resume: ResumePolicy = ResumePolicy.AUTO,
+    ) -> Union[JobFunctionProtocol, Callable[[F], JobFunctionProtocol]]:
+        """Register a function as a job of this app (usable bare or with keyword options)."""
+        ...
+
+    def local_entrypoint(self, fn: F) -> F:
+        """Register the function ``simulo run`` invokes on the user's machine."""
+        ...

{simulo_interfaces-0.4.0 → simulo_interfaces-0.6.0}/src/simulo/interfaces/platform/asset.py

@@ -8,6 +8,12 @@ class AssetProtocol(Protocol):
     """Read-only mounted cloud resource handle (Rule #6). FORWARD.
 
     Distinct from ``simulo.core.asset.Asset`` (a USD/URDF simulation asset).
+
+    This is the user-facing *handle* protocol; the asset-catalog **wire**
+    contract (ref grammar, routes, caps, wire dataclasses) lives in
+    ``simulo.interfaces.platform.asset_catalog`` — an implementation of
+    :meth:`from_registry` consumes that module's ``parse_asset_ref`` to
+    interpret ``uri``. The two modules stay decoupled (no import cycle).
     """
 
     @classmethod