cmpnd 0.18.0__tar.gz → 0.18.2__tar.gz

{cmpnd-0.18.0 → cmpnd-0.18.2}/PKG-INFO

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

{cmpnd-0.18.0 → cmpnd-0.18.2}/cmpnd/_rlm_patch.py

@@ -1,5 +1,17 @@
 """Emit tool spans for ``dspy.RLM`` tool calls.
 
+DEPRECATED: redundant on DSPy >= 3.3.0. DSPy 3.3.0 added
+``RLM._make_interpreter_tool``, which routes each user tool through
+``dspy.Tool.__call__`` (``@with_callbacks``), so DSPy's own path now fires the
+tool hooks this shim was written to supply, and the interpreter-callback
+instrumentation (``on_interpreter_tool_call_*``) synthesizes a span for the
+``llm_query`` builtins besides. On >= 3.3.0 this patch also *replaces* DSPy's
+path, discarding the pydantic kwarg coercion and async ``tool.acall`` routing
+DSPy intends. It stays active for backwards compatibility with older DSPy and
+because retiring it is a separable behavior change (user-tool kwargs would go
+back through DSPy's coercion); remove it once the supported DSPy floor is
+>= 3.3.0.
+
 cmpnd creates a ``TOOL`` span only from DSPy's ``on_tool_start``/``on_tool_end``
 callbacks, and those fire only through ``dspy.Tool.__call__`` (decorated
 ``@with_callbacks``). ``dspy.RLM._prepare_execution_tools`` hands the code

{cmpnd-0.18.0 → cmpnd-0.18.2}/cmpnd/callback.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import contextvars
 import logging
 from datetime import datetime, timezone
 from typing import Any
@@ -11,6 +12,16 @@ from . import configuration, context, eval_handler, exporter, helpers, identity,
 
 logger = logging.getLogger(__name__)
 
+# The interpreter tool-call frame active in the current execution context. A real
+# dspy.Tool fires on_tool_start synchronously inside the interpreter's invoke_tool,
+# so it reads this to mark its enclosing frame — per-thread and per-async-task,
+# unlike a callback-wide stack, so two RLM runs on different threads (e.g. under
+# dspy.Evaluate) cannot mark each other's frame. Default None means no interpreter
+# tool call is in scope, so an ordinary dspy.Tool (a ReAct action) marks nothing.
+_current_interpreter_tool_frame: contextvars.ContextVar[dict[str, Any] | None] = contextvars.ContextVar(
+    "cmpnd_interpreter_tool_frame", default=None
+)
+
 
 def trace_id(prediction: Any) -> str | None:
     """Return the cmpnd trace id for a prediction returned by an instrumented program.
@@ -51,6 +62,35 @@ def _get_dspy():
     return _dspy, _BaseCallback
 
 
