Metadata-Version: 2.4
Name: quantumize-sdk
Version: 1.0.1
Summary: Python SDK for the Quantumize post-quantum cryptography API
Project-URL: Homepage, https://quantumize.io
Project-URL: Documentation, https://quantumize.io/docs/sdk/python
Project-URL: OpenAPI Spec, https://quantumize.io/api/v1/openapi.json
Project-URL: Source Code, https://github.com/eaquiroz/quantumize-platform
Author-email: Quantumize Platform <support@quantumize.io>
License: Proprietary
Keywords: cryptography,dilithium,falcon,kyber,post-quantum,pqc
Classifier: Intended Audience :: Developers
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 :: Security :: Cryptography
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Provides-Extra: async
Requires-Dist: httpx>=0.24.0; extra == 'async'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# Quantumize Python SDK

A typed Python client for the [Quantumize](https://quantumize.io) post-quantum
cryptography API. Supports both sync (`httpx`) and async usage.

## Installation

```bash
pip install quantumize-sdk
```

Or install directly from source:

```bash
pip install ./sdk/python
```

**Requirements:** Python ≥ 3.9, `httpx ≥ 0.24.0`

## Quick Start

```python
from quantumize import QuantumizeClient

# 1. Initialise the client with your API key
client = QuantumizeClient(api_key="qtz_k_your_key_here")

# 2. Encrypt a file
with open("report.pdf", "rb") as f:
    result = client.encrypt_file(f, "report.pdf", algo="kyber768")

# 3. The encrypted artifact and decryption key are now stored in Quantumize
print("Encrypted file:", result.encrypted_file_name)
print("Decryption key:", result.private_decryption_key_name)

# 4. List your files
files = client.list_files()
for file in files:
    print(file.name, "•", "encrypted" if file.encrypted else "plaintext")

# 5. Check your account and credit balance
account = client.get_account()
print(f"Credits remaining: {account.credits}")
```

> **Generate an API key** at Account Settings → API Keys in the dashboard, or
> via `POST /api/v1/api-keys`. The full key value is shown only once — store it
> in an environment variable or a secrets manager.

---

## Authentication

All requests authenticate via the `X-API-Key` header:

```python
client = QuantumizeClient(api_key="qtz_k_...")
```

For on-premise / enterprise deployments behind a firewall, pass your internal
base URL:

```python
client = QuantumizeClient(
    api_key="qtz_k_...",
    base_url="https://pqc.internal.acme.com",
)
```

---

## Core Methods

### Cryptographic Operations

| Method | Description | Credits |
|--------|-------------|---------|
| `encrypt_file(file, filename, algo, parent_id)` | Encrypt with a post-quantum KEM | 2 |
| `decrypt_file(encrypted_file, key, algo, record_id)` | Decrypt using the stored key | 0 |
| `sign_file(file, filename, algo, parent_id)` | Sign with a post-quantum DSA | 2 |
| `verify_file(sig_file, pub_key, algo, record_id)` | Verify a signature | 0 |

### File Management

| Method | Description |
|--------|-------------|
| `list_files(parent_id=None)` | List files/folders (root or in a folder) |

### Account & Platform

| Method | Description |
|--------|-------------|
| `get_account()` | Get profile + credit balance |
| `get_algorithms()` | List all supported PQC algorithms |
| `list_api_keys()` | List API keys for this account |
| `create_api_key(name, expires_at)` | Create a new API key |
| `revoke_api_key(key_id)` | Revoke an API key |

---

## Algorithms

Fetch available algorithms at runtime:

```python
algos = client.get_algorithms()
kem_algos = [a for a in algos if a.type == "KEM"]
dsa_algos = [a for a in algos if a.type == "DSA"]

for algo in kem_algos:
    print(f"{algo.name:30s}  Security Level {algo.security_level}  {algo.nist_status}")
```

**Common KEM algorithms:** `kyber512`, `kyber768` (default), `kyber1024`,
`mceliece348864`, `hqc-128`, `hqc-192`, `hqc-256`

**Common DSA algorithms:** `dilithium2` (default), `dilithium3`, `dilithium5`,
`falcon-512`, `falcon-1024`, `sphincs-sha2-128f`

---

## Async Usage

```python
import asyncio
from quantumize import AsyncQuantumizeClient

async def main():
    async with AsyncQuantumizeClient(api_key="qtz_k_...") as client:
        # Encrypt a file asynchronously
        with open("contract.docx", "rb") as f:
            result = await client.encrypt_file(f, "contract.docx", algo="kyber1024")

        print("Encrypted:", result.encrypted_file_name)

        # List supported algorithms
        algos = await client.get_algorithms()
        print(f"{len(algos)} algorithms available")

asyncio.run(main())
```

---

## Error Handling

```python
from quantumize import (
    QuantumizeClient,
    AuthenticationError,
    InsufficientCreditsError,
    VerificationError,
)

client = QuantumizeClient(api_key="qtz_k_...")

try:
    result = client.encrypt_file(open("data.bin", "rb"), "data.bin")
except InsufficientCreditsError:
    print("Not enough credits — top up at quantumize.io/billing")
except AuthenticationError:
    print("Invalid or revoked API key")
```

| Exception | HTTP | Cause |
|-----------|------|-------|
| `AuthenticationError` | 401 | Invalid / revoked API key or token |
| `AuthorizationError` | 403 | Admin-only endpoint |
| `NotFoundError` | 404 | Record / key not found |
| `ValidationError` | 400 / 422 | Bad request parameters |
| `InsufficientCreditsError` | 402 | Too few credits |
| `RateLimitError` | 429 | Request rate exceeded |
| `VerificationError` | 422 | Signature verification failed |
| `ServerError` | 5xx | Unexpected server error |

---

## OpenAPI Specification

The full machine-readable API contract is available at:

```
GET /api/v1/openapi.json
```

Or download the YAML source from the repository at
`docs/api/openapi.yaml`.

---

## License

Proprietary — © Quantumize Platform. All rights reserved.
