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

{simulo_interfaces-0.2.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.2.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.2.0 → simulo_interfaces-0.4.0}/pyproject.toml

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

@@ -14,12 +14,14 @@ from simulo.interfaces.platform.debug import DebugSessionProtocol, ReplaySession
 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,
 )
@@ -36,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,
@@ -75,9 +81,11 @@ __all__ = [
     "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",
@@ -106,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.2.0 → simulo_interfaces-0.4.0}/src/simulo/interfaces/platform/runs.py

@@ -37,8 +37,50 @@ HTTP API shape (all responses JSON; all timestamps ISO 8601 UTC, e.g.
   ``next_offset == offset``; the accompanying ``status`` tells the client
   whether more output may still arrive (poll while the status is
   non-terminal, stop once it is in :data:`TERMINAL_JOB_STATUSES`).
+
+  **Tail semantics (optional, additive):** ``?tail_bytes=K`` (``0 <= K <=``
+  :data:`LOG_TAIL_MAX_BYTES`; ``offset`` must be omitted or 0, otherwise the
+  request is ambiguous and answers 422 — the control plane's code is
+  ``tail_bytes_conflicts_with_offset``; clients need only the status)
+  asks the server to start the read near the END of the stream instead of at
+  ``offset``: the server computes ``start = max(0, total_len - K)`` and
+  returns the chunk from there, adding ``"start_offset": start`` to the
+  response. ``start_offset`` is present ONLY when tail was honored — its
+  absence tells a tail-requesting client it is talking to an older server
+  that ignored the (undeclared) parameter and answered from offset 0, so the
+  client can degrade to full history instead of mis-trimming. ``tail_bytes=0``
+  is the "seek to end-of-log" primitive: an empty ``chunk`` with
+  ``next_offset == start_offset == total_len``. After one tail response the
+  client resumes normal offset paging from ``next_offset`` (never sending
+  ``tail_bytes`` again), so a tail-following client never drains the full
+  history. ``start`` is a byte position and may land mid-line or mid-UTF-8
+  sequence; a line-oriented client trims its first partial line client-side
+  (``simulo logs --follow`` requests a generous byte window for its line
+  count and does exactly that).
 * ``GET /v1/jobs/{job_id}/result`` — the job's result JSON object. 404 (code
   ``result_not_available``) until the job has completed successfully.
+* ``POST /v1/jobs/{job_id}/cancel`` — request cancellation of a queued or
+  running job (no request body). Semantics by current status:
+
+  - ``queued`` → the job transitions to terminal ``cancelled`` immediately
+    (it can never be claimed afterwards). 200::
+
+        {"job_id": "...", "status": "cancelled"}
+
+  - ``running`` → cancellation is REQUESTED; the executor observes it on its
+    next heartbeat, stops the job, and reports terminal ``cancelled``
+    (existing ``best.pt``/``latest.pt`` checkpoints are uploaded first —
+    cancel never vaporizes training progress; partial recordings are
+    dropped). Idempotent: repeat requests return the same 202::
+
+        {"job_id": "...", "status": "running", "cancel_requested": true}
+
+    A ``running`` job whose executor is provably gone (expired lease, no
+    active claim) transitions directly to ``cancelled`` → 200 as above.
+  - terminal (``completed``/``failed``/``cancelled``) → 409, code
+    ``job_not_running``, with the job's actual status in the human message.
+  - unknown/cross-tenant/malformed id → 404 ``job_not_found`` (never 403 —
+    anti-enumeration, same as every other per-job route).
 
 **Scoping (evolves toward the cloud):** every route above is UNSCOPED locally
 — there is no project/org filter because the local stand-in has exactly one
@@ -77,10 +119,48 @@ JOB_ROUTE_TEMPLATE = "/v1/jobs/{job_id}"
 JOB_LOGS_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/logs"
 #: ``GET`` — the result JSON of a successfully completed job. ``.format(job_id=...)``.
 JOB_RESULT_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/result"
+#: ``POST`` — cancel a queued/running job (no body). ``.format(job_id=...)``.
+#: 200 terminal ``cancelled`` (queued, or running with a provably-dead
+#: executor); 202 ``{"cancel_requested": true}`` (running — the executor
+#: stops it within one heartbeat interval); 409 ``job_not_running``
+#: (already terminal); 404 ``job_not_found``. Full semantics in the module
+#: docstring above.
+JOB_CANCEL_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/cancel"
 
 #: Upper bound on the log bytes a single ``/logs`` response carries. The server
 #: may return fewer bytes (never more); clients keep reading from ``next_offset``.
-LOG_CHUNK_MAX_BYTES = 64 * 1024
+#: This is a server-side response-size POLICY value, not a structural wire
+#: shape — clients are not expected to depend on the exact number (they
+#: read ``chunk``/``next_offset`` generically and loop until caught up), so
+#: it is safe to raise without breaking already-published clients reading
+#: OFFSET responses. **Rollout order caveat (added with tail semantics):**
+#: :data:`LOG_TAIL_MAX_BYTES` is DERIVED from this constant (``4x``), so
+#: raising this ALSO raises what a new client may send as ``?tail_bytes=``.
+#: A server that has not yet picked up the raised bound still enforces its
+#: OLD, smaller ``le=`` cap on that query param and answers 422 — a hard
+#: rejection the client's tail-degradation path does not cover (that path
+#: handles an old server IGNORING the unknown param, not one REJECTING an
+#: in-range-for-the-client-but-out-of-range-for-the-server value). Deploy
+#: every server before shipping a `simulo-interfaces` release that raises
+#: this constant. Bumped
+#: 64 KiB -> 256 KiB (simulo-control-plane PR6, 2026-07-11): a poll-cadence
+#: rate limit sized against the OLD 64 KiB cap could still 429 mid-drain on
+#: a large/fast-growing log because a no-sleep catch-up loop bursts through
+#: it; see that PR's `jobs/routes.py::_LOGS_POLL_RATE` docstring for the
+#: exact math. No PyPI republish accompanies this source change — no
+#: published thin-client version reads this constant at runtime; it takes
+#: effect for whichever `simulo-interfaces` version ships next.
+LOG_CHUNK_MAX_BYTES = 256 * 1024
+
+#: Upper bound on ``?tail_bytes=`` (the "start this many bytes before the end"
+#: request parameter — see the module docstring's tail semantics). A tail
+#: window is a REQUEST-side positioning value, not a response-size promise:
+#: the response is still capped at :data:`LOG_CHUNK_MAX_BYTES`, and a window
+#: larger than one response chunk arrives across normal offset pages. 4x the
+#: response cap comfortably covers the CLI's default (50 lines x ~200
+#: bytes/line ≈ 10 KiB) and any plausible ``--tail N`` while keeping the
+#: server's tail scan bounded. Values above this cap answer 422.
+LOG_TAIL_MAX_BYTES = 4 * LOG_CHUNK_MAX_BYTES
 
 #: Statuses after which a job's log stream and record no longer change. A log
 #: follower drains the remaining bytes and stops once the status is terminal.

{simulo_interfaces-0.2.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)
@@ -344,10 +440,11 @@ MAX_PACKAGE_BYTES = 64 * 1024 * 1024  # 64 MiB
 #: (``POST`` :data:`WORKER_JOB_LOGS_ROUTE_TEMPLATE` body) — the write-side cap, 1 MiB.
 #:
 #: **Not the same constant as** ``simulo.interfaces.platform.runs.LOG_CHUNK_MAX_BYTES``
-#: (64 KiB) — that is the pre-existing **client** read-side cap on a single
-#: ``GET .../logs?offset=N`` response (``runs.py``). Both are now re-exported
-#: from ``simulo.interfaces.platform``, so importing the wrong one silently
-#: changes behavior by 16x: a worker that POSTs up to ``runs.LOG_CHUNK_MAX_BYTES``
+#: (256 KiB as of 2026-07-11 — see that constant's docstring) — that is the
+#: pre-existing **client** read-side cap on a single ``GET .../logs?offset=N``
+#: response (``runs.py``). Both are now re-exported from
+#: ``simulo.interfaces.platform``, so importing the wrong one silently
+#: changes behavior by 4x: a worker that POSTs up to ``runs.LOG_CHUNK_MAX_BYTES``
 #: per call under-uses its allowance; a client GET that budgeted for this
 #: (larger) constant would be surprised the server never returns that much.
 MAX_LOG_CHUNK_BYTES = 1 * 1024 * 1024  # 1 MiB

{simulo_interfaces-0.2.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.2.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