cmpnd 0.31.0__tar.gz → 0.32.0__tar.gz

{cmpnd-0.31.0 → cmpnd-0.32.0}/PKG-INFO

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

{cmpnd-0.31.0 → cmpnd-0.32.0}/cmpnd/__init__.py

@@ -33,7 +33,7 @@ from .deployment_metadata import (
     DeploymentSignatureResponse,
     UnsupportedDeploymentMetadataVersion,
 )
-from .execution import DeployedProgram, RetryableProviderError, execute
+from .execution import DeployedProgram, RetryableProviderError, deployment_run_id, execute
 from .exporter import flush_exporter, shutdown_exporter
 from .lm_configuration import configure_lm
 from .mcp_servers import (
@@ -104,6 +104,7 @@ __all__ = [
     "DeploymentMetadataError",
     "UnsupportedDeploymentMetadataVersion",
     "execute",
+    "deployment_run_id",
     "DeployedProgram",
     "RetryableProviderError",
     # Optimize

{cmpnd-0.31.0 → cmpnd-0.32.0}/cmpnd/_gepa_patch.py

@@ -10,8 +10,6 @@ module-style (``from . import identity``); basedpyright can't resolve
 
 import contextvars
 
-from . import context
-
 _gepa_patched = False
 
 # Set by a client's run_optimization while it owns the run. The class patch reads
@@ -22,6 +20,12 @@ _client_owns_optimization: contextvars.ContextVar[bool] = contextvars.ContextVar
     "cmpnd_client_owns_optimization", default=False
 )
 
+# TrackedGEPA reserves its own run before invoking this native optimizer. Match
+# the instance so an unrelated optimizer nested inside it still gets a run.
+_tracked_compile_optimizer: contextvars.ContextVar[object | None] = contextvars.ContextVar(
+    "cmpnd_tracked_compile_optimizer", default=None
+)
+
 
 def _gepa_supports_callbacks() -> bool:
     """Check if the installed gepa version supports callbacks in optimize()."""
@@ -110,8 +114,7 @@ def _run_tracked_compile(
         max_metric_calls=max_metric_calls,
     )
 
-    trk.start()
-    context.set_current_optimization_run_id(trk.optimization_run_id)
+    restore_attribution = callback.start_trace_attribution()
 
     try:
         result = run_original()
@@ -139,8 +142,7 @@ def _run_tracked_compile(
         raise
 
     finally:
-        context.set_current_optimization_run_id(None)
-        callback.clear_trace_association_state()
+        restore_attribution()
 
 
 def patch_gepa() -> None:
@@ -176,9 +178,9 @@ def patch_gepa() -> None:
         type(self)._cmpnd_original_init(self, *args, **kwargs)
 
     def _patched_compile(self, student, *, trainset, teacher=None, valset=None, **kwargs):
-        # When a client's run_optimization owns this run it records the run on its
-        # own account and has suppressed the global track; run the search only.
-        if _client_owns_optimization.get():
+        # A client or TrackedGEPA already records this run. TrackedGEPA claims
+        # only its own optimizer instance, leaving distinct nested runs tracked.
+        if _client_owns_optimization.get() or _tracked_compile_optimizer.get() is self:
             return type(self)._cmpnd_original_compile(
                 self, student, trainset=trainset, teacher=teacher, valset=valset, **kwargs
             )

{cmpnd-0.31.0 → cmpnd-0.32.0}/cmpnd/_http.py

@@ -11,6 +11,7 @@ resolution; this module is only the wire.
 from __future__ import annotations
 
 import os
+import re
 from typing import Any
 
 import httpx
@@ -24,10 +25,45 @@ class ApiError(Exception):
     is the process exit the CLI maps the error to; the library client ignores it.
     """
 
-    def __init__(self, message: str, exit_code: int = 1, *, status_code: int | None = None):
+    def __init__(
+        self,
+        message: str,
+        exit_code: int = 1,
+        *,
+        status_code: int | None = None,
+        deployment_run_id: str | None = None,
+    ):
         super().__init__(message)
         self.exit_code = exit_code
         self.status_code = status_code
+        self._cmpnd_deployment_run_id = deployment_run_id
+
+
+def response_deployment_run_id(response: httpx.Response) -> str | None:
+    """Read the server's execute correlation key from its JSON response body."""
+    try:
+        body = response.json()
+    except ValueError:
+        return None
+    return _body_deployment_run_id(body)
+
+
+def _body_deployment_run_id(body: object) -> str | None:
+    run_id = body.get("deployment_run_id") if isinstance(body, dict) else None
+    if isinstance(run_id, str) and re.fullmatch(r"dr_[A-Za-z0-9]{12}", run_id):
+        return run_id
+    return None
+
+
+def execute_response_output(response: httpx.Response) -> tuple[dict[str, Any], str]:
+    """Read program output and serve's run id from the execute envelope."""
+    body = response.json()
+    run_id = _body_deployment_run_id(body)
+    if not isinstance(body, dict) or run_id is None or not isinstance(body.get("output"), dict):
+        error = RuntimeError("Execute response has an invalid run envelope")
+        error._cmpnd_deployment_run_id = run_id  # pyright: ignore[reportAttributeAccessIssue]
+        raise error
+    return body["output"], run_id
 
 
 def server_detail(response: httpx.Response) -> str:
@@ -81,6 +117,10 @@ class ApiClient:
     def post(self, path: str, json: dict[str, Any] | None = None) -> Any:
         return self._request("POST", path, json=json)
 
+    def post_response(self, path: str, json: dict[str, Any] | None = None) -> httpx.Response:
+        """POST through the shared error ladder and return the complete response."""
+        return self._request("POST", path, json=json, return_response=True)
+
     def patch(self, path: str, json: dict[str, Any] | None = None) -> Any:
         return self._request("PATCH", path, json=json)
 
@@ -100,6 +140,7 @@ class ApiClient:
         params: dict[str, str] | None = None,
         json: dict[str, Any] | None = None,
         decode: bool | None = True,
+        return_response: bool = False,
     ) -> Any:
         url = f"{self._endpoint}{path}"
         # 180s default: deploy/optimize/run wait in-band on an LM round-trip
@@ -137,15 +178,22 @@ class ApiClient:
         except httpx.TimeoutException:
             raise ApiError(f"Request timed out connecting to {self._endpoint}.")
 
+        run_id = response_deployment_run_id(response) if response.status_code >= 400 else None
+
+        def error(message: str, exit_code: int = 1) -> ApiError:
+            if run_id:
+                message += f"\nDeployment run: {run_id}"
+            return ApiError(message, exit_code, status_code=response.status_code, deployment_run_id=run_id)
+
         if response.status_code == 401:
-            raise ApiError("Invalid or missing API key. Check CMPND_API_KEY or --api-key.", status_code=401)
+            raise error("Invalid or missing API key. Check CMPND_API_KEY or --api-key.")
         if response.status_code == 404:
             # The server's own words, not a generic stand-in. Every route here 404s
             # for a reason it already states — "signature not found", "deployment
             # not found", "no such organization" — and flattening them into one
             # sentence makes a missing record and a mistyped URL read identically,
             # which is the difference a user needs most and had the least of.
-            raise ApiError(server_detail(response) or "Resource not found.", status_code=404)
+            raise error(server_detail(response) or "Resource not found.")
         if response.status_code >= 500:
             # 5xx usually means the server is up but blew up handling the
             # request — a database hiccup, an unhandled exception, etc.
@@ -157,13 +205,16 @@ class ApiClient:
             if body_excerpt:
                 msg += f": {body_excerpt}"
             msg += "\n  If you operate this server, check its logs for the underlying exception."
-            raise ApiError(msg, exit_code=2, status_code=response.status_code)
+            raise error(msg, exit_code=2)
         if response.status_code >= 400:
             try:
                 detail = response.json()
             except Exception:
                 detail = response.text
-            raise ApiError(f"Request failed ({response.status_code}): {detail}", status_code=response.status_code)
+            raise error(f"Request failed ({response.status_code}): {detail}")
+
+        if return_response:
+            return response
 
         # A bytes route hands the raw body back before httpx decodes it.
         if decode is None:

{cmpnd-0.31.0 → cmpnd-0.32.0}/cmpnd/callback.py

@@ -929,19 +929,21 @@ class _ModuleMixin(_CallbackBase):
                 trace.span_count = len(trace_spans)
                 logger.debug(f"Trace totals: {trace.total_tokens} tokens, ${trace.total_cost}")
 
-                # Link trace to optimization run if we're inside one
-                # Try instance var first (thread-safe), fall back to contextvar
-
-                opt_run_id = self._active_optimization_run_id or context.get_current_optimization_run_id()
-                if opt_run_id:
-                    trace.optimization_run_id = opt_run_id
-
-                # If we're in an eval run, collect trace for metric correlation
-                # Use instance var (thread-safe) instead of contextvar (thread-local)
-                current_eval = self._active_eval_run
-                if current_eval:
-                    eval_run_id = str(current_eval.eval_run_id)
-                    trace.eval_run_id = current_eval.eval_run_id
+                # trace.optimization_run_id and trace.eval_run_id were attached
+                # in _create_trace, from this callback's own active-run state
+                # when the trace started. Do not re-read that state here: by
+                # finalize the run may already have ended (a trace that
+                # outlives it), and re-reading would drop the attribution the
+                # start row already sent — the trace keeps the ids it started
+                # with either way.
+
+                # If this trace's eval run is still collecting traces for
+                # metric correlation, add it — keyed by the id the trace
+                # already carries, not by whether the eval is still the live
+                # one (it may have finalized already, in which case there is
+                # nothing left to add to).
+                if trace.eval_run_id:
+                    eval_run_id = str(trace.eval_run_id)
                     eval_traces = self._eval_handler._eval_traces
                     if eval_run_id in eval_traces:
                         eval_traces[eval_run_id].append(trace)
@@ -1085,6 +1087,41 @@ class _ModuleMixin(_CallbackBase):
         )
         self._stamp(trace)
 
