sbn-sdk 0.3.0__tar.gz

sbn_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: sbn-sdk
+Version: 0.3.0
+Summary: Python SDK for the SmartBlocks Network — attestation, GEC compute, SnapChore integrity, governance, and more.
+License: MIT
+Keywords: smartblocks,sbn,snapchore,gec,attestation,integrity
+Author: SmartBlocks Team
+Author-email: devrel@smartblocks.network
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: PyJWT (>=2.8)
+Requires-Dist: cryptography (>=41.0)
+Requires-Dist: httpx (>=0.27.0,<0.28.0)
+Project-URL: Documentation, https://smartblocks.network/docs/sdk
+Project-URL: Homepage, https://smartblocks.network
+Project-URL: Repository, https://github.com/smartblocks-network/sbn-sdk
+Description-Content-Type: text/markdown
+
+# SmartBlocks Network Python SDK
+
+Canonical Python client for the SBN infrastructure. Covers the full network
+surface — gateway, SnapChore, console, and control plane.
+
+## Install
+
+```bash
+pip install sbn-sdk
+# or from source
+cd sdk/python && pip install -e .
+```
+
+## Quick start
+
+```python
+from sbn import SbnClient
+
+client = SbnClient(base_url="https://api.smartblocks.network")
+client.authenticate_api_key("sbn_live_abc123")
+
+# SnapChore — capture, verify, seal
+block = client.snapchore.capture({"event": "signup", "user": "u-42"})
+client.snapchore.verify(block["snapchore_hash"], {"event": "signup", "user": "u-42"})
+client.snapchore.seal(block["snapchore_hash"], {"event": "signup", "user": "u-42"})
+
+# Gateway — slots, receipts, attestations
+slot = client.gateway.create_slot(worker_id="w-1", task_type="classify")
+receipt = client.gateway.fetch_receipt(slot.receipt_id)
+
+# Console — API keys, usage, billing
+keys = client.console.list_api_keys("proj-123")
+usage = client.console.get_usage("proj-123")
+
+# Control plane — rate plans, tenants, validators
+plans = client.control_plane.list_rate_plans()
+client.control_plane.create_tenant(
+    name="Acme Corp",
+    contact_email="ops@acme.co",
+    aggregator_endpoint="https://agg.acme.co",
+    rate_plan_id=plans[0].id,
+)
+```
+
+## Auth methods
+
+```python
+# API key (most common for external devs)
+client.authenticate_api_key("sbn_live_...")
+
+# Bearer token (console sessions, service-to-service)
+client.authenticate_bearer("eyJ...")
+
+# Ed25519 signing key (auto-refreshing JWTs for agents)
+from sbn import SigningKey
+key = SigningKey.from_pem("/path/to/key.pem", issuer="my-svc", audience="sbn")
+client.authenticate_signing_key(key, scopes=["attest.write", "snapchore.seal"])
+```
+
+## Sub-clients
+
+| Property | Domain | Key operations |
+|----------|--------|----------------|
+| `client.gateway` | Slots & receipts | `create_slot`, `close_slot`, `fetch_receipt`, `request_attestation` |
+| `client.snapchore` | Hash capture | `capture`, `verify`, `seal`, `create_chain`, `append_to_chain` |
+| `client.console` | Developer console | `list_api_keys`, `create_api_key`, `get_usage`, `get_billing_status` |
+| `client.control_plane` | Multi-tenancy | `list_rate_plans`, `create_tenant`, `register_validator` |
+
+## Legacy compatibility
+
+The original `sbn_gateway.py` single-file SDK is preserved for backward
+compatibility. New integrations should use `from sbn import SbnClient`.
+

sbn_sdk-0.3.0/README.md

