cmpnd 0.45.0__tar.gz → 0.46.0__tar.gz

{cmpnd-0.45.0 → cmpnd-0.46.0}/PKG-INFO

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

{cmpnd-0.45.0 → cmpnd-0.46.0}/cmpnd/__init__.py

@@ -15,6 +15,8 @@ Usage:
 import importlib.metadata
 from typing import TYPE_CHECKING
 
+from cmpnd_ingest.client_floor import UpgradeRequiredWarning
+
 from . import authored, programs, traces
 from ._http import ApiError
 from .callback import CmpndCallback, trace_id
@@ -111,6 +113,8 @@ __all__ = [
     "program",
     "authored",
     "ApiError",
+    # Raised once when the server no longer supports this release
+    "UpgradeRequiredWarning",
     # Types
     "SpanType",
     "TraceStatus",

{cmpnd-0.45.0 → cmpnd-0.46.0}/cmpnd/_authored_import.py

@@ -118,16 +118,14 @@ def _program_facts(
 ) -> dict[str, Any]:
     """Everything the deployment create call reads off the imported program."""
 
-    from . import configuration, deployment, identity, mcp_servers, packaging
+    from . import _http, configuration, deployment, identity, mcp_servers, packaging
     from .authored import ProgramFacts
 
     references = deployment._mcp_tool_references(program)
     pinned: dict[tuple[str, str], Any] = {}
     if references:
-        import httpx
-
         config = configuration.require_config()
-        with httpx.Client(timeout=30) as client:
+        with _http.new_client(timeout=30) as client:
             pinned = deployment._resolve_mcp_tool_references(client, config, references)
     tool_references = [
         {

{cmpnd-0.45.0 → cmpnd-0.46.0}/cmpnd/_http.py

@@ -13,8 +13,10 @@ from __future__ import annotations
 import os
 import re
 from typing import Any
+from urllib.parse import urlsplit
 
 import httpx
+from cmpnd_ingest import client_floor
 
 
 class ApiError(Exception):
@@ -76,6 +78,48 @@ def server_detail(response: httpx.Response) -> str:
     return (response.text or "").strip()[:2000]
 
 
+def new_client(**kwargs: Any) -> httpx.Client:
+    """An ``httpx.Client`` that warns when the server no longer supports this
+    release (:mod:`cmpnd_ingest.client_floor`).
+
+    Every client the SDK builds comes from here, so every answer the platform
+    sends gets the check. A caller's own ``event_hooks`` run after it.
+    """
+    hooks = client_floor.event_hooks()
+    for event, callers in (kwargs.pop("event_hooks", None) or {}).items():
+        hooks.setdefault(event, []).extend(callers)
+    return httpx.Client(event_hooks=hooks, **kwargs)
+
+
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+
+
+def _origin(url: str) -> tuple[str, str, int] | None:
+    """A URL's (scheme, host, port), or None when it cannot be read as one."""
+    try:
+        parts = urlsplit(url)
+        port = parts.port
+    except ValueError:
+        return None
+    scheme = parts.scheme.lower()
+    if scheme not in _DEFAULT_PORTS or not parts.hostname:
+        return None
+    return scheme, parts.hostname.lower(), port if port is not None else _DEFAULT_PORTS[scheme]
+
+
+def upload_auth_headers(upload_url: str, endpoint: str, api_key: str) -> dict[str, str]:
+    """The authentication header for a PUT to an ``upload_url`` serve advertised.
+
+    Serve authenticates its upload routes with the API key. The SDK sends the URL
+    as given, so the key goes only to a URL on the configured endpoint's origin:
+    the same scheme, host and port. Any other origin gets no key.
+    """
+    own = _origin(endpoint)
+    if not api_key or own is None or _origin(upload_url) != own:
+        return {}
+    return {"X-API-Key": api_key}
+
+
 class ApiClient:
     """Thin HTTP client for the cmpnd backend API."""
 
@@ -150,7 +194,7 @@ class ApiClient:
         url = f"{self._endpoint}{path}"
         timeout = self.configured_timeout()
         try:
-            with httpx.Client(
+            with new_client(
                 headers={"X-API-Key": self._api_key, "Content-Type": "application/json"},
                 timeout=timeout,
             ) as client:

{cmpnd-0.45.0 → cmpnd-0.46.0}/cmpnd/dataset_sync.py

@@ -10,9 +10,7 @@ from __future__ import annotations
 import logging
 from typing import Any
 
-import httpx
-
-from . import configuration, identity, models
+from . import _http, configuration, identity, models
 
 logger = logging.getLogger(__name__)
 
@@ -37,7 +35,7 @@ def check_dataset_exists(dataset_hash: str) -> bool:
     url = f"{config.endpoint}/api/v1/datasets/check/{dataset_hash}"
 
     try:
-        with httpx.Client(timeout=5.0) as client:
+        with _http.new_client(timeout=5.0) as client:
             response = client.get(
                 url,
                 headers={"Authorization": f"Bearer {config.api_key}"},

{cmpnd-0.45.0 → cmpnd-0.46.0}/cmpnd/datasets.py

@@ -8,9 +8,7 @@ from __future__ import annotations
 
 from typing import Any
 
-import httpx
-
-from . import configuration
+from . import _http, configuration
 
 
 class DatasetNotFoundError(Exception):
@@ -114,7 +112,7 @@ def _fetch_dataset(
         params["version"] = str(version)
 
     # Make request to backend
-    with httpx.Client(timeout=30.0) as client:
+    with _http.new_client(timeout=30.0) as client:
         response = client.get(
             url,
             params=params,

{cmpnd-0.45.0 → cmpnd-0.46.0}/cmpnd/deployment.py

@@ -17,7 +17,18 @@ from typing import Any
 
 import httpx
 
-from . import authored, configuration, deployment_metadata, execution, identity, mcp_servers, models, packaging, retry
+from . import (
+    _http,
+    authored,
+    configuration,
+    deployment_metadata,
+    execution,
+    identity,
+    mcp_servers,
+    models,
+    packaging,
+    retry,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -427,7 +438,7 @@ def deploy(module, metric=None, timeout=300, metadata=None, *, program_id=None):
     references = _mcp_tool_references(module)
     pinned_mcp_tools: dict[tuple[str, str], Any] = {}
     if references:
-        with httpx.Client(timeout=httpx.Timeout(_TIMEOUT_SECONDS, connect=_CONNECT_TIMEOUT_SECONDS)) as client:
+        with _http.new_client(timeout=httpx.Timeout(_TIMEOUT_SECONDS, connect=_CONNECT_TIMEOUT_SECONDS)) as client:
             pinned_mcp_tools = _resolve_mcp_tool_references(client, config, references)
 
     # Package the module
@@ -539,7 +550,7 @@ def _deploy_prepared(
     """Create, upload, and poll one fully prepared source bundle."""
     headers = {"X-API-Key": config.api_key, "Content-Type": "application/json"}
 
-    with httpx.Client(timeout=httpx.Timeout(_TIMEOUT_SECONDS, connect=_CONNECT_TIMEOUT_SECONDS)) as client:
+    with _http.new_client(timeout=httpx.Timeout(_TIMEOUT_SECONDS, connect=_CONNECT_TIMEOUT_SECONDS)) as client:
         created = _send_retrying(
             lambda: client.post(
                 f"{config.endpoint}/api/v1/deployments",
@@ -568,12 +579,13 @@ def _deploy_prepared(
             )
         for warning in answer.get("warnings") or []:
             logger.warning("deploy: %s", warning)
+        upload_url = answer["upload_url"]
+        upload_headers = {
+            "Content-Type": "application/zip",
+            **_http.upload_auth_headers(upload_url, config.endpoint, config.api_key),
+        }
         uploaded = _send_retrying(
-            lambda: client.put(
-                answer["upload_url"],
-                content=zip_bytes,
-                headers={"Content-Type": "application/zip"},
-            ),
+            lambda: client.put(upload_url, content=zip_bytes, headers=upload_headers),
             "upload deployment ZIP",
             may_resend_with_no_answer=lambda _: True,
             may_resend_after_answer=_repeatable_answer,

{cmpnd-0.45.0 → cmpnd-0.46.0}/cmpnd/deployment_runs.py

@@ -327,7 +327,7 @@ class _RunClient:
         self.retry_after = 0.0
 
     def __enter__(self) -> _RunClient:
-        self.client = httpx.Client(headers={"X-API-Key": self.api_key})
+        self.client = _http.new_client(headers={"X-API-Key": self.api_key})
         return self
 
     def __exit__(self, *_: object) -> None:

{cmpnd-0.45.0 → cmpnd-0.46.0}/cmpnd/mcp_servers.py

@@ -669,15 +669,14 @@ def _registered_tools(url: str, timeout_s: float) -> list[PinnedTool] | None | o
     the registry route, so notebook use keeps its existing direct connection.
     ``None`` means the configured registry answered and does not know this server.
     """
-    from . import configuration
+    from . import _http, configuration
 
     config = configuration.get_config()
     if config is None:
         return _NO_PLATFORM_REGISTRY
-    import httpx
 
     headers = {"X-API-Key": config.api_key}
-    with httpx.Client(timeout=timeout_s) as client:
+    with _http.new_client(timeout=timeout_s) as client:
         listing = client.get(f"{config.endpoint}/api/v1/org/tool-servers", headers=headers)
         if listing.status_code == 404:
             return _NO_PLATFORM_REGISTRY

{cmpnd-0.45.0 → cmpnd-0.46.0}/cmpnd/optimization.py

@@ -1008,7 +1008,7 @@ def _run_steps(
     current_deployment_id = deployment_id
     non_improving = 0
 
-    with httpx.Client(timeout=_HTTP_TIMEOUT_SECONDS) as client:
+    with _http.new_client(timeout=_HTTP_TIMEOUT_SECONDS) as client:
         for step in range(max_steps):
             data = "upload" if step == 0 else "reuse"
             step_config = dict(config)
@@ -1031,7 +1031,7 @@ def _run_steps(
             optimization_id = initiated["optimization_id"]
 
             if data == "upload":
-                _upload_bundle(client, initiated, bundle)
+                _upload_bundle(client, initiated, bundle, endpoint=cfg.endpoint, api_key=cfg.api_key)
 
             status = _poll_until_terminal(
                 client,
@@ -1243,7 +1243,7 @@ def _refuse_conflicting_members(
     headers = {"X-API-Key": cfg.api_key}
     conflicting: list[str] = []
     try:
-        with httpx.Client(timeout=_HTTP_TIMEOUT_SECONDS) as client:
+        with _http.new_client(timeout=_HTTP_TIMEOUT_SECONDS) as client:
             listing = client.get(f"{cfg.endpoint}/api/v1/deployments/{deployment_id}/source", headers=headers)
             if not listing.is_success:
                 return
@@ -1414,26 +1414,21 @@ def _initiate_step(
     )
 
 
-def _upload_bundle(client: httpx.Client, initiated: dict[str, Any], bundle: bytes) -> None:
+def _upload_bundle(
+    client: httpx.Client, initiated: dict[str, Any], bundle: bytes, *, endpoint: str, api_key: str
+) -> None:
     """Upload the optimization bundle to the slot the initiate step returned.
 
-    Two postures, one path — keyed on ``upload_fields`` exactly as the deploy
-    upload is:
-
-    - **Presigned POST** (the deploy Lambda stack): ``upload_fields`` is a
-      non-empty form the destination key is pinned by; the bundle rides as the
-      ``file`` part of a multipart POST.
-    - **PUT** (the on-prem worker-sandbox): no form fields — the URL *is* the
-      slot. The bundle is the raw PUT body.
-
-    serve normalizes the awaiting_data response so both keys are always present
-    (``upload_method`` defaulting to PUT, ``upload_fields`` to ``{}``), so the
-    branch here is just "are there presigned fields to post."
+    Serve answers an ``awaiting_data`` initiate with ``upload_url``, ``upload_method:
+    "PUT"`` and empty ``upload_fields``, and the bundle goes out as the raw PUT body.
+    Serve authenticates that route with the API key, which rides the PUT only when
+    ``upload_url`` is on ``endpoint``'s origin (``_http.upload_auth_headers``). A
+    non-empty ``upload_fields`` is a presigned form, which no current server sends.
+    The bundle then rides as the ``file`` part of a multipart POST.
 
-    Both postures write to a slot the destination key is already pinned to, so
-    re-sending the same bytes overwrites the same object — this call is
-    idempotent by construction, and rides through a transient answer *and* a
-    transport blip alike.
+    The slot pins its destination, so re-sending the same bytes writes the same
+    object. That makes this call idempotent, so it rides through a transient answer
+    and a transport blip alike.
     """
     upload_url = initiated.get("upload_url")
     if not upload_url:
@@ -1441,6 +1436,7 @@ def _upload_bundle(client: httpx.Client, initiated: dict[str, Any], bundle: byte
     upload_fields = initiated.get("upload_fields")
     method = (initiated.get("upload_method") or ("POST" if upload_fields else "PUT")).upper()
     what = "upload optimization bundle"
+    auth = _http.upload_auth_headers(upload_url, endpoint, api_key)
 
     if upload_fields:
         resp = _request(
@@ -1448,6 +1444,7 @@ def _upload_bundle(client: httpx.Client, initiated: dict[str, Any], bundle: byte
                 upload_url,
                 data=dict(upload_fields),
                 files={"file": ("data.zip", bundle, "application/zip")},
+                headers=auth,
             ),
             what,
         )
@@ -1457,7 +1454,7 @@ def _upload_bundle(client: httpx.Client, initiated: dict[str, Any], bundle: byte
                 method,
                 upload_url,
                 content=bundle,
-                headers={"Content-Type": "application/zip"},
+                headers={"Content-Type": "application/zip", **auth},
             ),
             what,
         )

{cmpnd-0.45.0 → cmpnd-0.46.0}/docs/cli.md

@@ -32,6 +32,16 @@ retries, because a second send would create a second program.
 `cmpnd.programs.create(name=...)` makes the same call from Python and returns
 the row.
 
+## When the server no longer supports your release
+
+Every answer from the platform names the oldest `cmpnd` release it supports.
+When yours is older, the CLI and the SDK warn once per process and name the
+upgrade, `pip install -U cmpnd`. The server still answers, so an older release
+keeps working wherever nothing it relies on has changed. To stay on an older
+release without the warning, set `CMPND_NO_UPGRADE_WARNING=1`. In code,
+`warnings.filterwarnings("ignore", category=cmpnd.UpgradeRequiredWarning)`
+does the same.
+
 ## Deploy flow (Docker-style)
 
 These commands print human-readable output by default. Each takes `--json` for

{cmpnd-0.45.0 → cmpnd-0.46.0}/docs/sdk-instrumentation.md

@@ -306,6 +306,10 @@ Two callers implement the waiting:
 - **`exporter_http._send_json_retrying`** waits on the shutdown event rather than sleeping, so a backoff can't hold the process open at exit (and the post-shutdown drain gets no retries at all, deliberately).
 - **`optimization._request`** clips every wait by the caller's `timeout` deadline, which stays the outer bound of `optimize()`. See [the optimize loop](#the-optimize-loop-and-transient-tolerance) below.
 
+### The server says when this release is too old
+
+Every API answer names the oldest cmpnd release the server supports, in the `X-Cmpnd-Minimum-Client-Version` header. `cmpnd_ingest/client_floor.py` reads it in an httpx response hook. When the installed `cmpnd` is older, it raises an `UpgradeRequiredWarning` once per process that names both versions and the command `pip install -U cmpnd`. The server refuses nothing for a client's version, so a call below the floor still goes through, and the warning appears beside whatever it does. Every client the SDK builds comes from `cmpnd._http.new_client`, which installs the hook, and the exporter installs it in `_client_kwargs`. `tests/test_client_floor.py` fails on an `httpx.Client` built any other way in `cmpnd/`. An install of `cmpnd_ingest` without `cmpnd` has no version to compare and says nothing. `CMPND_NO_UPGRADE_WARNING=1` silences the warning for a user who stays on an older release on purpose, and the warning names that switch. `cmpnd.UpgradeRequiredWarning` is public, so a `warnings` filter silences it in code.
+
 ### The optimize loop and transient tolerance
 
 `optimization._poll_until_terminal` is what a caller blocks on for the length of a run, so one transient answer or one reset connection must not destroy a healthy run. It rides through transient answers on the shared budget, resetting after each successful poll, and never extends past the caller's `timeout` (default 600s per step) — a backoff wait is clipped by the deadline rather than overshooting it.
@@ -354,6 +358,11 @@ done.
 | `PUT upload_url` (the ZIP) | retried — the slot pins the key and the bytes are fixed, so a re-send overwrites the same object | retried, for the same reason |
 | `GET /api/v1/deployments/{id}` (poll) | retried on the next tick — a read is repeatable | retried on the next tick |
 
+Serve authenticates its upload routes with the API key. The deploy upload and
+the optimization bundle upload send `X-API-Key` when `upload_url` has the
+configured endpoint's scheme, host and port (`_http.upload_auth_headers`). A URL
+on any other origin gets no key.
+
 After the poll reports ready, the SDK reads
 `GET /api/v1/deployments/{id}/signature`. This bounded read returns persisted
 artifact metadata and never asks a worker or analytics store. A failed metadata

cmpnd-0.46.0/ingest/cmpnd_ingest/client_floor.py

@@ -0,0 +1,101 @@
+"""Tell the user when the server no longer supports this cmpnd release.
+
+The server names the oldest cmpnd release it supports on every API answer, in
+the ``X-Cmpnd-Minimum-Client-Version`` header. A client older than that may
+still work, and the server refuses nothing for it, but the server promises
+nothing either. So the first answer that names a floor above this client's
+version raises an :class:`UpgradeRequiredWarning` that says how to upgrade. It
+appears once per process, beside whatever the call then does.
+
+A user who stays on an older release on purpose silences the warning with
+``CMPND_NO_UPGRADE_WARNING=1`` in the environment, or in code with
+``warnings.filterwarnings("ignore", category=cmpnd.UpgradeRequiredWarning)``.
+
+The check runs as an httpx response hook (:func:`event_hooks`) on every client
+the SDK builds, so no call site has to remember it. It compares against the
+installed ``cmpnd`` distribution and does nothing when ``cmpnd`` is not
+installed, because the floor is about ``cmpnd``.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import os
+import re
+import threading
+import warnings
+from collections.abc import Callable
+
+import httpx
+
+HEADER = "X-Cmpnd-Minimum-Client-Version"
+
+# Set to "1" to silence the warning, matching the SDK's other switches.
+SILENCE_ENV = "CMPND_NO_UPGRADE_WARNING"
+
+_RELEASE = re.compile(r"(\d+)\.(\d+)\.(\d+)")
+
+
+class UpgradeRequiredWarning(UserWarning):
+    """The server supports no cmpnd release older than the one it names."""
+
+
+_warned: set[str] = set()
+_lock = threading.Lock()
+
+
+def _reset_lock_after_fork() -> None:
+    """Give a forked child a lock of its own.
+
+    A fork copies ``_lock`` as it stood, and a thread that held it does not exist
+    in the child, so the child's first check would block forever. The exporter
+    resets its own locks after a fork for the same reason.
+    """
+    global _lock
+    _lock = threading.Lock()
+
+
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_reset_lock_after_fork)
+
+
+def _installed_version() -> str | None:
+    try:
+        return importlib.metadata.version("cmpnd")
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def _release(version: str) -> tuple[int, int, int] | None:
+    match = _RELEASE.match(version.strip())
+    if match is None:
+        return None
+    major, minor, patch = match.groups()
+    return int(major), int(minor), int(patch)
+
+
+def check_client_floor(response: httpx.Response) -> None:
+    """Warn once when the answer names a floor above this client's version."""
+    floor = response.headers.get(HEADER)
+    if not floor or os.environ.get(SILENCE_ENV) == "1":
+        return
+    mine = _installed_version()
+    floor_release = _release(floor)
+    mine_release = _release(mine) if mine else None
+    if floor_release is None or mine_release is None or mine_release >= floor_release:
+        return
+    with _lock:
+        if floor in _warned:
+            return
+        _warned.add(floor)
+    warnings.warn(
+        f"cmpnd {mine} is older than the oldest release this server supports ({floor.strip()}). "
+        f"Upgrade with: pip install -U cmpnd (or set {SILENCE_ENV}=1 to stay on this release quietly)",
+        UpgradeRequiredWarning,
+        stacklevel=2,
+    )
+
+
+def event_hooks() -> dict[str, list[Callable[[httpx.Response], None]]]:
+    """The ``event_hooks`` argument that installs the check on an httpx client."""
+    return {"response": [check_client_floor]}

{cmpnd-0.45.0 → cmpnd-0.46.0}/ingest/cmpnd_ingest/exporter_http.py

@@ -34,7 +34,7 @@ from typing import Any, cast
 
 import httpx
 
-from . import program_names, request_log, retry
+from . import client_floor, program_names, request_log, retry
 from .bodies import EncodedTraceBody, TraceBody
 from .protocols import (
     EvalRunRecord,
@@ -1029,8 +1029,8 @@ class BatchExporter:
 
     def _client_kwargs(self) -> dict[str, Any]:
         """Shared httpx.Client construction args for the background and sync
-        clients, so both carry the same base URL, auth header, and (in tests)
-        injected transport."""
+        clients, so both carry the same base URL, auth header, client-floor
+        check (``client_floor``) and, in tests, injected transport."""
         kwargs: dict[str, Any] = {
             "base_url": self._config.endpoint,
             "headers": {
@@ -1038,6 +1038,7 @@ class BatchExporter:
                 "Content-Type": "application/json",
             },
             "timeout": self._http_timeout,
+            "event_hooks": client_floor.event_hooks(),
         }
         if self._transport:
             kwargs["transport"] = self._transport

{cmpnd-0.45.0 → cmpnd-0.46.0}/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.45.0"
+version = "0.46.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"

{cmpnd-0.45.0 → cmpnd-0.46.0}/tests/integration/conftest.py

@@ -27,6 +27,8 @@ import os
 import httpx
 import pytest
 
+from cmpnd._http import upload_auth_headers
+
 CMPND_API_KEY = os.environ.get("CMPND_API_KEY")
 CMPND_ENDPOINT = os.environ.get("CMPND_ENDPOINT", "http://localhost:3000")
 CMPND_STUB_URL = os.environ.get("CMPND_STUB_URL", "http://localhost:9292")
@@ -77,18 +79,17 @@ def parser_running(stub_health: dict) -> None:
 
 
 def upload_deploy_zip(create_resp: dict, zip_bytes: bytes) -> None:
-    """Upload a deploy ZIP via the single PUT slot the server returns.
+    """Upload a deploy ZIP to the PUT slot the create response names.
 
-    Slice E: both postures advertise ``upload_method: "PUT"`` and one
-    ``upload_url`` — a presigned S3 PUT (hosted) or the worker's own
-    ``/programs/{id}/source`` (on-prem). Raw body, no form. Mirrors
-    ``cmpnd.deploy``'s upload step so integration tests can drive it without
-    the SDK's full deploy() wrapper.
+    Mirrors ``cmpnd.deploy``'s upload step, API key included when ``upload_url``
+    is on the endpoint's origin, so integration tests can drive it without the
+    SDK's full deploy() wrapper.
     """
-    with httpx.Client(timeout=30.0) as anon:
-        resp = anon.put(
-            create_resp["upload_url"],
-            content=zip_bytes,
-            headers={"Content-Type": "application/zip"},
-        )
+    upload_url = create_resp["upload_url"]
+    headers = {
+        "Content-Type": "application/zip",
+        **upload_auth_headers(upload_url, CMPND_ENDPOINT, CMPND_API_KEY or ""),
+    }
+    with httpx.Client(timeout=30.0) as client:
+        resp = client.put(upload_url, content=zip_bytes, headers=headers)
         resp.raise_for_status()