cmpnd 0.33.0__tar.gz → 0.33.2__tar.gz

{cmpnd-0.33.0 → cmpnd-0.33.2}/PKG-INFO

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

{cmpnd-0.33.0 → cmpnd-0.33.2}/cmpnd/execution.py

@@ -8,6 +8,8 @@ from __future__ import annotations
 
 import inspect
 import keyword
+import math
+import time
 from typing import TYPE_CHECKING, Any
 
 import httpx
@@ -20,6 +22,7 @@ from httpx import HTTPStatusError
 
 from . import _http, configuration
 from .deployment_metadata import DeploymentArtifactMetadata, DeploymentSignatureResponse, ProgramFieldType
+from .retry import retry_after_seconds
 
 if TYPE_CHECKING:
     from dspy.primitives.prediction import Prediction
@@ -89,6 +92,64 @@ def _retryable_provider_failure(
     )
 
 
+_CAPACITY_MAX_ATTEMPTS = 3
+_CAPACITY_MAX_WAIT_SECONDS = 15.0
+_capacity_now = time.monotonic
+_capacity_sleep = time.sleep
+
+
+def _pre_admission_capacity(resp: httpx.Response) -> bool:
+    """Only a worker's explicit pre-admission refusal proves no program ran."""
+    if resp.status_code != 503:
+        return False
+    try:
+        body = resp.json()
+    except ValueError:
+        return False
+    return (
+        isinstance(body, dict)
+        and body.get("retryable") is True
+        and isinstance(body.get("error"), dict)
+        and body["error"].get("type") == "Capacity"
+    )
+
+
+def _post_with_capacity_retry(
+    client: httpx.Client, url: str, body: dict[str, Any], api_key: str, timeout: Any
+) -> httpx.Response:
+    # httpx's numeric timeout applies to each network phase, not the entire call.
+    # Also bound the waits and each later request by elapsed time so retries do
+    # not silently grant the call a fresh timeout.
+    deadline = (
+        _capacity_now() + timeout
+        if isinstance(timeout, (int, float)) and not isinstance(timeout, bool) and timeout > 0
+        else None
+    )
+    last_response: httpx.Response | None = None
+    for attempt in range(_CAPACITY_MAX_ATTEMPTS):
+        remaining = deadline - _capacity_now() if deadline is not None else None
+        if attempt and remaining is not None and remaining <= 0:
+            assert last_response is not None
+            return last_response
+        if remaining is None:
+            resp = client.post(url, json=body, headers={"X-API-Key": api_key})
+        else:
+            resp = client.post(url, json=body, headers={"X-API-Key": api_key}, timeout=remaining)
+        last_response = resp
+        if not _pre_admission_capacity(resp) or attempt == _CAPACITY_MAX_ATTEMPTS - 1:
+            return resp
+
+        asked = retry_after_seconds(resp)
+        if asked is not None and (not math.isfinite(asked) or asked > _CAPACITY_MAX_WAIT_SECONDS):
+            return resp
+        delay = max(0.5 * 2**attempt, asked or 0.0, 0.0)
+        if delay > _CAPACITY_MAX_WAIT_SECONDS or (deadline is not None and delay >= deadline - _capacity_now()):
+            return resp
+        _capacity_sleep(delay)
+    assert last_response is not None
+    return last_response
+
+
 class DeployedProgram:
     """A deployed DSPy program that can be called like a local module.
 
@@ -258,7 +319,8 @@ def execute(deployment_id, timeout=30, metadata=None, tags=None, **inputs):
     Args:
         deployment_id: The deployment ID returned by deploy(), or a
             DeployedProgram instance.
-        timeout: HTTP request timeout in seconds (default 30).
+        timeout: HTTP request timeout in seconds (default 30). Capacity retries
+            share this budget when it is numeric.
         metadata: Optional ``dict[str, str]`` of decision-time correlation
             data merged onto the server-side root trace (e.g.
             ``{"discord.message_id": "123"}``). Forwarded to the execute
@@ -298,10 +360,12 @@ def execute(deployment_id, timeout=30, metadata=None, tags=None, **inputs):
         body["tags"] = _validate_str_map("tags", tags)
 
     with httpx.Client(timeout=timeout) as client:
-        resp = client.post(
+        resp = _post_with_capacity_retry(
+            client,
             f"{config.endpoint}/api/v1/deployments/{dep_id}/execute",
-            json=body,
-            headers={"X-API-Key": config.api_key},
+            body,
+            config.api_key,
+            timeout,
         )
 
         if resp.status_code == 409:

{cmpnd-0.33.0 → cmpnd-0.33.2}/docs/sdk-instrumentation.md

@@ -241,6 +241,11 @@ All tunables live on `Config` in `python-sdk/cmpnd/config.py:12`:
 
 Override any of these by passing kwargs to `cmpnd.configure(...)`.
 
+The HTTP transport also reads connect, read, write and connection pool timeouts from
+environment variables when the exporter is constructed. Each defaults to 30 seconds. See
+[`cmpnd-ingest` HTTP request timeouts](../ingest/README.md#http-request-timeouts) for
+the variable names and their scope.
+
 ### Shape of the loop
 
 - `start()` at `exporter_http.py:131` creates the worker thread and the `ThreadPoolExecutor`, then registers `shutdown()` via `threading._register_atexit` (or `atexit.register` as a fallback). The registration ordering is deliberate — there's a comment at `exporter_http.py:139` explaining why it has to go after the executor init.
@@ -358,6 +363,21 @@ private prediction metadata, so a program can use `output` or
 `deployment_run_id` as an output field. The accessor also accepts an execute
 exception. Trace delivery can finish after the execute response arrives.
 
+When the worker refuses an execute before admitting it, serve returns HTTP 503
+with `error.type: "Capacity"`, `retryable: true`, and a `Retry-After` hint.
+`cmpnd.execute()` retries only that exact response, up to three total attempts.
+It waits at least as long as the hint, but never waits more than 15 seconds for
+one retry. If the hint exceeds that bound, the SDK returns the Capacity error
+without retrying early. Other failures, including provider errors and uncertain
+transport failures, return immediately because the program may have run.
+
+A numeric `timeout` still controls each HTTP request. The SDK also charges
+Capacity retry waits and later requests against the same elapsed budget. The
+default is 30 seconds, so callers running programs that may spend longer in
+admission or execution must pass a larger timeout. Serve assigns a fresh run id
+to each attempt. When serve responds, `cmpnd.deployment_run_id()` returns only
+the final attempt's run id, whether execute succeeds or raises.
+
 ```python
 try:
     result = deployed(question="What changed?")

{cmpnd-0.33.0 → cmpnd-0.33.2}/ingest/README.md

@@ -97,6 +97,24 @@ queue is `max_queue_size` deep and sheds past it rather than growing. Only the t
 run-record entry points block, because a run must exist before anything referring to it
 ships.
 
+## HTTP request timeouts
+
+`BatchExporter` reads these environment variables when it is constructed. Each accepts a finite,
+positive number of seconds and defaults to 30 seconds.
+
+| Variable | What it bounds |
+|---|---|
+| `CMPND_INGEST_CONNECT_TIMEOUT_SECONDS` | Establishing a connection to serve |
+| `CMPND_INGEST_READ_TIMEOUT_SECONDS` | Waiting for the next response chunk |
+| `CMPND_INGEST_WRITE_TIMEOUT_SECONDS` | Waiting to send the next request chunk |
+| `CMPND_INGEST_POOL_TIMEOUT_SECONDS` | Waiting for an available connection |
+
+The same settings apply to blocking run writes and queued exports in both the SDK and
+the hosted search process. HTTPX applies each timeout to a phase of network activity;
+none sets a total request deadline. The body size caps do not bound upload time or
+serve's processing time. Raise the write timeout for slow uploads or the read timeout
+for slow responses. Export retry budgets remain separate.
+
 ## Proving conformance from another producer
 
 Set `CMPND_INGEST_REQUEST_LOG=<path>` and the transport appends one

{cmpnd-0.33.0 → cmpnd-0.33.2}/ingest/cmpnd_ingest/exporter_http.py

@@ -20,6 +20,7 @@ import base64
 import gzip
 import json
 import logging
+import math
 import os
 import queue
 import threading
@@ -112,6 +113,31 @@ class ExportRetriesExhausted(RuntimeError):
 # spending a round trip — and megabytes of gzip — on a 400 it could have predicted.
 CHECKPOINT_STATE_MAX_BYTES = 8 * 1024 * 1024
 
+_DEFAULT_HTTP_TIMEOUT_SECONDS = 30.0
+
+
+def _http_timeout_seconds(phase: str) -> float:
+    name = f"CMPND_INGEST_{phase}_TIMEOUT_SECONDS"
+    value = os.getenv(name)
+    if value is None:
+        return _DEFAULT_HTTP_TIMEOUT_SECONDS
+    try:
+        seconds = float(value)
+    except ValueError as exc:
+        raise ValueError(f"{name} must be a finite, positive number of seconds") from exc
+    if not math.isfinite(seconds) or seconds <= 0:
+        raise ValueError(f"{name} must be a finite, positive number of seconds")
+    return seconds
+
+
+def _http_timeout() -> httpx.Timeout:
+    return httpx.Timeout(
+        connect=_http_timeout_seconds("CONNECT"),
+        read=_http_timeout_seconds("READ"),
+        write=_http_timeout_seconds("WRITE"),
+        pool=_http_timeout_seconds("POOL"),
+    )
+
 
 class CheckpointStateTooLarge(ValueError):
     """A checkpoint's state is past the contract's ceiling, so it was never sent.
