cmpnd 0.80.0__tar.gz → 0.81.0__tar.gz

{cmpnd-0.80.0 → cmpnd-0.81.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.80.0
+Version: 0.81.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -722,6 +722,9 @@ errors:
 
 - A refused request raises `httpx.HTTPStatusError`.
 - A lost or failed submission reply raises `RunSubmissionUncertain`.
+- A connection to the platform that never opened, such as one refused, raises
+  `RunNotSubmitted` after a few attempts. It names the endpoint, and nothing was
+  sent, so submitting again is safe. It is a `RunSubmissionUncertain`.
 - A spent budget raises `RunWaitTimeout`, which holds the run ID.
 - An answer that expired before it was read raises `RunResultExpired`.
 

{cmpnd-0.80.0 → cmpnd-0.81.0}/README.md

@@ -671,6 +671,9 @@ errors:
 
 - A refused request raises `httpx.HTTPStatusError`.
 - A lost or failed submission reply raises `RunSubmissionUncertain`.
+- A connection to the platform that never opened, such as one refused, raises
+  `RunNotSubmitted` after a few attempts. It names the endpoint, and nothing was
+  sent, so submitting again is safe. It is a `RunSubmissionUncertain`.
 - A spent budget raises `RunWaitTimeout`, which holds the run ID.
 - An answer that expired before it was read raises `RunResultExpired`.
 

{cmpnd-0.80.0 → cmpnd-0.81.0}/cmpnd/__init__.py

@@ -37,7 +37,7 @@ from .deployment_metadata import (
     DeploymentSignatureResponse,
     UnsupportedDeploymentMetadataVersion,
 )
-from .deployment_runs import RunResultExpired, RunSubmissionUncertain, RunWaitTimeout
+from .deployment_runs import RunNotSubmitted, RunResultExpired, RunSubmissionUncertain, RunWaitTimeout
 from .execution import DeployedProgram, RetryableProviderError
 from .exporter import flush_exporter, shutdown_exporter
 from .lm_configuration import HostedLM, SystemOne, configure_lm
@@ -120,6 +120,7 @@ __all__ = [
     "DeploymentMetadataError",
     "UnsupportedDeploymentMetadataVersion",
     "RunSubmissionUncertain",
+    "RunNotSubmitted",
     "RunWaitTimeout",
     "RunResultExpired",
     "DeployedProgram",

{cmpnd-0.80.0 → cmpnd-0.81.0}/cmpnd/client.py

@@ -360,6 +360,9 @@ class Client:
                 failure. No run is started again automatically.
             RunSubmissionUncertain: If the POST reply was lost or was a server
                 error, so serve may have accepted the run.
+            RunNotSubmitted: If no connection to serve opened, after a few
+                attempts inside the budget. Nothing was sent. It is a
+                ``RunSubmissionUncertain``.
             RunWaitTimeout: If the run has not settled within the local budget.
                 The run continues.
             RunResultExpired: If the retained answer expired before it was read.

{cmpnd-0.80.0 → cmpnd-0.81.0}/cmpnd/deployment_runs.py

@@ -1,9 +1,10 @@
 """Durable deployment run submission, discovery, and result retrieval.
 
-Submission sends one POST and never repeats it. A lost or failed reply may hide
-an accepted run, so callers inspect the run list before deciding whether to
-submit new work. Waiting reads the accepted run's status and result routes,
-retrying those reads inside one local budget.
+Submission sends one POST and never repeats it once a connection opened. A lost or
+failed reply may hide an accepted run, so callers inspect the run list before
+deciding whether to submit new work. A connection that never opened sent nothing,
+so the POST is tried again a few times inside the local budget. Waiting reads the
+accepted run's status and result routes, retrying those reads inside one local budget.
 """
 
 from __future__ import annotations
@@ -40,6 +41,11 @@ _UNBOUNDED_POST_READ = 60.0
 # retried rather than consuming the whole budget.
 _READ_TIMEOUT = 30.0
 _FIRST_POLL_DELAY = 0.5
+# Attempts to open the POST's connection, and the first pause between them, which
+# doubles. A connection that never opened sent nothing, so another attempt cannot
+# submit a second run.
+_CONNECT_ATTEMPTS = 3
+_FIRST_CONNECT_DELAY = 0.5
 _MAX_POLL_DELAY = 5.0
 # A server poll hint is honored up to this many seconds.
 _MAX_RETRY_AFTER = 60.0
@@ -100,6 +106,30 @@ class RunSubmissionUncertain(RuntimeError):
         _set_run_id(self, run_id)
 
 
+class RunNotSubmitted(RunSubmissionUncertain):
+    """No connection to serve opened, so the POST sent nothing and no run exists.
+
+    ``endpoint`` is the address the SDK could not connect to, and the message gives
+    the transport's reason, such as a refused connection. Submitting again is safe.
+
+    A ``RunSubmissionUncertain`` so a caller that handles the uncertain outcome
+    still catches it. Its recovery, inspecting the run list before submitting
+    again, is unnecessary here but never wrong.
+    """
+
+    def __init__(self, deployment_id: str, endpoint: str, *, attempts: int, cause: BaseException):
+        reason = str(cause) or type(cause).__name__
+        RuntimeError.__init__(
+            self,
+            f"Deployment {deployment_id} was not submitted: no connection to {endpoint} opened "
+            f"in {attempts} attempt(s) ({reason}). Nothing was sent, so submitting again is safe.",
+        )
+        self.deployment_id = deployment_id
+        self.endpoint = endpoint
+        self.status_code = None
+        _set_run_id(self, None)
+
+
 def _cancel_command(run_id: str) -> str:
     return f"cmpnd deployments runs cancel {run_id}"
 
@@ -387,24 +417,42 @@ class _RunClient:
         return response
 
     def submit(self, deployment_id: str, body: dict[str, Any], deadline: float | None, *, wait: bool) -> dict[str, Any]:
-        """Send the one POST. Never retried: a repeat would be a second paid run."""
-        remaining = _remaining(deadline)
-        if remaining is not None and remaining <= 0:
-            raise TimeoutError(f"The local budget ran out before deployment {deployment_id} was submitted")
-        prefer = server_wait(remaining) if wait else 0
-        # The read timeout outlasts the server wait, so the transport never gives
-        # up while serve is still holding an accepted run's reply.
-        read_timeout = remaining if remaining is not None else prefer + _UNBOUNDED_POST_READ
-        try:
-            response = self._send(
-                "POST",
-                f"/api/v1/deployments/{deployment_id}/runs",
-                timeout=read_timeout,
-                body=body,
-                headers={"Prefer": f"wait={prefer}"} if prefer > 0 else None,
-            )
-        except httpx.RequestError as exc:
-            raise RunSubmissionUncertain(deployment_id) from exc
+        """Send the one POST.
+
+        Never repeated once a connection opened: a repeat would be a second paid run. A
+        connection that never opened sent nothing, so it is attempted again while the
+        budget allows, and then raises ``RunNotSubmitted``.
+        """
+        attempt = 0
+        while True:
+            attempt += 1
+            remaining = _remaining(deadline)
+            if remaining is not None and remaining <= 0:
+                raise TimeoutError(f"The local budget ran out before deployment {deployment_id} was submitted")
+            prefer = server_wait(remaining) if wait else 0
+            # The read timeout outlasts the server wait, so the transport never gives
+            # up while serve is still holding an accepted run's reply.
+            read_timeout = remaining if remaining is not None else prefer + _UNBOUNDED_POST_READ
+            try:
+                response = self._send(
+                    "POST",
+                    f"/api/v1/deployments/{deployment_id}/runs",
+                    timeout=read_timeout,
+                    body=body,
+                    headers={"Prefer": f"wait={prefer}"} if prefer > 0 else None,
+                )
+                break
+            # httpx raises these two only while it opens a connection, before any byte
+            # of the request is written. Every other transport error may follow a sent
+            # request, so it leaves acceptance uncertain.
+            except (httpx.ConnectError, httpx.ConnectTimeout) as exc:
+                pause = _jitter(_FIRST_CONNECT_DELAY * 2 ** (attempt - 1))
+                left = _remaining(deadline)
+                if attempt >= _CONNECT_ATTEMPTS or (left is not None and left <= pause):
+                    raise RunNotSubmitted(deployment_id, self.endpoint, attempts=attempt, cause=exc) from exc
+                _sleep(pause)
+            except httpx.RequestError as exc:
+                raise RunSubmissionUncertain(deployment_id) from exc
         if response.status_code >= 500:
             raise RunSubmissionUncertain(
                 deployment_id,

{cmpnd-0.80.0 → cmpnd-0.81.0}/cmpnd/execution.py

@@ -291,9 +291,11 @@ def _raise_stored_failure(run_id: str, result: object, endpoint: str) -> None:
     provider_failure = _retryable_provider_failure(response)
     if provider_failure is not None:
         provider_status, attempts, retry_after = provider_failure
+        # The worker's status says only that the run failed, and the provider's own
+        # status is in the detail, so the message leaves the worker's out.
         raise _with_run_id(
             RetryableProviderError(
-                message,
+                f"Deployment run {run_id} failed" + (f": {detail}" if detail else ""),
                 request=request,
                 response=response,
                 provider_status=provider_status,

{cmpnd-0.80.0 → cmpnd-0.81.0}/docs/sdk-instrumentation.md

@@ -457,7 +457,15 @@ Serve's not-ready `409` and `422` refusals keep the `RuntimeError` type and
 message that `run_deployment()` raises, and are `httpx.HTTPStatusError` too. A
 lost POST reply or a server `5xx` leaves acceptance uncertain, so the SDK raises
 `RunSubmissionUncertain` with `status_code` set when serve answered. Its message
-names the command to list recent runs. Reads that time out or answer `408`,
+names the command to list recent runs. A connection that never opened sent
+nothing: httpx raises `ConnectError` or `ConnectTimeout` only before any byte of
+the request is written. The SDK tries the POST up to three times, pausing about
+half a second and then a second, and stops early when the pause would outlast
+the budget. Then it raises `RunNotSubmitted`, which names the endpoint and the
+transport's reason, such as a refused connection, and says submitting again is
+safe. `RunNotSubmitted` subclasses `RunSubmissionUncertain`, so a handler for the
+uncertain case still catches it. A read timeout, a write failure or a broken
+reply may follow a sent request, so each stays uncertain. 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. Its `status` and
@@ -477,7 +485,11 @@ the same metadata, for a completed run's prediction and a failed run's error.
 trace, when the server names none, and when the run failed before serve
 accepted it. A
 retained provider failure keeps its structured `RetryableProviderError` type but
-does not start another run. Trace delivery can finish after the result is
+does not start another run. Its message is the provider's outage as the egress
+service reported it, such as `Deployment run dr_… failed: the provider at
+gw.lunaroute.com was unavailable: 3 attempt(s) over 3m1.367s; its last answer was
+503: backend unavailable`. It leaves out the worker's status, which the exception's
+`response` still carries, and the run's `error_code` is `ProviderUnavailable`. Trace delivery can finish after the result is
 available.
 
 Call `client.submit_deployment_run(deployment, inputs)` to accept work without a

{cmpnd-0.80.0 → cmpnd-0.81.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.80.0"
+version = "0.81.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"

{cmpnd-0.80.0 → cmpnd-0.81.0}/tests/test_deployment_runs.py

@@ -199,6 +199,95 @@ def test_execute_never_repeats_uncertain_post(monkeypatch: pytest.MonkeyPatch, f
     assert [req.method for req in seen] == ["POST"]
 
 
+@pytest.mark.parametrize(
+    ("failure", "cause"),
+    [
+        (httpx.ConnectError, "[Errno 61] Connection refused"),
+        (httpx.ConnectTimeout, "timed out"),
+    ],
+)
+def test_a_connection_that_never_opened_submitted_nothing(
+    monkeypatch: pytest.MonkeyPatch, failure: type[httpx.TransportError], cause: str
+):
+    seen: list[httpx.Request] = []
+
+    def answer(req: httpx.Request) -> httpx.Response:
+        seen.append(req)
+        raise failure(cause, request=req)
+
+    _transport(monkeypatch, answer)
+    _clock(monkeypatch)
+    with pytest.raises(deployment_runs.RunNotSubmitted) as caught:
+        _client().run_deployment(DEPLOYMENT_ID, question="hi")
+    error = caught.value
+    assert str(error) == (
+        f"Deployment {DEPLOYMENT_ID} was not submitted: no connection to https://example.test opened "
+        f"in {len(seen)} attempt(s) ({cause}). Nothing was sent, so submitting again is safe."
+    )
+    assert error.endpoint == "https://example.test"
+    assert error.deployment_id == DEPLOYMENT_ID
+    assert error.status_code is None
+    assert isinstance(error.__cause__, failure)
+    assert _client().deployment_run_id(error) is None
+    # A caller that already handles the uncertain outcome still catches it: inspecting
+    # the run list before resubmitting is unnecessary here, never wrong.
+    assert isinstance(error, deployment_runs.RunSubmissionUncertain)
+    assert cmpnd.RunNotSubmitted is deployment_runs.RunNotSubmitted
+    assert [req.method for req in seen] == ["POST"] * deployment_runs._CONNECT_ATTEMPTS
+
+
+def test_a_connection_that_opens_on_a_later_attempt_submits_once(monkeypatch: pytest.MonkeyPatch):
+    seen: list[str] = []
+
+    def answer(req: httpx.Request) -> httpx.Response:
+        seen.append(req.method)
+        if len(seen) == 1:
+            raise httpx.ConnectError("[Errno 61] Connection refused", request=req)
+        if req.method == "POST":
+            return httpx.Response(200, json=_run("completed", {"output": {"answer": "ready"}}), request=req)
+        raise AssertionError(f"unexpected {req.method}")
+
+    _transport(monkeypatch, answer)
+    _clock(monkeypatch)
+    assert _client().run_deployment(DEPLOYMENT_ID, question="hi").answer == "ready"
+    assert seen == ["POST", "POST"]
+
+
+def test_a_refused_connection_is_not_retried_past_the_budget(monkeypatch: pytest.MonkeyPatch):
+    seen: list[httpx.Request] = []
+    now = _clock(monkeypatch)
+
+    def answer(req: httpx.Request) -> httpx.Response:
+        seen.append(req)
+        now[0] += 1.0
+        raise httpx.ConnectError("[Errno 61] Connection refused", request=req)
+
+    _transport(monkeypatch, answer)
+    with pytest.raises(deployment_runs.RunNotSubmitted, match="in 1 attempt"):
+        _client().run_deployment(DEPLOYMENT_ID, timeout=1.2, question="hi")
+    assert len(seen) == 1
+
+
+@pytest.mark.parametrize(
+    "failure",
+    [httpx.ReadTimeout, httpx.ReadError, httpx.WriteError, httpx.WriteTimeout, httpx.RemoteProtocolError],
+)
+def test_a_failure_after_the_connection_opened_stays_uncertain(
+    monkeypatch: pytest.MonkeyPatch, failure: type[httpx.TransportError]
+):
+    seen: list[httpx.Request] = []
+
+    def answer(req: httpx.Request) -> httpx.Response:
+        seen.append(req)
+        raise failure("lost", request=req)
+
+    _transport(monkeypatch, answer)
+    with pytest.raises(deployment_runs.RunSubmissionUncertain, match="uncertain") as caught:
+        _client().run_deployment(DEPLOYMENT_ID, question="hi")
+    assert not isinstance(caught.value, deployment_runs.RunNotSubmitted)
+    assert len(seen) == 1
+
+
 def test_wait_polls_after_accepted_response_without_resubmitting(monkeypatch: pytest.MonkeyPatch):
     seen: list[str] = []
     replies = [

{cmpnd-0.80.0 → cmpnd-0.81.0}/tests/test_execute.py

@@ -272,6 +272,37 @@ def test_execute_stored_failure_preserves_run_id_and_provider_type(monkeypatch:
         assert type(caught.value) is httpx.HTTPStatusError
 
 
+OUTAGE = (
+    "the provider at gw.lunaroute.com was unavailable: 3 attempt(s) over 3m1.367s; "
+    "its last answer was 503: backend unavailable"
+)
+
+
+def test_a_provider_outage_reads_as_the_providers_and_names_no_platform_status(monkeypatch: pytest.MonkeyPatch):
+    failure = {
+        "error": {"type": "ProviderUnavailable", "message": OUTAGE},
+        "execution_status": 500,
+        "retryable": True,
+        "retry_after": 120,
+        "failure": {"domain": "provider", "class": "provider_unavailable", "upstream_status": 503, "attempts": 3},
+    }
+    _transport(monkeypatch, lambda req: httpx.Response(200, json=_run("failed", failure), request=req))
+    with pytest.raises(execution.RetryableProviderError) as caught:
+        _client().run_deployment("d_ready")
+    assert str(caught.value) == f"Deployment run {RUN_ID} failed: {OUTAGE}"
+    # The status stays on the exception for a caller that reads it.
+    assert caught.value.response.status_code == 500
+    assert (caught.value.provider_status, caught.value.attempts, caught.value.retry_after) == (503, 3, 120)
+
+
+def test_a_failure_that_is_not_the_providers_keeps_its_status(monkeypatch: pytest.MonkeyPatch):
+    failure = {"error": {"type": "RunFailed", "message": "KeyError: 'answer'"}, "execution_status": 500}
+    _transport(monkeypatch, lambda req: httpx.Response(200, json=_run("failed", failure), request=req))
+    with pytest.raises(httpx.HTTPStatusError) as caught:
+        _client().run_deployment("d_ready")
+    assert str(caught.value) == f"Deployment run {RUN_ID} failed with 500: KeyError: 'answer'"
+
+
 class TestDeployedProgram:
     def test_identity_and_repr(self):
         deployed = execution.DeployedProgram("d_ready")

{cmpnd-0.80.0 → cmpnd-0.81.0}/uv.lock

@@ -505,7 +505,7 @@ wheels = [
 
 [[package]]
 name = "cmpnd"
-version = "0.80.0"
+version = "0.81.0"
 source = { editable = "." }
 default-groups = ["dspy-3-4-1"]
 dependencies = [