dense-evolution 8.3.0__py3-none-win_amd64.whl

mcp_server/tools/system_tools.py

@@ -0,0 +1,149 @@
+"""Tools: kernel status and catalogs (presets, gates, noise models,
+molecules). Registered against the shared `mcp` instance created in
+server.py -- see that module's docstring for why importing `mcp` back
+from there (rather than the other way around) is safe despite looking
+circular."""
+import json
+
+from .. import client
+from ..client import _request, catch_errors
+from ..config import READ_ONLY_IDEMPOTENT
+from ..models import ListMoleculesInput
+from ..molecules import _get_annotated_molecule_catalog, _molecule_catalog_cache
+from ..server import mcp
+from ..utils import images as _images
+
+
+@mcp.tool(name="dense_evolution_health", annotations={"title": "Check Dense Evolution kernel status", **READ_ONLY_IDEMPOTENT})
+@catch_errors
+async def dense_evolution_health() -> str:
+    """Check whether the local Dense Evolution Composer kernel is running and reachable.
+
+    Always call this first if unsure whether the kernel is up -- every other
+    tool in this server depends on it. Returns the kernel's dense_evolution
+    version, hostname, and free/total RAM (useful to sanity-check qubit-count
+    limits before requesting a large simulation).
+
+    Returns:
+        str: JSON with {status, dense_evolution_version, hostname,
+        total_ram_gb, available_ram_gb, ram_percent_free}, plus a
+        `version_mismatch` warning if the kernel's dense_evolution differs
+        from the one importable in this MCP adapter's own environment (a
+        stale kernel process left running across a `pip install --upgrade
+        dense-evolution` silently serves the old version's behavior --
+        this makes that visible instead of a confusing missing-feature
+        report), or an "Error: ..." string if the kernel is not running.
+    """
+    result = await _request("GET", "/api/health", timeout=5.0)
+    mismatch = client.version_mismatch_message(result)
+    if mismatch is not None:
+        result["version_mismatch"] = mismatch
+    return json.dumps(result, indent=2)
+
+
+@mcp.tool(name="dense_evolution_system_limits", annotations={"title": "Get max safe qubit count", **READ_ONLY_IDEMPOTENT})
+@catch_errors
+async def dense_evolution_system_limits() -> str:
+    """Get the maximum qubit count this machine can currently simulate with
+    a dense statevector, computed from actual free RAM right now (not a
+    fixed constant) -- call before requesting a large `dense_evolution_run_circuit`.
+
+    Returns:
+        str: JSON describing the current safe qubit ceiling for the dense backend.
+    """
+    return json.dumps(await _request("GET", "/api/system_limits", timeout=5.0), indent=2)
+
+
+@mcp.tool(name="dense_evolution_kernel_status", annotations={"title": "Inspect this MCP adapter's own local state", **READ_ONLY_IDEMPOTENT})
+@catch_errors
+async def dense_evolution_kernel_status() -> str:
+    """Report this MCP adapter's own local configuration and diagnostics --
+    distinct from dense_evolution_health, which only proxies the kernel's
+    own /api/health. Useful for debugging the adapter process itself:
+    which kernel URL it's pointed at, whether that kernel currently
+    answers, how many circuit/histogram/Q-sphere PNGs have piled up on
+    disk (see the module docstring on why images are saved to disk
+    instead of inlined), and how warm the molecule-catalog cache is.
+
+    Returns:
+        str: JSON with {kernel_url, kernel_reachable, image_output_dir,
+        image_count, image_max_files, molecule_cache_entries}.
+    """
+    try:
+        await _request("GET", "/api/health", timeout=5.0)
+        reachable = True
+    except Exception:
+        reachable = False
+
+    image_dir = _images.IMAGE_OUTPUT_DIR
+    image_count = len(list(image_dir.glob("*.png"))) if image_dir.exists() else 0
+
+    return json.dumps({
+        "kernel_url": client.KERNEL_URL,
+        "kernel_reachable": reachable,
+        "image_output_dir": str(image_dir),
+        "image_count": image_count,
+        "image_max_files": _images.IMAGE_MAX_FILES,
+        "molecule_cache_entries": len(_molecule_catalog_cache),
+    }, indent=2)
+
+
+@mcp.tool(name="dense_evolution_list_presets", annotations={"title": "List preset OpenQASM circuits", **READ_ONLY_IDEMPOTENT})
+@catch_errors
+async def dense_evolution_list_presets() -> str:
+    """List the built-in example OpenQASM circuits bundled with the Composer
+    (e.g. Bell state, GHZ, QFT) -- useful as ready-made input for
+    `dense_evolution_run_circuit` without writing QASM by hand.
+
+    Returns:
+        str: JSON mapping preset names to their OpenQASM source text.
+    """
+    return json.dumps(await _request("GET", "/api/presets", timeout=5.0), indent=2)
+
+
+@mcp.tool(name="dense_evolution_list_gates", annotations={"title": "List available quantum gates", **READ_ONLY_IDEMPOTENT})
+@catch_errors
+async def dense_evolution_list_gates() -> str:
+    """List every gate the graphical circuit builder (and therefore
+    `dense_evolution_build_circuit`) supports, with their display metadata.
+
+    Returns:
+        str: JSON gate palette (name, symbol, qubit arity, etc. per gate).
+    """
+    return json.dumps(await _request("GET", "/api/palette", timeout=5.0), indent=2)
+
+
+@mcp.tool(name="dense_evolution_list_noise_models", annotations={"title": "List available noise models", **READ_ONLY_IDEMPOTENT})
+@catch_errors
+async def dense_evolution_list_noise_models() -> str:
+    """List the real Kraus-channel noise models available for
+    `dense_evolution_run_circuit` and the mitigation tools (e.g.
+    depolarizing, amplitude damping, bit-flip).
+
+    Returns:
+        str: JSON mapping noise model names to their parameters/description.
+    """
+    return json.dumps(await _request("GET", "/api/noise_models", timeout=5.0), indent=2)
+
+
+@mcp.tool(name="dense_evolution_list_molecules", annotations={"title": "List catalog molecules", **READ_ONLY_IDEMPOTENT})
+@catch_errors
+async def dense_evolution_list_molecules(params: ListMoleculesInput) -> str:
+    """List every molecule in the built-in Hartree-Fock catalog, each with
+    its real qubit count under the requested mapping. Use this to find valid
+    `name` values for `dense_evolution_molecule_energy`, `_mix_molecules`,
+    `_run_vqe`, `_qmmm_forces`, `_md_trajectory`, and `_energy_scan`.
+
+    Each entry includes a short `id` (e.g. "H2", "LiH", "HeH+") derived from
+    the catalog's full descriptive name -- pass either form to any tool that
+    takes a molecule `name`; the short id is easier to copy exactly across
+    multiple tool calls than the full "H2 (Idrogeno) - R = 0.7414 A
+    [equilibrio reale]"-style string.
+
+    Args:
+        params (ListMoleculesInput): mapping -- 'jordan_wigner' (default) or 'bravyi_kitaev'.
+
+    Returns:
+        str: JSON list of {id, full_name, symbols, geometry, charge, n_qubits} per molecule.
+    """
+    return json.dumps(await _get_annotated_molecule_catalog(params.mapping), indent=2)

