docs/ARCHITECTURE.md

# QAC-L Cloud-Only Architecture

This document is the **source of truth** for the QAC-L deployment architecture.
The accompanying diagram lives in [`architecture.mmd`](./architecture.mmd)
(render to SVG with `mmdc -i architecture.mmd -o architecture.svg`).

## Why cloud-only

QAC-L was first prototyped locally on a 6 GB RTX 3050. That GPU is too small to
serve the model interactively, and tying the demo to one developer's laptop makes
it impossible to share. The cloud-only design below keeps the local machine as a
**browser only** — everything runs on two free platforms:

- **Hugging Face Spaces (free CPU tier)** — the always-on application layer.
- **Kaggle (T4 / T4×2 GPU, 30 GPU-hours/week)** — the batch compute layer.

> The earlier `diagram.svg` / `diagram (1).svg` in the repo root are the
> **previous hybrid plan** (local GPU as the always-on box) and are superseded
> by this document. They are kept only for history.

## Layer responsibilities

### HF Spaces — always-on application layer (free CPU, 2 vCPU, 16 GB RAM)

| Component            | Role                                                              |
| -------------------- | ---------------------------------------------------------------- |
| Gradio Web UI        | Public URL, natural-language input, receipt + explanation output |
| Qwen2.5-3B GGUF      | English → JSON spec (compile) and results → English (report)     |
| Bouncer verifier     | Deterministic validation: PySCF geometry + SymPy numeric bounds  |
| Lowering pass        | Validated spec → OpenQASM 3                                       |
| Transpile + execute  | `<16 qubit` circuits on CPU via AerSimulator                     |
| Statistics layer     | Expectation values, zero-noise extrapolation (mitiq)             |

This layer handles **every interactive query** end to end. Small molecules
(H₂, LiH) and the five demo actions never need Kaggle.

### Kaggle — batch compute layer (T4/T4×2, 30 GPU-hours/week)

| Component            | Role                                                              |
| -------------------- | ---------------------------------------------------------------- |
| QLoRA fine-tune      | Unsloth + Qwen2.5-3B, ~1–2 hr per run, deploys adapter → Space   |
| Large-circuit routing| SABRE layout/routing for `>16 qubit` circuits                    |
| qiskit-aer-gpu       | Statevector simulation up to ~30 qubits (T4), ~32 (T4×2)         |
| Heavy PySCF          | Hamiltonian generation for larger molecules (NH₃, H₂O, …)        |

Kaggle is invoked **on demand** — the Space triggers a notebook via the Kaggle
API or pulls pre-computed results from a HF Dataset. It is never kept warm.

### Quantum Cloud APIs

- **IBM Quantum** — superconducting (primary hardware path; `qiskit-ibm-runtime`).
- **Quantinuum** — trapped ion (`pytket`-quantinuum).
- **AWS Braket / QuEra** — neutral atom (Braket is the cloud-accessible route).

## Model decision: Qwen2.5-3B-Instruct, 4-bit GGUF

| Model  | Verdict                                                        |
| ------ | -------------------------------------------------------------- |
| 1.5B   | Fast on CPU but too weak for reliable JSON spec with chemistry |
| **3B** | **Chosen.** ~2 GB RAM, 5–15 s/response on 2 vCPU. Sweet spot.  |
| 7B     | The existing adapter proves the approach, but 7B won't serve on 2 vCPU (30–60 s/response, OOM risk) |

The existing 7B adapter (`qwen-quantum-adapter/`) is **base-model-specific and
cannot be reused**. Task 2 re-fine-tunes 3B on the existing dataset (which is
model-agnostic — it only defines `messages`, not the base model).

Inference uses **`llama-cpp-python`** (not `transformers` + `bitsandbytes`) to
avoid bitsandbytes CPU-compatibility issues on HF Spaces.

## What does *not* live here

| Removed              | Reason                                                         |
| -------------------- | -------------------------------------------------------------- |
| Local RTX 3050 box   | Replaced by HF Spaces free CPU as the always-on layer          |
| bitsandbytes / 4-bit-on-GPU | CPU-only serving uses GGUF via llama-cpp-python        |
| Direct QuEra SDK     | AWS Braket is the cloud-accessible neutral-atom route instead  |
| The 7B serving path  | 3B GGUF is the served model; 7B is fine-tune-only on Kaggle    |

## Phase status

| Phase | Component                                      | Status        |
| ----- | ---------------------------------------------- | ------------- |
| 1     | HF Space scaffold, Gradio UI, Bouncer (×5)     | ✅ This commit |
| 1     | Lowering + transpile + Aer + statistics        | ✅ This commit |
| 1     | Deterministic demo pipeline (no LLM wired)     | ✅ This commit |
| 1     | Lazy GGUF loader module                        | ✅ This commit (wired in Task 2) |
| 2     | QLoRA re-fine-tune of 3B on Kaggle             | Pending (Task 2) |
| 2     | Wire 3B adapter into the Space LLM slot        | Pending (Task 2) |
| 3     | Kaggle large-circuit / aer-gpu / heavy PySCF   | Pending       |
| 3     | IBM Quantum + Quantinuum + Braket adapters     | Pending       |