cmpnd 0.26.0__tar.gz → 0.26.1__tar.gz

{cmpnd-0.26.0 → cmpnd-0.26.1}/PKG-INFO

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

{cmpnd-0.26.0 → cmpnd-0.26.1}/docs/sdk-instrumentation.md

@@ -412,9 +412,13 @@ Every session opened this way lives on one background thread and loop
 binds to the loop it was opened on, and `dspy.Tool.__call__` runs an async tool
 body under `asyncio.run` — a fresh loop — whenever none is already running.
 
-### Loose spans vs bundled traces
+### A span is sent exactly once
 
-A span can arrive at `_flush_batch` before its parent trace has been exported — this happens whenever the exporter ticks in the middle of a DSPy call. The exporter holds those loose spans in `self._pending_spans` (`exporter_http.py:122`) keyed by `trace_id`, and when the trace finally arrives it attaches the buffered spans before shipping. Spans for which the trace never arrives get flushed as a bare spans batch via `/api/v1/traces/:id/spans` — see `_send_spans` at `exporter_http.py:637`.
+`_flush_batch` picks one route per span and no producer can make both happen. When a flush carries a trace's own `trace` item, that trace's loose `span` items ride its body (`POST /api/v1/traces`) and the spans route is not called for them; a span is folded in only when the body does not already carry its `span_id`, because `TraceRecord.to_api_dict` already serialises the trace's `_batch_spans`. A span whose trace is not in the flush — an orphan, or a span the callback streams while its trace is still running — goes to `/api/v1/traces/:id/spans` and nowhere else.
+
+The flush is the only place that decides, and it decides per flush with no buffer carried between them: both routes write the same trace's rows, so a span on both at once is two concurrent writers over one trace, and double upload for whoever pays for the bandwidth.
+
+Two producers put a `span` item and its trace's `trace` item in the same flush. `cmpnd.start_span` / `@cmpnd.trace` export the span they close directly, and the callback's `_should_stream_span` streams a span whose trace it has no record of. Neither has to know about the other.
 
 ### In-progress trace starts (CMP-257)
 

{cmpnd-0.26.0 → cmpnd-0.26.1}/ingest/cmpnd_ingest/exporter_http.py

@@ -306,10 +306,6 @@ class BatchExporter:
         # fresh lock mid-restart would let a second thread in immediately.
         self._restart_lock = threading.Lock()
 
-        # Buffer spans by trace_id until trace arrives
-        self._pending_spans: dict[str, list[dict[str, Any]]] = {}
-        self._pending_spans_lock = threading.Lock()
-
         # Stats (guarded by _stats_lock for thread-safe parallel dispatch)
         self._exported_count = 0
         self._dropped_count = 0
@@ -438,8 +434,6 @@ class BatchExporter:
 
         self._sync_client_lock = threading.Lock()
         self._stats_lock = threading.Lock()
-        self._pending_spans_lock = threading.Lock()
-        self._pending_spans = {}
 
         self._flush_cond = threading.Condition()
         self._flush_requested_gen = 0
@@ -1138,7 +1132,6 @@ class BatchExporter:
         trace_starts: list[tuple[str, dict[str, Any]]] = []
         trace_finalizes: list[tuple[str, dict[str, Any]]] = []
         spans_by_trace: dict[str, list[dict[str, Any]]] = {}
-        new_spans: dict[str, list[dict[str, Any]]] = {}
 
         for item in batch:
             if item.item_type == "trace":
@@ -1170,9 +1163,6 @@ class BatchExporter:
                     logger.warning("Dropping span without trace_id")
                     continue
                 spans_by_trace.setdefault(trace_id, []).append(span_dict)
-                if trace_id not in new_spans:
-                    new_spans[trace_id] = []
-                new_spans[trace_id].append(span_dict)
 
         # Coalesce start + batch within one flush: if a trace's full
         # batch trace is in this same flush, sending it upserts the row to its
@@ -1185,23 +1175,31 @@ class BatchExporter:
             batched_ids = {str(t.get("trace_id")) for t in traces_to_send}
             trace_starts = [pair for pair in trace_starts if pair[0] not in batched_ids]
 