mcp_server/tools/wormhole_tools.py

@@ -0,0 +1,142 @@
+"""Tools: traversable-wormhole-inspired quantum teleportation (SYK
+model)."""
+import json
+
+from ..client import _request, catch_errors
+from ..config import COMPUTE
+from ..models import WormholeScanInput, WormholeSelectInstanceInput, WormholeTeleportationInput
+from ..server import mcp
+
+
+@mcp.tool(name="dense_evolution_wormhole_select_instance",
+          annotations={"title": "Select a good SYK instance for wormhole teleportation", **COMPUTE})
+@catch_errors
+async def dense_evolution_wormhole_select_instance(params: WormholeSelectInstanceInput) -> str:
+    """Find a binary-sparse-SYK random-instance seed suitable for the
+    traversable-wormhole-inspired teleportation protocol
+    (`dense_evolution_wormhole_teleportation`).
+
+    A uniformly-random seed does NOT reliably show the protocol's
+    sign-dependent teleportation signal -- verified directly across many
+    seeds (some give a clean peak, some the wrong sign for most of a
+    sweep, some are flat noise). arXiv:2604.10090 didn't use an arbitrary
+    instance either: they picked one "selected for favorable commutation
+    properties" among their chosen terms. This tool reproduces that same
+    selection criterion -- screening `n_candidates` seeds by their exact
+    commuting/anticommuting term-pair count and returning the one closest
+    to `target_commuting` -- rather than trusting a random seed.
+
+    Always call this before `dense_evolution_wormhole_teleportation` /
+    `dense_evolution_wormhole_scan` unless you already have a known-good
+    seed (e.g. 61, for the defaults n_majorana=8/k_terms=10/target=34,
+    the exact match found and used throughout this project's own
+    verification -- see research/wormhole_syk.md).
+
+    Args:
+        params (WormholeSelectInstanceInput): n_majorana, k_terms, J,
+            n_candidates, target_commuting.
+
+    Returns:
+        str: JSON {seed, n_majorana, k_terms, commuting, anticommuting,
+        target_commuting} -- pass `seed` straight into
+        dense_evolution_wormhole_teleportation / _wormhole_scan.
+    """
+    return json.dumps(await _request("POST", "/api/wormhole_select_instance", timeout=60.0, json=params.model_dump()), indent=2)
+
+
+@mcp.tool(name="dense_evolution_wormhole_teleportation",
+          annotations={"title": "Run traversable-wormhole-inspired quantum teleportation", **COMPUTE})
+@catch_errors
+async def dense_evolution_wormhole_teleportation(params: WormholeTeleportationInput) -> str:
+    """Run one point of the real traversable-wormhole-inspired quantum
+    teleportation protocol (Gao-Jafferis-Wall theory, arXiv:2604.10090)
+    on a binary sparse SYK model: two coupled chaotic Hamiltonians (L,R),
+    a message injected into L via a reference-qubit pair (P,Q), a real
+    bilinear L-R coupling exp(i*mu*V), and a readout that is NOT a
+    single-qubit expectation value (which the no-signaling theorem
+    forbids from ever showing this signal) but the mutual information
+    between the reference qubit P and a qubit read out from R.
+
+    Returns a single mutual-information value for the given mu -- the
+    physically meaningful result is the *difference* between a positive-
+    and negative-mu run at the same (n_majorana, k_terms, seed, t0, t1).
+    Call this tool twice with opposite-sign mu, or use
+    dense_evolution_wormhole_scan to sweep many (t1, mu) combinations in
+    one batched call.
+
+    Requires a well-selected seed (see
+    dense_evolution_wormhole_select_instance) -- an arbitrary random seed
+    will likely not show a clean signal.
+
+    Args:
+        params (WormholeTeleportationInput): n_majorana, k_terms, J, mu,
+            t0, t1, seed, with_message, backend, n_steps_evolution,
+            n_steps_coupling.
+
+    Returns:
+        str: JSON {mutual_information_pt, backend, n_majorana, k_terms,
+        mu, t0, t1, seed, with_message}.
+    """
+    return json.dumps(await _request("POST", "/api/wormhole_teleportation", timeout=120.0, json=params.model_dump()), indent=2)
+
+
+@mcp.tool(name="dense_evolution_wormhole_scan",
+          annotations={"title": "Sweep the wormhole teleportation signal over t1", **COMPUTE})
+@catch_errors
+async def dense_evolution_wormhole_scan(params: WormholeScanInput) -> str:
+    """Sweep `t1_values` for the traversable-wormhole-inspired
+    teleportation protocol, running both +mu_magnitude and -mu_magnitude
+    at every point -- one call instead of 2*len(t1_values) separate
+    dense_evolution_wormhole_teleportation calls. Returns each point's
+    mutual information for both signs plus their difference (mu<0 minus
+    mu>0 in this project's own convention), the standard readout for the
+    protocol's qualitative signature: a smooth peak in that difference
+    across the sweep (known peak for seed=61/n_majorana=8/k_terms=10/
+    t0=0.3: around t1≈0.6-0.7).
+
+    Unlike dense_evolution_energy_scan, points run sequentially, not
+    concurrently: each single teleportation call does real exact
+    diagonalization (or Trotterized circuit execution) of the full joint
+    L+R+P+Q system and takes several seconds on its own (verified:
+    concurrent calls to this specific endpoint crashed the kernel process
+    outright -- a real BLAS/eigh thread-safety issue under this protocol's
+    heavier-than-usual concurrent linear algebra, not present in the
+    lighter Hamiltonian-diagonalization calls energy_scan batches). A
+    full 20-point sweep can take several minutes; start with fewer points
+    to gauge cost.
+
+    A point that fails does not abort the rest of the sweep; its error is
+    reported alongside the successful points.
+
+    Args:
+        params (WormholeScanInput): n_majorana, k_terms, J, mu_magnitude,
+            t0, t1_values (list, max 20 points), seed, with_message,
+            backend, n_steps_evolution, n_steps_coupling.
+
+    Returns:
+        str: JSON with:
+        {
+            "n_points": int,
+            "results": [{"t1": float, "mu_positive": float, "mu_negative": float, "delta": float} |
+                        {"t1": float, "error": str}, ...],
+            "peak": {"t1": ..., "delta": ...} | null  # point with the largest delta, successful points only
+        }
+    """
+    async def _one_point(t1):
+        base = dict(
+            n_majorana=params.n_majorana, k_terms=params.k_terms, J=params.J, t0=params.t0, t1=t1,
+            seed=params.seed, with_message=params.with_message, backend=params.backend,
+            n_steps_evolution=params.n_steps_evolution, n_steps_coupling=params.n_steps_coupling,
+        )
+        try:
+            pos = await _request("POST", "/api/wormhole_teleportation", timeout=120.0, json={**base, "mu": params.mu_magnitude})
+            neg = await _request("POST", "/api/wormhole_teleportation", timeout=120.0, json={**base, "mu": -params.mu_magnitude})
+            i_pos, i_neg = pos["mutual_information_pt"], neg["mutual_information_pt"]
+            return {"t1": t1, "mu_positive": i_pos, "mu_negative": i_neg, "delta": i_neg - i_pos}
+        except Exception as e:
+            return {"t1": t1, "error": str(e)}
+
+    results = [await _one_point(t1) for t1 in params.t1_values]
+    successful = [r for r in results if "delta" in r]
+    peak = max(successful, key=lambda r: r["delta"]) if successful else None
+    return json.dumps({"n_points": len(results), "results": results, "peak": peak}, indent=2)

