cmpnd 0.7.2__tar.gz → 0.8.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmpnd
-Version: 0.7.2
+Version: 0.8.1
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -28,11 +28,14 @@ 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: pillow>=10.0; 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'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: images
+Requires-Dist: pillow>=10.0; extra == 'images'
 Provides-Extra: stub
 Requires-Dist: cmpnd-deploy; (python_version >= '3.11') and extra == 'stub'
 Requires-Dist: fastapi>=0.110; extra == 'stub'

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

@@ -62,21 +62,68 @@ def _send_json(client: httpx.Client, method: str, path: str, payload: Any) -> ht
 # so a re-POST of a request that actually landed can't double-insert.
 _RETRYABLE_STATUS = frozenset({502, 503, 504})
 
+# Backpressure, not unavailability: the server's buffer is full and it wants the
+# record dropped, so the caller counts it as *dropped* and we never retry it —
+# not even if the body carried a retryable flag. Named because that exemption is
+# the one thing the body-flag read below must not be able to override.
+_DROP_STATUS = 429
+
+
+def _server_says_retryable(response: httpx.Response) -> bool:
+    """Whether the server explicitly marked this error response retryable.
+
+    The `"retryable": true` error-body field is the server's stable machine
+    signal for "this failed transiently and did not commit — send it again". It
+    is what keeps this side off a hard-coded status list: the server can start
+    signalling a new transient condition without an SDK release. A body that
+    isn't JSON, isn't an object, or lacks the field reads as not-retryable.
+    """
+    try:
+        body = response.json()
+    except Exception:
+        return False
+    return isinstance(body, dict) and body.get("retryable") is True
+
 
 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)."""
+    True for gateway/overload statuses (502/503/504), a response the server
+    explicitly flagged retryable (see `_server_says_retryable`), 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
+    no body flag overrides that), and an unflagged 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
+        status = exc.response.status_code
+        if status == _DROP_STATUS:
+            return False
+        return status in _RETRYABLE_STATUS or _server_says_retryable(exc.response)
     return isinstance(exc, (httpx.TimeoutException, httpx.TransportError))
 
 
+def _retry_after_seconds(exc: BaseException) -> float | None:
+    """The server's own backoff hint for this failure, in seconds, or None.
+
+    Only the delta-seconds form of `Retry-After` is honored — that is what the
+    server emits alongside a retryable error. A missing header, the HTTP-date
+    form, or an unparseable value returns None so the caller falls back to its
+    own exponential backoff rather than trusting a number it can't read. A
+    transport error has no response at all and so has no hint.
+    """
+    if not isinstance(exc, httpx.HTTPStatusError):
+        return None
+    raw = exc.response.headers.get("retry-after")
+    if not raw:
+        return None
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return None
+
+
 @dataclass
 class ExportItem:
     """Item in the export queue."""
@@ -144,6 +191,12 @@ class BatchExporter:
         # can zero the backoff. Distinct from the start-post budget above.
         self._data_post_attempts = 3
         self._data_post_backoff = 0.5
+        # Ceiling on a single inter-attempt wait, including one the server asked
+        # for via Retry-After. The exporter thread is the only thing draining the
+        # queue, so an over-long wait doesn't just delay this send — it stalls
+        # every queued record behind it and risks the queue filling. Honoring the
+        # server's hint is worth it; honoring an unbounded one is not.
+        self._data_post_max_delay = 5.0
 
         # Guard against registering multiple exit handlers on repeated start()
         self._atexit_registered = False
@@ -473,13 +526,16 @@ class BatchExporter:
     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."""
