dense-evolution 8.3.0__py3-none-win_amd64.whl

mcp_server/client.py

@@ -0,0 +1,324 @@
+"""HTTP client layer for the dense_evolution_mcp adapter: the shared
+httpx.AsyncClient, the low-level _request helper every tool calls, and the
+@catch_errors decorator that replaces the try/except-return-_handle_error(e)
+boilerplate every tool used to repeat individually.
+
+KERNEL_URL and _TEST_TRANSPORT live here (not config.py) specifically
+because tests/integration/test_mcp_server.py mutates them via
+`monkeypatch.setattr(mcp_client, "KERNEL_URL"/"_TEST_TRANSPORT", ...)`
+(autouse fixture + a couple of per-test overrides, never a raw manual
+assignment) to exercise the unreachable-kernel and in-process-ASGI-
+transport paths -- _get_client/_request must see those mutations as
+their OWN module globals, which only works if the value's single source
+of truth lives in the same module that reads it. `_TEST_TRANSPORT`
+staying a real module attribute in production code (rather than
+disappearing entirely behind dependency injection) is a deliberate,
+narrow seam for exactly that monkeypatch, not leftover tech debt --
+Phase 4's original goal (prog.txt Sezione 3.3) of routing every override
+through pytest's own fixture mechanism, not a bare global, is already
+what happens here.
+"""
+import functools
+import os
+import subprocess
+import sys
+import threading
+from typing import Optional
+
+import httpx
+
+from .config import DEFAULT_TIMEOUT
+
+KERNEL_URL = os.environ.get("DENSE_EVOLUTION_KERNEL_URL", "http://127.0.0.1:8800").rstrip("/")
+
+# Only auto-start a kernel we'd actually be able to reach: skip entirely if
+# the caller pointed KERNEL_URL somewhere else (a remote kernel, a
+# different port) via the env var -- spawning a *local* subprocess would
+# never help in that case, and could confuse a deliberately-remote setup.
+_KERNEL_URL_IS_DEFAULT = "DENSE_EVOLUTION_KERNEL_URL" not in os.environ
+
+# Set by tests to route through httpx.ASGITransport straight into the real,
+# in-process local_site.app.server.app (see tests/integration/test_mcp_server.py) --
+# None here means "use a real TCP connection to KERNEL_URL", unchanged from
+# before this existed. This is the one seam in the whole adapter: it lets
+# tests exercise every tool function against the real FastAPI kernel (real
+# DenseSVSimulator, real PennyLane Hamiltonians -- no mocked physics) without
+# a live subprocess bound to a real port in CI.
+_TEST_TRANSPORT = None
+
+# Lazily-created, reused across calls -- _request used to open a fresh
+# httpx.AsyncClient (TCP handshake to the kernel) per tool call, real
+# overhead for an MCP session that calls many tools in a row. Keyed on
+# (_TEST_TRANSPORT identity, KERNEL_URL): production code never changes
+# KERNEL_URL after import (it's a plain module-level constant read once
+# from os.environ), but the test suite mutates both KERNEL_URL and
+# _TEST_TRANSPORT directly to exercise the unreachable-kernel path, and its
+# autouse fixture swaps _TEST_TRANSPORT to a fresh ASGITransport before
+# every test and back to None after -- a client cached against a stale
+# transport or base_url must not be reused across either kind of swap.
+_shared_client: Optional[httpx.AsyncClient] = None
+_shared_client_key = None  # (transport identity, base_url) the cached client was built with
+# Issue #258 point 6 asked whether the originally-suspected data race here
+# is actually reachable: verified by reading the installed mcp package
+# (mcp/shared/jsonrpc_dispatcher.py) -- tool calls are dispatched via
+# `anyio.create_task_group()` / `start_soon`, i.e. concurrent tasks on ONE
+# event loop, never separate OS threads. _get_client() has no `await`
+# inside it, so it can't actually be preempted mid-check-then-create by
+# another task today -- the race prog.txt described isn't currently live.
+# This threading.Lock (not asyncio.Lock -- that was the first attempt,
+# reverted for breaking 3 tests that monkeypatch _get_client as a plain
+# sync callable) is defensive, not a fix for an active bug: near-zero cost
+# uncontended, and it keeps this safe if a future edit ever adds an
+# `await` here or a caller ever invokes it off the event-loop thread.
+_client_lock = threading.Lock()
+
+
+def _get_client() -> httpx.AsyncClient:
+    global _shared_client, _shared_client_key
+    current_key = (id(_TEST_TRANSPORT), KERNEL_URL)
+    with _client_lock:
+        if _shared_client is None or _shared_client_key != current_key:
+            # Client-level timeout is just the fallback ceiling -- every real
+            # call site passes its own timeout= to _request, sized to that
+            # endpoint's actual expected cost (a health check and a 10-minute
+            # VQE run have nothing in common).
+            _shared_client = httpx.AsyncClient(base_url=KERNEL_URL, transport=_TEST_TRANSPORT, timeout=DEFAULT_TIMEOUT)
+            _shared_client_key = current_key
+        return _shared_client
+
+
+async def ensure_kernel_running(startup_wait: float = 20.0, poll_interval: float = 0.5) -> None:
+    """Best-effort auto-start for the Composer kernel, called once from
+    server.py's main() before mcp.run() starts serving tool calls -- not
+    from _request()'s own error handling, so the existing
+    kernel-unreachable tests (which force a real ConnectError against a
+    kernel that's deliberately never started) keep exercising that path
+    unmodified and un-slowed.
+
+    Skips entirely if KERNEL_URL was overridden via the env var (a remote
+    or custom-port kernel -- spawning a local subprocess would never help
+    there), or if the kernel is already reachable. Otherwise spawns
+    `python -m local_site.app.server` detached, with its stdout/stderr
+    redirected away from this process's own stdio -- this process IS an
+    MCP stdio server, so anything the child wrote to inherited stdout
+    would corrupt the JSON-RPC stream -- and polls health for up to
+    `startup_wait` seconds (observed real cold-start: ~10s).
+
+    Never raises: if the composer extra isn't installed, the subprocess
+    fails to spawn, or it doesn't come up in time, this just returns and
+    the first real tool call gets the normal, actionable
+    KernelUnreachableError -- auto-start is a convenience on top of that
+    existing fallback, not a replacement for it."""
+    if not _KERNEL_URL_IS_DEFAULT:
+        return
+    try:
+        client = _get_client()
+        resp = await client.get("/api/health", timeout=2.0)
+        if resp.status_code == 200:
+            _warn_if_version_mismatch(resp.json())
+            return  # already up, nothing to do
+    except httpx.HTTPError:
+        pass  # genuinely unreachable -- fall through to the spawn attempt
+
+    try:
+        creationflags = subprocess.CREATE_NO_WINDOW if sys.platform == "win32" else 0
+        subprocess.Popen(
+            [sys.executable, "-m", "local_site.app.server"],
+            stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            start_new_session=(sys.platform != "win32"),
+            creationflags=creationflags,
+        )
+    except Exception:
+        return  # e.g. composer extra not installed -- let the normal error path handle it
+
+    import asyncio
+    elapsed = 0.0
+    while elapsed < startup_wait:
+        await asyncio.sleep(poll_interval)
+        elapsed += poll_interval
+        try:
+            resp = await client.get("/api/health", timeout=2.0)
+            if resp.status_code == 200:
+                _warn_if_version_mismatch(resp.json())
+                return
+        except httpx.HTTPError:
+            continue
+
+
+def version_mismatch_message(health: dict) -> Optional[str]:
+    """None if the kernel's dense_evolution_version matches the one
+    importable in this adapter's own environment (or the kernel didn't
+    report one), else an actionable message describing the drift -- shared
+    by _warn_if_version_mismatch (stderr, at startup) and
+    dense_evolution_health (a `version_mismatch` JSON field, on every call)
+    so the two surfaces can never say something different for a bug this
+    trivial to describe consistently."""
+    kernel_version = health.get("dense_evolution_version")
+    if kernel_version is None:
+        return None
+    import dense_evolution
+    adapter_version = dense_evolution.__version__
+    if kernel_version == adapter_version:
+        return None
+    return (
+        f"Kernel is running dense_evolution {kernel_version}, but this MCP adapter's "
+        f"own environment has {adapter_version} installed. The kernel process was "
+        "likely started before the last `pip install --upgrade dense-evolution` -- "
+        "restart it (stop the running `dense-evolution serve` process, then start it "
+        "again) to pick up the current version."
+    )
+
+
+def _warn_if_version_mismatch(health: dict) -> None:
+    """Print version_mismatch_message to stderr (never stdout -- this
+    process is an MCP stdio server) if there is one. Deliberately does NOT
+    kill/restart the kernel automatically: it may be a long-running process
+    someone is actively using through the public Composer web page, and
+    force-killing another user's live session to fix a version drift this
+    adapter merely noticed would be a worse failure mode than the drift
+    itself. Surfacing it loudly (here, and again on every
+    dense_evolution_health call -- see system_tools.py) is the safe middle
+    ground: visible, never destructive."""
+    message = version_mismatch_message(health)
+    if message is not None:
+        print(f"[dense_evolution_mcp] WARNING: {message}", file=sys.stderr)
+
+
+async def close_shared_client() -> None:
+    """Closes the shared client's connection pool, if one was ever created,
+    and resets the cache so a later call rebuilds a fresh one. Call this
+    once at process shutdown (server.py's main(), in a try/finally around
+    mcp.run()) -- without it httpx logs unclosed-connection warnings when
+    the interpreter exits, and a dev reload can leave the client bound to
+    an event loop that's already gone."""
+    global _shared_client, _shared_client_key
+    with _client_lock:
+        client, _shared_client, _shared_client_key = _shared_client, None, None
+    if client is not None:
+        await client.aclose()
+
+
+class KernelError(RuntimeError):
+    """Base for every error this adapter raises about reaching or talking to
+    the kernel. `kind` is a short, stable token -- not the message text --
+    that catch_errors below embeds in its "Error: <kind>: ..." output, so
+    an MCP client can branch on error type (prog.txt Sezione 3, punto 10:
+    "ConnectError -> suggerisci dense-evolution serve; TimeoutException ->
+    suggerisci di ridurre n_qubits; ...") without parsing prose."""
+    kind = "kernel_error"
+
+
+class KernelUnreachableError(KernelError):
+    kind = "unreachable"
+
+
+class KernelTimeoutError(KernelError):
+    kind = "timeout"
+
+
+class KernelProtocolError(KernelError):
+    kind = "protocol_error"
+
+
+class KernelConnectionClosedError(KernelError):
+    kind = "connection_closed"
+
+
+class KernelHTTPError(KernelError):
+    kind = "http_error"
+
+
+async def _request(method: str, path: str, timeout: float = DEFAULT_TIMEOUT, **kwargs) -> dict:
+    """Reusable request helper for every tool. `timeout` (seconds) should be
+    sized to the specific endpoint's real expected cost -- see each tool's
+    own call site."""
+    client = _get_client()
+    try:
+        resp = await client.request(method, path, timeout=timeout, **kwargs)
+    except httpx.ConnectError:
+        raise KernelUnreachableError(
+            f"Dense Evolution kernel not reachable at {KERNEL_URL}. Start it with "
+            "`dense-evolution serve` (or `python -m local_site.app.server` from the "
+            "repo root), then retry. Use dense_evolution_health to check connectivity."
+        )
+    except httpx.TimeoutException:
+        raise KernelTimeoutError(
+            f"Request to the Dense Evolution kernel timed out after {timeout:g}s -- the "
+            "simulation may be too large or slow for this request (e.g. high qubit "
+            "count, many VQE iterations, or a long MD trajectory). Try reducing its size."
+        )
+    except httpx.RemoteProtocolError:
+        # kernel process died/crashed mid-response rather than closing the
+        # connection cleanly -- the exact symptom documented in the README
+        # for the BLAS/eigh thread-safety issue under wormhole_scan's heavy
+        # linear algebra, not a generic network blip.
+        raise KernelProtocolError(
+            "Dense Evolution kernel terminated mid-response, likely the BLAS "
+            "thread-safety issue documented in the README for heavy linear "
+            "algebra (e.g. wormhole_scan). Retry, or reduce the request's size."
+        )
+    except httpx.ReadError:
+        raise KernelConnectionClosedError(
+            f"Connection to the Dense Evolution kernel at {KERNEL_URL} was closed "
+            "before the response finished -- the kernel process may have crashed. "
+            "Use dense_evolution_health to check it's still up, then retry."
+        )
+    except httpx.HTTPError as e:
+        # Catch-all for the rest of httpx's exception hierarchy (e.g.
+        # WriteError, PoolTimeout) that isn't specific enough to warrant its
+        # own message/kind above.
+        raise KernelError(f"Dense Evolution kernel request failed: {e}")
+    if resp.status_code >= 400:
+        try:
+            detail = resp.json().get("detail", resp.text)
+        except Exception:
+            detail = resp.text
+        raise KernelHTTPError(f"Dense Evolution kernel returned HTTP {resp.status_code}: {detail}")
+    return resp.json()
+
+
+def _handle_error(e: Exception) -> str:
+    """Consistent error formatting across all tools: "Error: <kind>:
+    <message>". `kind` is a stable token (see the KernelError hierarchy
+    above for kernel-communication errors; "invalid_input" for a
+    ValueError a tool's own validation raised, e.g. models.py's
+    cross-field checks; "internal" for anything else) an MCP client can
+    branch on programmatically, without parsing message prose -- the
+    "Error: " prefix itself is unchanged so every existing
+    `result.startswith("Error:")` check still holds."""
+    if isinstance(e, KernelError):
+        kind = e.kind
+    elif isinstance(e, ValueError):
+        kind = "invalid_input"
+    else:
+        kind = "internal"
+    return f"Error: {kind}: {e}"
+
+
+def catch_errors(func):
+    """Wraps an async tool function so any exception raised anywhere in its
+    body becomes the same "Error: ..." string every tool used to return
+    from its own try/except -- replaces ~20 repeated
+    `try: ... except Exception as e: return _handle_error(e)` blocks with
+    one decorator.
+
+    A strict superset of the old behavior for the handful of tools whose
+    try block only wrapped part of the function -- e.g.
+    dense_evolution_run_circuit's post-request image saving/truncation used
+    to sit OUTSIDE its try block, so an exception there would have
+    propagated uncaught; now it's caught too.
+
+    Tools that do their own internal per-item exception handling
+    (dense_evolution_energy_scan, dense_evolution_wormhole_scan -- a single
+    failed point shouldn't abort the whole batch) are unaffected by this:
+    it only adds an outer safety net around exceptions those inner
+    try/excepts don't already catch (e.g. a bug in the post-loop
+    aggregation code), it does not change their partial-failure behavior.
+    """
+    @functools.wraps(func)
+    async def wrapper(*args, **kwargs):
+        try:
+            return await func(*args, **kwargs)
+        except Exception as e:
+            return _handle_error(e)
+    return wrapper

