cmpnd 0.85.1__tar.gz → 0.85.2__tar.gz

{cmpnd-0.85.1 → cmpnd-0.85.2}/PKG-INFO

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

{cmpnd-0.85.1 → cmpnd-0.85.2}/cmpnd/_http.py

@@ -16,7 +16,7 @@ from typing import Any
 from urllib.parse import urlsplit
 
 import httpx
-from cmpnd_ingest import client_floor
+from cmpnd_ingest import client_floor, user_agent
 
 
 class ApiError(Exception):
@@ -79,16 +79,22 @@ def server_detail(response: httpx.Response) -> str:
 
 
 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`).
+    """An ``httpx.Client`` that names this release to the server and warns when
+    the server no longer supports it (: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.
+    Every client the SDK builds comes from here, so every request carries the
+    release's ``User-Agent`` (:mod:`cmpnd_ingest.user_agent`) and every answer
+    the platform sends gets the check. A caller's own ``headers`` override the
+    ``User-Agent``, and its own ``event_hooks`` run after the check.
     """
     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)
+    # httpx.Headers matches names without regard to case, so a caller's `user-agent`
+    # replaces the default rather than travelling beside it.
+    headers = httpx.Headers(user_agent.headers())
+    headers.update(kwargs.pop("headers", None) or {})
+    return httpx.Client(event_hooks=hooks, headers=headers, **kwargs)
 
 
 _DEFAULT_PORTS = {"http": 80, "https": 443}

{cmpnd-0.85.1 → cmpnd-0.85.2}/docs/sdk-instrumentation.md

@@ -373,6 +373,8 @@ Two callers implement the waiting:
 
 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.
 
+Every request names its release in the other direction, so the server can count which releases are in use. `cmpnd_ingest/user_agent.py` builds the `User-Agent` value, such as `cmpnd/0.85.2 python/3.12.13 httpx/0.28.1 dspy/3.4.1`. The first product is `cmpnd` for the SDK and `cmpnd-ingest` for a producer that installs only the transport, such as the optimizer's search process. A library that is not installed is left out. `cmpnd._http.new_client` and the exporter's `_client_kwargs` both send it. A caller that passes its own `User-Agent` to `new_client` keeps it. `tests/test_user_agent.py` checks the value that reaches the wire.
+
 ### 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.

{cmpnd-0.85.1 → cmpnd-0.85.2}/ingest/cmpnd_ingest/exporter_http.py

@@ -34,7 +34,7 @@ from typing import Any, cast
 
 import httpx
 
-from . import client_floor, program_names, request_log, retry
+from . import client_floor, program_names, request_log, retry, user_agent
 from .bodies import EncodedTraceBody, SpanBody, TraceBody
 from .protocols import (
     EvalRunRecord,
@@ -1106,11 +1106,13 @@ 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, client-floor
-        check (``client_floor``) and, in tests, injected transport."""
+        clients, so both carry the same base URL, auth header, release
+        ``User-Agent`` (``user_agent``), client-floor check (``client_floor``)
+        and, in tests, injected transport."""
         kwargs: dict[str, Any] = {
             "base_url": self._config.endpoint,
             "headers": {
+                **user_agent.headers(),
                 "X-API-Key": self._config.api_key,
                 "Content-Type": "application/json",
             },

cmpnd-0.85.2/ingest/cmpnd_ingest/user_agent.py

@@ -0,0 +1,52 @@
+"""The ``User-Agent`` every client the SDK builds sends, so the server can count releases.
+
+The value names the installed distribution first, then the runtime it runs on:
+
+    cmpnd/0.85.2 python/3.12.13 httpx/0.28.1 dspy/3.4.1
+
+The first product is ``cmpnd`` for the SDK and ``cmpnd-ingest`` for a producer that
+installs only the transport, so the two never count as one. A distribution that is not
+installed, such as ``dspy`` for a transport-only producer, is left out. A value that
+cannot be read becomes ``unknown`` rather than failing a request.
+"""
+
+from __future__ import annotations
+
+import functools
+import importlib.metadata
+import platform
+
+# The distributions that provide this package, in the order the first one found names
+# the client. Only one is installed at a time (ingest/README.md).
+_CLIENTS = ("cmpnd", "cmpnd-ingest")
+# Runtime libraries whose version shapes what a client sends.
+_LIBRARIES = ("httpx", "dspy")
+
+
+def _version(distribution: str) -> str | None:
+    """The installed version, or None when it is not installed or cannot be read.
+
+    Any failure to read metadata counts as absent, because a broken install's
+    metadata must not stop a client from being built.
+    """
+    try:
+        return importlib.metadata.version(distribution)
+    except Exception:
+        return None
+
+
+@functools.cache
+def user_agent() -> str:
+    """The ``User-Agent`` header value for this process."""
+    client = next(
+        (f"{name}/{version}" for name in _CLIENTS if (version := _version(name)) is not None),
+        "cmpnd/unknown",
+    )
+    products = [client, f"python/{platform.python_version()}"]
+    products += [f"{name}/{version}" for name in _LIBRARIES if (version := _version(name)) is not None]
+    return " ".join(products)
+
+
+def headers() -> dict[str, str]:
+    """The headers that identify this client, to merge into a client's own."""
+    return {"User-Agent": user_agent()}

{cmpnd-0.85.1 → cmpnd-0.85.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.85.1"
+version = "0.85.2"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"

cmpnd-0.85.2/tests/test_user_agent.py

@@ -0,0 +1,109 @@
+"""Every client the SDK builds names its release in ``User-Agent``, so the server can
+count which releases are in use.
+
+Driven over real ``httpx.Client`` instances with ``MockTransport``: the property is
+what reaches the wire.
+"""
+
+from __future__ import annotations
+
+import platform
+from collections.abc import Iterator
+
+import httpx
+import pytest
+from cmpnd_ingest import user_agent
+
+import cmpnd
+from cmpnd import _http
+from cmpnd.configuration import Config
+from cmpnd.exporter import BatchExporter
+
+
+@pytest.fixture(autouse=True)
+def _fresh_user_agent() -> Iterator[None]:
+    user_agent.user_agent.cache_clear()
+    yield
+    user_agent.user_agent.cache_clear()
+
+
+def _sent_user_agent(client: httpx.Client, requests: list[httpx.Request]) -> str:
+    with client:
+        client.get("https://app.cmpnd.ai/api/v1/deployments")
+    assert len(requests) == 1
+    return requests[0].headers["User-Agent"]
+
+
+def _capturing(requests: list[httpx.Request]) -> httpx.MockTransport:
+    def handle(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        return httpx.Response(200, json={})
+
+    return httpx.MockTransport(handle)
+
+
+def test_the_user_agent_names_the_release_python_and_libraries() -> None:
+    products = user_agent.user_agent().split(" ")
+    assert products[0] == f"cmpnd/{cmpnd.__version__}"
+    assert products[1] == f"python/{platform.python_version()}"
+    assert f"httpx/{httpx.__version__}" in products
+
+
+def test_an_api_client_sends_the_release_user_agent() -> None:
+    requests: list[httpx.Request] = []
+    sent = _sent_user_agent(_http.new_client(transport=_capturing(requests)), requests)
+    assert sent == user_agent.user_agent()
+    assert sent.startswith(f"cmpnd/{cmpnd.__version__} ")
+
+
+def test_a_callers_own_user_agent_wins() -> None:
+    requests: list[httpx.Request] = []
+    client = _http.new_client(transport=_capturing(requests), headers={"User-Agent": "mine/1"})
+    assert _sent_user_agent(client, requests) == "mine/1"
+
+
+@pytest.mark.parametrize("name", ["user-agent", "USER-AGENT"])
+def test_a_callers_user_agent_wins_in_any_case(name: str) -> None:
+    requests: list[httpx.Request] = []
+    client = _http.new_client(transport=_capturing(requests), headers={name: "mine/1"})
+    _sent_user_agent(client, requests)
+    assert requests[0].headers.get_list("User-Agent") == ["mine/1"]
+
+
+def test_a_callers_httpx_headers_win() -> None:
+    requests: list[httpx.Request] = []
+    client = _http.new_client(transport=_capturing(requests), headers=httpx.Headers({"User-Agent": "mine/1"}))
+    _sent_user_agent(client, requests)
+    assert requests[0].headers.get_list("User-Agent") == ["mine/1"]
+
+
+def test_the_exporter_sends_the_release_user_agent() -> None:
+    requests: list[httpx.Request] = []
+    exporter = BatchExporter(Config(api_key="k", endpoint="http://localhost:9999"), transport=_capturing(requests))
+    sent = _sent_user_agent(httpx.Client(**exporter._client_kwargs()), requests)
+    assert sent == user_agent.user_agent()
+    assert requests[0].headers["X-API-Key"] == "k"
+
+
+def test_a_transport_only_producer_names_itself(monkeypatch: pytest.MonkeyPatch) -> None:
+    versions = {"cmpnd-ingest": "0.1.0", "httpx": "0.28.1"}
+    monkeypatch.setattr(user_agent, "_version", versions.get)
+    assert user_agent.user_agent() == f"cmpnd-ingest/0.1.0 python/{platform.python_version()} httpx/0.28.1"
+
+
+def test_an_unreadable_release_still_sends_a_user_agent(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(user_agent, "_version", lambda _name: None)
+    assert user_agent.user_agent() == f"cmpnd/unknown python/{platform.python_version()}"
+
+
+def test_unreadable_metadata_still_builds_both_clients(monkeypatch: pytest.MonkeyPatch) -> None:
+    def broken(_name: str) -> str:
+        raise OSError("metadata unreadable")
+
+    monkeypatch.setattr(user_agent.importlib.metadata, "version", broken)
+    requests: list[httpx.Request] = []
+    expected = f"cmpnd/unknown python/{platform.python_version()}"
+    assert _sent_user_agent(_http.new_client(transport=_capturing(requests)), requests) == expected
+    requests.clear()
+    exporter = BatchExporter(Config(api_key="k", endpoint="http://localhost:9999"), transport=_capturing(requests))
+    assert _sent_user_agent(httpx.Client(**exporter._client_kwargs()), requests) == expected

{cmpnd-0.85.1 → cmpnd-0.85.2}/uv.lock

@@ -505,7 +505,7 @@ wheels = [
 
 [[package]]
 name = "cmpnd"
-version = "0.85.1"
+version = "0.85.2"
 source = { editable = "." }
 default-groups = ["dspy-3-4-1"]
 dependencies = [