cmpnd 0.18.2__tar.gz → 0.19.0__tar.gz

{cmpnd-0.18.2 → cmpnd-0.19.0}/PKG-INFO

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

{cmpnd-0.18.2 → cmpnd-0.19.0}/cmpnd/__init__.py

@@ -14,6 +14,8 @@ Usage:
 
 import importlib.metadata
 
+from . import traces
+from ._http import ApiError
 from .callback import CmpndCallback, trace_id
 from .configuration import configure, get_config, require_config
 from .context import (
@@ -67,6 +69,9 @@ __all__ = [
     # Cleanup
     "flush_exporter",
     "shutdown_exporter",
+    # Programmatic backend reads (cmpnd.traces.list / cmpnd.traces.show)
+    "traces",
+    "ApiError",
     # Types
     "SpanType",
     "TraceStatus",

cmpnd-0.18.2/cmpnd/cli/api_client.py → cmpnd-0.19.0/cmpnd/_http.py

@@ -1,4 +1,12 @@
-"""HTTP client for the cmpnd CLI."""
+"""Shared HTTP transport for the cmpnd backend API.
+
+Two surfaces reach the backend: the CLI (``cmpnd.cli.api_client``) and the
+programmatic library client (``cmpnd.Client``). Both send every request through
+the one transport here, so they cannot drift on base-URL handling, the API-key
+header, the timeout, or the error ladder. The CLI keeps its own credential
+resolution and argparse glue on top; the library client keeps its own config
+resolution; this module is only the wire.
+"""
 
 from __future__ import annotations
 
@@ -7,37 +15,23 @@ from typing import Any
 
 import httpx
 
-from . import credentials
 
+class ApiError(Exception):
+    """An error from a cmpnd backend request.
 
-class CliError(Exception):
-    """CLI error with an exit code."""
+    ``status_code`` is the HTTP status when the server answered one, or ``None``
+    for a transport-level failure (could not connect, timed out). ``exit_code``
+    is the process exit the CLI maps the error to; the library client ignores it.
+    """
 
-    def __init__(self, message: str, exit_code: int = 1):
+    def __init__(self, message: str, exit_code: int = 1, *, status_code: int | None = None):
         super().__init__(message)
         self.exit_code = exit_code
-
-
-def resolve_endpoint(args: Any) -> str:
-    return getattr(args, "endpoint", None) or os.getenv("CMPND_ENDPOINT", "https://platform.cmpnd.ai")
-
-
-def resolve_config(args: Any) -> tuple[str, str]:
-    """Resolve API key and endpoint.
-
-    Order: ``--api-key`` flag → ``CMPND_API_KEY`` env → stored credentials
-    (keyed by endpoint). The stored-credentials fallback is what makes
-    ``cmpnd login`` stick across shell sessions.
-    """
-    endpoint = resolve_endpoint(args)
-    api_key = getattr(args, "api_key", None) or os.getenv("CMPND_API_KEY") or credentials.load(endpoint)
-    if not api_key:
-        raise CliError("Not logged in. Run `cmpnd login`, pass --api-key, or set CMPND_API_KEY.")
-    return api_key, endpoint
+        self.status_code = status_code
 
 
 class ApiClient:
-    """Thin HTTP client for the cmpnd observe API."""
+    """Thin HTTP client for the cmpnd backend API."""
 
     def __init__(self, api_key: str, endpoint: str):
         self._api_key = api_key
@@ -89,7 +83,7 @@ class ApiClient:
         try:
             timeout = float(raw_timeout)
         except ValueError:
-            raise CliError(f"Invalid CMPND_HTTP_TIMEOUT={raw_timeout!r}; expected a number of seconds.")
+            raise ApiError(f"Invalid CMPND_HTTP_TIMEOUT={raw_timeout!r}; expected a number of seconds.")
         try:
             with httpx.Client(
                 headers={"X-API-Key": self._api_key, "Content-Type": "application/json"},
@@ -110,14 +104,14 @@ class ApiClient:
                 else:
                     response = client.post(url, json=json)
         except httpx.ConnectError:
-            raise CliError(f"Could not connect to {self._endpoint}. Check CMPND_ENDPOINT.")
+            raise ApiError(f"Could not connect to {self._endpoint}. Check CMPND_ENDPOINT.")
         except httpx.TimeoutException:
-            raise CliError(f"Request timed out connecting to {self._endpoint}.")
+            raise ApiError(f"Request timed out connecting to {self._endpoint}.")
 
         if response.status_code == 401:
-            raise CliError("Invalid or missing API key. Check CMPND_API_KEY or --api-key.")
+            raise ApiError("Invalid or missing API key. Check CMPND_API_KEY or --api-key.", status_code=401)
         if response.status_code == 404:
-            raise CliError("Resource not found.")
+            raise ApiError("Resource not found.", status_code=404)
         if response.status_code >= 500:
             # 5xx usually means the server is up but blew up handling the
             # request — a database hiccup, an unhandled exception, etc.
@@ -129,13 +123,13 @@ class ApiClient:
             if body_excerpt:
                 msg += f": {body_excerpt}"
             msg += "\n  If you operate this server, check its logs for the underlying exception."
-            raise CliError(msg, exit_code=2)
+            raise ApiError(msg, exit_code=2, status_code=response.status_code)
         if response.status_code >= 400:
             try:
                 detail = response.json()
             except Exception:
                 detail = response.text
-            raise CliError(f"Request failed ({response.status_code}): {detail}")
+            raise ApiError(f"Request failed ({response.status_code}): {detail}", status_code=response.status_code)
 
         # A non-JSON route hands its body back verbatim. Checked before the
         # empty-body arm so such a route answers "" rather than None, which is

cmpnd-0.19.0/cmpnd/_timespec.py

@@ -0,0 +1,45 @@
+"""Search time-bound sugar, shared by the CLI and the library read client.
+
+A search lower/upper bound may be written three ways: an ISO 8601 timestamp, a
+bare date (``YYYY-MM-DD``), or a duration back from now (``30d``, ``2w``,
+``12h``, ``90m``). Both surfaces resolve it the same way here, so ``--since 30d``
+on the command line and ``since="30d"`` in the library mean one thing. The sugar
+lives at the client edge rather than on the wire, so the API stays timestamp-only
+— one grammar for every client, resolved once at the edge that knows what "now"
+means to the user.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+
+_RELATIVE_TIME = re.compile(r"^(\d+)([mhdw])$")
+_BARE_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+_RELATIVE_UNITS = {
+    "m": "minutes",
+    "h": "hours",
+    "d": "days",
+    "w": "weeks",
+}
+
+
+def resolve_search_time(value: str, *, end_of_day: bool = False) -> str:
+    """Resolve a search bound to an ISO 8601 timestamp.
+
+    A duration (``30d``, ``2w``, ``12h``, ``90m``) means that far back from now;
+    a bare date (``YYYY-MM-DD``) resolves to that whole day in UTC — start of day
+    normally, end of day (``23:59:59Z``) when ``end_of_day`` is set, so an upper
+    bound of ``2026-07-15`` includes all of the 15th; anything else passes through
+    for the server to parse.
+    """
+    text = value.strip()
+    if _BARE_DATE.match(text):
+        return f"{text}T23:59:59Z" if end_of_day else f"{text}T00:00:00Z"
+    m = _RELATIVE_TIME.match(text)
+    if not m:
+        return value
+    amount, unit = int(m.group(1)), m.group(2)
+    when = datetime.now(timezone.utc) - timedelta(**{_RELATIVE_UNITS[unit]: amount})
+    return when.replace(microsecond=0).isoformat().replace("+00:00", "Z")

cmpnd-0.19.0/cmpnd/cli/api_client.py

@@ -0,0 +1,42 @@
+"""CLI credential resolution over the shared HTTP transport.
+
+The transport itself (``ApiClient``) and its error (``ApiError``) live in
+``cmpnd._http`` so the CLI and the programmatic library client share one wire.
+This module adds the CLI-only pieces on top: reading the endpoint and API key
+from ``--api-key`` / ``--endpoint`` flags, the environment, and the stored login
+credentials. ``CliError`` is the historical CLI name for the shared error and
+stays as an alias so existing handlers keep raising and catching it.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from .. import _http
+from . import credentials
+
+# The shared transport and its error, re-exported under the names the CLI has
+# always used. `CliError` is `ApiError` — the CLI names it for the process exit
+# it carries; both are the same class.
+ApiClient = _http.ApiClient
+ApiError = _http.ApiError
+CliError = _http.ApiError
+
+
+def resolve_endpoint(args: Any) -> str:
+    return getattr(args, "endpoint", None) or os.getenv("CMPND_ENDPOINT", "https://platform.cmpnd.ai")
+
+
+def resolve_config(args: Any) -> tuple[str, str]:
+    """Resolve API key and endpoint.
+
+    Order: ``--api-key`` flag → ``CMPND_API_KEY`` env → stored credentials
+    (keyed by endpoint). The stored-credentials fallback is what makes
+    ``cmpnd login`` stick across shell sessions.
+    """
+    endpoint = resolve_endpoint(args)
+    api_key = getattr(args, "api_key", None) or os.getenv("CMPND_API_KEY") or credentials.load(endpoint)
+    if not api_key:
+        raise CliError("Not logged in. Run `cmpnd login`, pass --api-key, or set CMPND_API_KEY.")
+    return api_key, endpoint

{cmpnd-0.18.2 → cmpnd-0.19.0}/cmpnd/cli/commands/traces.py

@@ -3,13 +3,12 @@
 from __future__ import annotations
 
 import json
-import re
 import sys
 import time
 from argparse import ArgumentParser, ArgumentTypeError, _SubParsersAction
-from datetime import datetime, timedelta, timezone
 from typing import Any
 
+from ... import _timespec
 from .. import api_client, deprecation, pagination, trace_render
 
 
@@ -161,39 +160,6 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     follow.set_defaults(func=handle_follow)
 
 
-_RELATIVE_TIME = re.compile(r"^(\d+)([mhdw])$")
-_BARE_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
-
-_RELATIVE_UNITS = {
-    "m": "minutes",
-    "h": "hours",
-    "d": "days",
-    "w": "weeks",
-}
-
-
-def resolve_search_time(value: str, *, end_of_day: bool = False) -> str:
-    """Resolve a search bound to an ISO 8601 timestamp.
-
-    A duration (``30d``, ``2w``, ``12h``, ``90m``) means that far back from now;
-    a bare date (``YYYY-MM-DD``) resolves to that whole day in UTC — start of day
-    normally, end of day (``23:59:59Z``) when ``end_of_day`` is set, so an upper
-    bound of ``2026-07-15`` includes all of the 15th; anything else passes through
-    for the server to parse. The sugar lives here rather than in the API so the
-    wire stays timestamp-only — one grammar for every client, resolved once at the
-    edge that knows what "now" means to the user.
-    """
-    text = value.strip()
-    if _BARE_DATE.match(text):
-        return f"{text}T23:59:59Z" if end_of_day else f"{text}T00:00:00Z"
-    m = _RELATIVE_TIME.match(text)
-    if not m:
-        return value
-    amount, unit = int(m.group(1)), m.group(2)
-    when = datetime.now(timezone.utc) - timedelta(**{_RELATIVE_UNITS[unit]: amount})
-    return when.replace(microsecond=0).isoformat().replace("+00:00", "Z")
-
-
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
     max_window = bool(getattr(args, "max_window", False))
     if max_window and (getattr(args, "start_time_from", None) or getattr(args, "start_time_to", None)):
@@ -234,9 +200,9 @@ def handle_list(client: api_client.ApiClient, args: Any) -> Any:
     # The lower bound resolves to the start of a bare date, the upper bound to
     # the end of it, so `--until 2026-07-15` includes all of the 15th.
     if "start_time_from" in body:
-        body["start_time_from"] = resolve_search_time(str(body["start_time_from"]))
+        body["start_time_from"] = _timespec.resolve_search_time(str(body["start_time_from"]))
     if "start_time_to" in body:
-        body["start_time_to"] = resolve_search_time(str(body["start_time_to"]), end_of_day=True)
+        body["start_time_to"] = _timespec.resolve_search_time(str(body["start_time_to"]), end_of_day=True)
     resp = client.post("/api/v1/traces/search", json=body)
 
     # A window the caller did not ask for has to be visible: read as an org

{cmpnd-0.18.2 → cmpnd-0.19.0}/cmpnd/optimization.py

@@ -704,6 +704,7 @@ def optimize(
     lms: dict[str, Any] | None = None,
     max_metric_calls: int | None = None,
     auto: str | None = None,
+    may_author_code: bool | None = None,
     max_steps: int = 10,
     patience: int = 2,
     seed: int = 0,
@@ -842,6 +843,16 @@ def optimize(
             ``"heavy"`` — sized from the program's predictor count and the
             valset, using GEPA's own settings. Easier to reach for than a call
             count when you do not yet know what a run costs.
+        may_author_code: Whether this run may rewrite the SOURCE of the program's
+            ``dspy.Flex`` submodules, rather than only their instructions. Left
+            unset, the platform's answer is yes — writing a ``dspy.Flex`` is
+            already asking for its source to be optimized.
+
+            Pass ``False`` for "improve my prompts, don't rewrite my code" on a
+            program that has both: a cheaper, lower-variance search that still
+            optimizes every ordinary predictor and leaves each ``dspy.Flex`` at
+            the source you deployed. A program with no ``dspy.Flex`` in it is
+            unaffected either way.
         max_steps: How many times to re-optimize the winner, each step a fresh
             ``optimize`` call with an advanced seed (default 10). Distinct from
             the budget above, which bounds ONE step's search: total spend is
@@ -901,7 +912,14 @@ def optimize(
             step_config["seed"] = seed
 
             initiated = _initiate_step(
-                client, cfg.endpoint, headers, current_deployment_id, optimizer, data, step_config
+                client,
+                cfg.endpoint,
+                headers,
+                current_deployment_id,
+                optimizer,
+                data,
+                step_config,
+                may_author_code,
             )
             optimization_id = initiated["optimization_id"]
 
@@ -1040,6 +1058,7 @@ def _initiate_step(
     optimizer: str,
     data: str,
     config: dict[str, Any],
+    may_author_code: bool | None = None,
 ) -> dict[str, Any]:
     """POST one optimize step to serve; return the 201 body. Raises
     OptimizeError carrying the server's error on any non-2xx (e.g. 409/422).
@@ -1058,7 +1077,11 @@ def _initiate_step(
     resp = _request(
         lambda: client.post(
             f"{endpoint}/api/v1/deployments/{deployment_id}/optimize/{optimizer}",
-            json={"data": data, "config": config},
+            json=(
+                {"data": data, "config": config}
+                if may_author_code is None
+                else {"data": data, "config": config, "may_author_code": may_author_code}
+            ),
             headers=headers,
         ),
         what,

cmpnd-0.19.0/cmpnd/traces.py

@@ -0,0 +1,136 @@
+"""Programmatic trace reads for the cmpnd backend.
+
+``import cmpnd`` already emits traces; this module reads them back. ``cmpnd.traces``
+reaches the same two backend reads the CLI does — ``list`` and ``show`` — over the
+same HTTP transport, so the library and the CLI cannot drift. It follows the SDK's
+existing shape: module-level verbs over the credentials ``cmpnd.configure()`` set,
+like ``cmpnd.deploy`` / ``cmpnd.execute`` / ``cmpnd.load_dataset``.
+
+    >>> import cmpnd
+    >>> cmpnd.configure(api_key="ct_xxx")
+    >>> page = cmpnd.traces.list(status="error", since="30d", limit=10)
+    >>> for row in page["traces"]:
+    ...     detail = cmpnd.traces.show(row["trace_id"])
+
+The verbs and filter names match the ``cmpnd traces`` CLI vocabulary — ``list`` and
+``show``, filtered by ``query``, ``program``, ``hash``, ``deployment``, ``since`` /
+``until``, ``all_history`` — so a user moves between the two surfaces without
+relearning names. (The CLI's ``traces search`` spelling is a deprecated alias of
+``traces list``; this surface offers only ``list``.)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from . import _http, _timespec, configuration
+
+DEFAULT_ENDPOINT = "https://platform.cmpnd.ai"
+
+# The traces route paginates by page number; these verbs offer the friendlier
+# limit/offset pair and map it, matching how the CLI presents pagination.
+_DEFAULT_LIMIT = 50
+
+
+def list(
+    *,
+    status: str | None = None,
+    query: str | None = None,
+    model: str | None = None,
+    program: str | None = None,
+    hash: str | None = None,
+    deployment: str | None = None,
+    metadata: dict[str, str] | None = None,
+    tags: list[str] | None = None,
+    since: str | None = None,
+    until: str | None = None,
+    all_history: bool = False,
+    limit: int = _DEFAULT_LIMIT,
+    offset: int = 0,
+    api_key: str | None = None,
+    endpoint: str | None = None,
+) -> dict[str, Any]:
+    """List and search traces, newest first.
+
+    Returns the raw response: ``{"traces": [...], "total": N, ...}``. It also
+    carries ``default_window_applied`` and ``start_time_from`` when no time filter
+    was given, so the caller can tell an org-wide total from a windowed one, and
+    ``ignored_fields`` naming any request field an older server did not understand.
+
+    The filters mirror ``cmpnd traces list``: ``query`` searches indexed span text;
+    ``program`` / ``hash`` name the program by name or signature hash;
+    ``deployment`` is a deployment id; ``metadata`` is matched by containment (every
+    pair must be present); ``tags`` matches any of the given tags. ``since`` /
+    ``until`` accept an ISO 8601 timestamp, a bare date (``YYYY-MM-DD``), or a
+    duration back from now (``30d``, ``2w``, ``12h``, ``90m``), resolved the same
+    way the CLI resolves ``--since`` / ``--until``. An upper bound needs a lower
+    one, and ``all_history`` (the CLI's ``--all``) cannot combine with either bound
+    — the backend enforces both.
+
+    ``api_key`` / ``endpoint`` override the configured credentials for this call.
+    """
+    body: dict[str, Any] = _pagination(limit, offset)
+    if all_history:
+        body["max_window"] = True
+    for wire_key, val in (
+        ("status", status),
+        ("q", query),
+        ("model", model),
+        ("program_name", program),
+        ("program_signature_hash", hash),
+        ("deployment_id", deployment),
+        ("tags", tags),
+    ):
+        if val is not None:
+            body[wire_key] = val
+    if metadata is not None:
+        body["metadata"] = dict(metadata)
+    if since is not None:
+        body["start_time_from"] = _timespec.resolve_search_time(since)
+    if until is not None:
+        body["start_time_to"] = _timespec.resolve_search_time(until, end_of_day=True)
+    return _client(api_key, endpoint).post("/api/v1/traces/search", json=body)
+
+
+def show(trace_id: str, *, api_key: str | None = None, endpoint: str | None = None) -> dict[str, Any]:
+    """Fetch one trace and its spans: ``{"trace": {...}, "spans": [...]}``.
+
+    ``api_key`` / ``endpoint`` override the configured credentials for this call.
+    """
+    return _client(api_key, endpoint).get(f"/api/v1/traces/{trace_id}")
+
+
+def _client(api_key: str | None, endpoint: str | None) -> _http.ApiClient:
+    """Build a transport from the resolved credentials.
+
+    Resolution order: an explicit ``api_key`` / ``endpoint`` argument, then whatever
+    ``cmpnd.configure()`` set, then the ``CMPND_API_KEY`` / ``CMPND_ENDPOINT``
+    environment. The endpoint falls back to the public platform when nothing names
+    one; a missing API key raises, since no read is possible without one.
+    """
+    cfg = configuration.get_config()
+    resolved_key = api_key or (cfg.api_key if cfg else None) or os.getenv("CMPND_API_KEY")
+    if not resolved_key:
+        raise _http.ApiError("No API key. Pass api_key=, call cmpnd.configure(api_key=...), or set CMPND_API_KEY.")
+    resolved_endpoint = endpoint or (cfg.endpoint if cfg else None) or os.getenv("CMPND_ENDPOINT") or DEFAULT_ENDPOINT
+    return _http.ApiClient(resolved_key, resolved_endpoint)
+
+
+def _pagination(limit: int, offset: int) -> dict[str, Any]:
+    """Map the caller's limit/offset onto the route's page/page_size.
+
+    The route addresses rows by page, so the offset must be a whole multiple of the
+    limit — the same rule the CLI's pagination helper enforces.
+    """
+    if limit <= 0:
+        raise _http.ApiError("limit must be positive")
+    if offset < 0:
+        raise _http.ApiError("offset must not be negative")
+    if offset % limit != 0:
+        lower = (offset // limit) * limit
+        raise _http.ApiError(
+            f"offset must be a multiple of limit (the traces route paginates by page); "
+            f"try offset {lower} or {lower + limit}"
+        )
+    return {"page": offset // limit + 1, "page_size": limit}

cmpnd-0.19.0/docs/reading-traces.md

@@ -0,0 +1,77 @@
+# Reading traces from a program
+
+The `cmpnd` SDK emits traces through `configure()` + `auto_instrument()`. It also
+reads them back: `cmpnd.traces` is a programmatic view over the backend's trace
+reads, so a program that builds an eval, a dashboard, or an agent lists and
+fetches its own traces without shelling out to the CLI or hand-rolling httpx.
+It follows the SDK's existing shape — module-level verbs over the credentials
+`cmpnd.configure()` set, like `cmpnd.deploy` / `cmpnd.execute` / `cmpnd.load_dataset`.
+
+## Entry point
+
+```python
+import cmpnd
+
+cmpnd.configure(api_key="ct_...")     # or set CMPND_API_KEY
+
+page = cmpnd.traces.list(status="error", since="30d", limit=10)
+for row in page["traces"]:
+    detail = cmpnd.traces.show(row["trace_id"])
+```
+
+Each call resolves its API key and endpoint in this order: an explicit `api_key` /
+`endpoint` argument, then whatever `cmpnd.configure()` set, then the
+`CMPND_API_KEY` / `CMPND_ENDPOINT` environment. The endpoint falls back to the
+public platform when nothing names one; a missing API key raises `cmpnd.ApiError`.
+
+## Verbs and filters match the CLI
+
+The verb and argument names are the `cmpnd traces` CLI vocabulary, so a user moves
+between the two surfaces without relearning names. (The CLI's `traces search`
+spelling is a deprecated alias of `traces list`; this surface offers only `list`.)
+
+## `cmpnd.traces.list(...)`
+
+Lists and searches traces, newest first, returning the raw response:
+`{"traces": [...], "total": N, ...}`.
+
+| Argument | CLI flag | Meaning |
+| -- | -- | -- |
+| `status` | `--status` | `ok`, `error`, `incomplete`, `in_progress` |
+| `query` | `--query` / `-q` | Full-text search over indexed span text (prompts, completions, tool calls, errors) |
+| `model` | `--model` | Exact model name, e.g. `openai/gpt-4o` |
+| `program` | `--program` | Program name |
+| `hash` | `--hash` | Program signature hash, as a string |
+| `deployment` | `--deployment` | Deployment UUID |
+| `metadata` | `--metadata` | `dict` matched by containment — every pair must be present on the trace |
+| `tags` | `--tag` | `list` — matches any of the given project tags |
+| `since` / `until` | `--since` / `--until` | Time bounds (see below) |
+| `all_history` | `--all` | Widen to the route's longest window |
+| `limit` / `offset` | `--limit` / `--offset` | Page size and start; `offset` must be a whole multiple of `limit` |
+
+`since` / `until` accept an ISO 8601 timestamp, a bare date (`YYYY-MM-DD`), or a
+duration back from now (`30d`, `2w`, `12h`, `90m`) — resolved by the same code the
+CLI's `--since` / `--until` use. An upper bound needs a lower one, and
+`all_history` cannot combine with either bound; the backend enforces both.
+
+When no time filter is given the response carries `default_window_applied` and the
+`start_time_from` the server chose, so a caller can tell an org-wide total from a
+windowed one. `ignored_fields` names any request field an older server did not
+understand.
+
+`api_key` / `endpoint` keyword arguments override the configured credentials for a
+single call, for a script that reads from more than one place.
+
+## `cmpnd.traces.show(trace_id)`
+
+Fetches one trace and its spans: `{"trace": {...}, "spans": [...]}`. A missing
+trace raises `cmpnd.ApiError`.
+
+## One transport, two surfaces
+
+`cmpnd.traces` and the `cmpnd` CLI send every request through the same HTTP
+transport (`cmpnd._http.ApiClient`), so the library and the CLI cannot drift on
+base-URL handling, the API-key header, the timeout, or the error ladder. The CLI
+adds its own credential resolution (`--api-key` / `--endpoint` flags, stored
+login) on top; the `cmpnd traces list` / `cmpnd traces show` commands reach the
+same two routes these functions do.

{cmpnd-0.18.2 → cmpnd-0.19.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.18.2"
+version = "0.19.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.10"

cmpnd-0.19.0/tests/e2e/test_traces_read.py

@@ -0,0 +1,41 @@
+"""End-to-end tests for the programmatic trace reads against a live server.
+
+Drives ``cmpnd.traces`` — the library surface a user reaches through
+``import cmpnd`` — against a real backend: run a program, then list and show the
+trace it produced. This is the level that catches a library↔API contract
+mismatch a mocked transport cannot. Skipped unless CMPND_E2E_API_KEY is set
+(see conftest).
+"""
+
+from __future__ import annotations
+
+import dspy
+import pytest
+
+import cmpnd
+from tests.e2e.conftest import CMPND_E2E_API_KEY, E2E_ENDPOINT, flush_and_wait
+
+pytestmark = pytest.mark.e2e
+
+
+class TestTracesReadE2E:
+    def test_list_and_show_round_trip(self, server_client, trace_capture):
+        dspy.Predict("question -> answer")(question="Who represents District 4?")
+        flush_and_wait()
+        trace_id = trace_capture.last_trace_id
+        assert trace_id is not None, "no trace captured"
+        program_hash = server_client.get_trace(trace_id)["trace"]["program_signature_hash"]
+
+        # list by the program that produced it finds the trace.
+        page = cmpnd.traces.list(hash=str(program_hash), limit=50, api_key=CMPND_E2E_API_KEY, endpoint=E2E_ENDPOINT)
+        assert trace_id in [t["trace_id"] for t in page["traces"]]
+
+        # show returns the trace and its spans.
+        detail = cmpnd.traces.show(trace_id, api_key=CMPND_E2E_API_KEY, endpoint=E2E_ENDPOINT)
+        assert detail["trace"]["trace_id"] == trace_id
+        assert isinstance(detail["spans"], list)
+        assert len(detail["spans"]) >= 1
+
+    def test_show_missing_trace_raises(self):
+        with pytest.raises(cmpnd.ApiError):
+            cmpnd.traces.show("00000000-0000-0000-0000-000000000000", api_key=CMPND_E2E_API_KEY, endpoint=E2E_ENDPOINT)

{cmpnd-0.18.2 → cmpnd-0.19.0}/tests/test_cli/test_deployments.py

@@ -95,7 +95,7 @@ def _transport(response: httpx.Response) -> mock._patch[mock.MagicMock]:
     """
     made = mock.MagicMock()
     made.__enter__.return_value.get.return_value = response
-    return mock.patch("cmpnd.cli.api_client.httpx.Client", return_value=made)
+    return mock.patch("cmpnd._http.httpx.Client", return_value=made)
 
 
 class TestOpenAPI: