dense-evolution 8.3.0__py3-none-win_amd64.whl

mcp_server/tools/chemistry_tools.py

@@ -0,0 +1,225 @@
+"""Tools: molecular Hamiltonians, VQE, QM/MM forces, and molecular
+dynamics."""
+import asyncio
+import json
+
+from ..client import _request, catch_errors
+from ..config import COMPUTE
+from ..models import (
+    CustomMoleculeInput, EnergyScanInput, MassDecompositionInput, MdTrajectoryInput, MixMoleculesInput,
+    MoleculeEnergyInput, NativeHfDiagnosticsInput, QmmmForcesInput, RunVqeInput,
+)
+from ..molecules import _resolve_molecule_name
+from ..server import mcp
+
+
+@mcp.tool(name="dense_evolution_molecule_energy", annotations={"title": "Get catalog molecule ground-state energy", **COMPUTE})
+@catch_errors
+async def dense_evolution_molecule_energy(params: MoleculeEnergyInput) -> str:
+    """Compute the exact ground-state energy of a catalog molecule via real
+    Hartree-Fock + Jordan-Wigner/Bravyi-Kitaev Hamiltonian construction and
+    exact dense diagonalization.
+
+    Args:
+        params (MoleculeEnergyInput): name (short id or full catalog name), mapping.
+
+    Returns:
+        str: JSON with n_qubits, symbols, geometry, charge, ground_state_energy_hartree.
+        "Error: ..." with a 404-style message if `name` is not in the catalog
+        (call dense_evolution_list_molecules to see valid names/ids).
+    """
+    resolved = await _resolve_molecule_name(params.name)
+    payload = {**params.model_dump(), "name": resolved}
+    return json.dumps(await _request("POST", "/api/hamiltonian/molecule", timeout=60.0, json=payload), indent=2)
+
+
+@mcp.tool(name="dense_evolution_mix_molecules", annotations={"title": "Mix two catalog Hamiltonians", **COMPUTE})
+@catch_errors
+async def dense_evolution_mix_molecules(params: MixMoleculesInput) -> str:
+    """Compute H_mix = weight_a*H_a + weight_b*H_b for two catalog molecules
+    that share the same qubit count (same electron space), and diagonalize
+    all three (H_a, H_b, H_mix) for their ground-state energies. Mixing
+    molecules with different qubit counts is physically meaningless and is
+    rejected with a clear error.
+
+    Args:
+        params (MixMoleculesInput): name_a, name_b (short id or full catalog name), weight_a, weight_b, mapping.
+
+    Returns:
+        str: JSON with n_qubits, energy_a, energy_b, energy_mixed (all in Hartree).
+    """
+    name_a = await _resolve_molecule_name(params.name_a)
+    name_b = await _resolve_molecule_name(params.name_b)
+    payload = {**params.model_dump(), "name_a": name_a, "name_b": name_b}
+    return json.dumps(await _request("POST", "/api/hamiltonian/mix", timeout=60.0, json=payload), indent=2)
+
+
+@mcp.tool(name="dense_evolution_custom_molecule_energy", annotations={"title": "Get custom molecule ground-state energy", **COMPUTE})
+@catch_errors
+async def dense_evolution_custom_molecule_energy(params: CustomMoleculeInput) -> str:
+    """Compute the ground-state energy of an arbitrary molecule (not in the
+    catalog) from its atomic symbols and geometry, via the same Hartree-Fock
+    pipeline as the catalog. Small molecules only -- exact dense
+    diagonalization caps out at 12 qubits, rejected before PennyLane runs if
+    the electron/orbital count would exceed that.
+
+    Args:
+        params (CustomMoleculeInput): symbols, geometry, charge, mapping.
+            len(symbols) must equal len(geometry).
+
+    Returns:
+        str: JSON with n_qubits, ground_state_energy_hartree, or "Error: ..."
+        if the molecule needs more than 12 qubits.
+    """
+    return json.dumps(await _request("POST", "/api/hamiltonian/custom", timeout=60.0, json=params.model_dump()), indent=2)
+
+
+@mcp.tool(name="dense_evolution_native_hf_diagnostics", annotations={"title": "Diagnose Hartree-Fock SCF convergence", **COMPUTE})
+@catch_errors
+async def dense_evolution_native_hf_diagnostics(params: NativeHfDiagnosticsInput) -> str:
+    """Run real Hartree-Fock SCF (dense_evolution.native_hf, the fallback
+    path for elements outside PennyLane's bundled STO-3G table, e.g.
+    Silicon) and run Dense-Armor's Hampel/Tukey anomaly filters over the
+    real per-iteration energy trace, instead of trusting the final
+    `converged` flag alone. Needs the `armor` extra (pip install
+    dense-evolution[armor]) -- returns an actionable "Error: ..." if it
+    isn't installed.
+
+    Args:
+        params (NativeHfDiagnosticsInput): symbols, geometry, charge,
+            active_electrons, active_orbitals. len(symbols) must equal len(geometry).
+
+    Returns:
+        str: JSON with n_qubits, converged, n_iterations,
+        electronic_energy_hartree, total_energy_hartree,
+        n_anomalies_hampel, n_anomalies_tukey, anomaly_fraction_hampel,
+        anomaly_fraction_tukey.
+    """
+    return json.dumps(await _request("POST", "/api/native_hf/diagnose", timeout=60.0, json=params.model_dump()), indent=2)
+
+
+@mcp.tool(name="dense_evolution_mass_decomposition", annotations={"title": "Check a mass-spectrometry neutral loss", **COMPUTE})
+@catch_errors
+async def dense_evolution_mass_decomposition(params: MassDecompositionInput) -> str:
+    """Check whether a mass-spectrometry peak-pair difference is a
+    chemically valid, reachable sub-formula mass of a precursor formula
+    (dense_evolution.utils.mass_decomposition, promoted from CASMI26
+    spectral-identification work). `nearest_reachable_mass` is the exact,
+    RDBE-filtered answer; `density_at_target` is a plausibility density
+    from the same landscape via FFT, not a probability.
+
+    Args:
+        params (MassDecompositionInput): formula, target_mass, max_mass.
+
+    Returns:
+        str: JSON with formula_counts, rdbe, nearest_reachable_mass, density_at_target.
+    """
+    return json.dumps(await _request("POST", "/api/mass_decomposition", timeout=30.0, json=params.model_dump()), indent=2)
+
+
+@mcp.tool(name="dense_evolution_energy_scan", annotations={"title": "Scan ground-state energy over several geometries", **COMPUTE})
+@catch_errors
+async def dense_evolution_energy_scan(params: EnergyScanInput) -> str:
+    """Compute the ground-state energy at each of several geometries in one
+    call -- e.g. a bond-length dissociation curve or a bond-angle sweep --
+    instead of calling dense_evolution_custom_molecule_energy once per
+    point. Points are evaluated concurrently against the kernel. A point
+    that fails (e.g. too many qubits for exact diagonalization) is reported
+    with its own error and does not abort the rest of the scan.
+
+    Args:
+        params (EnergyScanInput): symbols, geometries (list of points, max 50),
+            charge, mapping, labels (optional, one per point).
+
+    Returns:
+        str: JSON with:
+        {
+            "n_points": int,
+            "results": [{"label": ..., "n_qubits": int, "ground_state_energy_hartree": float} | {"label": ..., "error": str}, ...],
+            "minimum": {"label": ..., "ground_state_energy_hartree": float} | null  # over successful points only
+        }
+    """
+    if params.labels is not None and len(params.labels) != len(params.geometries):
+        raise ValueError(f"{len(params.labels)} labels but {len(params.geometries)} geometries -- must match.")
+    labels = params.labels if params.labels is not None else list(range(len(params.geometries)))
+
+    async def _one_point(label, geometry):
+        if len(params.symbols) != len(geometry):
+            return {"label": label, "error": f"{len(params.symbols)} symbols but {len(geometry)} geometry rows"}
+        try:
+            data = await _request(
+                "POST", "/api/hamiltonian/custom", timeout=60.0,
+                json={"symbols": params.symbols, "geometry": geometry, "charge": params.charge, "mapping": params.mapping},
+            )
+            return {"label": label, "n_qubits": data["n_qubits"], "ground_state_energy_hartree": data["ground_state_energy_hartree"]}
+        except Exception as e:
+            return {"label": label, "error": str(e)}
+
+    results = await asyncio.gather(*(_one_point(l, g) for l, g in zip(labels, params.geometries)))
+    successful = [r for r in results if "ground_state_energy_hartree" in r]
+    minimum = min(successful, key=lambda r: r["ground_state_energy_hartree"]) if successful else None
+    return json.dumps({"n_points": len(results), "results": results, "minimum": minimum}, indent=2)
+
+
+@mcp.tool(name="dense_evolution_run_vqe", annotations={"title": "Run VQE ground-state optimization", **COMPUTE})
+@catch_errors
+async def dense_evolution_run_vqe(params: RunVqeInput) -> str:
+    """Run real VQE (Adam gradient descent with adjoint differentiation)
+    against a molecule's Jordan-Wigner Hamiltonian, from a fresh random
+    start every call -- not a cached/precomputed result. Can take a while
+    for 'uccsd' ansatz or high maxiter; consider dense_evolution_health's
+    RAM figures and start with a small maxiter/n_layers to gauge cost first.
+
+    Args:
+        params (RunVqeInput): either `name` (short id or full catalog name)
+            or `symbols`+`geometry` (custom) must be given, plus
+            ansatz_type, n_layers, maxiter, step_size, beta1, beta2, seed.
+
+    Returns:
+        str: JSON with the optimized energy, convergence history, and
+        optimized parameters. "Error: ..." if neither name nor
+        symbols+geometry is provided, or the molecule is unknown.
+    """
+    payload = params.model_dump()
+    if params.name:
+        payload["name"] = await _resolve_molecule_name(params.name)
+    return json.dumps(await _request("POST", "/api/vqe", timeout=600.0, json=payload), indent=2)
+
+
+@mcp.tool(name="dense_evolution_qmmm_forces", annotations={"title": "Compute Hellmann-Feynman nuclear forces", **COMPUTE})
+@catch_errors
+async def dense_evolution_qmmm_forces(params: QmmmForcesInput) -> str:
+    """Compute real Hellmann-Feynman nuclear forces (F = -d<psi|H(R)|psi>/dR
+    via PennyLane autodiff, not finite differences) on a catalog molecule's
+    real Hartree-Fock ground state.
+
+    Args:
+        params (QmmmForcesInput): name (short id or full catalog name), mapping.
+
+    Returns:
+        str: JSON with per-atom force vectors and related energetics.
+    """
+    resolved = await _resolve_molecule_name(params.name)
+    payload = {**params.model_dump(), "name": resolved}
+    return json.dumps(await _request("POST", "/api/qmmm_forces", timeout=120.0, json=payload), indent=2)
+
+
+@mcp.tool(name="dense_evolution_md_trajectory", annotations={"title": "Run a molecular dynamics trajectory", **COMPUTE})
+@catch_errors
+async def dense_evolution_md_trajectory(params: MdTrajectoryInput) -> str:
+    """Run a real Velocity-Verlet MD trajectory driven by Hellmann-Feynman
+    forces at every step, for a catalog molecule.
+
+    Args:
+        params (MdTrajectoryInput): name (short id or full catalog name),
+            n_steps, dt_fs, mapping, recompute_electronic_state (true = true
+            ab-initio MD, capped at 30 steps; false = fixed electronic
+            state, capped at 200 steps).
+
+    Returns:
+        str: JSON with the trajectory (positions/energies per step).
+        "Error: ..." if n_steps is out of range for the chosen mode.
+    """
+    resolved = await _resolve_molecule_name(params.name)
+    payload = {**params.model_dump(), "name": resolved}
+    return json.dumps(await _request("POST", "/api/md_trajectory", timeout=600.0, json=payload), indent=2)

