Metadata-Version: 2.4
Name: qbitseed
Version: 0.1.0
Summary: Python client for the QbitSeed Quantum Randomness-as-a-Service API
Author-email: QbitSeed <hello@qbitseed.com>
License-Expression: MIT
Project-URL: Homepage, https://qbitseed.com
Project-URL: API Docs, https://qbitseed-api-production.up.railway.app/docs
Keywords: quantum,random,randomness,rng,entropy,qrng,cryptography
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1.0,>=0.27
Dynamic: license-file

# qbitseed (Python)

Python client for the [QbitSeed](https://qbitseed-api-production.up.railway.app) Quantum Randomness-as-a-Service API.

**Not yet published to PyPI.** For now, install from this repo:

```bash
pip install -e sdks/python
```

## Quickstart

```python
from qbitseed import QbitSeedClient

client = QbitSeedClient(api_key="qbs_live_...")

result = client.random(bits=256)
print(result.source)        # "ibm_quantum" (or "classical_failover" on quantum failure -- always honest)
print(result.data)          # raw bytes, decoded from result.data_base64
print(result.certificate_id)

# Independently verify the certificate that came with it
verification = client.verify_certificate(result.certificate_id)
print(verification.valid)   # True

# Check usage against your monthly quota
summary = client.get_usage_summary()
print(f"{summary.requests_used_this_month}/{summary.monthly_limit}")
```

## Errors

All errors subclass `qbitseed.QbitSeedError` and carry a `.status_code`:

| Exception | HTTP status | Cause |
|---|---|---|
| `AuthenticationError` | 401 | Missing, malformed, unknown, revoked, or expired API key |
| `ValidationError` | 422 | `bits` outside 256-16384, or not a multiple of 8 |
| `RateLimitError` | 429 | This key's monthly limit has been exceeded |
| `ServerError` | 5xx | Something went wrong on QbitSeed's end |

```python
from qbitseed import QbitSeedClient, RateLimitError

try:
    client.random()
except RateLimitError as exc:
    print(f"rate limited: {exc}")
```

## Reference

- `QbitSeedClient(api_key, base_url=DEFAULT_BASE_URL, timeout=30.0)`
- `.random(bits: int = 256) -> RandomResponse`
- `.get_certificate(certificate_id: str) -> Certificate`
- `.verify_certificate(certificate_id: str) -> VerifyResponse`
- `.list_certificates(limit: int = 50, offset: int = 0) -> CertificateListResponse` — certificates issued to this key, newest first
- `.get_usage_summary() -> UsageSummary` — this key's usage against its own monthly quota
- `.list_requests(limit: int = 50, offset: int = 0) -> UsageRequestsListResponse` — requests served under this key, newest first

Full endpoint documentation, including request/response schemas, is available live at `/docs` on any running instance (e.g. https://qbitseed-api-production.up.railway.app/docs).

## License

MIT — see [`LICENSE`](LICENSE).
