advay-platform 0.2.0__py3-none-any.whl

advay_platform/__init__.py

@@ -0,0 +1,70 @@
+"""Advay Labs Platform — customer-facing circuit ingestion and SQPU projection.
+
+The primary entry point is `run_circuit`. See README for the API contract.
+
+Example:
+    from advay_platform import run_circuit, RunOptions
+    from qiskit import QuantumCircuit
+
+    qc = QuantumCircuit(2, 2)
+    qc.h(0); qc.cx(0, 1); qc.measure([0, 1], [0, 1])
+
+    response = run_circuit(qc, RunOptions(shots=1024))
+    print(response.to_json())
+
+For the digital twin connection:
+    from advay_platform import is_live_mode, twin_info
+    print(is_live_mode())   # True if sqpu_digital_twin is importable
+    print(twin_info())      # full twin connection descriptor
+
+CLI: `advay-platform info` or `advay-platform run <circuit.qasm>`.
+"""
+from .api import run_circuit, get_platform_info, PLATFORM_VERSION
+from .schemas import (
+    RunOptions,
+    Response,
+    CircuitSummary,
+    IdealResult,
+    ResourceProjection,
+    NoiseProjection,
+    Provenance,
+    Bound,
+)
+from .ingestion import CircuitIR, Operation, ingest
+from .twin_bridge import (
+    load_profile,
+    twin_version,
+    twin_info,
+    is_live_mode,
+    force_refresh as refresh_twin_detection,
+)
+
+__version__ = PLATFORM_VERSION
+
+__all__ = [
+    # Public API
+    "run_circuit",
+    "get_platform_info",
+    # Schemas
+    "RunOptions",
+    "Response",
+    "CircuitSummary",
+    "IdealResult",
+    "ResourceProjection",
+    "NoiseProjection",
+    "Provenance",
+    "Bound",
+    # IR
+    "CircuitIR",
+    "Operation",
+    "ingest",
+    # Twin connection
+    "load_profile",
+    "twin_version",
+    "twin_info",
+    "is_live_mode",
+    "refresh_twin_detection",
+    # Meta
+    "PLATFORM_VERSION",
+    "__version__",
+]

