cyberian-client 0.1.0__tar.gz

cyberian_client-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: cyberian-client
+Version: 0.1.0
+Summary: Python client for the Cyberian Systems verified-inference API
+Author-email: Cyberian Systems <philippe@cyberiansystems.ai>
+License: Proprietary
+Project-URL: Homepage, https://cyberiansystems.ai
+Project-URL: Documentation, https://cyberiansystems.ai/docs
+Project-URL: Support, https://cyberiansystems.ai/docs
+Keywords: ai,ml,verified-inference,merkle,embeddings,cyberian
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0,>=0.27.0
+Requires-Dist: numpy<3.0,>=1.26.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# cyberian-client
+
+Python client for the [Cyberian Systems](https://cyberiansystems.ai) verified-inference API.
+
+Each call returns embeddings + a cryptographic receipt that proves an independent prover
+re-executed a sample of your batch and got bitwise-identical results. The receipt is
+self-verifying: any third party can validate it without access to the platform.
+
+## Install
+
+```bash
+pip install cyberian-client
+```
+
+Requires Python 3.9+. Pulls in `httpx` and `numpy`.
+
+## Get an API key
+
+[https://cyberiansystems.ai/signup](https://cyberiansystems.ai/signup) — 14-day free
+trial, no card required. The plaintext key is shown once at signup; save it. We store
+only its SHA-256.
+
+## Quickstart — one shot
+
+```python
+from cyberian import Client
+
+client = Client(api_key="cyb_trial_…")  # or set CYBERIAN_API_KEY in env and pass it in
+
+result = client.submit_and_wait(
+    spec_yaml=open("spec.yaml").read(),
+    input_texts=[
+        "The property title search revealed no encumbrances.",
+        "Quarterly compliance attestation per SOX 404.",
+    ],
+)
+
+print("receipt_hash:", result.receipt["receipt_hash"])
+print("verified:    ", result.verification["valid"])  # True
+print("shape:       ", result.embeddings.shape)        # (2, 384) for BGE-small
+print("first vec:   ", result.embeddings[0, :8])
+```
+
+## Step-by-step — when you need finer control
+
+```python
+job = client.submit_job(spec_yaml="spec.yaml", input_texts=["a", "b", "c"])
+
+# Poll yourself, or use wait_for_completion:
+final = client.wait_for_completion(job["id"], poll_interval_sec=2.0, timeout_sec=600)
+
+receipt      = client.get_receipt(final["receipt_id"])
+verification = client.verify_receipt(final["receipt_id"])
+embeddings   = client.get_job_output(final["id"])  # numpy ndarray, float32
+```
+
+## Verification as a Service (VaaS)
+
+You ran inference on your own infrastructure. Cyberian re-runs it and certifies the
+SHA-256 commitment of your output matches. Useful for compliance — you keep the
+inference, we provide independent auditable verification.
+
+```python
+import hashlib
+
+# Your in-house inference output:
+my_embeddings_bytes = my_pipeline.run(["text"]).astype("float32").tobytes()
+my_commitment = hashlib.sha256(my_embeddings_bytes).hexdigest()
+
+receipt = client.verify_outputs(
+    spec_yaml="spec.yaml",
+    input_texts=["text"],
+    claimed_output_commitment=my_commitment,
+)
+# Raises VerificationFailedError if our prover's re-execution doesn't match yours.
+```
+
+Phase 2: VaaS is single-chunk only — `len(input_texts) <= spec.chunking.chunk_size`.
+
+## Account management
+
+```python
+info = client.get_account()
+print(info["tier"], info["effective_tier"], info["subscription_status"])
+print(info["chunks_consumed_period"], "/", info["limits"]["chunks_per_period"])
+
+# Mint an additional key (old one stays valid until you revoke it)
+new_key = client.rotate_key()
+
+# Revoke a specific key by its 12-char key_id (the prefix shown in /account)
+client.revoke_key(key_id="a1b2c3d4e5f6")
+```
+
+## Error handling
+
+Typed exceptions; catch the most specific one you care about.
+
+```python
+from cyberian import (
+    Client,
+    AuthError,            # 401, 403
+    TrialExpiredError,    # 402 — email upgrade@cyberiansystems.ai
+    QuotaError,           # 402 / 413
+    RateLimitError,       # 429 — has .retry_after_sec
+    ServiceBusyError,     # 503 — has .retry_after_sec
+    JobFailedError,       # job ended in FAILED state during wait_for_completion
+    VerificationFailedError,  # /verify returned valid=False
+    ApiError,             # any other 4xx/5xx
+    CyberianError,        # base of everything above
+)
+
+try:
+    result = client.submit_and_wait(spec_yaml=…, input_texts=[…])
+except RateLimitError as exc:
+    time.sleep(exc.retry_after_sec)
+    result = client.submit_and_wait(spec_yaml=…, input_texts=[…])
+except TrialExpiredError:
+    print("Email upgrade@cyberiansystems.ai for an extension or enterprise tier.")
+    raise
+```
+
+## Trial limits (Phase 2)
+
+| | trial (default) | free (post-trial) |
+|---|---|---|
+| Period | 14 days | 30 days |
+| Chunks per period | 400 | 100 |
+| Chunks per day | 100 | 25 |
+| Requests per minute | 60 | 10 |
+| Max chunks per request | 100 | 50 |
+| Max input texts | 1000 | 500 |
+
+A "chunk" is one ONNX inference unit, sized by your CES `chunking.chunk_size`. With
+`chunk_size: 1` each input text is its own chunk; with `chunk_size: 100` a 1000-text
+batch is 10 chunks. Counting chunks (not requests) means the quota tracks actual
+compute consumption.
+
+## Documentation
+
+- API + SDK reference: <https://cyberiansystems.ai/docs>
+- Trial terms: <https://cyberiansystems.ai/terms>
+- Privacy: <https://cyberiansystems.ai/privacy>
+- Issues / support: support@cyberiansystems.ai
+- Upgrade / enterprise inquiries: upgrade@cyberiansystems.ai
+
+## Patents
+
+The verification mechanism (Canonical Execution Specification, Merkle receipts,
+sample-and-replay verification with game-theoretic deterrence, the four-tuple binding)
+is covered by a U.S. provisional patent. Use of this client does not grant any patent
+license beyond what's needed to call the API as documented.

cyberian_client-0.1.0/README.md

@@ -0,0 +1,151 @@
+# cyberian-client
+
+Python client for the [Cyberian Systems](https://cyberiansystems.ai) verified-inference API.
+
+Each call returns embeddings + a cryptographic receipt that proves an independent prover
+re-executed a sample of your batch and got bitwise-identical results. The receipt is
+self-verifying: any third party can validate it without access to the platform.
+
+## Install
+
+```bash
+pip install cyberian-client
+```
+
+Requires Python 3.9+. Pulls in `httpx` and `numpy`.
+
+## Get an API key
+
+[https://cyberiansystems.ai/signup](https://cyberiansystems.ai/signup) — 14-day free
+trial, no card required. The plaintext key is shown once at signup; save it. We store
+only its SHA-256.
+
+## Quickstart — one shot
+
+```python
+from cyberian import Client
+
+client = Client(api_key="cyb_trial_…")  # or set CYBERIAN_API_KEY in env and pass it in
+
+result = client.submit_and_wait(
+    spec_yaml=open("spec.yaml").read(),
+    input_texts=[
+        "The property title search revealed no encumbrances.",
+        "Quarterly compliance attestation per SOX 404.",
+    ],
+)
+
+print("receipt_hash:", result.receipt["receipt_hash"])
+print("verified:    ", result.verification["valid"])  # True
+print("shape:       ", result.embeddings.shape)        # (2, 384) for BGE-small
+print("first vec:   ", result.embeddings[0, :8])
+```
+
+## Step-by-step — when you need finer control
+
+```python
+job = client.submit_job(spec_yaml="spec.yaml", input_texts=["a", "b", "c"])
+
+# Poll yourself, or use wait_for_completion:
+final = client.wait_for_completion(job["id"], poll_interval_sec=2.0, timeout_sec=600)
+
+receipt      = client.get_receipt(final["receipt_id"])
+verification = client.verify_receipt(final["receipt_id"])
+embeddings   = client.get_job_output(final["id"])  # numpy ndarray, float32
+```
+
+## Verification as a Service (VaaS)
+
+You ran inference on your own infrastructure. Cyberian re-runs it and certifies the
+SHA-256 commitment of your output matches. Useful for compliance — you keep the
+inference, we provide independent auditable verification.
+
+```python
+import hashlib
+
+# Your in-house inference output:
+my_embeddings_bytes = my_pipeline.run(["text"]).astype("float32").tobytes()
+my_commitment = hashlib.sha256(my_embeddings_bytes).hexdigest()
+
+receipt = client.verify_outputs(
+    spec_yaml="spec.yaml",
+    input_texts=["text"],
+    claimed_output_commitment=my_commitment,
+)
+# Raises VerificationFailedError if our prover's re-execution doesn't match yours.
+```
+
+Phase 2: VaaS is single-chunk only — `len(input_texts) <= spec.chunking.chunk_size`.
+
+## Account management
+
+```python
+info = client.get_account()
+print(info["tier"], info["effective_tier"], info["subscription_status"])
+print(info["chunks_consumed_period"], "/", info["limits"]["chunks_per_period"])
+
+# Mint an additional key (old one stays valid until you revoke it)
+new_key = client.rotate_key()
+
+# Revoke a specific key by its 12-char key_id (the prefix shown in /account)
+client.revoke_key(key_id="a1b2c3d4e5f6")
+```
+
+## Error handling
+
+Typed exceptions; catch the most specific one you care about.
+
+```python
+from cyberian import (
+    Client,
+    AuthError,            # 401, 403
+    TrialExpiredError,    # 402 — email upgrade@cyberiansystems.ai
+    QuotaError,           # 402 / 413
+    RateLimitError,       # 429 — has .retry_after_sec
+    ServiceBusyError,     # 503 — has .retry_after_sec
+    JobFailedError,       # job ended in FAILED state during wait_for_completion
+    VerificationFailedError,  # /verify returned valid=False
+    ApiError,             # any other 4xx/5xx
+    CyberianError,        # base of everything above
+)
+
+try:
+    result = client.submit_and_wait(spec_yaml=…, input_texts=[…])
+except RateLimitError as exc:
+    time.sleep(exc.retry_after_sec)
+    result = client.submit_and_wait(spec_yaml=…, input_texts=[…])
+except TrialExpiredError:
+    print("Email upgrade@cyberiansystems.ai for an extension or enterprise tier.")
+    raise
+```
+
+## Trial limits (Phase 2)
+
+| | trial (default) | free (post-trial) |
+|---|---|---|
+| Period | 14 days | 30 days |
+| Chunks per period | 400 | 100 |
+| Chunks per day | 100 | 25 |
+| Requests per minute | 60 | 10 |
+| Max chunks per request | 100 | 50 |
+| Max input texts | 1000 | 500 |
+
+A "chunk" is one ONNX inference unit, sized by your CES `chunking.chunk_size`. With
+`chunk_size: 1` each input text is its own chunk; with `chunk_size: 100` a 1000-text
+batch is 10 chunks. Counting chunks (not requests) means the quota tracks actual
+compute consumption.
+
+## Documentation
+
+- API + SDK reference: <https://cyberiansystems.ai/docs>
+- Trial terms: <https://cyberiansystems.ai/terms>
+- Privacy: <https://cyberiansystems.ai/privacy>
+- Issues / support: support@cyberiansystems.ai
+- Upgrade / enterprise inquiries: upgrade@cyberiansystems.ai
+
+## Patents
+
+The verification mechanism (Canonical Execution Specification, Merkle receipts,
+sample-and-replay verification with game-theoretic deterrence, the four-tuple binding)
+is covered by a U.S. provisional patent. Use of this client does not grant any patent
+license beyond what's needed to call the API as documented.

cyberian_client-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "cyberian-client"
+version = "0.1.0"
+description = "Python client for the Cyberian Systems verified-inference API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "Cyberian Systems", email = "philippe@cyberiansystems.ai" }]
+keywords = ["ai", "ml", "verified-inference", "merkle", "embeddings", "cyberian"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.27.0,<1.0",
+    "numpy>=1.26.0,<3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[project.urls]
+Homepage = "https://cyberiansystems.ai"
+Documentation = "https://cyberiansystems.ai/docs"
+Support = "https://cyberiansystems.ai/docs"
+
+[build-system]
+requires = ["setuptools>=69.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

cyberian_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cyberian_client-0.1.0/src/cyberian/__init__.py

@@ -0,0 +1,30 @@
+"""Cyberian Systems — Python client for the verified-inference API."""
+
+from .client import Client, JobResult
+from .exceptions import (
+    ApiError,
+    AuthError,
+    CyberianError,
+    JobFailedError,
+    QuotaError,
+    RateLimitError,
+    ServiceBusyError,
+    TrialExpiredError,
+    VerificationFailedError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "JobResult",
+    "CyberianError",
+    "AuthError",
+    "TrialExpiredError",
+    "QuotaError",
+    "RateLimitError",
+    "ServiceBusyError",
+    "JobFailedError",
+    "VerificationFailedError",
+    "ApiError",
+]

cyberian_client-0.1.0/src/cyberian/client.py

@@ -0,0 +1,348 @@
+"""
+Cyberian Systems client — Phase 2 SDK.
+
+The Bearer key is the credential. There's no separate login; the key
+is granted by /auth/register (use the /signup page on the website) or
+issued by an operator.
+
+Quick start:
+
+    from cyberian import Client
+
+    c = Client(api_key="cyb_trial_…")
+
+    # One-shot: submit, wait, fetch receipt + outputs
+    result = c.submit_and_wait(
+        spec_yaml=open("spec.yaml").read(),
+        input_texts=["sentence one", "sentence two"],
+    )
+    print(result.receipt["receipt_hash"])
+    print(result.embeddings.shape)  # (2, 384)  for BGE-small
+
+    # Or step-by-step
+    job = c.submit_job(spec_yaml=…, input_texts=[…])
+    final = c.wait_for_completion(job["id"])
+    receipt = c.get_receipt(final["receipt_id"])
+    verification = c.verify_receipt(final["receipt_id"])
+    embeddings = c.get_job_output(final["id"])  # numpy ndarray
+
+    # VaaS — verify a commitment for inference you ran yourself
+    receipt = c.verify_outputs(
+        spec_yaml=…,
+        input_texts=[…],
+        claimed_output_commitment="sha256-hex-of-your-output",
+    )
+
+    # Account info, key management
+    info = c.get_account()
+    new_key = c.rotate_key()
+    c.revoke_key(key_id="abc123def456")
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import httpx
+import numpy as np
+
+from .exceptions import (
+    ApiError,
+    AuthError,
+    CyberianError,
+    JobFailedError,
+    QuotaError,
+    RateLimitError,
+    ServiceBusyError,
+    TrialExpiredError,
+    VerificationFailedError,
+)
+
+DEFAULT_API_URL = "https://api.cyberiansystems.ai"
+
+
+@dataclass
+class JobResult:
+    """Returned by submit_and_wait. Bundles the three things customers
+    most often need at the end of a job: the final job state, the full
+    receipt, and the decoded output embeddings."""
+
+    job: dict[str, Any]
+    receipt: dict[str, Any]
+    embeddings: np.ndarray
+    verification: dict[str, Any] | None = None
+
+
+class Client:
+    """Synchronous Cyberian Systems API client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_API_URL,
+        timeout: float = 60.0,
+        http_client: httpx.Client | None = None,
+    ):
+        if not api_key or not api_key.startswith("cyb_"):
+            raise AuthError(
+                "api_key must be a Cyberian Bearer key (starts with cyb_). "
+                "Mint one via the /signup page or via /auth/register."
+            )
+        self.base_url = base_url.rstrip("/")
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+
+    # ─── core HTTP wrapper ────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        expect_json: bool = True,
+    ) -> Any:
+        try:
+            resp = self._http.request(method, path, json=json)
+        except httpx.RequestError as exc:
+            raise ApiError(f"network error talking to {path}: {exc}") from exc
+
+        if resp.status_code < 400:
+            if not expect_json:
+                return resp
+            if resp.status_code == 204 or not resp.content:
+                return None
+            return resp.json()
+
+        # 4xx/5xx — translate to typed exceptions.
+        try:
+            body = resp.json()
+        except Exception:
+            body = {"raw": resp.text}
+
+        msg = body.get("message") or body.get("error") or f"HTTP {resp.status_code}"
+        retry_after = int(resp.headers.get("retry-after", 0) or 0) or body.get("retry_after_sec", 0)
+
+        if resp.status_code == 401 or resp.status_code == 403:
+            raise AuthError(msg, status_code=resp.status_code, body=body)
+        if resp.status_code == 402:
+            err = (body.get("error") or "").lower()
+            if "trial" in err:
+                raise TrialExpiredError(msg, status_code=402, body=body)
+            raise QuotaError(msg, status_code=402, body=body)
+        if resp.status_code == 413:
+            raise QuotaError(msg, status_code=413, body=body)
+        if resp.status_code == 429:
+            raise RateLimitError(msg, retry_after_sec=retry_after or 60, status_code=429, body=body)
+        if resp.status_code == 503:
+            raise ServiceBusyError(msg, retry_after_sec=retry_after or 30, status_code=503, body=body)
+        raise ApiError(msg, status_code=resp.status_code, body=body)
+
+    # ─── public surface ──────────────────────────────────────────────────
+
+    def health(self) -> dict[str, Any]:
+        """GET /health — connectivity probe; doesn't require auth."""
+        return self._request("GET", "/health")
+
+    def get_account(self) -> dict[str, Any]:
+        """GET /account — tier, trial status, usage, key list."""
+        return self._request("GET", "/account")
+
+    def rotate_key(self) -> str:
+        """POST /auth/keys/rotate — returns the NEW plaintext key. Old key
+        remains valid until you call revoke_key with its key_id."""
+        body = self._request("POST", "/auth/keys/rotate")
+        return body["api_key"]
+
+    def revoke_key(self, *, key_id: str) -> None:
+        """POST /auth/keys/revoke — invalidate the key with the given 12-
+        char key_id prefix. Idempotent."""
+        self._request("POST", "/auth/keys/revoke", json={"key_id": key_id})
+
+    def submit_job(
+        self,
+        *,
+        spec_yaml: str | Path,
+        input_texts: list[str],
+    ) -> dict[str, Any]:
+        """POST /jobs — submit a verified inference batch."""
+        spec_text = _read_spec(spec_yaml)
+        return self._request(
+            "POST",
+            "/jobs",
+            json={"spec_yaml": spec_text, "input_texts": input_texts},
+        )
+
+    def get_job(self, job_id: str) -> dict[str, Any]:
+        """GET /jobs/:id — current job status."""
+        return self._request("GET", f"/jobs/{job_id}")
+
+    def get_job_results(self, job_id: str) -> dict[str, Any]:
+        """GET /jobs/:id/results — per-chunk progress (status, commitments)."""
+        return self._request("GET", f"/jobs/{job_id}/results")
+
+    def get_job_output(self, job_id: str) -> np.ndarray:
+        """GET /jobs/:id/output — decoded float32 embeddings as a 2D ndarray.
+
+        Shape is (total_input_texts, output_dimensions). Only available
+        after the job reaches SETTLED.
+        """
+        resp = self._request("GET", f"/jobs/{job_id}/output", expect_json=False)
+        shape_h = resp.headers.get("x-cyberian-shape", "")
+        try:
+            rows, cols = (int(p.strip()) for p in shape_h.split(","))
+        except Exception as exc:
+            raise ApiError(f"unexpected x-cyberian-shape header: {shape_h!r}") from exc
+        return np.frombuffer(resp.content, dtype=np.float32).reshape(rows, cols)
+
+    def get_receipt(self, receipt_id: str) -> dict[str, Any]:
+        """GET /receipts/:id — full Merkle receipt JSON."""
+        return self._request("GET", f"/receipts/{receipt_id}")
+
+    def verify_receipt(self, receipt_id: str) -> dict[str, Any]:
+        """GET /receipts/:id/verify — coordinator re-verifies the receipt's
+        self-referential hash and the input/output Merkle roots from
+        stored chunk commitments. Returns
+        {valid, checks: {receipt_hash, input_root, output_root, proof_root}, errors}.
+        """
+        return self._request("GET", f"/receipts/{receipt_id}/verify")
+
+    def wait_for_completion(
+        self,
+        job_id: str,
+        *,
+        poll_interval_sec: float = 2.0,
+        timeout_sec: float = 600.0,
+    ) -> dict[str, Any]:
+        """Poll GET /jobs/:id until SETTLED, FAILED, or REFUNDED, or timeout.
+
+        Raises JobFailedError on FAILED. Returns the final job dict.
+        """
+        deadline = time.monotonic() + timeout_sec
+        terminal = {"SETTLED", "FAILED", "REFUNDED"}
+        while True:
+            job = self.get_job(job_id)
+            if job["status"] in terminal:
+                if job["status"] == "FAILED":
+                    raise JobFailedError(job_id, body=job)
+                return job
+            if time.monotonic() > deadline:
+                raise CyberianError(
+                    f"Job {job_id} did not reach a terminal state in {timeout_sec}s "
+                    f"(last status: {job['status']})"
+                )
+            time.sleep(poll_interval_sec)
+
+    def submit_and_wait(
+        self,
+        *,
+        spec_yaml: str | Path,
+        input_texts: list[str],
+        poll_interval_sec: float = 2.0,
+        timeout_sec: float = 600.0,
+        verify_receipt: bool = True,
+    ) -> JobResult:
+        """One-shot helper: submit_job → wait_for_completion → get_receipt
+        → get_job_output → optionally verify_receipt. Most customers will
+        only ever call this method.
+        """
+        job = self.submit_job(spec_yaml=spec_yaml, input_texts=input_texts)
+        final = self.wait_for_completion(
+            job["id"],
+            poll_interval_sec=poll_interval_sec,
+            timeout_sec=timeout_sec,
+        )
+        receipt = self.get_receipt(final["receipt_id"])
+        embeddings = self.get_job_output(final["id"])
+        verification = self.verify_receipt(final["receipt_id"]) if verify_receipt else None
+        if verification and not verification.get("valid", False):
+            raise VerificationFailedError(
+                receipt_id=final["receipt_id"],
+                checks=verification.get("checks", {}),
+                errors=verification.get("errors", []),
+            )
+        return JobResult(
+            job=final,
+            receipt=receipt,
+            embeddings=embeddings,
+            verification=verification,
+        )
+
+    # ─── VaaS ────────────────────────────────────────────────────────────
+
+    def verify_outputs(
+        self,
+        *,
+        spec_yaml: str | Path,
+        input_texts: list[str],
+        claimed_output_commitment: str,
+    ) -> dict[str, Any]:
+        """POST /verify — Verification as a Service. You ran inference on
+        your own infrastructure; we re-execute on ours and confirm your
+        SHA-256 commitment matches.
+
+        Phase 2 supports single-chunk only — input_texts.length must fit
+        in one chunk per the spec's chunk_size.
+
+        Returns the receipt on success (HTTP 200). Raises
+        VerificationFailedError on commitment mismatch (HTTP 422).
+        """
+        spec_text = _read_spec(spec_yaml)
+        try:
+            return self._request(
+                "POST",
+                "/verify",
+                json={
+                    "spec_yaml": spec_text,
+                    "input_texts": input_texts,
+                    "claimed_output_commitment": claimed_output_commitment,
+                },
+            )
+        except ApiError as exc:
+            if exc.status_code == 422:
+                raise VerificationFailedError(
+                    receipt_id="(no receipt issued)",
+                    checks={"output_match": False},
+                    errors=[exc.body.get("reason") if isinstance(exc.body, dict) else str(exc.body)],
+                ) from exc
+            raise
+
+    # ─── lifecycle ───────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+def _read_spec(spec: str | Path) -> str:
+    """Accept either a YAML string or a path to a YAML file."""
+    if isinstance(spec, Path):
+        return spec.read_text()
+    if isinstance(spec, str):
+        # Heuristic: treat as a path if it looks file-y AND the file exists.
+        # Otherwise treat as inline YAML.
+        if "\n" not in spec and len(spec) < 4096:
+            try:
+                p = Path(spec)
+                if p.exists() and p.is_file():
+                    return p.read_text()
+            except (OSError, ValueError):
+                pass
+        return spec
+    raise TypeError(f"spec_yaml must be str or Path, got {type(spec).__name__}")

cyberian_client-0.1.0/src/cyberian/exceptions.py

@@ -0,0 +1,91 @@
+"""
+Exception types raised by the Cyberian Systems client.
+
+Catch hierarchy (most-to-least specific):
+
+    CyberianError                 base
+    ├── AuthError                 401, 403
+    ├── TrialExpiredError         402 trial_expired / quota_exceeded
+    ├── QuotaError                402 quota / 413 request_too_large
+    ├── RateLimitError            429 (any flavor) — has .retry_after_sec
+    ├── ServiceBusyError          503 — has .retry_after_sec
+    ├── JobFailedError            job reached FAILED status during wait
+    ├── VerificationFailedError   /verify returned valid=False
+    └── ApiError                  any other 4xx/5xx
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class CyberianError(Exception):
+    """Base class for all Cyberian client errors."""
+
+    def __init__(self, message: str, *, status_code: int | None = None, body: Any = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class AuthError(CyberianError):
+    """The Bearer key was missing, malformed, invalid, or revoked."""
+
+
+class TrialExpiredError(CyberianError):
+    """The account's trial has ended without an upgrade. Email upgrade@cyberiansystems.ai."""
+
+
+class QuotaError(CyberianError):
+    """A period or per-request quota was exceeded."""
+
+
+class RateLimitError(CyberianError):
+    """The per-minute or daily rate limit was hit. Retry after `retry_after_sec`."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after_sec: int = 60,
+        status_code: int | None = None,
+        body: Any = None,
+    ):
+        super().__init__(message, status_code=status_code, body=body)
+        self.retry_after_sec = retry_after_sec
+
+
+class ServiceBusyError(CyberianError):
+    """The platform is at capacity. Retry after `retry_after_sec`."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after_sec: int = 30,
+        status_code: int | None = None,
+        body: Any = None,
+    ):
+        super().__init__(message, status_code=status_code, body=body)
+        self.retry_after_sec = retry_after_sec
+
+
+class JobFailedError(CyberianError):
+    """A job reached FAILED status during wait_for_completion."""
+
+    def __init__(self, job_id: str, body: Any = None):
+        super().__init__(f"Job {job_id} ended in FAILED state", body=body)
+        self.job_id = job_id
+
+
+class VerificationFailedError(CyberianError):
+    """The receipt's /verify call returned valid=False."""
+
+    def __init__(self, receipt_id: str, checks: dict[str, bool], errors: list[str]):
+        super().__init__(f"Receipt {receipt_id} failed verification: {errors}")
+        self.receipt_id = receipt_id
+        self.checks = checks
+        self.errors = errors
+
+
+class ApiError(CyberianError):
+    """Any other unexpected HTTP error from the API."""

cyberian_client-0.1.0/src/cyberian_client.egg-info/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: cyberian-client
+Version: 0.1.0
+Summary: Python client for the Cyberian Systems verified-inference API
+Author-email: Cyberian Systems <philippe@cyberiansystems.ai>
+License: Proprietary
+Project-URL: Homepage, https://cyberiansystems.ai
+Project-URL: Documentation, https://cyberiansystems.ai/docs
+Project-URL: Support, https://cyberiansystems.ai/docs
+Keywords: ai,ml,verified-inference,merkle,embeddings,cyberian
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0,>=0.27.0
+Requires-Dist: numpy<3.0,>=1.26.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# cyberian-client
+
+Python client for the [Cyberian Systems](https://cyberiansystems.ai) verified-inference API.
+
+Each call returns embeddings + a cryptographic receipt that proves an independent prover
+re-executed a sample of your batch and got bitwise-identical results. The receipt is
+self-verifying: any third party can validate it without access to the platform.
+
+## Install
+
+```bash
+pip install cyberian-client
+```
+
+Requires Python 3.9+. Pulls in `httpx` and `numpy`.
+
+## Get an API key
+
+[https://cyberiansystems.ai/signup](https://cyberiansystems.ai/signup) — 14-day free
+trial, no card required. The plaintext key is shown once at signup; save it. We store
+only its SHA-256.
+
+## Quickstart — one shot
+
+```python
+from cyberian import Client
+
+client = Client(api_key="cyb_trial_…")  # or set CYBERIAN_API_KEY in env and pass it in
+
+result = client.submit_and_wait(
+    spec_yaml=open("spec.yaml").read(),
+    input_texts=[
+        "The property title search revealed no encumbrances.",
+        "Quarterly compliance attestation per SOX 404.",
+    ],
+)
+
+print("receipt_hash:", result.receipt["receipt_hash"])
+print("verified:    ", result.verification["valid"])  # True
+print("shape:       ", result.embeddings.shape)        # (2, 384) for BGE-small
+print("first vec:   ", result.embeddings[0, :8])
+```
+
+## Step-by-step — when you need finer control
+
+```python
+job = client.submit_job(spec_yaml="spec.yaml", input_texts=["a", "b", "c"])
+
+# Poll yourself, or use wait_for_completion:
+final = client.wait_for_completion(job["id"], poll_interval_sec=2.0, timeout_sec=600)
+
+receipt      = client.get_receipt(final["receipt_id"])
+verification = client.verify_receipt(final["receipt_id"])
+embeddings   = client.get_job_output(final["id"])  # numpy ndarray, float32
+```
+
+## Verification as a Service (VaaS)
+
+You ran inference on your own infrastructure. Cyberian re-runs it and certifies the
+SHA-256 commitment of your output matches. Useful for compliance — you keep the
+inference, we provide independent auditable verification.
+
+```python
+import hashlib
+
+# Your in-house inference output:
+my_embeddings_bytes = my_pipeline.run(["text"]).astype("float32").tobytes()
+my_commitment = hashlib.sha256(my_embeddings_bytes).hexdigest()
+
+receipt = client.verify_outputs(
+    spec_yaml="spec.yaml",
+    input_texts=["text"],
+    claimed_output_commitment=my_commitment,
+)
+# Raises VerificationFailedError if our prover's re-execution doesn't match yours.
+```
+
+Phase 2: VaaS is single-chunk only — `len(input_texts) <= spec.chunking.chunk_size`.
+
+## Account management
+
+```python
+info = client.get_account()
+print(info["tier"], info["effective_tier"], info["subscription_status"])
+print(info["chunks_consumed_period"], "/", info["limits"]["chunks_per_period"])
+
+# Mint an additional key (old one stays valid until you revoke it)
+new_key = client.rotate_key()
+
+# Revoke a specific key by its 12-char key_id (the prefix shown in /account)
+client.revoke_key(key_id="a1b2c3d4e5f6")
+```
+
+## Error handling
+
+Typed exceptions; catch the most specific one you care about.
+
+```python
+from cyberian import (
+    Client,
+    AuthError,            # 401, 403
+    TrialExpiredError,    # 402 — email upgrade@cyberiansystems.ai
+    QuotaError,           # 402 / 413
+    RateLimitError,       # 429 — has .retry_after_sec
+    ServiceBusyError,     # 503 — has .retry_after_sec
+    JobFailedError,       # job ended in FAILED state during wait_for_completion
+    VerificationFailedError,  # /verify returned valid=False
+    ApiError,             # any other 4xx/5xx
+    CyberianError,        # base of everything above
+)
+
+try:
+    result = client.submit_and_wait(spec_yaml=…, input_texts=[…])
+except RateLimitError as exc:
+    time.sleep(exc.retry_after_sec)
+    result = client.submit_and_wait(spec_yaml=…, input_texts=[…])
+except TrialExpiredError:
+    print("Email upgrade@cyberiansystems.ai for an extension or enterprise tier.")
+    raise
+```
+
+## Trial limits (Phase 2)
+
+| | trial (default) | free (post-trial) |
+|---|---|---|
+| Period | 14 days | 30 days |
+| Chunks per period | 400 | 100 |
+| Chunks per day | 100 | 25 |
+| Requests per minute | 60 | 10 |
+| Max chunks per request | 100 | 50 |
+| Max input texts | 1000 | 500 |
+
+A "chunk" is one ONNX inference unit, sized by your CES `chunking.chunk_size`. With
+`chunk_size: 1` each input text is its own chunk; with `chunk_size: 100` a 1000-text
+batch is 10 chunks. Counting chunks (not requests) means the quota tracks actual
+compute consumption.
+
+## Documentation
+
+- API + SDK reference: <https://cyberiansystems.ai/docs>
+- Trial terms: <https://cyberiansystems.ai/terms>
+- Privacy: <https://cyberiansystems.ai/privacy>
+- Issues / support: support@cyberiansystems.ai
+- Upgrade / enterprise inquiries: upgrade@cyberiansystems.ai
+
+## Patents
+
+The verification mechanism (Canonical Execution Specification, Merkle receipts,
+sample-and-replay verification with game-theoretic deterrence, the four-tuple binding)
+is covered by a U.S. provisional patent. Use of this client does not grant any patent
+license beyond what's needed to call the API as documented.

cyberian_client-0.1.0/src/cyberian_client.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/cyberian/__init__.py
+src/cyberian/client.py
+src/cyberian/exceptions.py
+src/cyberian_client.egg-info/PKG-INFO
+src/cyberian_client.egg-info/SOURCES.txt
+src/cyberian_client.egg-info/dependency_links.txt
+src/cyberian_client.egg-info/requires.txt
+src/cyberian_client.egg-info/top_level.txt
+tests/test_client.py

cyberian_client-0.1.0/src/cyberian_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cyberian_client-0.1.0/src/cyberian_client.egg-info/requires.txt

@@ -0,0 +1,6 @@
+httpx<1.0,>=0.27.0
+numpy<3.0,>=1.26.0
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.23

cyberian_client-0.1.0/src/cyberian_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+cyberian

cyberian_client-0.1.0/tests/test_client.py

@@ -0,0 +1,197 @@
+"""
+Smoke tests for the Cyberian Client.
+
+Uses httpx.MockTransport to fake the API. We're not testing the
+coordinator's logic here (the TS test suite owns that) — just that
+the client constructs the right requests and parses the right
+responses.
+"""
+from __future__ import annotations
+
+import json
+
+import httpx
+import numpy as np
+import pytest
+
+from cyberian import (
+    ApiError,
+    AuthError,
+    Client,
+    JobFailedError,
+    QuotaError,
+    RateLimitError,
+    ServiceBusyError,
+    TrialExpiredError,
+    VerificationFailedError,
+)
+
+
+def make_client(handler):
+    transport = httpx.MockTransport(handler)
+    http = httpx.Client(
+        base_url="https://api.test",
+        transport=transport,
+        headers={"Authorization": "Bearer cyb_test_" + "a" * 32, "Content-Type": "application/json"},
+    )
+    return Client(api_key="cyb_test_" + "a" * 32, base_url="https://api.test", http_client=http)
+
+
+def test_client_rejects_non_cyb_key():
+    with pytest.raises(AuthError):
+        Client(api_key="not-a-cyberian-key")
+
+
+def test_health():
+    def handler(req):
+        assert req.url.path == "/health"
+        return httpx.Response(200, json={"ok": True, "service": "coordinator"})
+
+    c = make_client(handler)
+    assert c.health() == {"ok": True, "service": "coordinator"}
+
+
+def test_get_account():
+    def handler(req):
+        assert req.url.path == "/account"
+        assert req.headers["authorization"].startswith("Bearer cyb_test_")
+        return httpx.Response(200, json={"tier": "free", "subscription_status": "trial"})
+
+    c = make_client(handler)
+    info = c.get_account()
+    assert info["tier"] == "free"
+
+
+def test_submit_job_serializes_body():
+    captured = {}
+
+    def handler(req):
+        captured["body"] = json.loads(req.content)
+        return httpx.Response(201, json={"id": "abc-123", "status": "EXECUTING"})
+
+    c = make_client(handler)
+    out = c.submit_job(spec_yaml="version: 1.0", input_texts=["a", "b"])
+    assert out["id"] == "abc-123"
+    assert captured["body"] == {"spec_yaml": "version: 1.0", "input_texts": ["a", "b"]}
+
+
+def test_get_job_output_decodes_to_ndarray():
+    # Pretend the server returned 6 floats = 3 rows × 2 cols.
+    raw = np.array([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]], dtype=np.float32).tobytes()
+
+    def handler(req):
+        assert req.url.path == "/jobs/job-99/output"
+        return httpx.Response(
+            200,
+            content=raw,
+            headers={
+                "x-cyberian-shape": "3,2",
+                "x-cyberian-dtype": "float32",
+                "content-type": "application/octet-stream",
+            },
+        )
+
+    c = make_client(handler)
+    arr = c.get_job_output("job-99")
+    assert arr.shape == (3, 2)
+    assert arr.dtype == np.float32
+    assert arr[1, 0] == 3.0
+
+
+def test_wait_for_completion_terminates_on_settled():
+    seq = iter(["EXECUTING", "PROVING", "SETTLED"])
+
+    def handler(req):
+        return httpx.Response(200, json={"id": "j", "status": next(seq), "receipt_id": "r"})
+
+    c = make_client(handler)
+    final = c.wait_for_completion("j", poll_interval_sec=0.001, timeout_sec=2.0)
+    assert final["status"] == "SETTLED"
+
+
+def test_wait_for_completion_raises_on_failed():
+    def handler(req):
+        return httpx.Response(200, json={"id": "j", "status": "FAILED"})
+
+    c = make_client(handler)
+    with pytest.raises(JobFailedError):
+        c.wait_for_completion("j", poll_interval_sec=0.001, timeout_sec=2.0)
+
+
+def test_402_trial_expired_raises_typed():
+    def handler(req):
+        return httpx.Response(
+            402,
+            json={"error": "trial_expired", "message": "Your trial has ended"},
+        )
+
+    c = make_client(handler)
+    with pytest.raises(TrialExpiredError):
+        c.submit_job(spec_yaml="x", input_texts=["a"])
+
+
+def test_402_quota_raises_quota_error():
+    def handler(req):
+        return httpx.Response(402, json={"error": "quota_exceeded", "message": "out of chunks"})
+
+    c = make_client(handler)
+    with pytest.raises(QuotaError):
+        c.submit_job(spec_yaml="x", input_texts=["a"])
+
+
+def test_413_oversize_raises_quota_error():
+    def handler(req):
+        return httpx.Response(413, json={"error": "request_too_large"})
+
+    c = make_client(handler)
+    with pytest.raises(QuotaError):
+        c.submit_job(spec_yaml="x", input_texts=["a"])
+
+
+def test_429_rate_limited_carries_retry_after():
+    def handler(req):
+        return httpx.Response(
+            429,
+            headers={"retry-after": "42"},
+            json={"error": "rate_limited"},
+        )
+
+    c = make_client(handler)
+    with pytest.raises(RateLimitError) as ei:
+        c.submit_job(spec_yaml="x", input_texts=["a"])
+    assert ei.value.retry_after_sec == 42
+
+
+def test_503_busy_carries_retry_after():
+    def handler(req):
+        return httpx.Response(
+            503,
+            headers={"retry-after": "20"},
+            json={"error": "service_busy"},
+        )
+
+    c = make_client(handler)
+    with pytest.raises(ServiceBusyError) as ei:
+        c.submit_job(spec_yaml="x", input_texts=["a"])
+    assert ei.value.retry_after_sec == 20
+
+
+def test_verify_outputs_422_raises_verification_failed():
+    def handler(req):
+        return httpx.Response(
+            422,
+            json={"error": "verification_failed", "reason": "commitments differ"},
+        )
+
+    c = make_client(handler)
+    with pytest.raises(VerificationFailedError):
+        c.verify_outputs(spec_yaml="x", input_texts=["a"], claimed_output_commitment="0" * 64)
+
+
+def test_unknown_error_falls_through_to_apierror():
+    def handler(req):
+        return httpx.Response(418, json={"error": "i_am_a_teapot"})
+
+    c = make_client(handler)
+    with pytest.raises(ApiError):
+        c.submit_job(spec_yaml="x", input_texts=["a"])