cmpnd 0.80.0__tar.gz → 0.82.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.80.0
+Version: 0.82.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.82.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.82.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.82.0}/cmpnd/cli/commands/optimizations.py

@@ -6,7 +6,7 @@ import sys
 from argparse import ArgumentParser, _SubParsersAction
 from typing import Any
 
-from .. import api_client, deprecation, pagination
+from .. import api_client, deprecation, pagination, views
 from . import top
 
 
@@ -20,6 +20,7 @@ def _add_list_args(p: ArgumentParser) -> None:
     p.add_argument("--optimizer-type", help="Filter by optimizer type")
     p.add_argument("--min-score", type=float, help="Minimum best score")
     pagination.add_args(p, with_page_aliases=True, default_limit=50)
+    views.add_text_flag(p)
 
 
 def _add_comparability_args(p: ArgumentParser) -> None:
@@ -172,7 +173,8 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     failed.set_defaults(func=handle_compare_failed_examples)
 
     iters = sub.add_parser("iterations", help="List iterations for an optimization run")
-    iters.add_argument("id", help="Optimization run ID (UUID)")
+    iters.add_argument("id", help="Optimization run ID (op_...)")
+    views.add_text_flag(iters)
     iters.set_defaults(func=handle_iterations)
 
     cands = sub.add_parser(
@@ -187,6 +189,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         "optimization actually wrote. Off by default: the text dwarfs the metrics, "
         "and listing candidates is usually how you find the one worth reading",
     )