advay_platform/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python -m advay_platform`."""
+import sys
+from .cli import main
+
+sys.exit(main())

advay_platform/api.py

@@ -0,0 +1,409 @@
+"""advay_platform.run_circuit — the single internal API entry point.
+
+Customer programs call run_circuit(circuit, options) and get a Response.
+This function:
+  1. Validates options
+  2. Ingests the circuit (Qiskit / OpenQASM / IR → CircuitIR)
+  3. Decides which components to compute (execute / resources / noise)
+  4. Routes to the right simulator if executing — with thread-based timeout
+  5. Builds the resource projection (from algorithm template OR from circuit)
+  6. Builds the noise projection
+  7. Assembles a Response with status reflecting partial/declined components
+
+Statelessness contract: this function performs ZERO disk writes, no
+network calls, and no mutation of module-level state. Every call is
+independent; customer circuits are never persisted by the platform.
+"""
+from __future__ import annotations
+import hashlib
+import json
+import threading
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
+from .schemas.request import RunOptions
+from .schemas.response import (
+    Response, CircuitSummary, Provenance, IdealResult,
+    ResourceProjection, NoiseProjection, EvidenceClass,
+)
+from .ingestion import ingest, CircuitIR
+from .execution.router import execute as run_execution, can_execute
+from .resources.estimator import (
+    estimate_circuit_resources, estimate_algorithm_resources, select_template,
+)
+from .noise.projector import project_noise
+from .twin_bridge import load_profile, twin_version, twin_info, is_live_mode
+
+
+PLATFORM_VERSION = "0.2.0"
+
+
+def _options_hash(opts: RunOptions) -> str:
+    """Stable hash of the options for provenance."""
+    import dataclasses
+    d = dataclasses.asdict(opts)
+    s = json.dumps(d, sort_keys=True, default=str)
+    return hashlib.sha256(s.encode()).hexdigest()[:16]
+
+
+def _circuit_summary(ir: CircuitIR) -> CircuitSummary:
+    gate_counts = ir.gate_counts()
+    return CircuitSummary(
+        num_qubits=ir.num_qubits,
+        num_clbits=ir.num_clbits,
+        depth=ir.depth,
+        total_operations=len(ir.operations),
+        is_clifford=ir.is_clifford,
+        gate_counts=gate_counts,
+        non_clifford_count=ir.non_clifford_count(),
+        two_qubit_count=ir.two_qubit_count(),
+        measurement_count=ir.measurement_count(),
+        has_classical_control=any(op.clbits for op in ir.operations if not op.is_measurement),
+        source_format=ir.source_format,
+    )
+
+
+def _build_provenance(opts: RunOptions, profile: dict, run_id: str) -> Provenance:
+    return Provenance(
+        platform_version=PLATFORM_VERSION,
+        twin_version=twin_version(),
+        twin_profile_version=profile.get("schema_version", "unknown"),
+        timestamp_utc=datetime.now(timezone.utc).isoformat(),
+        run_id=run_id,
+        caller_id=opts.caller_id,
+        options_hash=_options_hash(opts),
+        tags=dict(opts.tags),
+    )
+
+
+def _aggregate_classification(*items) -> EvidenceClass:
+    """Most conservative classification among the *populated* components.
+
+    Order from least to most conservative:
+      measured < stitched_composition < projection < extrapolation < literature_estimate
+
+    `declined` is a component status, not an evidence class — we ignore it
+    if any real classification is present. If everything declined, we
+    return 'declined' for the aggregate.
+    """
+    order = {
+        "measured": 0, "stitched_composition": 1, "projection": 2,
+        "extrapolation": 3, "literature_estimate": 4,
+    }
+    real = [c for c in items if c and c != "declined"]
+    if real:
+        return max(real, key=lambda c: order.get(c, 10))
+    return "declined"
+
+
+class _ExecutionThread(threading.Thread):
+    """Run execution in a daemon thread so we can enforce timeout."""
+    def __init__(self, ir, shots, seed, max_qubits):
+        super().__init__(daemon=True)
+        self.ir = ir
+        self.shots = shots
+        self.seed = seed
+        self.max_qubits = max_qubits
+        self.result: Optional[IdealResult] = None
+        self.error: Optional[BaseException] = None
+
+    def run(self):
+        try:
+            self.result = run_execution(
+                self.ir,
+                shots=self.shots,
+                seed=self.seed,
+                max_qubits_non_clifford=self.max_qubits,
+            )
+        except BaseException as e:  # noqa: BLE001
+            self.error = e
+
+
+def _execute_with_timeout(ir, shots, seed, max_qubits, timeout_seconds):
+    """Run execution; return (result, error, timed_out).
+
+    On timeout the worker thread is left to finish in the background
+    (daemonised; will be torn down with the process) but the caller
+    receives a timely response. This is a 'logical timeout' — the work
+    isn't forcibly killed but the API contract is honored.
+    """
+    worker = _ExecutionThread(ir, shots, seed, max_qubits)
+    worker.start()
+    worker.join(timeout=timeout_seconds)
+    if worker.is_alive():
+        return None, None, True
+    return worker.result, worker.error, False
+
+
+def run_circuit(circuit, options: RunOptions = None, **kwargs) -> Response:
+    """Run a customer circuit against the SQPU platform.
+
+    Args:
+        circuit: One of
+            - qiskit.QuantumCircuit
+            - OpenQASM 3.0 string
+            - advay_platform.CircuitIR
+        options: A RunOptions. If None, defaults are used.
+        **kwargs: Convenience — passed directly to RunOptions if options is None.
+
+    Returns:
+        Response — JSON-serializable structured result.
+
+    The function does not raise on customer-input errors; it returns
+    status='declined' with structured reasons. It only raises on internal
+    bugs.
+
+    Statelessness: this function does not write to disk, mutate any
+    module-level state, or persist the customer circuit anywhere.
+    """
+    # job_id is generated up-front so the caller can correlate even if
+    # the function returns early (declined). In future async mode, this
+    # is the identifier the caller polls with.
+    job_id = uuid.uuid4().hex
+
+    # Build options
+    if options is None:
+        options = RunOptions(**kwargs)
+    elif kwargs:
+        raise ValueError("Pass either `options` OR keyword args, not both")
+
+    err = options.validate()
+    if err:
+        return _early_decline("invalid_options", err, options,
+                                job_id=job_id, circuit_summary=None)
+
+    # Ingest. User input can fail in many ways (parse errors from various
+    # backends, type mismatches, missing dependencies). Catch broadly because
+    # this is a hard boundary between caller-supplied data and our code —
+    # we owe the caller a structured declined response, not a stack trace.
+    try:
+        ir = ingest(circuit)
+    except Exception as e:
+        return _early_decline("ingestion_failed", f"{type(e).__name__}: {e}",
+                                options, job_id=job_id, circuit_summary=None)
+
+    summary = _circuit_summary(ir)
+    notes: list = []
+    declined: list = []
+    classifications: list = []
+
+    # Surface any ingestion-time preprocessor notes (e.g. "Renamed register
+    # 's' → 's_reg' to avoid OpenQASM 3 symbol-table collision") so the
+    # customer can see what we did before parsing their QASM. These come
+    # from advay_platform.ingestion.qasm_adapter.preprocess_qasm3 via
+    # ir.metadata["ingestion_notes"].
+    for n in ir.metadata.get("ingestion_notes", []):
+        notes.append(n)
+
+    # Load profile
+    try:
+        profile = load_profile(options.profile)
+    except (ValueError, FileNotFoundError) as e:
+        return _early_decline("profile_load_failed", str(e), options,
+                                job_id=job_id, circuit_summary=summary)
+
+    # --- Execution ---
+    ideal_result = None
+    if options.execute:
+        ok, reason = can_execute(ir, options.max_simulatable_qubits_non_clifford)
+        if not ok:
+            notes.append(f"Execution declined: {reason}")
+            declined.append({
+                "component": "execution",
+                "code": "circuit_too_large",
+                "message": reason,
+                "suggestion": (
+                    "Increase max_simulatable_qubits_non_clifford (up to 25), "
+                    "decompose into Clifford-only segments, or rely on resource estimation only."
+                ),
+            })
+            classifications.append("declined")
+        else:
+            result, error, timed_out = _execute_with_timeout(
+                ir,
+                shots=options.shots,
+                seed=options.seed,
+                max_qubits=options.max_simulatable_qubits_non_clifford,
+                timeout_seconds=options.timeout_seconds,
+            )
+
+            if timed_out:
+                notes.append(
+                    f"Execution exceeded timeout ({options.timeout_seconds}s). "
+                    "Resource and noise projections may still proceed."
+                )
+                declined.append({
+                    "component": "execution",
+                    "code": "execution_timeout",
+                    "message": f"Did not complete within {options.timeout_seconds}s",
+                    "suggestion": (
+                        "Increase timeout_seconds, reduce shots, or use a smaller circuit. "
+                        "For Clifford-only circuits, stim should be fast — check that "
+                        "is_clifford is True in circuit_summary."
+                    ),
+                })
+                classifications.append("declined")
+            elif error is not None:
+                notes.append(f"Execution failed: {error}")
+                declined.append({
+                    "component": "execution",
+                    "code": "execution_failed",
+                    "message": str(error),
+                    "suggestion": "Check circuit for unsupported gates or memory pressure.",
+                })
+                classifications.append("declined")
+            else:
+                ideal_result = result
+                classifications.append("measured")
+
+    # --- Resource projection ---
+    resource_projection = None
+    if options.resource_estimate:
+        try:
+            if options.algorithm in ("shor", "grover", "qaoa"):
+                algo_est = select_template(options.algorithm, options.algorithm_input_bits)
+                resource_projection = estimate_algorithm_resources(algo_est, options, profile)
+                classifications.append("literature_estimate")
+            else:
+                resource_projection = estimate_circuit_resources(ir, options, profile)
+                classifications.append("projection")
+        except ValueError as e:
+            notes.append(f"Resource estimation failed: {e}")
+            declined.append({
+                "component": "resource_estimate",
+                "code": "estimation_failed",
+                "message": str(e),
+                "suggestion": "Check algorithm_input_bits and algorithm parameters.",
+            })
+            classifications.append("declined")
+
+    # --- Noise projection ---
+    noise_projection = None
+    if options.noise_projection:
+        try:
+            if resource_projection is not None:
+                n_logical = int(resource_projection.logical_qubits.value)
+                d = int(resource_projection.code_distance.value)
+                cycle_s = profile.get("cycle_time_s", 1e-6)
+                total_cycles = max(int(resource_projection.wall_clock_seconds.value / cycle_s), 1)
+                num_logical_ops = n_logical * total_cycles
+            else:
+                n_logical = ir.num_qubits
+                d = 11
+                num_logical_ops = max(n_logical * ir.depth, 1)
+                notes.append(
+                    "Noise projection used default code distance d=11 because "
+                    "resource estimation was not requested."
+                )
+
+            modes_to_project = [options.control_mode]
+            if "full" not in modes_to_project:
+                modes_to_project.insert(0, "full")
+            if options.control_mode == "full":
+                modes_to_project = ["full", "hybrid", "reduced"]
+
+            noise_projection = project_noise(
+                num_logical_qubits=n_logical,
+                num_logical_operations=num_logical_ops,
+                code_distance=d,
+                sqpu_profile=profile,
+                requested_modes=modes_to_project,
+            )
+            classifications.append("projection")
+        except (ValueError, ZeroDivisionError) as e:
+            notes.append(f"Noise projection failed: {e}")
+            declined.append({
+                "component": "noise_projection",
+                "code": "projection_failed",
+                "message": str(e),
+                "suggestion": "Ensure resource_estimate is enabled or supply explicit parameters.",
+            })
+            classifications.append("declined")
+
+    # Decide overall status
+    requested = []
+    if options.execute: requested.append("execution")
+    if options.resource_estimate: requested.append("resources")
+    if options.noise_projection: requested.append("noise")
+    produced = []
+    if ideal_result is not None: produced.append("execution")
+    if resource_projection is not None: produced.append("resources")
+    if noise_projection is not None: produced.append("noise")
+
+    if not produced:
+        status = "declined"
+    elif set(produced) == set(requested):
+        status = "succeeded"
+    else:
+        status = "partial"
+
+    return Response(
+        status=status,
+        job_id=job_id,
+        circuit_summary=summary,
+        ideal_result=ideal_result,
+        resource_projection=resource_projection,
+        noise_projection=noise_projection,
+        evidence_classification=_aggregate_classification(*classifications),
+        notes=notes,
+        declined_reasons=declined,
+        provenance=_build_provenance(options, profile, run_id=job_id),
+    )
+
+
+def _early_decline(code: str, message: str, opts: RunOptions, *,
+                    job_id: str, circuit_summary=None) -> Response:
+    """Build a declined-status Response when we couldn't even start."""
+    try:
+        profile = load_profile(opts.profile)
+        prov_profile = profile
+    except Exception:
+        prov_profile = {"schema_version": "unknown"}
+
+    return Response(
+        status="declined",
+        job_id=job_id,
+        circuit_summary=circuit_summary or CircuitSummary(
+            num_qubits=0, num_clbits=0, depth=0, total_operations=0,
+            is_clifford=False,
+        ),
+        ideal_result=None,
+        resource_projection=None,
+        noise_projection=None,
+        evidence_classification="declined",
+        notes=[f"Request declined before processing: {message}"],
+        declined_reasons=[{
+            "component": "request",
+            "code": code,
+            "message": message,
+            "suggestion": "Review options.validate() and the input circuit.",
+        }],
+        provenance=_build_provenance(opts, prov_profile, run_id=job_id),
+    )
+
+
+def get_platform_info() -> dict:
+    """Return platform metadata (version, twin connection, capabilities).
+
+    Stable, JSON-serializable. Suitable for /info endpoint or CLI `info`
+    sub-command. Surfaces twin live/bundled status so the caller knows
+    which mode is active.
+    """
+    return {
+        "platform_version": PLATFORM_VERSION,
+        "twin": twin_info(),
+        "supported_profiles": ["advay_sqpu_v2_1_4"],
+        "supported_input_formats": [
+            "qiskit.QuantumCircuit", "openqasm3", "advay_platform.CircuitIR",
+        ],
+        "supported_algorithms": ["shor", "grover", "qaoa", "generic"],
+        "max_simulatable_qubits_non_clifford": 25,
+        "max_simulatable_qubits_clifford": 10_000,
+        "supported_control_modes": ["full", "hybrid", "reduced"],
+        "async_supported": False,
+        "auth_required": False,
+        "persistent_storage": False,
+        "rest_api_available": False,
+    }