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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.3.0
+Version: 0.4.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.3.0 → simulo_interfaces-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.3.0"
+version = "0.4.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.3.0 → simulo_interfaces-0.4.0}/src/simulo/interfaces/platform/__init__.py

@@ -38,11 +38,15 @@ from simulo.interfaces.platform.submit import (
     MAX_LOG_TOTAL_BYTES,
     MAX_PACKAGE_BYTES,
     MAX_RESULT_BYTES,
+    MAX_SEED_REF_CHARS,
     MODEL_KINDS,
     PACKAGE_ARCHIVE_ROUTE_TEMPLATE,
     PACKAGES_ROUTE,
     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,
@@ -110,6 +114,11 @@ __all__ = [
     "RecordingRecord",
     "RESERVED_RUNTIME_ENV_KEYS",
     "RESERVED_RUNTIME_ENV_PREFIXES",
+    # explicit-run-intent plan: submit-time seed source (additive)
+    "SEED_SOURCE_FIELDS",
+    "SEED_SOURCE_CONFLICT_CODE",
+    "SEED_JOB_REF_GRAMMAR",
+    "MAX_SEED_REF_CHARS",
     # protocols
     "RuntimeProtocol",
     "AssetProtocol",

{simulo_interfaces-0.3.0 → simulo_interfaces-0.4.0}/src/simulo/interfaces/platform/submit.py

@@ -83,6 +83,49 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
   with the *existing* record rather than creating a second job — a client
   retry (e.g. after a dropped response) must not double-submit.
 
+  **Seed source (explicit-run-intent plan, additive):** the request body
+  optionally carries one of two further top-level fields, both **siblings of
+  ``args`` — never nested inside it, and never written into the package
+  manifest**::
+
+      {"package_id": "...", "job_name": "train_cartpole", "args": {...},
+       "seed_from_job_id": "<job-id>[:latest]"}
+
+  This placement is load-bearing, not stylistic: ``args``' canonical JSON is
+  what the client hashes (together with the source digest and job name) to
+  derive ``package_id`` (``_client/manifest.py``), so a seed reference living
+  inside ``args`` would make re-running the exact same package bytes with a
+  *different* seed register as a *different* package — collapsing package
+  identity (content-addressed, immutable) into job identity (per-submit,
+  mutable). ``viewstream`` (the worker's ``_child_env``) already follows this
+  same package-≠-job placement rule; these two fields are the same shape.
+  Consumers of this contract MUST build the seed fields onto the request
+  exactly the way ``create_job`` builds ``viewstream`` today — as extra keys
+  set directly on the top-level body dict — and MUST NOT fold them into the
+  ``args`` mapping that gets hashed.
+
+  :data:`SEED_SOURCE_FIELDS` pins the two field names:
+
+  - ``seed_from_job_id`` (``str``) — continue training from another job's
+    checkpoint. A bare job id selects that job's ``best.pt``; suffixing
+    ``:latest`` (``"<job-id>:latest"``) selects ``latest.pt`` instead — the
+    suffix lives inside this one string; there is no separate "kind" field.
+  - ``seed_from_model_id`` (``str``) — continue from one exact
+    :class:`ModelRecord` artifact, pinned by id.
+
+  Both default to (and an old client that predates this field pair always
+  sends) absent/``None`` — a **fresh run**, the new default with no
+  exceptions: an un-upgraded client that omits both fields degrades to
+  exactly the semantics this plan wants, with zero change to the bytes it
+  already sends. The two are **mutually exclusive**: a request setting both
+  is rejected whole, ``422`` :data:`SEED_SOURCE_CONFLICT_CODE`
+  (``"seed_source_conflict"``) — the server never silently prefers one over
+  the other. Further validation of the referenced job/model (org membership,
+  terminal status, artifact kind) is server-side business logic layered on
+  top of this wire shape, not defined by this module — see the
+  explicit-run-intent plan's "Server validation" section
+  (``context/implementation-plans/explicit-run-intent-plan.md``).
+
 ## Client-facing: recordings
 
 * :data:`JOB_RECORDINGS_ROUTE_TEMPLATE` (``GET``) — paginated envelope of
@@ -298,6 +341,59 @@ JOB_MODEL_DOWNLOAD_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/models/{model_id}/downloa
 #: There is deliberately no separate ``*_SUBMIT_ROUTE`` constant here — see
 #: the module docstring's "Client-facing: package submit + job create" section.
 
+#: The two mutually-exclusive, optional ``POST /v1/jobs`` body fields — both
+#: **siblings of ``args``**, never nested inside it — that seed a fresh job's
+#: starting checkpoint from another job's or model's already-uploaded
+#: artifact (explicit-run-intent plan). Neither set = a fresh run, the
+#: default and the only behavior an old client (unaware of this pair) can
+#: produce. Setting both in the same request is rejected whole as
+#: :data:`SEED_SOURCE_CONFLICT_CODE`. Full field-by-field semantics live in
+#: the module docstring's "Client-facing: package submit + job create"
+#: section, above — this tuple exists so PRs building against this contract
+#: (control plane request validation, the thin client's ``--from`` flag —
+#: which resolves a job-ref + artifact name to a concrete ``model_id``, so no
+#: UUID ever reaches a human) import one pinned pair of literal names instead
+#: of re-typing them. There is deliberately no ``--from-model`` CLI flag.
+SEED_SOURCE_FIELDS = ("seed_from_job_id", "seed_from_model_id")
+
+#: Grammar of the ``seed_from_job_id`` value (the ``seed_from_model_id`` value
+#: is a bare model id, no suffix). Pinned here because BOTH sides parse it and
+#: a divergence is silent: the client would accept a value the server rejects
+#: (a wasted package build + archive upload for a typo), or reject one the
+#: server accepts.
+#:
+#: ``<job-ref>[:<kind>]`` — ``job-ref`` is a full job UUID or an unambiguous
+#: id prefix; ``kind`` is one of :data:`MODEL_KINDS`, compared **lowercased
+#: after stripping surrounding whitespace**. Rules, in the order both sides
+#: apply them:
+#:
+#: * ``":" not in value`` → the whole value is the ref; ``kind`` defaults to
+#:   ``MODEL_KINDS[0]`` (``"best"``). ``":"`` is not in the UUID/prefix
+#:   alphabet, so its presence is an unambiguous suffix signal.
+#: * otherwise split on the LAST ``":"`` (``rpartition``) and reject — never
+#:   silently fall back — when EITHER side is empty (``":latest"`` is not a
+#:   ref named ``latest``; ``"8b52:"`` is not an implicit ``:best``) or when
+#:   ``kind`` is outside :data:`MODEL_KINDS`.
+#:
+#: A value violating this grammar is ``422`` ``seed_artifact_invalid``.
+SEED_JOB_REF_GRAMMAR = "<job-ref>[:best|:latest]"
+
+#: Server-pinned max length of either :data:`SEED_SOURCE_FIELDS` value on the
+#: wire (the control plane's Pydantic ``max_length``). A client MUST check
+#: this before packaging: a longer value is otherwise packaged and uploaded
+#: only to be rejected by generic schema validation, whose envelope carries
+#: none of the seed error codes a client maps to friendly copy.
+MAX_SEED_REF_CHARS = 80
+
+#: Error code (``POST /v1/jobs``, ``422``) when a request sets BOTH
+#: :data:`SEED_SOURCE_FIELDS` in the same body. Pinned as a constant — unlike
+#: this module's other wire error codes (e.g. ``lease_lost``,
+#: ``log_offset_gap``), which are documented as literal strings only —
+#: because both the control plane raising it and the thin client's seed-source
+#: mutual-exclusion check need to switch on this exact string; a bare literal
+#: risks silent drift between the two.
+SEED_SOURCE_CONFLICT_CODE = "seed_source_conflict"
+
 # --------------------------------------------------------------------------
 # Worker-facing routes (bearer = static WORKER_TOKEN, constant-time compare;
 # empty server-side config disables every route below, fail-closed)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.3.0
+Version: 0.4.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