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 (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