quantufai 0.1.0__tar.gz

quantufai-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: quantufai
+Version: 0.1.0
+Summary: QuantufAI developer SDK: quote quantum runs before any spend, read job status/results/receipts, export circuits, and simulate on the free sandbox — this SDK can price and read, it can never spend.
+Author: QuantufAI, Inc.
+License: Proprietary
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: verify
+Requires-Dist: cryptography>=41; extra == "verify"
+
+# quantufai — the QuantufAI Python SDK
+
+Quantum compute a program can **price and read — never spend**.
+
+> ⚠️ **Publish gate:** this package is repo-code only. It is **not** on PyPI
+> and must not be published or linked from public docs until the founder
+> confirms counsel's provisional filing. Local installs are fine:
+> `pip install -e sdks/python`.
+
+## What this SDK can do
+
+| You want | Call | Key scope |
+|---|---|---|
+| "What would this run cost?" | `client.quote(circuit, shots=...)` | `quotes:read` |
+| "Is it done yet?" | `client.job_status(job_id)` / `client.wait(job_id)` | `jobs:read` |
+| Counts + ledger + error bars, verbatim | `client.job_result(job_id)` | `jobs:read` |
+| The signed, tamper-evident receipt | `client.governed_receipt(job_id)` | `jobs:read` |
+| Check a receipt you hold | `client.verify_receipt(receipt)` | `jobs:read` (platform tier) / none (offline tier) |
+| The exact circuit that ran, as Qiskit/Cirq/Braket/pytket/QASM | `client.export_circuit(job_id, format=..., which=...)` | `results:export` |
+| Download the result artifact | `client.export_result(job_id)` | `results:export` |
+| Run on the **free local simulator** ($0) | `client.sandbox_simulate(circuit)` | `runs:simulate` (sandbox key) |
+| What can this key do? | `client.me()` | `account:read` |
+
+## What this SDK cannot do — by design, not omission
+
+**There is no dispatch method. There is no approval method. There is no
+billing method.** Spending money on quantum hardware requires a human
+approving a signed quote in the QuantufAI dashboard:
+
+- The platform enforces quote-before-spend server-side; scoped API keys
+  cannot approve a spend.
+- On top of that, this SDK's one execution method (`sandbox_simulate`) pins
+  every request to the free local simulator (`preferredProviders:
+  ["classical"]`), so **even a key carrying the paid `runs:execute` scope
+  cannot reach billable hardware through this SDK**. Zero eligible providers
+  is a typed failure on the platform — never a silent reroute.
+
+An AI agent driving this client can tell you exactly what an experiment would
+cost and read every receipt — and cannot buy anything.
+
+## REFUSED is a status, not an exception
+
+Every deliberate platform refusal — missing scope, sandbox clamp, someone
+else's job, quota exhausted, unprovable circuit translation — comes back as a
+typed `Refusal` with the platform's `code`, `message`, and `details`
+verbatim:
+
+```python
+result = client.job_result("not-my-job")
+if isinstance(result, quantufai.Refusal):
+    print(result.status)   # "REFUSED"
+    print(result.code)     # e.g. "job_not_found", "insufficient_scope"
+    print(result.details)  # e.g. {"requiredScope": "jobs:read", ...}
+```
+
+Exceptions are reserved for transport failures (`TransportError`) and
+unexpected 5xx answers (`PlatformError`, body preserved).
+
+## Quickstart (sandbox — no card, $0)
+
+```python
+import quantufai
+
+client = quantufai.Client(
+    api_key="qfai_sk_...",        # or $QUANTUFAI_API_KEY; sandbox tier: mint
+                                  # with {"tier": "sandbox"} in the dashboard
+    base_url="https://YOUR_HOST", # or $QUANTUFAI_BASE_URL
+)
+
+bell = """OPENQASM 2.0;
+include "qelib1.inc";
+qreg q[2]; creg c[2];
+h q[0]; cx q[0], q[1];
+measure q -> c;"""
+
+# 1. Price it first — nothing is reserved, charged, or dispatched by quoting.
+quotes = client.quote(bell, shots=1000, qubits=2)
+if isinstance(quotes, quantufai.Refusal):
+    raise SystemExit(f"refused: {quotes.code} — {quotes.message}")
+for q in quotes.quotes:
+    print(f"{q.provider}: ~${q.estimated_cost_usd} ({q.reasons})")
+
+# 2. Run on the FREE local simulator (the only execution this SDK performs).
+run = client.sandbox_simulate(bell, shots=1000, qubits=2)
+if isinstance(run, quantufai.Refusal):
+    raise SystemExit(f"refused: {run.code} — {run.message}")
+print(run.state, run.counts)   # real statevector physics, real counts, $0
+
+# 3. Poll (async runs), then fetch the signed receipt.
+result = client.wait(run.job_id)
+receipt = client.governed_receipt(run.job_id)
+
+# 4. Verify the receipt — offline Ed25519 tier and/or the platform's check.
+report = client.verify_receipt(receipt)
+print(report.verified, report.offline.public_signature)
+
+# 5. Take the exact circuit home. `which` is required — the platform refuses
+#    to guess between "original" and "as-dispatched".
+code = client.export_circuit(run.job_id, format="qiskit", which="as-dispatched")
+print(code.source)
+```
+
+## Receipts: what the tiers mean
+
+- **Publicly-verifiable tier** (`publicSignature`, Ed25519): anyone can
+  verify offline with QuantufAI's published public key —
+  `verify_receipt(receipt, public_key=..., offline_only=True)` or the
+  standalone `tools/verify-receipt.mjs`. Needs the optional extra:
+  `pip install 'quantufai[verify]'`.
+- **Server-attested tier** (`signature`, HMAC): the platform's own
+  attestation; only the platform can check it (that's what the platform tier
+  of `verify_receipt` asks for). Older receipts carry only this tier — the
+  SDK reports that honestly instead of pretending to a verdict.
+
+## Results are verbatim
+
+Counts are never re-binned, error bars are never computed client-side —
+`JobResult.error_bars` returns exactly the uncertainty fields the platform
+attached (with their location in the payload), and returns nothing when the
+platform attached none.
+
+## History: this package replaces deleted fabricating stubs
+
+The repo previously carried `sdks/python/quantufai.py` and
+`sdks/js/quantufai.ts` — stubs that called endpoints that never existed and
+**invented job statuses by pattern-matching chat text**. They were deleted
+(PR #579) and a CI test keeps them deleted. This package is their honest
+replacement: every call maps to a real, mounted, scope-gated endpoint, and
+anything the platform refuses surfaces as a typed `REFUSED`.
+
+## Publish checklist (post-filing — founder go required)
+
+1. Founder confirms counsel's provisional filing covers the receipt/verifier
+   disclosures (roadmap #4 gate).
+2. `python -m build` from `sdks/python/`; check the wheel installs clean.
+3. Reserve/publish `quantufai` on PyPI from the org account (never a personal
+   one); enable 2FA + trusted publishing.
+4. Only then link the SDK from `/docs` (the docs deliberately do not mention
+   it today).
+5. Announcement claim (exact words matter): "quantum compute an AI agent can
+   spend safely — quote-before-spend enforced, auditable receipts." **Never
+   claim "first MCP"** (IBM's Qiskit MCP servers and Conductor's CODA exist);
+   "first *governed* one" is the true, stronger claim.

quantufai-0.1.0/README.md

@@ -0,0 +1,143 @@
+# quantufai — the QuantufAI Python SDK
+
+Quantum compute a program can **price and read — never spend**.
+
+> ⚠️ **Publish gate:** this package is repo-code only. It is **not** on PyPI
+> and must not be published or linked from public docs until the founder
+> confirms counsel's provisional filing. Local installs are fine:
+> `pip install -e sdks/python`.
+
+## What this SDK can do
+
+| You want | Call | Key scope |
+|---|---|---|
+| "What would this run cost?" | `client.quote(circuit, shots=...)` | `quotes:read` |
+| "Is it done yet?" | `client.job_status(job_id)` / `client.wait(job_id)` | `jobs:read` |
+| Counts + ledger + error bars, verbatim | `client.job_result(job_id)` | `jobs:read` |
+| The signed, tamper-evident receipt | `client.governed_receipt(job_id)` | `jobs:read` |
+| Check a receipt you hold | `client.verify_receipt(receipt)` | `jobs:read` (platform tier) / none (offline tier) |
+| The exact circuit that ran, as Qiskit/Cirq/Braket/pytket/QASM | `client.export_circuit(job_id, format=..., which=...)` | `results:export` |
+| Download the result artifact | `client.export_result(job_id)` | `results:export` |
+| Run on the **free local simulator** ($0) | `client.sandbox_simulate(circuit)` | `runs:simulate` (sandbox key) |
+| What can this key do? | `client.me()` | `account:read` |
+
+## What this SDK cannot do — by design, not omission
+
+**There is no dispatch method. There is no approval method. There is no
+billing method.** Spending money on quantum hardware requires a human
+approving a signed quote in the QuantufAI dashboard:
+
+- The platform enforces quote-before-spend server-side; scoped API keys
+  cannot approve a spend.
+- On top of that, this SDK's one execution method (`sandbox_simulate`) pins
+  every request to the free local simulator (`preferredProviders:
+  ["classical"]`), so **even a key carrying the paid `runs:execute` scope
+  cannot reach billable hardware through this SDK**. Zero eligible providers
+  is a typed failure on the platform — never a silent reroute.
+
+An AI agent driving this client can tell you exactly what an experiment would
+cost and read every receipt — and cannot buy anything.
+
+## REFUSED is a status, not an exception
+
+Every deliberate platform refusal — missing scope, sandbox clamp, someone
+else's job, quota exhausted, unprovable circuit translation — comes back as a
+typed `Refusal` with the platform's `code`, `message`, and `details`
+verbatim:
+
+```python
+result = client.job_result("not-my-job")
+if isinstance(result, quantufai.Refusal):
+    print(result.status)   # "REFUSED"
+    print(result.code)     # e.g. "job_not_found", "insufficient_scope"
+    print(result.details)  # e.g. {"requiredScope": "jobs:read", ...}
+```
+
+Exceptions are reserved for transport failures (`TransportError`) and
+unexpected 5xx answers (`PlatformError`, body preserved).
+
+## Quickstart (sandbox — no card, $0)
+
+```python
+import quantufai
+
+client = quantufai.Client(
+    api_key="qfai_sk_...",        # or $QUANTUFAI_API_KEY; sandbox tier: mint
+                                  # with {"tier": "sandbox"} in the dashboard
+    base_url="https://YOUR_HOST", # or $QUANTUFAI_BASE_URL
+)
+
+bell = """OPENQASM 2.0;
+include "qelib1.inc";
+qreg q[2]; creg c[2];
+h q[0]; cx q[0], q[1];
+measure q -> c;"""
+
+# 1. Price it first — nothing is reserved, charged, or dispatched by quoting.
+quotes = client.quote(bell, shots=1000, qubits=2)
+if isinstance(quotes, quantufai.Refusal):
+    raise SystemExit(f"refused: {quotes.code} — {quotes.message}")
+for q in quotes.quotes:
+    print(f"{q.provider}: ~${q.estimated_cost_usd} ({q.reasons})")
+
+# 2. Run on the FREE local simulator (the only execution this SDK performs).
+run = client.sandbox_simulate(bell, shots=1000, qubits=2)
+if isinstance(run, quantufai.Refusal):
+    raise SystemExit(f"refused: {run.code} — {run.message}")
+print(run.state, run.counts)   # real statevector physics, real counts, $0
+
+# 3. Poll (async runs), then fetch the signed receipt.
+result = client.wait(run.job_id)
+receipt = client.governed_receipt(run.job_id)
+
+# 4. Verify the receipt — offline Ed25519 tier and/or the platform's check.
+report = client.verify_receipt(receipt)
+print(report.verified, report.offline.public_signature)
+
+# 5. Take the exact circuit home. `which` is required — the platform refuses
+#    to guess between "original" and "as-dispatched".
+code = client.export_circuit(run.job_id, format="qiskit", which="as-dispatched")
+print(code.source)
+```
+
+## Receipts: what the tiers mean
+
+- **Publicly-verifiable tier** (`publicSignature`, Ed25519): anyone can
+  verify offline with QuantufAI's published public key —
+  `verify_receipt(receipt, public_key=..., offline_only=True)` or the
+  standalone `tools/verify-receipt.mjs`. Needs the optional extra:
+  `pip install 'quantufai[verify]'`.
+- **Server-attested tier** (`signature`, HMAC): the platform's own
+  attestation; only the platform can check it (that's what the platform tier
+  of `verify_receipt` asks for). Older receipts carry only this tier — the
+  SDK reports that honestly instead of pretending to a verdict.
+
+## Results are verbatim
+
+Counts are never re-binned, error bars are never computed client-side —
+`JobResult.error_bars` returns exactly the uncertainty fields the platform
+attached (with their location in the payload), and returns nothing when the
+platform attached none.
+
+## History: this package replaces deleted fabricating stubs
+
+The repo previously carried `sdks/python/quantufai.py` and
+`sdks/js/quantufai.ts` — stubs that called endpoints that never existed and
+**invented job statuses by pattern-matching chat text**. They were deleted
+(PR #579) and a CI test keeps them deleted. This package is their honest
+replacement: every call maps to a real, mounted, scope-gated endpoint, and
+anything the platform refuses surfaces as a typed `REFUSED`.
+
+## Publish checklist (post-filing — founder go required)
+
+1. Founder confirms counsel's provisional filing covers the receipt/verifier
+   disclosures (roadmap #4 gate).
+2. `python -m build` from `sdks/python/`; check the wheel installs clean.
+3. Reserve/publish `quantufai` on PyPI from the org account (never a personal
+   one); enable 2FA + trusted publishing.
+4. Only then link the SDK from `/docs` (the docs deliberately do not mention
+   it today).
+5. Announcement claim (exact words matter): "quantum compute an AI agent can
+   spend safely — quote-before-spend enforced, auditable receipts." **Never
+   claim "first MCP"** (IBM's Qiskit MCP servers and Conductor's CODA exist);
+   "first *governed* one" is the true, stronger claim.

quantufai-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+##############################################################################
+# quantufai — the official QuantufAI Python SDK
+#
+# ⚠️  PUBLISH GATE (founder/counsel — DO NOT REMOVE): this package is
+# repo-code ONLY. Do NOT publish to PyPI and do NOT link it from public docs
+# until the founder confirms counsel's provisional filing (the same exposure
+# gate as the publicly-verifiable-receipts surface, advancement roadmap #4).
+# Building/installing locally (`pip install -e sdks/python`) is fine.
+##############################################################################
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quantufai"
+version = "0.1.0"
+description = "QuantufAI developer SDK: quote quantum runs before any spend, read job status/results/receipts, export circuits, and simulate on the free sandbox — this SDK can price and read, it can never spend."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "QuantufAI, Inc." }]
+# ZERO runtime dependencies by design: the client is stdlib urllib. The one
+# optional extra is offline receipt verification (Ed25519 needs `cryptography`).
+dependencies = []
+
+[project.optional-dependencies]
+verify = ["cryptography>=41"]
+
+[tool.setuptools]
+packages = ["quantufai"]

quantufai-0.1.0/quantufai/__init__.py

@@ -0,0 +1,68 @@
+"""quantufai — the official QuantufAI Python SDK.
+
+Quantum compute a program can PRICE and READ, but never SPEND: quotes before
+any spend, job status/results with receipts and error bars verbatim, signed
+receipt verification, circuit export, and a free sandbox simulator. There is
+no dispatch or approval method — spending stays with a human in the dashboard
+(see ``quantufai.client`` for the full contract).
+
+This package intentionally replaces the repo's former SDK stubs, which called
+endpoints that did not exist and fabricated job statuses from pattern-matched
+text. Everything here calls the real, mounted, scope-gated API — and what the
+API refuses, this SDK reports as a typed ``REFUSED``, never a made-up answer.
+"""
+from ._version import __version__
+from .client import FREE_SIMULATOR_PROVIDER, Client, ReceiptVerification
+from .types import (
+    FAILED,
+    QUEUED,
+    REFUSED,
+    RUNNING,
+    SUCCEEDED,
+    CircuitExport,
+    GovernedReceipt,
+    JobResult,
+    JobStatus,
+    Me,
+    PlatformError,
+    Quote,
+    QuoteResponse,
+    ReceiptBundle,
+    Refusal,
+    ResultExport,
+    SandboxRun,
+    TransportError,
+    is_terminal,
+    normalize_state,
+)
+from .verify import ChainCheck, OfflineVerification, verify_receipt_offline
+
+__all__ = [
+    "__version__",
+    "Client",
+    "FREE_SIMULATOR_PROVIDER",
+    "ReceiptVerification",
+    "Refusal",
+    "REFUSED",
+    "QUEUED",
+    "RUNNING",
+    "SUCCEEDED",
+    "FAILED",
+    "Quote",
+    "QuoteResponse",
+    "JobStatus",
+    "JobResult",
+    "ReceiptBundle",
+    "GovernedReceipt",
+    "CircuitExport",
+    "ResultExport",
+    "SandboxRun",
+    "Me",
+    "TransportError",
+    "PlatformError",
+    "normalize_state",
+    "is_terminal",
+    "OfflineVerification",
+    "ChainCheck",
+    "verify_receipt_offline",
+]

quantufai-0.1.0/quantufai/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

quantufai-0.1.0/quantufai/canonical.py

@@ -0,0 +1,100 @@
+"""Canonical JSON — a byte-exact Python port of the platform's stableStringify.
+
+Receipt signatures cover ``stableStringify(receipt minus signature fields)``:
+deterministic JSON with lexicographically sorted object keys, serialized the
+way JavaScript's ``JSON.stringify`` serializes scalars. Verification in Python
+therefore needs the SAME bytes — including JavaScript's number formatting
+(``1e21`` -> ``"1e+21"``, ``1e-7`` -> ``"1e-7"``, ``1.0`` -> ``"1"``), which
+differs from Python's ``json.dumps`` in the corners.
+
+Parity is pinned by shared test vectors (tests/fixtures/canonical_vectors.json)
+asserted against both this module and the Node implementation.
+"""
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+
+def _js_number(value: float) -> str:
+    """Format a float exactly as ECMAScript Number::toString(10) would.
+
+    JSON.stringify emits non-finite numbers as ``null``; integral values
+    without a fractional part; exponential notation only for |exponent|
+    outside [-6, 21); exponents unpadded with an explicit sign.
+    """
+    if math.isnan(value) or math.isinf(value):
+        return "null"  # JSON.stringify(NaN) === "null"
+    if value == 0:
+        return "0"
+    # Shortest round-trip decimal digits (repr is shortest in Python >= 3.1,
+    # same guarantee V8 uses).
+    rep = repr(abs(value))
+    if "e" in rep or "E" in rep:
+        mantissa, _, exp_part = rep.lower().partition("e")
+        exp10 = int(exp_part)
+    else:
+        mantissa, exp10 = rep, 0
+    int_part, _, frac_part = mantissa.partition(".")
+    digits = (int_part + frac_part).lstrip("0")
+    # Decimal point position: value = 0.<digits> * 10**point
+    point = len(int_part.lstrip("0")) + exp10 if int_part.strip("0") else (
+        exp10 - (len(frac_part) - len(frac_part.lstrip("0")))
+    )
+    digits = digits.rstrip("0") or "0"
+    sign = "-" if value < 0 else ""
+
+    k = len(digits)
+    if k <= point <= 21:  # integral, printed in full
+        return sign + digits + "0" * (point - k)
+    if 0 < point <= 21:  # decimal point inside the digits
+        return sign + digits[:point] + "." + digits[point:]
+    if -6 < point <= 0:  # small: leading zeros after "0."
+        return sign + "0." + "0" * (-point) + digits
+    # Exponential: d[.ddd]e±e  (exponent = point - 1, unpadded, signed)
+    exponent = point - 1
+    exp_str = ("+" if exponent >= 0 else "-") + str(abs(exponent))
+    if k == 1:
+        return sign + digits + "e" + exp_str
+    return sign + digits[0] + "." + digits[1:] + "e" + exp_str
+
+
+def stable_stringify(value: Any) -> str:
+    """Deterministic JSON with sorted object keys — parity with the platform."""
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, str):
+        # ensure_ascii=False matches JSON.stringify (raw UTF-8, control chars
+        # escaped); Python and JS agree on the mandatory escape set.
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        # JS has one number type: 1.0 serializes as "1" (handled in _js_number).
+        return _js_number(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(stable_stringify(v) for v in value) + "]"
+    if isinstance(value, dict):
+        # JavaScript's Array.prototype.sort() compares strings by UTF-16 code
+        # units; utf-16-be byte order reproduces that exactly (receipt keys are
+        # ASCII in practice, but parity should not depend on practice).
+        items = sorted(
+            ((str(k), v) for k, v in value.items()),
+            key=lambda kv: kv[0].encode("utf-16-be"),
+        )
+        return "{" + ",".join(
+            json.dumps(k, ensure_ascii=False) + ":" + stable_stringify(v) for k, v in items
+        ) + "}"
+    raise TypeError(f"stable_stringify: unsupported type {type(value).__name__}")
+
+
+def unsigned_canonical(receipt: dict) -> str:
+    """The exact bytes both platform signatures cover: the receipt minus its
+    ``signature`` and ``publicSignature`` fields."""
+    clone = {k: v for k, v in receipt.items() if k not in ("signature", "publicSignature")}
+    return stable_stringify(clone)