cmpnd 0.84.0__tar.gz → 0.85.1__tar.gz

{cmpnd-0.84.0 → cmpnd-0.85.1}/PKG-INFO

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

{cmpnd-0.84.0 → cmpnd-0.85.1}/cmpnd/callback.py

@@ -687,18 +687,20 @@ class _CallbackBase:
         # repl_history (see _AdapterMixin._thin_rlm_adapter_inputs).
         self._rlm_turn_adapter_spans: set[UUID] = set()
 
-        # Parent span -> the last adapter ``format`` span under it and its full
-        # rendered messages, for the LM call that follows to reference. See
-        # _AdapterMixin._remember_rendered_messages and _LMMixin.on_lm_start.
-        self._rendered_messages: dict[UUID, tuple[models.SpanBuilder, Any]] = {}
+        # Parent span -> the last adapter ``format`` span under it and the full
+        # value of each prompt key it stored whole, for the LM calls that follow
+        # to reference. See _AdapterMixin._remember_rendered_prompt and
+        # _LMMixin._reference_rendered_prompt.
+        self._rendered_prompts: dict[UUID, tuple[models.SpanBuilder, dict[str, Any]]] = {}
 
         # Open module span -> id() of its module instance, so an adapter span can
         # name the predictor it renders for. And (trace, predictor) -> the last
-        # rendering of each message index that serve can rebuild in full, as
-        # (the format span storing it, its full text). Dropped when the trace
-        # ends. See _AdapterMixin._extend_previous_rendering.
+        # rendering of each prompt text that serve can rebuild in full, by its
+        # path in the format span's outputs, as (the format span storing it, its
+        # full text). Dropped when the trace ends. See
+        # _AdapterMixin._extend_previous_rendering.
         self._module_instance_by_span: dict[UUID, int] = {}
-        self._last_rendering: dict[tuple[str, int], list[tuple[UUID, str] | None]] = {}
+        self._last_rendering: dict[tuple[str, int], dict[tuple[str | int, ...], tuple[UUID, str]]] = {}
 
         # Ensure exporter is running
         self._ensure_exporter()
@@ -1058,7 +1060,7 @@ class _ModuleMixin(_CallbackBase):
 
         # An adapter rendering this module's prompt is only ever referenced by an
         # LM call under this module, which has ended with it.
-        self._rendered_messages.pop(span.span_id, None)
+        self._rendered_prompts.pop(span.span_id, None)
         self._module_instance_by_span.pop(span.span_id, None)
 
         # RLM repl_history: append trajectory data from PREDICT children
@@ -1213,9 +1215,9 @@ class _ModuleMixin(_CallbackBase):
 
     def _forget_trace_references(self, trace_id: UUID) -> None:
         """Drop the per-trace state reference encoding keeps, once the trace ends."""
-        for parent, (fmt_span, _) in list(self._rendered_messages.items()):
+        for parent, (fmt_span, _) in list(self._rendered_prompts.items()):
             if fmt_span.trace_id == trace_id:
-                self._rendered_messages.pop(parent, None)
+                self._rendered_prompts.pop(parent, None)
         for key in [k for k in self._last_rendering if k[0] == str(trace_id)]:
             self._last_rendering.pop(key, None)
 
@@ -1540,39 +1542,53 @@ class _LMMixin(_CallbackBase):
 
         # Capture prompt/messages if enabled. A credential passed to the call itself, as in
         # `lm(prompt, api_key=...)`, is stripped first: every member of the org reads a span.
+        # The rendered prompt becomes a reference before truncation, so the rest of the
+        # inputs keep the whole budget.
         if self._capture_prompts:
-            cleaned_inputs = helpers.clean_inputs(helpers.without_credentials(inputs), dspy, self._max_input_field_size)
-            self._reference_rendered_messages(parent_span, inputs, cleaned_inputs)
-            span.set_inputs(cleaned_inputs)
+            referenced = self._reference_rendered_prompt(parent_span, helpers.without_credentials(inputs))
+            span.set_inputs(helpers.clean_inputs(referenced, dspy, self._max_input_field_size))
 
         self._call_id_to_span[call_id] = span
         # Store LM instance reference to access history for token usage
         self._call_id_to_instance[call_id] = instance
         context.push_span(span)
 
-    def _reference_rendered_messages(
-        self, parent_span: models.SpanBuilder | None, inputs: dict[str, Any], cleaned: dict[str, Any]
-    ) -> None:
-        """Store the LM's messages as a reference to the adapter output they came from.
+    def _reference_rendered_prompt(
+        self, parent_span: models.SpanBuilder | None, inputs: dict[str, Any]
+    ) -> dict[str, Any]:
+        """``inputs`` with the rendered prompt as references to the adapter output it came from.
 
         The adapter's ``format`` span ended just before this call started, under
