cmpnd 0.47.1__tar.gz → 0.49.0__tar.gz

{cmpnd-0.47.1 → cmpnd-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.47.1
+Version: 0.49.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>

{cmpnd-0.47.1 → cmpnd-0.49.0}/cmpnd/cli/commands/deployments.py

@@ -73,6 +73,12 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         if name == "wait":
             command.add_argument("--timeout", type=float, default=None, help=TIMEOUT_HELP)
         command.set_defaults(func=handler)
+    cancel = run_sub.add_parser(
+        "cancel",
+        help="Cancel a queued or running deployment run. It settles as failed with error_code cancelled",
+    )
+    cancel.add_argument("id", help="Deployment run ID")
+    cancel.set_defaults(func=handle_runs_cancel)
 
     openapi = sub.add_parser(
         "openapi",
@@ -251,6 +257,16 @@ def handle_runs_wait(client: api_client.ApiClient, args: Any) -> Any:
     return settled
 
 
+def handle_runs_cancel(client: api_client.ApiClient, args: Any) -> Any:
+    """Settle an open run as cancelled and return its header.
+
+    Serve stops dispatching and collecting the run at once. A run already
+    executing on a worker runs on there until its deadline and may spend model
+    calls, but its answer is discarded.
+    """
+    return client.post(f"/api/v1/deployments/runs/{args.id}/cancel")
+
+
 def handle_openapi(client: api_client.ApiClient, args: Any) -> None:
     """Write the deployment's OpenAPI document to stdout.
 

{cmpnd-0.47.1 → cmpnd-0.49.0}/cmpnd/cli/verbs.py

@@ -152,6 +152,7 @@ DOMAIN_VERBS: dict[str, str] = {
     "revoke-invite": "withdraws the open owner invites to an address; bare revoke would read as revoking the org",
     "run": "submits a deployment execution and optionally waits for its retained answer",
     "wait": "polls one accepted run until it settles or the local budget expires",
+    "cancel": "settles an open run as cancelled and keeps its record; delete would read as removing the run",
     "follow": "tails a record until it settles — a list over time rather than a snapshot",
     "select": "marks one candidate as the program's chosen version",
     "refresh": "re-reads a record from the system of record it mirrors; nothing the caller supplies is written",

{cmpnd-0.47.1 → cmpnd-0.49.0}/cmpnd/deployment_runs.py

@@ -100,11 +100,28 @@ class RunSubmissionUncertain(RuntimeError):
         _set_run_id(self, run_id)
 
 
+def _cancel_command(run_id: str) -> str:
+    return f"cmpnd deployments runs cancel {run_id}"
+
+
 class RunWaitTimeout(TimeoutError):
-    """The local budget ran out; the accepted run continues."""
+    """The local budget ran out; the accepted run continues.
 
-    def __init__(self, run_id: str):
-        super().__init__(f"Deployment run {run_id} has not settled. Resume with `{_wait_command(run_id)}`.")
+    ``status`` and ``status_reason`` are the run's last header read, when one
+    arrived: why the run is still open, such as a queued run waiting for a
+    credential or a worker.
+    """
+
+    def __init__(self, run_id: str, *, status: str | None = None, status_reason: str | None = None):
+        state = ""
+        if status:
+            state = f" ({status}: {status_reason})" if status_reason else f" ({status})"
+        super().__init__(
+            f"Deployment run {run_id} has not settled{state}. "
+            f"Resume with `{_wait_command(run_id)}`, or stop it with `{_cancel_command(run_id)}`."
+        )
+        self.status = status
+        self.status_reason = status_reason
         _set_run_id(self, run_id)
 
 
@@ -325,6 +342,9 @@ class _RunClient:
         self.api_key = api_key
         self.client: httpx.Client | None = None
         self.retry_after = 0.0
+        # The last run header a wait read, so a wait that runs out can say why
+        # the run is still open.
+        self.last_header: dict[str, Any] | None = None
 
     def __enter__(self) -> _RunClient:
         self.client = _http.new_client(headers={"X-API-Key": self.api_key})
@@ -444,8 +464,23 @@ class _RunClient:
         """Follow an accepted run until its retained answer is read or the budget ends.
 
         Reads only. A read refused with 401, 403 or 404 raises at once; timeouts,
-        408, 429 and server errors are retried with backoff and jitter.
+        408, 429 and server errors are retried with backoff and jitter. When the
+        budget runs out, the timeout names the run's last status and reason.
         """
+        self.last_header = initial
+        try:
+            return self._follow(run_id, deadline, initial)
+        except RunWaitTimeout:
+            header = self.last_header
+            if header is None:
+                raise
+            reason = header.get("status_reason")
+            raise RunWaitTimeout(
+                run_id, status=header.get("status"), status_reason=reason if isinstance(reason, str) else None
+            ) from None
+
+    def _follow(self, run_id: str, deadline: float | None, initial: dict[str, Any] | None) -> dict[str, Any]:
+        """The wait loop. It records each header it reads in ``last_header``."""
         header = initial
         need_status = header is None
         delay = _FIRST_POLL_DELAY
@@ -455,6 +490,7 @@ class _RunClient:
                 response = self._poll(status_path, deadline, run_id)
                 if response is not None:
                     header = _validate_run(_json(response, "status", run_id), submitted=False)
+                    self.last_header = header
             need_status = True
             if header is not None and header["status"] in _TERMINAL:
                 # The status is settled, so only the answer remains to be read.

{cmpnd-0.47.1 → cmpnd-0.49.0}/cmpnd/optimization.py

@@ -862,7 +862,12 @@ def optimize(
             in ``config["reflection_model"]``, which is what the server
             establishes this run's reflection credential from, and its sampling in
             ``config["reflection_sampling"]``, which only the reflecting tier
-            reads. An ``api_key``, ``api_base`` or ``base_url`` on it is refused
+            reads. A reflection turn that names no output cap or temperature
+            gets the platform's (a large ``max_tokens`` and ``temperature=1.0``).
+            To send none and let the model's own defaults apply, pass the model
+            name as a string and set those keys to ``None`` in
+            ``config["reflection_sampling"]``, e.g.
+            ``{"max_tokens": None, "temperature": None}``. An ``api_key``, ``api_base`` or ``base_url`` on it is refused
             rather than dropped: the credential a run spends and the endpoint it
             is spent at are both the platform's, so one set here would be
             discarded without a word. The server refuses a gepa run

{cmpnd-0.47.1 → cmpnd-0.49.0}/docs/cli.md

@@ -88,6 +88,9 @@ within the budget.
 
 The budget or Ctrl-C stops the local wait, and an accepted run continues.
 After acceptance the CLI prints `cmpnd deployments runs wait <id>` on stderr.
+A wait that runs out also names the run's last status and `status_reason`,
+such as `queued: execution_authority_unavailable`, and the command that
+cancels it.
 When the submission reply is lost or fails, acceptance is uncertain. The CLI
 then prints `cmpnd deployments runs list --deployment <id>`. Check that list
 before you submit again.
@@ -104,7 +107,13 @@ with `--deployment ID`. It takes these filters:
 Each page reports `total`, the number of matching runs, and `has_more` when another page follows.
 
 `show ID` prints one run, `result ID` reads its retained answer, and
-`wait ID [--timeout SECONDS]` resumes waiting. The run commands' JSON output
+`wait ID [--timeout SECONDS]` resumes waiting. `cancel ID` settles a queued or
+running run as `failed` with `error_code` `cancelled` and prints it. Serve
+stops dispatching and collecting the run at once. A run already executing on a
+worker runs on there until its deadline and may spend model calls, but its
+answer is discarded. A key with `deployments:write` cancels any run, and a key
+with only `deployments:execute` cancels the runs it submitted. Cancelling a run
+that already settled exits nonzero. The run commands' JSON output
 needs no DSPy install.
 
 ### A file deploys as the source you wrote

{cmpnd-0.47.1 → cmpnd-0.49.0}/docs/sdk-instrumentation.md

@@ -407,7 +407,9 @@ lost POST reply or a server `5xx` leaves acceptance uncertain, so the SDK raises
 names the command to list recent runs. Reads that time out or answer `408`,
 `429` or `5xx` are retried with backoff and jitter, honoring `Retry-After`. A
 `401`, `403` or `404` read raises at once. A spent budget raises
-`RunWaitTimeout`, and the accepted run continues. Ctrl-C prints the run ID and
+`RunWaitTimeout`, and the accepted run continues. Its `status` and
+`status_reason` hold the run's last header read, and its message names them
+with the commands that resume the wait and cancel the run. Ctrl-C prints the run ID and
 `cmpnd deployments runs wait <id>` on stderr, or before acceptance the list
 command, and re-raises.
 

{cmpnd-0.47.1 → cmpnd-0.49.0}/pyproject.toml

@@ -5,7 +5,7 @@ name = "cmpnd"
 # it's new) — no git tags. Bump with `uv version --bump {minor,patch}` or by
 # hand. Runtime `cmpnd.__version__` reads installed metadata, so it tracks
 # this automatically. See docs/plans/2026-07-02-sdk-pypi-tag-free-publish.md.
-version = "0.47.1"
+version = "0.49.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"

{cmpnd-0.47.1 → cmpnd-0.49.0}/tests/test_cli/test_deployment_runs.py

@@ -215,6 +215,51 @@ def test_interrupted_run_names_the_accepted_run(monkeypatch: pytest.MonkeyPatch,
     assert f"cmpnd deployments runs wait {RUN_ID}" in capsys.readouterr().err
 
 
+@pytest.mark.parametrize("verb", [["run", DEPLOYMENT_ID, "{}"], ["deployments", "runs", "wait", RUN_ID]])
+def test_a_wait_that_runs_out_names_why_the_run_is_still_open(monkeypatch: pytest.MonkeyPatch, capsys, verb):
+    from cmpnd import deployment_runs
+
+    clock = iter(float(tick) for tick in range(1000))
+    monkeypatch.setattr(deployment_runs, "_now", lambda: next(clock))
+    monkeypatch.setattr(deployment_runs, "_sleep", lambda _: None)
+    waiting = {**_envelope("queued"), "status_reason": "execution_authority_unavailable"}
+
+    def answer(req):
+        return httpx.Response(202 if req.method == "POST" else 200, json=waiting, request=req)
+
+    with pytest.raises(SystemExit) as caught:
+        _run_cli(monkeypatch, [*verb, "--timeout", "6"], answer)
+    assert caught.value.code != 0
+    err = capsys.readouterr().err
+    assert f"Deployment run {RUN_ID} has not settled" in err
+    assert "queued: execution_authority_unavailable" in err
+    assert f"cmpnd deployments runs wait {RUN_ID}" in err
+    assert f"cmpnd deployments runs cancel {RUN_ID}" in err
+
+
+def test_runs_cancel_posts_the_cancel_and_prints_the_settled_run(monkeypatch: pytest.MonkeyPatch, capsys):
+    seen = []
+    cancelled = {**_envelope("failed"), "error_code": "cancelled"}
+
+    def answer(req):
+        seen.append(req)
+        return httpx.Response(200, json=cancelled, request=req)
+
+    _run_cli(monkeypatch, ["deployments", "runs", "cancel", RUN_ID], answer)
+    assert [(req.method, req.url.path) for req in seen] == [("POST", f"/api/v1/deployments/runs/{RUN_ID}/cancel")]
+    assert json.loads(capsys.readouterr().out)["error_code"] == "cancelled"
+
+
+def test_runs_cancel_of_a_settled_run_exits_nonzero(monkeypatch: pytest.MonkeyPatch, capsys):
+    def answer(req):
+        return httpx.Response(409, json={"error": "deployment run already settled as completed"}, request=req)
+
+    with pytest.raises(SystemExit) as caught:
+        _run_cli(monkeypatch, ["deployments", "runs", "cancel", RUN_ID], answer)
+    assert caught.value.code != 0
+    assert "already settled as completed" in capsys.readouterr().err
+
+
 def test_interrupted_submission_reports_uncertainty(monkeypatch: pytest.MonkeyPatch, capsys):
     def answer(req):
         raise KeyboardInterrupt

{cmpnd-0.47.1 → cmpnd-0.49.0}/tests/test_optimize_reflection_lm.py

@@ -189,6 +189,18 @@ def test_the_refusal_fires_even_when_the_lm_would_have_overwritten_it():
         optimization._reflection_config(config, _LM("openai/gpt-4o", top_p=0.9))
 
 
+def test_a_none_in_config_sampling_travels_as_none():
+    """``None`` asks the reflecting tier to drop its own default for that key, so the
+    model's default applies. This layer must carry it rather than filter it out as
+    "unset", which is what it means everywhere an LM's own state is read."""
+    config = {"reflection_sampling": {"max_tokens": None, "temperature": None}}
+    optimization._reflection_config(config, "openai/gpt-4o")
+    assert config == {
+        "reflection_model": "openai/gpt-4o",
+        "reflection_sampling": {"max_tokens": None, "temperature": None},
+    }
+
+
 def test_a_model_name_beside_config_sampling_stays_legal():
     """The string path is the one way left to name sampling through ``config``, so it
     keeps working — a name says nothing about sampling and so contradicts nothing."""

{cmpnd-0.47.1 → cmpnd-0.49.0}/uv.lock

@@ -496,7 +496,7 @@ wheels = [
 
 [[package]]
 name = "cmpnd"
-version = "0.47.1"
+version = "0.49.0"
 source = { editable = "." }
 dependencies = [
     { name = "dspy" },