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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.2.0
+Version: 0.3.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.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.2.0"
+version = "0.3.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.3.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,
 )
@@ -75,9 +77,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",

{simulo_interfaces-0.2.0 → simulo_interfaces-0.3.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.3.0}/src/simulo/interfaces/platform/submit.py

@@ -344,10 +344,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.3.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.3.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