quantinuumclaw

# QuantinuumClaw – Quantum Guppy/Selene Stack

This skill provides everything needed to build production-ready quantum applications using **Quantinuum** (hardware/emulator), **Guppy** (quantum language), **Selene** (FastAPI backend), and **Fly.io** (deployment), with optional **Lovable** frontend. It is tuned for the **OpenClaw Clinical Hackathon** and general quantum web apps.

## When to Use This Skill

**Use when:**
- Building for the OpenClaw Clinical Hackathon or any clinical/healthcare quantum project
- Building web applications that use quantum computing (optimization, chemistry, ML, random, crypto)
- Deploying quantum algorithms as REST APIs or creating dashboards for quantum results
- User mentions: clinical, healthcare, drug discovery, treatment optimization, patient stratification, molecular simulation, clinical trials, Guppy, Selene, Fly.io

**Example requests:** "Build a quantum portfolio optimizer with a web interface" · "Deploy my Guppy algorithm to the cloud" · "Create a clinical molecular simulation demo" · "Set up a quantum ML service on Fly.io"

## Stack at a Glance

| Component   | Role |
|------------|------|
| **Quantinuum** | Quantum hardware (H-series) or emulator |
| **Guppy**      | Quantum programming (circuits, gates, measurement) |
| **Selene**     | FastAPI backend that runs Guppy and exposes REST API |
| **Fly.io**     | Hosts the Selene backend in the cloud |
| **Lovable**    | React/TS frontend template; use `assets/lovable-template/` or any app that calls the Selene API |

## Quick Start (One Command)

From the repo root:

```bash
python3 scripts/create_quantum_app.py \
  --app-name "clinical-demo" \
  --use-case "chemistry" \
  --description "Clinical molecular simulation" \
  --deploy
```

Then set `VITE_API_URL` in the frontend to your Fly.io app URL (e.g. `https://clinical-demo.fly.dev`).

**Clinical use-case → `--use-case` mapping:**

| Clinical idea                     | `--use-case`   | Notes |
|------------------------------...

## QuantinuumClaw – Quantum Guppy/Selene Stack for Clinical Hackathons

**QuantinuumClaw** is a starter kit and Cursor skill bundle for the **OpenClaw Clinical Hackathon**.  
It gives participants a batteries-included way to:

- **Write quantum algorithms** in **Guppy** targeting **Quantinuum** hardware or emulators.
- **Expose them as APIs** using a **Selene** (FastAPI) backend.
- **Deploy the backend** to **Fly.io** with a single command.
- **Connect a Lovable/React frontend** for interactive clinical demos.

The same stack works for any quantum web app, but the docs and examples in this repo are tuned for **clinical and healthcare** projects (drug discovery, treatment optimization, patient stratification, trial randomization, etc.).

> The public GitHub repo backing this project is [`arunnadarasa/quantinuumclaw`](https://github.com/arunnadarasa/quantinuumclaw).

---

## 1. Architecture at a Glance

- **Quantinuum** – Quantum hardware (H-series) or emulator.
- **Guppy** – Quantum programming language with a Pythonic API.
- **Selene** – FastAPI backend service that:
  - Wraps Guppy circuits,
  - Exposes REST endpoints for quantum jobs,
  - Manages jobs, errors, and health checks.
- **Fly.io** – Cloud platform that runs the Selene backend.
- **Lovable (React/TS)** – Frontend UI that calls the Selene API and visualizes quantum results.

```text
Browser (Lovable/React)
        │  HTTPS
        ▼
Selene backend (FastAPI on Fly.io)
        │  Python + Guppy
        ▼
Quantinuum hardware or emulator
```

Key reference docs in this repo:

- `SKILL.md` – Full Quantum Guppy/Selene skill reference.
- `references/guppy_guide.md` – Guppy language & circuit patterns.
- `references/selene_api.md` – API endpoints, job models, errors.
- `references/flyio_config.md` – Fly.io deployment & tuning.
- `references/lovable_patterns.md` – Frontend/React patterns.

For hackathon and clinical use-case details, see the root **SKILL.md** (QuantinuumClaw skill) and `references/clinical-use-cas...