+        # Attach the run ids this trace starts under, from this callback's own
+        # state right now — not at finalize (on_module_end), where the
+        # optimization or eval may already have ended for a trace that
+        # outlives it. These are the same sources finalization read before
+        # this change; reading them here only moves *when* they're read, not
+        # what they read.
+        #
+        # Optimization reads the callback field first, then the shared
+        # contextvar. GEPA's start hook and both SDK compile wrappers
+        # both publish the reserved id on the installed callback before
+        # evaluator workers start. The contextvar supports a call with no
+        # active optimization field on this callback.
+        #
+        # Eval has no such gap — on_evaluate_start always sets the instance
+        # field in the same call that sets the contextvar — so it stays
+        # instance-field only, deliberately without the same fallback: adding
+        # one would read a DIFFERENT callback's eval off the same process-wide
+        # contextvar for a nested scoped client with no eval of its own.
+        #
+        # Both are callback-wide fields, not thread- or call-scoped: a
+        # concurrent unrelated call on another thread sharing this callback,
+        # or a nested scoped client's call inside another client's
+        # optimization metric, can still adopt a run it did not start via the
+        # contextvar fallback. Pre-existing behavior, unchanged by this
+        # attach-at-start change.
+        if self._active_optimization_run_id:
+            trace.optimization_run_id = self._active_optimization_run_id
+        else:
+            ctx_opt_run_id = context.get_current_optimization_run_id()
+            if ctx_opt_run_id:
+                trace.optimization_run_id = ctx_opt_run_id
+
+        if self._active_eval_run:
+            trace.eval_run_id = self._active_eval_run.eval_run_id
+
         # Capture signature info for the root module - this identifies the program
         signature = None
         if hasattr(instance, "signature"):
