catalyst-q 0.1.0__py3-none-any.whl

catalyst_hmk/__init__.py

@@ -0,0 +1,18 @@
+from .client import CatalystClient, CatalystQClient, PreparedRequest, execute_prepared_request
+from .cloudflare import CloudflareDeploymentSpec, RenderedDeployment
+from .hmk import HypervectorMemoryKey
+from .identity import InstallIdentity
+from .licensing import FreemiumLimitError, UsagePolicy
+
+__all__ = [
+    "CatalystClient",
+    "CatalystQClient",
+    "CloudflareDeploymentSpec",
+    "FreemiumLimitError",
+    "HypervectorMemoryKey",
+    "InstallIdentity",
+    "PreparedRequest",
+    "RenderedDeployment",
+    "UsagePolicy",
+    "execute_prepared_request",
+]

catalyst_hmk/client.py

@@ -0,0 +1,440 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+from urllib import error, request
+
+from .hmk import HypervectorMemoryKey
+from .identity import InstallIdentity
+from .licensing import UsagePolicy
+
+
+@dataclass(frozen=True)
+class PreparedRequest:
+    method: str
+    url: str
+    headers: Dict[str, str]
+    json: Dict[str, Any]
+
+
+Transport = Callable[[PreparedRequest, float], Tuple[int, Dict[str, str], bytes]]
+
+
+class CatalystClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.strategic-innovations.ai/v3turbo",
+        control_plane_url: str = "https://catalyst-q-sdk.strategic-innovations.workers.dev",
+        policy: Optional[UsagePolicy] = None,
+        install_identity: Optional[InstallIdentity] = None,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.control_plane_url = control_plane_url.rstrip("/")
+        self.policy = policy or UsagePolicy.free()
+        self.install_identity = install_identity
+
+    def prepare_execute_request(
+        self,
+        circuit: List[Dict[str, Any]],
+        hmk: HypervectorMemoryKey,
+        calls_this_month: int,
+    ) -> PreparedRequest:
+        return self.prepare_execute(circuit, hmk=hmk, calls_this_month=calls_this_month)
+
+    def prepare_execute(
+        self,
+        circuit: Union[List[Dict[str, Any]], Any],
+        hmk: HypervectorMemoryKey,
+        calls_this_month: int,
+        qubits: Optional[int] = None,
+        shots: Optional[int] = None,
+        compute_units_this_month: int = 0,
+        production: bool = False,
+    ) -> PreparedRequest:
+        circuit_payload = _circuit_payload(circuit)
+        resolved_qubits = qubits or circuit_payload.get("qubits") or _infer_qubits(circuit_payload["circuit"])
+        gate_count = max(1, len(circuit_payload["circuit"]))
+        requested_compute_units = _circuit_compute_units(resolved_qubits, gate_count, shots)
+        body: Dict[str, Any] = {
+            "qubits": resolved_qubits,
+            "circuit": circuit_payload["circuit"],
+            "hmk": hmk.to_wire(),
+            "state_mode": "hmk_state_in_payload",
+            "registration": self._identity().to_wire(),
+            "billing_estimate": {
+                "circuit_runs": 1,
+                "qubits": resolved_qubits,
+                "gate_count": gate_count,
+                "shots": shots or 1,
+                "compute_units": requested_compute_units,
+            },
+        }
+        if shots is not None:
+            body["shots"] = shots
+        self.policy.check_circuit_run(
+            "execute",
+            circuit_runs_this_month=calls_this_month,
+            compute_units_this_month=compute_units_this_month,
+            qubits=resolved_qubits,
+            requested_compute_units=requested_compute_units,
+            production=production,
+        )
+        return self._request("/execute", body)
+
+    def prepare_qasm(
+        self,
+        qasm: str,
+        hmk: HypervectorMemoryKey,
+        calls_this_month: int,
+        qubits: Optional[int] = None,
+        shots: Optional[int] = None,
+        output_format: Optional[str] = None,
+        compute_units_this_month: int = 0,
+        production: bool = False,
+    ) -> PreparedRequest:
+        resolved_qubits = qubits or _infer_qasm_qubits(qasm)
+        gate_count = max(1, _infer_qasm_gate_count(qasm))
+        requested_compute_units = _circuit_compute_units(resolved_qubits, gate_count, shots)
+        body: Dict[str, Any] = {
+            "qasm": qasm,
+            "hmk": hmk.to_wire(),
+            "state_mode": "hmk_state_in_payload",
+            "registration": self._identity().to_wire(),
+            "billing_estimate": {
+                "circuit_runs": 1,
+                "qubits": resolved_qubits,
+                "gate_count": gate_count,
+                "shots": shots or 1,
+                "compute_units": requested_compute_units,
+            },
+        }
+        if shots is not None:
+            body["shots"] = shots
+        if output_format is not None:
+            body["output_format"] = output_format
+        self.policy.check_circuit_run(
+            "execute_qasm",
+            circuit_runs_this_month=calls_this_month,
+            compute_units_this_month=compute_units_this_month,
+            qubits=resolved_qubits,
+            requested_compute_units=requested_compute_units,
+            production=production,
+        )
+        return self._request("/execute/qasm", body)
+
+    def prepare_solver(
+        self,
+        kind: str,
+        payload: Dict[str, Any],
+        hmk: HypervectorMemoryKey,
+        solver_runs_this_month: int,
+        compute_units_this_month: int = 0,
+        problem_size: Optional[int] = None,
+        requested_compute_units: Optional[int] = None,
+        production: bool = False,
+    ) -> PreparedRequest:
+        allowed = {"sat", "tsp", "knapsack", "portfolio"}
+        if kind not in allowed:
+            raise ValueError(f"solver kind must be one of {sorted(allowed)}")
+        resolved_problem_size = problem_size or _infer_problem_size(kind, payload)
+        resolved_compute_units = requested_compute_units or _infer_solver_compute_units(
+            kind, payload, resolved_problem_size
+        )
+        body = {
+            **payload,
+            "hmk": hmk.to_wire(),
+            "state_mode": "hmk_state_in_payload",
+            "registration": self._identity().to_wire(),
+            "billing_estimate": {
+                "solver_runs": 1,
+                "problem_size": resolved_problem_size,
+                "compute_units": resolved_compute_units,
+            },
+        }
+        self.policy.check_solver_run(
+            f"solve_{kind}",
+            solver_runs_this_month=solver_runs_this_month,
+            compute_units_this_month=compute_units_this_month,
+            problem_size=resolved_problem_size,
+            requested_compute_units=resolved_compute_units,
+            production=production,
+        )
+        return self._request(f"/solve/{kind}", body)
+
+    def prepare_activation_request(self) -> PreparedRequest:
+        identity = self._identity()
+        return self._control_request(
+            "/v1/installs/activate",
+            {
+                "install_id": identity.install_id,
+                "tier": identity.tier,
+                "mode": identity.mode,
+                "register_on": identity.register_on,
+                "sdk_version": "0.1.0",
+                "package": "catalyst-q",
+            },
+        )
+
+    def prepare_usage_check_request(
+        self,
+        operation: str,
+        route: str,
+        billing_estimate: Dict[str, Any],
+        production: bool = False,
+    ) -> PreparedRequest:
+        identity = self._identity()
+        return self._control_request(
+            "/v1/usage/check",
+            {
+                "install_id": identity.install_id,
+                "operation": operation,
+                "route": route,
+                "billing_estimate": billing_estimate,
+                "production": production,
+                "sdk_version": "0.1.0",
+            },
+        )
+
+    def prepare_sat(
+        self,
+        problem: Any,
+        hmk: HypervectorMemoryKey,
+        solver_runs_this_month: int,
+        compute_units_this_month: int = 0,
+        production: bool = False,
+    ) -> PreparedRequest:
+        return self._prepare_problem("sat", problem, hmk, solver_runs_this_month, compute_units_this_month, production)
+
+    def prepare_tsp(
+        self,
+        problem: Any,
+        hmk: HypervectorMemoryKey,
+        solver_runs_this_month: int,
+        compute_units_this_month: int = 0,
+        production: bool = False,
+    ) -> PreparedRequest:
+        return self._prepare_problem("tsp", problem, hmk, solver_runs_this_month, compute_units_this_month, production)
+
+    def prepare_knapsack(
+        self,
+        problem: Any,
+        hmk: HypervectorMemoryKey,
+        solver_runs_this_month: int,
+        compute_units_this_month: int = 0,
+        production: bool = False,
+    ) -> PreparedRequest:
+        return self._prepare_problem(
+            "knapsack", problem, hmk, solver_runs_this_month, compute_units_this_month, production
+        )
+
+    def prepare_portfolio(
+        self,
+        problem: Any,
+        hmk: HypervectorMemoryKey,
+        solver_runs_this_month: int,
+        compute_units_this_month: int = 0,
+        production: bool = False,
+    ) -> PreparedRequest:
+        return self._prepare_problem(
+            "portfolio", problem, hmk, solver_runs_this_month, compute_units_this_month, production
+        )
+
+    def _prepare_problem(
+        self,
+        kind: str,
+        problem: Any,
+        hmk: HypervectorMemoryKey,
+        solver_runs_this_month: int,
+        compute_units_this_month: int,
+        production: bool,
+    ) -> PreparedRequest:
+        payload = _problem_payload(problem)
+        return self.prepare_solver(
+            kind,
+            payload,
+            hmk=hmk,
+            solver_runs_this_month=solver_runs_this_month,
+            compute_units_this_month=compute_units_this_month,
+            problem_size=getattr(problem, "problem_size", None),
+            requested_compute_units=getattr(problem, "compute_units", None),
+            production=production,
+        )
+
+    def _request(self, path: str, body: Dict[str, Any]) -> PreparedRequest:
+        identity = self._identity()
+        return PreparedRequest(
+            method="POST",
+            url=f"{self.base_url}{path}",
+            headers={
+                "Authorization": f"Bearer {self.api_key or 'catalyst-free-anonymous'}",
+                "Content-Type": "application/json",
+                "User-Agent": "catalyst-q/0.1.0",
+                "X-Catalyst-SDK": "catalyst-q/0.1.0",
+                "X-Catalyst-API": "catalyst-q",
+                "X-Catalyst-Install-ID": identity.install_id,
+                "X-Catalyst-Install-Tier": identity.tier,
+                "X-Catalyst-Account-Mode": identity.mode,
+            },
+            json=body,
+        )
+
+    def _control_request(self, path: str, body: Dict[str, Any]) -> PreparedRequest:
+        identity = self._identity()
+        return PreparedRequest(
+            method="POST",
+            url=f"{self.control_plane_url}{path}",
+            headers={
+                "Authorization": f"Bearer {self.api_key or 'catalyst-free-anonymous'}",
+                "Content-Type": "application/json",
+                "User-Agent": "catalyst-q/0.1.0",
+                "X-Catalyst-SDK": "catalyst-q/0.1.0",
+                "X-Catalyst-API": "catalyst-q",
+                "X-Catalyst-Install-ID": identity.install_id,
+                "X-Catalyst-Install-Tier": identity.tier,
+                "X-Catalyst-Account-Mode": identity.mode,
+            },
+            json=body,
+        )
+
+    def _identity(self) -> InstallIdentity:
+        if self.install_identity is None:
+            self.install_identity = InstallIdentity.load()
+        return self.install_identity
+
+
+CatalystQClient = CatalystClient
+
+
+def execute_prepared_request(
+    prepared: PreparedRequest,
+    timeout: float = 30.0,
+    transport: Optional[Transport] = None,
+) -> Dict[str, Any]:
+    started = time.perf_counter()
+    try:
+        status_code, headers, body = (transport or _urllib_transport)(prepared, timeout)
+    except Exception as exc:  # noqa: BLE001 - benchmark artifacts should capture transport failures.
+        latency_ms = (time.perf_counter() - started) * 1000.0
+        return {
+            "ok": False,
+            "status_code": 0,
+            "latency_ms": round(latency_ms, 3),
+            "response_bytes": 0,
+            "response_sha256": hashlib.sha256(b"").hexdigest(),
+            "headers": {},
+            "error_type": exc.__class__.__name__,
+            "error": str(exc),
+        }
+    latency_ms = (time.perf_counter() - started) * 1000.0
+    result: Dict[str, Any] = {
+        "ok": 200 <= status_code < 300,
+        "status_code": status_code,
+        "latency_ms": round(latency_ms, 3),
+        "response_bytes": len(body),
+        "response_sha256": hashlib.sha256(body).hexdigest(),
+        "headers": dict(headers),
+    }
+    parsed = _try_parse_json(body)
+    if parsed is not None:
+        result["json"] = parsed
+    else:
+        result["text_preview"] = body[:512].decode("utf-8", errors="replace")
+    return result
+
+
+def _urllib_transport(prepared: PreparedRequest, timeout: float) -> Tuple[int, Dict[str, str], bytes]:
+    encoded = json.dumps(prepared.json, separators=(",", ":")).encode("utf-8")
+    req = request.Request(prepared.url, data=encoded, method=prepared.method, headers=prepared.headers)
+    try:
+        with request.urlopen(req, timeout=timeout) as response:
+            return response.status, dict(response.headers.items()), response.read()
+    except error.HTTPError as exc:
+        return exc.code, dict(exc.headers.items()), exc.read()
+
+
+def _try_parse_json(body: bytes) -> Optional[Any]:
+    try:
+        return json.loads(body.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return None
+
+
+def _circuit_payload(circuit: Union[List[Dict[str, Any]], Any]) -> Dict[str, Any]:
+    if hasattr(circuit, "to_payload"):
+        payload = circuit.to_payload()
+        if not isinstance(payload, dict) or "circuit" not in payload:
+            raise ValueError("circuit.to_payload() must return a dict with a circuit key")
+        return payload
+    return {"circuit": circuit}
+
+
+def _problem_payload(problem: Any) -> Dict[str, Any]:
+    if hasattr(problem, "to_payload"):
+        payload = problem.to_payload()
+        if not isinstance(payload, dict):
+            raise ValueError("problem.to_payload() must return a dict")
+        return payload
+    if not isinstance(problem, dict):
+        raise ValueError("solver problem must be a problem dataclass or payload dict")
+    return problem
+
+
+def _infer_qubits(circuit: List[Dict[str, Any]]) -> int:
+    maximum = 0
+    for gate in circuit:
+        for key in ("target", "control"):
+            if key in gate and isinstance(gate[key], int):
+                maximum = max(maximum, gate[key] + 1)
+        for key in ("targets", "controls"):
+            values = gate.get(key)
+            if isinstance(values, list) and values:
+                maximum = max(maximum, *[int(value) + 1 for value in values])
+    return max(1, maximum)
+
+
+def _infer_qasm_qubits(qasm: str) -> int:
+    matches = [int(match.group(1)) for match in re.finditer(r"\bqreg\s+\w+\[(\d+)\]", qasm)]
+    return max(matches) if matches else 1
+
+
+def _infer_qasm_gate_count(qasm: str) -> int:
+    ignored = ("OPENQASM", "include", "qreg", "creg", "//")
+    count = 0
+    for raw_line in qasm.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith(ignored):
+            continue
+        count += 1
+    return count
+
+
+def _circuit_compute_units(qubits: int, gate_count: int, shots: Optional[int]) -> int:
+    return max(1, qubits) * max(1, gate_count) * max(1, shots or 1)
+
+
+def _infer_problem_size(kind: str, payload: Dict[str, Any]) -> int:
+    if kind == "sat":
+        return int(payload.get("variables", 1))
+    if kind == "tsp":
+        return len(payload.get("distances", [])) or len(payload.get("cities", [])) or 1
+    if kind == "knapsack":
+        return len(payload.get("weights", [])) or 1
+    if kind == "portfolio":
+        return len(payload.get("returns", [])) or 1
+    return 1
+
+
+def _infer_solver_compute_units(kind: str, payload: Dict[str, Any], problem_size: int) -> int:
+    if kind == "sat":
+        return max(1, problem_size * len(payload.get("clauses", [])))
+    if kind in {"tsp", "portfolio"}:
+        return max(1, problem_size * problem_size)
+    if kind == "knapsack":
+        return max(1, problem_size * max(1, int(payload.get("capacity", 1))))
+    return max(1, problem_size)

catalyst_hmk/cloudflare.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List
+
+
+@dataclass(frozen=True)
+class RenderedDeployment:
+    files: Dict[str, str]
+    deploy_command: List[str]
+
+
+@dataclass(frozen=True)
+class CloudflareDeploymentSpec:
+    worker_name: str
+    route_prefix: str = "/v3turbo"
+    compatibility_date: str = "2026-05-11"
+
+    def render(self) -> RenderedDeployment:
+        wrangler = "\n".join(
+            [
+                f'name = "{self.worker_name}"',
+                'main = "src/worker.ts"',
+                f'compatibility_date = "{self.compatibility_date}"',
+                "",
+                "[vars]",
+                'CATALYST_STATE_MODE = "hmk_state_in_payload"',
+                'CATALYST_SHARDING = "nonlinear"',
+                "",
+            ]
+        )
+        worker = "\n".join(
+            [
+                "export default {",
+                "  async fetch(request: Request): Promise<Response> {",
+                "    const url = new URL(request.url);",
+                f'    if (!url.pathname.startsWith("{self.route_prefix}")) {{',
+                '      return new Response("not found", { status: 404 });',
+                "    }",
+                "    return Response.json({",
+                '      status: "ready",',
+                '      state_mode: "hmk_state_in_payload",',
+                '      sharding: "nonlinear",',
+                "    });",
+                "  },",
+                "};",
+                "",
+            ]
+        )
+        return RenderedDeployment(
+            files={
+                "wrangler.toml": wrangler,
+                "src/worker.ts": worker,
+            },
+            deploy_command=["npx", "wrangler", "deploy"],
+        )