Quickstart

0 · API-Key anlegen

Erstellen Sie einen Workspace und holen Sie einen Admin-Key; jeder Client unten liest ihn aus der Umgebung:

export PAULI_API_KEY=pauli_sk_…   # shown once at creation; rotate any time

1 · Qiskit

Jedes Gerät der Registry ist ein Qiskit-BackendV2: Gerät wählen, ausführen, Counts in Qiskits eigener Schlüsselordnung lesen. Läufe bleiben an das gewählte Backend gebunden und weichen nie stillschweigend aus:

pip install qiskit-pauli   # Python ≥ 3.10

from qiskit import QuantumCircuit
from qiskit_pauli import PauliProvider

qc = QuantumCircuit(3, 3)                 # GHZ
qc.h(0); qc.cx(0, 1); qc.cx(0, 2)
qc.measure(range(3), range(3))

provider = PauliProvider()                # reads PAULI_API_KEY
backend = provider.least_busy(simulator=True)  # drop simulator=True for hardware
counts = backend.run(qc, shots=1000).result().get_counts()
print(counts)                             # {'000': 489, '111': 511}

Der Rest dieser Seite läuft über provider.client, den vollständigen typisierten Client unter jedem Backend: Geld als exaktes Decimal (ein float wirft), ein Idempotenzschlüssel bei jedem Submit, Exceptions entlang der stabilen Codes unten.

2 · Die Flotte schätzen (kostenlos)

Ein Aufruf bepreist Ihren Schaltkreis auf jedem geeigneten Gerät, mit erwarteter Warteschlange, Fidelity und begründeten Ausschlüssen:

from qiskit import qasm3

client = provider.client                  # the full pauli-sdk client
fleet = client.jobs.estimate(qasm3.dumps(qc), shots=1000)
for e in fleet.estimates:                 # cheapest first
    print(e.device, e.amount, e.predicted_queue_seconds, e.fidelity_score)
for x in fleet.excluded:                  # reasoned exclusions, complete
    print(x.device, x.reasons[0].code)

ionq.simulator 0.000000 1.0 1.0
ionq.qpu.forte-enterprise-1 2.700000 6871.0 0.953

3 · Mit Policy einreichen

Wählen Sie cheapest, fastest, highest_fidelity oder balanced; pinnen Sie ein Gerät, oder beschränken Sie nach Anbieter, Preis, Warteschlange oder Region. Der Job kehrt sofort mit Routing-Entscheidung und exakten Kosten zurück; jeder Submit trägt einen Idempotenzschlüssel (automatisch erzeugt, sofern Sie keinen übergeben), sodass eine Wiederholung nie doppelt einreichen kann:

job = client.jobs.submit(qasm3.dumps(qc), shots=1000,
                         policy="highest_fidelity", only=["ionq"],
                         allow_simulator_fallback=True, max_spend_usd="10.00",
                         idempotency_key="exp-042-run-7",
                         webhook_url="https://example.com/hooks/pauli")
print(job.routing_decision.selected_device, job.cost_estimate.amount)

Fehler vor der Ausführung weichen auf das nächstbeste Gerät aus, außer bei allow_fallback=False; jeder Sprung wird protokolliert, und Sie zahlen nur für das Gerät, das ausgeführt hat.

4 · Abfragen oder den Webhook nehmen

job.wait()   # jittered backoff to a terminal state; timeout=… to bound it
# created → validating → estimating → queued → transpiling → submitted → running → completed

Mit einer webhook_url (nur https) POSTet jeder Zustandsübergang genau einmal, signiert mit dem Webhook-Secret des einreichenden Keys (bei der Key-Erstellung angezeigt); deduplizieren Sie über X-Pauli-Event-Id:

import hashlib, hmac, time

def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
    pairs = [p.split("=", 1) for p in header.split(",")]  # header: X-Pauli-Signature
    t = next(v for k, v in pairs if k == "t")
    if abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, v) for k, v in pairs if k == "v1")

Das SDK liefert dieses Rezept als pauli_sdk.webhooks.unwrap(body, headers, secret=…).

5 · Ergebnisse: eine Bit-Reihenfolge

{
  "counts": {"000": 489, "111": 511},
  "bit_ordering": "cbit0_left",
  "register_map": {"c": ["q[0]", "q[1]", "q[2]"]},
  "metadata": {"provider_job_id": "…", "calibration_snapshot_id": "…"},
  "insights": {"shape": "cat_pair", "confidence": "high", "headline": "GHZ-like cat state: …"},
  "billing": {"billed_usd": "2.470000"}
}

Die Counts-Konvention: das Zeichen ganz links jedes Schlüssels ist das klassische Bit 0 des zuerst deklarierten Registers; Register werden in Deklarationsreihenfolge flachgelegt. Jeder Anbieter wird darauf normalisiert; Analysecode verzweigt nie.

Insights: eine rein hinweisende Klassifikation der Histogrammform (Katzenzustand, uniform, periodischer Kamm, Porter-Thomas-Speckle, …) mit Klartext-Überschrift und Shots-bewusster Konfidenz, allein aus den Counts abgeleitet. Eine Lesehilfe, nie eine Bewertungsfläche.

6 · Eigene Zugangsdaten (BYOK)

Registrieren Sie Zugangsdaten (/console/credentials oder PUT /v1/credentials/{provider}), und Jobs auf diesem Anbieter laufen unter Ihrem Konto: der Anbieter stellt Ihnen direkt in Rechnung; Ihre Wallet zahlt nur die Plattformgebühr (Preise). Schätzungen, Status und Ergebnisse zeigen byok; ein Fallback wechselt nie den Abrechnungsmodus.

7 · Agenten (MCP)

Model Context Protocol unter https://pauli.xyz/mcp (Streamable HTTP), gleicher Bearer-Key. Die Tools spiegeln den Ablauf dieser Seite.

claude mcp add --transport http pauli https://pauli.xyz/mcp \
  --header "Authorization: Bearer $PAULI_API_KEY"

8 · Bezahlen aus dem Agenten

Ein bezahlter Submit über Ihr Guthaben hinaus liefert 402 billing.insufficient_credits; sein detail ist eine Payment-Challenge mit Fehlbetrag, Auflade-Endpoint und dem Weg, die Gutschrift zu bestätigen. Laden Sie auf (Top-ups liefern eine gehostete checkout_url, die ein Mensch abschließt), dann reichen Sie mit demselben Idempotency-Key erneut ein. Auto-Top-up (PATCH /v1/billing/settings) füllt von einer hinterlegten Karte nach, bevor Jobs die 402 je sehen. MCP-Tool-Ergebnisse tragen dieselbe Challenge wörtlich.

Die anderen 402, billing.monthly_cap_exceeded und billing.key_cap_exceeded, sind von Ihnen gesetzte Deckel; sie tragen keine Challenge. Heben Sie den Deckel an, wenn die Ausgabe gewollt ist.

Fehler

Jeder Fehler ist {"error": {"code", "message", "detail?", "request_id"}} mit stabilem Code; das Register ist /public/errors. Nennen Sie dem Support die request_id. Die ersten, denen Sie begegnen: