cmpnd 0.42.0__tar.gz → 0.42.2__tar.gz

{cmpnd-0.42.0 → cmpnd-0.42.2}/PKG-INFO

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

{cmpnd-0.42.0 → cmpnd-0.42.2}/cmpnd/authored.py

@@ -32,7 +32,7 @@ from typing import Any
 _MAX_BUNDLE_BYTES = 50 * 1024 * 1024
 _CHECK_TIMEOUT_SECONDS = 60.0
 _CHECK_TIMEOUT_ENV = "CMPND_AUTHORED_IMPORT_TIMEOUT_SECONDS"
-_WORKER_DSPY_BASELINE = (3, 3, 1)
+_WORKER_DSPY_BASELINE = (3, 4, 1)
 
 
 class SourceCheckError(ValueError):

{cmpnd-0.42.0 → cmpnd-0.42.2}/cmpnd/models.py

@@ -961,6 +961,10 @@ class TraceBuilder:
     # the configuration at construction like project_tags. None declares none,
     # and the key is then left off the wire rather than sent as null.
     program_id: str | None = field(default_factory=configuration._current_program_id)
+    # The program name the trace declares, or None. It never goes on the wire: the
+    # exporter resolves it to a program id and writes that into ``program_id`` on the
+    # bodies it sends, unless the trace already carries an id.
+    declared_name: str | None = None
 
     # Optimization lineage - tracks which optimization produced this program
     compiled_from_run_id: str | None = None

{cmpnd-0.42.0 → cmpnd-0.42.2}/docs/sdk-instrumentation.md

@@ -768,6 +768,33 @@ names its program, so the id is optional there. Later steps
 optimize a result deployment the platform created and whose program it allocated, so
 the caller's id rides only the steps on the caller's own deployment.
 
+#### A declared program name resolves to an id in the exporter
+
+A trace can declare its program by name instead of by id, in `TraceBuilder.declared_name`.
+No public API sets it yet. The name never goes on the wire. The exporter resolves it with
+`PUT /api/v1/programs/by-name/{name}` and writes the id into the trace start and full
+trace bodies, at the top level and in `started_fact`, before it compares or sends them.
+`cmpnd_ingest/program_names.py` keeps the answers, and
+`BatchExporter._stamp_program_ids` makes the requests:
+
+- **Once per name per process.** Each exporter keeps its answers for its own life, and
+  the pool keeps one exporter per endpoint and key, so each name resolves once for each.
+  A forked child keeps its parent's answers.
+- **On the export thread.** The batch waits for the resolve, and the producer never
+  does. The exit flush resolves the names still waiting, with no retries.
+- **An id already on the trace stands.** Inside a worker, a deployment's traces carry
+  its id from the start, and no name is resolved.
+- **A refusal settles the name with no id.** Serve answers 404 or 405 when it has no
+  program names, as self-host release 2026-001 does, and 409, 422 or 403 for a name it
+  will not resolve. The traces go without an id, and the exporter warns once per name.
+- **An outage leaves the name unsettled.** A 5xx, a 429 or an unreachable server is
+  retried with backoff, wider than the data sends' rule because the request is a
+  get-or-create that a repeat cannot double. The names in one batch share one retry
+  budget, so an outage delays a batch by one budget however many new names it holds.
+  When the budget is spent, the batch's traces go without an id, and later batches try
+  the names again. A trace keeps the decision its first body carried,
+  because serve refuses a trace whose started fact changes between sends.
+
 ### LM usage evidence
 
 Optimization LM spans carry `optimization.role` in their string attributes.

{cmpnd-0.42.0 → cmpnd-0.42.2}/ingest/cmpnd_ingest/exporter_http.py

@@ -25,6 +25,7 @@ import os
 import queue
 import threading
 import time
+import urllib.parse
 import weakref
 from collections.abc import Callable
 from concurrent.futures import ThreadPoolExecutor, as_completed
@@ -33,7 +34,7 @@ from typing import Any, cast
 
 import httpx
 
