Introduction

Qlro answers one question end-to-end: given a quantum workload, which device should you run it on first, and how do you prove the choice was reasonable? The product is shipped as a Python SDK, a CLI, a REST API, and a web app at qlro.io. They share one canonical scoring pipeline (WCPP §5 of the methodology paper), one snapshot of vendor benchmark data, and one decision-record format you can cite from a paper or an RFP.

This page is the full reference. For the 5-minute installer walkthrough, see the quickstart. Methodology and validation live in the Zenodo paper; trust posture lives at /independence and /data-policy.

Quickstart (5 min)

1. Install

pip install qlro

# Optional: vendor extras (Braket / IBM Runtime) pull in their SDKs
pip install "qlro[braket,ibm]"

2. Authenticate

Two ways. Either is fine; both end up storing the same key in a way the SDK will pick up automatically.

# Option A — browser-mediated (recommended)
qlro auth login
# Opens https://qlro.io/cli-auth, you confirm in the browser, the key
# lands in ~/.qlro/credentials with 0600 permissions.

# Option B — env var (CI / Docker friendly)
export QLRO_API_KEY="qlro_..."   # copy from qlro.io/settings

3. Run a recommendation

import qlro

result = qlro.recommend_workload(
    "industry.pharma.drug_similarity_search",
    parameters={"library_size": 50_000},
)
print(result.primary)            # top device
print(result.rankings[0].fit)    # workload-conditioned fit score
print(result.snapshot_commit)    # provenance handle for citations

4. Submit an outcome (closes the loop)

qlro.log_outcome(
    recommendation=result,
    actually_ran_on="ibm_kingston",
    observed_fidelity=0.61,
    note="Ran on real hardware 2026-06-08",
)
# Appears at qlro.io/accuracy (public aggregate) and qlro.io/my-runs
# (your personal feed). Counts toward your 500-call monthly quota.

Core concepts

WCPP — Workload-Conditioned Physical Projection

Devices are scored against four axes — Γ (connectivity), Φ (coherence), F (fidelity), T (throughput) — and combined with a workload-specific weight vector via geometric mean. The weights are derived deterministically from the circuit shape and the workload category; there is no language model in the scoring path.

Snapshots

Every recommendation pins a snapshot_commit hash from the Metriq benchmark dataset. Re-running with the same inputs and the same commit yields the same ranking; switching commits is the only way a result can drift. Snapshots are versioned monthly.

Decision records

A decision record is a content-hashed bundle: the WCPP ranking, the snapshot commit, a bilingual PDF, a BibTeX entry, and a ZIP of the underlying inputs. It is the artefact a procurement officer or external reviewer can cite to defend the choice. Generated from the SDK (qlro.mint_decision_record()) or from any template page on qlro.io.

SDK reference (Python)

All functions are importable from the top-level qlro package. Local-only entry points (recommend, recommend_workload,list_workloads, status, lint) do not need an API key. Cloud-write entry points (log_outcome, mint_decision_record) do.

qlro.recommend(
    circuit: QuantumCircuit | None = None,
    category: str = "chemistry",
    priorities: dict[str, float] | None = None,
    shots: int = 1024,
    devices: list[str] | None = None,
    snapshot: MetriqSnapshot | None = None,
) -> Recommendation

import qlro

result = qlro.recommend(category="chemistry")
print(result.primary, result.rankings[0].fit)

from qiskit import QuantumCircuit
import qlro

qc = QuantumCircuit(4)
qc.h(0); qc.cx(0, 1); qc.cx(1, 2); qc.cx(2, 3); qc.measure_all()

rec = qlro.recommend(circuit=qc, category="ml", shots=4096)
rec.show()

qlro.recommend_workload(
    template_id: str,
    parameters: dict[str, Any] | None = None,
    priorities: dict[str, float] | None = None,
    shots: int = 1024,
    devices: list[str] | None = None,
    snapshot: MetriqSnapshot | None = None,
    category: str | None = None,
) -> Recommendation

import qlro

rec = qlro.recommend_workload(
    "industry.pharma.drug_similarity_search",
    parameters={"library_size": 50_000},
)
print(rec.primary)

# Pin a specific provider channel via the devices filter
rec = qlro.recommend_workload(
    "industry.finance.barrier_option_pricing",
    parameters={"expiry_days": 180},
    devices=["ibm_kingston", "ibm_brisbane", "ibm_fez"],
)

qlro.list_workloads(industry: str | None = None) -> list[dict[str, Any]]
qlro.list_industries() -> list[str]

import qlro

for tpl in qlro.list_workloads(industry="pharma")[:3]:
    print(tpl["template_id"], "-", tpl["display_name"])

qlro.status(
    device: str,
    workload: str | None = None,
    return_path: str = "json",
) -> Status

import qlro