mcp_server/utils/cache.py

@@ -0,0 +1,55 @@
+"""A minimal in-memory TTL cache, used to avoid re-fetching the
+(effectively static) molecule catalog on every tool call that needs to
+resolve a molecule name, while still eventually picking up a real catalog
+change (e.g. after a kernel restart with a different build) instead of
+caching forever like the pre-Phase-2 code did (a plain dict, reset only by
+the test suite, never by production code). Also caches FAILURES for a
+short TTL, so a tight loop of tool calls made while the kernel is down
+doesn't each wait out their own full connection/timeout error -- see
+`set_failure`/`get`'s re-raise behavior below.
+"""
+import time
+from typing import Any, Optional
+
+
+class TTLCache:
+    def __init__(self, ttl_seconds: float = 300.0, failure_ttl_seconds: float = 10.0):
+        self._ttl = ttl_seconds
+        self._failure_ttl = failure_ttl_seconds
+        # key -> (expires_at, value_or_exception, is_failure)
+        self._store: dict[str, tuple[float, Any, bool]] = {}
+
+    def get(self, key: str):
+        """Returns the cached value, or None if missing/expired. Re-raises
+        a cached failure (so callers see the same error shape they would
+        from a fresh call) instead of returning it as if it were a value."""
+        entry = self._store.get(key)
+        if entry is None:
+            return None
+        expires_at, value, is_failure = entry
+        if time.monotonic() >= expires_at:
+            del self._store[key]
+            return None
+        if is_failure:
+            raise value
+        return value
+
+    def set(self, key: str, value: Any) -> None:
+        self._store[key] = (time.monotonic() + self._ttl, value, False)
+
+    def set_failure(self, key: str, exc: Exception) -> None:
+        self._store[key] = (time.monotonic() + self._failure_ttl, exc, True)
+
+    def invalidate(self, key: Optional[str] = None) -> None:
+        """Clears one key, or the whole cache if key is None."""
+        if key is None:
+            self._store.clear()
+        else:
+            self._store.pop(key, None)
+
+    def __len__(self) -> int:
+        """Raw entry count, including any not-yet-pruned expired ones --
+        entries only drop out on their next get(), not on a timer. Good
+        enough for a diagnostics tool (dense_evolution_kernel_status);
+        don't rely on this for anything that needs an exact live count."""
+        return len(self._store)

