simulo-interfaces 0.1.0__tar.gz

simulo_interfaces-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: simulo-interfaces
+Version: 0.1.0
+Summary: Implementation-free contract layer for the Simulo platform — torch-free runtime/sim Protocols and platform/workspace domain contracts. Importable with no torch/numpy/gymnasium/Isaac installed.
+Author-email: Simulo Team <team@simulo.ai>
+License: BSD-3-Clause
+Project-URL: Homepage, https://simulo.ai
+Project-URL: Source, https://github.com/simulo-org/simulo-platform
+Keywords: robotics,contracts,protocols,interfaces,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
+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-interfaces
+
+The **implementation-free contract layer** for the Simulo platform. A single,
+stable, torch-free, **zero-runtime-dependency** package that both Simulo SDK
+distributions depend on:
+
+- `simulo-backend` — the cloud GPU SDK (torch + IsaacLab + Isaac Sim).
+- `simulo` — the future thin local client (no heavy deps).
+
+Because both distributions share these contracts, `simulo-interfaces` is the one
+place the runtime Protocols and the platform/workspace domain model are defined.
+
+## What it is
+
+A pure-stdlib set of `typing.Protocol` contracts, frozen dataclasses, enums,
+`NewType` identifiers, and an exception hierarchy. Nothing here does any work —
+it only describes shapes.
+
+## What it is NOT
+
+It imports **none** of: `torch`, `numpy`, `gymnasium`, IsaacLab / Isaac Sim, AWS
+SDKs, HTTP clients, or database drivers. It performs **no** I/O, persistence, or
+computation. It is **not** a dumping ground (Contract Rule #12) — only contracts
+shared by more than one distribution belong here.
+
+The central invariant (Contract Rule #11): this package must import on a laptop
+with no torch/numpy/gymnasium/Isaac installed. Two tests enforce it:
+`tests/test_import_without_torch.py` (no heavy module enters `sys.modules`) and
+`tests/test_no_heavy_deps.py` (zero unconditional `Requires-Dist`).
+
+## Two parts
+
+### Part A — `simulo.interfaces.runtime`
+
+Tensor-library-agnostic structural mirrors of the `simulo.core` runtime surface.
+Tensors are typed as `TensorLike` (an alias for `Any`) so the contracts never
+bind to a concrete tensor library.
+
+- `TaskProtocol`, `PolicyProtocol`, `TrainerProtocol`, `PlayerProtocol`
+- `LearningEnvProtocol`, `ScenarioProtocol`
+- `ObservationComponentProtocol`, `RewardComponentProtocol`,
+  `TerminationConditionProtocol`
+- `PolicyExporterProtocol` — the narrow *optional* export capability
+  (`export_policy(path) -> str`). Deliberately not a `TrainerProtocol` member:
+  a Protocol binds all implementations, and only some trainers (today
+  `simulo.core.trainer.RLTrainer`) can deliver a deterministic standalone
+  policy export. Consumers feature-detect with `isinstance(trainer,
+  PolicyExporterProtocol)`.
+
+### Part B — `simulo.interfaces.platform`
+
+The platform/workspace domain contracts:
+
+- **Enums** — `JobStatus`, `ResumePolicy`, `ResourceKind`, `ArtifactKind`.
+- **Domain dataclasses** (frozen, slotted, keyword-only) — `Tag`, `Project`,
+  `Package`, `Resource`, `Job`, `Checkpoint`, `TrainedModel`.
+- **Cloud-execution Protocols** — `AppProtocol`, `JobFunctionProtocol`,
+  `RuntimeProtocol`, `AssetProtocol`, `VolumeProtocol`, `JobCallbackProtocol`,
+  `DebugSessionProtocol`, `ReplaySessionProtocol`, `VisualizationSessionProtocol`.
+
+## Public import surface
+
+```python
+import simulo.interfaces as si
+
+# exceptions + ids re-exported at the top level
+si.SimuloError, si.ContractViolationError, si.JobFailedError
+si.ProjectId, si.JobId, si.ResourceUri, si.Digest
+
+# Part A
+from simulo.interfaces.runtime import TaskProtocol, PolicyProtocol, LearningEnvProtocol
+
+# Part B
+from simulo.interfaces.platform import (
+    JobStatus, ResumePolicy, ResourceKind, ArtifactKind,
+    Project, Package, Job, Resource, Checkpoint, TrainedModel, Tag,
+    AppProtocol, RuntimeProtocol, AssetProtocol, VolumeProtocol,
+)
+```
+
+## Conformance model
+
+The contracts are `typing.Protocol`s — implementers conform **structurally**, no
+inheritance required.
+
+- **Static** — implementers (e.g. `simulo-backend`) are type-checked against
+  these Protocols by mypy. That static assertion is the primary conformance
+  gate and lives in the **implementer** package, not here.
+- **Runtime** — every Protocol is `@runtime_checkable`, so `isinstance(obj,
+  SomeProtocol)` provides a lightweight smoke check (presence of members only —
+  not signatures). This package's tests use that smoke form.
+- **Nominal (optional, opt-in per implementer)** — `simulo-backend`'s
+  `simulo.core` classes additionally *declare* the Part A Protocols as base
+  classes, so mypy drift-checks each implementation against its mirror at the
+  class-definition site. Nominal declaration never replaces the structural
+  contract — a third-party implementation that merely matches the signatures
+  still conforms.
+
+## Domain-model invariants
+
+- **Package ≠ Job** (Rule #5) — a `Package` is an immutable, content-addressed
+  source archive; a `Job` is one execution of a package and references it by id.
+- **Resource ≠ Package** (Rule #6) — a `Resource` is a read-only, versioned,
+  registry-resolved mount (robot / environment / dataset / …).
+- **Checkpoint ≠ TrainedModel** (Rule #8) — an intermediate training artifact is
+  a distinct type from the final, deployable model. Never collapse them.
+- **Project is the anchor** (Rule #7) — every other domain object hangs off a
+  `Project`.
+- **No packaged-skill type** (Rule #11) — there is deliberately no `Skill` /
+  `PackagedSkill` type here.
+
+## Stability policy
+
+- Enum **values** are a stable wire ABI: append-only, never renumber or rename.
+- Dataclass fields and Protocol method signatures follow the same
+  breaking-change discipline as the rest of the contract layer.
+- The package follows SemVer; additive changes (new optional field, new
+  Protocol, new enum member at the end) are minor/patch, removals/renames major.
+
+## Requirements
+
+- Python **>= 3.11** (uses `enum.StrEnum`). Tested on 3.11 and 3.12.
+- Standard library only — **zero** runtime dependencies.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check src
+black --check src tests
+isort --check-only src tests
+mypy src            # strict
+python -m build && twine check dist/*
+pytest
+```

simulo_interfaces-0.1.0/README.md

@@ -0,0 +1,135 @@
+# simulo-interfaces
+
+The **implementation-free contract layer** for the Simulo platform. A single,
+stable, torch-free, **zero-runtime-dependency** package that both Simulo SDK
+distributions depend on:
+
+- `simulo-backend` — the cloud GPU SDK (torch + IsaacLab + Isaac Sim).
+- `simulo` — the future thin local client (no heavy deps).
+
+Because both distributions share these contracts, `simulo-interfaces` is the one
+place the runtime Protocols and the platform/workspace domain model are defined.
+
+## What it is
+
+A pure-stdlib set of `typing.Protocol` contracts, frozen dataclasses, enums,
+`NewType` identifiers, and an exception hierarchy. Nothing here does any work —
+it only describes shapes.
+
+## What it is NOT
+
+It imports **none** of: `torch`, `numpy`, `gymnasium`, IsaacLab / Isaac Sim, AWS
+SDKs, HTTP clients, or database drivers. It performs **no** I/O, persistence, or
+computation. It is **not** a dumping ground (Contract Rule #12) — only contracts
+shared by more than one distribution belong here.
+
+The central invariant (Contract Rule #11): this package must import on a laptop
+with no torch/numpy/gymnasium/Isaac installed. Two tests enforce it:
+`tests/test_import_without_torch.py` (no heavy module enters `sys.modules`) and
+`tests/test_no_heavy_deps.py` (zero unconditional `Requires-Dist`).
+
+## Two parts
+
+### Part A — `simulo.interfaces.runtime`
+
+Tensor-library-agnostic structural mirrors of the `simulo.core` runtime surface.
+Tensors are typed as `TensorLike` (an alias for `Any`) so the contracts never
+bind to a concrete tensor library.
+
+- `TaskProtocol`, `PolicyProtocol`, `TrainerProtocol`, `PlayerProtocol`
+- `LearningEnvProtocol`, `ScenarioProtocol`
+- `ObservationComponentProtocol`, `RewardComponentProtocol`,
+  `TerminationConditionProtocol`
+- `PolicyExporterProtocol` — the narrow *optional* export capability
+  (`export_policy(path) -> str`). Deliberately not a `TrainerProtocol` member:
+  a Protocol binds all implementations, and only some trainers (today
+  `simulo.core.trainer.RLTrainer`) can deliver a deterministic standalone
+  policy export. Consumers feature-detect with `isinstance(trainer,
+  PolicyExporterProtocol)`.
+
+### Part B — `simulo.interfaces.platform`
+
+The platform/workspace domain contracts:
+
+- **Enums** — `JobStatus`, `ResumePolicy`, `ResourceKind`, `ArtifactKind`.
+- **Domain dataclasses** (frozen, slotted, keyword-only) — `Tag`, `Project`,
+  `Package`, `Resource`, `Job`, `Checkpoint`, `TrainedModel`.
+- **Cloud-execution Protocols** — `AppProtocol`, `JobFunctionProtocol`,
+  `RuntimeProtocol`, `AssetProtocol`, `VolumeProtocol`, `JobCallbackProtocol`,
+  `DebugSessionProtocol`, `ReplaySessionProtocol`, `VisualizationSessionProtocol`.
+
+## Public import surface
+
+```python
+import simulo.interfaces as si
+
+# exceptions + ids re-exported at the top level
+si.SimuloError, si.ContractViolationError, si.JobFailedError
+si.ProjectId, si.JobId, si.ResourceUri, si.Digest
+
+# Part A
+from simulo.interfaces.runtime import TaskProtocol, PolicyProtocol, LearningEnvProtocol
+
+# Part B
+from simulo.interfaces.platform import (
+    JobStatus, ResumePolicy, ResourceKind, ArtifactKind,
+    Project, Package, Job, Resource, Checkpoint, TrainedModel, Tag,
+    AppProtocol, RuntimeProtocol, AssetProtocol, VolumeProtocol,
+)
+```
+
+## Conformance model
+
+The contracts are `typing.Protocol`s — implementers conform **structurally**, no
+inheritance required.
+
+- **Static** — implementers (e.g. `simulo-backend`) are type-checked against
+  these Protocols by mypy. That static assertion is the primary conformance
+  gate and lives in the **implementer** package, not here.
+- **Runtime** — every Protocol is `@runtime_checkable`, so `isinstance(obj,
+  SomeProtocol)` provides a lightweight smoke check (presence of members only —
+  not signatures). This package's tests use that smoke form.
+- **Nominal (optional, opt-in per implementer)** — `simulo-backend`'s
+  `simulo.core` classes additionally *declare* the Part A Protocols as base
+  classes, so mypy drift-checks each implementation against its mirror at the
+  class-definition site. Nominal declaration never replaces the structural
+  contract — a third-party implementation that merely matches the signatures
+  still conforms.
+
+## Domain-model invariants
+
+- **Package ≠ Job** (Rule #5) — a `Package` is an immutable, content-addressed
+  source archive; a `Job` is one execution of a package and references it by id.
+- **Resource ≠ Package** (Rule #6) — a `Resource` is a read-only, versioned,
+  registry-resolved mount (robot / environment / dataset / …).
+- **Checkpoint ≠ TrainedModel** (Rule #8) — an intermediate training artifact is
+  a distinct type from the final, deployable model. Never collapse them.
+- **Project is the anchor** (Rule #7) — every other domain object hangs off a
+  `Project`.
+- **No packaged-skill type** (Rule #11) — there is deliberately no `Skill` /
+  `PackagedSkill` type here.
+
+## Stability policy
+
+- Enum **values** are a stable wire ABI: append-only, never renumber or rename.
+- Dataclass fields and Protocol method signatures follow the same
+  breaking-change discipline as the rest of the contract layer.
+- The package follows SemVer; additive changes (new optional field, new
+  Protocol, new enum member at the end) are minor/patch, removals/renames major.
+
+## Requirements
+
+- Python **>= 3.11** (uses `enum.StrEnum`). Tested on 3.11 and 3.12.
+- Standard library only — **zero** runtime dependencies.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check src
+black --check src tests
+isort --check-only src tests
+mypy src            # strict
+python -m build && twine check dist/*
+pytest
+```

simulo_interfaces-0.1.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simulo-interfaces"
+version = "0.1.0"
+description = "Implementation-free contract layer for the Simulo platform — torch-free runtime/sim Protocols and platform/workspace domain contracts. Importable with no torch/numpy/gymnasium/Isaac installed."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "BSD-3-Clause" }
+authors = [{ name = "Simulo Team", email = "team@simulo.ai" }]
+keywords = ["robotics", "contracts", "protocols", "interfaces", "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",
+]
+# ZERO runtime dependencies. Hard invariant (Rule #11): the thin client must
+# import this with no torch/numpy/gymnasium/Isaac/AWS/HTTP present. Enforced by
+# tests/test_no_heavy_deps.py + tests/test_import_without_torch.py.
+dependencies = []
+
+[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"]
+# Mirrors simulo-backend's [release] extra. `dev` above carries build/twine
+# but deliberately NOT commitizen — the release skill (.claude/skills/release/
+# SKILL.md) installs THIS extra specifically so `cz` is available without
+# also pulling in a second copy of build/twine.
+release = ["commitizen>=3.27", "build>=1.2", "twine>=5.1"]
+
+[project.urls]
+Homepage = "https://simulo.ai"
+Source = "https://github.com/simulo-org/simulo-platform"
+
+# PEP 420 namespace package: NO src/simulo/__init__.py. `namespaces = true`
+# makes setuptools pick up simulo.interfaces.* while leaving `simulo` a shared
+# namespace simulo-backend also contributes to. Mirrors simulo-backend exactly.
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+[tool.setuptools.package-data]
+"simulo.interfaces" = ["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"
+
+[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 ------------------------------------------------------------
+# Path B release flow (see `.claude/skills/release/SKILL.md`): `cz bump` here
+# creates the bump commit + tag locally; `.github/workflows/release.yml`
+# 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 is a hand-written bump commit per the release skill's
+# First-release appendix, NOT a `cz bump` — this package's version is
+# already 0.1.0 with no releasable commits since repo history began, so a
+# real `cz bump --dry-run` would report "no increment"; the first tag simply
+# publishes the current 0.1.0 as-is.
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "pep621"
+version_files = []
+tag_format = "simulo-interfaces-v$version"
+update_changelog_on_bump = true
+changelog_incremental = true
+major_version_zero = true
+bump_message = "chore(release): bump simulo-interfaces to v$new_version"

simulo_interfaces-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

simulo_interfaces-0.1.0/src/simulo/interfaces/__init__.py

@@ -0,0 +1,65 @@
+"""Simulo Interfaces — implementation-free contract layer for the Simulo platform.
+
+Torch-free, zero-runtime-dependency (Rule #11). Importable on a laptop with no
+torch / numpy / gymnasium / Isaac / AWS / HTTP / DB installed. Two parts:
+
+* **Part A — ``simulo.interfaces.runtime``**: tensor-library-agnostic structural
+  Protocols mirroring the ``simulo.core`` runtime surface (Task, Policy,
+  Trainer, Player, LearningEnv, Scenario, and the observation/reward/termination
+  components).
+* **Part B — ``simulo.interfaces.platform``**: 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, callbacks, and
+  debug/replay/visualization sessions).
+
+This package contributes ``simulo.interfaces.*`` to the shared ``simulo`` PEP 420
+namespace that ``simulo-backend`` also contributes to; it ships NO
+``src/simulo/__init__.py``.
+"""
+
+from simulo.interfaces import platform, runtime
+from simulo.interfaces.exceptions import (
+    ContractViolationError,
+    ImportResolutionError,
+    JobFailedError,
+    ResourceNotFoundError,
+    ResumeIncompatibleError,
+    SimuloError,
+)
+from simulo.interfaces.ids import (
+    CheckpointId,
+    Digest,
+    JobId,
+    OrganizationId,
+    PackageId,
+    ProjectId,
+    ResourceId,
+    ResourceUri,
+    TagId,
+    TrainedModelId,
+)
+
+__all__ = [
+    # subpackages
+    "platform",
+    "runtime",
+    # exception hierarchy
+    "SimuloError",
+    "ContractViolationError",
+    "ImportResolutionError",
+    "ResourceNotFoundError",
+    "ResumeIncompatibleError",
+    "JobFailedError",
+    # identifiers
+    "OrganizationId",
+    "ProjectId",
+    "PackageId",
+    "JobId",
+    "ResourceId",
+    "CheckpointId",
+    "TrainedModelId",
+    "TagId",
+    "ResourceUri",
+    "Digest",
+]

simulo_interfaces-0.1.0/src/simulo/interfaces/exceptions.py

@@ -0,0 +1,31 @@
+"""Shared Simulo contract exception hierarchy.
+
+Implementation-free (Rule #11): no I/O, no heavy deps. These types are the
+common error vocabulary the thin ``simulo`` client and the ``simulo-backend``
+GPU SDK both raise/catch when a contract is violated.
+"""
+
+
+class SimuloError(Exception):
+    """Root of the shared Simulo contract exception hierarchy."""
+
+
+class ContractViolationError(SimuloError):
+    """An object failed to satisfy a Simulo contract/Protocol."""
+
+
+class ImportResolutionError(SimuloError):
+    """A deferred ``runtime.imports()`` symbol was used in local discovery mode
+    without a resolved cloud import (Rule #3)."""
+
+
+class ResourceNotFoundError(SimuloError):
+    """``from_registry()``/``from_name()`` could not resolve a resource/volume (Rule #6)."""
+
+
+class ResumeIncompatibleError(SimuloError):
+    """A discovered checkpoint is incompatible with the current job (Rule #9)."""
+
+
+class JobFailedError(SimuloError):
+    """A submitted job terminated in ``JobStatus.FAILED``."""

simulo_interfaces-0.1.0/src/simulo/interfaces/ids.py

@@ -0,0 +1,21 @@
+"""Strongly-typed string identifiers for the platform domain model (Part B).
+
+``NewType`` aliases — zero runtime cost (each is the underlying ``str`` at
+runtime) but distinct to the type checker, so a ``ProjectId`` can never be
+passed where a ``JobId`` is expected.
+"""
+
+from typing import NewType
+
+OrganizationId = NewType("OrganizationId", str)
+ProjectId = NewType("ProjectId", str)
+PackageId = NewType("PackageId", str)
+JobId = NewType("JobId", str)
+ResourceId = NewType("ResourceId", str)
+CheckpointId = NewType("CheckpointId", str)
+TrainedModelId = NewType("TrainedModelId", str)
+TagId = NewType("TagId", str)
+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)

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

@@ -0,0 +1,120 @@
+"""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.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_LOGS_ROUTE_TEMPLATE,
+    JOB_RESULT_ROUTE_TEMPLATE,
+    JOB_ROUTE_TEMPLATE,
+    JOBS_API_DEFAULT_PORT,
+    JOBS_ROUTE,
+    LOG_CHUNK_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,
+    MODEL_KINDS,
+    PACKAGE_ARCHIVE_ROUTE_TEMPLATE,
+    PACKAGES_ROUTE,
+    RESERVED_RUNTIME_ENV_KEYS,
+    RESERVED_RUNTIME_ENV_PREFIXES,
+    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,
+)
+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_LOGS_ROUTE_TEMPLATE",
+    "JOB_RESULT_ROUTE_TEMPLATE",
+    "LOG_CHUNK_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",
+    # protocols
+    "RuntimeProtocol",
+    "AssetProtocol",
+    "VolumeProtocol",
+    "JobCallbackProtocol",
+    "JobFunctionProtocol",
+    "AppProtocol",
+    "Mount",
+    "DebugSessionProtocol",
+    "ReplaySessionProtocol",
+    "VisualizationSessionProtocol",
+]

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

@@ -0,0 +1,47 @@
+"""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]
+
+
+@runtime_checkable
+class JobFunctionProtocol(Protocol):
+    """What ``@app.job`` returns: the user's original function, wrapped (Rule #1 — source-preserving). FORWARD."""
+
+    def __call__(self, *args: object, **kwargs: object) -> object: ...
+    def submit(self, *args: object, **kwargs: object) -> JobId: ...
+
+
+@runtime_checkable
+class AppProtocol(Protocol):
+    """User-facing job container: ``app = simulo.App(name, runtime=, mounts={...})``. FORWARD."""
+
+    @property
+    def name(self) -> str: ...
+    @property
+    def runtime(self) -> RuntimeProtocol: ...
+    @property
+    def mounts(self) -> Mapping[str, Mount]: ...
+    @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]]: ...
+    def local_entrypoint(self, fn: F) -> F: ...