+# Hook names already reported as unhandled, so the debug line below is one per
+# hook rather than one per dispatch.
+_reported_unhandled_hooks: set[str] = set()
+
+
+def _ignore_hook(*_args: Any, **_kwargs: Any) -> None:
+    """Stand in for a DSPy callback hook cmpnd does not instrument.
+
+    DSPy invokes a start hook as ``(call_id=, instance=, inputs=)`` and an end
+    hook as ``(call_id=, outputs=, exception=)``; accepting anything keeps this
+    correct for whatever shape a later hook takes.
+    """
+
+
+def _dspy_declares_hook(name: str) -> bool:
+    """Report whether the installed DSPy declares ``name`` on ``BaseCallback``.
+
+    Asking DSPy rather than matching a name pattern is what keeps the fallback
+    in :meth:`CmpndCallback.__getattr__` narrow: it absorbs the hooks DSPy
+    actually dispatches and nothing else. When dspy is absent the answer is no
+    — nothing is dispatching callbacks in that case.
+    """
+    try:
+        _, base = _get_dspy()
+    except ImportError:
+        return False
+    return callable(getattr(base, name, None))
+
+
 def _cached_prompt_tokens(usage: Any) -> int:
     """Read the provider-side prompt-cache read count off a LiteLLM usage dict.
 
@@ -161,6 +201,21 @@ class _CallbackBase:
         # Track which traces use streaming export (thread-safe lookup for child spans)
         self._streaming_traces: dict[str, bool] = {}
 
+        # In-flight interpreter tool-call frames, keyed by DSPy call_id (unique per
+        # call, so this map is thread-safe the way _call_id_to_span is). An
+        # interpreter tool call fires on_interpreter_tool_call_*, and a real
+        # dspy.Tool fires an on_tool_* pair nested inside it; the frame lets the
+        # tool_call end suppress its own synthesized span when a real tool span
+        # already covered the call. Which frame a nested on_tool_start marks is
+        # carried by the _current_interpreter_tool_frame contextvar, not by this
+        # map, so overlapping runs on different threads stay isolated. See
+        # _InterpreterMixin.
+        self._interpreter_tool_frames: dict[str, dict[str, Any]] = {}
+
+        # call_id -> start time for interpreter startup/shutdown, whose duration
+        # folds into an attribute on the enclosing span rather than its own span.
+        self._interpreter_lifecycle_starts: dict[str, datetime] = {}
+
         # Ensure exporter is running
         exporter.ensure_exporter_started()
 
@@ -1014,6 +1069,14 @@ class _ToolMixin(_CallbackBase):
         if tool_name == "finish":
             return
 
+        # A real dspy.Tool span is firing beneath an interpreter tool call, so the
+        # tool_call end must not synthesize its own row for the same call. Mark the
+        # frame active in THIS execution context (the contextvar), not a global
+        # stack top, so a concurrent run on another thread is unaffected.
+        active_frame = _current_interpreter_tool_frame.get()
+        if active_frame is not None:
+            active_frame["had_real_tool"] = True
+
         span = context.create_child_span(f"Tool.{tool_name}", models.SpanType.TOOL)
 
         # Tool-specific attributes
@@ -1071,7 +1134,214 @@ class _ToolMixin(_CallbackBase):
                 exp.export_span(span)
 
 
-class CmpndCallback(_ModuleMixin, _LMMixin, _AdapterMixin, _ToolMixin):
+class _InterpreterMixin(_CallbackBase):
+    """DSPy CodeInterpreter callbacks — one span per REPL code execution.
+
+    DSPy >=3.3.1 decorates ``PythonInterpreter.execute`` with ``@with_callbacks``,
+    so a module that runs code in the interpreter — ``RLM``, ``ProgramOfThought``,
+    ``CodeAct``, ``Flex``, every module reaching it through ``_create_interpreter``
+    — dispatches ``on_interpreter_execute_start`` / ``on_interpreter_execute_end``
+    around each cell. One ``interpreter_execute`` span records the cell: the code
+    in, its captured stdout out, wall time, and the error type when the cell
+    raised. The ``SUBMIT()`` result comes back wrapped in ``FinalOutput``, recorded
+    distinctly from stdout so a reader can tell the run's answer from a cell's
+    print output.
+    """
+
+    def on_interpreter_execute_start(
+        self,
+        call_id: str,
+        instance: Any,
+        inputs: dict[str, Any],
+    ) -> None:
+        """Handle a CodeInterpreter code execution start — one REPL cell."""
+        # An interpreter event with no active trace and no active span — a pooled
+        # pre-warm, or a caller-owned interpreter used outside a program call —
+        # has no span to attach to and no trace to root, so drop it.
+        if context.get_current_trace() is None and context.get_current_span() is None:
+            return
+
+        span = context.create_child_span(f"{instance.__class__.__name__}.execute", models.SpanType.INTERPRETER_EXECUTE)
+
+        if self._capture_inputs:
+            code = inputs.get("code")
+            if code is not None:
+                span.set_inputs({"code": helpers.truncate_field(code, self._max_input_field_size, depth=1)})
+
+        self._call_id_to_span[call_id] = span
+        context.push_span(span)
+
+    def on_interpreter_execute_end(
+        self,
+        call_id: str,
+        outputs: Any | None,
+        exception: BaseException | None = None,
+    ) -> None:
+        """Handle a CodeInterpreter code execution end."""
+        span = self._call_id_to_span.pop(call_id, None)
+        if not span:
+            return
+
+        span.end_time = datetime.now(timezone.utc)
+
+        if exception:
+            span.set_error(exception)
+        else:
+            span.status = models.TraceStatus.OK
+            if self._capture_outputs and outputs is not None:
+                # execute() returns FinalOutput(...) for a SUBMIT() cell and the
+                # captured stdout string for an ordinary cell. Record the two
+                # distinctly: FinalOutput carries the run's answer, stdout the
+                # cell's print output.
+                if type(outputs).__name__ == "FinalOutput":
+                    final = getattr(outputs, "output", outputs)
+                    span.set_outputs({"final_output": helpers.truncate_outputs(final, self._max_output_field_size)})
+                    span.attributes["interpreter.submitted"] = "true"
+                else:
+                    span.set_outputs({"stdout": helpers.truncate_outputs(outputs, self._max_output_field_size)})
+
+        context.pop_span()
+        self._track_span(span)
+
+        if self._should_stream_span(span):
+            exp = exporter.get_exporter()
+            if exp:
+                exp.export_span(span)
+
+    def on_interpreter_tool_call_start(
+        self,
+        call_id: str,
+        instance: Any,
+        inputs: dict[str, Any],
+    ) -> None:
+        """Handle a tool call made from interpreter code (invoke_tool).
+
+        A frame is opened but no span is created yet: a real dspy.Tool nested in
+        this call emits its own TOOL span (nested under the enclosing execute
+        span, the current top of the stack), and the end handler synthesizes a
+        TOOL span only when no real tool span covered the call — the case of a
+        builtin like llm_query, which fires no tool hook.
+        """
+        del instance  # DSPy keyword-calls this hook; the interpreter instance is unused
+        if context.get_current_trace() is None and context.get_current_span() is None:
+            return
+        frame: dict[str, Any] = {
+            "tool_name": inputs.get("tool_name", "unknown"),
+            "inputs": inputs.get("kwargs", {}),
+            "had_real_tool": False,
+            "parent_span": context.get_current_span(),
+            "start_time": datetime.now(timezone.utc),
+        }
+        self._interpreter_tool_frames[call_id] = frame
+        # Publish this frame as the one a nested on_tool_start marks, in this
+        # context only. The token restores the prior frame (nested tool calls) on
+        # end; DSPy runs start and end on the same thread/task, so reset is valid.
+        frame["_cv_token"] = _current_interpreter_tool_frame.set(frame)
+
+    def on_interpreter_tool_call_end(
+        self,
+        call_id: str,
+        outputs: Any | None,
+        exception: BaseException | None = None,
+    ) -> None:
+        """Close an interpreter tool-call frame; synthesize a TOOL span if needed."""
+        frame = self._interpreter_tool_frames.pop(call_id, None)
+        if frame is None:
+            return
+        token = frame.pop("_cv_token", None)
+        if token is not None:
+            try:
+                _current_interpreter_tool_frame.reset(token)
+            except ValueError:
+                # Reset from a different context than the set (should not happen —
+                # DSPy pairs start/end on one thread); leave the contextvar as is.
+                pass
+
+        # A real dspy.Tool already emitted its span for this call; one TOOL span
+        # is enough, so suppress the synthesized row.
+        if frame["had_real_tool"]:
+            return
+
+        # A real dspy.Tool already emitted its span for this call; one TOOL span
+        # is enough, so suppress the synthesized row.
+        if frame["had_real_tool"]:
+            return
+
+        # A builtin (llm_query / llm_query_batched) fired no tool hook, so give it
+        # the visibility it would otherwise lack: a synthesized TOOL span.
+        parent = frame["parent_span"]
+        span = models.SpanBuilder(
+            span_id=uuid4(),
+            trace_id=parent.trace_id if parent else None,
+            name=f"Tool.{frame['tool_name']}",
+            span_type=models.SpanType.TOOL,
+            parent_span_id=parent.span_id if parent else None,
+            start_time=frame["start_time"],
+        )
+        span.attributes["tool.name"] = str(frame["tool_name"])
+        span.attributes["tool.synthesized"] = "true"
+
+        if self._capture_inputs and frame["inputs"]:
+            span.set_inputs(
+                helpers.clean_inputs({"kwargs": frame["inputs"]}, _get_dspy()[0], self._max_input_field_size)
+            )
+
+        span.end_time = datetime.now(timezone.utc)
+        if exception:
+            span.set_error(exception)
+        else:
+            span.status = models.TraceStatus.OK
+            if self._capture_outputs and outputs is not None:
+                span.set_outputs(helpers.truncate_outputs(outputs, self._max_output_field_size))
+
+        self._track_span(span)
+        if self._should_stream_span(span):
+            exp = exporter.get_exporter()
+            if exp:
+                exp.export_span(span)
+
+    def on_interpreter_startup_start(self, call_id: str, instance: Any, inputs: dict[str, Any]) -> None:
+        """Mark interpreter startup (Deno spawn + Pyodide boot) start."""
+        del instance, inputs  # DSPy keyword-calls this hook; only call_id is needed
+        self._interpreter_lifecycle_starts[call_id] = datetime.now(timezone.utc)
+
+    def on_interpreter_startup_end(
+        self, call_id: str, outputs: Any | None, exception: BaseException | None = None
+    ) -> None:
+        """Fold interpreter cold-start duration into the enclosing span."""
+        del outputs, exception  # a lifecycle event carries no outputs to record
+        self._fold_lifecycle_duration(call_id, "interpreter.startup_ms")
+
+    def on_interpreter_shutdown_start(self, call_id: str, instance: Any, inputs: dict[str, Any]) -> None:
+        """Mark interpreter shutdown start."""
+        del instance, inputs  # DSPy keyword-calls this hook; only call_id is needed
+        self._interpreter_lifecycle_starts[call_id] = datetime.now(timezone.utc)
+
+    def on_interpreter_shutdown_end(
+        self, call_id: str, outputs: Any | None, exception: BaseException | None = None
+    ) -> None:
+        """Fold interpreter shutdown duration into the enclosing span."""
+        del outputs, exception  # a lifecycle event carries no outputs to record
+        self._fold_lifecycle_duration(call_id, "interpreter.shutdown_ms")
+
+    def _fold_lifecycle_duration(self, call_id: str, attr: str) -> None:
+        """Record a lifecycle event's duration as an attribute on the enclosing span.
+
+        No span of its own — two lifecycle rows per RLM turn would bury the tree.
+        An event with no enclosing span (a pooled pre-warm, or a shutdown after the
+        program call already ended) is dropped: it has nothing to attach to.
+        """
+        start = self._interpreter_lifecycle_starts.pop(call_id, None)
+        if start is None:
+            return
+        span = context.get_current_span()
+        if span is None:
+            return
+        ms = (datetime.now(timezone.utc) - start).total_seconds() * 1000
+        span.attributes[attr] = f"{ms:.1f}"
+
+
+class CmpndCallback(_ModuleMixin, _LMMixin, _AdapterMixin, _ToolMixin, _InterpreterMixin):
     """
     DSPy callback for cmpnd observability.
 