mcp_server/config.py

@@ -0,0 +1,32 @@
+"""Central configuration for the dense_evolution_mcp adapter: the MCP
+tool-annotation presets shared across every tool, plus DEFAULT_TIMEOUT.
+
+Two settings that conceptually belong here are deliberately NOT here,
+because the test suite mutates them directly and that mutation has to
+reach the specific function that reads them as its own module global (a
+`from .config import X` copy elsewhere would silently stop seeing the
+mutation): KERNEL_URL/_TEST_TRANSPORT live in client.py (see its
+docstring), and IMAGE_OUTPUT_DIR/IMAGE_MAX_FILES live in utils/images.py
+(see its docstring) since that's where _save_png/_prune_old_images moved
+in Phase 2 of the refactor (prog.txt Sezione 3).
+"""
+
+READ_ONLY_IDEMPOTENT = {
+    "readOnlyHint": True,
+    "destructiveHint": False,
+    "idempotentHint": True,
+    "openWorldHint": False,
+}
+# Circuit/VQE/MD runs don't mutate any stored resource -- nothing server-side
+# persists between calls -- so they're "read-only" in the MCP sense too, but
+# re-running with the same seed can differ slightly run-to-run (floating
+# point reduction order in the linear-algebra backend), so idempotentHint
+# is left False for anything that actually executes a simulation.
+COMPUTE = {
+    "readOnlyHint": True,
+    "destructiveHint": False,
+    "idempotentHint": False,
+    "openWorldHint": False,
+}
+
+DEFAULT_TIMEOUT = 60.0  # fallback for any call site that doesn't pass timeout= explicitly