cmpnd 0.71.0__tar.gz → 0.72.0__tar.gz

{cmpnd-0.71.0 → cmpnd-0.72.0}/PKG-INFO

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

{cmpnd-0.71.0 → cmpnd-0.72.0}/cmpnd/cli/commands/deployments.py

@@ -191,6 +191,9 @@ def submit_cli_run(
         raise
     except httpx.HTTPStatusError as exc:
         raise _http_refusal(exc) from exc
+    trace_id = settled.get("trace_id")
+    if isinstance(trace_id, str) and trace_id:
+        print(f"Trace: {trace_id}", file=sys.stderr)
     if settled["status"] == "failed":
         return settled, None
     result = settled.get("result")

{cmpnd-0.71.0 → cmpnd-0.72.0}/cmpnd/client.py

@@ -390,6 +390,19 @@ class Client:
 
         return execution.deployment_run_id(result_or_error)
 
+    def get_trace_id(self, result_or_error: Any) -> str | None:
+        """The root trace id of a ``run_deployment`` prediction or exception.
+
+        It reads the id serve returned with the settled run and sends no
+        request. ``get_trace`` opens the trace.
+        The id lives outside the prediction's output fields. A run that stored no
+        trace, a server that names none, and a failure before serve accepted a run
+        all return ``None``.
+        """
+        from . import execution
+
+        return execution.get_trace_id(result_or_error)
+
     def submit_deployment_run(
         self,
         deployment_or_id: Any,

{cmpnd-0.71.0 → cmpnd-0.72.0}/cmpnd/execution.py

@@ -33,6 +33,21 @@ def deployment_run_id(result_or_error: Any) -> str | None:
     return getattr(result_or_error, "_cmpnd_deployment_run_id", None)
 
 
+def get_trace_id(result_or_error: Any) -> str | None:
+    """Return the root trace id serve named for a run's prediction or exception.
+
+    The id lives outside the prediction's program output fields. A run that
+    stored no trace, a server that names none, and a failure before serve
+    accepted a run all return ``None``.
+    """
+    return getattr(result_or_error, "_cmpnd_deployment_trace_id", None)
+
+
+def _settled_trace_id(settled: dict[str, Any]) -> str | None:
+    trace_id = settled.get("trace_id")
+    return trace_id if isinstance(trace_id, str) and trace_id else None
+
+
 def _with_run_id(error: Exception, run_id: str | None) -> Exception:
     error._cmpnd_deployment_run_id = run_id  # pyright: ignore[reportAttributeAccessIssue]
     return error
@@ -247,14 +262,20 @@ def run_deployment(
         raise
 
     settled_id: str = settled["deployment_run_id"]
+    trace_id = _settled_trace_id(settled)
     result = settled["result"]
     if settled["status"] == "failed":
-        _raise_stored_failure(settled_id, result, config.endpoint)
+        try:
+            _raise_stored_failure(settled_id, result, config.endpoint)
+        except Exception as error:
+            error._cmpnd_deployment_trace_id = trace_id  # pyright: ignore[reportAttributeAccessIssue]
+            raise
     if not isinstance(result, dict) or "output" not in result:
         raise _with_run_id(RuntimeError("Deployment run result has no program output"), settled_id)
     output = result["output"]
     prediction = Prediction(**output) if isinstance(output, dict) else Prediction(**{"output": output})
     setattr(prediction, "_cmpnd_deployment_run_id", settled_id)
+    setattr(prediction, "_cmpnd_deployment_trace_id", trace_id)
     return prediction
 
 

{cmpnd-0.71.0 → cmpnd-0.72.0}/docs/cli.md

@@ -228,6 +228,10 @@ seconds, unless `--timeout` sets the budget. The CLI prints the accepted run ID
 on stderr as soon as serve replies, which can take up to serve's five-second
 wait. A failed run exits nonzero. Human mode prints the stored error code,
 message and provider status. `--json` prints the whole settled run on stdout.
+When a settled run names its root trace, the CLI prints `Trace: <id>` on
+stderr, completed or failed. `cmpnd traces show <id>` opens that trace. The
+run's `trace_id` field holds the same ID, and serve leaves it out when the run
+stored no trace.
 The CLI retries status reads that time out or answer `408`, `429` or `5xx`
 within the budget.
 

{cmpnd-0.71.0 → cmpnd-0.72.0}/docs/client.md

@@ -147,7 +147,9 @@ endpoint. None of these reads the global config:
 - `sdk.submit_deployment_run`, `list_deployment_runs`, `get_deployment_run`,
   `get_deployment_run_result` and `wait_deployment_run` submit, find and resume
   runs without waiting in one call. `sdk.deployment_run_id(result)` reads the run
-  id of a prediction or an exception.
+  id of a prediction or an exception. `sdk.get_trace_id(result)` reads the
+  id of the run's root trace the same way, or returns `None` when serve named no
+  trace.
 - `sdk.optimize_deployment(deployment, optimizer="gepa", ...)` runs the
   platform's optimization on a deployment and returns the best
   `DeployedProgram`, with `.score`. It never deploys. The program's model comes

{cmpnd-0.71.0 → cmpnd-0.72.0}/docs/sdk-instrumentation.md

@@ -432,7 +432,12 @@ command, and re-raises.
 `client.deployment_run_id(result)` reads the ID from
 private prediction metadata, so a program can use `output` or
 `deployment_run_id` as an output field. The accessor also accepts a stored
-execution error, a refused read, `RunWaitTimeout` and `RunResultExpired`. A
+execution error, a refused read, `RunWaitTimeout` and `RunResultExpired`.
+`client.get_trace_id(result)` reads the id of the run's root trace from
+the same metadata, for a completed run's prediction and a failed run's error.
+`cmpnd traces show` opens that trace. It returns `None` when the run stored no
+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
 available.
@@ -454,8 +459,10 @@ header readable.
 try:
     result = client.run_deployment(deployed, question="What changed?")
     run_id = client.deployment_run_id(result)
+    trace_id = client.get_trace_id(result)
 except Exception as error:
     run_id = client.deployment_run_id(error)
+    trace_id = client.get_trace_id(error)
     raise
 ```
 

{cmpnd-0.71.0 → cmpnd-0.72.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.71.0"
+version = "0.72.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"

{cmpnd-0.71.0 → cmpnd-0.72.0}/tests/test_cli/test_deployment_runs.py

@@ -537,3 +537,37 @@ def test_json_run_commands_do_not_import_dspy(argv: list[str], replies: list):
     assert "JSON run command imported dspy" not in result.stderr
     out = json.loads(result.stdout)
     assert RUN_ID in result.stdout or "yes" in json.dumps(out)
+
+
+TRACE_ID = "0b9c6f2e-4f1d-4c3a-9e2b-7a1d5c3e8f00"
+
+
+def test_failed_run_names_its_trace_on_stderr(monkeypatch: pytest.MonkeyPatch, capsys):
+    failure = {"error": {"type": "ProgramError", "message": "bad input"}, "execution_status": 500}
+
+    def answer(req):
+        return httpx.Response(200, json={**_envelope("failed", failure), "trace_id": TRACE_ID}, request=req)
+
+    with pytest.raises(SystemExit):
+        _run_cli(monkeypatch, ["run", DEPLOYMENT_ID, "{}"], answer)
+    assert f"Trace: {TRACE_ID}" in capsys.readouterr().err
+
+
+def test_completed_run_names_its_trace_on_stderr_and_keeps_stdout_the_output(monkeypatch: pytest.MonkeyPatch, capsys):
+    def answer(req):
+        return httpx.Response(
+            200, json={**_envelope("completed", {"output": {"answer": "yes"}}), "trace_id": TRACE_ID}, request=req
+        )
+
+    _run_cli(monkeypatch, ["run", DEPLOYMENT_ID, "{}", "--json"], answer)
+    out = capsys.readouterr()
+    assert json.loads(out.out) == {"answer": "yes"}
+    assert f"Trace: {TRACE_ID}" in out.err
+
+
+def test_run_without_a_trace_names_none(monkeypatch: pytest.MonkeyPatch, capsys):
+    def answer(req):
+        return httpx.Response(200, json=_envelope("completed", {"output": {"answer": "yes"}}), request=req)
+
+    _run_cli(monkeypatch, ["run", DEPLOYMENT_ID, "{}", "--json"], answer)
+    assert "Trace:" not in capsys.readouterr().err

{cmpnd-0.71.0 → cmpnd-0.72.0}/tests/test_deployment_runs.py

@@ -505,3 +505,71 @@ def test_failure_summary_names_code_message_and_provider_status():
         f"Deployment run {RUN_ID} failed: EgressFailed: provider failed (provider status 429)"
     )
     assert deployment_runs.failure_summary(_run("failed", {"error": "boom"})) == f"Deployment run {RUN_ID} failed: boom"
+
+
+TRACE_ID = "0b9c6f2e-4f1d-4c3a-9e2b-7a1d5c3e8f00"
+
+
+def test_a_completed_run_names_its_trace_beside_its_run_id(monkeypatch: pytest.MonkeyPatch):
+    def answer(req: httpx.Request) -> httpx.Response:
+        body = {**_run("completed", {"output": {"answer": "yes"}}, available=True), "trace_id": TRACE_ID}
+        return httpx.Response(200, json=body, request=req)
+
+    _transport(monkeypatch, answer)
+    prediction = _client().run_deployment(DEPLOYMENT_ID, question="hi")
+    assert prediction.answer == "yes"
+    assert _client().get_trace_id(prediction) == TRACE_ID
+    assert _client().deployment_run_id(prediction) == RUN_ID
+    assert "trace_id" not in prediction.keys()
+
+
+def test_a_failed_run_names_its_trace_on_the_raised_error(monkeypatch: pytest.MonkeyPatch):
+    failure = {"error": {"type": "ProgramError", "message": "bad input"}, "execution_status": 500}
+
+    def answer(req: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={**_run("failed", failure, available=True), "trace_id": TRACE_ID}, request=req)
+
+    _transport(monkeypatch, answer)
+    with pytest.raises(httpx.HTTPStatusError) as caught:
+        _client().run_deployment(DEPLOYMENT_ID)
+    assert _client().get_trace_id(caught.value) == TRACE_ID
+    assert _client().deployment_run_id(caught.value) == RUN_ID
+
+
+def test_a_retryable_provider_failure_names_its_trace(monkeypatch: pytest.MonkeyPatch):
+    failure = {
+        "error": {"type": "EgressFailed", "message": "provider refused"},
+        "execution_status": 503,
+        "retryable": True,
+        "failure": {"domain": "provider", "upstream_status": 429, "attempts": 3},
+    }
+
+    def answer(req: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={**_run("failed", failure, available=True), "trace_id": TRACE_ID}, request=req)
+
+    _transport(monkeypatch, answer)
+    with pytest.raises(cmpnd.RetryableProviderError) as caught:
+        _client().run_deployment(DEPLOYMENT_ID)
+    assert _client().get_trace_id(caught.value) == TRACE_ID
+
+
+@pytest.mark.parametrize("trace_field", [{}, {"trace_id": None}, {"trace_id": ""}, {"trace_id": 7}])
+def test_a_run_serve_names_no_trace_for_has_none(monkeypatch: pytest.MonkeyPatch, trace_field: dict):
+    def answer(req: httpx.Request) -> httpx.Response:
+        body = {**_run("completed", {"output": {"answer": "yes"}}, available=True), **trace_field}
+        return httpx.Response(200, json=body, request=req)
+
+    _transport(monkeypatch, answer)
+    prediction = _client().run_deployment(DEPLOYMENT_ID, question="hi")
+    assert _client().get_trace_id(prediction) is None
+
+
+def test_a_failure_before_acceptance_has_no_trace(monkeypatch: pytest.MonkeyPatch):
+    def answer(req: httpx.Request) -> httpx.Response:
+        return httpx.Response(404, json={"error": "not found"}, request=req)
+
+    _transport(monkeypatch, answer)
+    with pytest.raises(httpx.HTTPStatusError) as caught:
+        _client().run_deployment(DEPLOYMENT_ID)
+    assert _client().get_trace_id(caught.value) is None
+    assert _client().get_trace_id(object()) is None

{cmpnd-0.71.0 → cmpnd-0.72.0}/uv.lock

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