cmpnd 0.7.2__tar.gz → 0.8.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmpnd
-Version: 0.7.2
+Version: 0.8.0
 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.8.0/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.0}/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.0}/docs/sdk-instrumentation.md

@@ -245,6 +245,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.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.7.2"
+version = "0.8.0"
 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.0}/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

cmpnd-0.8.0/tests/test_imaging.py

@@ -0,0 +1,193 @@
+"""Image-thumbnail path for oversized image inputs/outputs.
+
+Covers the imaging helper directly and its integration into truncate_field: an
+oversized inline image becomes a `_type:"image"` envelope carrying a small
+complete thumbnail in `_preview`, while non-images and the Pillow-absent case
+fall back to today's `_type:"string"` truncation.
+"""
+
+import base64
+import io
+import os
+
+import pytest
+
+from cmpnd import imaging
+from cmpnd.models import _MAX_FIELD_JSON_SIZE, truncate_field
+
+PIL_Image = pytest.importorskip("PIL.Image")
+
+
+def _data_uri(img, fmt="PNG") -> str:
+    buf = io.BytesIO()
+    img.save(buf, format=fmt)
+    mime = "jpeg" if fmt.upper() == "JPEG" else fmt.lower()
+    return f"data:image/{mime};base64," + base64.b64encode(buf.getvalue()).decode("ascii")
+
+
+def _noise_image(px: int):
+    # Random pixels barely compress, so the encoded data URI reliably clears the
+    # 64 KB field cap (a flat image would compress under it).
+    return PIL_Image.frombytes("RGB", (px, px), os.urandom(px * px * 3))
+
+
+def _oversized_png_uri() -> str:
+    uri = _data_uri(_noise_image(256))
+    assert len(uri) > _MAX_FIELD_JSON_SIZE, "fixture must exceed the field cap"
+    return uri
+
+
+def _decoded_edge(data_uri: str) -> int:
+    with PIL_Image.open(io.BytesIO(base64.b64decode(data_uri.split(",", 1)[1]))) as im:
+        assert im.format == "JPEG"
+        return max(im.size)
+
+
+def test_thumbnail_is_valid_jpeg_within_budget():
+    uri = _oversized_png_uri()
+    thumb = imaging.image_thumbnail(uri)
+    assert thumb is not None
+    assert thumb.startswith("data:image/jpeg;base64,")
+    assert len(thumb) <= 65536  # fits the default field budget
+    assert len(thumb) < len(uri)  # smaller than the original data URI
+    _decoded_edge(thumb)  # decodes to a real JPEG
+
+
+def test_thumbnail_sizes_to_byte_budget():
+    # A smooth gradient compresses predictably yet grows with pixel size, so a
+    # bigger byte budget yields a physically larger thumbnail.
+    gradient = PIL_Image.linear_gradient("L").convert("RGB").resize((1024, 1024))
+    uri = _data_uri(gradient)
+    small = imaging.image_thumbnail(uri, budget=8000)
+    large = imaging.image_thumbnail(uri, budget=64000)
+    assert small is not None and large is not None
+    assert len(small) <= 8000
+    assert len(large) <= 64000
+    # Sizing is byte-driven, not a fixed pixel cap: more budget -> more pixels.
+    assert _decoded_edge(large) > _decoded_edge(small)
+
+
+def test_thumbnail_keeps_native_size_when_it_fits():
+    # An image whose JPEG already fits the budget is returned at full resolution,
+    # not resized — the scale-down-from-native path handles this for free.
+    img = PIL_Image.linear_gradient("L").convert("RGB").resize((96, 96))
+    thumb = imaging.image_thumbnail(_data_uri(img), budget=64000)
+    assert thumb is not None
+    assert _decoded_edge(thumb) == 96
+
+
+def test_thumbnail_flattens_alpha_png():
+    # An RGBA source must not fail the JPEG encode (JPEG has no alpha).
+    rgba = PIL_Image.frombytes("RGBA", (256, 256), os.urandom(256 * 256 * 4))
+    thumb = imaging.image_thumbnail(_data_uri(rgba))
+    assert thumb is not None and thumb.startswith("data:image/jpeg;base64,")
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "not a data uri at all",
+        "data:text/plain;base64,aGVsbG8=",
+        "data:image/svg+xml;base64,PHN2Zy8+",  # vector, refused
+        "data:image/png,notbase64",  # not a base64 data URI
+        "data:image/png;base64,@@@not-base64@@@",
+    ],
+)
+def test_thumbnail_returns_none_for_non_raster_or_garbage(value):
+    assert imaging.image_thumbnail(value) is None
+
+
+def test_thumbnail_refuses_oversized_source(monkeypatch):
+    monkeypatch.setattr(imaging, "_MAX_DECODE_BYTES", 1024)
+    assert imaging.image_thumbnail(_oversized_png_uri()) is None
+
+
+def test_thumbnail_pixel_ceiling_rejects_before_decode(monkeypatch):
+    # A tiny pixel ceiling must reject a normal 256x256 (65536 px) image: the
+    # size is read from the header and checked before any pixel decode.
+    monkeypatch.setattr(imaging, "_MAX_IMAGE_PIXELS", 100)
+    assert imaging.image_thumbnail(_oversized_png_uri()) is None
+
+
+def test_thumbnail_never_mutates_pillow_global():
+    # The helper enforces its own ceiling and must never touch Pillow's
+    # process-global MAX_IMAGE_PIXELS — neither on the success path nor on the
+    # reject path — so it can't race concurrent captures.
+    before = PIL_Image.MAX_IMAGE_PIXELS
+    assert imaging.image_thumbnail(_oversized_png_uri()) is not None
+    assert PIL_Image.MAX_IMAGE_PIXELS == before
+
+    with pytest.MonkeyPatch.context() as mp:
+        mp.setattr(imaging, "_MAX_IMAGE_PIXELS", 100)
+        assert imaging.image_thumbnail(_oversized_png_uri()) is None
+    assert PIL_Image.MAX_IMAGE_PIXELS == before
+
+
+def test_thumbnail_none_without_pillow(monkeypatch):
+    # Simulate Pillow not installed: make the in-function `from PIL import Image`
+    # raise ImportError, so the helper returns None (today's behavior).
+    import builtins
+
+    real_import = builtins.__import__
+
+    def fake_import(name, *args, **kwargs):
+        if name == "PIL" or name.startswith("PIL."):
+            raise ImportError("simulated: no pillow")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+    assert imaging.image_thumbnail(_oversized_png_uri()) is None
+
+
+def test_truncate_field_emits_image_envelope():
+    uri = _oversized_png_uri()
+    result = truncate_field(uri)
+    assert result["_truncated"] is True
+    assert result["_type"] == "image"
+    assert result["_size_chars"] == len(uri)
+    assert result["_preview"].startswith("data:image/jpeg;base64,")
+    # The whole envelope still fits the field cap (thumbnail is a few KB).
+    import json
+
+    assert len(json.dumps(result)) <= _MAX_FIELD_JSON_SIZE
+
+
+def test_truncate_field_falls_back_to_string_without_thumbnail(monkeypatch):
+    # No thumbnail (no Pillow / failure) => today's string truncation, byte-identical.
+    monkeypatch.setattr("cmpnd.models.imaging.image_thumbnail", lambda *a, **k: None)
+    uri = _oversized_png_uri()
+    result = truncate_field(uri)
+    assert result["_type"] == "string"
+    assert result["_preview"] == uri[:1000]
+
+
+def test_truncate_field_non_image_string_unchanged():
+    result = truncate_field("x" * (_MAX_FIELD_JSON_SIZE + 10))
+    assert result["_type"] == "string"
+    assert result["_preview"] == "x" * 1000
+
+
+def _dspy_image_wrapper(data_uri: str) -> str:
+    # Mirrors how DSPy serializes a dspy.Image (adapters/types/base_type.py): the
+    # data URI is nested inside a JSON image_url block wrapped in custom-type
+    # markers, so the captured leaf is NOT a bare data URI.
+    import json
+
+    body = json.dumps([{"type": "image_url", "image_url": {"url": data_uri}}])
+    return f"<<CUSTOM-TYPE-START-IDENTIFIER>>{body}<<CUSTOM-TYPE-END-IDENTIFIER>>"
+
+
+def test_thumbnail_extracts_from_dspy_wrapper():
+    wrapped = _dspy_image_wrapper(_oversized_png_uri())
+    thumb = imaging.image_thumbnail(wrapped)
+    assert thumb is not None
+    assert thumb.startswith("data:image/jpeg;base64,")
+
+
+def test_truncate_field_image_envelope_from_dspy_wrapper():
+    wrapped = _dspy_image_wrapper(_oversized_png_uri())
+    assert len(wrapped) > _MAX_FIELD_JSON_SIZE
+    result = truncate_field(wrapped)
+    assert result["_type"] == "image"
+    assert result["_preview"].startswith("data:image/jpeg;base64,")
+    assert result["_size_chars"] == len(wrapped)