-        # Add new spans to pending buffer
-        with self._pending_spans_lock:
-            for trace_id, spans in new_spans.items():
-                if trace_id not in self._pending_spans:
-                    self._pending_spans[trace_id] = []
-                self._pending_spans[trace_id].extend(spans)
-
-        # Attach buffered spans to traces
+        # A span is sent exactly once. When its trace ships in this same flush it
+        # rides that trace's body and is taken off the spans route; otherwise the
+        # spans route is the only way it reaches the server. This is the one
+        # place that decides, so no producer can make both happen.
+        #
+        # Sending it twice is not merely wasteful upload: POST /traces and
+        # POST /traces/{id}/spans write the same trace's rows, so a span on both
+        # routes at once is two concurrent writers racing over one trace — the
+        # shape the server has to be lock-ordered against. Not emitting the pair
+        # is the SDK's half of that.
+        #
+        # A trace's own spans are already in its body (TraceRecord.to_api_dict
+        # serialises them), so a span is folded in only when the body does not
+        # already carry its span_id.
         for trace_dict in traces_to_send:
             trace_id = str(trace_dict.get("trace_id"))
-            with self._pending_spans_lock:
-                buffered_spans = self._pending_spans.pop(trace_id, [])
-            if buffered_spans:
-                existing = trace_dict.get("spans", [])
-                trace_dict["spans"] = existing + buffered_spans
-            elif "spans" not in trace_dict:
-                trace_dict["spans"] = []
+            body_spans = list(trace_dict.get("spans") or [])
+            carried = {str(span.get("span_id")) for span in body_spans}
+            for span_dict in spans_by_trace.pop(trace_id, []):
+                span_id = str(span_dict.get("span_id"))
+                if span_id in carried:
+                    continue
+                carried.add(span_id)
+                body_spans.append(span_dict)
+            trace_dict["spans"] = body_spans
 
         # --- Phase 2: Parallel dispatch ---
 

{cmpnd-0.26.0 → cmpnd-0.26.1}/pyproject.toml

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

{cmpnd-0.26.0 → cmpnd-0.26.1}/tests/test_exporter.py

@@ -339,25 +339,92 @@ def test_exporter_sends_trace_finalize():
     assert payload["total_tokens"] == 100
 
 
-def test_exporter_old_trace_path_still_works():
-    """The old trace item type should still work with pending spans."""
+# ---------------------------------------------------------------------------
+# A span is sent exactly once
+# ---------------------------------------------------------------------------
+
+
+def test_span_rides_its_trace_body_and_skips_the_spans_route():
+    """A span flushed alongside its own trace ships in that trace's body, and the
+    spans route is not called for it — the two server paths write the same trace,
+    so one span must not arrive on both at once."""
     capture = RequestCapture()
     exporter = _make_exporter(capture)
 
     tid = uuid4()
     trace = _make_trace(trace_id=tid)
-
-    # Simulate old path: manually buffer a span
     span = _make_span(trace_id=tid)
-    exporter._pending_spans[str(tid)] = [span.to_api_dict()]
-
-    batch = [ExportItem(item_type="trace", data=trace, timestamp=0.0)]
+    batch = [
+        ExportItem(item_type="trace", data=trace, timestamp=0.0),
+        ExportItem(item_type="span", data=span, timestamp=0.0),
+    ]
     exporter._flush_batch(batch)
 
+    assert capture.requests_to(f"/api/v1/traces/{tid}/spans") == []
     reqs = capture.requests_to("/api/v1/traces")
     assert len(reqs) == 1
     payload = decode_body(reqs[0])