+    views.add_text_flag(cands)
     cands.set_defaults(func=handle_candidates)
 
     compiled = sub.add_parser(
@@ -226,7 +229,11 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
 
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
     if getattr(args, "status", None) == "queued":
-        return _list_queued(client, args)
+        payload = _list_queued(client, args)
+        if getattr(args, "text", False):
+            _render_queued(payload)
+            return None
+        return payload
     # This route paginates by page/per_page; the shared helper maps the
     # user-facing --limit/--offset onto that pair.
     body: dict[str, Any] = pagination.wire(args, "per_page")
@@ -239,7 +246,112 @@ def handle_list(client: api_client.ApiClient, args: Any) -> Any:
         val = getattr(args, attr, None)
         if val is not None:
             body[key] = val
-    return client.post("/api/v1/optimizations/search", json=body)
+    payload = client.post("/api/v1/optimizations/search", json=body)
+    if getattr(args, "text", False):
+        _render_runs(payload)
+        return None
+    return payload
+
+
+# The statuses of a run that has not settled. Serve's open set: `interrupted` is open and
+# not progressing, and any delivered progress returns it to `running`.
+_OPEN_STATUSES = ("running", "interrupted")
+
+# What a cell shows for a value serve does not hold. Never a zero: a zero is a value.
+_UNRECORDED = "-"
+
+
+def _rows(payload: Any, key: str) -> list[dict[str, Any]]:
+    items = payload.get(key) if isinstance(payload, dict) else None
+    return [item for item in items or [] if isinstance(item, dict)]
+
+
+def _table(header: tuple[str, ...], rows: list[tuple[str, ...]]) -> None:
+    """Print rows under a header, each column as wide as its widest cell."""
+    widths = [max(len(row[i]) for row in [header, *rows]) for i in range(len(header))]
+    for row in [header, *rows]:
+        print("  ".join(cell.ljust(widths[i]) for i, cell in enumerate(row)).rstrip())
+
+
+def _score(value: Any) -> str:
+    return f"{value:.3f}" if isinstance(value, (int, float)) and not isinstance(value, bool) else _UNRECORDED
+
+
+def _int(value: Any) -> str:
+    return str(value) if isinstance(value, int) and not isinstance(value, bool) else _UNRECORDED
+
+
+def _metric_calls(run: dict[str, Any]) -> str:
+    """Metric calls spent of the budget. An open run reads its live counter, which serve
+    keeps the total in step with; a settled run reads its total."""
+    used = run.get("total_metric_calls")
+    live = run.get("current_metric_calls")
+    if isinstance(live, int) and (not isinstance(used, int) or live > used):
+        used = live
+    budget = run.get("max_metric_calls")
+    if not isinstance(used, int):
+        return _UNRECORDED
+    return f"{used}/{budget}" if isinstance(budget, int) and budget > 0 else str(used)
+
+
+def _best_score(run: dict[str, Any]) -> str:
+    """The run's best score. Serve sends `best_score` as zero until the run records one,
+    and flags that with `best_score_recorded: false`. A serve that sends no flag leaves
+    an unrecorded score indistinguishable from a measured zero, so the score shows."""
+    if run.get("best_score_recorded") is False:
+        return _UNRECORDED
+    return _score(run.get("best_score"))
+
+
+def _verdicts(run: dict[str, Any]) -> str:
+    """Accepted and rejected proposals, as the run's producer counted them. A run that
+    never reported them shows a dash rather than 0/0."""
+    accepted, rejected = run.get("candidates_accepted"), run.get("candidates_rejected")
+    if accepted is None and rejected is None:
+        return _UNRECORDED
+    return f"{_int(accepted)}/{_int(rejected)}"
+
+
+def _render_runs(payload: Any) -> None:
+    runs = _rows(payload, "optimization_runs")
+    if not runs:
+        print("No optimization runs match.")
+        return
+    rows = [
+        (
+            str(run.get("run_id") or ""),
+            str(run.get("status") or ""),
+            str(run.get("program_name") or _UNRECORDED),
+            str(run.get("optimizer_type") or ""),
+            _metric_calls(run),
+            _verdicts(run),
+            _best_score(run),
+            str(run.get("start_time") or ""),
+        )
+        for run in runs
+    ]
+    _table(("RUN", "STATUS", "PROGRAM", "OPTIMIZER", "METRIC CALLS", "ACCEPTED/REJECTED", "BEST", "STARTED"), rows)
+    total = payload.get("total") if isinstance(payload, dict) else None
+    if isinstance(total, int) and total > len(runs):
+        print(f"{len(runs)} of {total} runs. Page with --limit and --offset.")
+
+
+def _render_queued(payload: Any) -> None:
+    queued = _rows(payload, "optimizations")
+    if not queued:
+        print("No optimization runs are queued.")
+        return
+    rows = [
+        (
+            _int(run.get("position")),
+            str(run.get("optimization_id") or ""),
+            str(run.get("status") or "queued"),
+            str(run.get("optimizer") or ""),
+            str(run.get("created_at") or ""),
+        )
+        for run in queued
+    ]
+    _table(("POSITION", "RUN", "STATUS", "OPTIMIZER", "QUEUED AT"), rows)
 
 
 def _list_queued(client: api_client.ApiClient, args: Any) -> Any:
@@ -370,12 +482,114 @@ def handle_compare_failed_examples(client: api_client.ApiClient, args: Any) -> A
 
 
 def handle_iterations(client: api_client.ApiClient, args: Any) -> Any:
-    return client.get(f"/api/v1/optimizations/{args.id}/iterations")
+    payload = client.get(f"/api/v1/optimizations/{args.id}/iterations")
+    if not getattr(args, "text", False):
+        return payload
+    _render_iterations(args.id, payload)
+    return None
+
+
+def _verdict(iteration: dict[str, Any]) -> str:
+    accepted = iteration.get("accepted")
+    if accepted is None:
+        return _UNRECORDED
+    return "accepted" if accepted else "rejected"
+
+
+def _result(iteration: dict[str, Any]) -> str:
+    """The candidate an accepted proposal became, with its validation score."""
+    idx = iteration.get("result_candidate_idx")
+    if not isinstance(idx, int):
+        return _UNRECORDED
+    score = iteration.get("validation_score")
+    return f"{idx} ({_score(score)})" if isinstance(score, (int, float)) else str(idx)
+
+
+def _render_iterations(run_id: str, payload: Any) -> None:
+    """One row per iteration: the candidate it mutated and that candidate's minibatch mean,
+    the proposal's mean over the same minibatch, gepa's verdict, and the candidate an
+    accepted proposal became. A dash is a value serve does not hold for that iteration."""
+    iterations = _rows(payload, "iterations")
+    if not iterations:
+        print(f"{run_id} has no iterations yet.")
+        return
+    rows = [
+        (
+            _int(it.get("idx")),
+            _int(it.get("parent_candidate_idx")),
+            str(it.get("batch_size") or _UNRECORDED),
+            _score(it.get("parent_minibatch_score")),
+            _score(it.get("proposal_minibatch_score")),
+            _verdict(it),
+            _result(it),
+            str(it.get("duration") or _UNRECORDED),
+        )
+        for it in iterations
+    ]
+    _table(
+        ("ITER", "PARENT", "BATCH", "PARENT SCORE", "PROPOSAL SCORE", "VERDICT", "CANDIDATE", "DURATION"),
+        rows,
+    )
+    print(
+        "Scores are means over the iteration's minibatch. CANDIDATE is the candidate an accepted "
+        "proposal became, with its validation score."
+    )
+    if any(_UNRECORDED in row[1:] for row in rows):
+        print(
+            f"{_UNRECORDED}: not recorded for that iteration. An open run holds what its optimizer "
+            "has reported so far, and the settled record fills the rest."
+        )
 
 
 def handle_candidates(client: api_client.ApiClient, args: Any) -> Any:
     params = {"include": "instructions"} if getattr(args, "full", False) else None
-    return client.get(f"/api/v1/optimizations/{args.id}/candidates", params=params)
+    payload = client.get(f"/api/v1/optimizations/{args.id}/candidates", params=params)
+    if not getattr(args, "text", False):
+        return payload
+    _render_candidates(args.id, payload, full=getattr(args, "full", False))
+    return None
+
+
+def _origin(candidate: dict[str, Any]) -> str:
+    """How the candidate entered the pool. The seed starts it; every other candidate came
+    from an accepted proposal, a reflective mutation or a merge."""
+    if "accepted" not in candidate or candidate.get("mutation_type") == "seed":
+        return "seed"
+    return f"accepted ({candidate.get('mutation_type') or 'proposal'})"
+
+
+def _render_candidates(run_id: str, payload: Any, *, full: bool) -> None:
+    candidates = _rows(payload, "candidates")
+    status = payload.get("run_status") if isinstance(payload, dict) else None
+    summary = [f"{run_id}: {status}" if status else run_id]
+    if isinstance(payload, dict) and ("candidates_accepted" in payload or "candidates_rejected" in payload):
+        summary.append(
+            f"{_int(payload.get('candidates_accepted'))} accepted, {_int(payload.get('candidates_rejected'))} rejected"
+        )
+    summary.append(f"{len(candidates)} candidate{'' if len(candidates) == 1 else 's'} listed")
+    print(" · ".join(summary))
+    if candidates:
+        rows = [
+            (
+                str(c.get("candidate_id") or ""),
+                _int(c.get("candidate_idx", c.get("idx"))),
+                _int(c.get("parent_candidate_idx")),
+                str(c.get("generation") or _UNRECORDED),
+                _score(c.get("aggregate_score")),
+                _origin(c),
+                "yes" if c.get("is_pareto_member") else "",
+            )
+            for c in candidates
+        ]
+        _table(("CANDIDATE", "IDX", "PARENT", "GEN", "VAL SCORE", "ORIGIN", "PARETO"), rows)
+        if full:
+            for c in candidates:
+                print(f"{c.get('candidate_id')}: {_first_line(_instruction_texts(c.get('instructions')))}")
+    if status in _OPEN_STATUSES:
+        print(
+            "The run is open: the list grows as the optimizer reports each candidate it accepts, "
+            "and the settled record completes it."
+        )
 
 
 def handle_compiled_program(client: api_client.ApiClient, args: Any) -> Any:

{cmpnd-0.80.0 → cmpnd-0.82.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.82.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.82.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.82.0}/docs/cli.md

@@ -190,8 +190,9 @@ does the same.
 A namespaced read, such as `cmpnd traces show`, `cmpnd deployments list` or
 `cmpnd tool-servers list`, prints the API's JSON by default, so a script can
 pipe it to `jq`. A human view is an opt-in flag: `--tree` and `--timeline` on
-`traces show`, and `--text` on `tool-servers list`, `tool-servers show` and
-`credentials list`. Those three accept `--json` as well, so older scripts keep
+`traces show`, and `--text` on `tool-servers list`, `tool-servers show`,
+`credentials list`, `optimizations list`, `optimizations iterations` and
+`optimizations candidates`. Those accept `--json` as well, so older scripts keep
 working. An action command may print a short result and take `--json` for the
 whole answer: `cmpnd programs create` prints the new id, and
 `cmpnd optimizations continue` prints the best deployment. The top-level
@@ -798,6 +799,36 @@ live objects and takes named models through its `lms` argument. An authored file
 binding cannot be combined with `lms` in the parent call or `config["lms"]`.
 The CLI has no named-model flag.
 
+### Watch a run
+
+A hosted run reports its progress while it runs, so these reads show an open
+run as it is. Each prints the API's JSON, and `--text` renders a table.
+
+- `cmpnd optimizations list --text` shows each run's status, its metric calls
+  of the budget, its accepted and rejected proposals and its best score. The
+  JSON's `total_metric_calls` keeps pace with `current_metric_calls` while the
+  run is open, and `total_candidates` counts the candidates the platform holds
+  for it, which `candidates` lists. `best_score` reads 0 until the run
+  records a score, and `best_score_recorded` is `false` until then, so
+  `--text` shows a dash. `show` and `list` read the same row, so they agree.
+- `cmpnd optimizations iterations RUN_ID` lists each iteration: the candidate
+  it mutated (`parent_candidate_idx`) and that candidate's mean over the
+  iteration's minibatch (`parent_minibatch_score`), the proposal's mean over the
+  same minibatch (`proposal_minibatch_score`), whether gepa `accepted` it, the
+  candidate an accepted proposal became (`result_candidate_idx`) with its
+  `validation_score`, and its `batch_size` and `duration_ms`. A field the
+  platform does not hold for an iteration is left out, and `--text` shows a
+  dash. A run the SDK tracks on your machine reports only each iteration's
+  number and score until it settles.
+- `cmpnd optimizations candidates RUN_ID` lists every candidate the run holds,
+  beside its `run_status` and its `candidates_accepted` and
+  `candidates_rejected` counts. An open hosted run lists each candidate as the
+  optimizer accepts it, and the settled record completes the list and keeps
+  each `ca_` id. A run the SDK tracks lists its candidates once it settles.
+  The seed carries no `accepted`, because no verdict admitted it.
+- `cmpnd optimizations show RUN_ID` names the run's `reflection_model_name`
+  from the moment it starts.
+
 ### Cancel a run
 
 `cmpnd optimizations cancel RUN_ID` stops an open run and keeps its record,

{cmpnd-0.80.0 → cmpnd-0.82.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.82.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.82.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"