cmpnd 0.7.0__tar.gz → 0.7.2__tar.gz

{cmpnd-0.7.0 → cmpnd-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmpnd
-Version: 0.7.0
+Version: 0.7.2
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -27,6 +27,7 @@ Requires-Dist: basedpyright>=1.39; extra == 'dev'
 Requires-Dist: boto3>=1.34; extra == 'dev'
 Requires-Dist: hypothesis>=6.100; extra == 'dev'
 Requires-Dist: jsonschema>=4.0; extra == 'dev'
+Requires-Dist: numpy>=1.26; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-rerunfailures>=14.0; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.0; extra == 'dev'

{cmpnd-0.7.0 → cmpnd-0.7.2}/cmpnd/_gepa_patch.py

@@ -64,7 +64,7 @@ def patch_gepa() -> None:
         # This ensures each optimization gets its own run_id, even when
         # the same GEPA instance is reused (e.g., optimizing an already-optimized program).
         trk = tracker.OptimizationTracker(
-            optimizer_type="GEPA",
+            optimizer_type="gepa",
             program_name="",
         )
         callback = gepa_callback.CmpndGEPACallback(trk, defer_finalize=True)
@@ -157,7 +157,14 @@ def patch_gepa() -> None:
 
             return result
 
-        except Exception as e:
+        # `BaseException`, because the invariant does not get to have an exception: a
+        # run that ends by ANY route must transition the row start() sent, or the
+        # program page shows a perpetual in-progress optimization. A backend that
+        # rejected a model request raises a failure that deliberately does NOT derive
+        # from `Exception` — that is the only way past gepa's and dspy's own blanket
+        # `except Exception` clauses — so narrowing this one reopens exactly the bug
+        # this block exists for. Re-raised either way, so widening swallows nothing.
+        except BaseException as e:
             if callback is not None:  # pyright: ignore[reportUnnecessaryComparison]
                 # Flush a terminal 'failed', not just in-memory state — else the
                 # running row start() sent lingers forever.

{cmpnd-0.7.0 → cmpnd-0.7.2}/cmpnd/exporter_http.py

@@ -55,6 +55,28 @@ def _send_json(client: httpx.Client, method: str, path: str, payload: Any) -> ht
     return client.request(method, path, content=body, headers=_GZIP_HEADERS)
 
 
+# Gateway/overload statuses a data POST should retry rather than count as a hard
+# export error: the backend (or the proxy in front of it) is transiently busy,
+# not rejecting the payload. A retry is safe because serve dedups on ingest —
+# traces by (org_id, trace_id, start_time) and spans by the spans_dedup index —
+# so a re-POST of a request that actually landed can't double-insert.
+_RETRYABLE_STATUS = frozenset({502, 503, 504})
+
+
+def _is_retryable_export_error(exc: BaseException) -> bool:
+    """Whether a failed data send is a transient delivery blip worth retrying.
+
+    True for gateway/overload statuses (502/503/504) and httpx transport/timeout
+    errors (connect/read/pool timeouts, connection refused/reset). False for
+    everything else — 4xx (client error, a retry won't help), 429 (backpressure,
+    the caller records it as *dropped* not errored), and 500 (the platform's to
+    answer for, mirroring the is_external_outage boundary). Non-httpx exceptions
+    are not retried (a bug in our own build path shouldn't loop)."""
+    if isinstance(exc, httpx.HTTPStatusError):
+        return exc.response.status_code in _RETRYABLE_STATUS
+    return isinstance(exc, (httpx.TimeoutException, httpx.TransportError))
+
+
 @dataclass
 class ExportItem:
     """Item in the export queue."""
@@ -115,6 +137,14 @@ class BatchExporter:
         self._start_post_attempts = 3
         self._start_post_backoff = 0.5
 
+        # Bounded retry for the best-effort data POSTs (traces/spans/stats/…):
+        # a transient gateway/overload or transport blip retries with backoff
+        # instead of immediately counting a hard export error. Idempotent on the
+        # serve side (see _is_retryable_export_error). Instance attrs so tests
+        # can zero the backoff. Distinct from the start-post budget above.
+        self._data_post_attempts = 3
+        self._data_post_backoff = 0.5
+
         # Guard against registering multiple exit handlers on repeated start()
         self._atexit_registered = False
 
@@ -440,6 +470,34 @@ class BatchExporter:
             raise RuntimeError("BackgroundExporter has no HTTP client (not started or already shut down)")
         return self._client
 
+    def _send_json_retrying(self, client: httpx.Client, method: str, path: str, payload: Any) -> httpx.Response:
+        """`_send_json` + `raise_for_status`, retrying transient delivery blips.
+
+        Retries `_data_post_attempts` times with exponential backoff on a
+        retryable failure (502/503/504 or a transport/timeout error — see
+        `_is_retryable_export_error`), then re-raises. A non-retryable failure
+        (4xx, 429, 500, or a 2xx that somehow raised) propagates on the first
+        attempt, so the caller's existing except blocks still record it (429 →
+        dropped, everything else → error) exactly as before — the only change
+        is that a transient blip now gets a few tries before it counts."""
+        last_exc: Exception | None = None
+        for attempt in range(self._data_post_attempts):
+            try:
+                response = _send_json(client, method, path, payload)
+                response.raise_for_status()
+                return response
+            except Exception as e:
+                last_exc = e
+                if _is_retryable_export_error(e) and attempt + 1 < self._data_post_attempts:
+                    logger.debug(
+                        "cmpnd: retrying %s %s after transient error (attempt %d): %s", method, path, attempt + 1, e
+                    )
+                    time.sleep(self._data_post_backoff * (2**attempt))
+                    continue
+                raise
+        assert last_exc is not None  # unreachable: the loop either returns or raises
+        raise last_exc
+
     def _flush_batch(self, batch: list[ExportItem]) -> None:
         """Send a batch of items to the backend with parallel dispatch."""
         if not batch or not self._client:
@@ -600,9 +658,9 @@ class BatchExporter:
         total_spans = sum(len(t.get("spans", [])) for t in traces_to_send)
         try:
             if len(traces_to_send) == 1:
-                response = _send_json(client, "POST", "/api/v1/traces", traces_to_send[0])
+                response = self._send_json_retrying(client, "POST", "/api/v1/traces", traces_to_send[0])
             else:
-                response = _send_json(client, "POST", "/api/v1/traces/batch", traces_to_send)
+                response = self._send_json_retrying(client, "POST", "/api/v1/traces/batch", traces_to_send)
             response.raise_for_status()
             with self._stats_lock:
                 self._exported_count += len(traces_to_send) + total_spans
@@ -627,7 +685,7 @@ class BatchExporter:
         client = self._require_client()
         for trace_id, start_dict in trace_starts:
             try:
-                response = _send_json(client, "POST", f"/api/v1/traces/{trace_id}/start", start_dict)
+                response = self._send_json_retrying(client, "POST", f"/api/v1/traces/{trace_id}/start", start_dict)
                 response.raise_for_status()
                 with self._stats_lock:
                     self._exported_count += 1
@@ -641,7 +699,9 @@ class BatchExporter:
         client = self._require_client()
         for trace_id, span_list in spans_by_trace.items():
             try:
-                response = _send_json(client, "POST", f"/api/v1/traces/{trace_id}/spans", {"spans": span_list})
+                response = self._send_json_retrying(
+                    client, "POST", f"/api/v1/traces/{trace_id}/spans", {"spans": span_list}
+                )
                 response.raise_for_status()
                 with self._stats_lock:
                     self._exported_count += len(span_list)
@@ -655,7 +715,9 @@ class BatchExporter:
         client = self._require_client()
         for trace_id, finalize_dict in trace_finalizes:
             try:
-                response = _send_json(client, "POST", f"/api/v1/traces/{trace_id}/finalize", finalize_dict)
+                response = self._send_json_retrying(
+                    client, "POST", f"/api/v1/traces/{trace_id}/finalize", finalize_dict
+                )
                 response.raise_for_status()
                 with self._stats_lock:
                     self._exported_count += 1
@@ -668,7 +730,7 @@ class BatchExporter:
     def _send_stats(self, stats_to_send: list[dict[str, Any]]) -> None:
         client = self._require_client()
         try:
-            response = _send_json(client, "POST", "/api/v1/traces/stats", stats_to_send)
+            response = self._send_json_retrying(client, "POST", "/api/v1/traces/stats", stats_to_send)
             response.raise_for_status()
             with self._stats_lock:
                 self._exported_count += len(stats_to_send)
@@ -686,7 +748,7 @@ class BatchExporter:
             eval_run_id = str(eval_run_dict.get("eval_run_id"))
             num_examples = len(eval_run_dict.get("examples", []))
             try:
-                response = _send_json(client, "PATCH", f"/api/v1/evals/{eval_run_id}", eval_run_dict)
+                response = self._send_json_retrying(client, "PATCH", f"/api/v1/evals/{eval_run_id}", eval_run_dict)
                 response.raise_for_status()
                 with self._stats_lock:
                     self._exported_count += 1 + num_examples
@@ -703,7 +765,7 @@ class BatchExporter:
             num_iterations = len(opt_run_dict.get("iterations", []))
             num_candidates = len(opt_run_dict.get("candidates", []))
             try:
-                response = _send_json(client, "POST", "/api/v1/optimizations", opt_run_dict)
+                response = self._send_json_retrying(client, "POST", "/api/v1/optimizations", opt_run_dict)
                 response.raise_for_status()
                 with self._stats_lock:
                     self._exported_count += 1
@@ -722,7 +784,9 @@ class BatchExporter:
         client = self._require_client()
         for opt_run_id, progress_dict, trk in optimization_progress_to_send:
             try:
-                response = _send_json(client, "PATCH", f"/api/v1/optimizations/{opt_run_id}/progress", progress_dict)
+                response = self._send_json_retrying(
+                    client, "PATCH", f"/api/v1/optimizations/{opt_run_id}/progress", progress_dict
+                )
                 response.raise_for_status()
                 # Delivery-acknowledged high-water: only advance past these
                 # iteration_points now that the PATCH succeeded (2xx, no
@@ -745,7 +809,7 @@ class BatchExporter:
             num_iterations = len(opt_run_dict.get("iterations", []))
             num_candidates = len(opt_run_dict.get("candidates", []))
             try:
-                response = _send_json(client, "PUT", f"/api/v1/optimizations/{opt_run_id}", opt_run_dict)
+                response = self._send_json_retrying(client, "PUT", f"/api/v1/optimizations/{opt_run_id}", opt_run_dict)
                 response.raise_for_status()
                 with self._stats_lock:
                     self._exported_count += 1

{cmpnd-0.7.0 → cmpnd-0.7.2}/cmpnd/optimizers/gepa.py

@@ -152,7 +152,7 @@ class TrackedGEPA:
 
         # Initialize optimization tracking
         self._tracker = tracker.OptimizationTracker(
-            optimizer_type="GEPA",
+            optimizer_type="gepa",
             program_name=student.__class__.__name__,
             config=config,
             model_name=model_name,
@@ -218,7 +218,11 @@ class TrackedGEPA:
 
             return result
 
-        except Exception as e:
+        # `BaseException` for the reason `_gepa_patch._patched_compile` documents: the
+        # row must transition however the run ends, and a rejected model request
+        # reaches here as something that is not an `Exception`, by design. Re-raised
+        # either way.
+        except BaseException as e:
             if self._tracker:
                 # Flush a terminal 'failed', not just in-memory state — else the
                 # running row start() sent lingers forever.

{cmpnd-0.7.0 → cmpnd-0.7.2}/cmpnd/optimizers/gepa_callback.py

@@ -5,7 +5,7 @@ monkey-patching or wrapper classes. Replaces the monkey-patched
 InstrumentedDspyAdapter approach used by TrackedGEPA.
 
 Usage:
-    tracker = OptimizationTracker(optimizer_type="GEPA", ...)
+    tracker = OptimizationTracker(optimizer_type="gepa", ...)
     callback = CmpndGEPACallback(tracker)
     gepa = dspy.GEPA(gepa_kwargs={"callbacks": [callback]})
 """

{cmpnd-0.7.0 → cmpnd-0.7.2}/cmpnd/optimizers/tracker.py

@@ -199,7 +199,7 @@ class OptimizationTracker:
 
     Usage:
         tracker = OptimizationTracker(
-            optimizer_type="GEPA",
+            optimizer_type="gepa",
             program_name="MyProgram",
             config={"auto": "light", "seed": 42}
         )
@@ -634,14 +634,21 @@ class OptimizationTracker:
         except Exception as e:
             logger.warning(f"Failed to capture compiled program state: {e}")
 
-    def set_error(self, exception: Exception) -> None:
-        """Mark the optimization run as failed (in-memory only)."""
+    def set_error(self, exception: BaseException) -> None:
+        """Mark the optimization run as failed (in-memory only).
+
+        ``BaseException`` and not ``Exception``: a backend that rejected a model request
+        reports it as a failure that deliberately does not derive from ``Exception``,
+        since that is the only thing gepa's and dspy's blanket ``except Exception``
+        clauses do not swallow. A run that ended is a run that has to be recorded as
+        ended, whichever base class carried the reason.
+        """
         self.status = "failed"
         self.error_message = str(exception)
         self.end_time = datetime.now(timezone.utc)
         logger.error(f"Optimization failed: {exception}")
 
-    def finalize_error(self, exception: Exception) -> None:
+    def finalize_error(self, exception: BaseException) -> None:
         """Mark the run failed AND flush the terminal 'failed' to the backend.
 
         The success path is finalize(); on an optimizer exception the run must

{cmpnd-0.7.0 → cmpnd-0.7.2}/docs/sdk-instrumentation.md

@@ -154,6 +154,10 @@ Override any of these by passing kwargs to `cmpnd.configure(...)`.
 - `_flush_batch` at `exporter_http.py:443` sorts items by type (`trace`, `span`, `trace_start`, `trace_finalize`, `trace_stats`, `eval_run`, `optimization_run`, various optimization progress records), buffers loose spans keyed by `trace_id` so they can be attached to their parent trace when it arrives, and submits each type's `_send_*` call to the thread pool in parallel.
 - `shutdown()` at `exporter_http.py:163` sets the shutdown event, joins the worker thread, drains any leftover queue items, then shuts down the executor and HTTP client. It is safe to call multiple times.
 
+### Delivery errors, dropping, and transient retry
+
+Each `_send_*` method routes a failed delivery to one of two counters: a `429` (server buffer full) increments `_dropped_count` and is *not* retried (it's backpressure — the caller intentionally sheds the load), while any other non-2xx or transport failure increments `_error_count`. The data POSTs go through `_send_json_retrying` (`exporter_http.py`), which retries a **transient** failure — a `502`/`503`/`504` gateway/overload status, or an httpx transport/timeout error — up to `_data_post_attempts` (3) times with exponential backoff before it counts, so a momentary blip against a busy backend doesn't register as a hard error. It is *not* retried on `4xx` (client error), `429` (dropped, above), or `500` (the platform's to answer for — the same boundary as the stress harness's `is_external_outage`). Retrying is safe because serve dedups ingest — traces on `(org_id, trace_id, start_time)`, spans on the `spans_dedup` index — so a re-POST of a request that actually landed can't double-insert. The blocking run-*start* POSTs keep their own separate retry budget (`_start_post_attempts`), since they must return a server-assigned id synchronously.
+
 ### Loose spans vs bundled traces
 
 A span can arrive at `_flush_batch` before its parent trace has been exported — this happens whenever the exporter ticks in the middle of a DSPy call. The exporter holds those loose spans in `self._pending_spans` (`exporter_http.py:122`) keyed by `trace_id`, and when the trace finally arrives it attaches the buffered spans before shipping. Spans for which the trace never arrives get flushed as a bare spans batch via `/api/v1/traces/:id/spans` — see `_send_spans` at `exporter_http.py:637`.

{cmpnd-0.7.0 → cmpnd-0.7.2}/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.7.0"
+version = "0.7.2"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -58,6 +58,10 @@ dev = [
     # litellm's bedrock/ provider imports boto3 in-process, so the client-side
     # Bedrock stress tests (committee twins) need it in the test env.
     "boto3>=1.34",
+    # test_reflector_smoke.py builds numpy fixtures. dspy <=3.2.x required numpy
+    # unconditionally so it rode in transitively; dspy 3.3.0 moved numpy behind a
+    # `numpy` extra, so declare it directly as the test dependency it always was.
+    "numpy>=1.26",
 ]
 # Deps for `deploy/deploy/stub/`, the local FastAPI server that emulates
 # the AWS deploy stack. The stub itself ships in the cmpnd-deploy
@@ -92,6 +96,39 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["cmpnd"]
 
+[tool.pytest.ini_options]
+# Deliberately minimal: `markers` and `--strict-markers`, nothing else. Setting
+# `testpaths` or a broader `addopts` here would change how every existing
+# invocation resolves (CI lanes, `uv run pytest tests/ -k "not e2e"`, a bare
+# `pytest` from a subdirectory), and this file's job is only to make the marker
+# vocabulary explicit.
+#
+# --strict-markers turns a typo'd marker into an error instead of a silent
+# no-op. That matters most for `forall_workers`: it SELECTS the merge-queue's
+# wasm lane, so a misspelling there would quietly select nothing and report a
+# green lane that ran zero tests. `asyncio` and `flaky` are registered by
+# pytest-asyncio / pytest-rerunfailures, so they are not listed here.
+addopts = "--strict-markers"
+markers = [
+    # Tests that must hold for EVERY worker backend — i.e. that provision,
+    # execute or optimize through a data plane, and so can distinguish the
+    # Lambda plane from the wasm plane from the on-prem worker. This is the
+    # selector for the per-plane stress lanes: the set worth running against a
+    # second worker is exactly the set claimed to hold for all of them.
+    #
+    # A stress test that deploys or executes gets this marker. Its absence on
+    # such a test is a bug; its PRESENCE on a test no worker can affect (one
+    # that only exercises client-side tracing, or serve's own health) is worse,
+    # because it costs a second real-provider run to prove nothing.
+    # See docs/plans/2026-07-29-wasm-stress-lane.md.
+    "forall_workers: must hold for every worker backend (reaches a data plane)",
+    # Pre-existing vocabulary, registered here because --strict-markers now
+    # requires it — not introduced by this block.
+    "parity: CLI dual-front-end parity (argparse vs. interactive shell)",
+    "e2e: needs a live platform; excluded from the fast lane via -k 'not e2e'",
+    "integration: crosses a component boundary (SDK ↔ serve ↔ worker)",
+]
+
 [tool.ruff]
 line-length = 120
 target-version = "py310"