-from . import request_log, retry
+from . import program_names, request_log, retry
 from .bodies import EncodedTraceBody, TraceBody
 from .protocols import (
     EvalRunRecord,
@@ -96,6 +97,16 @@ def _send_encoded(client: httpx.Client, method: str, path: str, body: EncodedTra
 _SHED_STATUS = 429
 
 
+def _error_text(response: httpx.Response) -> str:
+    """The ``error`` field of a refusal, else its body, shortened for a log line."""
+    try:
+        error = response.json().get("error")
+    except (ValueError, AttributeError):
+        error = None
+    text = error if isinstance(error, str) and error else (response.text or "").strip()
+    return text[:200] or "no detail"
+
+
 class ExportRetriesExhausted(RuntimeError):
     """A data POST rode through transient answers until its budget ran out.
 
@@ -183,6 +194,22 @@ def _is_retryable_export_error(exc: BaseException) -> bool:
     return isinstance(exc, (httpx.TimeoutException, httpx.TransportError))
 
 
+def _may_retry_a_name_resolve(exc: BaseException) -> bool:
+    """Whether a failed program-name resolve is worth asking again.
+
+    Wider than the data sends' rule, for two reasons. A failed resolve sends its batch
+    without program ids, and a trace whose start went without an id keeps none, so
+    giving up early costs more than waiting. And the request is a get-or-create that
+    returns one id per name however often it is repeated, so a repeat can never
+    allocate twice. So a 429 and a plain 500 are retried here too, with ``Retry-After``
+    honoured, while a 4xx refusal is final.
+    """
+    if isinstance(exc, httpx.HTTPStatusError):
+        status = exc.response.status_code
+        return status == _SHED_STATUS or status >= 500 or retry.is_retryable(exc.response)
+    return isinstance(exc, (httpx.TimeoutException, httpx.TransportError))
+
+
 def _may_resend_a_minting_post(exc: BaseException) -> bool:
     """The same question as above, asked of a POST that BOTH mints an id and
     creates the record under it — on this contract, only ``POST /api/v1/evals``.
@@ -225,6 +252,20 @@ class ExportItem:
     # documentation and to catch misuse at enqueue.
     data: TraceRecord | SpanRecord | EvalRunRecord | OptimizationRunRecord | EncodedTraceBody
     timestamp: float
+    # The program name a trace declared, which the flush resolves to an id. It rides the
+    # queue item because the body is serialized at enqueue and the name never goes on
+    # the wire.
+    declared_name: str | None = None
+
+
+def _declared_name(trace: TraceRecord) -> str | None:
+    """The program name a trace record declares, or None.
+
+    Read with ``getattr`` because the member is optional: a ``Protocol`` cannot declare
+    an optional member, and a producer that names no programs should not need one.
+    """
+    name = getattr(trace, "declared_name", None)
+    return name if isinstance(name, str) and name else None
 
 
 # The only record the exporter will shed under load, and the reason overflow can
@@ -366,6 +407,10 @@ class BatchExporter:
         self._dropped_at_last_log = 0
         self._stats_lock = threading.Lock()
 
+        # The program ids serve gave for the names traces declare. Kept across a fork:
+        # see _reinit_after_fork.
+        self._program_names = program_names.ProgramNames()
+
     def start(self) -> None:
         """Start the background export thread."""
         # Before the liveness check, not after: in a forked child `_thread` is a
@@ -472,6 +517,8 @@ class BatchExporter:
 
         self._sync_client_lock = threading.Lock()
         self._stats_lock = threading.Lock()
+        # The resolved program names stay: the ids are still right in the child.
+        self._program_names.after_fork()
 
         self._flush_cond = threading.Condition()
         self._flush_requested_gen = 0
@@ -584,7 +631,7 @@ class BatchExporter:
 
     def export_trace(self, trace: TraceRecord) -> None:
         """Queue a trace for export (non-blocking)."""
-        self._enqueue(ExportItem("trace", TraceBody(trace.to_api_dict()), time.time()))
+        self._enqueue(ExportItem("trace", TraceBody(trace.to_api_dict()), time.time(), _declared_name(trace)))
 
     def export_encoded_trace(self, trace: EncodedTraceBody) -> None:
         """Queue a compressed finished trace for export (non-blocking).
@@ -622,12 +669,12 @@ class BatchExporter:
     def export_trace_start(self, trace: TraceRecord) -> None:
         """Queue a trace start for export (non-blocking)."""
         body = {**trace.to_start_dict(), "trace_id": str(trace.trace_id)}
-        self._enqueue(ExportItem("trace_start", TraceBody(body), time.time()))
+        self._enqueue(ExportItem("trace_start", TraceBody(body), time.time(), _declared_name(trace)))
 
     def export_trace_finalize(self, trace: TraceRecord) -> None:
         """Queue a trace finalization for export (non-blocking)."""
         body = {**trace.to_finalize_dict(), "trace_id": str(trace.trace_id)}
-        self._enqueue(ExportItem("trace_finalize", TraceBody(body), time.time()))
+        self._enqueue(ExportItem("trace_finalize", TraceBody(body), time.time(), _declared_name(trace)))
 
     def export_optimization_start(self, optimization_run: OptimizationRunRecord) -> str:
         """Create the optimization record server-side and return the
@@ -1089,7 +1136,15 @@ class BatchExporter:
     def _send_json_retrying(self, client: httpx.Client, method: str, path: str, payload: Any) -> httpx.Response:
         return self._send_retrying(method, path, lambda: _send_json(client, method, path, payload))
 
-    def _send_retrying(self, method: str, path: str, send: Callable[[], httpx.Response]) -> httpx.Response:
+    def _send_retrying(
+        self,
+        method: str,
+        path: str,
+        send: Callable[[], httpx.Response],
+        *,
+        retryable: Callable[[BaseException], bool] = _is_retryable_export_error,
+        tally: retry.TransientTally | None = None,
+    ) -> httpx.Response:
         """`_send_json` + `raise_for_status`, riding through transient blips.
 
         Retries a failure the retryable-error contract calls transient (see
@@ -1103,21 +1158,26 @@ class BatchExporter:
 
         An exhausted budget raises ExportRetriesExhausted naming the count and
         the window, so a run that could not be saved says what it endured.
+
+        ``retryable`` replaces the data sends' rule for a caller with a different one.
+        ``tally`` lets several calls share one budget: a caller passes the same tally
+        to each, and once it is spent every later call gives up at its first failure.
         """
-        tally = retry.TransientTally()
+        tally = tally if tally is not None else retry.TransientTally()
+        ridden_before = tally.count
         while True:
             try:
                 response = send()
                 response.raise_for_status()
-                if tally.count:
-                    self._note_ridden_through(tally.count)
+                if tally.count > ridden_before:
+                    self._note_ridden_through(tally.count - ridden_before)
                     logger.warning("cmpnd: rode through %s to %s %s", tally.describe(time.monotonic()), method, path)
                 return response
             except Exception as e:
                 resp = e.response if isinstance(e, httpx.HTTPStatusError) else None
                 if resp is not None:
                     self._note_status(resp)
-                if not _is_retryable_export_error(e):
+                if not retryable(e):
                     raise
                 tally.record(
                     str(resp.status_code) if resp is not None else type(e).__name__,
@@ -1126,7 +1186,7 @@ class BatchExporter:
                 )
                 now = time.monotonic()
                 if tally.exhausted(now) or not self._wait_before_retry(retry.delay_for(tally.count - 1, resp)):
-                    self._note_ridden_through(tally.count)
+                    self._note_ridden_through(tally.count - ridden_before)
                     raise ExportRetriesExhausted(f"{method} {path} gave up after {tally.describe(now)}: {e}") from e
 
     def _note_status(self, response: httpx.Response) -> None:
@@ -1184,10 +1244,21 @@ 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]]] = {}
+        # Bodies that declare a program by name, as (name, trace id, body), so the
+        # names can be resolved and the ids written before anything compares or sends
+        # them. A finalize body restates no creation field and carries no id, but it
+        # and a full trace body are a trace's last, so both end the trace's decision.
+        named_bodies: list[tuple[str, str, dict[str, Any]]] = []
+        ended_traces: list[str] = []
 
         for item in batch:
             if item.item_type == "trace":