+        Retries `_data_post_attempts` times on a retryable failure — a
+        gateway/overload status, a response the server flagged `retryable`, or a
+        transport/timeout error (see `_is_retryable_export_error`) — then
+        re-raises. The wait between attempts is the server's `Retry-After` hint
+        when it sent one, else exponential backoff, capped either way by
+        `_data_post_max_delay`. A non-retryable failure (4xx, 429, an unflagged
+        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:
@@ -489,10 +545,19 @@ class BatchExporter:
             except Exception as e:
                 last_exc = e
                 if _is_retryable_export_error(e) and attempt + 1 < self._data_post_attempts:
+                    delay = _retry_after_seconds(e)
+                    if delay is None:
+                        delay = self._data_post_backoff * (2**attempt)
+                    delay = min(delay, self._data_post_max_delay)
                     logger.debug(
-                        "cmpnd: retrying %s %s after transient error (attempt %d): %s", method, path, attempt + 1, e
+                        "cmpnd: retrying %s %s after transient error in %.2fs (attempt %d): %s",
+                        method,
+                        path,
+                        delay,
+                        attempt + 1,
+                        e,
                     )
-                    time.sleep(self._data_post_backoff * (2**attempt))
+                    time.sleep(delay)
                     continue
                 raise
         assert last_exc is not None  # unreachable: the loop either returns or raises

cmpnd-0.8.1/cmpnd/imaging.py

@@ -0,0 +1,162 @@
+"""Optional image thumbnailing for oversized image inputs/outputs.
+
+When a captured field is an oversized inline image data URI, the truncator would
+otherwise discard every pixel and keep a 1000-char base64 fragment. If Pillow is
+installed (`cmpnd[images]`), `image_thumbnail` decodes that data URI, downscales
+it, and returns a small complete JPEG data URI that fits well under the field
+size cap — so the trace page can show what the image was instead of an opaque
+fragment.
+
+Everything here is best-effort and must never raise into the capture path:
+Pillow missing, an unparseable URI, a decode failure, or an implausibly large
+source all return ``None``, and the caller falls back to plain-string
+truncation. Only raster formats are handled; SVG and other non-raster or vector
+mimes are refused (an SVG is markup, not pixels to resample).
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import io
+import re
+
+_THUMBNAIL_JPEG_QUALITY = 70
+
+# The thumbnail is sized to a BYTE budget, not a fixed pixel dimension: it should
+# be as large as fits the field's own size budget (the caller passes its max_size)
+# so the preview is as detailed as the truncation system already allows. Starting
+# from the source's NATIVE size, it encodes and — if that overflows the budget —
+# halves the longest edge and re-encodes, until the data URI fits. So an image
+# already small enough is returned at full resolution with no resize, and a large
+# one is scaled down just enough to fit. No pixel dimension is hard-coded anywhere.
+
+# Bytes reserved for the envelope around _preview ({"_truncated":…,"_type":"image",
+# "_size_chars":<N>,"_preview":"<uri>"}) so the whole envelope, not just the URI,
+# serializes within the budget. Generous — covers the keys, a large _size_chars,
+# and JSON punctuation.
+_ENVELOPE_HEADROOM = 160
+
+# Fallback budget when a caller doesn't pass one. Mirrors models._MAX_FIELD_JSON_SIZE
+# (not imported: models imports this module, so importing it back would cycle);
+# models.truncate_field passes its actual max_size, which is the real bound.
+_DEFAULT_FIELD_BUDGET = 65536
+
+# Refuse sources larger than this before decoding: a bound on the synchronous
+# capture-path work, and a first guard against decompression bombs (the pixel
+# ceiling below is the second).
+_MAX_DECODE_BYTES = 8 * 1024 * 1024
+
+# A conservative pixel ceiling so a small compressed payload can't expand into a
+# huge bitmap on decode (decompression bomb). Enforced strictly against the
+# declared image size read from the header BEFORE any pixel decode, so an
+# oversized image is rejected outright rather than merely warned about. We never
+# read or write Pillow's process-global Image.MAX_IMAGE_PIXELS, so this ceiling
+# holds regardless of the host's Pillow configuration and never perturbs it.
+_MAX_IMAGE_PIXELS = 24_000_000
+
+# Raster mimes we thumbnail. SVG and other vector/non-raster mimes are excluded
+# (an SVG is markup, not pixels to resample).
+_RASTER_MIMES = ("png", "jpeg", "jpg", "gif", "webp", "bmp")
+
+# Finds the first embedded raster image data URI and captures its base64 body
+# (up to the first non-base64 char — e.g. the closing quote in JSON). The URI may
+# be bare, or nested inside a wrapper: a captured field is rarely a bare data URI.
+# DSPy serializes a dspy.Image inside custom-type markers as a JSON image_url
+# block — `<<CUSTOM-TYPE-START-IDENTIFIER>>[{"type":"image_url","image_url":
+# {"url":"data:image/…"}}]<<CUSTOM-TYPE-END-IDENTIFIER>>` — so the data URI sits
+# inside an `image_url.url`. Searching handles that, a plain JSON blob, and the
+# bare case alike.
+_DATA_IMAGE_RE = re.compile(r"data:image/(?:" + "|".join(_RASTER_MIMES) + r");base64,([A-Za-z0-9+/]+=*)")
+
+
+def _extract_image_bytes(value: str) -> bytes | None:
+    """Return the decoded bytes of the first embedded raster-image data URI in
+    ``value``, or None if there is none or it exceeds the size bound.
+    """
+    match = _DATA_IMAGE_RE.search(value)
+    if match is None:
+        return None
+    b64 = match.group(1)
+    # Cheap size gate on the encoded text before decoding (base64 is ~4/3 the
+    # raw size); the decoded check below is the exact one.
+    if len(b64) > (_MAX_DECODE_BYTES // 3) * 4 + 4:
+        return None
+    try:
+        raw = base64.b64decode(b64, validate=True)
+    except (binascii.Error, ValueError):
+        return None
+    if len(raw) > _MAX_DECODE_BYTES:
+        return None
+    return raw
+
+
+def _encode_jpeg_data_uri(img) -> str:
+    """Encode an RGB image as a `data:image/jpeg;base64,…` string."""
+    buf = io.BytesIO()
+    img.save(buf, format="JPEG", quality=_THUMBNAIL_JPEG_QUALITY, optimize=True)
+    return "data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode("ascii")
+
+
+def image_thumbnail(value: str, budget: int = _DEFAULT_FIELD_BUDGET) -> str | None:
+    """Re-encode an oversized inline image as the largest JPEG data URI that fits
+    ``budget`` bytes (the caller's field size cap).
+
+    Sizes by BYTES, not pixels: it encodes at the source's native size and, while
+    that overflows ``budget`` minus the envelope overhead, halves the longest edge
+    and re-encodes until it fits — so an already-small image is returned at full
+    resolution and a large one is scaled down just enough. Returns a
+    `data:image/jpeg;base64,…` string on success, or None when the value contains
+    no raster image data URI, Pillow is unavailable, no size fits the budget, or
+    anything fails. Never raises.
+    """
+    raw = _extract_image_bytes(value)
+    if raw is None:
+        return None
+    limit = budget - _ENVELOPE_HEADROOM
+    if limit <= len("data:image/jpeg;base64,"):
+        return None
+    try:
+        from PIL import Image  # optional dependency (cmpnd[images])
+    except ImportError:
+        return None
+    try:
+        with Image.open(io.BytesIO(raw)) as opened:
+            # Image.open is lazy: it reads only the header (enough for .size),
+            # not the pixels. Reject on the declared size BEFORE load() so a
+            # small compressed payload that claims a huge bitmap never decodes at
+            # full resolution. This is our own strict ceiling; we never touch
+            # Pillow's Image.MAX_IMAGE_PIXELS global.
+            w, h = opened.size
+            if w * h > _MAX_IMAGE_PIXELS:
+                return None
+            opened.load()
+            # JPEG has no alpha: flatten transparency / palette onto white so
+            # a PNG/GIF with an alpha channel doesn't fail the encode.
+            if opened.mode in ("RGBA", "LA", "P"):
+                rgba = opened.convert("RGBA")
+                background = Image.new("RGBA", rgba.size, (255, 255, 255, 255))
+                base = Image.alpha_composite(background, rgba).convert("RGB")
+            elif opened.mode != "RGB":
+                base = opened.convert("RGB")
+            else:
+                base = opened.copy()
+        # Encode at native size; while it overflows the budget, halve the
+        # longest edge and re-encode. Returns the first (largest) size that
+        # fits — native itself when the image is already small enough.
+        best: str | None = None
+        edge = max(base.size)
+        while edge >= 1:
+            candidate = base.copy()
+            candidate.thumbnail((edge, edge))  # only ever downscales
+            uri = _encode_jpeg_data_uri(candidate)
+            if len(uri) <= limit:
+                best = uri
+                break
+            edge //= 2
+    except Exception:
+        # Any decode/resize/encode failure — corrupt bytes or a header that
+        # can't be read, an unsupported sub-format — degrades to no thumbnail.
+        # Instrumentation must not break the host program.
+        return None
+    return best

{cmpnd-0.7.2 → cmpnd-0.8.1}/cmpnd/models.py

@@ -9,7 +9,7 @@ from enum import Enum
 from typing import Any
 from uuid import UUID
 
-from . import identity
+from . import identity, imaging
 
 
 def _safe_serialize(value: Any, _stack: set[int] | None = None) -> Any:
@@ -169,6 +169,20 @@ def truncate_field(value: Any, max_size: int = _MAX_FIELD_JSON_SIZE, depth: int
         # bytes (exporter.py); a raw char count or UTF-8 byte count both
         # undercount that. _size_chars stays the char count.
         if len(json.dumps(value)) > max_size:
+            # An oversized inline image would otherwise lose every pixel to the
+            # 1000-char fragment below. If the value is a raster image data URI
+            # and Pillow is available, keep a small COMPLETE thumbnail in the
+            # _preview slot and flip _type to "image" so the reader can render it.
+            # Returns None (→ plain-string truncation) for non-images, no Pillow,
+            # or any failure, so this path is purely additive and never raises.
+            thumbnail = imaging.image_thumbnail(value, max_size)
+            if thumbnail is not None:
+                return {
+                    "_truncated": True,
+                    "_type": "image",
+                    "_size_chars": len(value),
+                    "_preview": thumbnail,
+                }
             return {
                 "_truncated": True,
                 "_type": "string",

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

@@ -464,17 +464,9 @@ class CmpndGEPACallback:
 
         for idx, instructions in enumerate(candidates):
             try:
-                # Extract parent index (first non-None parent)
-                parent_idx = None
-                if idx < len(parents):
-                    parent_list = parents[idx]
-                    if isinstance(parent_list, (list, tuple)):
-                        for p in parent_list:
-                            if p is not None:
-                                parent_idx = p
-                                break
-                    elif parent_list is not None:
-                        parent_idx = parent_list
+                # Extract the full parent list — a merge proposal has two, and
+                # serve derives the mutation type and generation from them.
+                parents_of = tracker.normalize_parent_indices(parents[idx] if idx < len(parents) else None)
 
                 # Compute aggregate score: prefer val_subscores (per-example),
                 # fall back to objective_scores (per-objective)
@@ -503,7 +495,7 @@ class CmpndGEPACallback:
                     tracker.CandidateData(
                         candidate_idx=idx,
                         instructions=instructions if isinstance(instructions, dict) else {},
-                        parent_idx=parent_idx,
+                        parent_indices=parents_of,
                         discovery_iteration=int(discovery_counts[idx]) if idx < len(discovery_counts) else 0,
                         val_aggregate_score=val_aggregate_score,
                         val_subscores=val_subs,

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

@@ -22,6 +22,25 @@ _ETA_WINDOW = 10
 _ETA_MIN_SAMPLES = 3
 
 
+def normalize_parent_indices(parent_entry: Any) -> list[int]:
+    """Normalize one candidate's optimizer parent entry into candidate indices.
+
+    GEPA records parents per candidate as a list — two entries for a merge
+    proposal, `[None]` for the seed — while some result shapes give a bare
+    index or nothing at all. `None` entries are padding, not edges, so they
+    are dropped rather than becoming a parentless-but-present link.
+    """
+    if parent_entry is None:
+        return []
+    if isinstance(parent_entry, int):
+        return [int(parent_entry)]
+    if isinstance(parent_entry, (list, tuple, set, frozenset)):
+        entries: list[Any] = list(parent_entry)
+        return [int(p) for p in entries if p is not None]
+    logger.debug(f"Unknown parent format: {type(parent_entry)} = {parent_entry}")
+    return []
+
+
 def _sanitize_for_json(obj: Any) -> Any:
     """Recursively sanitize an object for JSON serialization.
 
@@ -155,7 +174,14 @@ class CandidateData:
 
     candidate_idx: int
     instructions: dict[str, str]  # component_name -> instruction text
+    # Lineage. `parent_indices` is the full parent list — a GEPA merge proposal
+    # has two, and serve derives mutation_type (seed / reflective / merge) and
+    # generation from it, so collapsing to one parent loses the merge. Indices
+    # are into this run's candidate list: serve mints the candidate ids, so an
+    # index is the only lineage the SDK can name. `parent_idx` is the first
+    # parent, kept for the single-parent call sites and read surfaces.
     parent_idx: int | None = None
+    parent_indices: list[int] = field(default_factory=list)
     discovery_iteration: int = 0
 
     # Validation scores
@@ -174,12 +200,20 @@ class CandidateData:
     subsample_score_before: float | None = None  # parent's subsample score
     subsample_score_after: float | None = None  # this candidate's subsample score
 
+    def __post_init__(self) -> None:
+        """Reconcile the two parent forms so both are always populated."""
+        self.parent_indices = normalize_parent_indices(self.parent_indices)
+        if not self.parent_indices and self.parent_idx is not None:
+            self.parent_indices = [int(self.parent_idx)]
+        self.parent_idx = self.parent_indices[0] if self.parent_indices else None
+
     def to_api_dict(self) -> dict[str, Any]:
         """Convert to API-compatible dictionary."""
         return {
             "candidate_idx": int(self.candidate_idx),
             "instructions": _sanitize_for_json(self.instructions),
             "parent_idx": int(self.parent_idx) if self.parent_idx is not None else None,
+            "parent_indices": [int(p) for p in self.parent_indices],
             "discovery_iteration": int(self.discovery_iteration) if self.discovery_iteration else 0,
             "val_aggregate_score": float(self.val_aggregate_score) if self.val_aggregate_score else 0.0,
             "val_subscores": [float(s) for s in self.val_subscores] if self.val_subscores else [],
@@ -563,24 +597,15 @@ class OptimizationTracker:
             elif isinstance(candidate, dict):
                 instructions = candidate
 
-            parent_idx = None
-            if idx < len(parents_list):
-                parent_val = parents_list[idx]
-                # Handle different parent structures
-                if isinstance(parent_val, (list, tuple)) and len(parent_val) > 0:
-                    parent_idx = parent_val[0]
-                elif isinstance(parent_val, int):
-                    parent_idx = parent_val
-                elif parent_val is not None:
-                    logger.debug(f"Unknown parent format for candidate {idx}: {type(parent_val)} = {parent_val}")
+            parents = normalize_parent_indices(parents_list[idx] if idx < len(parents_list) else None)
 
-            logger.debug(f"Candidate {idx}: parent_idx={parent_idx}")
+            logger.debug(f"Candidate {idx}: parents={parents}")
 
             self.candidates.append(
                 CandidateData(
                     candidate_idx=idx,
                     instructions=instructions,
-                    parent_idx=parent_idx,
+                    parent_indices=parents,
                     discovery_iteration=discovery_counts[idx] if idx < len(discovery_counts) else 0,
                     val_aggregate_score=scores_list[idx] if idx < len(scores_list) else 0.0,
                     val_subscores=subscores_list[idx] if idx < len(subscores_list) else [],

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

@@ -156,7 +156,17 @@ Override any of these by passing kwargs to `cmpnd.configure(...)`.
 
 ### 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.
+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 up to `_data_post_attempts` (3) times before it counts, so a momentary blip against a busy backend doesn't register as a hard error. Three things count as transient, checked by `_is_retryable_export_error`:
+
+- a `502`/`503`/`504` gateway/overload status;
+- **any** status the server explicitly flagged with a `{"retryable": true}` error body (`_server_says_retryable`) — the server's stable machine signal for "this failed transiently and did not commit", which is what keeps this side off a hard-coded status list and lets the server start signalling a new transient condition without an SDK release;
+- an httpx transport/timeout error.
+
+It is *not* retried on `4xx` (client error), `429`, or an **unflagged** `500` (the platform's to answer for — the same boundary as the stress harness's `is_external_outage`). The `429` exemption is absolute: a flagged `429` still drops, because retrying into a server that asked us to shed would amplify the overload the status exists to relieve.
+
+The wait between attempts is the server's `Retry-After` hint when it sent one (delta-seconds form only; an HTTP-date or unparseable value falls back), else `_data_post_backoff` exponential backoff. Either way it is clamped to `_data_post_max_delay` (5s) — the exporter thread is the sole queue drainer, so an unbounded wait wouldn't just delay one send, it would stall every record behind it.
+
+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; on the flagged path the server only sets the flag when it did *not* commit. 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
 
@@ -245,6 +255,7 @@ Every envelope carries `_truncated: true`, a `_type`, and a `_preview` (serve re
 - **list** → `{_truncated, _type: "list", _total_items, _shown_items, _size_bytes, _preview}` — `_preview` is the first ≤10 items, each recursively truncated (`_shown_items == len(_preview)`); an oversized first item survives as its own nested envelope.
 - **dict** (nested, over the key ceiling `_MAX_DICT_KEYS` = 50) → `{_truncated, _type: "dict", _total_keys, _shown_keys, _preview}` — `_preview` holds the first K kept keys, each recursively truncated. Kept keys nest under `_preview` (not inline) so a user key named like a marker can't be clobbered.
 - **other scalar** → `{_truncated, _type: <typename>, _size_bytes | _size_chars, _preview}`.
+- **image** → `{_truncated, _type: "image", _size_chars, _preview}` — when an oversized string is a raster image data URI (`data:image/<png|jpeg|gif|webp|bmp>;base64,…`) **and** the optional `cmpnd[images]` extra (Pillow) is installed, `_preview` holds a *complete* small JPEG thumbnail — sized to fit the field's byte budget (as large as fits, scaled down from the source's native size, with no fixed pixel dimension) — instead of a 1000-char fragment, and `_type` is `"image"`. Emitted only on a successful thumbnail; without Pillow, or on any failure, the field degrades to the plain **string** envelope above (byte-identical to before). The `_type` is the render gate: serve shows `_preview` as an `<img>` only for `_type:"image"` (a `string`-envelope fragment also starts with `data:image/` but is incomplete, so it stays text). Thumbnailing lives in `python-sdk/cmpnd/imaging.py`; it is import-guarded and never raises into the capture path.
 
 Dict handling: **value-aware allocation** keeps every key (small values whole, the remaining budget split across the large ones — a missing key would read as "not captured", the symptom this replaced). Two things can still drop keys, each recorded via the `_type:"dict"` envelope: the **key ceiling** (`_MAX_DICT_KEYS`), which applies to nested dicts only — the root is exempt from it; and the **whole-payload guard** — since `max_size` bounds the whole payload, after assembly any dict (root included) sheds trailing keys until it serializes within `max_size`. So the root keeps all its fields when they fit and is trimmed (with `_total_keys`/`_shown_keys`) when the payload still exceeds the cap. The callback capture path (`helpers.clean_inputs`) truncates each field value at depth 1, so a nested dict field value caps consistently with `SpanBuilder.to_dict` (where the whole inputs dict is the depth-0 root and field values are depth 1).
 

{cmpnd-0.7.2 → cmpnd-0.8.1}/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.2"
+version = "0.8.1"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -46,6 +46,13 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+# Image thumbnailing for oversized image inputs/outputs. Optional and
+# import-guarded: without it, an oversized image degrades to today's text
+# preview. Pillow is heavyweight and most instrumentation captures no images, so
+# it is not a hard dependency.
+images = [
+    "pillow>=10.0",
+]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
@@ -62,6 +69,9 @@ dev = [
     # 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",
+    # Exercises the image-thumbnail path (the `images` extra) so the positive
+    # branch is covered in CI, not just the Pillow-absent fallback.
+    "pillow>=10.0",
 ]
 # Deps for `deploy/deploy/stub/`, the local FastAPI server that emulates
 # the AWS deploy stack. The stub itself ships in the cmpnd-deploy

{cmpnd-0.7.2 → cmpnd-0.8.1}/tests/e2e/test_optimize_loop.py

@@ -215,10 +215,18 @@ class TestOptimizeGepaDeployDetail:
 
         # The producer ran a cmpnd OptimizationTracker: the run lands full detail
         # (>= the seed candidate), not just a summary header. Asserted first so a
-        # producer/tracker failure is distinguished from a trace-stamping one. The
-        # watcher writes the run header + candidates in one transaction, so once
-        # the run is visible the candidates are too.
-        candidates = server_client.get_optimization_candidates(run_id).get("candidates", [])
+        # producer/tracker failure is distinguished from a trace-stamping one.
+        #
+        # Polled, because a run is addressable BEFORE it has any detail: serve
+        # writes the header at initiate with status "running" so the run is listed
+        # and its detail URL resolves for its whole duration (CMP-412), and the
+        # candidates arrive later, when the completion watcher settles it. The
+        # search above therefore returns the run while the candidate set is still
+        # legitimately empty, and a single read here races the watcher.
+        def _find_candidates():
+            return server_client.get_optimization_candidates(run_id).get("candidates", [])
+
+        candidates = _poll(_find_candidates)
         assert candidates, f"GEPA deploy run {run_id} landed a header but no candidate detail (CMP-323)"
 
         # CMP-323/CMP-318 activation: the Lambda's tracker stamps the run id onto