@@ -1086,6 +1356,29 @@ class CmpndCallback(_ModuleMixin, _LMMixin, _AdapterMixin, _ToolMixin):
         >>> dspy.configure(callbacks=[cmpnd.CmpndCallback()])
     """
 
+    def __getattr__(self, name: str) -> Any:
+        """Absorb the DSPy callback hooks this SDK does not instrument.
+
+        DSPy resolves a handler with a bare ``getattr(callback, "on_…")`` and
+        has no guard for a callback that omits one, so every hook DSPy adds
+        turns each dispatch into an ``AttributeError`` it catches and logs as a
+        warning — one per interpreter call, one per ``compile()``. DSPy 3.3.1
+        added ten that way (``on_interpreter_*`` for the code interpreter,
+        ``on_compile_*`` for optimizers), and later releases will add more.
+
+        So answer any hook the installed DSPy declares with a no-op instead of
+        chasing its releases. Names DSPy does not declare still raise, which
+        keeps a misspelled handler here an error rather than a silent no-op.
+        This sits on the leaf class rather than ``_CallbackBase`` so the mixins,
+        where the instrumented handlers live, keep strict attribute checking.
+        """
+        if name.startswith("on_") and _dspy_declares_hook(name):
+            if name not in _reported_unhandled_hooks:
+                _reported_unhandled_hooks.add(name)
+                logger.debug("DSPy callback hook %s is not instrumented by cmpnd; ignoring it.", name)
+            return _ignore_hook
+        raise AttributeError(f"{type(self).__name__!r} object has no attribute {name!r}")
+
     def on_evaluate_start(
         self,
         call_id: str,

{cmpnd-0.18.0 → cmpnd-0.18.2}/cmpnd/cli/trace_render.py

@@ -76,6 +76,7 @@ _SPAN_LABELS = {
     "module": "Module",
     "retrieve": "Retrieve",
     "tool": "Tool",
+    "interpreter_execute": "Interpreter",
     "chain_of_thought": "Chain of Thought",
     "react": "ReAct",
     "program_of_thought": "Program of Thought",

{cmpnd-0.18.0 → cmpnd-0.18.2}/cmpnd/models.py

@@ -397,6 +397,7 @@ class SpanType(str, Enum):
     ADAPTER_FORMAT = "adapter_format"
     ADAPTER_PARSE = "adapter_parse"
     TOOL = "tool"
+    INTERPRETER_EXECUTE = "interpreter_execute"
     SIGNATURE_VALIDATE = "signature_validate"
     DEMO_SELECT = "demo_select"
     OPTIMIZATION = "optimization"
@@ -501,8 +502,13 @@ class SpanBuilder:
         """Set a span attribute."""
         self.attributes[key] = str(value)
 
-    def set_error(self, exception: Exception) -> None:
-        """Mark span as errored."""
+    def set_error(self, exception: BaseException) -> None:
+        """Mark span as errored.
+
+        Accepts any ``BaseException``: DSPy's ``@with_callbacks`` catches
+        ``BaseException`` and hands it to an end hook, so an interpreter cell that
+        raised a non-``Exception`` still errors its span rather than being lost.
+        """
         self.status = TraceStatus.ERROR
         self.error_message = str(exception)
         self.error_type = exception.__class__.__name__

{cmpnd-0.18.0 → cmpnd-0.18.2}/cmpnd/optimization.py

@@ -412,6 +412,15 @@ def _lms_config(config: dict[str, Any], lms: Any) -> None:
     ``lms`` is untyped here where :func:`optimize` annotates it, because this is the layer
     that answers what a caller actually passed: an SDK user runs no typechecker of ours,
     so the shape checks below are the ones that fire.
+
+    **A name is declared exactly as it is written, and a padded one is refused rather than
+    corrected.** Every layer below this one trims — serve's `lmBindingSet`, the optimizer's,
+    and both workers' — so a binding declared as ``" critic"`` would be resolved, granted,
+    minted for and served consistently under ``"critic"``, and the only thing left wrong
+    would be the author's own ``lms[" critic"]`` in the metric, raising mid-run against a
+    set whose entries look identical to what they typed. Trimming it here would agree with
+    the wire and keep that mismatch; naming it here is the corrected line before the bundle
+    is built, which is the whole cost the binding design exists to avoid.
     """
     if lms is None:
         return