-                traces_to_send.append(cast("TraceRecord", item.data).to_api_dict())
+                body = cast("TraceRecord", item.data).to_api_dict()
+                traces_to_send.append(body)
+                if item.declared_name is not None:
+                    trace_id = str(body.get("trace_id"))
+                    named_bodies.append((item.declared_name, trace_id, body))
+                    ended_traces.append(trace_id)
             elif item.item_type == "encoded_trace":
                 encoded_traces.append(cast("EncodedTraceBody", item.data))
             elif item.item_type == "eval_run":
@@ -1205,11 +1276,16 @@ class BatchExporter:
             elif item.item_type == "trace_start":
                 trace = cast("TraceRecord", item.data)
                 trace_id = str(trace.trace_id)
-                trace_starts.append((trace_id, trace.to_start_dict()))
+                body = trace.to_start_dict()
+                trace_starts.append((trace_id, body))
+                if item.declared_name is not None:
+                    named_bodies.append((item.declared_name, trace_id, body))
             elif item.item_type == "trace_finalize":
                 trace = cast("TraceRecord", item.data)
                 trace_id = str(trace.trace_id)
                 trace_finalizes.append((trace_id, trace.to_finalize_dict()))
+                if item.declared_name is not None:
+                    ended_traces.append(trace_id)
             elif item.item_type == "span":
                 span_dict = cast("SpanRecord", item.data).to_api_dict()
                 trace_id = str(span_dict.get("trace_id") or "")
@@ -1218,6 +1294,9 @@ class BatchExporter:
                     continue
                 spans_by_trace.setdefault(trace_id, []).append(span_dict)
 
+        if named_bodies or ended_traces:
+            self._stamp_program_ids(named_bodies, ended_traces)
+
         # 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
         # final status directly (serve traceUpsertSQL, ON CONFLICT on
@@ -1329,6 +1408,72 @@ class BatchExporter:
                 errored,
             )
 
+    # ------------------------------------------------------------------
+    # Declared program names
+    # ------------------------------------------------------------------
+
+    def _stamp_program_ids(self, named_bodies: list[tuple[str, str, dict[str, Any]]], ended_traces: list[str]) -> None:
+        """Resolve the batch's declared names, then write their ids into its bodies.
+
+        Runs on the export thread, so the batch waits for the resolve and the
+        producer never does. A body that already declares an id keeps it: inside a
+        worker, a deployment's traces carry its id from the start.
+
+        The batch's names share one retry budget, so an outage delays the batch by one
+        budget however many new names it holds. Once the budget is spent, the names not
+        yet asked stay unsettled for the next batch.
+        """
+        waiting = [name for name, _, body in named_bodies if "program_id" not in body]
+        tally = retry.TransientTally()
+        for name in self._program_names.unsettled(waiting):
+            if tally.exhausted(time.monotonic()):
+                self._warn_program_name(name, "the batch's retry budget is spent; later traces will try again")
+                continue
+            self._resolve_program_name(name, tally)
+        for name, trace_id, body in named_bodies:
+            self._program_names.stamp(name, trace_id, body)
+        for trace_id in ended_traces:
+            self._program_names.trace_ended(trace_id)
+
+    def _resolve_program_name(self, name: str, tally: retry.TransientTally) -> None:
+        """Ask serve for a name's program id, and settle the name unless serve was unreachable.
+
+        The request has no body. A 429, a 5xx or an unreachable server is retried on
+        the batch's shared budget (see `_may_retry_a_name_resolve`), and a spent budget
+        leaves the name unsettled for the next batch. A refusal settles the name with
+        no id. Each name warns once.
+        """
+        client = self._require_client()
+        path = "/api/v1/programs/by-name/" + urllib.parse.quote(name, safe="")
+        try:
+            response = self._send_retrying(
+                "PUT", path, lambda: client.request("PUT", path), retryable=_may_retry_a_name_resolve, tally=tally
+            )
+        except httpx.HTTPStatusError as e:
+            status = e.response.status_code
+            self._program_names.settle(name, None)
+            if status in (404, 405):
+                self._warn_program_name(name, "the server has no program names")
+            else:
+                self._warn_program_name(name, f"the server refused it with {status}: {_error_text(e.response)}")
+            return
+        except Exception as e:
+            self._warn_program_name(name, f"the server gave no answer ({e}); later traces will try again")
+            return
+        try:
+            program_id = response.json().get("program_id")
+        except (ValueError, AttributeError):
+            program_id = None
+        if not isinstance(program_id, str) or not program_id:
+            self._program_names.settle(name, None)
+            self._warn_program_name(name, "the server's answer had no program id")
+            return
+        self._program_names.settle(name, program_id)
+
+    def _warn_program_name(self, name: str, reason: str) -> None:
+        if self._program_names.first_warning(name):
+            logger.warning("cmpnd: traces of program %r are sent without a program id: %s.", name, reason)
+
     # ------------------------------------------------------------------
     # Individual send methods (run in thread pool)
     # ------------------------------------------------------------------

cmpnd-0.42.2/ingest/cmpnd_ingest/program_names.py