mcp_server/tools/circuit_tools.py

@@ -0,0 +1,83 @@
+"""Tools: circuit building and execution."""
+import json
+
+from ..client import _request, catch_errors
+from ..config import COMPUTE, READ_ONLY_IDEMPOTENT
+from ..models import BuildCircuitInput, RunCircuitInput
+from ..server import mcp
+from ..utils.images import _save_png
+from ..utils.truncation import _truncate_probabilities, _truncate_statevector
+
+
+@mcp.tool(name="dense_evolution_build_circuit", annotations={"title": "Build OpenQASM from gate operations", **READ_ONLY_IDEMPOTENT})
+@catch_errors
+async def dense_evolution_build_circuit(params: BuildCircuitInput) -> str:
+    """Convert a list of gate operations (as used by the graphical circuit
+    builder) into real OpenQASM text, ready to pass to `dense_evolution_run_circuit`.
+
+    Args:
+        params (BuildCircuitInput): n_qubits, ops (see dense_evolution_list_gates for valid gate names).
+
+    Returns:
+        str: JSON {"qasm": "..."} on success, or "Error: ..." if the op list is invalid.
+    """
+    data = await _request("POST", "/api/build_from_ops", timeout=30.0, json=params.model_dump())
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool(name="dense_evolution_run_circuit", annotations={"title": "Run an OpenQASM circuit", **COMPUTE})
+@catch_errors
+async def dense_evolution_run_circuit(params: RunCircuitInput) -> str:
+    """Run real OpenQASM on dense_evolution's DenseSVSimulator (or the MPS
+    backend for large circuits) and return measurement counts, probabilities,
+    and statevector amplitudes. Above the dense backend's safe qubit ceiling
+    (see dense_evolution_system_limits), automatically switches to an MPS
+    top-k-states approximation instead of failing.
+
+    Large statevectors/probability arrays are truncated to their most
+    significant entries (see 'shown' vs 'total_*' fields) to keep the
+    response usable in an agent's context -- the full histogram is always
+    returned in 'counts' since it's naturally bounded by `shots`.
+
+    Args:
+        params (RunCircuitInput): qasm, shots, seed, noise_model, noise_p, backend,
+            top_k, include_visualizations (see field descriptions).
+
+    Returns:
+        str: JSON with n_qubits, backend, counts, truncated probabilities/statevector,
+        fidelity_vs_ideal, and (if include_visualizations) paths to saved PNG files.
+        For circuits above the dense limit on the 'mps' backend, returns a
+        differently-shaped {"large_scale": true, "top_k_states": [...], ...} response.
+    """
+    payload = params.model_dump(exclude={"include_visualizations", "top_k"})
+    data = await _request("POST", "/api/run", timeout=60.0, json=payload)
+
+    image_metadata = {
+        "tool": "dense_evolution_run_circuit", "qasm": params.qasm, "shots": params.shots,
+        "seed": params.seed, "noise_model": params.noise_model, "noise_p": params.noise_p,
+        "backend": params.backend,
+    }
+
+    if data.get("large_scale"):
+        result = {k: v for k, v in data.items() if k != "circuit_png"}
+        if params.include_visualizations:
+            result["circuit_png_path"] = _save_png(data.get("circuit_png"), "circuit_large_scale", metadata=image_metadata)
+        return json.dumps(result, indent=2)
+
+    result = {
+        "n_qubits": data["n_qubits"],
+        "backend": data["backend"],
+        "counts": data["counts"],
+        "probabilities": _truncate_probabilities(data["probabilities"], top_k=params.top_k),
+        "statevector": _truncate_statevector(data["statevector"], top_k=params.top_k),
+        "fidelity_vs_ideal": data.get("fidelity_vs_ideal"),
+        "mps_max_bond_used": data.get("mps_max_bond_used"),
+        "mps_memory_mb": data.get("mps_memory_mb"),
+        "mps_avg_jsd": data.get("mps_avg_jsd"),
+    }
+    if params.include_visualizations:
+        result["circuit_png_path"] = _save_png(data.get("circuit_png"), "circuit", metadata=image_metadata)
+        result["histogram_png_path"] = _save_png(data.get("histogram_png"), "histogram", metadata=image_metadata)
+        result["qsphere_png_path"] = _save_png(data.get("qsphere_png"), "qsphere", metadata=image_metadata)
+        result["bloch_png_path"] = _save_png(data.get("bloch_png"), "bloch", metadata=image_metadata)
+    return json.dumps(result, indent=2)