-        the same parent, and its ``outputs.result`` holds the rendered messages.
-        When the LM received exactly those, compared on the full values before any
-        truncation, ``messages`` becomes a ``_same_as`` reference to them; serve
-        resolves it on read. Anything else — messages the adapter changed after
-        rendering, or an LM call no adapter rendered for, such as an RLM
-        ``llm_query`` — keeps a full copy, so a mismatch costs bytes, never
-        correctness.
+        the same parent, and stored the rendered prompt (``references.prompt_keys``).
+        In the list shape, ``messages`` equal to the stored ``result`` becomes a
+        ``_same_as`` reference to it. In the typed shape, each of ``prompt.system``
+        and ``prompt.messages`` equal to the stored key becomes a reference to that
+        key, and the rest of the request stays inline. Values are compared in full,
+        before any truncation, and serve resolves the references on read.
+        Anything else, such as messages the adapter changed after rendering or an
+        LM call no adapter rendered for, like an RLM ``llm_query``, keeps a full
+        copy, so a mismatch costs bytes, never correctness. Each LM call the
+        adapter makes from one rendering gets the references.
         """
-        if parent_span is None or "messages" not in cleaned:
-            return
-        remembered = self._rendered_messages.pop(parent_span.span_id, None)
+        remembered = self._rendered_prompts.get(parent_span.span_id) if parent_span is not None else None
         if remembered is None:
-            return
+            return inputs
         fmt_span, rendered = remembered
-        if models._safe_serialize(inputs.get("messages")) != rendered:
-            return
-        cleaned["messages"] = references.same_as(str(fmt_span.span_id), "outputs", ["result"])
+        fmt_id = str(fmt_span.span_id)
+        if "result" in rendered:
+            if "messages" in inputs and models._safe_serialize(inputs["messages"]) == rendered["result"]:
+                return {**inputs, "messages": references.same_as(fmt_id, "outputs", ["result"])}
+            return inputs
+        if inputs.get("prompt") is None:
+            return inputs
+        prompt = models._safe_serialize(inputs["prompt"])
+        if not isinstance(prompt, dict):
+            return inputs
+        referenced = dict(prompt)
+        for key in references.TYPED_PROMPT_KEYS:
+            if key in rendered and key in prompt and prompt[key] == rendered[key]:
+                referenced[key] = references.same_as(fmt_id, "outputs", [key])
+        return inputs if referenced == prompt else {**inputs, "prompt": referenced}
 
     def on_lm_end(
         self,
@@ -1962,12 +1978,16 @@ class _AdapterMixin(_CallbackBase):
             if self._capture_outputs and outputs:
                 rendered = models._safe_serialize(outputs)
                 if span.span_type == models.SpanType.ADAPTER_FORMAT:
-                    # Encode against the previous rendering first, then truncate:
-                    # only a suffix that alone overflows the budget is cut.
-                    encoded = self._extend_previous_rendering(span, rendered)
-                    span.set_outputs(helpers.truncate_outputs(encoded, self._max_output_field_size))
-                    self._record_rendering(span, rendered)
-                    self._remember_rendered_messages(span, rendered)
+                    # The outputs as stored: a typed Prompt as its own dict, a list
+                    # of messages under "result". Encode against the previous
+                    # rendering first, then truncate: only a suffix that alone
+                    # overflows the budget is cut.
+                    body = rendered if isinstance(rendered, dict) else {"result": rendered}
+                    encoded = self._extend_previous_rendering(span, body)
+                    stored = encoded if isinstance(rendered, dict) else encoded["result"]
+                    span.set_outputs(helpers.truncate_outputs(stored, self._max_output_field_size))
+                    self._record_rendering(span, body)
+                    self._remember_rendered_prompt(span, body)
                 else:
                     span.set_outputs(helpers.truncate_outputs(rendered, self._max_output_field_size))
 
@@ -1992,78 +2012,81 @@ class _AdapterMixin(_CallbackBase):
         predictor = self._module_instance_by_span.get(span.parent_span_id)
         return None if predictor is None else (str(span.trace_id), predictor)
 
-    def _extend_previous_rendering(self, span: models.SpanBuilder, rendered: Any) -> Any:
-        """``rendered`` with each message that extends the predictor's last one encoded.
+    def _extend_previous_rendering(self, span: models.SpanBuilder, body: dict[str, Any]) -> dict[str, Any]:
+        """``body`` with each prompt text that extends the predictor's last one encoded.
 
         A predictor called once per turn — an RLM's action step, a ReAct step —
-        renders the previous turn's prompt plus what the turn added. For each
-        message whose content begins with the same-index message of the last
-        rendering this predictor stored in this trace, the content becomes an
-        ``_extends`` envelope over that stored message. Matching compares the full
-        rendered text and needs no knowledge of the module. The base may itself be
-        an extension, and serve resolves the chain.
+        renders the previous turn's prompt plus what the turn added. For each text
+        of the prompt (``references.prompt_text_leaves``) that begins with the text
+        at the same path in the last rendering this predictor stored in this trace,
+        the text becomes an ``_extends`` envelope over that stored text. In the
+        typed shape this covers the system prompt, which is the same on every turn,
+        as well as each message's text parts. Matching compares the full rendered
+        text and needs no knowledge of the module. The base may itself be an
+        extension, and serve resolves the chain.
         """
         key = self._rendering_key(span)
         previous = self._last_rendering.get(key) if key else None
