singularity-grid 0.2.0__tar.gz → 0.4.0__tar.gz

{singularity_grid-0.2.0 → singularity_grid-0.4.0}/.gitignore

@@ -3,3 +3,6 @@ __pycache__/
 dist/
 *.egg-info/
 .venv/
+
+# agent tooling state
+.omx/

{singularity_grid-0.2.0 → singularity_grid-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: singularity-grid
-Version: 0.2.0
-Summary: Python SDK for the SGL Network confidential compute grid
+Version: 0.4.0
+Summary: Python SDK for the SGL Network confidential compute grid (end-to-end encrypted + streaming)
 Project-URL: Homepage, https://singularitylayer.xyz
 Project-URL: Repository, https://github.com/SingularityLayer/sgl-network-sdk
 Project-URL: Documentation, https://docs.singularitylayer.xyz/sdk
@@ -20,8 +20,11 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
+Requires-Dist: base58>=2.1
+Requires-Dist: cryptography>=42.0
 Requires-Dist: httpx>=0.24
 Requires-Dist: pydantic>=2.0
+Requires-Dist: pynacl>=1.5
 Provides-Extra: openai
 Requires-Dist: openai>=1.0; extra == 'openai'
 Description-Content-Type: text/markdown
@@ -52,7 +55,7 @@ The SGL Network orchestrator exposes an OpenAI-compatible `/v1/chat/completions`
 from openai import OpenAI
 
 client = OpenAI(
-    base_url="https://sgl-network-orchestrator.ivaavimusicproductions.workers.dev/v1",
+    base_url="https://grid.x402compute.cc/v1",
     api_key="scg_your_api_key",
 )
 

{singularity_grid-0.2.0 → singularity_grid-0.4.0}/README.md

@@ -24,7 +24,7 @@ The SGL Network orchestrator exposes an OpenAI-compatible `/v1/chat/completions`
 from openai import OpenAI
 
 client = OpenAI(
-    base_url="https://sgl-network-orchestrator.ivaavimusicproductions.workers.dev/v1",
+    base_url="https://grid.x402compute.cc/v1",
     api_key="scg_your_api_key",
 )
 

{singularity_grid-0.2.0 → singularity_grid-0.4.0}/examples/openai_compatible.py

@@ -10,7 +10,7 @@ beyond swapping the base URL and API key.
 from openai import OpenAI
 
 client = OpenAI(
-    base_url="https://sgl-network-orchestrator.ivaavimusicproductions.workers.dev/v1",
+    base_url="https://grid.x402compute.cc/v1",
     api_key="scg_your_api_key_here",
 )
 

{singularity_grid-0.2.0 → singularity_grid-0.4.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "singularity-grid"
-version = "0.2.0"
-description = "Python SDK for the SGL Network confidential compute grid"
+version = "0.4.0"
+description = "Python SDK for the SGL Network confidential compute grid (end-to-end encrypted + streaming)"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.9"
@@ -28,6 +28,9 @@ classifiers = [
 dependencies = [
     "httpx>=0.24",
     "pydantic>=2.0",
+    "pynacl>=1.5",
+    "cryptography>=42.0",
+    "base58>=2.1",
 ]
 
 [project.optional-dependencies]

{singularity_grid-0.2.0 → singularity_grid-0.4.0}/singularity_grid/client.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
-from typing import Any, Dict, List, Optional
+import json as _json
+from typing import Any, Dict, Iterator, List, Optional
 
 import httpx
 
+from . import e2e
 from .models import (
     AttestationProof,
     CapacityResponse,
@@ -23,9 +25,7 @@ from .models import (
     ProcessorResult,
 )
 
-DEFAULT_BASE_URL = (
-    "https://sgl-network-orchestrator.ivaavimusicproductions.workers.dev"
-)
+DEFAULT_BASE_URL = "https://grid.x402compute.cc"
 
 DEFAULT_TIMEOUT = 60.0
 
@@ -93,6 +93,9 @@ class GridClient:
         headers: Dict[str, str] = {"Accept": "application/json"}
         if api_key:
             headers["Authorization"] = f"Bearer {api_key}"
+            # Grid credit billing reads X-API-Key; send both so reserve + chat
+            # resolve the paying wallet (credits mode) for end-to-end requests.
+            headers["X-API-Key"] = api_key
         self._client = httpx.Client(
             base_url=self._base_url,
             headers=headers,
@@ -206,6 +209,197 @@ class GridClient:
         data = self._request("GET", f"/grid/jobs/{job_id}/attestation")
         return AttestationProof.model_validate(data)
 
+    # -- chat (end-to-end encrypted) ---------------------------------------
+
+    def providers(self, model: str, cluster: Optional[str] = None) -> List[Dict[str, Any]]:
+        """List nodes serving ``model`` with their effective price + reputation,
+        cheapest first — pick one and pass its ``node_id`` to ``chat_completions(node=...)``."""
+        q = f"/v1/providers?model={model}" + (f"&cluster={cluster}" if cluster else "")
+        data = self._request("GET", q)
+        return data.get("providers", [])
+
+    def _reserve(self, model: str, cluster: Optional[str] = None, node: Optional[str] = None) -> Dict[str, Any]:
+        """Reserve a node + learn its X25519 key so we can seal the prompt to it.
+
+        When ``cluster`` is given, a node *inside that cluster* (a Tokenised Compute
+        Market) is reserved. When ``node`` is given, that specific provider is reserved.
+        """
+        payload: Dict[str, Any] = {"model": model}
+        if cluster is not None:
+            payload["cluster"] = cluster
+        if node is not None:
+            payload["node"] = node
+        data = self._request("POST", "/v1/reserve", json=payload)
+        if not data.get("node_x25519_pubkey"):
+            raise SGLAPIError(503, "Reserved node does not support E2E encryption")
+        return data
+
+    def chat_completions(
+        self,
+        model: str,
+        messages: List[Dict[str, str]],
+        *,
+        temperature: float = 0.7,
+        max_tokens: int = 512,
+        cluster: Optional[str] = None,
+        node: Optional[str] = None,
+        pay_in_coin: bool = False,
+    ) -> Dict[str, Any]:
+        """End-to-end encrypted chat completion.
+
+        The prompt is sealed in this client to the serving node's key and only
+        decrypts inside its TEE — the orchestrator only relays ciphertext. Requires
+        ``api_key`` (credits); x402 pay-per-call isn't signed here (use the wallet
+        flow). Returns an OpenAI-style dict with an extra ``attestation`` field.
+
+        Parameters
+        ----------
+        cluster:
+            Optional cluster slug — route to a node inside that Tokenised Compute
+            Market (only nodes that joined the cluster serve it).
+        pay_in_coin:
+            When ``True`` and the cluster has a tradeable coin, pay for the request
+            in that coin (the believer lane) instead of USDC/credits. Falls back to
+            USDC if the coin's oracle price is untrusted.
+        """
+        reservation = self._reserve(model, cluster=cluster, node=node)
+        resp_sk, resp_pub = e2e.new_response_keypair()
+        sealed_ct, eph = e2e.seal_input(
+            reservation["node_x25519_pubkey"], resp_pub,
+            _json.dumps({"messages": messages, "temperature": temperature, "max_tokens": max_tokens}).encode(),
+        )
+        body: Dict[str, Any] = {
+            "reservation_token": reservation["reservation_token"],
+            "max_tokens": max_tokens,  # cleartext, only used to quote the x402 price
+            "enc": {
+                "ciphertext": sealed_ct,
+                "client_ephemeral_pubkey": eph,
+                "client_response_pubkey": resp_pub,
+                "algorithm": e2e.ALGO_V2,
+            },
+        }
+        if pay_in_coin:
+            body["pay_in_coin"] = True
+        try:
+            data = self._request("POST", "/v1/chat/completions", json=body)
+        except SGLAPIError as err:
+            if err.status_code == 402:
+                raise SGLAPIError(402, "Payment required — pass api_key (credits); the Python GridClient does not sign x402 payments.") from err
+            raise
+
+        sealed = data.get("sealed_result")
+        if not sealed:
+            raise SGLAPIError(500, "No sealed result returned")
+        plain = e2e.open_output(resp_sk, resp_pub, sealed["ephemeral_public_key"], sealed["ciphertext"])
+        parsed = _json.loads(plain)
+        return {
+            "id": data.get("id", ""),
+            "object": "chat.completion",
+            "model": model,
+            "choices": [{"index": 0, "message": {"role": "assistant", "content": parsed.get("content", "")}, "finish_reason": "stop"}],
+            "usage": data.get("usage") or parsed.get("usage", {}),
+            "attestation": {
+                "node_id": reservation.get("node_id"),
+                "tee_type": reservation.get("tee_type"),
+                "verified": bool(reservation.get("attestation_verified", False)),
+            },
+        }
+
+    def chat_completion_stream(
+        self,
+        model: str,
+        messages: List[Dict[str, str]],
+        *,
+        temperature: float = 0.7,
+        max_tokens: int = 512,
+    ) -> Iterator[str]:
+        """Yield decoded text as it streams (end-to-end encrypted). Requires
+        ``api_key`` (credits). Each chunk is decrypted and its ordering +
+        termination verified (a truncated stream raises). If streaming isn't
+        enabled server-side, the whole reply is yielded as one chunk."""
+        reservation = self._reserve(model)
+        resp_sk, resp_pub = e2e.new_response_keypair()
+        nonce = e2e.random_nonce_b58()
+        sealed_ct, eph = e2e.seal_input(
+            reservation["node_x25519_pubkey"], resp_pub,
+            _json.dumps({"messages": messages, "temperature": temperature, "max_tokens": max_tokens, "stream": True, "nonce": nonce}).encode(),
+        )
+        body = {
+            "reservation_token": reservation["reservation_token"],
+            "stream": True,
+            "max_tokens": max_tokens,
+            "enc": {
+                "ciphertext": sealed_ct,
+                "client_ephemeral_pubkey": eph,
+                "client_response_pubkey": resp_pub,
+                "algorithm": e2e.ALGO_V2,
+            },
+        }
+        with self._client.stream("POST", "/v1/chat/completions", json=body) as resp:
+            if resp.status_code != 200:
+                resp.read()
+                if resp.status_code == 402:
+                    raise SGLAPIError(402, "Payment required — pass api_key (credits); the Python GridClient does not sign x402 payments.")
+                msg = resp.text
+                try:
+                    err = resp.json().get("error")
+                    msg = err.get("message", msg) if isinstance(err, dict) else (err or msg)
+                except Exception:
+                    pass
+                raise SGLAPIError(resp.status_code, str(msg))
+
+            if "text/event-stream" not in resp.headers.get("content-type", ""):
+                resp.read()
+                data = _json.loads(resp.text)
+                sealed = data.get("sealed_result")
+                if not sealed:
+                    raise SGLAPIError(500, "No sealed result returned")
+                plain = e2e.open_output(resp_sk, resp_pub, sealed["ephemeral_public_key"], sealed["ciphertext"])
+                content = _json.loads(plain).get("content", "")
+                if content:
+                    yield content
+                return
+
+            expected_seq = 0
+            out_key = None
+            stream_eph = None
+            saw_final = False
+            for line in resp.iter_lines():
+                line = line.strip()
+                if not line:
+                    continue
+                if line.startswith("event: error"):
+                    raise SGLAPIError(502, "stream aborted by server")
+                if line.startswith(":") or not line.startswith("data:"):
+                    continue
+                payload = line[5:].strip()
+                if payload == "[DONE]":
+                    continue
+                try:
+                    chunk = _json.loads(payload)
+                except _json.JSONDecodeError as exc:
+                    raise SGLAPIError(502, "malformed stream chunk") from exc
+                seq = chunk.get("seq")
+                if seq is None or "ct" not in chunk:
+                    raise SGLAPIError(502, "invalid stream chunk (missing seq/ciphertext)")
+                if seq != expected_seq:
+                    raise SGLAPIError(502, f"stream out of order (expected {expected_seq}, got {seq})")
+                if seq == 0:
+                    stream_eph = chunk.get("eph")
+                    if not stream_eph:
+                        raise SGLAPIError(502, "stream chunk 0 missing ephemeral key")
+                    out_key = e2e.stream_out_key(resp_sk, stream_eph)
+                is_final = chunk.get("final") is True
+                text = e2e.open_stream_chunk(out_key, resp_pub, stream_eph, nonce, seq, is_final, chunk["ct"]).decode()
+                if text:
+                    yield text
+                expected_seq += 1
+                if is_final:
+                    saw_final = True
+                    break
+            if not saw_final:
+                raise SGLAPIError(502, "stream ended before final chunk (truncated)")
+
     # -- processor endpoints -----------------------------------------------
 
     def deploy_processor(

singularity_grid-0.4.0/singularity_grid/e2e.py

@@ -0,0 +1,138 @@
+"""
+End-to-end encryption for the SGL grid (client side).
+
+Must match the node, orchestrator, and browser/TS clients byte-for-byte:
+  X25519 ECDH -> HKDF-SHA256 -> XChaCha20-Poly1305 (24-byte nonce), AAD-bound.
+Sealed blob layout: nonce(24) || ciphertext, base58.
+
+The orchestrator only ever relays ciphertext — it never sees the prompt or reply.
+"""
+
+from __future__ import annotations
+
+import base58
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from nacl import bindings
+
+ALGO_V2 = "x25519-xchacha20poly1305-hkdf-v2"
+ALGO_V2_STREAM = "x25519-xchacha20poly1305-hkdf-v2-stream"
+
+_SALT = b"sgl-e2e-v2-salt"
+_INFO_INPUT = b"sgl-e2e-v2-input"
+_INFO_OUTPUT = b"sgl-e2e-v2-output"
+
+
+def _hkdf(shared: bytes, info: bytes) -> bytes:
+    return HKDF(algorithm=hashes.SHA256(), length=32, salt=_SALT, info=info).derive(shared)
+
+
+def _aad_input(node_b58: str, eph_b58: str, resp_b58: str) -> bytes:
+    return f"sgl-aad/v2/input|node={node_b58}|eph={eph_b58}|resp={resp_b58}".encode()
+
+
+def _aad_output(resp_b58: str, eph_b58: str) -> bytes:
+    return f"sgl-aad/v2/output|resp={resp_b58}|eph={eph_b58}".encode()
+
+
+def _aad_stream(resp_b58: str, eph_b58: str, nonce_b58: str, seq: int, final: bool) -> bytes:
+    f = 1 if final else 0
+    return (
+        f"sgl-aad/v2/stream|resp={resp_b58}|eph={eph_b58}|nonce={nonce_b58}|seq={seq}|final={f}"
+    ).encode()
+
+
+def _b58e(b: bytes) -> str:
+    return base58.b58encode(b).decode()
+
+
+def _b58d(s: str) -> bytes:
+    return base58.b58decode(s)
+
+
+def _gen_keypair() -> tuple[bytes, bytes]:
+    sk = bindings.randombytes(32)
+    pk = bindings.crypto_scalarmult_base(sk)
+    return sk, pk
+
+
+def new_response_keypair() -> tuple[bytes, str]:
+    """The caller's response keypair — the node seals its reply to this."""
+    sk, pk = _gen_keypair()
+    return sk, _b58e(pk)
+
+
+def random_nonce_b58() -> str:
+    """A per-request nonce bound into every stream chunk's AAD."""
+    return _b58e(bindings.randombytes(16))
+
+
+def seal_input(node_pub_b58: str, resp_pub_b58: str, plaintext: bytes) -> tuple[str, str]:
+    """Seal the prompt to the node's X25519 key. Returns (ciphertext_b58, ephemeral_pub_b58)."""
+    node_pub = _b58d(node_pub_b58)
+    eph_sk, eph_pk = _gen_keypair()
+    eph_b58 = _b58e(eph_pk)
+    shared = bindings.crypto_scalarmult(eph_sk, node_pub)
+    key = _hkdf(shared, _INFO_INPUT)
+    nonce = bindings.randombytes(24)
+    aad = _aad_input(node_pub_b58, eph_b58, resp_pub_b58)
+    ct = bindings.crypto_aead_xchacha20poly1305_ietf_encrypt(plaintext, aad, nonce, key)
+    return _b58e(nonce + ct), eph_b58
+
+
+def open_output(resp_sk: bytes, resp_pub_b58: str, node_eph_b58: str, ct_b58: str) -> bytes:
+    """Open the node's (non-stream) reply sealed to our response key."""
+    shared = bindings.crypto_scalarmult(resp_sk, _b58d(node_eph_b58))
+    key = _hkdf(shared, _INFO_OUTPUT)
+    aad = _aad_output(resp_pub_b58, node_eph_b58)
+    blob = _b58d(ct_b58)
+    return bindings.crypto_aead_xchacha20poly1305_ietf_decrypt(blob[24:], aad, blob[:24], key)
+
+
+def stream_out_key(resp_sk: bytes, node_stream_eph_b58: str) -> bytes:
+    """Derive the stream output key once from the node's stream ephemeral (chunk 0)."""
+    shared = bindings.crypto_scalarmult(resp_sk, _b58d(node_stream_eph_b58))
+    return _hkdf(shared, _INFO_OUTPUT)
+
+
+def open_stream_chunk(
+    out_key: bytes,
+    resp_pub_b58: str,
+    eph_b58: str,
+    nonce_b58: str,
+    seq: int,
+    final: bool,
+    ct_b58: str,
+) -> bytes:
+    """Open one stream chunk with the precomputed key + nonce/seq/final-bound AAD."""
+    aad = _aad_stream(resp_pub_b58, eph_b58, nonce_b58, seq, final)
+    blob = _b58d(ct_b58)
+    return bindings.crypto_aead_xchacha20poly1305_ietf_decrypt(blob[24:], aad, blob[:24], out_key)
+
+
+if __name__ == "__main__":
+    # Cross-language vector from the node's encryption.rs: proves this module's
+    # X25519+HKDF+XChaCha20+AAD+base58 match the Rust/TS/browser clients byte-for-byte.
+    import hashlib
+    import json
+
+    node_secret = bytes([0x42] * 32)
+    node_x25519_sk = hashlib.sha256(b"sgl-x25519-derive:" + node_secret).digest()
+    node_pub_b58 = _b58e(bindings.crypto_scalarmult_base(node_x25519_sk))
+
+    eph_b58 = "DQFdwcBsqukJEBn9UNfQruaTHKHxHFMVRA2B5qZuFdfB"
+    resp_b58 = "2L54SXdEHm5mraF2X2GPid3m4PSkwVehEvhk487mWTx8"
+    ct_b58 = ("gbEA6dFFVPxdar6e8QsjPKWj7xHcBo32nAqweQC5arnt4M5LmHhjREKoUTdVZsU6mmkxKu1Xmv"
+              "Eo4oG8EUySndq2ytTyzDgyfMjyBSmPE2fqjdPDzKYtdrC2kZbAfCXv227GczHgmtQBqchA5qMB5"
+              "ydxgxYnk9V8jb8sifTjHM61iEQkisdwYCqna")
+
+    shared = bindings.crypto_scalarmult(node_x25519_sk, _b58d(eph_b58))
+    key = _hkdf(shared, _INFO_INPUT)
+    aad = _aad_input(node_pub_b58, eph_b58, resp_b58)
+    blob = _b58d(ct_b58)
+    pt = bindings.crypto_aead_xchacha20poly1305_ietf_decrypt(blob[24:], aad, blob[:24], key)
+    got = json.loads(pt)
+    expected = {"messages": [{"role": "user", "content": "cross-lang v2 test"}],
+                "temperature": 0.7, "max_tokens": 512}
+    assert got == expected, f"MISMATCH: {got}"
+    print("OK: singularity-grid E2E crypto matches the cross-language vector")