Metadata-Version: 2.4
Name: obelyzk
Version: 0.4.0
Summary: Python SDK for ObelyZK — Provable ML Inference
Author: Bitsage Network
License: Apache-2.0
Project-URL: Homepage, https://github.com/Bitsage-Network/stwo-ml
Project-URL: Documentation, https://github.com/Bitsage-Network/stwo-ml/tree/main/sdk/python
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-httpserver>=1.0; extra == "dev"

# ObelyZK Python SDK

Python client for the ObelyZK provable inference API. Supports 7 model families with cryptographic self-verification.

## Install

```bash
pip install obelyzk
# or from source:
pip install -e sdk/python/
```

## Quick Start

```python
import obelyzk

# Connect to prove-server
client = obelyzk.Client("http://localhost:8080")

# Load a HuggingFace model (any of the 7 proven families)
model = client.load_hf_model("~/.obelysk/models/qwen2-0.5b")
print(f"Model ID: {model.model_id}")
print(f"Weight commitment: {model.weight_commitment}")

# Run provable inference
result = client.infer(
    model_id=model.model_id,
    input_data=[0.1, 0.2, 0.3, 0.4],  # must match model input shape
)

print(f"Output: {result.output}")
print(f"Proof hash: {result.proof_hash}")
print(f"Proved in {result.prove_time_seconds:.1f}s")
print(f"Calldata size: {result.calldata_size} felts")

# Verify the proof
verification = client.verify(result.proof_hash)
assert verification.valid
print(f"Verified: {verification.valid} (method: {verification.method})")

# List all proven inferences
proofs = client.list_proofs()
for p in proofs:
    print(f"  {p.proof_hash[:16]}... model={p.model_id[:16]}... layers={p.num_proven_layers}")
```

## Supported Models

All 7 proven model families work with the SDK:

| Model | Prove Time (Apple Silicon) |
|-------|---------------------------|
| Qwen2-0.5B | 0.57s |
| Qwen2-1.5B | 1.14s |
| SmolLM2-135M | 3.41s |
| Phi-3 Mini 3.8B | 48.86s |
| Llama-3.2-3B | 48.48s |
| Yi-1.5-6B | 86.58s |
| Mistral-7B-v0.3 | 88.19s |

## REST API Endpoints

The SDK communicates with the prove-server REST API:

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/health` | Server status, GPU/TEE detection, loaded models |
| `POST` | `/api/v1/models` | Load ONNX model, compute weight commitment |
| `GET` | `/api/v1/models/{id}` | Get model info |
| `POST` | `/api/v1/infer` | Provable inference -- run model + generate proof |
| `GET` | `/api/v1/verify/:hash` | Verify a proof by hash |
| `GET` | `/api/v1/proofs` | List all generated proofs |
| `POST` | `/api/v1/prove` | Submit prove job (returns 202 + job_id) |
| `GET` | `/api/v1/prove/{id}` | Poll job status + progress |
| `GET` | `/api/v1/prove/{id}/result` | Get completed proof (calldata, commitments, gas) |

## API Reference

### `Client(base_url, api_key=None, timeout=300)`

Create a client connected to an ObelyZK prove-server.

### `client.load_model(model_path)` -> `ModelInfo`

Load an ONNX model on the server.

### `client.load_hf_model(model_dir, num_layers=None)` -> `ModelInfo`

Load a HuggingFace model directory. Supports Qwen, Phi, Llama, Yi, Mistral, and other transformer architectures with SafeTensors weights.

### `client.infer(model_id, input_data, ...)` -> `InferResult`

Run provable inference. Returns output + proof. The proof covers every matmul, activation, normalization, and attention operation.

### `client.verify(proof_hash)` -> `VerifyResult`

Verify a proof by hash. Returns verification status and method (local or on-chain).

### `client.list_proofs()` -> `list[StoredProof]`

List all proven inferences.

## What This Proves

Every call to `client.infer()` generates a cryptographic proof (GKR sumcheck over M31 field arithmetic) that:

1. The **output** was computed by running the **committed model weights** on the **given input**
2. Every matmul, activation, normalization, and attention operation was executed correctly
3. The proof is verifiable on Starknet (on-chain) or locally (off-chain)

No IEEE 754 floating-point is used in the proving path. All arithmetic is native M31 field operations -- deterministic across every platform.

## Docker

```bash
# Start prove-server with Docker
docker compose up prove-server

# With GPU support
docker compose -f docker-compose.gpu.yml up prove-server
```
