Skip to main content

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)

Source distribution for alea-q 0.3.0
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)

Table of built distributions (wheels) for alea-q 0.3.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page