-    assert len(payload["spans"]) == 1
+    assert [s["span_id"] for s in payload["spans"]] == [str(span.span_id)]
+
+
+def test_span_without_its_trace_in_the_flush_goes_to_the_spans_route_once():
+    """No trace item for the span's trace means the spans route is the only way
+    it reaches the server — and it goes there exactly once."""
+    capture = RequestCapture()
+    exporter = _make_exporter(capture)
+
+    tid = uuid4()
+    span = _make_span(trace_id=tid)
+    other = _make_trace()
+    batch = [
+        ExportItem(item_type="span", data=span, timestamp=0.0),
+        ExportItem(item_type="trace", data=other, timestamp=0.0),
+    ]
+    exporter._flush_batch(batch)
+
+    reqs = capture.requests_to(f"/api/v1/traces/{tid}/spans")
+    assert len(reqs) == 1
+    payload = decode_body(reqs[0])
+    assert [s["span_id"] for s in payload["spans"]] == [str(span.span_id)]
+    # The unrelated trace ships with an empty body, not with someone else's span.
+    assert decode_body(capture.requests_to("/api/v1/traces")[0])["spans"] == []
+
+
+def test_span_already_in_the_trace_body_is_not_appended_twice():
+    """A trace carries its own spans by construction. A span item naming one of
+    them adds nothing — the body keeps a single copy."""
+    capture = RequestCapture()
+    exporter = _make_exporter(capture)
+
+    tid = uuid4()
+    span = _make_span(trace_id=tid)
+    trace = _make_trace(trace_id=tid)
+    trace._batch_spans = [span]
+    batch = [
+        ExportItem(item_type="trace", data=trace, timestamp=0.0),
+        ExportItem(item_type="span", data=span, timestamp=0.0),
+    ]
+    exporter._flush_batch(batch)
+
+    assert capture.requests_to(f"/api/v1/traces/{tid}/spans") == []
+    payload = decode_body(capture.requests_to("/api/v1/traces")[0])
+    assert [s["span_id"] for s in payload["spans"]] == [str(span.span_id)]
+
+
+def test_span_of_an_earlier_flush_is_not_re_attached_to_a_later_trace():
+    """A span dispatched on the spans route in one flush is delivered. A later
+    flush carrying its trace must not send it a second time in the body."""
+    capture = RequestCapture()
+    exporter = _make_exporter(capture)
+
+    tid = uuid4()
+    span = _make_span(trace_id=tid)
+    exporter._flush_batch([ExportItem(item_type="span", data=span, timestamp=0.0)])
+    assert len(capture.requests_to(f"/api/v1/traces/{tid}/spans")) == 1
+
+    exporter._flush_batch([ExportItem(item_type="trace", data=_make_trace(trace_id=tid), timestamp=0.0)])
+    payload = decode_body(capture.requests_to("/api/v1/traces")[0])
+    assert payload["spans"] == []
 
 
 # ---------------------------------------------------------------------------
@@ -747,8 +814,10 @@ def test_full_trace_spans_counted_in_confirmation(caplog):
 
     tid = uuid4()
     trace = _make_trace(trace_id=tid)
-    exporter._pending_spans[str(tid)] = [_make_span(trace_id=tid).to_api_dict()]
-    batch = [ExportItem(item_type="trace", data=trace, timestamp=0.0)]
+    batch = [
+        ExportItem(item_type="trace", data=trace, timestamp=0.0),
+        ExportItem(item_type="span", data=_make_span(trace_id=tid), timestamp=0.0),
+    ]
 
     with caplog.at_level(logging.INFO, logger="cmpnd.exporter"):
         exporter._flush_batch(batch)

{cmpnd-0.26.0 → cmpnd-0.26.1}/tests/test_exporter_real.py

@@ -312,29 +312,40 @@ class TestErrorHandling:
 # ---------------------------------------------------------------------------
 
 
-class TestSpanBuffering:
-    """Test that spans arriving before their trace get attached correctly."""
+class TestSpanRouting:
+    """A span takes one route to the server, decided by the flush it lands in."""
 
-    def test_buffered_spans_attached_to_trace(self):
+    def test_span_flushed_before_its_trace_is_not_sent_again_with_it(self):
+        """The spans route already delivered it, so the trace that follows carries
+        only the spans of its own body."""
         capture = RequestCapture()
         exporter = _make_exporter(capture)
         tid = uuid4()
 
-        # Span arrives first (via old batching path)
-        span = _make_span(trace_id=tid)
-        exporter.export_span(span)
-        # Flush spans first to populate pending buffer
+        exporter.export_span(_make_span(trace_id=tid))
         exporter._flush_batch(exporter._drain_pending())
+        assert len(capture.payloads_to(f"/api/v1/traces/{tid}/spans")) == 1
 
-        # Now trace arrives
-        trace = _make_trace(trace_id=tid)
-        exporter.export_trace(trace)
+        exporter.export_trace(_make_trace(trace_id=tid))
+        exporter._flush_batch(exporter._drain_pending())
+
+        trace_payloads = capture.payloads_to("/api/v1/traces")
+        assert len(trace_payloads) == 1
+        assert trace_payloads[0]["spans"] == []
+
+    def test_span_flushed_with_its_trace_rides_the_trace_body(self):
+        capture = RequestCapture()
+        exporter = _make_exporter(capture)
+        tid = uuid4()
+
+        exporter.export_span(_make_span(trace_id=tid))
+        exporter.export_trace(_make_trace(trace_id=tid))
         exporter._flush_batch(exporter._drain_pending())
 
-        # The trace POST should include the buffered span
+        assert capture.payloads_to(f"/api/v1/traces/{tid}/spans") == []
         trace_payloads = capture.payloads_to("/api/v1/traces")
         assert len(trace_payloads) == 1
-        assert len(trace_payloads[0]["spans"]) >= 1
+        assert len(trace_payloads[0]["spans"]) == 1
 
 
 # ---------------------------------------------------------------------------

{cmpnd-0.26.0 → cmpnd-0.26.1}/tests/test_ingest_second_producer.py