mcp_server/tools/crypto_tools.py

@@ -0,0 +1,66 @@
+"""Tools: quantum cryptography protocols (crypto-q, promoted from
+Dense-Evolution-Discovery issue #189). 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 ..client import _request, catch_errors
+from ..config import COMPUTE
+from ..models import Bb84Input, DiQkdGhzInput, DickaInput
+from ..server import mcp
+
+
+@mcp.tool(name="dense_evolution_crypto_bb84", annotations={"title": "Run BB84 quantum key distribution", **COMPUTE})
+@catch_errors
+async def dense_evolution_crypto_bb84(params: Bb84Input) -> str:
+    """Run real BB84 quantum key distribution: prepare -> channel ->
+    measure -> sift -> QBER. Validated at N=5000 rounds, 5 independent
+    seeds: QBER=0 on a perfect channel, QBER=2*p_channel/3 under isotropic
+    depolarizing noise, QBER=0.25 under an intercept-resend attack
+    (eve=True) -- all within +-1sigma of theory.
+
+    Args:
+        params (Bb84Input): n_rounds, p_channel, eve, seed.
+
+    Returns:
+        str: JSON with n_rounds, p_channel, eve, qber, sifted_key_length.
+    """
+    return json.dumps(await _request("POST", "/api/crypto/bb84", timeout=60.0, json=params.model_dump()), indent=2)
+
+
+@mcp.tool(name="dense_evolution_crypto_di_qkd_ghz", annotations={"title": "Run device-independent QKD via GHZ(3)", **COMPUTE})
+@catch_errors
+async def dense_evolution_crypto_di_qkd_ghz(params: DiQkdGhzInput) -> str:
+    """Run real three-party device-independent conference key agreement
+    via a GHZ(3) state (Ribeiro, Murta & Wehner 2018, arXiv:1708.00798),
+    using the paper's own Parity-CHSH inequality. win_rate reaches the
+    quantum maximum ~0.85355 to machine precision on an ideal channel,
+    comfortably clearing the classical bound of 0.75.
+
+    Args:
+        params (DiQkdGhzInput): n_rounds, p_dep, seed.
+
+    Returns:
+        str: JSON with n_rounds, p_dep, win_rate, expected_win_rate, qber_b1, qber_b2.
+    """
+    return json.dumps(await _request("POST", "/api/crypto/di_qkd_ghz", timeout=60.0, json=params.model_dump()), indent=2)
+
+
+@mcp.tool(name="dense_evolution_crypto_dicka", annotations={"title": "Run the multi-round DICKA protocol", **COMPUTE})
+@catch_errors
+async def dense_evolution_crypto_dicka(params: DickaInput) -> str:
+    """Run the full multi-round DICKA structure (Appendix Protocol 2 of
+    Ribeiro, Murta & Wehner 2018) around the GHZ(3) primitives:
+    round selection, parameter estimation, and the abort decision.
+    Deliberately does not report a secure key length -- Theorem 4's exact
+    value depends on a numerical optimization the source paper never
+    reduces to closed form.
+
+    Args:
+        params (DickaInput): n_rounds, gamma, beta, p_dep, seed.
+
+    Returns:
+        str: JSON with n_rounds, n_test, n_key, p_hat, beta, aborted, qber_b1, qber_b2.
+    """
+    return json.dumps(await _request("POST", "/api/crypto/dicka", timeout=60.0, json=params.model_dump()), indent=2)

mcp_server/tools/mitigation_tools.py

@@ -0,0 +1,81 @@
+"""Tools: error mitigation (ZNE, density-matrix ZNE, vector healing)."""
+import json
+
+from ..client import _request, catch_errors
+from ..config import COMPUTE
+from ..models import MitigateDensityMatrixInput, MitigateZneInput, VectorHealingInput
+from ..server import mcp
+
+
+@mcp.tool(name="dense_evolution_mitigate_zne", annotations={"title": "Zero-Noise Extrapolation on an expectation value", **COMPUTE})
+@catch_errors
+async def dense_evolution_mitigate_zne(params: MitigateZneInput) -> str:
+    """Run real Zero-Noise Extrapolation: measure a Pauli expectation value
+    at several noise scales under a real Kraus noise channel, then
+    extrapolate back to zero noise.
+
+    Args:
+        params (MitigateZneInput): qasm, pauli_string, noise_model, noise_p,
+            seed, extrapolation_method.
+
+    Returns:
+        str: JSON with n_qubits, ideal_expectation, noise_factors,
+        noisy_expectations, zne_extrapolated, extrapolation_method.
+    """
+    return json.dumps(await _request("POST", "/api/mitigate", timeout=120.0, json=params.model_dump()), indent=2)
+
+
+@mcp.tool(name="dense_evolution_mitigate_density_matrix", annotations={"title": "Density-matrix Zero-Noise Extrapolation", **COMPUTE})
+@catch_errors
+async def dense_evolution_mitigate_density_matrix(params: MitigateDensityMatrixInput) -> str:
+    """Run real density-matrix ZNE: Monte-Carlo density-matrix estimate at
+    1x/2x/3x noise_p, extrapolated and projected onto the nearest physical
+    state, graded by Uhlmann fidelity against the true ideal state.
+
+    Args:
+        params (MitigateDensityMatrixInput): qasm, noise_model, noise_p, seed.
+
+    Returns:
+        str: JSON with n_qubits, noise_factors, fidelity_raw, fidelity_corrected.
+    """
+    return json.dumps(await _request("POST", "/api/mitigate_matrix", timeout=120.0, json=params.model_dump()), indent=2)
+
+
+@mcp.tool(name="dense_evolution_mitigate_coherence", annotations={"title": "Coherence-predictive density-matrix ZNE", **COMPUTE})
+@catch_errors
+async def dense_evolution_mitigate_coherence(params: MitigateDensityMatrixInput) -> str:
+    """Run real coherence-L1-predictive density-matrix ZNE: the same
+    Monte-Carlo density-matrix construction as
+    dense_evolution_mitigate_density_matrix, but extrapolated via a signal
+    that covers phase-type noise (phaseflip, dephasing) the classical-JSD
+    signal behind that other tool is structurally blind to -- it only ever
+    reads the density matrix's diagonal. Use this one for phase-type noise
+    models, the JSD one for amplitude/bitflip-type noise.
+
+    Args:
+        params (MitigateDensityMatrixInput): qasm, noise_model, noise_p, seed.
+
+    Returns:
+        str: JSON with n_qubits, noise_factors, fidelity_raw, fidelity_corrected.
+    """
+    return json.dumps(await _request("POST", "/api/mitigate_coherence", timeout=120.0, json=params.model_dump()), indent=2)
+
+
+@mcp.tool(name="dense_evolution_vector_healing", annotations={"title": "Heal a noisy vector sequence", **COMPUTE})
+@catch_errors
+async def dense_evolution_vector_healing(params: VectorHealingInput) -> str:
+    """Run a real predictive-healing pass over a noisy (n_steps, dim)
+    vector sequence -- e.g. VQE convergence telemetry or an MD
+    trajectory. Per step, a Phi-Trigger (dense_evolution.healing) decides
+    whether the change from a local baseline looks like genuine dynamics
+    (kept as-is) or static noise (replaced by the local median). NaN/Inf
+    entries are sanitized first regardless of that decision.
+
+    Args:
+        params (VectorHealingInput): vectors, radius_baseline.
+
+    Returns:
+        str: JSON with healed_vectors, fallback_triggered,
+        adaptive_radius_used, reconstruction_error.
+    """
+    return json.dumps(await _request("POST", "/api/vector_healing", timeout=30.0, json=params.model_dump()), indent=2)

mcp_server/tools/noise_tools.py

@@ -0,0 +1,60 @@
+"""Tools: standalone noise profiles and density-matrix channels."""
+import json
+
+from ..client import _request, catch_errors
+from ..config import COMPUTE
+from ..models import CosmicRayBurstInput, OscillatingNoiseInput, DensityMatrixChannelInput
+from ..server import mcp
+
+
+@mcp.tool(name="dense_evolution_cosmic_ray_burst", annotations={"title": "Cosmic-ray burst noise profile", **COMPUTE})
+@catch_errors
+async def dense_evolution_cosmic_ray_burst(params: CosmicRayBurstInput) -> str:
+    """Real time-dependent decay-probability profile for a cosmic-ray/
+    gamma-ray-induced quasiparticle burst, reproducing a real measured
+    event from arXiv:2104.05219 on a 26-qubit chip: a two-stage rise then
+    a single-exponential recovery.
+
+    Args:
+        params (CosmicRayBurstInput): baseline_gamma, times_us.
+
+    Returns:
+        str: JSON with times_us, baseline_gamma, decay_probabilities, peak_ratio.
+    """
+    return json.dumps(await _request("POST", "/api/cosmic_ray_burst", timeout=30.0, json=params.model_dump()), indent=2)
+
+
+@mcp.tool(name="dense_evolution_oscillating_noise", annotations={"title": "Oscillating noise-scale profile", **COMPUTE})
+@catch_errors
+async def dense_evolution_oscillating_noise(params: OscillatingNoiseInput) -> str:
+    """A noise strength that oscillates instead of scaling smoothly with
+    a ZNE-style scale factor -- for checking whether a mitigation
+    technique that assumes smooth noise-vs-scale still works when that
+    assumption breaks down.
+
+    Args:
+        params (OscillatingNoiseInput): base_p, freq, amp, factors.
+
+    Returns:
+        str: JSON with base_p, freq, amp, factors, p_eff.
+    """
+    return json.dumps(await _request("POST", "/api/oscillating_noise", timeout=30.0, json=params.model_dump()), indent=2)
+
+
+@mcp.tool(name="dense_evolution_density_matrix_channel", annotations={"title": "Apply a density-matrix noise channel", **COMPUTE})
+@catch_errors
+async def dense_evolution_density_matrix_channel(params: DensityMatrixChannelInput) -> str:
+    """Apply a density-matrix-level noise channel to the ideal density
+    matrix of a QASM circuit -- distinct from per-qubit statevector
+    noise (see dense_evolution_run_circuit's noise_model/noise_p):
+    'global_depolarizing' mixes the whole register toward the fully
+    mixed state as one unit (a SPAM-style error), 'amplitude_damping' is
+    single-qubit asymmetric energy relaxation.
+
+    Args:
+        params (DensityMatrixChannelInput): qasm, channel, param.
+
+    Returns:
+        str: JSON with n_qubits, channel, param, ideal_diagonal, noisy_diagonal, trace.
+    """
+    return json.dumps(await _request("POST", "/api/density_matrix_channel", timeout=30.0, json=params.model_dump()), indent=2)

mcp_server/tools/retrieval_tools.py

@@ -0,0 +1,44 @@
+"""Tools: document retrieval (ia_utils.rag, promoted from the quantumrag
+literature-grounding tool). 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 ..client import _request, catch_errors
+from ..config import COMPUTE
+from ..models import RagSearchInput
+from ..server import mcp
+
+
+@mcp.tool(name="dense_evolution_rag_search", annotations={"title": "Search documents with hybrid retrieval", **COMPUTE})
+@catch_errors
+async def dense_evolution_rag_search(params: RagSearchInput) -> str:
+    """Build an ephemeral index over the given documents and search it for
+    `query` in one call -- ground an agent's own answer in a document
+    collection, not a quantum measurement result. Nothing persists
+    server-side: each call builds and searches its own index from
+    scratch, so pass the same `documents` again for a second query rather
+    than expecting a prior index to still exist.
+
+    Two modes: semantic (default) pools TF-IDF and dense-bi-encoder
+    candidates then re-scores with a cross-encoder if rerank=True --
+    catches paraphrases plain TF-IDF misses. exact=True instead does a
+    substring/regex search over raw chunk text (no embedding, no
+    reranker) -- use this when you already know roughly what wording
+    you're looking for and semantic ranking buries it under
+    topically-similar-but-wrong chunks.
+
+    Needs the `rag` extra (pip install dense-evolution[rag]) -- returns an
+    actionable "Error: ..." if it isn't installed.
+
+    Args:
+        params (RagSearchInput): documents ([[text, source], ...]), query,
+            top, rerank, exact, regex, max_hits, context.
+
+    Returns:
+        str: JSON with `results` -- semantic mode: a list of {rank,
+        source, text, score, score_type, cosine}; exact mode: a list of
+        {source, chunk_index, match, snippet, start, end}.
+    """
+    return json.dumps(await _request("POST", "/api/rag_search", timeout=60.0, json=params.model_dump()), indent=2)