@@ -1494,6 +1531,8 @@ class _LMMixin(_CallbackBase):
         trace.signature_name = span.model_name or phase
         trace.status = span.status
         trace.optimization_run_id = run_id
+        if self._active_eval_run is not None:
+            trace.eval_run_id = self._active_eval_run.eval_run_id
         trace.tags["optimization_phase"] = phase
 
         # Single-span trace: roll the span's usage up onto the trace so the

{cmpnd-0.31.0 → cmpnd-0.32.0}/cmpnd/cli/commands/deployments.py

@@ -6,9 +6,11 @@ top-level `cmpnd ps`, `status`, `logs`, `inspect`, `run` shortcuts.
 
 from __future__ import annotations
 
+import sys
 from argparse import ArgumentParser, _SubParsersAction
 from typing import Any
 
+from ... import _http
 from .. import api_client, deprecation, pagination
 
 
@@ -64,7 +66,11 @@ def handle_run(client: api_client.ApiClient, args: Any) -> Any:
         body = json.loads(args.body)
     except json.JSONDecodeError as exc:
         raise api_client.CliError(f"Invalid JSON for run body: {exc}")
-    return client.post(f"/api/v1/deployments/{args.id}/execute", json=body)
+    response = client.post_response(f"/api/v1/deployments/{args.id}/execute", json=body)
+    output, run_id = _http.execute_response_output(response)
+    if run_id:
+        print(f"Deployment run: {run_id}", file=sys.stderr)
+    return output
 
 
 def handle_openapi(client: api_client.ApiClient, args: Any) -> None:

