Kannaka Quantum

Run Kannaka's memory operations on real quantum hardware. Use for quantum circuits, true quantum random numbers, and resonance recall as amplitude amplification — on qBraid's free simulator (default, $0) or real QPUs (IonQ/Rigetti/IQM/AQT via qBraid or OpenQuantum, spends credits). Invoke when asked to run a quantum circuit, draw quantum entropy, list QPUs, or execute Kannaka recall on a quantum backend.

Kannaka's memory is a Holographic Resonance Medium — recall is wave interference, and "attention acts as gravity: wavefronts whose phase/amplitude align with the query are pulled forward." That is, almost verbatim, quantum amplitude amplification. This skill makes the correspondence literal: it runs Kannaka's recall, plus general circuits and a true-entropy source, on actual quantum backends.

Two surfaces — same core

You can drive the bridge either way; prefer whichever is wired in this session.

1. MCP tools (if the kannaka-quantum MCP server is connected): quantum_devices, run_circuit, quantum_random, resonance_recall. Call them directly.
2. JSON CLI — shell out to the kannaka-quantum command. Every subcommand prints one JSON object to stdout (errors included), so parse it directly.

If neither is available, install the package: pip install kannaka-quantum (or pip install -e . from the repo). Python ≥ 3.10. If a spawned process can't find Python, set KANNAKA_QUANTUM_PYTHON to the interpreter path.

⚠️ Spend safety — read first

• The default device is the free qBraid simulator qbraid:qbraid:sim:qir-sv (30 qubits, no credits). Casual/agent use never spends money.
• A real QPU runs only when you opt in explicitly: pass a hardware device= AND allow_spend=true (CLI: --allow-spend). A max_credits ceiling guards every paid run (default ≈ $2).
• Never run on a per-minute-billed device. The native rigetti:rigetti:qpu:cepheus-1-108q on qBraid bills $120/min — the bridge refuses per-minute devices outright. For a cheap real gate QPU use aws:rigetti:qpu:cepheus-1-108q (~$0.41 for 256 shots) or an OpenQuantum backend like openquantum:iqm:garnet.
• On paid QPUs keep shots low — resonance_recall defaults to 1024 shots.

Tools

tool / subcommand	what it does
quantum_devices / devices [--online]	List QPUs + simulators across providers (status, qubits, cost). Discover before running.
run_circuit / run	Execute an OpenQASM 3 program (include "stdgates.inc"; declare qubit[]/bit[], apply gates, measure). Returns measurement counts. CLI reads QASM from --qasm, --qasm-file, or stdin.
quantum_random / qrng	True quantum random bits from measurement collapse (not a PRNG) — entropy for the medium's irrationality (Ξ) and dream noise. Returns bitstring, integer, and a float in [0,1).
resonance_recall / recall	The showcase. Amplitude-encode candidate memory resonances into a quantum state and amplitude-amplify toward the strongest — Kannaka's recall, run as interference on a quantum computer. Returns the measured distribution plus quantum vs classical top pick.

CLI examples

bash

kannaka-quantum devices --online
kannaka-quantum run --qasm-file bell.qasm --shots 200
kannaka-quantum qrng --bits 16
kannaka-quantum recall --amplitudes 0.1,0.9,0.2,0.15 --labels alpha,beta,gamma,delta

Resonance recall output:

json

{"distribution": {"alpha": 2, "beta": 775, "gamma": 240, "delta": 7},
 "quantum_top": "beta", "classical_top": "beta", "agree": true,
 "qubits": 2, "candidates": 4, "amplified": true,
 "device": "qbraid:qbraid:sim:qir-sv"}

Amplitude amplification sharpens the prepared resonance state toward the strongest memory; on the free simulator the quantum pick agrees with the classical argmax.

Real-hardware run (deliberate, spends credits)

bash

kannaka-quantum recall --amplitudes 0.1,0.9,0.2,0.15 --labels a,b,c,d \
  --device aws:rigetti:qpu:cepheus-1-108q --shots 256 --allow-spend --max-credits 50

Authentication: qBraid resolves a key from QBRAID_API_KEY, ~/.qbraid/qbraidrc, or ~/Downloads/QBraid.txt. OpenQuantum (real QPUs, no free simulator) uses OAuth client-credentials at ~/.openquantum/sdk-key.json or OPENQUANTUM_CLIENT_ID/OPENQUANTUM_SECRET.

Notes

• Bitstrings from qBraid are big-endian; the bridge reverses them for qiskit's little-endian indexing internally — you get labeled results, not raw bits.
• All errors surface as a JSON object ({"error": ..., "type": ...}) so you can branch on failures without scraping text.