alea-q
SDK Python officiel pour l'API ALEA-Q / CERTROPI — génération d'entiers aléatoires certifiés Device-Independent depuis des ordinateurs quantiques réels.
Installation
pip install alea-q
# Avec vérification de certificats d'attestation
pip install "alea-q[verify]"
# Avec streaming Silver en temps réel
pip install "alea-q[stream]"
Démarrage rapide
from alea_q import AleaQClient
# Clé API dans le constructeur ou variable d'env ALEA_Q_API_KEY
client = AleaQClient(api_key="sk_plat_xxx")
# Platinum — entier DI-certifié depuis un ordinateur quantique réel
result = client.platinum.generate(n_bits=256)
print(result.as_hex()) # 0x3f2a...
print(result.certificate) # dict d'attestation SHA-3/ECDSA
# Silver — DRBG seedé QPU
result = client.silver.generate(n_bits=128)
# Ivory — batch haute vitesse
batch = client.ivory.batch(size=10000, n_bits=32)
print(batch.values[:5])
Authentification
# Option 1 — clé dans le constructeur
client = AleaQClient(api_key="sk_plat_xxx")
# Option 2 — variable d'environnement
import os
os.environ["ALEA_Q_API_KEY"] = "sk_plat_xxx"
client = AleaQClient()
Le tier est détecté automatiquement depuis le préfixe de la clé
(sk_ivor_ / sk_silv_ / sk_plat_) :
client = AleaQClient(api_key="sk_plat_xxx")
print(client.tier) # "platinum"
Compte authentifié
info = client.me()
print(info.tier) # "platinum"
print(info.quota.remaining_today) # entiers restants aujourd'hui
print(info.usage.total_calls) # appels cumulés
Tiers disponibles
| Tier | Source | Certification | Latence |
|---|---|---|---|
| Platinum | Ordinateur quantique réel | Device-Independent | < 1ms pool |
| Silver | DRBG seedé quantique | Seed quantique | < 1ms |
| Ivory | Simulateur Toeplitz | Haute qualité stat. | < 0.1ms |
Tirage dans un intervalle (generate_range / batch_range)
Tire un entier certifié dans [min, max] (ou [min, max[ si inclusive=False) plutôt que dans [0, 2^n_bits) — disponible sur Ivory et Silver (Platinum pas encore supporté sur ce chemin). Rejection sampling côté serveur, aucun biais statistique, facturé à plat (indépendant du nombre de retirages internes en cas de rejet).
# Un entier entre 5 et 15 inclus
result = client.ivory.generate_range(min=5, max=15)
print(result.value) # 5, 6, ..., ou 15
# Demi-ouvert : 15 exclu
result = client.ivory.generate_range(min=5, max=15, inclusive=False)
# Un dé à 6 faces, en lot de 10
batch = client.ivory.batch_range(min=1, max=6, size=10)
print(batch.values) # [3, 1, 6, ...]
Vérification des certificats Platinum
Chaque réponse Platinum inclut un certificat d'attestation vérifiable sans contacter CERTROPI.
# Vérification automatique à la génération
result = client.platinum.generate(
n_bits=256,
verify=True,
pubkey_path="certropi_public.pem",
)
# Vérification manuelle depuis un dict
from alea_q import verify_certificate_dict
S = verify_certificate_dict(result.certificate, pubkey_path="certropi_public.pem")
print(f"Certificat valide — S={S:.4f}")
# Vérification depuis un fichier JSON
from alea_q import verify_certificate
verify_certificate("cert.json", pubkey_path="certropi_public.pem")
Récupérer la clé publique CERTROPI :
curl https://api.alea-q.com/v1/platinum/pubkey -o certropi_public.pem
# ou
python -c "
from alea_q import AleaQClient
client = AleaQClient()
open('certropi_public.pem', 'wb').write(client.platinum.get_public_key())
"
Context manager
with AleaQClient(api_key="sk_plat_xxx") as client:
result = client.platinum.generate(n_bits=256)
Client asynchrone
import asyncio
from alea_q import AsyncAleaQClient
async def main():
async with AsyncAleaQClient(api_key="sk_plat_xxx") as client:
result = await client.platinum.generate(n_bits=256)
print(result.as_hex())
asyncio.run(main())
Streaming Silver (temps réel)
Flux continu d'entiers en WebSocket — utile pour alimenter en continu un consommateur d'entropie (HSM, pool applicatif, génération de clés en masse) sans refaire une requête HTTP par lot.
Nécessite l'extra stream : pip install "alea-q[stream]"
import asyncio
from alea_q import AsyncAleaQClient
async def main():
async with AsyncAleaQClient(api_key="sk_silv_xxx") as client:
count = 0
async for value in client.silver.stream(bits_per_second=100_000, n_bits=256):
print(value)
count += 1
if count >= 1000:
break # ferme proprement le flux côté client
asyncio.run(main())
Le débit est exprimé en bits/seconde, pas en nombre d'entiers — cohérent
avec la facturation volumétrique du service et indépendant de n_bits
(la largeur de chaque entier livré). Le flux reste ouvert tant que la
boucle async for n'est pas interrompue (break) et que la clé reste
valide — une révocation de clé en cours de flux le referme immédiatement.
Gestion des erreurs spécifiques au streaming :
from alea_q import AuthenticationError, InsufficientBalance, QuotaExceeded
async def main():
async with AsyncAleaQClient(api_key="sk_silv_xxx") as client:
try:
async for value in client.silver.stream(bits_per_second=100_000):
...
except AuthenticationError:
print("Clé invalide ou révoquée en cours de flux")
except InsufficientBalance:
print("Solde prépayé épuisé — recharger via le support")
except QuotaExceeded:
print("Capacité de débit disponible dépassée — réessayer plus tard")
asyncio.run(main())
Le client synchrone (AleaQClient) ne propose pas le streaming — le
flux est intrinsèquement asynchrone, utiliser AsyncAleaQClient.
Livraison chiffrée post-quantique (Platinum, recipient_pk)
Pour ne jamais faire transiter la valeur générée en clair, generate()
accepte (Platinum uniquement) un recipient_pk — une clé publique
ML-KEM-768 que vous générez localement. La valeur revient alors
enveloppée (ML-KEM + AES-256-GCM + signature SLH-DSA) dans .envelope
au lieu d'être renvoyée en clair dans .value :
import base64
from alea_q import mlkem_decaps
# my_mlkem_dk / my_mlkem_pubkey_hex : paire de clés ML-KEM-768 générée
# localement (ex. via pyca/cryptography — jamais transmise au serveur).
result = client.platinum.generate(n_bits=256, recipient_pk=my_mlkem_pubkey_hex)
if result.envelope:
# result.value est vide — la valeur réelle est dans
# result.envelope["encrypted_payload"], chiffrée pour my_mlkem_pubkey_hex.
# La décapsulation reste locale : le serveur ne voit jamais votre clé
# privée ni le secret déchiffré.
#
# Nécessite l'extra 'verify' : pip install 'alea-q[verify]'
#
# ATTENTION : les champs de l'enveloppe (ciphertext, encrypted_payload,
# nonce, signature, certropi_pk) sont en BASE64.
ciphertext = base64.b64decode(result.envelope["ciphertext"])
shared_key = mlkem_decaps(my_mlkem_dk, ciphertext, param_set="ML_KEM_768")
# shared_key (32 octets) est la clé AES-256-GCM utilisée pour chiffrer
# result.envelope["encrypted_payload"] (nonce en base64 lui aussi) —
# déchiffrement AES-GCM restant à la charge de l'appelant, non fourni
# par ce SDK à ce jour.
Gestion des erreurs
from alea_q import AleaQClient
from alea_q.exceptions import BackendUnavailable, AuthenticationError, InsufficientBalance
import time
client = AleaQClient()
try:
result = client.platinum.generate(n_bits=256)
except BackendUnavailable as e:
print(f"QPU indisponible — réessayer dans {e.retry_after}s")
time.sleep(e.retry_after or 300)
except AuthenticationError:
print("Clé API invalide")
except InsufficientBalance:
print("Solde prépayé épuisé (mode pay-as-you-go) — recharger via le support")
Configuration
| Variable d'env | Description | Défaut |
|---|---|---|
ALEA_Q_API_KEY |
Clé API | — |
ALEA_Q_BASE_URL |
URL de base de l'API | https://api.alea-q.com |
ALEA_Q_TIMEOUT |
Timeout HTTP en secondes | 60 |
ALEA_Q_MAX_RETRIES |
Nombre de retries automatiques | 2 |
ALEA_Q_PUBKEY_PATH |
Chemin clé publique CERTROPI | certropi_public.pem |
https://api.certropi.com est un alias B2B de la même API — les deux
domaines répondent de manière identique, ALEA_Q_BASE_URL accepte
indifféremment l'un ou l'autre.
Retry automatique
ALEA_Q_MAX_RETRIES (ou max_retries= au constructeur de AleaQClient/
AsyncAleaQClient) déclenche un nouvel essai uniquement sur un échec
transitoire :
- Erreur réseau (timeout, connexion refusée, DNS…)
RateLimitError(429 rate-limit)BackendUnavailable(503 — backend QPU temporairement indisponible)ServerError(5xx)
Jamais retenté (échec déterministe — un nouvel essai identique échouerait
pareil) : AuthenticationError, PermissionError, ValidationError,
InsufficientBalance, CertificateError, et QuotaExceeded (429
quota applicatif — distinct du rate-limit malgré le même code HTTP : un
quota ne se réinitialise pas en quelques secondes).
Backoff exponentiel (ou Retry-After du serveur si fourni), plafonné à
30 secondes dans tous les cas. max_retries=0 désactive le retry.
Développement
pip install -e ".[dev]"
# Suite de tests (mock HTTP via respx — aucun accès réseau requis)
pytest
# Avec couverture
pytest --cov=alea_q --cov-report=term-missing
# Tests contre l'API réelle (marqués `smoke`, nécessitent ALEA_Q_API_KEY
# et un accès réseau — exclus par défaut)
pytest -m smoke
Licence
Propriétaire — CERTROPI © 2026
Metadata
Release files for alea-q 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| alea_q-0.3.0.tar.gz | 42.8 kB | Without provenance | Details for alea_q-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| alea_q-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for alea_q-0.3.0-py3-none-any.whl |
Total release size: 70.7 kB
Release files / alea_q-0.3.0.tar.gz
| Download URL | alea_q-0.3.0.tar.gz |
|---|---|
| Size | 42.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
34d624123ad7a10354e51debe2458556be7720d74fcaae595a0c7a43d2ff937c
|
|
BLAKE2b-256 checksum How to use checksums |
6030638be71b39c6b370e0dde12969a490ded9dc97092d8e200a6ddbc0b34bff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Release files / alea_q-0.3.0-py3-none-any.whl
| Download URL | alea_q-0.3.0-py3-none-any.whl |
|---|---|
| Size | 27.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
07ef61c7737e9ee62c96cbf89c60dcdf6c5ebf50bc5487a50d9b04e8d26345df
|
|
BLAKE2b-256 checksum How to use checksums |
d8039662a3f398f40ed9d220e996d6a3e85a126a97bac9c2142a1326a69ccca6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for alea-q 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.