s = qlro.status("ibm_brisbane", workload="chemistry")
if s.severity != "green":
    raise RuntimeError(s.reason)
device.run(circuit, shots=1024)

qlro.lint(
    circuit: QuantumCircuit | str,
    device: str,
    shots: int | None = None,
    region: str | None = None,
    access: list[str] | None = None,
) -> LintReport

import qlro

report = qlro.lint(open("vqe.qasm").read(), device="H2-2", shots=2000)
for f in report.findings:
    print(f"[{f.severity}] {f.rule_id}: {f.message}")
if report.has_reject:
    raise SystemExit(2)

qlro.log_outcome(
    recommendation: Recommendation,
    actual_result: Any = None,
    actually_ran_on: str | None = None,
    observed_fidelity: float | None = None,
    shots: int | None = None,
    calibration_level: int | None = None,
    note: str | None = None,
    submit: bool = True,
    endpoint: str | None = None,
    timeout: float = 10.0,
) -> dict[str, Any]

import qlro

rec = qlro.recommend_workload("industry.pharma.drug_similarity_search")
result = qlro.log_outcome(
    recommendation=rec,
    actually_ran_on="ibm_kingston",
    observed_fidelity=0.61,
    note="Real hardware 2026-06-08",
)
print(result["submitted"], result.get("id"))

CLI reference

Installed as the qlro entry point. Run qlro --help for the full subcommand list, or qlro <subcommand> --help for per-command options.

qlro auth login

$ qlro auth login

$ QLRO_API_BASE=https://staging.qlro.io qlro auth login

qlro recommend <circuit> [--category <cat>] [--all] [--json]

$ qlro recommend vqe.qasm --category chemistry

$ qlro recommend vqe.qasm --category optimization --all

$ cat vqe.qasm | qlro recommend - --json | jq '.rankings[0]'

qlro workload <template_id> [--list] [--param key=value]...

$ qlro workload --list

$ qlro workload industry.pharma.drug_similarity_search --param library_size=50000

$ qlro workload industry.finance.barrier_option_pricing --param expiry=180d --json

qlro status <device> [--workload <cat>]

$ qlro status ibm_brisbane --workload chemistry

$ qlro status H2-2 --workload optimization || echo "skip submit"

qlro lint <circuit> --device <name> [--shots N] [--region R] [--access P,P] [--json] [--color WHEN]

$ qlro lint vqe.qasm --device ibm_brisbane

$ qlro lint vqe.qasm --device H2-2 --shots 2000

$ qlro lint vqe.qasm --device ibm_brisbane --access ibm,aws

$ qlro lint vqe.qasm --device H2-2 --json | jq '.findings[] | select(.severity=="REJECT")'

qlro doctor <device>

$ qlro doctor iqm_garnet

$ qlro doctor ionq_forte

qlro calibrate <device> [--ghz-fidelity F] [--deep-ladder-fidelity F] [--ghz-counts JSON]

$ qlro calibrate iqm_garnet --ghz-fidelity 0.84

$ qlro calibrate iqm_garnet --ghz-counts '{"0000": 412, "1111": 388, ...}'

qlro braket-retro [--days N] [--since ISO] [--until ISO] [--region R]

$ qlro braket-retro --days 30 --region us-east-1

$ qlro braket-retro --since 2026-05-01 --until 2026-06-01

qlro verify <decision-record.pdf>

$ qlro verify qlro-decision-rec_xyz.pdf

Global environment variables

REST API reference

Base URL: https://qlro-production.up.railway.app. Authenticated endpoints expect Authorization: Bearer <api_key>. All responses are JSON. Errors return a detail field with a short reason string and an HTTP status code. See Error reference below.

curl https://qlro-production.up.railway.app/api/v1/workloads?industry=pharma

{
  "industries": ["pharma", "finance", "manufacturing"],
  "templates": [
    {
      "template_id": "industry.pharma.drug_similarity_search",
      "display_name": "Drug similarity / virtual screening",
      "category": "ml",
      "industry": "pharma",
      "description": "Virtual screen N library compounds...",
      "parameters": [
        {"name": "library_size", "type": "int", "default": 10000}
      ]
    }
  ]
}

curl -X POST https://qlro-production.up.railway.app/api/v1/recommend/intake \
  -H 'Authorization: Bearer $QLRO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "template_id": "industry.pharma.drug_similarity_search",
    "accuracy_tier": "standard",
    "response_time": "analysis",
    "data_scale": "typical",
    "total_budget_usd": 1000,
    "audit_level": "internal"
  }'

curl -X POST https://qlro-production.up.railway.app/api/v1/predict/record \
  -H 'Authorization: Bearer $QLRO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "circuit": {"n_qubits": 4, "depth": 8, "n_1q": 6, "n_2q": 3, "n_measured": 4},
    "category": "chemistry",
    "source": {"kind": "circuit"}
  }'

