σpauli

クイックスタート

OpenQASM 3 を入れると、正準 counts が返る。ハッピーパスの全行程。各フィールドはAPIリファレンスに、生の仕様は /openapi.json にあります。

0 · キーの取得

ワークスペースを作成して管理者キーを取得します。以下の各クライアントは環境変数からキーを読み取ります：

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

1 · Qiskit

レジストリの各デバイスが Qiskit の BackendV2 になります：デバイスを選んで実行すれば、counts は Qiskit 本来のキー順で届きます。実行は選んだバックエンドに固定され、黙って他デバイスへフォールバックすることはありません：

install
pip install qiskit-pauli   # Python ≥ 3.10
run_ghz.py
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}

このページの残りは provider.client（各バックエンドの下にある完全な型付きクライアント）で進めます：金額は正確な Decimal（float は例外）、送信ごとに冪等キーを自動付与、例外は下記の安定コードに対応します。

2 · フリートを見積もる（無料）

1回の呼び出しでお客様の回路を全対象デバイスで見積もり、予測キュー・忠実度・理由付きの除外を返します：

estimate.py
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 · ポリシーを指定して送信

cheapest・fastest・highest_fidelity・balanced から選択。デバイスの固定も、プロバイダー・価格・キュー・リージョンによる制約もできます。ジョブはルーティング決定と正確なコストを載せて即座に返ります。送信ごとに冪等キーが付く（指定しなければ自動生成）ため、再試行が二重送信になることはありません：

submit.py
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)

実行前の失敗は次善のデバイスへフォールバックします（allow_fallback=False で無効化）。ホップはすべて記録され、支払いは実際に実行したデバイスの分だけです。

4 · ポーリング、または Webhook で受け取る

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

webhook_url（https のみ）を指定すると、状態遷移ごとに1回 POST され、送信キーの Webhook シークレット（キー作成時に表示）で署名されます。X-Pauli-Event-Id で重複排除してください：

verify_webhook.py
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")

SDK はこのレシピを pauli_sdk.webhooks.unwrap(body, headers, secret=…) として同梱しています。

5 · 結果：ビット順序はひとつ

GET /v1/jobs/{id}/results
{
  "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"}
}

counts の規約：各キーの最左の文字が、最初に宣言されたレジスタの古典ビット0です。レジスタは宣言順に平坦化されます。全プロバイダーがこの形に正規化されるため、解析コードが分岐することはありません。

Insights：ヒストグラム形状の参考分類（キャット状態、一様、周期コム、Porter-Thomas スペックル、…）。平易な見出しとショット数を考慮した確信度付きで、counts のみから導出されます。読み取りの補助であり、採点面ではありません。

6 · お客様自身の認証情報（BYOK）

認証情報を登録すると（/console/credentials または PUT /v1/credentials/{provider}）、そのプロバイダーのジョブはお客様のアカウントで実行されます：プロバイダーが直接請求し、ウォレットはプラットフォーム手数料のみを支払います（料金）。見積もり・ステータス・結果には byok が表示され、フォールバックが課金モードをまたぐことはありません。

7 · エージェント（MCP）

Model Context Protocol は https://pauli.xyz/mcp（Streamable HTTP）、同じ bearer キーで使えます。ツールはこのページの流れをそのまま映します。

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

8 · エージェントからの支払い

残高を超える有償送信は 402 billing.insufficient_credits を返します。その detail は支払いチャレンジで、不足額・入金エンドポイント・入金確認の方法を明示します。入金し（トップアップはホスト型 checkout_url を返すので、人が完了させます）、同じ Idempotency-Key で再送信してください。自動トップアップ（PATCH /v1/billing/settings）なら、ジョブが 402 を見る前に登録済みカードから補充されます。MCP ツールの結果にも同じチャレンジがそのまま載ります。

もう2つの 402、billing.monthly_cap_exceeded と billing.key_cap_exceeded はお客様が設定した上限で、チャレンジは付きません。意図した支出なら上限を引き上げてください。

エラー

すべてのエラーは {"error": {"code", "message", "detail?", "request_id"}} の形で、コードは安定しています。レジストリは /public/errors。サポートには request_id をお知らせください。最初に出会うもの：

コード意味
program.invalidOpenQASM 3 がパースできませんでした。detail に行と列が入ります。
routing.no_feasible_device指定の制約下でこのプログラムを実行できるデバイスがありません。detail にデバイスごとの理由が入ります。
billing.insufficient_credits402：不足分を入金して再送信してください（セクション8）。