Kannaka Quantum

Run Kannaka's memory operations on real quantum hardware. Use for quantum circuits, true quantum random numbers, and resonance recall as amplitude amplificat...

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.

qBraid Lab & compute (v0.2+)

Beyond circuits, the bridge exposes qBraid Lab operations as lab-* CLI subcommands — inspect environments, provision GPU/CPU compute, and launch autonomous coding agents on remote instances over SSH. (These are the surface the Kannaka Rust agent's lab_* tools shell out to.)

Free — inspect (no spend):

subcommand	what it does
lab-credits	qBraid credit balance
lab-list-profiles [--available-only]	compute profiles + per-minute credit cost
lab-compute-status / lab-compute-usage	Lab server status / usage + credit rates
lab-list-instances / lab-list-kernels	on-demand instances / local Jupyter kernels
lab-list-envs / lab-env-info <slug>	qBraid environments / one env's metadata

Free — environment management (in-Lab only): lab-create-env, lab-delete-env, lab-pip-install, lab-pip-freeze, lab-add-kernel, lab-remove-kernel.

PAID — compute (bills per wall-clock minute):

subcommand	what it does
lab-compute-up <profile> / lab-compute-down	start / stop the Lab server on a profile
lab-provision-instance / lab-start-instance / lab-stop-instance	provision / resume / pause an on-demand instance (stop preserves disk)

Autonomous remote agents (over SSH): lab-ssh-configure <instance> → alias; lab-agent-setup (inject API key + onboarding + model so a remote claude/codex runs autonomously); lab-agent-launch / lab-agent-list / lab-agent-read / lab-agent-send. On Windows, ssh-bridge is the websocket↔stdio ProxyCommand shim.

⚠️ Lab spend safety — SEPARATE gate from circuits

Paid compute bills per wall-clock minute until you stop it — a different risk shape from a one-off circuit run, so it has its own opt-in:

• Requires --allow-spend and a --max-credits ceiling, or KANNAKA_LAB_ALLOW_SPEND=1 — distinct from KANNAKA_QUANTUM_ALLOW_SPEND (a circuit-shot opt-in must never silently authorize open-ended compute).
• max_credits is the balance you accept to risk (runway = min(max_credits, balance) / rate), not an automatic cutoff — stop compute explicitly with lab-compute-down / lab-stop-instance.
• Refuses to start if the balance can't cover even one minute of burn.

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.
• The lab tools are CLI-only (the MCP server exposes the four quantum tools); drive them via kannaka-quantum lab-* or the Kannaka agent's lab_* tools.