cmpnd 0.18.3__tar.gz → 0.20.0__tar.gz

{cmpnd-0.18.3 → cmpnd-0.20.0}/PKG-INFO

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

{cmpnd-0.18.3 → cmpnd-0.20.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.3/cmpnd/cli/api_client.py → cmpnd-0.20.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.20.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.18.3 → cmpnd-0.20.0}/cmpnd/cli/__init__.py

@@ -13,6 +13,7 @@ import httpx
 from . import api_client, deprecation
 from .commands import (
     admin,
+    assessments,
     auth,
     datasets,
     deployments,
@@ -26,6 +27,7 @@ from .commands import (
     tool_servers,
     top,
     traces,
+    valsets,
 )
 
 
@@ -141,6 +143,15 @@ def main() -> None:
     datasets.register(subparsers)
     deployments.register(subparsers)
 
+    # Assessments and valsets CLIs are still in development, hidden behind
+    # CMPND_CLI_DEV=1 (mirroring the CMPND_CLI_ADMIN gate above). The env var
+    # only hides the commands from customers; the server still gates each action
+    # on the assessments:* / valsets:* scope, so this is discoverability, not
+    # enforcement.
+    if os.environ.get("CMPND_CLI_DEV") == "1":
+        assessments.register(subparsers)
+        valsets.register(subparsers)
+
     # Top-level Docker-style shortcuts (human-readable by default; --json opts in)
     top.register(subparsers)
 

cmpnd-0.20.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.20.0/cmpnd/cli/commands/assessments.py

@@ -0,0 +1,67 @@
+"""Assessments commands.
+
+An assessment is a person's judgement of a trace: an up/down/neutral
+conclusion, a prose body, and per-span annotations. See the assessments API.
+"""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser, _SubParsersAction
+from typing import Any
+
+from .. import api_client
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser("assessments", help="Record and read judgements of traces")
+    sub = parser.add_subparsers(dest="action")
+
+    create = sub.add_parser("create", help="Record a judgement of a trace")
+    create.add_argument("trace_id", help="The trace to assess (its SDK trace id)")
+    conclusion = create.add_mutually_exclusive_group(required=True)
+    conclusion.add_argument(
+        "--up", dest="conclusion", action="store_const", const="up", help="Affirm the trace's output"
+    )
+    conclusion.add_argument(
+        "--down", dest="conclusion", action="store_const", const="down", help="Dispute the trace's output"
+    )
+    conclusion.add_argument(
+        "--neutral", dest="conclusion", action="store_const", const="neutral", help="Neither affirm nor dispute"
+    )
+    create.add_argument("-m", "--message", dest="body", help="The prose body of the judgement")
+    create.add_argument(
+        "--annotate",
+        dest="annotations",
+        action="append",
+        nargs=2,
+        metavar=("SPAN_ID", "NOTE"),
+        help="Attach a note to one span in the trace (repeat for multiple)",
+    )
+    create.set_defaults(func=handle_create)
+
+    ls = sub.add_parser("list", help="List a program's assessments")
+    ls.add_argument(
+        "--program", required=True, help="Program signature hash (16-hex, as `cmpnd signatures list` shows)"
+    )
+    ls.set_defaults(func=handle_list)
+
+    show = sub.add_parser("show", help="Show one assessment with its annotations")
+    show.add_argument("id", help="Assessment id")
+    show.set_defaults(func=handle_show)
+
+
+def handle_create(client: api_client.ApiClient, args: Any) -> Any:
+    body: dict[str, Any] = {"trace_id": args.trace_id, "conclusion": args.conclusion}
+    if args.body:
+        body["body"] = args.body
+    if args.annotations:
+        body["annotations"] = [{"span_id": span, "note": note} for span, note in args.annotations]
+    return client.post("/api/v1/assessments", json=body)
+
+
+def handle_list(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get("/api/v1/assessments", params={"program": args.program})
+
+
+def handle_show(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/assessments/{args.id}")

{cmpnd-0.18.3 → cmpnd-0.20.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.20.0/cmpnd/cli/commands/valsets.py

@@ -0,0 +1,101 @@
+"""Valsets commands.
+
+A valset is a program-owned validation set: a name, the field shape derived
+from the owning program's signature, and its entries. Entries carry the
+inputs and expected outputs of one validation example.
+"""
+
+from __future__ import annotations
+
+import json
+from argparse import ArgumentParser, _SubParsersAction
+from typing import Any
+
+from .. import api_client
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser("valsets", help="Manage program-owned validation sets")
+    sub = parser.add_subparsers(dest="action")
+
+    create = sub.add_parser("create", help="Create a validation set owned by a program")
+    create.add_argument("program_hash", help="Owning program signature hash (16-hex, as `cmpnd signatures list` shows)")
+    create.add_argument("--name", required=True, help="Validation-set name (unique within the program)")
+    create.set_defaults(func=handle_create)
+
+    ls = sub.add_parser("list", help="List a program's validation sets")
+    ls.add_argument("--program", required=True, help="Program signature hash (16-hex)")
+    ls.set_defaults(func=handle_list)
+
+    show = sub.add_parser("show", help="Show a validation set")
+    show.add_argument("id", help="Valset id")
+    show.set_defaults(func=handle_show)
+
+    entries = sub.add_parser("entries", help="Manage a validation set's entries")
+    esub = entries.add_subparsers(dest="entries_action")
+
+    elist = esub.add_parser("list", help="List a valset's active entries")
+    elist.add_argument("valset_id", help="Valset id")
+    elist.set_defaults(func=handle_entries_list)
+
+    ecreate = esub.add_parser("create", help="Add an entry from JSON content")
+    ecreate.add_argument("valset_id", help="Valset id")
+    ecreate.add_argument(
+        "--inputs", required=True, metavar="JSON", help="Inputs object; its keys are the valset's input fields"
+    )
+    ecreate.add_argument(
+        "--expected-outputs",
+        dest="expected_outputs",
+        required=True,
+        metavar="JSON",
+        help="Expected-outputs object; its keys are the valset's output fields",
+    )
+    ecreate.add_argument(
+        "--from-assessment", dest="from_assessment", help="Source assessment id, recorded as the entry's provenance"
+    )
+    ecreate.set_defaults(func=handle_entries_create)
+
+    edelete = esub.add_parser("delete", help="Retire an entry (versioned, not a hard delete)")
+    edelete.add_argument("entry_id", help="Entry id")
+    edelete.set_defaults(func=handle_entries_delete)
+
+
+def handle_create(client: api_client.ApiClient, args: Any) -> Any:
+    return client.post("/api/v1/valsets", json={"program": args.program_hash, "name": args.name})
+
+
+def handle_list(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get("/api/v1/valsets", params={"program": args.program})
+
+
+def handle_show(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/valsets/{args.id}")
+
+
+def handle_entries_list(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/valsets/{args.valset_id}/entries")
+
+
+def handle_entries_create(client: api_client.ApiClient, args: Any) -> Any:
+    inputs = _parse_json_flag("--inputs", args.inputs)
+    expected = _parse_json_flag("--expected-outputs", args.expected_outputs)
+    body: dict[str, Any] = {"inputs": inputs, "expected_outputs": expected}
+    if args.from_assessment:
+        body["from_assessment"] = args.from_assessment
+    return client.post(f"/api/v1/valsets/{args.valset_id}/entries", json=body)
+
+
+def handle_entries_delete(client: api_client.ApiClient, args: Any) -> Any:
+    client.delete(f"/api/v1/valsets/entries/{args.entry_id}")
+    # The route returns 204; echo a confirmation so the CLI does not print null.
+    return {"deleted": args.entry_id}
+
+
+def _parse_json_flag(flag: str, value: str) -> dict[str, Any]:
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise api_client.CliError(f"{flag} JSON is invalid: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise api_client.CliError(f"{flag} JSON must be an object")
+    return parsed

cmpnd-0.20.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}