@@ -273,6 +299,7 @@ class BatchExporter:
     def __init__(self, config: ExporterConfig, transport: httpx.BaseTransport | None = None) -> None:
         self._config = config
         self._transport = transport
+        self._http_timeout = _http_timeout()
         # Two lanes, one bound each — see _SHEDDABLE_ITEM_TYPES for why the
         # split exists, and _next_item for why the drainer reads them in this
         # order. Both are bounded: an unbounded lifecycle lane would trade a
@@ -963,7 +990,7 @@ class BatchExporter:
                 "X-API-Key": self._config.api_key,
                 "Content-Type": "application/json",
             },
-            "timeout": 30.0,
+            "timeout": self._http_timeout,
         }
         if self._transport:
             kwargs["transport"] = self._transport

{cmpnd-0.33.0 → cmpnd-0.33.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.33.0"
+version = "0.33.2"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.10"

{cmpnd-0.33.0 → cmpnd-0.33.2}/tests/e2e/conftest.py

@@ -17,6 +17,8 @@ from __future__ import annotations
 
 import os
 import time
+from collections.abc import Callable
+from typing import Any
 
 import httpx
 import pytest
@@ -118,12 +120,12 @@ def flush_and_wait(seconds: float = 3.0) -> None:
 
 
 # ---------------------------------------------------------------------------
-# ServerClient — thin wrapper around the Rails API
+# ServerClient — thin wrapper around the serve API
 # ---------------------------------------------------------------------------
 
 
 class ServerClient:
-    """HTTP client for querying the Rails API during tests."""
+    """HTTP client for querying the serve API during tests."""
 
     def __init__(self, endpoint: str, api_key: str) -> None:
         self._client = httpx.Client(
@@ -140,16 +142,44 @@ class ServerClient:
 
     # -- Traces -------------------------------------------------------------
 
-    def get_trace(self, trace_id: str, retries: int = 3, delay: float = 2.0) -> dict:
-        for attempt in range(retries):
-            resp = self._client.get(f"/api/v1/traces/{trace_id}")
-            if resp.status_code == 404 and attempt < retries - 1:
-                time.sleep(delay)
-                continue
-            resp.raise_for_status()
-            return resp.json()
-        resp.raise_for_status()
-        return resp.json()
+    def get_trace(
+        self,
+        trace_id: str,
+        *,
+        ready: Callable[[dict[str, Any]], bool] | None = None,
+        timeout: float = 60.0,
+        interval: float = 2.0,
+    ) -> dict[str, Any]:
+        """Wait for a selected trace and the fields its caller will assert."""
+        deadline = time.monotonic() + timeout
+        last_detail: dict[str, Any] | None = None
+        last_status: int | None = None
+        while (remaining := deadline - time.monotonic()) > 0:
+            try:
+                response = self._client.get(f"/api/v1/traces/{trace_id}", timeout=min(10.0, remaining))
+            except httpx.TimeoutException:
+                response = None
+            if response is not None:
+                last_status = response.status_code
+                if response.status_code == 200:
+                    detail = response.json()
+                    assert isinstance(detail, dict), f"trace {trace_id} returned a non-object detail"
+                    last_detail = detail
+                    if (ready is None or ready(detail)) and time.monotonic() <= deadline:
+                        return detail
+                elif response.status_code != 404:
+                    response.raise_for_status()
+            remaining = deadline - time.monotonic()
+            if remaining > 0:
+                time.sleep(min(interval, remaining))
+        if last_detail is None:
+            raise AssertionError(f"trace {trace_id} did not appear within {timeout}s; last HTTP status={last_status}")
+        trace = last_detail.get("trace") or last_detail
+        spans = last_detail.get("spans")
+        raise AssertionError(
+            f"trace {trace_id} did not reach the asserted state within {timeout}s; "
+            f"last trace status={trace.get('status')!r}, spans={len(spans) if isinstance(spans, list) else None}"
+        )
 
     def search_traces(self, **filters) -> dict:
         resp = self._client.post("/api/v1/traces/search", json=filters)
@@ -218,9 +248,8 @@ class ServerClient:
 def _pin_fake_lm() -> None:
     """Set dspy's active LM to the deterministic in-process fake (CMP-255).
 
-    The dummy api_key/api_base ride into deploy's ensure_provider_key on both the
-    Rails and Go tiers (see docs/plans/2026-06-11-deterministic-e2e-inference.md);
-    the fake ignores them. Only touches ``dspy.settings.lm`` — the litellm
+    The dummy api_key/api_base satisfy DSPy's LM configuration; the fake
+    ignores them. Only touches ``dspy.settings.lm`` — the litellm
     provider map (and any test-specific responder) is left alone.
     """
     import dspy

{cmpnd-0.33.0 → cmpnd-0.33.2}/tests/e2e/test_capture_prompts.py

@@ -12,6 +12,7 @@ from cmpnd.callback import CmpndCallback
 from tests.e2e.conftest import (
     CMPND_E2E_API_KEY,
     E2E_ENDPOINT,
+    ServerClient,
     flush_and_wait,
 )
 
@@ -24,7 +25,7 @@ def _is_empty(value) -> bool:
 
 
 class TestCapturePromptsDisabled:
-    def test_lm_call_inputs_empty_when_disabled(self, server_client, trace_capture):
+    def test_lm_call_inputs_empty_when_disabled(self, server_client: ServerClient, trace_capture):
         """With capture_prompts=False: LM_CALL inputs should be empty."""
         from cmpnd.exporter import ensure_exporter_started, shutdown_exporter
 
@@ -55,7 +56,16 @@ class TestCapturePromptsDisabled:
 
         trace_id = trace_capture.last_trace_id
         assert trace_id is not None
-        data = server_client.get_trace(trace_id, retries=5, delay=2.0)
+        data = server_client.get_trace(
+            trace_id,
+            ready=lambda detail: (
+                detail["trace"]["status"] == "ok"
+                and any(
+                    span.get("span_type") == "lm_call" and not _is_empty(span.get("outputs"))
+                    for span in detail["spans"]
+                )
+            ),
+        )
         spans = data["spans"]
 
         lm_spans = [s for s in spans if s.get("span_type") == "lm_call"]
@@ -74,7 +84,7 @@ class TestCapturePromptsDisabled:
 
 
 class TestCapturePromptsEnabled:
-    def test_lm_call_inputs_present_when_enabled(self, server_client, trace_capture):
+    def test_lm_call_inputs_present_when_enabled(self, server_client: ServerClient, trace_capture):
         """With capture_prompts=True: LM_CALL inputs should contain the formatted prompt."""
         # Reconfigure with capture_prompts=True
         cmpnd.configure(
@@ -99,7 +109,18 @@ class TestCapturePromptsEnabled:
 
             trace_id = trace_capture.last_trace_id
             assert trace_id is not None
-            data = server_client.get_trace(trace_id)
+            data = server_client.get_trace(
+                trace_id,
+                ready=lambda detail: (
+                    detail["trace"]["status"] == "ok"
+                    and any(
+                        span.get("span_type") == "lm_call"
+                        and not _is_empty(span.get("inputs"))
+                        and not _is_empty(span.get("outputs"))
+                        for span in detail["spans"]
+                    )
+                ),
+            )
             spans = data["spans"]
 
             lm_spans = [s for s in spans if s.get("span_type") == "lm_call"]

{cmpnd-0.33.0 → cmpnd-0.33.2}/tests/e2e/test_edge_cases.py

@@ -9,13 +9,13 @@ from __future__ import annotations
 import dspy
 import pytest
 
-from tests.e2e.conftest import flush_and_wait
+from tests.e2e.conftest import ServerClient, flush_and_wait
 
 pytestmark = pytest.mark.e2e
 
 
 class TestMultipleSequentialCalls:
-    def test_sequential_calls_distinct_traces(self, server_client, trace_capture):
+    def test_sequential_calls_distinct_traces(self, server_client: ServerClient, trace_capture):
         predict = dspy.Predict("question -> answer")
 
         # First call
@@ -33,15 +33,15 @@ class TestMultipleSequentialCalls:
         flush_and_wait()
 
         # Both traces should be on the server
-        first_data = server_client.get_trace(first_trace_id)
+        first_data = server_client.get_trace(first_trace_id, ready=lambda data: data["trace"]["status"] == "ok")
         assert first_data["trace"]["status"] == "ok"
 
-        second_data = server_client.get_trace(second_trace_id)
+        second_data = server_client.get_trace(second_trace_id, ready=lambda data: data["trace"]["status"] == "ok")
         assert second_data["trace"]["status"] == "ok"
 
 
 class TestLargeInputTruncation:
-    def test_large_input(self, server_client, trace_capture):
+    def test_large_input(self, server_client: ServerClient, trace_capture):
         predict = dspy.Predict("text -> summary")
         large_text = "The quick brown fox. " * 2000
         predict(text=large_text)
@@ -51,7 +51,19 @@ class TestLargeInputTruncation:
         trace_id = trace_capture.last_trace_id
         assert trace_id is not None
 
-        data = server_client.get_trace(trace_id)
+        def ready(data: dict) -> bool:
+            predict_spans = [
+                span
+                for span in data["spans"]
+                if span.get("span_type") == "predict" or "predict" in span.get("name", "").lower()
+            ]
+            return (
+                data["trace"]["status"] == "ok"
+                and bool(predict_spans)
+                and "text" in (predict_spans[0].get("inputs") or {})
+            )
+
+        data = server_client.get_trace(trace_id, ready=ready)
         trace = data["trace"]
         spans = data["spans"]
 

{cmpnd-0.33.0 → cmpnd-0.33.2}/tests/e2e/test_parallel_export.py

@@ -7,11 +7,14 @@ across multiple endpoint types in a single flush cycle.
 
 from __future__ import annotations
 
+from collections.abc import Callable
+from typing import Any
+
 import dspy
 import pytest
 
 from cmpnd.exporter import get_exporter
-from tests.e2e.conftest import flush_and_wait
+from tests.e2e.conftest import ServerClient, flush_and_wait
 
 pytestmark = pytest.mark.e2e
 
@@ -21,12 +24,12 @@ pytestmark = pytest.mark.e2e
 # ---------------------------------------------------------------------------
 
 
-def _fetch_trace(server_client, trace_capture):
+def _fetch_trace(server_client: ServerClient, trace_capture, ready: Callable[[dict[str, Any]], bool]):
     """Flush, then fetch the last captured trace and its spans."""
     flush_and_wait()
     trace_id = trace_capture.last_trace_id
     assert trace_id is not None, "No trace was captured"
-    data = server_client.get_trace(trace_id)
+    data = server_client.get_trace(trace_id, ready=ready)
     return data["trace"], data["spans"]
 
 
@@ -38,12 +41,21 @@ def _fetch_trace(server_client, trace_capture):
 class TestParallelExportTraceIntegrity:
     """Verify traces and spans arrive intact after parallel dispatch."""
 
-    def test_trace_with_spans_arrives_intact(self, server_client, trace_capture):
+    def test_trace_with_spans_arrives_intact(self, server_client: ServerClient, trace_capture):
         """A standard DSPy call should produce a complete trace with all spans."""
         predict = dspy.Predict("question -> answer")
         predict(question="What is the speed of light?")
 
-        trace, spans = _fetch_trace(server_client, trace_capture)
+        trace, spans = _fetch_trace(
+            server_client,
+            trace_capture,
+            lambda data: (
+                data["trace"]["program_name"] is not None
+                and data["trace"]["status"] in ("ok", "error")
+                and len(data["spans"]) >= 1
+                and all(span["span_type"] is not None and span["name"] is not None for span in data["spans"])
+            ),
+        )
 
         assert trace["program_name"] is not None
         assert trace["status"] in ("ok", "error")
@@ -54,18 +66,26 @@ class TestParallelExportTraceIntegrity:
             assert span["span_type"] is not None
             assert span["name"] is not None
 
-    def test_token_counts_populated(self, server_client, trace_capture):
+    def test_token_counts_populated(self, server_client: ServerClient, trace_capture):
         """Token counts should survive parallel serialization."""
         predict = dspy.Predict("topic -> explanation")
         predict(topic="Gravity")
 
-        trace, spans = _fetch_trace(server_client, trace_capture)
+        trace, spans = _fetch_trace(
+            server_client,
+            trace_capture,
+            lambda data: (
+                (data["trace"].get("total_tokens") or 0) > 0
+                and (data["trace"].get("prompt_tokens") or 0) > 0
+                and (data["trace"].get("completion_tokens") or 0) > 0
+            ),
+        )
 
         assert trace["total_tokens"] > 0
         assert trace["prompt_tokens"] > 0
         assert trace["completion_tokens"] > 0
 
-    def test_no_data_loss_after_parallel_flush(self, server_client, trace_capture):
+    def test_no_data_loss_after_parallel_flush(self, server_client: ServerClient, trace_capture):
         """Exporter stats should show zero drops/errors for a clean call."""
         predict = dspy.Predict("animal -> habitat")
         predict(animal="Penguin")
@@ -85,7 +105,7 @@ class TestParallelExportTraceIntegrity:
 class TestParallelExportMixedWorkload:
     """Verify multiple export types dispatched in parallel all land on server."""
 
-    def test_multiple_traces_in_quick_succession(self, server_client, trace_capture):
+    def test_multiple_traces_in_quick_succession(self, server_client: ServerClient, trace_capture):
         """Multiple DSPy calls before flush should all arrive via parallel dispatch."""
         predict = dspy.Predict("fruit -> color")
 
@@ -99,6 +119,9 @@ class TestParallelExportMixedWorkload:
 
         # Verify all traces are retrievable from the server
         for trace_id in trace_capture.trace_ids[-3:]:
-            data = server_client.get_trace(trace_id)
+            data = server_client.get_trace(
+                trace_id,
+                ready=lambda detail: detail["trace"]["status"] in ("ok", "error") and len(detail["spans"]) >= 1,
+            )
             assert data["trace"]["status"] in ("ok", "error")
             assert len(data["spans"]) >= 1