-        if not previous or not isinstance(rendered, list):
-            return rendered
-        encoded = list(rendered)
-        for i, message in enumerate(rendered):
-            base = previous[i] if i < len(previous) else None
-            content = message.get("content") if isinstance(message, dict) else None
-            if base is None or not isinstance(content, str):
+        if not previous:
+            return body
+        encoded = body
+        for path, text in references.prompt_text_leaves(body):
+            base = previous.get(path)
+            if base is None:
                 continue
-            base_span_id, base_content = base
-            env = references.extends(
-                base_content, content, references.ref(str(base_span_id), "outputs", ["result", i, "content"])
-            )
+            base_span_id, base_text = base
+            env = references.extends(base_text, text, references.ref(str(base_span_id), "outputs", list(path)))
             if env is not None:
-                encoded[i] = {**message, "content": env}
+                encoded = references.with_value_at(encoded, path, env)
         return encoded
 
-    def _record_rendering(self, span: models.SpanBuilder, rendered: Any) -> None:
+    def _record_rendering(self, span: models.SpanBuilder, body: dict[str, Any]) -> None:
         """Keep this rendering as the base for the predictor's next one.
 
-        A message becomes the next base only where its stored form resolves to the
+        A text becomes the next base only where its stored form resolves to the
         full text: a whole string, or an extension whose suffix survived
-        truncation. Where it was cut, the previous base stays, so the next turn
-        extends a message serve can still rebuild.
+        truncation. Where it was cut, the previous base at that path stays, so the
+        next turn extends a text serve can still rebuild.
         """
         key = self._rendering_key(span)
-        stored = span.outputs.get("result") if isinstance(span.outputs, dict) else None
-        if key is None or not isinstance(rendered, list):
+        if key is None or not references.prompt_keys(body):
             return
