Fiabilité & confidentialité

L'instrumentation ne doit jamais casser votre application ni fuiter de données. Le SDK est conçu pour ça.

Le SDK ne casse jamais votre code

Sans clé API, le client devient no-op (sans effet) : toutes les primitives renvoient des contextes réels mais n'émettent rien, aucune branche if sdk: à écrire. En safe_mode, les erreurs de validation sont routées vers on_error au lieu d'être levées.

# zéro-config : lit NIAONE_API_KEY / NIAONE_BASE_URL / NIAONE_DISABLED / NIAONE_SAFE_MODEclient = NiaoneSDK.from_env(safe_mode=True, on_error=lambda exc, ctx: logger.warning("niaone %s: %s", ctx, exc))# explicitement désactivé (local, CI)client = NiaoneSDK.disabled()

Retries avec classification

Enveloppez un appel faillible : backoff exponentiel + jitter, un log WARN par tentative (annoté de la raison), et la métrique retry_count.

from niaone_sdk import with_retriesresp = with_retries(s, lambda: client_openai.chat.completions.create(model="gpt-4o", messages=msgs),                  max_attempts=3, backoff_factor=1.0, max_backoff_s=10.0)

Débit : sampling

Réduisez le volume tout en gardant des traces cohérentes : le sampling est trace-cohérent (un même trace_id est toujours gardé ou jeté en entier). Surchargez par type de record.

from niaone_sdk import SamplingPolicyclient = NiaoneSDK(api_key="sk_...", sampling=SamplingPolicy(rate=0.25, per_record_type={"log": 0.05}))

Confidentialité : scrubbing PII

Masquez les PII avant l'envoi. RegexScrubber couvre par défaut email, téléphone (FR + intl), IBAN, carte bancaire (validée par Luhn) et IPv4 ; ajoutez vos propres motifs.

from niaone_sdk import RegexScrubberscrubber = RegexScrubber(patterns={"ssn": r"\d{3}-\d{2}-\d{4}"},                       replacement="<{name}>", luhn_check_credit_card=True)client = NiaoneSDK(api_key="sk_...", scrub_pii=scrubber)

Sensibilité des données

Taggez chaque payload (charge utile) via Data(sensitivity=...) : public, internal (défaut), confidential, restricted. Combinez avec les modes de capture de prompts (HASH_ONLY / FULL / REDACTED) pour contrôler finement ce qui quitte votre infrastructure.

Débit : batching & arrêt propre

Le client bufferise et envoie par lots en arrière-plan. Réglez la taille et la cadence, et appelez close() à l'arrêt pour vider la file.

client = NiaoneSDK(api_key="sk_...", max_batch_size=50, flush_interval_seconds=2.0)# ... à l'arrêt du process ...client.close()   # flush final

Santé : heartbeat

Donnez un service_name pour activer un heartbeat (signal de présence) périodique (CPU, mémoire, GPU si dispo, statut OK/DEGRADED/UNHEALTHY). En Python, health_provider ajoute vos propres champs (taille de file, pool DB…).

client = NiaoneSDK(api_key="sk_...", service_name="ml-worker",                 heartbeat_interval_seconds=60,                 health_provider=lambda: {"queue_size": q.qsize()})

Introspection runtime de l'environnement

Au démarrage (sans aucun appel réseau), le SDK détecte la stack IA réellement déployée et l'ajoute au heartbeat (donc actif dès qu'un service_name / serviceName est configuré). La plateforme s'en sert pour enrichir le host-health / la topologie de votre SIA.

Détection one-shot et mémoïsée au premier heartbeat, sur une whitelist fermée (aucune énumération de vos dépendances). Les régions sont inférées depuis des patterns DNS ou des env vars dédiées, jamais par géolocalisation.

Framework ou DB propriétaire hors whitelist ? Déclarez-le (constructeur, ou env var CSV logical:pkg) :

client = NiaoneSDK(api_key="sk_...", service_name="svc",                 custom_ai_frameworks=[("internal-rag", "my_rag_lib")])# ou au déploiement : NIAONE_EXTRA_AI_FRAMEWORKS="internal-rag:my_rag_lib"