mcp_server/utils/images.py

@@ -0,0 +1,67 @@
+"""Image saving, rotating cleanup, and metadata for the dense_evolution_mcp
+adapter. Images (circuit diagrams, histograms, Q-sphere, Bloch vectors)
+come back from the kernel as base64 PNGs; see the top-level server.py
+module docstring for why they're written to disk instead of inlined.
+
+IMAGE_OUTPUT_DIR/IMAGE_MAX_FILES are defined HERE rather than in config.py,
+for the same reason KERNEL_URL/_TEST_TRANSPORT live in client.py rather
+than config.py (see client.py's own docstring): the test suite mutates
+both directly (`mcp_images.IMAGE_OUTPUT_DIR = tmp_path`), and that
+mutation only works if the value's single source of truth lives in the
+same module that reads it -- _prune_old_images/_save_png, which moved here
+in Phase 2 of the refactor (see prog.txt Sezione 3).
+
+Each saved PNG also gets an optional sidecar `<name>_<ts>.json` with
+whatever metadata the caller passes in (tool name, qasm, seed, ...) --
+BUG FIX: previously a saved image's filename (`circuit_<timestamp>.png`)
+carried no way to trace it back to the circuit/tool call that produced it,
+so an agent (or a human) looking at ~/.dense_evolution_mcp/images later
+had no way to tell which image was which beyond the generic `name` prefix
+shared by every call of the same kind.
+"""
+import base64
+import json
+import os
+import time
+from pathlib import Path
+from typing import Optional
+
+IMAGE_OUTPUT_DIR = Path(
+    os.environ.get("DENSE_EVOLUTION_MCP_IMAGE_DIR", str(Path.home() / ".dense_evolution_mcp" / "images"))
+)
+# Every include_visualizations=True call writes a new timestamped PNG with
+# no cleanup -- a long-running MCP session (or an agent looping over many
+# circuits) grows this directory without bound. Cap it to the most
+# recently written files; 0 or negative disables pruning entirely.
+IMAGE_MAX_FILES = int(os.environ.get("DENSE_EVOLUTION_MCP_IMAGE_MAX_FILES", "500"))
+
+
+def _prune_old_images() -> None:
+    """Keep at most IMAGE_MAX_FILES PNGs in IMAGE_OUTPUT_DIR, deleting the
+    oldest by mtime first (and their metadata sidecar, if any). Read at
+    call time (not module import) so tests that monkeypatch
+    IMAGE_OUTPUT_DIR/IMAGE_MAX_FILES take effect."""
+    if IMAGE_MAX_FILES <= 0:
+        return
+    files = sorted(IMAGE_OUTPUT_DIR.glob("*.png"), key=lambda p: p.stat().st_mtime)
+    excess_count = len(files) - IMAGE_MAX_FILES
+    for path in files[:excess_count]:
+        path.unlink(missing_ok=True)
+        path.with_suffix(".json").unlink(missing_ok=True)
+
+
+def _save_png(b64_png: Optional[str], name: str, metadata: Optional[dict] = None) -> Optional[str]:
+    """Decode a base64 PNG from the kernel and write it to disk, returning
+    the path instead of the raw base64 -- see module docstring. If
+    `metadata` is given, also writes a `<same-stem>.json` sidecar next to
+    the PNG (e.g. {"tool": "dense_evolution_run_circuit", "qasm": ...,
+    "seed": ..., "n_qubits": ...})."""
+    if not b64_png:
+        return None
+    IMAGE_OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    path = IMAGE_OUTPUT_DIR / f"{name}_{int(time.time() * 1000)}.png"
+    path.write_bytes(base64.b64decode(b64_png))
+    if metadata is not None:
+        path.with_suffix(".json").write_text(json.dumps(metadata, indent=2))
+    _prune_old_images()
+    return str(path)

