neomundi 2.0.0__py3-none-any.whl

neomundi/__init__.py

@@ -0,0 +1,165 @@
+"""SDK Python NeoMundi — client de l'API de mesure du comportement des IA.
+
+SDK v2 : REST post-call et proxy de génération SSE.
+
+Principe directeur, qui explique chaque choix de ce paquet :
+
+    Le SDK transporte et expose les mesures. Il ne les interprète pas.
+
+Concrètement :
+
+* aucun seuil n'est embarqué — pas de `is_safe()`, pas de niveau de
+  qualité dérivé ;
+* `null` reste `None` : aucune valeur par défaut numérique n'existe dans
+  le code source ;
+* un champ dont la sémantique est ambiguë est exposé sous son chemin
+  complet, avec l'ambiguïté documentée, plutôt que converti.
+
+Lire `docs/LIMITES.md` avant d'interpréter un score.
+"""
+
+from __future__ import annotations
+
+__version__ = "2.0.0"
+
+#: Le contrat backend auquel ce SDK se réfère.
+#:
+#: `backend_commit` est le commit où les modèles de requête et de réponse
+#: ont été relevés. Il est inscrit ici parce qu'aucun OpenAPI figé
+#: n'existe côté serveur : nommer le commit est le seul moyen de dire à
+#: quoi ce SDK correspond.
+#:
+#: `measurement_version` est le seul numéro qui ait un sens scientifique :
+#: deux résultats produits sous deux valeurs différentes ne sont pas
+#: comparables pour une même entrée. Comparer la valeur ci-dessous à
+#: `result.audit.measurement_version` avertit d'un écart.
+#:
+#: `verified_measurement_versions` est une liste **plus large**, et la
+#: distinction compte. `measurement_version` dit de quel commit ce SDK a
+#: été dérivé ; `verified_measurement_versions` dit sous quelles versions
+#: de mesure la surface REST a été vérifiée identique à celle-là. Un
+#: écart entre les deux n'est donc pas une incompatibilité tant que la
+#: version servie figure dans cette liste — mais il reste un écart, et il
+#: reste décisif pour la **comparabilité** de deux séries.
+#:
+#: `3.3.1` y figure depuis le 2026-10-22, sur deux preuves énoncées en
+#: entier dans `KNOWN_LIMITATIONS.md` §6 : les fichiers de contrat du
+#: backend sont **inchangés** entre `68d6057` et le commit déployé
+#: `aeff13c`, et une réponse réellement émise par la production sous
+#: `3.3.1` a été rejouée sans avertissement ni champ inconnu. **Aucune
+#: des deux n'est un appel de ce SDK contre le service hébergé.**
+API_CONTRACT = {
+    "backend_commit": "68d6057cf620e430e6488da3cfcec9c471c75ed6",
+    "measurement_version": "3.3.0",
+    "verified_measurement_versions": ("3.3.0", "3.3.1"),
+    "normalizer_version": "1.0.0",
+    "route": "POST /v1/govern",
+    "stream_route": "POST /v1/govern/stream",
+    "stream_backend_commit": "aeff13cca717205c9ebbc83c5755ba6a22b284bb",
+    "stream_verification": "local_backend_source_and_offline_tests_only",
+    "contract_source": "govern-v3/app/models/responses.py, requests.py",
+    "openapi_frozen": False,
+}
+
+from ._retry import NO_RETRY, RetryPolicy
+from .streaming import (
+    GOVERN_STREAM_PATH,
+    GovernStream,
+    StreamError,
+    StreamEvent,
+    StreamInterruptedError,
+    StreamProtocolError,
+    StreamResult,
+    StreamServerError,
+)
+from .client import GOVERN_PATH, KEY_PREFIXES, NeoMundiClient
+from .errors import (
+    AggregateWithheldError,
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    InvalidResponseError,
+    NeoMundiError,
+    NetworkError,
+    PaymentRequiredError,
+    PayloadTooLargeError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    TransportError,
+    ValidationError,
+)
+from .models import (
+    AGGREGATE_FIELDS,
+    COVERAGE_SIGNALS,
+    Audit,
+    Baseline,
+    Citation,
+    Density,
+    Esi,
+    Governance,
+    GovernResult,
+    Measurement,
+    MeasurementState,
+    Metrics,
+    ParseWarning,
+    Quality,
+    RagGrounding,
+    Runtime,
+    SuspectPhrase,
+    UngroundedSnippet,
+)
+
+__all__ = [
+    "GOVERN_STREAM_PATH",
+    "GovernStream",
+    "StreamEvent",
+    "StreamResult",
+    "StreamError",
+    "StreamInterruptedError",
+    "StreamProtocolError",
+    "StreamServerError",
+    "__version__",
+    "API_CONTRACT",
+    # client
+    "NeoMundiClient",
+    "GOVERN_PATH",
+    "KEY_PREFIXES",
+    # retry
+    "RetryPolicy",
+    "NO_RETRY",
+    # modèles
+    "GovernResult",
+    "MeasurementState",
+    "COVERAGE_SIGNALS",
+    "AGGREGATE_FIELDS",
+    "ParseWarning",
+    "Governance",
+    "Measurement",
+    "Quality",
+    "Runtime",
+    "Metrics",
+    "Baseline",
+    "Esi",
+    "Density",
+    "RagGrounding",
+    "Audit",
+    "SuspectPhrase",
+    "Citation",
+    "UngroundedSnippet",
+    # erreurs
+    "NeoMundiError",
+    "ConfigurationError",
+    "TransportError",
+    "TimeoutError",
+    "NetworkError",
+    "InvalidResponseError",
+    "AggregateWithheldError",
+    "APIError",
+    "AuthenticationError",
+    "PaymentRequiredError",
+    "PayloadTooLargeError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+]

neomundi/_retry.py

@@ -0,0 +1,114 @@
+"""Politique de réessai — **désactivée par défaut**, et c'est une décision de fond.
+
+`POST /v1/govern` n'est pas idempotent. Relevé dans le backend au commit
+`68d6057` :
+
+* une **nouvelle observation** est créée à chaque appel —
+  `request_id = str(uuid.uuid4())`, `runtime_engine.py:162` ;
+* le **quota ou le portefeuille est débité** avant le travail —
+  `enforce_trial_quota(client)`, `governance.py:172` ;
+* une **ligne de métrologie** est écrite — `usage_events`,
+  `governance.py:586-626` ;
+* la **référence `delta_g` du compte est écrasée** dans Redis —
+  `governance.py:2088`.
+
+Aucun en-tête d'idempotence n'existe sur cette route : la recherche de
+`Idempotency-Key` dans `govern-v3/` ne renvoie aucune occurrence.
+
+Conséquence : un réessai automatique produirait une **seconde mesure
+facturée** et faussserait le `delta_g` de l'appel suivant. Le SDK ne
+réessaie donc rien de lui-même. Il expose `Retry-After` sur
+`RateLimitError` et laisse l'appelant décider.
+
+Une politique explicite reste disponible pour qui l'assume, avec un
+garde-fou qui n'est pas négociable : **un délai dépassé n'est jamais
+réessayé**. C'est le seul cas où le SDK ne peut pas savoir si la requête
+a été exécutée côté serveur. Un `503` *reçu*, lui, prouve qu'elle n'a pas
+abouti.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Tuple
+
+__all__ = ["RetryPolicy", "NO_RETRY"]
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Réessais sur les statuts HTTP que l'appelant juge sûrs.
+
+    À construire **explicitement**. Il n'existe pas de `retry=True` ni
+    d'entier magique : activer des réessais sur une route non idempotente
+    est une décision, pas une option de confort.
+
+    Args:
+        max_attempts: nombre total de tentatives, réessais inclus. `1`
+            signifie « aucun réessai ». Doit être ≥ 1.
+        on: statuts HTTP réessayables. Par défaut `(503,)` — un service
+            indisponible a répondu, donc il n'a pas traité la requête.
+            **429 n'y est pas par défaut** : une limite de débit atteinte
+            demande d'attendre `Retry-After`, ce que l'appelant maîtrise
+            mieux que le SDK.
+        backoff_initial: délai de la première attente, en secondes.
+        backoff_multiplier: facteur appliqué à chaque nouvelle attente.
+        backoff_max: plafond d'une attente, en secondes.
+        respect_retry_after: quand le serveur envoie `Retry-After`, ce
+            délai prime sur le calcul exponentiel.
+
+    Jamais réessayé, quelle que soit la politique :
+
+    * un **délai dépassé** (`TimeoutError`) — la requête a peut-être été
+      exécutée et facturée ;
+    * une **erreur réseau** (`NetworkError`) — même raison ;
+    * tout statut absent de `on`.
+    """
+
+    max_attempts: int = 1
+    on: Tuple[int, ...] = field(default=(503,))
+    backoff_initial: float = 0.5
+    backoff_multiplier: float = 2.0
+    backoff_max: float = 8.0
+    respect_retry_after: bool = True
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts doit être >= 1 (1 = aucun réessai).")
+        if self.backoff_initial < 0 or self.backoff_max < 0:
+            raise ValueError("Les délais de backoff doivent être positifs.")
+        if self.backoff_multiplier < 1:
+            raise ValueError("backoff_multiplier doit être >= 1.")
+
+    @property
+    def enabled(self) -> bool:
+        """`True` seulement si plus d'une tentative est autorisée."""
+        return self.max_attempts > 1
+
+    def should_retry(self, status_code: int, attempt: int) -> bool:
+        """`True` si un statut peut être réessayé à cette tentative.
+
+        `attempt` est le numéro de la tentative qui vient d'échouer, à
+        partir de 1.
+        """
+        if not self.enabled:
+            return False
+        if attempt >= self.max_attempts:
+            return False
+        return status_code in self.on
+
+    def delay_for(self, attempt: int, retry_after: "float | None" = None) -> float:
+        """Le délai à attendre après la tentative `attempt`.
+
+        `retry_after`, quand le serveur le fournit et que
+        `respect_retry_after` est actif, prime : le serveur sait mieux que
+        nous quand il acceptera la requête suivante.
+        """
+        if retry_after is not None and self.respect_retry_after:
+            return max(0.0, float(retry_after))
+        delay = self.backoff_initial * (self.backoff_multiplier ** max(0, attempt - 1))
+        return min(delay, self.backoff_max)
+
+
+#: La politique par défaut : aucune tentative supplémentaire.
+NO_RETRY = RetryPolicy(max_attempts=1)