@@ -456,10 +456,10 @@ def test_a_dict_trace_body_posts_the_bytes_the_typed_builder_would_have(spec: In
 
 
 def test_a_dict_trace_body_collects_the_dict_spans_that_claim_it() -> None:
-    """A span emitted ahead of its trace is buffered and spliced into the trace that
-    claims it — the same coalescing the typed path gets, so a dict-backed producer that
-    hands spans over as it goes still sends one trace. Which trace a span belongs to is
-    read out of the span's own body, so `SpanBody` must not lose it."""
+    """A span flushed alongside the trace that claims it rides that trace's body and
+    takes no second route — the same coalescing the typed path gets, so a dict-backed
+    producer that hands spans over as it goes still sends each span once. Which trace a
+    span belongs to is read out of the span's own body, so `SpanBody` must not lose it."""
     builder = _trace()
     transport = CapturingTransport()
 
@@ -468,8 +468,7 @@ def test_a_dict_trace_body_collects_the_dict_spans_that_claim_it() -> None:
         exporter.export_trace(TraceBody(builder.to_api_dict()))
         assert exporter.flush(timeout=10)
 
-    spans_posts = [r for r in transport.requests if r.path.endswith("/spans")]
-    assert [r.path for r in spans_posts] == [f"/api/v1/traces/{builder.trace_id}/spans"]
+    assert [r for r in transport.requests if r.path.endswith("/spans")] == []
     traces_post = next(r for r in transport.requests if r.path == "/api/v1/traces")
     assert isinstance(traces_post.body, dict)
     assert len(traces_post.body["spans"]) == 1

{cmpnd-0.26.0 → cmpnd-0.26.1}/tests/test_integration.py

@@ -304,12 +304,10 @@ class TestExporterIntegration:
         shutdown_exporter()
         dspy.configure(callbacks=[])
 
-    def test_exporter_buffers_spans_until_trace(self):
-        """Test that exporter buffers spans until trace arrives.
-
-        With the streaming exporter, spans are sent both directly (streaming
-        path) AND buffered for the old trace path. So we expect 2 POST calls:
-        one to /api/v1/traces/:id/spans and one to /api/v1/traces.
+    def test_spans_ride_the_trace_they_are_flushed_with(self):
+        """A span whose trace is in the same flush ships inside that trace's body,
+        and the per-trace spans route is not called for it: the two server paths
+        write the same trace's rows, so one span must not travel both at once.
         """
         from datetime import datetime, timezone
         from uuid import uuid4
@@ -368,10 +366,10 @@ class TestExporterIntegration:
 
             exporter._flush_batch(items)
 
-            # Spans are sent via streaming path + trace picks up buffered spans.
-            # Bodies ship gzipped through client.request(method, path, content=…)
-            # now (CMP-314), so decode the content kwarg to inspect them.
-            assert mock_client.request.call_count == 2
+            # One POST carries the whole trace. Bodies ship gzipped through
+            # client.request(method, path, content=…), so decode the
+            # content kwarg to inspect them.
+            assert mock_client.request.call_count == 1
 
             # Identify calls by URL (positional args: method, path) and decode body.
             calls_by_url = {}
@@ -380,10 +378,6 @@ class TestExporterIntegration:
                 body = json.loads(gzip.decompress(c[1]["content"]))
                 calls_by_url[url] = body
 
-            # Old-path trace POST with embedded spans
+            assert f"/api/v1/traces/{trace_id}/spans" not in calls_by_url
             trace_data = calls_by_url["/api/v1/traces"]
             assert len(trace_data["spans"]) == 2
-
-            # Streaming spans POST
-            span_url = f"/api/v1/traces/{trace_id}/spans"
-            assert len(calls_by_url[span_url]["spans"]) == 2

cmpnd-0.26.1/tests/test_span_sent_once.py

@@ -0,0 +1,178 @@
+"""Every span the SDK produces reaches the server exactly once.
+
+A span has two routes to the server: ``POST /api/v1/traces/{id}/spans``, and its
+trace's own body on ``POST /api/v1/traces``. Both write the same trace's rows, so
+a span taking both at once is two concurrent writers over one trace, and it is
+double upload for whoever is paying for the bandwidth. The exporter's flush is
+the one place that picks a route, so these tests drive the real callback into a
+real ``BatchExporter`` over a mock transport and count what the wire carries.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest import mock
+
+import dspy
+import httpx
+import pytest
+
+import cmpnd
+from cmpnd.configuration import Config
+from cmpnd.exporter import BatchExporter
+from tests._exporter_helpers import decode_body
+from tests.e2e import fake_lm
+from tests.test_eval_trace_grouping import (  # noqa: F401  (autouse fixtures)
+    CapitalQA,
+    RecordingExporter,
+    _fake_provider,
+    _sdk_configured,
+)
+
+pytest.importorskip("dspy")
+
+
+class _Wire:
+    """Captures what the exporter puts on the wire."""
+
+    def __init__(self) -> None:
+        self.requests: list[httpx.Request] = []
+
+    def handler(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        return httpx.Response(200, json={"status": "ok"})
+
+    def span_ids_by_route(self) -> dict[str, list[str]]:
+        """span_id -> the request paths that carried it, one entry per carry."""
+        seen: dict[str, list[str]] = {}
+        for request in self.requests:
+            path = request.url.path
+            payload = decode_body(request)
+            spans: list[dict[str, Any]] = []
+            if path.endswith("/spans"):
+                spans = payload.get("spans", [])
+            elif path == "/api/v1/traces":
+                spans = payload.get("spans", [])
+            elif path == "/api/v1/traces/batch":
+                for trace in payload:
+                    spans.extend(trace.get("spans", []))
+            for span in spans:
+                seen.setdefault(str(span["span_id"]), []).append(path)
+        return seen
+
+
+def _exporter(wire: _Wire) -> BatchExporter:
+    config = Config(api_key="test", endpoint="http://localhost:9999")
+    exporter = BatchExporter(config)
+    exporter._client = httpx.Client(
+        base_url=config.endpoint,
+        headers={"X-API-Key": config.api_key, "Content-Type": "application/json"},
+        timeout=5.0,
+        transport=httpx.MockTransport(wire.handler),
+    )
+    return exporter
+
+
+class ManualStepProgram(dspy.Module):
+    """A program that opens a span of its own — the shape that puts a ``span``
+    item and its trace's ``trace`` item in the same flush."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.predict = dspy.Predict(CapitalQA)
+
+    def forward(self, question: str) -> Any:
+        with cmpnd.start_span("manual_step") as span:
+            span.set_attribute("step", "lookup")
+        return self.predict(question=question)
+
+
+def _run_under_exporter(program: dspy.Module) -> _Wire:
+    """Run ``program`` with the callback exporting into a real BatchExporter,
+    then flush that exporter's whole queue in one batch."""
+    from cmpnd.callback import CmpndCallback
+
+    wire = _Wire()
+    exporter = _exporter(wire)
+
+    with mock.patch("cmpnd.exporter.ensure_exporter_started"):
+        callback = CmpndCallback()
+
+    saved = list(dspy.settings.callbacks or [])
+    try:
+        dspy.settings.configure(callbacks=[callback])
+        with (
+            mock.patch("cmpnd.exporter.get_exporter", return_value=exporter),
+            dspy.context(lm=dspy.LM(fake_lm.FAKE_MODEL, cache=False)),
+        ):
+            program(question="What is the capital of France?")
+    finally:
+        dspy.settings.configure(callbacks=saved)
+
+    batch = []
+    for q in (exporter._lifecycle_queue, exporter._detail_queue):
+        while not q.empty():
+            batch.append(q.get_nowait())
+    exporter._flush_batch(batch)
+    return wire
+
+
+def test_a_program_opened_span_is_not_sent_on_both_routes():
+    wire = _run_under_exporter(ManualStepProgram())
+    carried = wire.span_ids_by_route()
+
+    manual = [routes for routes in carried.values() if len(routes) > 1]
+    assert manual == [], f"span sent more than once: {manual}"
+    assert carried, "the run produced no spans at all"
+
+
+def test_every_span_of_a_batched_trace_rides_its_body():
+    """A non-streaming trace and its spans in one flush means one POST carries
+    all of it, and the per-trace spans route is never called."""
+    wire = _run_under_exporter(ManualStepProgram())
+
+    spans_routes = [r for r in wire.requests if r.url.path.endswith("/spans")]
+    assert spans_routes == [], f"spans route called for a batched trace: {[r.url.path for r in spans_routes]}"
+
+    names = {
+        span["name"]
+        for request in wire.requests
+        if request.url.path == "/api/v1/traces"
+        for span in decode_body(request).get("spans", [])
+    }
+    assert "manual_step" in names
+    assert "Predict.forward" in names
+
+
+def test_callback_does_not_stream_spans_of_a_non_streaming_trace():
+    """The classification half of the rule: a span the callback tracked for a
+    batched trace is never handed to ``export_span``, whichever thread it ends on."""
+    from cmpnd.callback import CmpndCallback
+
+    with mock.patch("cmpnd.exporter.ensure_exporter_started"):
+        callback = CmpndCallback()
+    recorder = RecordingExporter()
+
+    saved = list(dspy.settings.callbacks or [])
+    try:
+        dspy.settings.configure(callbacks=[callback])
+        with (
+            mock.patch("cmpnd.exporter.get_exporter", return_value=recorder),
+            dspy.context(lm=dspy.LM(fake_lm.FAKE_MODEL, cache=False)),
+        ):
+            evaluate = dspy.Evaluate(
+                devset=[
+                    dspy.Example(question="What is the capital of France?", answer="Paris").with_inputs("question")
+                ],
+                metric=lambda example, prediction, trace=None: 1.0,
+                num_threads=4,
+                display_progress=False,
+                display_table=False,
+            )
+            evaluate(dspy.Predict(CapitalQA))
+    finally:
+        dspy.settings.configure(callbacks=saved)
+
+    streamed = {str(span.span_id) for span in recorder.spans}
+    batched = {str(span.span_id) for trace in recorder.traces for span in (trace._batch_spans or [])}
+    assert streamed & batched == set()

{cmpnd-0.26.0 → cmpnd-0.26.1}/uv.lock

@@ -496,7 +496,7 @@ wheels = [
 
 [[package]]
 name = "cmpnd"
-version = "0.26.0"
+version = "0.26.1"
 source = { editable = "." }
 dependencies = [
     { name = "dspy" },