curl -X POST https://qlro-production.up.railway.app/api/v1/feedback \
  -H 'Authorization: Bearer $QLRO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "device": "ibm_kingston",
    "n_qubits": 4, "depth": 8, "n_1q": 6, "n_2q": 3, "n_measured": 4,
    "predicted_fidelity": 0.62, "observed_fidelity": 0.61,
    "shots": 1024, "workload_tag": "chemistry"
  }'

curl -H 'Authorization: Bearer $QLRO_API_KEY' \
  https://qlro-production.up.railway.app/api/v1/me/quota

{"tier":"free","limit":500,"used":17,"resets_at":"2026-07-01T00:00:00Z"}

curl -H 'Authorization: Bearer $QLRO_API_KEY' \
  https://qlro-production.up.railway.app/api/v1/me/accuracy

curl -H 'Authorization: Bearer $QLRO_API_KEY' \
  https://qlro-production.up.railway.app/api/v1/me/runs

Authentication

How the SDK / CLI resolves the key

Resolution order, evaluated at first use:

1. QLRO_API_KEY environment variable
2. ~/.qlro/credentials  (first non-empty line)
3. None — calls run in degraded / anonymous mode where supported

qlro auth login writes the second file with 0600 permissions, so the env var keeps winning whenever it is set (CI and Docker stay deterministic).

Lost your key?

The backend stores only the hash of the original secret;/oauth/sync never re-emits the original key. If your cache is gone (cleared localStorage, new browser, new machine), use the Re-issue API key button on /settings or any gated surface. The old key stops working immediately; tier and quota carry over.

Integrations

Qiskit (native)

from qiskit import QuantumCircuit
import qlro

qc = QuantumCircuit(4)
qc.h(0); qc.cx(0, 1); qc.cx(1, 2); qc.cx(2, 3); qc.measure_all()

rec = qlro.recommend(circuit=qc, category="ml")
print(rec.primary)

AWS Braket (autolog wrapper)

from braket.aws import AwsDevice
import qlro

# Wrap once at import time
qlro.autolog.braket.enable()

device = AwsDevice("arn:aws:braket:...:device/qpu/iqm/Garnet")
task = device.run(circuit, shots=1024)
result = task.result()
# qlro automatically submits the (predicted, observed) pair

Jupyter magic

%load_ext qlro
%%qlro_status ibm_brisbane --workload chemistry
# Renders the live status verdict in the cell, no print() noise.

CI / CD gating

The qlro status and qlro lint subcommands return CI-friendly exit codes. Minimum workflow:

name: Pre-submit gate
on: [pull_request]
jobs:
  qlro-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install qlro
      - env:
          QLRO_API_KEY: ${{ secrets.QLRO_API_KEY }}
        run: |
          qlro lint vqe.qasm --device ibm_brisbane
          qlro status ibm_brisbane --workload chemistry

Decision records

A record bundles the WCPP ranking, the snapshot commit, the input circuit metadata, a bilingual PDF (en + ko), a BibTeX entry, and a ZIP of the inputs. Every record is content-hashed (SHA-256) and Ed25519-signed by qlro.io. Mint from Python:

record = qlro.mint_decision_record(
    recommendation=rec,
    audit_level="regulated",     # internal | procurement | regulated
    domain_label="VQE_4q_chem",
)
print(record["citation_url"])   # https://qlro.io/decision/<id>
print(record["bibtex"])          # paste into your bib file

See /audit-anatomy for a clickable walkthrough of an actual record.

Quota & tiers

Free Community: 500 calls / month per key, shared across the website and the CLI. Calls that hit the snapshot-only SDK code path (qlro.recommend(), qlro.recommend_workload() without outcome submission) do not count.

Tier breakdown lives at /pricing; usage is at /settings. At 80% the settings page surfaces a warning; at 100% writes return 429.

Error reference

HTTP 401  — Missing or invalid API key.
HTTP 402  — Reserved for paid features the current tier cannot use.
HTTP 403  — Authentication ok, but the operation is not allowed for the role.
HTTP 404  — Decision record / template / snapshot id is unknown.
HTTP 409  — Conflict (e.g. CLI session already granted, awaiting CLI fetch).
HTTP 410  — Resource gone (CLI session consumed / expired; old API key revoked).
HTTP 429  — Monthly quota or per-IP rate limit reached.
HTTP 502  — Backend unreachable through the Next.js proxy. Transient.
HTTP 503  — Server misconfigured (missing shared secret). Report this.

Support & contact

Pilot / enterprise enquiries: official@stockfolio.ai. Bug reports and feature requests: GitHub Issues at github.com/linsletoh/qlro. Operational status is reflected on /dashboard and the public accuracy aggregate at /accuracy.