zkai 0.5.0__tar.gz

zkai-0.5.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: zkai
+Version: 0.5.0
+Summary: Private, verifiable AI inference on 0G chain — drop-in OpenAI-compatible SDK
+Author-email: ZKai <team@zkai.network>
+License: MIT
+Project-URL: Homepage, https://zkai-ether-og.vercel.app
+Project-URL: Repository, https://github.com/skyyycodes/zkai-eth
+Project-URL: Issues, https://github.com/skyyycodes/zkai-eth/issues
+Keywords: ai,inference,openai,llm,tee,tdx,attestation,blockchain,0g,verifiable,privacy,encryption
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=43.0
+Requires-Dist: requests>=2.32
+Requires-Dist: pydantic>=2.9
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+
+# zkai
+
+OpenAI-compatible Python SDK for [ZKai](https://zkai-ether-og.vercel.app) — private, verifiable AI inference on 0G chain.
+
+ZKai sends your prompt through a Trusted Execution Environment (Intel TDX), encrypts it client-side so even the gateway cannot read it, and anchors a SHA-256 attestation of every inference on the 0G chain. You get back a normal OpenAI-style response plus an on-chain receipt.
+
+## Install
+
+```bash
+pip install zkai
+```
+
+Optional LangChain adapter:
+
+```bash
+pip install "zkai[langchain]"
+```
+
+## Quick start
+
+```python
+from zkai import ZKai
+
+client = ZKai(api_key="zkai-...")  # get one at https://zkai-ether-og.vercel.app
+
+response = client.chat.completions.create(
+    model="qwen2.5:1.5b",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+print(response.choices[0].message.content)
+print("Attestation hash:", response.attestation_hash)
+```
+
+The response is decrypted locally — the gateway sees only ciphertext.
+The attestation hash is anchored on 0G mainnet and can be verified independently.
+
+## How it works (gateway mode, default)
+
+1. The SDK fetches the enclave's X25519 public key from the gateway.
+2. It encrypts your prompt locally with ECDH + ChaCha20-Poly1305.
+3. It sends only the ciphertext to the gateway.
+4. The gateway routes the opaque blob to a TDX-sealed enclave running the requested model.
+5. The enclave decrypts inside sealed memory, runs the model, encrypts the response, and emits a SHA-256 attestation hash.
+6. The attestation lands on the on-chain `AttestationRegistry` contract.
+7. The SDK decrypts the response locally and returns it to you.
+
+End-to-end, the gateway never sees plaintext.
+
+## Configuration
+
+```python
+ZKai(
+    api_key="zkai-...",                             # issued from the dashboard
+    base_url="https://zkai-ether-og.vercel.app",    # default
+    encrypted=True,                                  # default; set False to use the legacy plaintext path
+    provider_endpoint=None,                          # set to bypass gateway and hit a provider directly
+    skip_attestation=False,                          # only for development; do not disable in prod
+)
+```
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | `str | None` | `None` | Sent as `X-API-Key`. Required for the hosted gateway. |
+| `base_url` | `str | None` | `https://zkai-ether-og.vercel.app` | Override to point at a self-hosted gateway. |
+| `encrypted` | `bool` | `True` | When `True`, prompts are encrypted client-side. Set `False` for legacy clients. |
+| `provider_endpoint` | `str | None` | `None` | When set, bypasses the gateway and talks directly to a provider's `/infer` endpoint. |
+| `skip_attestation` | `bool` | `False` | Disables attestation verification. Useful only for dev loops. |
+
+## OpenAI compatibility
+
+The response object mirrors OpenAI's chat completion shape:
+
+```python
+response.id
+response.model
+response.choices[0].message.content
+response.choices[0].finish_reason
+response.usage.prompt_tokens
+response.usage.completion_tokens
+
+# ZKai-specific:
+response.attestation_hash  # on-chain commitment
+```
+
+Drop-in replacement for most OpenAI SDK call sites — just swap the client class.
+
+## On-chain components (0G mainnet, chain ID 16661)
+
+| Contract | Address |
+|---|---|
+| ProviderRegistry | `0x6D400F5D1DcCaA3e98E3dE17322aA23DE38bAC99` |
+| PaymentEscrow | `0xb2C7c0F7a4C2877319E8Ed1Fae0bf3C705b6Fc4C` |
+| AttestationRegistry | `0x8c8Ae0A113084268D181fd1cf23d611DC2EAa2B2` |
+
+Verify any attestation hash on the [0G explorer](https://chainscan.0g.ai).
+
+## Running your own provider
+
+See the companion [`zkai-cli`](https://pypi.org/project/zkai-cli/) package:
+
+```bash
+pip install zkai-cli
+zkai init && zkai start && zkai register
+```
+
+## Links
+
+- Dashboard — https://zkai-ether-og.vercel.app
+- Repository — https://github.com/skyyycodes/zkai-eth
+- Provider CLI — https://pypi.org/project/zkai-cli/
+
+## License
+
+MIT

zkai-0.5.0/README.md

@@ -0,0 +1,115 @@
+# zkai
+
+OpenAI-compatible Python SDK for [ZKai](https://zkai-ether-og.vercel.app) — private, verifiable AI inference on 0G chain.
+
+ZKai sends your prompt through a Trusted Execution Environment (Intel TDX), encrypts it client-side so even the gateway cannot read it, and anchors a SHA-256 attestation of every inference on the 0G chain. You get back a normal OpenAI-style response plus an on-chain receipt.
+
+## Install
+
+```bash
+pip install zkai
+```
+
+Optional LangChain adapter:
+
+```bash
+pip install "zkai[langchain]"
+```
+
+## Quick start
+
+```python
+from zkai import ZKai
+
+client = ZKai(api_key="zkai-...")  # get one at https://zkai-ether-og.vercel.app
+
+response = client.chat.completions.create(
+    model="qwen2.5:1.5b",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+print(response.choices[0].message.content)
+print("Attestation hash:", response.attestation_hash)
+```
+
+The response is decrypted locally — the gateway sees only ciphertext.
+The attestation hash is anchored on 0G mainnet and can be verified independently.
+
+## How it works (gateway mode, default)
+
+1. The SDK fetches the enclave's X25519 public key from the gateway.
+2. It encrypts your prompt locally with ECDH + ChaCha20-Poly1305.
+3. It sends only the ciphertext to the gateway.
+4. The gateway routes the opaque blob to a TDX-sealed enclave running the requested model.
+5. The enclave decrypts inside sealed memory, runs the model, encrypts the response, and emits a SHA-256 attestation hash.
+6. The attestation lands on the on-chain `AttestationRegistry` contract.
+7. The SDK decrypts the response locally and returns it to you.
+
+End-to-end, the gateway never sees plaintext.
+
+## Configuration
+
+```python
+ZKai(
+    api_key="zkai-...",                             # issued from the dashboard
+    base_url="https://zkai-ether-og.vercel.app",    # default
+    encrypted=True,                                  # default; set False to use the legacy plaintext path
+    provider_endpoint=None,                          # set to bypass gateway and hit a provider directly
+    skip_attestation=False,                          # only for development; do not disable in prod
+)
+```
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | `str | None` | `None` | Sent as `X-API-Key`. Required for the hosted gateway. |
+| `base_url` | `str | None` | `https://zkai-ether-og.vercel.app` | Override to point at a self-hosted gateway. |
+| `encrypted` | `bool` | `True` | When `True`, prompts are encrypted client-side. Set `False` for legacy clients. |
+| `provider_endpoint` | `str | None` | `None` | When set, bypasses the gateway and talks directly to a provider's `/infer` endpoint. |
+| `skip_attestation` | `bool` | `False` | Disables attestation verification. Useful only for dev loops. |
+
+## OpenAI compatibility
+
+The response object mirrors OpenAI's chat completion shape:
+
+```python
+response.id
+response.model
+response.choices[0].message.content
+response.choices[0].finish_reason
+response.usage.prompt_tokens
+response.usage.completion_tokens
+
+# ZKai-specific:
+response.attestation_hash  # on-chain commitment
+```
+
+Drop-in replacement for most OpenAI SDK call sites — just swap the client class.
+
+## On-chain components (0G mainnet, chain ID 16661)
+
+| Contract | Address |
+|---|---|
+| ProviderRegistry | `0x6D400F5D1DcCaA3e98E3dE17322aA23DE38bAC99` |
+| PaymentEscrow | `0xb2C7c0F7a4C2877319E8Ed1Fae0bf3C705b6Fc4C` |
+| AttestationRegistry | `0x8c8Ae0A113084268D181fd1cf23d611DC2EAa2B2` |
+
+Verify any attestation hash on the [0G explorer](https://chainscan.0g.ai).
+
+## Running your own provider
+
+See the companion [`zkai-cli`](https://pypi.org/project/zkai-cli/) package:
+
+```bash
+pip install zkai-cli
+zkai init && zkai start && zkai register
+```
+
+## Links
+
+- Dashboard — https://zkai-ether-og.vercel.app
+- Repository — https://github.com/skyyycodes/zkai-eth
+- Provider CLI — https://pypi.org/project/zkai-cli/
+
+## License
+
+MIT

zkai-0.5.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zkai"
+version = "0.5.0"
+description = "Private, verifiable AI inference on 0G chain — drop-in OpenAI-compatible SDK"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "ZKai", email = "team@zkai.network" },
+]
+keywords = [
+    "ai", "inference", "openai", "llm", "tee", "tdx", "attestation",
+    "blockchain", "0g", "verifiable", "privacy", "encryption",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "cryptography>=43.0",
+    "requests>=2.32",
+    "pydantic>=2.9",
+]
+
+[project.optional-dependencies]
+langchain = [
+    "langchain-core>=0.3",
+]
+
+[project.urls]
+Homepage = "https://zkai-ether-og.vercel.app"
+Repository = "https://github.com/skyyycodes/zkai-eth"
+Issues = "https://github.com/skyyycodes/zkai-eth/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["zkai*"]
+exclude = ["zkai.egg-info*"]

zkai-0.5.0/setup.cfg

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

zkai-0.5.0/zkai/__init__.py

@@ -0,0 +1,10 @@
+from .client import ZKai, ChatCompletion, ZKaiAuthError
+from .attestation import ZKaiAttestationError
+
+def __getattr__(name):
+    if name == "ChatZKai":
+        from .langchain import ChatZKai
+        return ChatZKai
+    raise AttributeError(f"module 'zkai' has no attribute {name!r}")
+
+__all__ = ["ZKai", "ChatCompletion", "ZKaiAuthError", "ZKaiAttestationError", "ChatZKai"]

zkai-0.5.0/zkai/attestation.py

@@ -0,0 +1,102 @@
+"""
+Attestation verification.
+SDK calls this silently after every inference — user never thinks about it.
+"""
+
+import hashlib
+import json
+import requests
+
+INDEXER_URL = "https://indexer.preprod.midnight.network/api/v3/graphql"
+
+
+class ZKaiAttestationError(Exception):
+    pass
+
+
+def verify(
+    provider_url: str,
+    received_attestation_hash: str,
+    on_chain_hash: str | None = None,
+    attestation_contract: str | None = None,
+    job_id: str | None = None,
+):
+    """
+    Fetch attestation from provider, hash it, compare to:
+    1. The hash included in the /infer response
+    2. The hash anchored on-chain (if attestation_contract + job_id provided)
+
+    Raises ZKaiAttestationError if anything doesn't match.
+    """
+    resp = requests.get(f"{provider_url}/attestation", timeout=10)
+    resp.raise_for_status()
+    attestation = resp.json()
+
+    # Recompute hash of the report (excluding the hash field itself)
+    report_copy = {k: v for k, v in attestation.items() if k not in ("report_hash", "signature")}
+    report_bytes = json.dumps(report_copy, sort_keys=True).encode()
+    computed_hash = hashlib.sha256(report_bytes).hexdigest()
+
+    if computed_hash != received_attestation_hash:
+        raise ZKaiAttestationError(
+            f"Attestation hash mismatch.\n"
+            f"  From provider response: {received_attestation_hash}\n"
+            f"  Recomputed:             {computed_hash}\n"
+            f"  Provider may have tampered with the report."
+        )
+
+    # Fetch on-chain hash if not provided directly
+    if on_chain_hash is None and attestation_contract and job_id:
+        on_chain_hash = _fetch_on_chain_hash(attestation_contract, job_id)
+
+    if on_chain_hash and computed_hash != on_chain_hash:
+        raise ZKaiAttestationError(
+            f"Attestation does not match on-chain anchor.\n"
+            f"  On-chain:   {on_chain_hash}\n"
+            f"  Computed:   {computed_hash}\n"
+            f"  Model hash: {attestation.get('model_hash', 'unknown')}\n"
+            f"  Possible tampered model or manifest."
+        )
+
+    return attestation
+
+
+def _fetch_on_chain_hash(attestation_contract: str, job_id: str) -> str | None:
+    """Query Midnight indexer for the attestation hash stored for a given job_id."""
+    query = """
+    query GetAttestation($address: String!) {
+      contract(address: $address) {
+        state {
+          ... on ContractState {
+            ledger {
+              ... on ZkaiAttestationRegistryLedger {
+                att_hash { entries { key value } }
+              }
+            }
+          }
+        }
+      }
+    }
+    """
+    try:
+        resp = requests.post(
+            INDEXER_URL,
+            json={"query": query, "variables": {"address": attestation_contract}},
+            timeout=15,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        entries = (
+            data.get("data", {})
+            .get("contract", {})
+            .get("state", {})
+            .get("ledger", {})
+            .get("att_hash", {})
+            .get("entries", [])
+        )
+        for entry in entries:
+            if entry["key"] == job_id:
+                return entry["value"]
+        return None
+    except Exception:
+        return None

zkai-0.5.0/zkai/bridge.py

@@ -0,0 +1,28 @@
+"""
+HTTP client for the ZKai bridge server (Node.js).
+The bridge holds the Midnight wallet and translates Python calls into on-chain transactions.
+"""
+
+import requests
+
+
+class BridgeClient:
+    def __init__(self, base_url: str = "http://localhost:7300"):
+        self.base_url = base_url.rstrip("/")
+
+    def call(self, path: str, payload: dict) -> dict:
+        resp = requests.post(
+            f"{self.base_url}{path}",
+            json=payload,
+            timeout=120,  # ZK proofs can take 30-60s
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        if "error" in data:
+            raise RuntimeError(f"Bridge error on {path}: {data['error']}")
+        return data
+
+    def health(self) -> dict:
+        resp = requests.get(f"{self.base_url}/health", timeout=10)
+        resp.raise_for_status()
+        return resp.json()

zkai-0.5.0/zkai/client.py

@@ -0,0 +1,286 @@
+"""
+ZKai client — OpenAI-compatible interface with end-to-end encryption.
+
+Modes:
+  - Encrypted gateway (default): prompt encrypted client-side with the
+    enclave's X25519 pubkey; gateway sees only ciphertext.
+  - Plain gateway: legacy fallback for compatibility.
+  - Direct provider: bypass gateway entirely.
+
+Change 2 lines, everything else stays the same.
+"""
+
+import requests
+from dataclasses import dataclass, field
+
+from . import crypto, provider as provider_mod, attestation as att_mod
+from .attestation import ZKaiAttestationError
+
+# Default gateway — consumers send requests here, gateway picks a provider
+GATEWAY_URL = "https://zkai-ether-og.vercel.app"
+
+
+# ── OpenAI-compatible response types ────────────────────────────────────────
+
+@dataclass
+class Message:
+    role: str
+    content: str
+
+
+@dataclass
+class Choice:
+    index: int
+    message: Message
+    finish_reason: str = "stop"
+
+
+@dataclass
+class ChatCompletion:
+    id: str
+    object: str
+    model: str
+    choices: list[Choice]
+    usage: dict = field(default_factory=dict)
+    attestation_hash: str | None = None
+
+
+# ── Main client ──────────────────────────────────────────────────────────────
+
+class ZKai:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        # legacy / advanced: bypass gateway and talk to a provider directly
+        provider_endpoint: str | None = None,
+        max_price: float | None = None,
+        min_reputation: float = 0.0,
+        registry_contract: str | None = None,
+        attestation_contract: str | None = None,
+        skip_attestation: bool = False,
+        # End-to-end encryption via gateway (default ON). Set False to use
+        # the legacy plaintext-to-gateway path.
+        encrypted: bool = True,
+    ):
+        self._api_key = api_key
+        self._base_url = (base_url or GATEWAY_URL).rstrip("/")
+        self._provider_endpoint = provider_endpoint
+        self._max_price = max_price
+        self._min_reputation = min_reputation
+        self._registry_contract = registry_contract
+        self._attestation_contract = attestation_contract
+        self._skip_attestation = skip_attestation
+        self._encrypted = encrypted
+        self.chat = _Chat(self)
+
+    def _infer(self, model: str, messages: list[dict]) -> ChatCompletion:
+        if self._provider_endpoint:
+            return self._infer_direct(model, messages)
+        if self._encrypted:
+            return self._infer_via_gateway_encrypted(model, messages)
+        return self._infer_via_gateway_plain(model, messages)
+
+    # ── Encrypted gateway path (default) ─────────────────────────────────────
+
+    def _infer_via_gateway_encrypted(self, model: str, messages: list[dict]) -> ChatCompletion:
+        """
+        End-to-end encrypted via the ZKai gateway.
+
+        Flow:
+          1. GET  /api/providers/pubkey?model=...  → enclave pubkey + provider_id
+          2. Generate ephemeral X25519 keypair locally
+          3. Encrypt prompt with ECDH(ephemeral_priv, enclave_pub) → ciphertext
+          4. POST /api/v1/encrypted-chat  with { provider_id, client_pubkey, encrypted_prompt }
+          5. Decrypt response with ECDH(ephemeral_priv, enclave_pub)
+
+        Gateway never sees plaintext.
+        """
+        headers = {"Content-Type": "application/json"}
+        if self._api_key:
+            headers["X-API-Key"] = self._api_key
+
+        # 1. Fetch enclave pubkey for this model
+        pk_resp = requests.get(
+            f"{self._base_url}/api/providers/pubkey",
+            params={"model": model},
+            headers=headers,
+            timeout=15,
+        )
+        if pk_resp.status_code == 503:
+            raise ZKaiNoProviderError("No providers available for this model.")
+        pk_resp.raise_for_status()
+        pk_data = pk_resp.json()
+        enclave_pubkey = pk_data["pubkey"]
+        provider_id = pk_data["provider_id"]
+
+        # 2-3. Generate ephemeral keypair + encrypt
+        prompt = _messages_to_prompt(messages)
+        our_priv, our_pub = crypto.generate_keypair()
+        encrypted_prompt = crypto.encrypt(prompt, enclave_pubkey, our_priv)
+
+        # 4. Send encrypted blob via gateway
+        resp = requests.post(
+            f"{self._base_url}/api/v1/encrypted-chat",
+            json={
+                "provider_id": provider_id,
+                "client_pubkey": our_pub,
+                "encrypted_prompt": encrypted_prompt,
+                "model": model,
+            },
+            headers=headers,
+            timeout=120,
+        )
+        if resp.status_code == 401:
+            raise ZKaiAuthError("Invalid or missing API key. Get one at https://zkai-ether-og.vercel.app")
+        if resp.status_code == 503:
+            raise ZKaiNoProviderError("No providers available for this model.")
+        resp.raise_for_status()
+        data = resp.json()
+
+        # 5. Decrypt response locally
+        response_text = crypto.decrypt(data["encrypted_response"], enclave_pubkey, our_priv)
+        token_count = len(response_text.split())
+
+        return ChatCompletion(
+            id=f"zkai-{data['job_id'][:8]}",
+            object="chat.completion",
+            model=model,
+            choices=[Choice(
+                index=0,
+                message=Message(role="assistant", content=response_text),
+                finish_reason="stop",
+            )],
+            usage={"prompt_tokens": len(prompt.split()), "completion_tokens": token_count},
+            attestation_hash=data.get("attestation_hash"),
+        )
+
+    # ── Plain gateway path (legacy) ──────────────────────────────────────────
+
+    def _infer_via_gateway_plain(self, model: str, messages: list[dict]) -> ChatCompletion:
+        """Send plaintext request to the ZKai gateway (legacy)."""
+        headers = {"Content-Type": "application/json"}
+        if self._api_key:
+            headers["X-API-Key"] = self._api_key
+
+        resp = requests.post(
+            f"{self._base_url}/api/v1/chat/completions",
+            json={"model": model, "messages": messages},
+            headers=headers,
+            timeout=120,
+        )
+        if resp.status_code == 401:
+            raise ZKaiAuthError("Invalid or missing API key.")
+        if resp.status_code == 503:
+            raise ZKaiNoProviderError("No providers available for this model.")
+        resp.raise_for_status()
+        data = resp.json()
+
+        choice = data["choices"][0]
+        xz = data.get("x_zkai", {})
+        return ChatCompletion(
+            id=data.get("id", "zkai-gateway"),
+            object="chat.completion",
+            model=data.get("model", model),
+            choices=[Choice(
+                index=0,
+                message=Message(role="assistant", content=choice["message"]["content"]),
+                finish_reason=choice.get("finish_reason", "stop"),
+            )],
+            usage=data.get("usage", {}),
+            attestation_hash=xz.get("attestation_hash"),
+        )
+
+    # ── Direct provider path (advanced) ──────────────────────────────────────
+
+    def _infer_direct(self, model: str, messages: list[dict]) -> ChatCompletion:
+        """Bypass gateway — encrypt and send directly to a provider enclave."""
+        prompt = _messages_to_prompt(messages)
+
+        p = provider_mod.Provider(
+            id="direct",
+            endpoint=self._provider_endpoint,
+            pubkey="",
+            model=model,
+            price_per_token=0.0,
+            reputation=1.0,
+            stake=0.0,
+        )
+
+        tee_pubkey = provider_mod.fetch_pubkey(p)
+        our_private, our_public = crypto.generate_keypair()
+        encrypted_prompt = crypto.encrypt(prompt, tee_pubkey, our_private)
+
+        headers = {"X-API-Key": self._api_key} if self._api_key else {}
+        resp = requests.post(
+            f"{p.endpoint}/infer",
+            json={"client_pubkey": our_public, "encrypted_prompt": encrypted_prompt},
+            headers=headers,
+            timeout=120,
+        )
+        if resp.status_code == 401:
+            raise ZKaiAuthError("Invalid or missing API key.")
+        resp.raise_for_status()
+        data = resp.json()
+
+        job_id = data["job_id"]
+
+        if not self._skip_attestation:
+            att_mod.verify(
+                provider_url=p.endpoint,
+                received_attestation_hash=data["attestation_hash"],
+                attestation_contract=self._attestation_contract,
+                job_id=job_id,
+            )
+
+        response_text = crypto.decrypt(data["encrypted_response"], tee_pubkey, our_private)
+        token_count = len(response_text.split())
+
+        return ChatCompletion(
+            id=f"zkai-{job_id[:8]}",
+            object="chat.completion",
+            model=model,
+            choices=[Choice(index=0, message=Message(role="assistant", content=response_text))],
+            usage={"prompt_tokens": len(prompt.split()), "completion_tokens": token_count},
+            attestation_hash=data.get("attestation_hash"),
+        )
+
+
+class _Chat:
+    def __init__(self, client: ZKai):
+        self.completions = _Completions(client)
+
+
+class _Completions:
+    def __init__(self, client: ZKai):
+        self._client = client
+
+    def create(self, model: str, messages: list[dict], **kwargs) -> ChatCompletion:
+        return self._client._infer(model, messages)
+
+
+# ── Exceptions ───────────────────────────────────────────────────────────────
+
+class ZKaiAuthError(Exception):
+    pass
+
+
+class ZKaiNoProviderError(Exception):
+    pass
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+def _messages_to_prompt(messages: list[dict]) -> str:
+    parts = []
+    for m in messages:
+        role = m.get("role", "user")
+        content = m.get("content", "")
+        if role == "system":
+            parts.append(f"System: {content}")
+        elif role == "user":
+            parts.append(f"User: {content}")
+        elif role == "assistant":
+            parts.append(f"Assistant: {content}")
+    parts.append("Assistant:")
+    return "\n".join(parts)

zkai-0.5.0/zkai/crypto.py

@@ -0,0 +1,60 @@
+"""
+Client-side encryption primitives.
+Matches the enclave's decrypt logic exactly.
+"""
+
+import os
+import hashlib
+
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey, X25519PublicKey
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat, PrivateFormat, NoEncryption
+from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+
+
+def generate_keypair() -> tuple[str, str]:
+    """Generate ephemeral X25519 keypair. Returns (private_hex, public_hex)."""
+    private_key = X25519PrivateKey.generate()
+    private_bytes = private_key.private_bytes(Encoding.Raw, PrivateFormat.Raw, NoEncryption())
+    public_bytes = private_key.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+    return private_bytes.hex(), public_bytes.hex()
+
+
+def encrypt(plaintext: str, recipient_pubkey_hex: str, our_private_hex: str) -> str:
+    """
+    ECDH + ChaCha20-Poly1305 encrypt.
+    Returns hex(nonce + ciphertext + tag).
+    """
+    recipient_pubkey = X25519PublicKey.from_public_bytes(bytes.fromhex(recipient_pubkey_hex))
+    our_private = X25519PrivateKey.from_private_bytes(bytes.fromhex(our_private_hex))
+
+    shared_secret = our_private.exchange(recipient_pubkey)
+    key = _derive_key(shared_secret)
+
+    nonce = os.urandom(12)
+    chacha = ChaCha20Poly1305(key)
+    ciphertext = chacha.encrypt(nonce, plaintext.encode("utf-8"), None)
+    return (nonce + ciphertext).hex()
+
+
+def decrypt(encrypted_hex: str, sender_pubkey_hex: str, our_private_hex: str) -> str:
+    """
+    ECDH + ChaCha20-Poly1305 decrypt.
+    encrypted_hex = hex(nonce + ciphertext + tag)
+    """
+    sender_pubkey = X25519PublicKey.from_public_bytes(bytes.fromhex(sender_pubkey_hex))
+    our_private = X25519PrivateKey.from_private_bytes(bytes.fromhex(our_private_hex))
+
+    shared_secret = our_private.exchange(sender_pubkey)
+    key = _derive_key(shared_secret)
+
+    data = bytes.fromhex(encrypted_hex)
+    nonce = data[:12]
+    payload = data[12:]
+
+    chacha = ChaCha20Poly1305(key)
+    plaintext = chacha.decrypt(nonce, payload, None)
+    return plaintext.decode("utf-8")
+
+
+def _derive_key(shared_secret: bytes) -> bytes:
+    return hashlib.sha256(shared_secret).digest()

zkai-0.5.0/zkai/langchain.py

@@ -0,0 +1,63 @@
+"""
+LangChain adapter — one line change from ChatOpenAI.
+
+Before:
+    from langchain_openai import ChatOpenAI
+    llm = ChatOpenAI(model="gpt-4")
+
+After:
+    from zkai import ChatZKai
+    llm = ChatZKai(model="qwen2.5-1.5b", api_key="your-key")
+"""
+
+from typing import Any, List, Optional
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import BaseMessage, AIMessage
+from langchain_core.outputs import ChatGeneration, ChatResult
+
+from .client import ZKai
+
+
+class ChatZKai(BaseChatModel):
+    model: str = "qwen2.5-1.5b"
+    api_key: Optional[str] = None
+    max_price: Optional[float] = None
+    min_reputation: float = 0.0
+    registry_contract: Optional[str] = None
+    attestation_contract: Optional[str] = None
+    skip_attestation: bool = False
+
+    @property
+    def _llm_type(self) -> str:
+        return "zkai"
+
+    def _get_client(self) -> ZKai:
+        return ZKai(
+            api_key=self.api_key,
+            max_price=self.max_price,
+            min_reputation=self.min_reputation,
+            registry_contract=self.registry_contract,
+            attestation_contract=self.attestation_contract,
+            skip_attestation=self.skip_attestation,
+        )
+
+    def _generate(self, messages: List[BaseMessage], **kwargs: Any) -> ChatResult:
+        openai_messages = [
+            {"role": _lc_role(m), "content": m.content}
+            for m in messages
+        ]
+        completion = self._get_client().chat.completions.create(
+            model=self.model,
+            messages=openai_messages,
+        )
+        text = completion.choices[0].message.content
+        return ChatResult(generations=[ChatGeneration(message=AIMessage(content=text))])
+
+
+def _lc_role(message: BaseMessage) -> str:
+    from langchain_core.messages import HumanMessage, SystemMessage, AIMessage
+    if isinstance(message, SystemMessage):
+        return "system"
+    if isinstance(message, AIMessage):
+        return "assistant"
+    return "user"

zkai-0.5.0/zkai/payment.py

@@ -0,0 +1,38 @@
+"""
+Midnight payment escrow integration via ZKai bridge server.
+"""
+
+from .bridge import BridgeClient
+
+
+class PaymentClient:
+    def __init__(self, wallet_key: str | None = None, bridge_url: str | None = None):
+        self.wallet_key = wallet_key
+        self._bridge = BridgeClient(bridge_url) if bridge_url else None
+
+    def create_job(self, provider_id: str, token_budget: int, job_id: str) -> str:
+        """Lock DUST in escrow. Returns the same job_id."""
+        if self._bridge is None:
+            return job_id  # local dev no-op
+
+        self._bridge.call("/payment/create-job", {
+            "job_id": job_id,
+            "provider_id": provider_id,
+            "amount": str(token_budget),
+        })
+        return job_id
+
+    def complete_job(self, job_id: str, attestation_hash: str, token_count: int):
+        """Release escrow payment to provider."""
+        if self._bridge is None:
+            return
+        self._bridge.call("/payment/complete-job", {
+            "job_id": job_id,
+            "attestation_hash": attestation_hash,
+        })
+
+    def dispute_job(self, job_id: str):
+        """Trigger refund — called automatically on attestation failure."""
+        if self._bridge is None:
+            return
+        self._bridge.call("/payment/dispute-job", {"job_id": job_id})

zkai-0.5.0/zkai/provider.py

@@ -0,0 +1,142 @@
+"""
+Provider discovery and selection.
+- No registry_contract: local dev stub (localhost:8080)
+- With registry_contract: queries Midnight indexer GraphQL for on-chain providers
+"""
+
+import requests
+from dataclasses import dataclass
+
+INDEXER_URL = "https://indexer.preprod.midnight.network/api/v3/graphql"
+
+
+@dataclass
+class Provider:
+    id: str
+    endpoint: str
+    pubkey: str
+    model: str
+    price_per_token: float
+    reputation: float
+    stake: float
+
+
+def select_provider(
+    model: str,
+    max_price: float | None = None,
+    min_reputation: float = 0.0,
+    registry_contract: str | None = None,
+) -> Provider:
+    """Pick the best available provider. Ranked by reputation desc, price asc."""
+    providers = _get_providers(registry_contract)
+
+    candidates = [
+        p for p in providers
+        if p.model == model
+        and (max_price is None or p.price_per_token <= max_price)
+        and p.reputation >= min_reputation
+    ]
+
+    if not candidates:
+        raise RuntimeError(
+            f"No providers available for model '{model}' "
+            f"within price/reputation constraints."
+        )
+
+    candidates.sort(key=lambda p: (-p.reputation, p.price_per_token))
+    return candidates[0]
+
+
+def fetch_pubkey(provider: Provider) -> str:
+    """Fetch current TEE pubkey from provider (may rotate on restart)."""
+    resp = requests.get(f"{provider.endpoint}/pubkey", timeout=10)
+    resp.raise_for_status()
+    return resp.json()["pubkey"]
+
+
+def _get_providers(registry_contract: str | None) -> list[Provider]:
+    if registry_contract is None:
+        return _get_providers_stub()
+    return _get_providers_from_chain(registry_contract)
+
+
+def _get_providers_from_chain(registry_contract: str) -> list[Provider]:
+    """
+    Query Midnight indexer GraphQL for active providers in the ProviderRegistry.
+    The contract's export ledger maps are publicly readable.
+    """
+    query = """
+    query GetContractState($address: String!) {
+      contract(address: $address) {
+        state {
+          ... on ContractState {
+            ledger {
+              ... on ZkaiProviderRegistryLedger {
+                provider_active { entries { key value } }
+                provider_endpoint { entries { key value } }
+                provider_model { entries { key value } }
+                provider_price { entries { key value } }
+                provider_reputation { entries { key value } }
+                provider_pubkey { entries { key value } }
+              }
+            }
+          }
+        }
+      }
+    }
+    """
+    try:
+        resp = requests.post(
+            INDEXER_URL,
+            json={"query": query, "variables": {"address": registry_contract}},
+            timeout=15,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        ledger = data.get("data", {}).get("contract", {}).get("state", {}).get("ledger", {})
+
+        if not ledger:
+            # Indexer schema may differ — fall back to stub with a warning
+            print("Warning: Could not parse on-chain providers, falling back to stub")
+            return _get_providers_stub()
+
+        active_entries = {e["key"]: e["value"] for e in ledger.get("provider_active", {}).get("entries", [])}
+        endpoint_entries = {e["key"]: e["value"] for e in ledger.get("provider_endpoint", {}).get("entries", [])}
+        model_entries = {e["key"]: e["value"] for e in ledger.get("provider_model", {}).get("entries", [])}
+        price_entries = {e["key"]: e["value"] for e in ledger.get("provider_price", {}).get("entries", [])}
+        rep_entries = {e["key"]: e["value"] for e in ledger.get("provider_reputation", {}).get("entries", [])}
+        pubkey_entries = {e["key"]: e["value"] for e in ledger.get("provider_pubkey", {}).get("entries", [])}
+
+        providers = []
+        for pid, active in active_entries.items():
+            if not active:
+                continue
+            providers.append(Provider(
+                id=pid,
+                endpoint=endpoint_entries.get(pid, ""),
+                pubkey=pubkey_entries.get(pid, ""),
+                model=model_entries.get(pid, ""),
+                price_per_token=float(price_entries.get(pid, 0)),
+                reputation=float(rep_entries.get(pid, 500000)) / 1_000_000,
+                stake=0.0,
+            ))
+        return providers if providers else _get_providers_stub()
+
+    except Exception as e:
+        print(f"Warning: Failed to fetch on-chain providers ({e}), falling back to stub")
+        return _get_providers_stub()
+
+
+def _get_providers_stub() -> list[Provider]:
+    """Local dev stub — points to localhost enclave."""
+    return [
+        Provider(
+            id="local-dev",
+            endpoint="http://localhost:8080",
+            pubkey="",
+            model="qwen2.5-1.5b",
+            price_per_token=0.0,
+            reputation=1.0,
+            stake=0.0,
+        )
+    ]

zkai-0.5.0/zkai.egg-info/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: zkai
+Version: 0.5.0
+Summary: Private, verifiable AI inference on 0G chain — drop-in OpenAI-compatible SDK
+Author-email: ZKai <team@zkai.network>
+License: MIT
+Project-URL: Homepage, https://zkai-ether-og.vercel.app
+Project-URL: Repository, https://github.com/skyyycodes/zkai-eth
+Project-URL: Issues, https://github.com/skyyycodes/zkai-eth/issues
+Keywords: ai,inference,openai,llm,tee,tdx,attestation,blockchain,0g,verifiable,privacy,encryption
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=43.0
+Requires-Dist: requests>=2.32
+Requires-Dist: pydantic>=2.9
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+
+# zkai
+
+OpenAI-compatible Python SDK for [ZKai](https://zkai-ether-og.vercel.app) — private, verifiable AI inference on 0G chain.
+
+ZKai sends your prompt through a Trusted Execution Environment (Intel TDX), encrypts it client-side so even the gateway cannot read it, and anchors a SHA-256 attestation of every inference on the 0G chain. You get back a normal OpenAI-style response plus an on-chain receipt.
+
+## Install
+
+```bash
+pip install zkai
+```
+
+Optional LangChain adapter:
+
+```bash
+pip install "zkai[langchain]"
+```
+
+## Quick start
+
+```python
+from zkai import ZKai
+
+client = ZKai(api_key="zkai-...")  # get one at https://zkai-ether-og.vercel.app
+
+response = client.chat.completions.create(
+    model="qwen2.5:1.5b",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+print(response.choices[0].message.content)
+print("Attestation hash:", response.attestation_hash)
+```
+
+The response is decrypted locally — the gateway sees only ciphertext.
+The attestation hash is anchored on 0G mainnet and can be verified independently.
+
+## How it works (gateway mode, default)
+
+1. The SDK fetches the enclave's X25519 public key from the gateway.
+2. It encrypts your prompt locally with ECDH + ChaCha20-Poly1305.
+3. It sends only the ciphertext to the gateway.
+4. The gateway routes the opaque blob to a TDX-sealed enclave running the requested model.
+5. The enclave decrypts inside sealed memory, runs the model, encrypts the response, and emits a SHA-256 attestation hash.
+6. The attestation lands on the on-chain `AttestationRegistry` contract.
+7. The SDK decrypts the response locally and returns it to you.
+
+End-to-end, the gateway never sees plaintext.
+
+## Configuration
+
+```python
+ZKai(
+    api_key="zkai-...",                             # issued from the dashboard
+    base_url="https://zkai-ether-og.vercel.app",    # default
+    encrypted=True,                                  # default; set False to use the legacy plaintext path
+    provider_endpoint=None,                          # set to bypass gateway and hit a provider directly
+    skip_attestation=False,                          # only for development; do not disable in prod
+)
+```
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | `str | None` | `None` | Sent as `X-API-Key`. Required for the hosted gateway. |
+| `base_url` | `str | None` | `https://zkai-ether-og.vercel.app` | Override to point at a self-hosted gateway. |
+| `encrypted` | `bool` | `True` | When `True`, prompts are encrypted client-side. Set `False` for legacy clients. |
+| `provider_endpoint` | `str | None` | `None` | When set, bypasses the gateway and talks directly to a provider's `/infer` endpoint. |
+| `skip_attestation` | `bool` | `False` | Disables attestation verification. Useful only for dev loops. |
+
+## OpenAI compatibility
+
+The response object mirrors OpenAI's chat completion shape:
+
+```python
+response.id
+response.model
+response.choices[0].message.content
+response.choices[0].finish_reason
+response.usage.prompt_tokens
+response.usage.completion_tokens
+
+# ZKai-specific:
+response.attestation_hash  # on-chain commitment
+```
+
+Drop-in replacement for most OpenAI SDK call sites — just swap the client class.
+
+## On-chain components (0G mainnet, chain ID 16661)
+
+| Contract | Address |
+|---|---|
+| ProviderRegistry | `0x6D400F5D1DcCaA3e98E3dE17322aA23DE38bAC99` |
+| PaymentEscrow | `0xb2C7c0F7a4C2877319E8Ed1Fae0bf3C705b6Fc4C` |
+| AttestationRegistry | `0x8c8Ae0A113084268D181fd1cf23d611DC2EAa2B2` |
+
+Verify any attestation hash on the [0G explorer](https://chainscan.0g.ai).
+
+## Running your own provider
+
+See the companion [`zkai-cli`](https://pypi.org/project/zkai-cli/) package:
+
+```bash
+pip install zkai-cli
+zkai init && zkai start && zkai register
+```
+
+## Links
+
+- Dashboard — https://zkai-ether-og.vercel.app
+- Repository — https://github.com/skyyycodes/zkai-eth
+- Provider CLI — https://pypi.org/project/zkai-cli/
+
+## License
+
+MIT

zkai-0.5.0/zkai.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+zkai/__init__.py
+zkai/attestation.py
+zkai/bridge.py
+zkai/client.py
+zkai/crypto.py
+zkai/langchain.py
+zkai/payment.py
+zkai/provider.py
+zkai.egg-info/PKG-INFO
+zkai.egg-info/SOURCES.txt
+zkai.egg-info/dependency_links.txt
+zkai.egg-info/requires.txt
+zkai.egg-info/top_level.txt

zkai-0.5.0/zkai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zkai-0.5.0/zkai.egg-info/requires.txt

@@ -0,0 +1,6 @@
+cryptography>=43.0
+requests>=2.32
+pydantic>=2.9
+
+[langchain]
+langchain-core>=0.3

zkai-0.5.0/zkai.egg-info/top_level.txt

@@ -0,0 +1 @@
+zkai