{cmpnd-0.31.0 → cmpnd-0.32.0}/cmpnd/cli/commands/top.py

@@ -863,6 +863,11 @@ def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
             raise api_client.CliError(f"--run JSON is invalid: {exc}")
         print(_c(f"executing {_short_id(deployment_id)}…", "dim"), file=sys.stderr)
         result = deployed(**inputs)
+        from ...execution import deployment_run_id
+
+        run_id = deployment_run_id(result)
+        if run_id:
+            print(f"Deployment run: {run_id}", file=sys.stderr)
         if args.json:
             # result is a dspy.Prediction; json.dumps would fall through to
             # str(result) and emit the repr. Coerce to a dict first.
@@ -990,20 +995,32 @@ def cmd_run(client: api_client.ApiClient, args: Any) -> None:
         raise api_client.CliError(f"Invalid JSON: {exc}")
 
     try:
-        result = client.post(f"/api/v1/deployments/{did}/execute", json=body)
+        response = client.post_response(f"/api/v1/deployments/{did}/execute", json=body)
     except api_client.CliError as e:
         # Map known 409/422/502 errors to friendlier hints. ApiClient already
         # formats the message; just append next-step hints when we recognize
         # the pattern.
         msg = str(e)
         if "409" in msg or "is parsing" in msg or "is pending" in msg:
-            raise api_client.CliError(f"{msg}\nWait for it: {_hint_status(did, follow=True)}")
+            raise api_client.CliError(
+                f"{msg}\nWait for it: {_hint_status(did, follow=True)}",
+                status_code=e.status_code,
+                deployment_run_id=e._cmpnd_deployment_run_id,
+            )
         if "422" in msg and "provider" in msg.lower():
             raise api_client.CliError(
-                f"{msg}\nNo provider key configured. Provider-key management is not yet available."
+                f"{msg}\nNo provider key configured. Provider-key management is not yet available.",
+                status_code=e.status_code,
+                deployment_run_id=e._cmpnd_deployment_run_id,
             )
         raise
 
+    from ... import _http
+
+    result, run_id = _http.execute_response_output(response)
+    if run_id:
+        print(f"Deployment run: {run_id}", file=sys.stderr)
+
     if args.json:
         print(json.dumps(result, indent=2, default=str))
         return

{cmpnd-0.31.0 → cmpnd-0.32.0}/cmpnd/execution.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 import inspect
 import keyword
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import httpx
 
@@ -25,6 +25,21 @@ if TYPE_CHECKING:
     from dspy.primitives.prediction import Prediction
 
 
