cmpnd 0.24.0__tar.gz → 0.25.0__tar.gz

{cmpnd-0.24.0 → cmpnd-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.24.0
+Version: 0.25.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -22,6 +22,7 @@ Requires-Dist: httpx>=0.27.0
 Requires-Dist: ipython>=8.20
 Requires-Dist: openai<2
 Requires-Dist: pydantic>=2.0
+Requires-Dist: typing-extensions>=4.1.0
 Requires-Dist: xxhash>=3.0.0
 Provides-Extra: dev
 Requires-Dist: basedpyright>=1.39; extra == 'dev'
@@ -41,7 +42,8 @@ Requires-Dist: cmpnd-fake-provider; (python_version >= '3.11') and extra == 'fak
 Provides-Extra: images
 Requires-Dist: pillow>=10.0; extra == 'images'
 Provides-Extra: mcp
-Requires-Dist: mcp<2,>=1.9; extra == 'mcp'
+Requires-Dist: dspy>=3.3.1; extra == 'mcp'
+Requires-Dist: mcp>=1.9; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # cmpnd

{cmpnd-0.24.0 → cmpnd-0.25.0}/cmpnd/_assessments.py

@@ -46,15 +46,31 @@ def create(
 
 
 def list(
-    program: str, *, limit: int = 50, offset: int = 0, api_key: str | None = None, endpoint: str | None = None
+    program: str | None = None,
+    *,
+    trace_id: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+    api_key: str | None = None,
+    endpoint: str | None = None,
 ) -> dict[str, Any]:
-    """List a program's assessments, newest first.
+    """List assessments by program or by trace, newest first.
 
-    Returns ``{"assessments": [...], "total": N, "limit", "offset", "has_more"}``.
+    Pass exactly one of ``program`` (every assessment of that program) or
+    ``trace_id`` (only that trace's assessments). Returns
+    ``{"assessments": [...], "total": N, "limit", "offset", "has_more"}``.
     ``limit`` (max rows) and ``offset`` (skip this many) page the full set — the
     server clamps ``limit`` to at most 200.
     """
-    params = {"program": program, "limit": str(limit), "offset": str(offset)}
+    if program is not None and trace_id is not None:
+        raise ValueError("pass exactly one of program or trace_id")
+    if trace_id is not None:
+        scope: dict[str, str] = {"trace_id": trace_id}
+    elif program is not None:
+        scope = {"program": program}
+    else:
+        raise ValueError("pass exactly one of program or trace_id")
+    params = {**scope, "limit": str(limit), "offset": str(offset)}
     return _client(api_key, endpoint).get("/api/v1/assessments", params=params)
 
 
@@ -63,6 +79,11 @@ def get(assessment_id: str, *, api_key: str | None = None, endpoint: str | None
     return _client(api_key, endpoint).get(f"/api/v1/assessments/{assessment_id}")
 
 
+def delete(assessment_id: str, *, api_key: str | None = None, endpoint: str | None = None) -> None:
+    """Delete one assessment. Raises ``ApiError`` (404) if it does not exist."""
+    _client(api_key, endpoint).delete(f"/api/v1/assessments/{assessment_id}")
+
+
 def _client(api_key: str | None, endpoint: str | None) -> _http.ApiClient:
     cfg = configuration.get_config()
     resolved_key = api_key or (cfg.api_key if cfg else None) or os.getenv("CMPND_API_KEY")

{cmpnd-0.24.0 → cmpnd-0.25.0}/cmpnd/cli/commands/assessments.py

@@ -44,8 +44,14 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     )
     create.set_defaults(func=handle_create)
 
-    ls = sub.add_parser("list", help="List a program's assessments")
-    ls.add_argument("program", help="Program signature hash (16-hex, as `cmpnd signatures list` shows)")
+    ls = sub.add_parser("list", help="List assessments by program or by trace")
+    scope = ls.add_mutually_exclusive_group(required=True)
+    scope.add_argument(
+        "program",
+        nargs="?",
+        help="Program signature hash (16-hex, as `cmpnd signatures list` shows)",
+    )
+    scope.add_argument("--trace", dest="trace_id", metavar="TRACE_ID", help="A single trace's assessments")
     pagination.add_args(ls, with_page_aliases=False, default_limit=50)
     ls.set_defaults(func=handle_list)
 
@@ -53,6 +59,10 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     show.add_argument("id", help="Assessment id")
     show.set_defaults(func=handle_show)
 
+    delete = sub.add_parser("delete", help="Delete one assessment")
+    delete.add_argument("id", help="Assessment id")
+    delete.set_defaults(func=handle_delete)
+
 
 def handle_create(client: api_client.ApiClient, args: Any) -> Any:
     body: dict[str, Any] = {"trace_id": args.trace_id, "conclusion": args.conclusion}
@@ -64,9 +74,15 @@ def handle_create(client: api_client.ApiClient, args: Any) -> Any:
 
 
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
-    params = {"program": args.program, **pagination.wire(args, "limit_offset", as_str=True)}
+    scope = {"trace_id": args.trace_id} if args.trace_id else {"program": args.program}
+    params = {**scope, **pagination.wire(args, "limit_offset", as_str=True)}
     return client.get("/api/v1/assessments", params=params)
 
 
 def handle_show(client: api_client.ApiClient, args: Any) -> Any:
     return client.get(f"/api/v1/assessments/{args.id}")
+
+
+def handle_delete(client: api_client.ApiClient, args: Any) -> Any:
+    client.delete(f"/api/v1/assessments/{args.id}")
+    return {"deleted": args.id}

{cmpnd-0.24.0 → cmpnd-0.25.0}/cmpnd/cli/commands/top.py

@@ -15,7 +15,7 @@ from argparse import ArgumentParser, ArgumentTypeError, _SubParsersAction
 from datetime import datetime, timezone
 from typing import Any
 
-from .. import api_client, pagination
+from .. import api_client, pagination, snippet
 from . import signatures
 
 # --------------------------------------------------------------------------
@@ -782,30 +782,35 @@ def cmd_deploy(client: api_client.ApiClient, args: Any) -> None:
 
     configuration.configure(api_key=client._api_key, endpoint=client._endpoint)
 
-    namespace: dict[str, Any] = {"__name__": "__cmpnd_deploy__", "__file__": source_label}
-    try:
-        exec(compile(source, source_label, "exec"), namespace)
-    except Exception as exc:
-        raise api_client.CliError(f"Snippet raised {type(exc).__name__}: {exc}")
-
-    program = namespace.get("program")
-    if program is None:
-        # Fallback: pick the last dspy.Module instance defined.
+    # The whole packaging step stays inside the registration, not just the exec:
+    # both the annotations DSPy resolves and the class sources the packager
+    # inlines are read back out of `sys.modules` after the snippet has run.
+    with snippet.as_module("__cmpnd_deploy__", source_label) as module:
+        namespace: dict[str, Any] = module.__dict__
         try:
-            import dspy
-        except ImportError:
-            raise api_client.CliError("Snippet did not bind `program`, and dspy isn't importable to scan for one.")
-        candidates = [v for v in namespace.values() if isinstance(v, dspy.Module)]
-        if not candidates:
-            raise api_client.CliError(
-                "Snippet did not bind `program` to a dspy.Module instance. Add e.g. `program = dspy.Predict(...)`."
-            )
-        program = candidates[-1]
+            exec(compile(source, source_label, "exec"), namespace)
+        except Exception as exc:
+            raise api_client.CliError(f"Snippet raised {type(exc).__name__}: {exc}")
+
+        program = namespace.get("program")
+        if program is None:
+            # Fallback: pick the last dspy.Module instance defined.
+            try:
+                import dspy
+            except ImportError:
+                raise api_client.CliError("Snippet did not bind `program`, and dspy isn't importable to scan for one.")
+            candidates = [v for v in namespace.values() if isinstance(v, dspy.Module)]
+            if not candidates:
+                raise api_client.CliError(
+                    "Snippet did not bind `program` to a dspy.Module instance. Add e.g. `program = dspy.Predict(...)`."
+                )
+            program = candidates[-1]
+
+        metadata = _parse_deploy_metadata(getattr(args, "metadata", None))
 
-    metadata = _parse_deploy_metadata(getattr(args, "metadata", None))
+        print(_c("deploying…", "dim"), file=sys.stderr)
+        deployed = deployment.deploy(program, metadata=metadata)
 
-    print(_c("deploying…", "dim"), file=sys.stderr)
-    deployed = deployment.deploy(program, metadata=metadata)
     deployment_id = deployed.deployment_id
     print(deployment_id)
 
@@ -882,42 +887,46 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
 
     configuration.configure(api_key=client._api_key, endpoint=client._endpoint)
 
-    namespace: dict[str, Any] = {"__name__": "__cmpnd_optimize__", "__file__": source_label}
-    try:
-        exec(compile(source, source_label, "exec"), namespace)
-    except Exception as exc:
-        raise api_client.CliError(f"Snippet raised {type(exc).__name__}: {exc}")
+    # Registered for the whole run, not just the exec: optimize deploys the
+    # program, and packaging reads the snippet's classes back through
+    # `sys.modules`. See `cmpnd.cli.snippet`.
+    with snippet.as_module("__cmpnd_optimize__", source_label) as module:
+        namespace: dict[str, Any] = module.__dict__
+        try:
+            exec(compile(source, source_label, "exec"), namespace)
+        except Exception as exc:
+            raise api_client.CliError(f"Snippet raised {type(exc).__name__}: {exc}")
 
-    missing = [name for name in ("program", "trainset", "valset", "metric") if namespace.get(name) is None]
-    if missing:
-        raise api_client.CliError(
-            f"Snippet must bind {missing} — e.g. `program = dspy.Predict('q -> a')`, "
-            "`trainset = [...]`, `valset = [...]`, "
-            "`def metric(gold, pred, trace, pred_name, pred_trace): ...` returning "
-            "`dspy.Prediction(score=, feedback=)`."
-        )
+        missing = [name for name in ("program", "trainset", "valset", "metric") if namespace.get(name) is None]
+        if missing:
+            raise api_client.CliError(
+                f"Snippet must bind {missing} — e.g. `program = dspy.Predict('q -> a')`, "
+                "`trainset = [...]`, `valset = [...]`, "
+                "`def metric(gold, pred, trace, pred_name, pred_trace): ...` returning "
+                "`dspy.Prediction(score=, feedback=)`."
+            )
 
-    print(_c(f"optimizing with {args.optimizer}…", "dim"), file=sys.stderr)
-    try:
-        result = optimization.optimize(
-            namespace["program"],
-            optimizer=args.optimizer,
-            trainset=namespace["trainset"],
-            valset=namespace["valset"],
-            metric=namespace["metric"],
-            deployment_id=getattr(args, "deployment_id", None),
-            # The flag is named for what a command line can carry — a model name,
-            # never an LM object — and the parameter for what the Python surface
-            # accepts. Each layer's name says what that layer takes.
-            reflection_lm=getattr(args, "reflection_model", None),
-            max_metric_calls=getattr(args, "max_metric_calls", None),
-            auto=getattr(args, "auto", None),
-            max_steps=getattr(args, "max_steps", 10),
-            patience=getattr(args, "patience", 2),
-            seed=getattr(args, "seed", 0),
-        )
-    except (optimization.OptimizeError, optimization.OptimizeFailed, ValueError) as exc:
-        raise api_client.CliError(str(exc))
+        print(_c(f"optimizing with {args.optimizer}…", "dim"), file=sys.stderr)
+        try:
+            result = optimization.optimize(
+                namespace["program"],
+                optimizer=args.optimizer,
+                trainset=namespace["trainset"],
+                valset=namespace["valset"],
+                metric=namespace["metric"],
+                deployment_id=getattr(args, "deployment_id", None),
+                # The flag is named for what a command line can carry — a model name,
+                # never an LM object — and the parameter for what the Python surface
+                # accepts. Each layer's name says what that layer takes.
+                reflection_lm=getattr(args, "reflection_model", None),
+                max_metric_calls=getattr(args, "max_metric_calls", None),
+                auto=getattr(args, "auto", None),
+                max_steps=getattr(args, "max_steps", 10),
+                patience=getattr(args, "patience", 2),
+                seed=getattr(args, "seed", 0),
+            )
+        except (optimization.OptimizeError, optimization.OptimizeFailed, ValueError) as exc:
+            raise api_client.CliError(str(exc))
 
     if getattr(args, "json", False):
         print(

{cmpnd-0.24.0 → cmpnd-0.25.0}/cmpnd/cli/shell.py

@@ -33,6 +33,7 @@ from types import SimpleNamespace
 from typing import Any, Callable
 
 from . import api_client, commands, credentials, verbs
+from .snippet import as_module
 
 # --------------------------------------------------------------------------
 # Config + dismissible-tips marker
@@ -508,38 +509,43 @@ def _make_namespace(client: api_client.ApiClient, endpoint: str) -> dict[str, An
 
         configuration.configure(api_key=client._api_key, endpoint=client._endpoint)
 
-        namespace: dict[str, Any] = {"__name__": "__cmpnd_deploy__", "__file__": label}
-        try:
-            exec(compile(snippet, label, "exec"), namespace)
-        except SystemExit as exc:
-            # IPython catches SystemExit internally; the stdlib code.interact
-            # fallback would re-raise and kill the whole REPL. Convert to a
-            # plain exception so behavior is uniform across REPL flavors.
-            # The snippet runs with __name__ == "__cmpnd_deploy__", so a
-            # standard `if __name__ == "__main__":` guard already prevents
-            # this — call that out so users know how to fix.
-            raise RuntimeError(
-                f"Snippet called sys.exit({exc.code!r}). Remove the call or guard it "
-                'with `if __name__ == "__main__":` — the deploy runner sets '
-                "__name__ to '__cmpnd_deploy__', so a __main__ guard short-circuits "
-                "in deploy but still works when the file is run directly."
-            ) from None
-
-        program = namespace.get("program")
-        if program is None:
-            import dspy
-
-            candidates = [v for v in namespace.values() if isinstance(v, dspy.Module)]
-            if not candidates:
-                raise ValueError(
-                    "Snippet did not bind `program` to a dspy.Module instance "
-                    "(e.g. `program = dspy.Predict('q -> a')`)."
-                )
-            program = candidates[-1]
-
-        sys.stderr.write(_c("deploying…\n", "dim"))
-        sys.stderr.flush()
-        deployed = deployment.deploy(program)
+        # Registered for the whole deploy, not just the exec: the annotations
+        # DSPy resolves and the class sources the packager inlines are both read
+        # back through `sys.modules`. See `cmpnd.cli.snippet`.
+        with as_module("__cmpnd_deploy__", label) as module:
+            namespace: dict[str, Any] = module.__dict__
+            try:
+                exec(compile(snippet, label, "exec"), namespace)
+            except SystemExit as exc:
+                # IPython catches SystemExit internally; the stdlib code.interact
+                # fallback would re-raise and kill the whole REPL. Convert to a
+                # plain exception so behavior is uniform across REPL flavors.
+                # The snippet runs with __name__ == "__cmpnd_deploy__", so a
+                # standard `if __name__ == "__main__":` guard already prevents
+                # this — call that out so users know how to fix.
+                raise RuntimeError(
+                    f"Snippet called sys.exit({exc.code!r}). Remove the call or guard it "
+                    'with `if __name__ == "__main__":` — the deploy runner sets '
+                    "__name__ to '__cmpnd_deploy__', so a __main__ guard short-circuits "
+                    "in deploy but still works when the file is run directly."
+                ) from None
+
+            program = namespace.get("program")
+            if program is None:
+                import dspy
+
+                candidates = [v for v in namespace.values() if isinstance(v, dspy.Module)]
+                if not candidates:
+                    raise ValueError(
+                        "Snippet did not bind `program` to a dspy.Module instance "
+                        "(e.g. `program = dspy.Predict('q -> a')`)."
+                    )
+                program = candidates[-1]
+
+            sys.stderr.write(_c("deploying…\n", "dim"))
+            sys.stderr.flush()
+            deployed = deployment.deploy(program)
+
         record = client.get(f"/api/v1/deployments/{deployed.deployment_id}")
         deps.refresh()  # new deployment becomes visible in the registry
         return Deployment(client, record)

cmpnd-0.25.0/cmpnd/cli/snippet.py

@@ -0,0 +1,52 @@
+"""Run a user's deploy/optimize snippet as a real, importable module.
+
+A snippet exec'd into a bare dict is not reachable through ``sys.modules``, and
+two things the snippet's own program depends on look it up there:
+
+* **Deferred annotations.** With ``from __future__ import annotations`` a field's
+  type is stored as the string ``"Genre"``. Whatever resolves it later — DSPy
+  rebuilding a signature for ``ChainOfThought``, pydantic rebuilding a model —
+  reads the defining module's namespace out of ``sys.modules``. With no module
+  there the string stays a ``ForwardRef`` and the deploy is refused with "Field
+  types must be types".
+* **Source recovery.** The packager inlines a user-defined annotation type by
+  copying its source, and ``inspect`` finds a class's file through
+  ``sys.modules[cls.__module__].__file__``. Without the module the type silently
+  degrades to a stdlib stand-in.
+
+So the snippet gets a module object, registered for as long as the command needs
+it and removed afterwards.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+import types
+from collections.abc import Generator
+
+
+@contextlib.contextmanager
+def as_module(module_name: str, label: str) -> Generator[types.ModuleType]:
+    """Yield a module for a snippet to exec into, registered under ``module_name``.
+
+    ``label`` is the snippet's origin — a path, or ``<stdin>`` — and becomes the
+    module's ``__file__``, which is what lets ``inspect`` recover the source of a
+    class the snippet declares.
+
+    The registration is undone on the way out, whether the snippet raised or not,
+    so a REPL session or a second command in the same process never inherits the
+    previous snippet's module. Anything already registered under the name is put
+    back rather than dropped.
+    """
+    module = types.ModuleType(module_name)
+    module.__file__ = label
+    displaced = sys.modules.get(module_name)
+    sys.modules[module_name] = module
+    try:
+        yield module
+    finally:
+        if displaced is None:
+            sys.modules.pop(module_name, None)
+        else:
+            sys.modules[module_name] = displaced

{cmpnd-0.24.0 → cmpnd-0.25.0}/cmpnd/client.py

@@ -182,11 +182,22 @@ class Client:
             endpoint=self._config.endpoint,
         )
 
-    def list_assessments(self, program: str, *, limit: int = 50, offset: int = 0) -> list[dict[str, Any]]:
-        """A program's assessments, newest first (paged by limit/offset)."""
+    def list_assessments(
+        self, program: str | None = None, *, trace_id: str | None = None, limit: int = 50, offset: int = 0
+    ) -> list[dict[str, Any]]:
+        """Assessments newest first (paged by limit/offset).
+
+        Pass exactly one of ``program`` (all of that program's assessments) or
+        ``trace_id`` (one trace's assessments).
+        """
         self._check_active()
         page = _assessments.list(
-            program, limit=limit, offset=offset, api_key=self._config.api_key, endpoint=self._config.endpoint
+            program,
+            trace_id=trace_id,
+            limit=limit,
+            offset=offset,
+            api_key=self._config.api_key,
+            endpoint=self._config.endpoint,
         )
         return page.get("assessments", [])
 
@@ -195,6 +206,11 @@ class Client:
         self._check_active()
         return _assessments.get(assessment_id, api_key=self._config.api_key, endpoint=self._config.endpoint)
 
+    def delete_assessment(self, assessment_id: str) -> None:
+        """Delete one assessment. Raises if it does not exist."""
+        self._check_active()
+        _assessments.delete(assessment_id, api_key=self._config.api_key, endpoint=self._config.endpoint)
+
     def create_valset(self, program: str, *, name: str | None = None) -> dict[str, Any]:
         """Create a program-owned valset; name auto-assigned when omitted."""
         self._check_active()

{cmpnd-0.24.0 → cmpnd-0.25.0}/cmpnd/mcp_servers.py

@@ -52,8 +52,8 @@ import atexit
 import keyword
 import logging
 import threading
-from collections.abc import Callable, Coroutine, Mapping
-from contextlib import AsyncExitStack
+from collections.abc import AsyncGenerator, Callable, Coroutine, Mapping
+from contextlib import AsyncExitStack, asynccontextmanager
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, ClassVar
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
@@ -530,35 +530,126 @@ class _SessionHost:
         self._loop.call_soon_threadsafe(self._loop.stop)
 
 
+_MCP_IS_NOT_INSTALLED = (
+    "cmpnd.mcp_tools needs the MCP client library, which is an optional extra. "
+    "Install it with `pip install 'cmpnd[mcp]'` (or `uv add 'cmpnd[mcp]'`)."
+)
+
+# How long a tool call may take to be answered on the server-sent stream. The stream
+# is meant to idle between messages, and the older client took this as a separate
+# `sse_read_timeout` argument that cmpnd left at its default. The newer client folds
+# every timeout into one httpx client, so cmpnd has to name it to keep `timeout_s`
+# from cutting a long-running tool call short. It is NOT what bounds discovery —
+# `_connect` holds the caller's `timeout_s` over initialize and the tool listing,
+# because a budget that governs only the connect phase is no budget at all.
+_TOOL_CALL_READ_TIMEOUT_S = 300.0
+
+
+def _installed_mcp_version() -> str:
+    """The installed MCP client library's version, for a message that has to name it."""
+    from importlib import metadata
+
+    try:
+        return metadata.version("mcp")
+    except Exception:
+        return "unknown version"
+
+
+@asynccontextmanager
+async def _streamable_http_streams(
+    url: str, headers: Mapping[str, str], timeout_s: float
+) -> AsyncGenerator[tuple[Any, Any]]:
+    """Yield the read and write streams of a streamable-HTTP session to `url`.
+
+    Two generations of the MCP client library reach the same transport by different
+    shapes, and this is where the difference stops: `streamable_http_client` takes a
+    prebuilt httpx client, `streamablehttp_client` takes `headers` and `timeout`, and
+    the older one yields a third value (a session-id getter) that nothing here reads.
+    Which spelling exists is not a reliable guide to which shape it has — a client
+    library carrying both names yields three values from either — so the streams are
+    taken by position rather than unpacked.
+
+    Raises `ImportError` naming what to install when the library is absent, and a
+    different one naming the installed version when it is present but exposes neither
+    transport.
+    """
+    try:
+        import mcp.client.streamable_http as transport  # pyright: ignore[reportMissingImports]
+    except ImportError as exc:
+        raise ImportError(_MCP_IS_NOT_INSTALLED) from exc
+
+    with_prebuilt_client = getattr(transport, "streamable_http_client", None)
+    if with_prebuilt_client is not None:
+        httpx_module = getattr(transport, "httpx2", None) or getattr(transport, "httpx", None)
+        timeout: Any = timeout_s
+        if httpx_module is not None:
+            timeout = httpx_module.Timeout(timeout_s, read=_TOOL_CALL_READ_TIMEOUT_S)
+        http_client = transport.create_mcp_http_client(headers=dict(headers), timeout=timeout)
+        # A client the transport did not create is a client the transport does not
+        # close, so it is closed here — after the session that uses it.
+        async with http_client, with_prebuilt_client(url, http_client=http_client) as streams:
+            yield streams[0], streams[1]
+        return
+
+    with_headers = getattr(transport, "streamablehttp_client", None)
+    if with_headers is None:
+        raise ImportError(
+            f"cmpnd.mcp_tools cannot drive the installed MCP client library "
+            f"({_installed_mcp_version()}): mcp.client.streamable_http exposes neither "
+            "`streamable_http_client` nor `streamablehttp_client`, the two streamable-HTTP "
+            "transports cmpnd speaks. Install a version that has one of them."
+        )
+
+    async with with_headers(url, headers=dict(headers), timeout=timeout_s) as streams:
+        yield streams[0], streams[1]
+
+
 def _connect(url: str, headers: Mapping[str, str], timeout_s: float) -> tuple[Any, list[Any]]:
     """Open a session to `url` on the shared host loop and list the server's tools.
 
     The one function in this module that dials a network, kept separate so everything
     around it — the refusals, the conversion, the recording — is testable without one.
+
+    `timeout_s` bounds the whole of that: connecting, the initialize handshake and the
+    tool listing. It is held here rather than left to the transport because neither
+    client generation bounds those two calls by it — the modern one reads them on a
+    stream whose budget is a tool call's, and a caller asking for five seconds is
+    asking about the server answering at all, not about one socket read.
     """
     host = _SessionHost.shared()
 
     async def _open() -> tuple[Any, list[Any]]:
         try:
             from mcp import ClientSession  # pyright: ignore[reportMissingImports]
-            from mcp.client.streamable_http import (  # pyright: ignore[reportMissingImports]
-                streamablehttp_client,
-            )
         except ImportError as exc:
-            raise ImportError(
-                "cmpnd.mcp_tools needs the MCP client library, which is an optional extra. "
-                "Install it with `pip install 'cmpnd[mcp]'` (or `uv add 'cmpnd[mcp]'`)."
-            ) from exc
+            raise ImportError(_MCP_IS_NOT_INSTALLED) from exc
+
+        async def _discover() -> tuple[Any, list[Any], AsyncExitStack]:
+            # The stack is opened and, on any failure, closed inside this coroutine:
+            # the transport's cancel scopes must be exited by the task that entered
+            # them, and on timeout that task is this one rather than its caller.
+            stack = AsyncExitStack()
+            try:
+                read, write = await stack.enter_async_context(_streamable_http_streams(url, headers, timeout_s))
+                session = await stack.enter_async_context(ClientSession(read, write))
+                await session.initialize()
+                listing = await session.list_tools()
+            except BaseException:
+                await stack.aclose()
+                raise
+            return session, list(listing.tools), stack
 
-        stack = AsyncExitStack()
-        read, write, _ = await stack.enter_async_context(
-            streamablehttp_client(url, headers=dict(headers), timeout=timeout_s)
-        )
-        session = await stack.enter_async_context(ClientSession(read, write))
-        await session.initialize()
+        try:
+            session, tools, stack = await asyncio.wait_for(_discover(), timeout_s)
+        except asyncio.TimeoutError as exc:
+            raise TimeoutError(
+                f"the MCP server at {url} did not finish listing its tools within {timeout_s}s. "
+                "cmpnd.mcp_tools connects, initializes and reads the listing within the timeout you "
+                "pass it, so that a server which never answers costs you that and no more. Raise "
+                "timeout_s if the server is simply slow to start."
+            ) from exc
         host.adopt(stack)
-        listing = await session.list_tools()
-        return session, list(listing.tools)
+        return session, tools
 
     return host.run(_open())
 
@@ -586,8 +677,10 @@ def mcp_tools(
             Optional: a server with exactly one credential resolves without a name, and
             a server with two makes the deploy name one or be refused. Naming one here
             is also how you rotate a specific key rather than whichever one is there.
-        timeout_s: How long to wait on the server and, for OAuth, on the token
-            endpoint.
+        timeout_s: How long to wait for the server to answer — connecting,
+            initializing and listing its tools — and, for OAuth, on the token
+            endpoint. A tool call the returned tools make later is answered on the
+            session's own stream, which keeps a longer budget of its own.
 
     Returns:
         A list of `dspy.Tool`, each carrying an `McpToolReference` readable with