@@ -0,0 +1,72 @@
+# SmartBlocks Network Python SDK
+
+Canonical Python client for the SBN infrastructure. Covers the full network
+surface — gateway, SnapChore, console, and control plane.
+
+## Install
+
+```bash
+pip install sbn-sdk
+# or from source
+cd sdk/python && pip install -e .
+```
+
+## Quick start
+
+```python
+from sbn import SbnClient
+
+client = SbnClient(base_url="https://api.smartblocks.network")
+client.authenticate_api_key("sbn_live_abc123")
+
+# SnapChore — capture, verify, seal
+block = client.snapchore.capture({"event": "signup", "user": "u-42"})
+client.snapchore.verify(block["snapchore_hash"], {"event": "signup", "user": "u-42"})
+client.snapchore.seal(block["snapchore_hash"], {"event": "signup", "user": "u-42"})
+
+# Gateway — slots, receipts, attestations
+slot = client.gateway.create_slot(worker_id="w-1", task_type="classify")
+receipt = client.gateway.fetch_receipt(slot.receipt_id)
+
+# Console — API keys, usage, billing
+keys = client.console.list_api_keys("proj-123")
+usage = client.console.get_usage("proj-123")
+
+# Control plane — rate plans, tenants, validators
+plans = client.control_plane.list_rate_plans()
+client.control_plane.create_tenant(
+    name="Acme Corp",
+    contact_email="ops@acme.co",
+    aggregator_endpoint="https://agg.acme.co",
+    rate_plan_id=plans[0].id,
+)
+```
+
+## Auth methods
+
+```python
+# API key (most common for external devs)
+client.authenticate_api_key("sbn_live_...")
+
+# Bearer token (console sessions, service-to-service)
+client.authenticate_bearer("eyJ...")
+
+# Ed25519 signing key (auto-refreshing JWTs for agents)
+from sbn import SigningKey
+key = SigningKey.from_pem("/path/to/key.pem", issuer="my-svc", audience="sbn")
+client.authenticate_signing_key(key, scopes=["attest.write", "snapchore.seal"])
+```
+
+## Sub-clients
+
+| Property | Domain | Key operations |
+|----------|--------|----------------|
+| `client.gateway` | Slots & receipts | `create_slot`, `close_slot`, `fetch_receipt`, `request_attestation` |
+| `client.snapchore` | Hash capture | `capture`, `verify`, `seal`, `create_chain`, `append_to_chain` |
+| `client.console` | Developer console | `list_api_keys`, `create_api_key`, `get_usage`, `get_billing_status` |
+| `client.control_plane` | Multi-tenancy | `list_rate_plans`, `create_tenant`, `register_validator` |
+
+## Legacy compatibility
+
+The original `sbn_gateway.py` single-file SDK is preserved for backward
+compatibility. New integrations should use `from sbn import SbnClient`.

sbn_sdk-0.3.0/pyproject.toml