mcp_server/utils/truncation.py

@@ -0,0 +1,38 @@
+"""Truncation of large numeric arrays (statevector, probabilities) to
+their most significant entries -- a full statevector/probability array can
+be thousands of entries for a 20+ qubit circuit; agents almost always care
+about the dominant amplitudes, not the full dense array.
+
+`top_k` is configurable per call (`RunCircuitInput.top_k`, threaded
+through from dense_evolution_run_circuit) rather than a fixed 25 -- BUG
+FIX: the pre-Phase-2 code hardcoded top_k=25 in the function signature
+with no way for a caller to ask for more or fewer entries.
+
+Measurement `counts` are deliberately NOT truncated here (a real, open
+question from prog.txt's diagnosis, not silently dropped): `counts` is
+already naturally bounded by `shots` (RunCircuitInput caps that at
+1,000,000) and by the number of distinct basis states actually observed,
+which for realistic qubit counts is far smaller than a full statevector.
+Truncating it to a top-K + "other" shape would change
+dense_evolution_run_circuit's response schema for every caller, not just
+opt-in behavior -- left for a separate, deliberate decision rather than
+folded into this phase's mechanical extraction.
+"""
+
+
+def _truncate_statevector(rows: list, top_k: int = 25) -> dict:
+    sorted_rows = sorted(rows, key=lambda r: -r["abs"])
+    return {
+        "total_nonzero_amplitudes": len(rows),
+        "shown": min(top_k, len(rows)),
+        "top_amplitudes_by_magnitude": sorted_rows[:top_k],
+    }
+
+
+def _truncate_probabilities(probs: list, top_k: int = 25) -> dict:
+    indexed = sorted(enumerate(probs), key=lambda t: -t[1])[:top_k]
+    return {
+        "total_basis_states": len(probs),
+        "shown": min(top_k, len(probs)),
+        "top_states_by_probability": [{"index": i, "probability": p} for i, p in indexed],
+    }