-        previous = self._last_rendering.get(key) or []
-        current: list[tuple[UUID, str] | None] = []
-        for i, message in enumerate(rendered):
-            content = message.get("content") if isinstance(message, dict) else None
-            kept = stored[i] if isinstance(stored, list) and len(stored) == len(rendered) else None
-            kept_content = kept.get("content") if isinstance(kept, dict) else None
-            resolvable = kept_content == content or (
-                isinstance(kept_content, dict)
-                and set(kept_content) == {"_extends", "_prefix_chars", "_suffix"}
-                and isinstance(kept_content["_suffix"], str)
+        previous = self._last_rendering.get(key) or {}
+        current: dict[tuple[str | int, ...], tuple[UUID, str]] = {}
+        for path, text in references.prompt_text_leaves(body):
+            kept = references.value_at(span.outputs, path)
+            resolvable = kept == text or (
+                isinstance(kept, dict)
+                and set(kept) == {"_extends", "_prefix_chars", "_suffix"}
+                and isinstance(kept["_suffix"], str)
             )
-            if isinstance(content, str) and resolvable:
-                current.append((span.span_id, content))
-            else:
-                current.append(previous[i] if i < len(previous) else None)
+            if resolvable:
+                current[path] = (span.span_id, text)
+            elif path in previous:
+                current[path] = previous[path]
         self._last_rendering[key] = current
 
-    def _remember_rendered_messages(self, span: models.SpanBuilder, rendered: Any) -> None:
-        """Keep a ``format`` span's full rendered messages for the LM call that follows.
+    def _remember_rendered_prompt(self, span: models.SpanBuilder, body: dict[str, Any]) -> None:
+        """Keep a ``format`` span's full rendered prompt for the LM calls that follow.
 
-        The adapter hands exactly these messages to the LM, which starts after
-        this span ended, as its sibling under the same parent. ``on_lm_start``
-        compares its messages with them and writes a reference when they are
-        equal. Kept only when the stored output still holds the list at
-        ``outputs.result``: a list truncated whole into an envelope cannot be
-        walked into, and the LM span then keeps its own copy.
+        The adapter hands exactly this prompt to the LM, which starts after this
+        span ended, as its sibling under the same parent.
+        ``_reference_rendered_prompt`` compares the LM's prompt with it and writes
+        references where they are equal. A prompt key is kept only when its stored
+        value resolves in full: a list truncated into an envelope cannot be walked
+        into, and the LM span then keeps its own copy of that key.
         """
-        stored = span.outputs.get("result") if isinstance(span.outputs, dict) else None
-        if span.parent_span_id is None or not isinstance(rendered, list) or not isinstance(stored, list):
+        if span.parent_span_id is None:
             return
-        self._rendered_messages[span.parent_span_id] = (span, rendered)
+        kept = {}
+        for key in references.prompt_keys(body):
+            stored = references.value_at(span.outputs, (key,))
+            if stored is not None and references.resolves_in_full(stored):
+                kept[key] = body[key]
+        if kept:
+            self._rendered_prompts[span.parent_span_id] = (span, kept)
+        else:
+            self._rendered_prompts.pop(span.parent_span_id, None)
 
 
 class _ToolMixin(_CallbackBase):

{cmpnd-0.84.0 → cmpnd-0.85.1}/cmpnd/helpers.py

@@ -305,13 +305,15 @@ def credential_fields(kwargs: Any) -> list[str]:
 
 def without_credentials(inputs: Any) -> Any:
     """``inputs`` with every credential :func:`credential_fields` names removed, at the top
-    level and in the nested ``kwargs`` an LM call's hook inputs carry."""
+    level and in the nested keyword arguments an LM call's hook inputs carry: ``kwargs``
+    through DSPy 3.4, and ``options`` where the LM takes an lm15 ``Request``."""
     if not isinstance(inputs, dict):
         return inputs
     kept = _without_credential_kwargs(inputs)
-    nested = kept.get("kwargs")
-    if isinstance(nested, dict):
-        kept["kwargs"] = _without_credential_kwargs(nested)
+    for holder in ("kwargs", "options"):
+        nested = kept.get(holder)
+        if isinstance(nested, dict):
+            kept[holder] = _without_credential_kwargs(nested)
     return kept
 
 

{cmpnd-0.84.0 → cmpnd-0.85.1}/cmpnd/ir/reflection.py

@@ -114,7 +114,10 @@ def reflect(m: Any) -> program.Module:
         return program.ChainOfThought(project_sig(_user_sig_of_cot(m)))
     if isinstance(m, dspy.MultiChainComparison):
         return program.MultiChainComparison(project_sig(m.predict.signature))  # pyright: ignore[reportAttributeAccessIssue]
-    if isinstance(m, dspy.ProgramOfThought):
+    # DSPy main removed ProgramOfThought after 3.4, so it is looked up like the
+    # kinds a release may lack.
+    pot_cls = _opt("ProgramOfThought")
+    if pot_cls is not None and isinstance(m, pot_cls):
         return program.ProgramOfThought(project_sig(m.signature))
 
     rlm_cls = _opt("RLM")

{cmpnd-0.84.0 → cmpnd-0.85.1}/cmpnd/models.py

@@ -63,6 +63,40 @@ def _type_name(value: Any) -> str:
     return _strip_unstorable(type(value).__name__)
 
 
+def _is_lm15_value(value: Any) -> bool:
+    """Whether ``value`` is an lm15 object, or the typed ``Prompt`` a DSPy adapter renders from them.
+
+    DSPy vendors lm15 as ``dspy._vendor.lm15``. Its ``Prompt`` lives in
+    ``dspy.adapters.base`` and holds lm15 messages.
+    """
+    module = type(value).__module__
+    if module == "lm15" or module.startswith(("lm15.", "dspy._vendor.lm15")):
+        return True
+    return module == "dspy.adapters.base" and type(value).__name__ == "Prompt"
+
+
+def _compact_dataclass(value: Any, _stack: set[int]) -> dict[str, Any]:
+    """An lm15 dataclass as a dict without its null and empty fields.
+
+    lm15 objects carry many optional fields, such as a request's eighteen
+    ``config`` settings and an empty ``continuation`` on every message and part,
+    that are null or empty on almost every call. lm15's own serializer omits
+    them, and so does this. ``0``, ``False`` and ``""`` stay. The adapter's
+    ``Prompt`` and the LM call's ``Request`` serialize their messages by the
+    same rule, so the span references that compare them still match. Nested
+    lm15 objects are compacted too, and ``provider_data`` stays.
+    """
+    import dataclasses
+
+    compact: dict[str, Any] = {}
+    for member in dataclasses.fields(value):
+        serialized = _safe_serialize(getattr(value, member.name), _stack)
+        if serialized is None or serialized == [] or serialized == {}:
+            continue
+        compact[_strip_unstorable(member.name)] = serialized
+    return compact
+
+
 def _safe_serialize(value: Any, _stack: set[int] | None = None) -> Any:
     """Recursively serialize a value to JSON-safe types.
 
@@ -147,6 +181,8 @@ def _safe_serialize(value: Any, _stack: set[int] | None = None) -> Any:
             import dataclasses
 
             if dataclasses.is_dataclass(value) and not isinstance(value, type):
+                if _is_lm15_value(value):
+                    return _compact_dataclass(value, _stack)
                 return _safe_serialize(dataclasses.asdict(value), _stack)
         except Exception:
             pass

cmpnd-0.85.1/cmpnd/references.py

@@ -0,0 +1,180 @@
+"""Reference envelopes: a span body that names a value an earlier span recorded.
+
+A trace records the same prompt on several spans: the adapter renders the
+messages, and the LM call receives them. Rather than store a second copy, the
+SDK writes the later occurrence as a reference to the earlier one:
+
+    {"_same_as": {"span_id": "<uuid>", "field": "outputs", "path": ["result"]}}
+
+``field`` is ``inputs``, ``outputs`` or ``attributes``, and ``path`` walks object
+keys (strings) and list indexes (integers) inside it. Like the truncation
+envelope, a reference envelope carries only its marker keys, so serve can tell
+it from a user object that happens to hold one of them.
+
+A string that begins with a string an earlier span recorded is written as an
+extension of it: the length of the shared prefix and what follows.
+
+    {"_extends": {"span_id": "<uuid>", "field": "outputs", "path": ["result", 1, "content"]},
+     "_prefix_chars": 71234, "_suffix": "=== Step 9 ===\\n..."}
+
+``_prefix_chars`` counts code points, the unit a Python ``str`` indexes, and
+serve slices the base by code point too. A turn of an RLM or ReAct program
+renders the previous turn's prompt plus one more step, so each turn is stored
+as a small suffix and the whole trace grows linearly with its turns.
+
+An adapter's ``format`` span stores its rendered prompt in one of two shapes,
+and references name text inside either:
+
+* DSPy 3.4 and earlier render a list of ``{role, content}`` messages, stored at
+  ``outputs.result``. The LM call receives the same list as ``inputs.messages``.
+* lm15's typed ``Prompt`` stores ``outputs.system`` and ``outputs.messages``,
+  where each message holds ``parts`` and each text part holds ``text``. The LM
+  call receives both inside ``inputs.prompt``, an lm15 ``Request``.
+
+A reference always names a span that ended before the referring span started,
+so its base has already been exported when the reference is written. serve
+resolves references when it reads a trace, so every reader sees the full value;
+the SDK never has to.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+FIELDS = ("inputs", "outputs", "attributes")
+
+# An extension must share at least this many code points with its base, and at
+# least half of its own length: below that the envelope saves too little to be
+# worth a hop on read.
+MIN_PREFIX_CHARS = 1024
+
+
+def ref(span_id: str, field: str, path: list[Any]) -> dict[str, Any]:
+    """The location of a stored value: a span, one of its bodies, and a path into it."""
+    if field not in FIELDS:
+        raise ValueError(f"field must be one of {FIELDS}, not {field!r}")
+    return {"span_id": span_id, "field": field, "path": list(path)}
+
+
+def same_as(span_id: str, field: str, path: list[Any]) -> dict[str, Any]:
+    """A value equal to the one stored at ``span_id``'s ``field`` under ``path``."""
+    return {"_same_as": ref(span_id, field, path)}
+
+
+def common_prefix_chars(a: str, b: str) -> int:
+    """The number of leading code points ``a`` and ``b`` share.
+
+    A binary search over slice comparisons, so the character loop runs in C:
+    prompts reach hundreds of kilobytes and a turn compares two of them.
+    """
+    lo, hi = 0, min(len(a), len(b))
+    while lo < hi:
+        mid = (lo + hi + 1) // 2
+        if a[:mid] == b[:mid]:
+            lo = mid
+        else:
+            hi = mid - 1
+    return lo
+
+
+def extends(base: str, value: str, base_ref: dict[str, Any]) -> dict[str, Any] | None:
+    """``value`` as an extension of ``base``, stored at ``base_ref``, or None.
+
+    None when the shared prefix is shorter than ``MIN_PREFIX_CHARS`` or than half
+    of ``value``; the caller then stores ``value`` in full.
+    """
+    n = common_prefix_chars(base, value)
+    if n < MIN_PREFIX_CHARS or 2 * n < len(value):
+        return None
+    return {"_extends": base_ref, "_prefix_chars": n, "_suffix": value[n:]}
+
+
+# The keys of a rendered prompt an LM call receives, in each shape: the list at
+# ``outputs.result``, or the typed ``Prompt``'s two halves.
+LIST_PROMPT_KEYS = ("result",)
+TYPED_PROMPT_KEYS = ("system", "messages")
+
+
+def prompt_keys(outputs: Any) -> tuple[str, ...]:
+    """The keys of an adapter ``format`` span's outputs that hold its rendered prompt.
+
+    Empty when ``outputs`` is neither shape, such as a custom adapter's output.
+    """
+    if not isinstance(outputs, dict):
+        return ()
+    if isinstance(outputs.get("result"), list):
+        return LIST_PROMPT_KEYS
+    if isinstance(outputs.get("messages"), list):
+        return TYPED_PROMPT_KEYS
+    return ()
+
+
+def prompt_text_leaves(outputs: Any) -> list[tuple[tuple[str | int, ...], str]]:
+    """Each text of a rendered prompt, with its path inside the adapter span's outputs.
+
+    In the list shape, each message's string ``content``. In the typed shape, the
+    ``system`` text and each message's text parts. A message or part of another
+    form, such as an image, has no text leaf and is left out.
+    """
+    keys = prompt_keys(outputs)
+    leaves: list[tuple[tuple[str | int, ...], str]] = []
+    if keys == LIST_PROMPT_KEYS:
+        for i, message in enumerate(outputs["result"]):
+            content = message.get("content") if isinstance(message, dict) else None
+            if isinstance(content, str):
+                leaves.append((("result", i, "content"), content))
+    elif keys == TYPED_PROMPT_KEYS:
+        if isinstance(outputs.get("system"), str):
+            leaves.append((("system",), outputs["system"]))
+        for i, message in enumerate(outputs["messages"]):
+            parts = message.get("parts") if isinstance(message, dict) else None
+            for j, part in enumerate(parts if isinstance(parts, list) else []):
+                text = part.get("text") if isinstance(part, dict) and part.get("type") == "text" else None
+                if isinstance(text, str):
+                    leaves.append((("messages", i, "parts", j, "text"), text))
+    return leaves
+
+
+def value_at(value: Any, path: tuple[str | int, ...]) -> Any:
+    """The value under ``path``, or None when the path does not exist in ``value``."""
+    for step in path:
+        if isinstance(step, str) and isinstance(value, dict):
+            value = value.get(step)
+        elif isinstance(step, int) and isinstance(value, list) and 0 <= step < len(value):
+            value = value[step]
+        else:
+            return None
+    return value
+
+
+def with_value_at(value: Any, path: tuple[str | int, ...], new: Any) -> Any:
+    """A copy of ``value`` with ``new`` under ``path``.
+
+    Only the dicts and lists along the path are copied; everything else is shared.
+    """
+    if not path:
+        return new
+    step, rest = path[0], path[1:]
+    if isinstance(value, dict):
+        return {**value, step: with_value_at(value[step], rest, new)}
+    if not isinstance(step, int):
+        raise TypeError(f"a list is indexed by an int, not {step!r}")
+    copied = list(value)
+    copied[step] = with_value_at(copied[step], rest, new)
+    return copied
+
+
+def resolves_in_full(value: Any) -> bool:
+    """Whether a stored value holds its whole text: no truncation envelope inside it.
+
+    A reference to such a value, or an extension of it, gives a reader the full
+    value. An ``_extends`` envelope counts when its suffix survived; its base was
+    itself checked when it was stored.
+    """
+    if isinstance(value, dict):
+        if value.get("_truncated") is True:
+            return False
+        return all(resolves_in_full(v) for v in value.values())
+    if isinstance(value, list):
+        return all(resolves_in_full(v) for v in value)
+    return True

{cmpnd-0.84.0 → cmpnd-0.85.1}/docs/sdk-instrumentation.md

@@ -331,6 +331,18 @@ Each `_send_*` method routes a failed delivery to one of two counters: a `429` (
 
 Tolerating is never silent. A send that recovered logs a warning naming what it rode through (`rode through 3 transient responses over 12.4s (503=3) to POST /api/v1/traces`), and an exhausted budget raises `ExportRetriesExhausted` with the same count and window in its message. `BatchExporter.failure_summary()` reports the distribution of non-2xx statuses observed, how many transient answers were ridden through, and a sample error body — that's what the stress lane prints when it fails, so a red lane says *what* the wire answered rather than only how many errors there were.
 
+Trace delivery failures log at ERROR on `cmpnd.exporter`. The message names the
+operation and the number of records the exporter will not resend. HTTP failures
+include the status, route and serve's string `error`, `error_code`, `upgrade` and
+`field` values when present. The exporter bounds each value and escapes control
+characters. It omits other body fields and non-JSON responses. Exhausted retries
+include the last server message as well as the attempt count and elapsed time.
+
+A non-retryable 422 discards the submission. Upgrade the SDK when serve asks for
+it, then emit fresh telemetry. An upgrade cannot recover discarded records.
+Background failures keep the application running and increment the existing
+error counters. They do not raise an exception in the instrumented program.
+
 ### The retryable-error contract
 
 The server tells a client when a failed write is worth re-sending, in three signals carrying one fact:
@@ -1027,6 +1039,8 @@ The callback mints `source_observation_id` when the LM call starts and records `
 
 The LM span's `lm.finish_reason` attribute records why the model stopped, in the chat vocabulary serve's truncation warning reads. Each response shape spells it differently. Chat puts it on the first choice and DSPy 3.3's typed `LMResponse` on the first output. The lm15 `Response` a DSPy 3.4 engine returns carries it at the top level and names a tool-call stop `tool_call`, which the SDK records as `tool_calls`. The Responses API reports a `status`, and its `max_output_tokens` cutoff lands as `length`. `_finish_reason` in `python-sdk/cmpnd/callback.py` holds the mapping.
 
+An lm15 object in a span body, such as an LM call's `Request` and `Response` or an adapter's typed `Prompt`, is stored without its null and empty fields. A request's `config` holds eighteen settings that are null on almost every call, and every message and part holds an empty `continuation`. lm15's own serializer omits them, and `_compact_dataclass` in `python-sdk/cmpnd/models.py` does the same for lm15 types only. `0`, `False`, `""` and `provider_data` stay. A `Prompt` and a `Request` serialize their messages by the same rule, so the references in the next section still match.
+
 The LM span's other `lm.*` attributes copy only the LM kwargs that `SAFE_LM_KWARGS` in `python-sdk/cmpnd/helpers.py` names. These are the sampling and response-shape settings, such as `temperature` and `reasoning_effort`, and dspy.LM's own call settings, such as `num_retries`. Every member of the org can read a span. An LM's kwargs can also carry provider credentials under names no deny-list keeps up with, such as `aws_secret_access_key`, `azure_ad_token`, `vertex_credentials` and `extra_headers`. So the list names what may be copied, and a kwarg it does not name stays out. It also leaves out `api_base` and `base_url`, which name a destination. The `dspy.LM(...)` line in a programmatic deploy's generated source goes through the same list, because `dspy.LM.dump_state()` drops only `api_key`. The worker supplies the deployment's credential and destination itself.
 
 `CREDENTIAL_LM_KWARGS` in the same file names the credential arguments themselves: `api_key` and LiteLLM's others, such as `aws_secret_access_key`, `aws_session_token`, `vertex_credentials` and `azure_ad_token`. The callback strips each of them from an LM call's span inputs, so a key passed to the call itself, as in `lm(prompt, api_key=...)`, never reaches a span. A header in `extra_headers` or `headers` whose name carries `auth`, `key`, `token`, `secret`, `cookie` or `password`, such as `Authorization` or `x-api-key`, counts as a credential too, and the callback drops it while keeping a plain header such as `X-Title`. The same rules drive `cmpnd deploy FILE`'s import check and `cmpnd.Client.optimize_deployment`'s refusal of a keyed LM. `api_base` and `base_url` are not on it: an address holds nothing secret, and a program keeps its `api_base` for its laptop run.
@@ -1076,16 +1090,18 @@ A string that begins with a string an earlier span recorded is stored as an exte
 
 `field` is `inputs`, `outputs` or `attributes`, and `path` walks object keys and list indexes inside it. `_prefix_chars` counts code points. Like a truncation envelope, a reference carries only its marker keys. serve resolves references when it reads a trace (`serve/internal/platform/spanrefs`), so every reader sees the full value, and a reference serve cannot resolve renders as a truncation band naming the span.
 
+An adapter's `format` span stores its rendered prompt in one of two shapes. DSPy 3.4 and earlier render a list of `{role, content}` messages at `outputs.result`, and the LM call receives that list as `inputs.messages`. A DSPy with lm15 typed prompts renders a `Prompt` stored as `outputs.system` and `outputs.messages`, where each message holds `parts` and each text part holds `text`. Its LM call receives an lm15 `Request` whose `inputs.prompt.system` and `inputs.prompt.messages` hold the same values. `references.prompt_keys` and `references.prompt_text_leaves` read either shape.
+
 Where the SDK writes one:
 
-- **`lm_call.inputs.messages`** names the `adapter_format` span's `outputs.result`. `_AdapterMixin._remember_rendered_messages` keeps each `format` span's full rendered messages, keyed by its parent span. `_LMMixin._reference_rendered_messages` compares the LM's messages with them on the full values, before truncation, and writes the reference only when they are equal. Messages the adapter changed after rendering, an LM call with no adapter above it (an RLM `llm_query`), an adapter output that was not captured, and an adapter output truncated whole into a list envelope all keep a full copy.
-- **`adapter_format.outputs.result[i].content`** extends the same message of the previous `format` call by the same module instance in the trace. An RLM or ReAct turn renders the previous turn's prompt plus one step, so each turn stores only its new step and the trace grows linearly with its turns rather than quadratically. `_AdapterMixin._extend_previous_rendering` compares the full rendered content, before truncation, and writes `_extends` only when the shared prefix is at least `MIN_PREFIX_CHARS` (1024) code points and at least half the message; otherwise the message is stored whole. The base is the most recent rendering whose stored form resolves back to the full text: a message stored truncated is never a base, so a later turn extends the last one that was stored intact. A suffix larger than the field budget is stored truncated like any other string, and the next turn extends an earlier base instead. A different predictor, such as RLM's extract fallback, has no previous rendering and stores its prompt whole.
+- **The LM call's prompt** names the `adapter_format` span's output. In the list shape, `lm_call.inputs.messages` names `outputs.result`. In the typed shape, `lm_call.inputs.prompt.system` and `lm_call.inputs.prompt.messages` each name the same key of the outputs, and the rest of the request (`model`, `tools`, `config`) stays inline. `_AdapterMixin._remember_rendered_prompt` keeps each `format` span's full rendered prompt, keyed by its parent span, for every prompt key whose stored value resolves in full. `_LMMixin._reference_rendered_prompt` compares the LM's prompt with it on the full values, before truncation, and writes a reference for each key that is equal. Every LM call the adapter makes from one rendering gets the references. Messages the adapter changed after rendering, an LM call with no adapter above it (an RLM `llm_query`), an adapter output that was not captured, and an adapter output truncated into a list envelope all keep a full copy.
+- **Each text of an adapter rendering** extends the text at the same path in the previous `format` call by the same module instance in the trace. In the list shape that is `outputs.result[i].content`. In the typed shape it is `outputs.system` and `outputs.messages[i].parts[j].text`, so the system prompt, which is the same on every turn, stores as an extension with an empty suffix. An RLM or ReAct turn renders the previous turn's prompt plus one step, so each turn stores only its new step and the trace grows linearly with its turns rather than quadratically. `_AdapterMixin._extend_previous_rendering` compares the full rendered text, before truncation, and writes `_extends` only when the shared prefix is at least `MIN_PREFIX_CHARS` (1024) code points and at least half the text; otherwise the text is stored whole. A typed `system` made of content parts has no text leaf and stays whole. The base is the most recent rendering whose stored form resolves back to the full text: a text stored truncated is never a base, so a later turn extends the last one that was stored intact. A suffix larger than the field budget is stored truncated like any other string, and the next turn extends an earlier base instead. A different predictor, such as RLM's extract fallback, has no previous rendering and stores its prompt whole.
 
 A reference always names a span that ended before the referring span started, so the base has been exported when the reference is written, including on the streaming (RLM) path.
 
 The adapter span under an RLM turn also drops `repl_history` from its inputs and carries `thinned="true"`, the same thinning `on_module_end` applies to the turn's `Predict` span. The RLM span's `repl_history` attribute holds the trajectory once, and the adapter's rendered messages still hold the history the LM saw.
 
-`docs/schemas/span-references/vectors.json` holds the golden vectors. `tests/test_span_references.py` checks the SDK's emitter against them, and serve's `spanrefs` tests resolve them. `docs/schemas/span-references/rlm-30-turns.json.gz` is the SDK's own output for a 30-turn RLM run, with a digest of every prompt the LM received; serve ingests it into Postgres and checks each prompt resolves (`serve/internal/platform/pg/traces_spanrefs_integration_test.go`). `tests/span_reference_fixture.py` regenerates it, and `tests/test_span_references.py` fails when the committed copy is stale on the DSPy version `uv.lock` pins.
+`docs/schemas/span-references/vectors.json` holds the golden vectors. `tests/test_span_references.py` checks the SDK's emitter against them, and serve's `spanrefs` tests resolve them. `docs/schemas/span-references/rlm-30-turns.json.gz` is the SDK's own output for a 30-turn RLM run, with a digest of every prompt the LM received; serve ingests it into Postgres and checks each prompt resolves (`serve/internal/platform/pg/traces_spanrefs_integration_test.go`). `tests/span_reference_fixture.py` regenerates it, and `tests/test_span_references.py` fails when the committed copy is stale on the DSPy version `uv.lock` pins. `tests/test_lm15_prompt_references.py` drives the callback with typed prompts, because no DSPy in the test matrix renders them.
 
 ## Storability: what the SDK guarantees about the payloads it emits