@@ -0,0 +1,90 @@
+"""The program ids serve gave for the program names this process declared.
+
+A trace can declare the name of its program instead of its id. The name never goes on
+the wire: the transport asks serve for the name's program id with
+``PUT /api/v1/programs/by-name/{name}``, once per name per process, and writes the id
+into each trace body before it sends it. This module keeps the answers. The transport
+makes the requests, because they ride its client and its retry budget.
+
+An answer is kept for the life of the process. A name that serve later points at
+another program reaches a process only when the process starts again, and a renamed
+program's old name keeps resolving to it.
+
+A name settles in one of two ways. Serve gives an id, or serve refuses the name, as a
+server without program names does with ``405``. A refused name sends its traces without
+an id for the rest of the process. A name that could not be resolved because serve was
+unreachable stays unsettled, and the transport tries it again for later traces.
+
+A trace keeps the decision its first body carried. Serve refuses a trace whose started
+fact changes between sends, so a trace whose start went without an id during an outage
+sends every later body without one too, even after the name resolves.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Iterable
+from typing import Any
+
+
+class ProgramNames:
+    """Resolved and refused names, and the id each unfinished trace was sent with."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        # Settled names: the id serve gave, or None for a name serve refused.
+        self._ids: dict[str, str | None] = {}
+        # Traces whose first body went out while their name was unsettled, keyed by
+        # trace id. They keep sending without an id until they end.
+        self._sent_without_id: set[str] = set()
+        self._warned: set[str] = set()
+
+    def after_fork(self) -> None:
+        """Keep the answers in a forked child, with a lock the child can take.
+
+        The ids are still right in the child, so it does not ask again. A lock that
+        another thread held at the fork stays held in the child, so it is replaced.
+        """
+        self._lock = threading.Lock()
+
+    def unsettled(self, names: Iterable[str]) -> list[str]:
+        """The names among ``names`` that have no answer yet, each once, in order."""
+        with self._lock:
+            return list(dict.fromkeys(name for name in names if name not in self._ids))
+
+    def settle(self, name: str, program_id: str | None) -> None:
+        """Record serve's answer for a name: its id, or None when serve refused it."""
+        with self._lock:
+            self._ids[name] = program_id
+
+    def first_warning(self, name: str) -> bool:
+        """True the first time this is asked for a name, so each name warns once."""
+        with self._lock:
+            if name in self._warned:
+                return False
+            self._warned.add(name)
+            return True
+
+    def stamp(self, name: str, trace_id: str, body: dict[str, Any]) -> None:
+        """Write the name's id into a trace start or full trace body.
+
+        The id goes at the top level and in the started fact, where the builder puts
+        an id it was given. A body that already declares an id keeps it.
+        """
+        if "program_id" in body:
+            return
+        with self._lock:
+            program_id = None if trace_id in self._sent_without_id else self._ids.get(name)
+            if program_id is None and name not in self._ids:
+                self._sent_without_id.add(trace_id)
+        if program_id is None:
+            return
+        body["program_id"] = program_id
+        started = body.get("started_fact")
+        if isinstance(started, dict):
+            started["program_id"] = program_id
+
+    def trace_ended(self, trace_id: str) -> None:
+        """Forget a trace's decision once its last body is built."""
+        with self._lock:
+            self._sent_without_id.discard(trace_id)

{cmpnd-0.42.0 → cmpnd-0.42.2}/ingest/cmpnd_ingest/protocols.py

@@ -49,7 +49,13 @@ class SpanRecord(Protocol):
 
 
 class TraceRecord(Protocol):
-    """A trace, in each of the three shapes the contract's routes take."""
+    """A trace, in each of the three shapes the contract's routes take.
+
+    A trace may also have a ``declared_name`` attribute: the name of its program, which
+    the transport resolves to a program id before it sends the trace (see
+    `program_names`). The member is optional, so it is not declared here, and the
+    transport reads it with ``getattr``.
+    """
 
     @property
     def trace_id(self) -> Any: ...

{cmpnd-0.42.0 → cmpnd-0.42.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.42.0"
+version = "0.42.2"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"

{cmpnd-0.42.0 → cmpnd-0.42.2}/tests/test_authored.py

@@ -100,11 +100,11 @@ def test_newer_local_dspy_warns_about_the_worker_compatibility_boundary(monkeypa
     monkeypatch.setattr(
         authored,
         "_dependency_versions",
-        lambda: {"python": "3.14.0", "dspy": "3.4.0", "cmpnd": "0.26.0"},
+        lambda: {"python": "3.14.0", "dspy": "3.5.0", "cmpnd": "0.26.0"},
     )
     monkeypatch.setattr(authored, "_check_bundle", lambda *_args, **_kwargs: authored.ProgramFacts.minimal())
 
-    with pytest.warns(RuntimeWarning, match="newer than the worker's 3.3.1 compatibility baseline"):
+    with pytest.warns(RuntimeWarning, match="newer than the worker's 3.4.1 compatibility baseline"):
         authored.prepare_stdin(b"program = object()\n")