+def deployment_run_id(result_or_error: Any) -> str | None:
+    """Return the server-owned run id from an execute prediction or exception.
+
+    The id lives outside the prediction's program output fields. Older servers
+    and failures before the server resolves the deployment supply no run id and
+    return ``None``.
+    """
+    return getattr(result_or_error, "_cmpnd_deployment_run_id", None)
+
+
+def _with_run_id(error: Exception, response: httpx.Response) -> Exception:
+    error._cmpnd_deployment_run_id = _http.response_deployment_run_id(response)  # pyright: ignore[reportAttributeAccessIssue]
+    return error
+
+
 class RetryableProviderError(HTTPStatusError):
     """A provider failure the platform identified as safe to retry.
 
@@ -256,7 +271,9 @@ def execute(deployment_id, timeout=30, metadata=None, tags=None, **inputs):
             keys (``lms``, ``deployment_id``, ...).
 
     Returns:
-        A dspy.Prediction with the program's output fields.
+        A dspy.Prediction with the program's output fields. Read the run id with
+        ``cmpnd.deployment_run_id(result)``. The same accessor accepts an
+        exception from a failed execute.
 
     Raises:
         TypeError: If metadata or tags is provided and is not a ``dict[str, str]``.
@@ -288,10 +305,10 @@ def execute(deployment_id, timeout=30, metadata=None, tags=None, **inputs):
         )
 
         if resp.status_code == 409:
-            raise RuntimeError(f"Deployment {dep_id} is not ready")
+            raise _with_run_id(RuntimeError(f"Deployment {dep_id} is not ready"), resp)
         if resp.status_code == 422:
             data = resp.json()
-            raise RuntimeError(data.get("error", "Execution failed"))
+            raise _with_run_id(RuntimeError(data.get("error", "Execution failed")), resp)
 
         if resp.status_code >= 400:
             # Same exception `raise_for_status()` would raise — the type is a contract:
@@ -310,17 +327,26 @@ def execute(deployment_id, timeout=30, metadata=None, tags=None, **inputs):
             provider_failure = _retryable_provider_failure(resp)
             if provider_failure is not None:
                 provider_status, attempts, retry_after = provider_failure
-                raise RetryableProviderError(
+                raise _with_run_id(
+                    RetryableProviderError(
+                        message,
+                        request=resp.request,
+                        response=resp,
+                        provider_status=provider_status,
+                        attempts=attempts,
+                        retry_after=retry_after,
+                    ),
+                    resp,
+                )
+            raise _with_run_id(
+                HTTPStatusError(
                     message,
                     request=resp.request,
                     response=resp,
-                    provider_status=provider_status,
-                    attempts=attempts,
-                    retry_after=retry_after,
-                )
-            raise HTTPStatusError(
-                message,
-                request=resp.request,
-                response=resp,
+                ),
+                resp,
             )
-        return Prediction(**resp.json())
+        output, run_id = _http.execute_response_output(resp)
+        prediction = Prediction(**output)
+        setattr(prediction, "_cmpnd_deployment_run_id", run_id)
+        return prediction

{cmpnd-0.31.0 → cmpnd-0.32.0}/cmpnd/models.py

@@ -949,7 +949,7 @@ class TraceBuilder:
         }
 
     def to_start_dict(self) -> dict[str, Any]:
-        """Lightweight payload for trace start — identity + signature only."""
+        """Lightweight payload for trace identity, signature and run attribution."""
         return {
             "start_time": self.start_time.isoformat() if self.start_time else None,
             "program_name": self.program_name,
@@ -963,8 +963,14 @@ class TraceBuilder:
             "signature_summary": self.signature_summary,
             "component_signatures": _safe_serialize(self.component_signatures),
             "root_span_type": self.root_span_type,
+            "compiled_from_run_id": self.compiled_from_run_id,
             "project": self.project_tags[0] if self.project_tags else None,
             "project_tags": self.project_tags if self.project_tags else [],
+            # Known at start (the callback attaches them in _create_trace), so
+            # the start row carries them from the first send instead of the
+            # finalize row re-attributing them later.
+            "eval_run_id": str(self.eval_run_id) if self.eval_run_id else None,
+            "optimization_run_id": (str(self.optimization_run_id) if self.optimization_run_id else None),
         }
 
     def to_finalize_dict(self) -> dict[str, Any]:

{cmpnd-0.31.0 → cmpnd-0.32.0}/cmpnd/optimizers/gepa.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Any
 
-from .. import identity
+from .. import _gepa_patch, identity
 from . import gepa_callback, tracker
 
 if TYPE_CHECKING:
@@ -199,10 +199,16 @@ class TrackedGEPA:
         # Inject callback into GEPA's gepa_kwargs
         existing_callbacks = self._gepa.gepa_kwargs.get("callbacks") or []
         self._gepa.gepa_kwargs["callbacks"] = existing_callbacks + [gcb]
+        restore_attribution = None
 
         try:
+            restore_attribution = gcb.start_trace_attribution()
             # Run optimization (trainset/valset are keyword-only in GEPA)
-            result = self._gepa.compile(student, trainset=trainset, teacher=teacher, valset=valset)
+            compile_token = _gepa_patch._tracked_compile_optimizer.set(self._gepa)
+            try:
+                result = self._gepa.compile(student, trainset=trainset, teacher=teacher, valset=valset)
+            finally:
+                _gepa_patch._tracked_compile_optimizer.reset(compile_token)
 
             # Capture the compiled program state
             self._tracker.capture_compiled_program(result)
@@ -235,11 +241,8 @@ class TrackedGEPA:
             raise
 
         finally:
-            # Clear optimization context (in case on_optimization_end didn't fire)
-            from .. import context
-
-            context.set_current_optimization_run_id(None)
-            gcb.clear_trace_association_state()
+            if restore_attribution is not None:
+                restore_attribution()
             # Remove our callback from gepa_kwargs
             cbs = self._gepa.gepa_kwargs.get("callbacks", [])
             self._gepa.gepa_kwargs["callbacks"] = [cb for cb in cbs if cb is not gcb]

{cmpnd-0.31.0 → cmpnd-0.32.0}/cmpnd/optimizers/gepa_callback.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 
 import logging
 import time
+from collections.abc import Callable
 from typing import Any
 from uuid import UUID
 
@@ -171,6 +172,26 @@ class CmpndGEPACallback:
         if cmpnd_cb:
             cmpnd_cb._clear_optimization_trace_state()
 
+    def start_trace_attribution(self) -> Callable[[], None]:
+        """Reserve and publish this run before compile, then return its cleanup."""
+        cmpnd_cb = self._get_cmpnd_callback()
+        prior_callback_run_id = cmpnd_cb._active_optimization_run_id if cmpnd_cb is not None else None
+        prior_context_run_id = context.get_current_optimization_run_id()
+        self._tracker.start()
+        context.set_current_optimization_run_id(self._tracker.optimization_run_id)
+        if cmpnd_cb is not None:
+            # Evaluator threads need not inherit contextvars, and older GEPA
+            # versions notify their start hook after the seed evaluation.
+            cmpnd_cb._active_optimization_run_id = self._tracker.optimization_run_id
+
+        def restore() -> None:
+            if cmpnd_cb is not None:
+                cmpnd_cb._clear_optimization_trace_state()
+                cmpnd_cb._active_optimization_run_id = prior_callback_run_id
+            context.set_current_optimization_run_id(prior_context_run_id)
+
+        return restore
+
     def on_optimization_start(self, event: dict[str, Any]) -> None:
         """Handle optimization start: set context and start tracker."""
         try:

{cmpnd-0.31.0 → cmpnd-0.32.0}/docs/sdk-instrumentation.md

@@ -345,6 +345,38 @@ The create POST is the one that mints something, so it carries the [minting-POST
 
 The poll loop has no retry budget of its own: the caller's `timeout` is the only bound, since giving up early on a deployment that is still progressing is the failure it exists to avoid. Running that budget out is still a `TimeoutError`, now naming what it rode through. A `4xx` and a `status: "failed"` are answers, not blips, and still raise (`RuntimeError` / `DeployFailed`).
 
+### Execute returns a deployment run id
+
+Serve mints a deployment run id before it sends an execute to the worker. A
+successful JSON response contains `deployment_run_id` and `output`. A failed
+execution keeps its error body and adds the run id. Errors before serve resolves
+the deployment have no id.
+
+`cmpnd.execute()` and a callable `DeployedProgram` return the program's output
+as a `dspy.Prediction`. `cmpnd.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 an execute
+exception. Trace delivery can finish after the execute response arrives.
+
+```python
+try:
+    result = deployed(question="What changed?")
+    run_id = cmpnd.deployment_run_id(result)
+except Exception as error:
+    run_id = cmpnd.deployment_run_id(error)
+    raise
+```
+
+The SDK reads the run id and program output from the response body.
+`cmpnd run`, `cmpnd deployments run` and `cmpnd deploy --run` print the run id
+on stderr and program output on stdout. `--json` keeps stdout as the program's
+JSON output. A CLI execution
+error carries the id in its message and exception metadata.
+
+SDK and CLI version 0.32.0 support this envelope. The API does not yet guarantee
+response compatibility across client versions. Upgrade `cmpnd` to the latest
+version when a client has trouble with execute responses.
+
 ### A programmatic deploy carries the types it names as generated source
 
 `cmpnd.deploy(module)` receives a live object rather than an authored file. Its
@@ -510,6 +542,47 @@ Two producers put a `span` item and its trace's `trace` item in the same flush.
 
 `trace.streaming` (set only for RLM) is a separate axis: it still governs whether individual spans stream (`export_span`) and whether finalize goes through `/finalize` (streaming) vs a bundled `export_trace` (batch). CMP-257 generalized only the start emission, not the whole streaming model.
 
+`_create_trace` also attaches `optimization_run_id` and `eval_run_id` at trace start, so the start row carries both from its first send. `on_module_end` never re-reads either source at finalize: a trace's module call can outlive the optimization or eval it started under, and re-reading at finalize would send a later update that clears the ids the start row already carried. A finalizing trace always keeps the ids it started with.
+
+Optimization reads this callback's `_active_optimization_run_id` field first,
+then the shared `cmpnd.context` contextvar. Both SDK compile wrappers publish
+the reserved id on the installed callback before evaluator workers start,
+including when native GEPA fires its start hook after the seed evaluation or
+has no callback support. The wrappers restore the previous
+callback and context ids when the search returns or raises. Eval reads only
+the callback field. `on_evaluate_start` sets it before the evaluator workers
+start, so eval needs no contextvar fallback.
+
+The callback fields let evaluator threads read the active run ids. A plain
+thread need not inherit Python contextvars, and DSPy versions and wrappers
+differ in how they carry context to workers. The fields also let an unrelated
+concurrent call sharing the callback adopt the active run. A nested scoped
+client can adopt another client's optimization through the contextvar
+fallback. Run attribution therefore requires calls that belong to the run
+owning this callback. Callback-wide state does not prove ownership across
+overlapping runs or scoped clients.
+
+The callback has two automatic trace constructors. `_create_trace` snapshots
+the root module's run ids before it exports a start. `EvalHandler` obtains the
+eval id synchronously before evaluator workers call the program.
+`OptimizationTracker.start()` obtains the optimization id before rollouts.
+Both SDK compile wrappers set that id on the installed callback and in the
+contextvar before compile. GEPA's start callback also sets it when the event
+arrives. The tracker reserves one id even when both paths call `start()`.
+`TrackedGEPA` also claims its native optimizer while calling compile. The
+automatic class patch then runs that instance's search without reserving a
+second id. The claim ends when compile returns or raises. An instance override
+still runs, and a distinct optimizer nested inside it gets its own run.
+The start payload also carries the compiled program's `compiled_from_run_id`.
+
+Nested modules add spans to their root trace. `asyncify`, native `acall` and
+`streamify` dispatch through the module hooks. RLM exports its start before it
+streams spans and keeps those run ids through finalize. A standalone GEPA LM
+trace is constructed when the LM call ends and exports as one complete trace.
+Its first payload carries the optimization id, plus the active eval id for a
+metric call. A reflection call outside evaluation has no eval id. Manual
+decorators and `start_span` create spans rather than another automatic trace.
+
 Two things keep the extra start cheap and correct:
 
 - **Upsert, not duplicate.** The batch finalize (`export_trace`) and the start write the same row: serve's `traceUpsertSQL` keys `ON CONFLICT (org_id, trace_id, start_time)`, and the SDK's `start_time` is immutable across a trace's life, so the batch overwrites the `in_progress` row with the final status. A trace that never finalizes (crash / cancel) correctly stays `in_progress`.

{cmpnd-0.31.0 → cmpnd-0.32.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.31.0"
+version = "0.32.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.10"