@@ -0,0 +1,38 @@
+[tool.poetry]
+name = "sbn-sdk"
+version = "0.3.0"
+description = "Python SDK for the SmartBlocks Network — attestation, GEC compute, SnapChore integrity, governance, and more."
+authors = ["SmartBlocks Team <devrel@smartblocks.network>"]
+readme = "README.md"
+license = "MIT"
+packages = [{include = "sbn"}, {include = "tower"}]
+keywords = ["smartblocks", "sbn", "snapchore", "gec", "attestation", "integrity"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[tool.poetry.urls]
+Homepage = "https://smartblocks.network"
+Repository = "https://github.com/smartblocks-network/sbn-sdk"
+Documentation = "https://smartblocks.network/docs/sdk"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+httpx = "^0.27.0"
+cryptography = ">=41.0"
+PyJWT = ">=2.8"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.2"
+
+[build-system]
+requires = ["poetry-core>=1.5.0"]
+build-backend = "poetry.core.masonry.api"

sbn_sdk-0.3.0/sbn/__init__.py

@@ -0,0 +1,102 @@
+"""SmartBlocks Network SDK — canonical client for the SBN infrastructure.
+
+Usage::
+
+    from sbn import SbnClient
+
+    client = SbnClient(base_url="https://api.smartblocks.network")
+    client.authenticate_api_key("sbn_live_abc123")
+
+    # SnapChore
+    block = client.snapchore.capture({"event": "signup", "user": "u-42"})
+    ok    = client.snapchore.verify(block["snapchore_hash"], {"event": "signup", "user": "u-42"})
+
+    # Gateway (slots / receipts / attestations)
+    slot    = client.gateway.create_slot(worker_id="w-1", task_type="classify")
+    receipt = client.gateway.fetch_receipt(slot.receipt_id)
+
+    # Console (projects, API keys, usage)
+    keys  = client.console.list_api_keys()
+    usage = client.console.get_usage()
+
+    # GEC (frontier registry, compute, health)
+    result = client.gec.compute(y=85.0, x=100.0, frontier_id="core-ops")
+
+    # Governance (proposal lifecycle)
+    proposals = client.governance.list_proposals()
+
+    # Control plane (tenants, rate plans, validators)
+    plans = client.control_plane.list_rate_plans()
+"""
+
+from __future__ import annotations
+
+__version__ = "0.3.0"
+
+# Re-export top-level conveniences
+from sbn.client import SbnClient
+from sbn.auth import SigningKey, MintedToken
+from sbn._http import SbnError, SbnTransportError, RetryConfig
+from sbn.gateway import (
+    GatewayClient,
+    SlotCreateRequest,
+    SlotHandle,
+    SlotClosure,
+    SlotSummary,
+    Receipt,
+)
+from sbn.snapchore import SnapChoreClient
+from sbn.console import ConsoleClient, ApiKeyRecord, ApiKeyLimits, ProjectUsage
+from sbn.control_plane import (
+    ControlPlaneClient,
+    RatePlan,
+    TenantSummary,
+    TenantDetail,
+    Validator,
+)
+from sbn.lattice import LatticeClient
+from sbn.reality import RealityClient
+from sbn.blocks import BlocksClient
+from sbn.gec import GecClient
+from sbn.governance import GovernanceClient
+
+__all__ = [
+    "SbnClient",
+    # Auth
+    "SigningKey",
+    "MintedToken",
+    # HTTP / errors
+    "SbnError",
+    "SbnTransportError",
+    "RetryConfig",
+    # Gateway
+    "GatewayClient",
+    "SlotCreateRequest",
+    "SlotHandle",
+    "SlotClosure",
+    "SlotSummary",
+    "Receipt",
+    # SnapChore
+    "SnapChoreClient",
+    # Console
+    "ConsoleClient",
+    "ApiKeyRecord",
+    "ApiKeyLimits",
+    "ProjectUsage",
+    # Control plane
+    "ControlPlaneClient",
+    "RatePlan",
+    "TenantSummary",
+    "TenantDetail",
+    "Validator",
+    # Lattice
+    "LatticeClient",
+    # Reality Check
+    "RealityClient",
+    # Blocks
+    "BlocksClient",
+    # GEC
+    "GecClient",
+    # Governance
+    "GovernanceClient",
+]

sbn_sdk-0.3.0/sbn/_http.py

@@ -0,0 +1,220 @@
+"""Shared HTTP transport with retry, error handling, and auth injection."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping, MutableMapping, Sequence
+
+import httpx
+
+
+# ---------------------------------------------------------------------------
+# Error types
+# ---------------------------------------------------------------------------
+
+
+class SbnError(RuntimeError):
+    """Raised when the SBN API responds with an error payload."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: str | None = None,
+        details: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.details = dict(details or {})
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        parts = [f"status={self.status_code}"]
+        if self.code:
+            parts.append(f"code={self.code}")
+        if self.details:
+            parts.append(f"details={self.details}")
+        return f"{base} ({', '.join(parts)})"
+
+
+class SbnTransportError(RuntimeError):
+    """Raised when the SDK cannot reach SBN after retries."""
+
+    def __init__(self, message: str, *, last_exception: Exception | None = None) -> None:
+        super().__init__(message)
+        self.last_exception = last_exception
+
+
+# ---------------------------------------------------------------------------
+# Retry config
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class RetryConfig:
+    """Retry configuration for transient failures."""
+
+    attempts: int = 3
+    backoff_factor: float = 0.5
+    status_forcelist: Sequence[int] = (500, 502, 503, 504)
+
+
+# ---------------------------------------------------------------------------
+# Auth state
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class AuthState:
+    """Mutable auth state shared across sub-clients."""
+
+    api_key: str | None = None
+    bearer_token: str | None = None
+    tenant_id: str | None = None
+    token_provider: Callable[[], str] | None = None
+
+
+# ---------------------------------------------------------------------------
+# HTTP transport
+# ---------------------------------------------------------------------------
+
+
+class HttpTransport:
+    """Thin wrapper around httpx.Client with retry and auth injection."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        auth: AuthState,
+        retry: RetryConfig | None = None,
+        timeout: float = 10.0,
+        user_agent: str = "sbn-sdk/0.2",
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._auth = auth
+        self._retry = retry or RetryConfig()
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=timeout,
+            headers={"User-Agent": user_agent},
+            transport=transport,
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ------------------------------ auth headers ---------------------------
+
+    def _headers(self, extra: Mapping[str, str] | None = None) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        if self._auth.tenant_id:
+            headers["X-Tenant-ID"] = self._auth.tenant_id
+
+        # API key auth takes precedence
+        if self._auth.api_key:
+            headers["x-api-key"] = self._auth.api_key
+        elif self._auth.token_provider:
+            headers["Authorization"] = f"Bearer {self._auth.token_provider()}"
+        elif self._auth.bearer_token:
+            headers["Authorization"] = f"Bearer {self._auth.bearer_token}"
+
+        if extra:
+            headers.update(extra)
+        return headers
+
+    # ------------------------------ request core ---------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        attempts = max(1, self._retry.attempts)
+        backoff = max(0.0, self._retry.backoff_factor)
+        method_upper = method.upper()
+
+        for attempt in range(1, attempts + 1):
+            try:
+                response = self._client.request(
+                    method_upper,
+                    path,
+                    headers=self._headers(headers),
+                    **kwargs,
+                )
+            except httpx.RequestError as exc:
+                if attempt >= attempts:
+                    raise SbnTransportError(
+                        "Failed to reach SBN", last_exception=exc
+                    ) from exc
+                time.sleep(backoff)
+                backoff *= 2
+                continue
+
+            if (
+                response.status_code in self._retry.status_forcelist
+                and attempt < attempts
+            ):
+                response.close()
+                time.sleep(backoff)
+                backoff *= 2
+                continue
+
+            if response.status_code >= 400:
+                raise _error_from_response(response)
+            return response
+
+        raise SbnTransportError("Exhausted retries reaching SBN")
+
+    def get(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("POST", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("DELETE", path, **kwargs)
+
+
+def _error_from_response(response: httpx.Response) -> SbnError:
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = None
+
+    message = response.reason_phrase or "SBN request failed"
+    code: str | None = None
+    details: MutableMapping[str, Any] = {}
+
+    if isinstance(payload, Mapping):
+        if isinstance(payload.get("error"), Mapping):
+            err = payload["error"]
+            message = str(err.get("message") or message)
+            code = err.get("code")
+            if isinstance(err.get("details"), Mapping):
+                details.update(err["details"])
+        elif isinstance(payload.get("error"), str):
+            code = payload["error"]
+            message = str(payload.get("detail") or payload.get("message") or message)
+        else:
+            message = str(payload.get("message") or payload.get("detail") or message)
+        if isinstance(payload.get("details"), Mapping):
+            details.update(payload["details"])
+    elif payload is not None:
+        details["response"] = payload
+
+    return SbnError(message, status_code=response.status_code, code=code, details=details)

sbn_sdk-0.3.0/sbn/_version.py

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

sbn_sdk-0.3.0/sbn/auth.py

@@ -0,0 +1,136 @@
+"""Ed25519 signing and JWT minting for SBN service-to-service auth."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _canonical_json(data: Mapping[str, Any]) -> bytes:
+    return json.dumps(data, separators=(",", ":"), sort_keys=True).encode("utf-8")
+
+
+def _now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+@dataclass(slots=True)
+class MintedToken:
+    """A freshly minted bearer token and its expiry."""
+
+    token: str
+    expires_at: datetime
+
+    @classmethod
+    def from_ttl(cls, token: str, ttl_seconds: int) -> MintedToken:
+        return cls(token=token, expires_at=_now_utc() + timedelta(seconds=ttl_seconds))
+
+    @property
+    def expired(self) -> bool:
+        return _now_utc() >= self.expires_at
+
+
+@dataclass(slots=True)
+class SigningKey:
+    """Ed25519 signing helper for JWT minting and payload signatures."""
+
+    private_key: Ed25519PrivateKey
+    issuer: str
+    audience: str
+    kid: str = "sbn-ed25519"
+
+    @classmethod
+    def from_pem(
+        cls,
+        source: str | bytes | os.PathLike[str],
+        *,
+        issuer: str,
+        audience: str,
+        kid: str = "sbn-ed25519",
+    ) -> SigningKey:
+        if isinstance(source, (str, os.PathLike)):
+            text = str(source)
+            path = Path(text)
+            pem_data = path.read_bytes() if path.exists() else text.encode("utf-8")
+        else:
+            pem_data = bytes(source)
+        key = serialization.load_pem_private_key(pem_data, password=None)
+        if not isinstance(key, Ed25519PrivateKey):
+            raise TypeError("Expected an Ed25519 private key")
+        return cls(private_key=key, issuer=issuer, audience=audience, kid=kid)
+
+    @classmethod
+    def generate(
+        cls,
+        *,
+        issuer: str,
+        audience: str,
+        kid: str = "sbn-ed25519",
+    ) -> SigningKey:
+        return cls(
+            private_key=Ed25519PrivateKey.generate(),
+            issuer=issuer,
+            audience=audience,
+            kid=kid,
+        )
+
+    def issue_token(
+        self,
+        *,
+        subject: str,
+        scopes: Sequence[str],
+        cdna: str,
+        ttl_seconds: int,
+        tenant_id: str | None = None,
+        role: str = "agent",
+    ) -> MintedToken:
+        if ttl_seconds <= 0:
+            raise ValueError("ttl_seconds must be positive")
+
+        issued_at = _now_utc()
+        scope_list = sorted({s.strip() for s in scopes if s})
+        header = {"alg": "EdDSA", "typ": "JWT", "kid": self.kid}
+        payload: dict[str, Any] = {
+            "iss": self.issuer,
+            "aud": self.audience,
+            "sub": subject,
+            "role": role,
+            "scope": scope_list,
+            "cdna": cdna,
+            "iat": int(issued_at.timestamp()),
+            "exp": int((issued_at + timedelta(seconds=ttl_seconds)).timestamp()),
+            "jti": uuid.uuid4().hex,
+        }
+        if tenant_id:
+            payload["tenant_id"] = tenant_id
+
+        signing_input = f"{_b64url(_canonical_json(header))}.{_b64url(_canonical_json(payload))}"
+        signature = self.private_key.sign(signing_input.encode("utf-8"))
+        token = f"{signing_input}.{_b64url(signature)}"
+        return MintedToken.from_ttl(token, ttl_seconds)
+
+    def sign_payload(self, data: Mapping[str, Any]) -> str:
+        """Sign arbitrary canonical JSON and return the base64url signature."""
+        canonical = _canonical_json(data)
+        signature = self.private_key.sign(canonical)
+        return _b64url(signature)
+
+    def private_key_pem(self) -> bytes:
+        return self.private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        )