@@ -430,8 +439,16 @@ def _lms_config(config: dict[str, Any], lms: Any) -> None:
 
     declared: dict[str, Any] = {}
     for name, lm in lms.items():
-        if not isinstance(name, str) or not name:
+        if not isinstance(name, str) or not name.strip():
             raise ValueError(f"an LM binding's name must be a non-empty string (got {name!r})")
+        if name != name.strip():
+            raise ValueError(
+                f"the LM binding name {name!r} is padded with whitespace, and every layer "
+                f"below this one trims it — so the run would deploy, dispatch and roll out "
+                f"under {name.strip()!r}, and a metric written to match, asking for "
+                f"lms[{name!r}], would raise mid-run against a set whose entries look "
+                f"identical to what you typed. Declare it as {name.strip()!r}"
+            )
         if name == DEFAULT_LM_BINDING:
             raise ValueError(
                 f"{DEFAULT_LM_BINDING!r} is the name the platform reserves for the program's own "

{cmpnd-0.18.0 → cmpnd-0.18.2}/docs/sdk-instrumentation.md

@@ -30,7 +30,7 @@ If you want to instrument manually (for example, to wire the callback into a non
 
 ## The callback
 
-`python-sdk/cmpnd/callback.py` implements `CmpndCallback`, a subclass of `dspy.utils.callback.BaseCallback`. DSPy calls its hook methods synchronously on whatever thread is executing the module. The callback owns no long-lived state beyond a per-call span builder map; everything trace/span related flows through context vars (see next section).
+`python-sdk/cmpnd/callback.py` implements `CmpndCallback`, which satisfies `dspy.utils.callback.BaseCallback` without inheriting it — `callback.py` must import on the standard library alone (`tests/test_import_weight.py`), so it cannot import dspy to get a base class. DSPy calls its hook methods synchronously on whatever thread is executing the module. The callback owns no long-lived state beyond a per-call span builder map; everything trace/span related flows through context vars (see next section).
 
 The hook methods, in the order you'd expect them to fire for a typical `dspy.ChainOfThought` call:
 
@@ -38,8 +38,22 @@ The hook methods, in the order you'd expect them to fire for a typical `dspy.Cha
 - **LM calls** — `on_lm_start` (`callback.py:448`) / `on_lm_end` (`callback.py:498`) wrap the actual provider call. These are where token counts, cost, model name, and the raw prompt get attached. `capture_prompts` (`config.py:29`) controls whether the prompt payload is recorded.
 - **Adapter format/parse** — `on_adapter_format_start` / `_end` and `on_adapter_parse_start` / `_end` (`callback.py:604`–`631`). Both route through shared helpers `_start_adapter_span` (`callback.py:640`) and `_end_adapter_span` (`callback.py:664`). Adapter spans have their raw inputs/outputs stripped in `models.py` — see `_ADAPTER_SPAN_TYPES` handling in `python-sdk/cmpnd/models.py:177` — because the same content already appears on the enclosing LM span.
 - **Tools** — `on_tool_start` (`callback.py:700`) / `on_tool_end` (`callback.py:733`). One span per `dspy.Tool` invocation, with the tool's args as inputs.
+- **Interpreter (code execution)** — `_InterpreterMixin` (`callback.py:1119`), for the DSPy `CodeInterpreter` hooks DSPy >= 3.3.1 fires around a program running code in the interpreter (`RLM`, `ProgramOfThought`, `CodeAct`, `Flex` — every module reaching it through `_create_interpreter`; `ReAct` / `ReActV2` use no interpreter and fire none). `on_interpreter_execute_start` / `_end` emit one `INTERPRETER_EXECUTE` span per REPL cell — the code in, its captured stdout out, and the `SUBMIT()` result (a DSPy `FinalOutput`) recorded distinctly from stdout. `on_interpreter_tool_call_start` / `_end` synthesize a `TOOL` span for a tool called from interpreter code **only when no real `dspy.Tool` span covered the call** (a user tool routes through `Tool.__call__` and fires `on_tool_*`, so its row is suppressed to avoid a duplicate; the `llm_query` builtins fire no tool hook, so they get the synthesized span). `on_interpreter_startup_*` / `on_interpreter_shutdown_*` emit no span — their duration folds into an `interpreter.startup_ms` / `interpreter.shutdown_ms` attribute on the enclosing span, and an event with no enclosing span (a pooled pre-warm) is dropped.
 - **Evaluate** — `on_evaluate_start` (`callback.py:773`) / `on_evaluate_end` (`callback.py:782`). These are thin forwarders that delegate to `EvalHandler` (see "Eval handling" below).
 
+Not inheriting the base class costs the free no-op every hook would otherwise
+have. DSPy resolves a handler with a bare `getattr(callback, "on_…")` and does
+not guard for a callback that omits one, so a DSPy release that adds hooks turns
+each dispatch into an `AttributeError` DSPy catches and logs as a warning — DSPy
+3.3.1 added ten (the eight `on_interpreter_*` for the code interpreter, now
+instrumented by `_InterpreterMixin`, and `on_compile_*` for optimizers, which the
+SDK still does not instrument). `CmpndCallback.__getattr__` closes that: any hook
+the installed DSPy declares on `BaseCallback` and this SDK does not instrument
+resolves to a no-op,
+and every other name still raises. `TestDspyHookCoverage` in
+`tests/test_callback.py` asserts the coverage against whatever DSPy is installed,
+so the next release that adds a hook is caught by CI rather than by a user's logs.
+
 ### Signature extraction and signature_hash
 
 This doc does not re-derive hash semantics — see [`./clustering.md`](../../docs/CLUSTERING.md) for why `signature_hash` exists and how xxhash maps to a signed Int64. Here's only _where_ it gets attached:
@@ -60,7 +74,8 @@ Both code paths import from `python-sdk/cmpnd/identity.py`, which is the authori
 | Module-ish    | `MODULE`, `PREDICT`, `CHAIN_OF_THOUGHT`, `REACT`, `RLM`, `RETRIEVE` | `on_module_start` fires. The concrete type is chosen by `_get_span_type_for_module` at `callback.py:793`.       |
 | LM            | `LM_CALL`                                                         | `on_lm_start` fires — one per provider round-trip.                                                             |
 | Adapter       | `ADAPTER_FORMAT`, `ADAPTER_PARSE`                                 | DSPy's adapter serializes the prompt or parses the response.                                                   |
-| Tool          | `TOOL`                                                            | `dspy.Tool` is invoked (typically inside a ReAct loop).                                                        |
+| Tool          | `TOOL`                                                            | `dspy.Tool` is invoked (inside a ReAct loop), or synthesized for a builtin called from interpreter code.       |
+| Interpreter   | `INTERPRETER_EXECUTE`                                             | `on_interpreter_execute_start` fires — one per REPL code cell a code-executing module runs (`_InterpreterMixin`). |
 | Eval/optimize | `EVALUATION`, `OPTIMIZATION`                                      | Created by `EvalHandler` and the optimization tracker, not by the normal module hooks.                        |
 | Other         | `SIGNATURE_VALIDATE`, `DEMO_SELECT`, `UNKNOWN`                    | Reserved for edge cases and custom spans that don't fit another bucket.                                        |
 

{cmpnd-0.18.0 → cmpnd-0.18.2}/pyproject.toml

@@ -5,7 +5,7 @@ name = "cmpnd"
 # it's new) — no git tags. Bump with `uv version --bump {minor,patch}` or by
 # hand. Runtime `cmpnd.__version__` reads installed metadata, so it tracks
 # this automatically. See docs/plans/2026-07-02-sdk-pypi-tag-free-publish.md.
-version = "0.18.0"
+version = "0.18.2"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.10"

cmpnd-0.18.2/stubs/dspy/utils/callback.pyi

@@ -0,0 +1,40 @@
+"""Stubs for dspy.utils.callback.BaseCallback — the callback protocol
+cmpnd.callback.CmpndCallback implements. It does not inherit this class:
+callback.py must import without dspy, so it satisfies the protocol
+structurally and absorbs hooks it does not instrument via __getattr__.
+Declared here are the hooks cmpnd implements; DSPy's full set is larger.
+
+End hooks take ``exception: BaseException | None`` because DSPy's
+``@with_callbacks`` catches ``BaseException`` and hands it to the end hook — a
+cell that raised a non-``Exception`` (KeyboardInterrupt, SystemExit) still
+reaches the handler, so the stub matches the dispatch rather than a narrower
+``Exception``.
+"""
+
+from typing import Any
+
+class BaseCallback:
+    def on_module_start(self, call_id: str, instance: Any, inputs: dict[str, Any]) -> None: ...
+    def on_module_end(self, call_id: str, outputs: Any, exception: BaseException | None = ...) -> None: ...
+    def on_lm_start(self, call_id: str, instance: Any, inputs: dict[str, Any]) -> None: ...
+    def on_lm_end(self, call_id: str, outputs: Any, exception: BaseException | None = ...) -> None: ...
+    def on_adapter_format_start(self, call_id: str, instance: Any, inputs: dict[str, Any]) -> None: ...
+    def on_adapter_format_end(self, call_id: str, outputs: Any, exception: BaseException | None = ...) -> None: ...
+    def on_adapter_parse_start(self, call_id: str, instance: Any, inputs: dict[str, Any]) -> None: ...
+    def on_adapter_parse_end(self, call_id: str, outputs: Any, exception: BaseException | None = ...) -> None: ...
+    def on_tool_start(self, call_id: str, instance: Any, inputs: dict[str, Any]) -> None: ...
+    def on_tool_end(self, call_id: str, outputs: Any, exception: BaseException | None = ...) -> None: ...
+    def on_evaluate_start(self, call_id: str, instance: Any, inputs: dict[str, Any]) -> None: ...
+    def on_evaluate_end(self, call_id: str, outputs: Any, exception: BaseException | None = ...) -> None: ...
+    def on_interpreter_execute_start(self, call_id: str, instance: Any, inputs: dict[str, Any]) -> None: ...
+    def on_interpreter_execute_end(self, call_id: str, outputs: Any, exception: BaseException | None = ...) -> None: ...
+    def on_interpreter_tool_call_start(self, call_id: str, instance: Any, inputs: dict[str, Any]) -> None: ...
+    def on_interpreter_tool_call_end(
+        self, call_id: str, outputs: Any, exception: BaseException | None = ...
+    ) -> None: ...
+    def on_interpreter_startup_start(self, call_id: str, instance: Any, inputs: dict[str, Any]) -> None: ...
+    def on_interpreter_startup_end(self, call_id: str, outputs: Any, exception: BaseException | None = ...) -> None: ...
+    def on_interpreter_shutdown_start(self, call_id: str, instance: Any, inputs: dict[str, Any]) -> None: ...
+    def on_interpreter_shutdown_end(
+        self, call_id: str, outputs: Any, exception: BaseException | None = ...
+    ) -> None: ...

{cmpnd-0.18.0 → cmpnd-0.18.2}/tests/e2e/fake_lm.py

@@ -96,6 +96,68 @@ def react_responder(tool_name: str, tool_args: dict[str, Any], answer: str = "fa
     return respond
 
 
+def rlm_responder(cells: Sequence[str], answer: str) -> Responder:
+    """A stateful responder that scripts a ``dspy.RLM`` code trajectory.
+
+    RLM's per-turn signature declares ``reasoning``/``code``; the model returns a
+    ```python block that RLM's real interpreter executes, and the run ends when
+    the code calls ``SUBMIT(...)``. This scripts that loop deterministically —
+    no real model deciding what code to write — so a real interpreter run
+    (``execute`` / ``invoke_tool`` callbacks, `interpreter_execute` spans) can be
+    exercised with the fake LM instead of a paid one.
+
+    ``cells`` is the code for iterations 1..N, run in order; after the last cell
+    the responder emits ``SUBMIT(answer=...)`` so the run terminates rather than
+    burning ``max_iters``. Each code string is wrapped in the ```python fence RLM
+    asks for, so pass bare Python. The current iteration is read from the prompt's
+    ``[[ ## iteration ## ]]`` block, so the trajectory advances on its own.
+
+    The forced-extract turn RLM runs if it never SUBMITs declares the program's
+    own output fields instead of ``code``; that turn gets ``answer``.
+
+    Construct a fresh responder per test (the iteration is read from the prompt,
+    but keep one responder to one scripted program for clarity).
+    """
+    iteration_re = re.compile(r"\[\[ ## iteration ## \]\]\n(\d+)")
+
+    def respond(messages: list[dict[str, Any]], fields: list[str]) -> dict[str, str]:
+        if "code" not in fields:  # the forced-extract turn asks for the real outputs
+            return {field: answer for field in fields}
+        last_user = next((m.get("content", "") for m in reversed(messages) if m.get("role") == "user"), "")
+        match = iteration_re.search(last_user)
+        iteration = int(match.group(1)) if match else 1
+        code = cells[iteration - 1] if iteration <= len(cells) else f"SUBMIT(answer={answer!r})"
+        return {"reasoning": f"step {iteration}", "code": f"```python\n{code}\n```"}
+
+    return respond
+
+
+def pot_responder(code: str, answer: str) -> Responder:
+    """A responder that scripts a ``dspy.ProgramOfThought`` run.
+
+    PoT drives three predictors: ``code_generate`` (outputs ``reasoning`` /
+    ``generated_code`` — the code its real interpreter runs), ``code_regenerate``
+    (same fields, on an execution error), and ``generate_output`` (outputs
+    ``reasoning`` / ``answer`` from the code's captured output). This scripts them
+    deterministically so a non-RLM code-executing module exercises the same real
+    interpreter path (``execute`` callbacks, ``interpreter_execute`` spans) as
+    ``rlm_responder`` does for RLM — the end-to-end proof that the interpreter
+    instrumentation is module-independent.
+
+    ``code`` is wrapped in the ```python fence PoT parses, so pass bare Python
+    that prints its result; ``answer`` is returned once the code has run.
+    """
+
+    def respond(messages: list[dict[str, Any]], fields: list[str]) -> dict[str, str]:
+        if "generated_code" in fields:
+            return {"reasoning": "compute the result", "generated_code": f"```python\n{code}\n```"}
+        if "answer" in fields:
+            return {"reasoning": "the code produced the result", "answer": answer}
+        return {field: answer for field in fields}
+
+    return respond
+
+
 def lift_responder(
     golds: dict[str, str],
     trainset_inputs: set[str],