kaneme 1.16.1__tar.gz

kaneme-1.16.1/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: kaneme
+Version: 1.16.1
+Summary: SDK Python officiel pour l'API d'identité écrite Kaneme
+License-Expression: MIT
+Project-URL: Homepage, https://kaneme.com
+Project-URL: Documentation, https://kaneme.com/developers
+Keywords: kaneme,writing,voice,authorship,api
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# kaneme
+
+```python
+from kaneme import KanemeClient
+
+kaneme = KanemeClient(api_key="kaneme_…")
+verdict = kaneme.verify_authorship(text="…", question="q1")
+```
+
+Sur Q2, la réponse contient aussi `explanation` avec les écarts observés de
+`cadence`, `registre`, `structure` et `lexique`. Ils éclairent le verdict sans
+prétendre décomposer la probabilité produite par la couche profonde :
+
+```python
+q2 = kaneme.verify_authorship(text="…", question="q2", profile_id=profile_id)
+for factor in q2.get("explanation", {}).get("factors", []):
+    print(factor["label"], factor["status"], factor["detail"])
+```
+
+Le SDK n’ajoute aucune dépendance. Les méthodes d’écriture acceptent
+`idempotency_key`. Les erreurs lèvent `KanemeAPIError`.
+
+## Sécurité du transport
+
+Depuis la version 1.16.1, le client impose HTTPS hors développement local,
+refuse toute redirection vers une autre origine et coupe les réponses trop
+volumineuses. Ces protections empêchent qu’une redirection malveillante reçoive
+la clé API et qu’une réponse incontrôlée épuise la mémoire du processus :
+
+```python
+kaneme = KanemeClient(
+    api_key="kaneme_…",
+    timeout=15,
+    max_response_bytes=4 * 1024 * 1024,
+)
+```
+
+La limite par défaut est de 8 Mio (64 Mio au maximum). Une redirection refusée
+lève `KanemeRedirectError` ; un dépassement lève `KanemeResponseTooLarge`.
+
+## Cadence et identifiant de requête
+
+Chaque réponse — succès compris — porte la cadence appliquée. `on_response` la
+donne, sur les appels qui marchent comme sur les refus :
+
+```python
+def tracer(meta):
+    if meta.rate_limit.remaining is not None and meta.rate_limit.remaining < 5:
+        time.sleep(1)          # ralentir AVANT le refus
+    print(meta.request_id)     # à journaliser : c'est ce qu'on te demandera
+
+kaneme = KanemeClient(api_key="kaneme_…", on_response=tracer)
+```
+
+`Retry-After` ne part que sur un 429, et se lit alors sur l’erreur :
+`error.metadata.retry_after`. Sur un succès il vaut `None` — un ordre d’attendre
+n’a pas de sens sur un appel qui a réussi.
+
+## Certificats et cycle de vie
+
+Une clé API dotée explicitement de `voice:certify` peut préparer puis publier
+un certificat. Les liens de page, JSON et badge sont utilisables sans ouvrir le
+compte Kaneme :
+
+```python
+preparation = kaneme.prepare_certificate(document_id, display_name="Alice")
+# En OAuth, ouvrir preparation["approvalUrl"] et attendre la validation humaine.
+certificate = kaneme.publish_certificate(
+    preparation["approvalId"],
+    idempotency_key=f"certificate-{preparation['approvalId']}",
+)
+print(certificate["certificateUrl"], certificate["verificationUrl"], certificate["badgeSvgUrl"])
+```
+
+`list_trash`, `list_project_contexts` et `manage_lifecycle` couvrent la
+corbeille, la restauration, l’archivage, l’expiration et la révocation. Il n’y a
+aucune purge définitive dans le SDK ; utilisez `dry_run=True` avant une mutation
+sensible et limitez chaque lot à 10 éléments.

kaneme-1.16.1/README.md

@@ -0,0 +1,78 @@
+# kaneme
+
+```python
+from kaneme import KanemeClient
+
+kaneme = KanemeClient(api_key="kaneme_…")
+verdict = kaneme.verify_authorship(text="…", question="q1")
+```
+
+Sur Q2, la réponse contient aussi `explanation` avec les écarts observés de
+`cadence`, `registre`, `structure` et `lexique`. Ils éclairent le verdict sans
+prétendre décomposer la probabilité produite par la couche profonde :
+
+```python
+q2 = kaneme.verify_authorship(text="…", question="q2", profile_id=profile_id)
+for factor in q2.get("explanation", {}).get("factors", []):
+    print(factor["label"], factor["status"], factor["detail"])
+```
+
+Le SDK n’ajoute aucune dépendance. Les méthodes d’écriture acceptent
+`idempotency_key`. Les erreurs lèvent `KanemeAPIError`.
+
+## Sécurité du transport
+
+Depuis la version 1.16.1, le client impose HTTPS hors développement local,
+refuse toute redirection vers une autre origine et coupe les réponses trop
+volumineuses. Ces protections empêchent qu’une redirection malveillante reçoive
+la clé API et qu’une réponse incontrôlée épuise la mémoire du processus :
+
+```python
+kaneme = KanemeClient(
+    api_key="kaneme_…",
+    timeout=15,
+    max_response_bytes=4 * 1024 * 1024,
+)
+```
+
+La limite par défaut est de 8 Mio (64 Mio au maximum). Une redirection refusée
+lève `KanemeRedirectError` ; un dépassement lève `KanemeResponseTooLarge`.
+
+## Cadence et identifiant de requête
+
+Chaque réponse — succès compris — porte la cadence appliquée. `on_response` la
+donne, sur les appels qui marchent comme sur les refus :
+
+```python
+def tracer(meta):
+    if meta.rate_limit.remaining is not None and meta.rate_limit.remaining < 5:
+        time.sleep(1)          # ralentir AVANT le refus
+    print(meta.request_id)     # à journaliser : c'est ce qu'on te demandera
+
+kaneme = KanemeClient(api_key="kaneme_…", on_response=tracer)
+```
+
+`Retry-After` ne part que sur un 429, et se lit alors sur l’erreur :
+`error.metadata.retry_after`. Sur un succès il vaut `None` — un ordre d’attendre
+n’a pas de sens sur un appel qui a réussi.
+
+## Certificats et cycle de vie
+
+Une clé API dotée explicitement de `voice:certify` peut préparer puis publier
+un certificat. Les liens de page, JSON et badge sont utilisables sans ouvrir le
+compte Kaneme :
+
+```python
+preparation = kaneme.prepare_certificate(document_id, display_name="Alice")
+# En OAuth, ouvrir preparation["approvalUrl"] et attendre la validation humaine.
+certificate = kaneme.publish_certificate(
+    preparation["approvalId"],
+    idempotency_key=f"certificate-{preparation['approvalId']}",
+)
+print(certificate["certificateUrl"], certificate["verificationUrl"], certificate["badgeSvgUrl"])
+```
+
+`list_trash`, `list_project_contexts` et `manage_lifecycle` couvrent la
+corbeille, la restauration, l’archivage, l’expiration et la révocation. Il n’y a
+aucune purge définitive dans le SDK ; utilisez `dry_run=True` avant une mutation
+sensible et limitez chaque lot à 10 éléments.

kaneme-1.16.1/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kaneme"
+version = "1.16.1"
+description = "SDK Python officiel pour l'API d'identité écrite Kaneme"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+keywords = ["kaneme", "writing", "voice", "authorship", "api"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://kaneme.com"
+Documentation = "https://kaneme.com/developers"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+kaneme = ["contract.json", "py.typed"]

kaneme-1.16.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kaneme-1.16.1/src/kaneme/__init__.py

@@ -0,0 +1,35 @@
+from .client import (
+    CORE_OPERATION_IDS,
+    KANEME_RATE_LIMIT_FIELDS,
+    KANEME_RESPONSE_HEADERS,
+    KANEME_RESPONSE_METADATA_FIELDS,
+    MAX_CONFIGURABLE_RESPONSE_BYTES,
+    DEFAULT_MAX_RESPONSE_BYTES,
+    SDK_VERSION,
+    KanemeAPIError,
+    KanemeClient,
+    KanemeRedirectError,
+    KanemeRateLimit,
+    KanemeResponseTooLarge,
+    KanemeResponseMetadata,
+    KanemeTransportError,
+)
+from . import types as types
+
+__all__ = [
+    "CORE_OPERATION_IDS",
+    "KANEME_RATE_LIMIT_FIELDS",
+    "KANEME_RESPONSE_HEADERS",
+    "KANEME_RESPONSE_METADATA_FIELDS",
+    "MAX_CONFIGURABLE_RESPONSE_BYTES",
+    "DEFAULT_MAX_RESPONSE_BYTES",
+    "SDK_VERSION",
+    "KanemeAPIError",
+    "KanemeClient",
+    "KanemeRedirectError",
+    "KanemeRateLimit",
+    "KanemeResponseTooLarge",
+    "KanemeResponseMetadata",
+    "KanemeTransportError",
+    "types",
+]

kaneme-1.16.1/src/kaneme/client.py

@@ -0,0 +1,358 @@
+"""Client stdlib pour le contrat Kaneme.
+
+⚠️ LA VERSION SUIT LE CONTRAT, PAS SON PROPRE RYTHME. Elle est restée à 1.5.0
+jusqu'au 22/08 pendant que le contrat passait à 1.9.0 — et pendant que ce client
+implémentait déjà la 1.8 (`X-Kaneme-Client`). Le numéro part dans cet en-tête à
+chaque appel : faux, il fausse aussi ce que le serveur croit savoir des clients
+qui l'appellent. Rien ne le comparait au contrat ; `sdk-contract.test.ts` le fait
+maintenant, en LISANT ce fichier et `pyproject.toml`.
+
+🔴 CE CLIENT JETAIT LES EN-TÊTES (corrigé le 22/08). Il rendait le corps JSON et
+rien d'autre : ni `X-RateLimit-*`, ni `Retry-After`, ni `X-Request-Id`. Sur ce
+point il était resté au contrat 1.5, où la cadence n'était qu'un nombre écrit
+dans la documentation. La conséquence est le contraire de ce que le contrat
+demande : la seule façon de se cadencer était d'attendre le 429, donc de
+PROVOQUER le refus qu'on veut éviter — et l'appelant refusé n'avait même pas la
+durée à attendre. Il rend maintenant la même enveloppe que le SDK TypeScript,
+champ pour champ (`KanemeResponseMetadata`), et `sdk-contract.test.ts` refuse
+qu'un des deux dérive de l'autre.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional, cast
+from urllib.error import HTTPError
+from urllib.parse import quote, urlencode, urljoin, urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+from .types import (
+    KanemeAddVoiceAssetResult,
+    KanemeAuthorshipResult,
+    KanemeBeliefListResult,
+    KanemeCertificatePreparationResult,
+    KanemeCertifyResult,
+    KanemeComparisonResult,
+    KanemeCreateVoiceResult,
+    KanemeGenerateResult,
+    KanemeImproveResult,
+    KanemeLifecycleResult,
+    KanemeProjectContextListResult,
+    KanemeScoreResult,
+    KanemeSignalResult,
+    KanemeSubvoiceListResult,
+    KanemeTrashListResult,
+    KanemeVoiceAssetListResult,
+    KanemeVoiceListResult,
+    KanemeVoiceResult,
+)
+
+SDK_VERSION = "1.16.1"
+DEFAULT_MAX_RESPONSE_BYTES = 8 * 1024 * 1024
+MAX_CONFIGURABLE_RESPONSE_BYTES = 64 * 1024 * 1024
+CORE_OPERATION_IDS = (
+    "listVoices", "getVoice", "createVoice", "listVoiceAssets", "addVoiceAsset",
+    "listBeliefs", "listSubvoices", "scoreText", "verifyAuthorship", "compareTexts",
+    "certifyDocument", "prepareCertificate", "publishCertificate",
+    "listProjectContexts", "listTrash", "manageLifecycle",
+    "generateInVoice", "improveInVoice", "recordSignal",
+)
+KANEME_RATE_LIMIT_FIELDS = ("limit", "remaining", "window")
+KANEME_RESPONSE_METADATA_FIELDS = ("status", "request_id", "retry_after", "rate_limit")
+KANEME_RESPONSE_HEADERS = {
+    "requestId": "X-Request-Id",
+    "retryAfter": "Retry-After",
+    "rateLimitLimit": "X-RateLimit-Limit",
+    "rateLimitRemaining": "X-RateLimit-Remaining",
+    "rateLimitWindow": "X-RateLimit-Window",
+}
+
+
+@dataclass(frozen=True)
+class KanemeRateLimit:
+    """La cadence AU PASSAGE DE LA GARDE : le jeton de cet appel est déjà décompté.
+
+    ⚠️ `window` reste le TEXTE de l'en-tête, comme dans le SDK TypeScript. Les
+    deux SDK décrivent le même en-tête : qu'un seul le convertisse suffirait à
+    ce qu'un intégrateur qui passe de l'un à l'autre écrive un test faux.
+    """
+
+    limit: Optional[int]
+    remaining: Optional[int]
+    window: Optional[str]
+
+
+@dataclass(frozen=True)
+class KanemeResponseMetadata:
+    """L'enveloppe d'exploitation d'UNE réponse — succès compris.
+
+    `retry_after` ne part que sur un refus : sur un succès, un client bien écrit
+    obéirait à un ordre d'attendre qu'on n'a pas voulu donner. La bonne façon de
+    se cadencer est de lire `rate_limit.remaining` sur les réponses qui MARCHENT.
+    """
+
+    status: int
+    request_id: Optional[str]
+    retry_after: Optional[str]
+    rate_limit: KanemeRateLimit
+
+
+def _header_number(value: Optional[str]) -> Optional[int]:
+    if value is None or not value.strip():
+        return None
+    try:
+        return int(value.strip())
+    except ValueError:
+        return None
+
+
+def _metadata(status: int, headers: Any) -> KanemeResponseMetadata:
+    # `headers` est un `email.message.Message` des deux côtés — réponse comme
+    # HTTPError — donc sa lecture est insensible à la casse. Ça compte : ces
+    # en-têtes traversent des proxys qui les renormalisent.
+    return KanemeResponseMetadata(
+        status=status,
+        request_id=headers.get(KANEME_RESPONSE_HEADERS["requestId"]),
+        retry_after=headers.get(KANEME_RESPONSE_HEADERS["retryAfter"]),
+        rate_limit=KanemeRateLimit(
+            limit=_header_number(headers.get(KANEME_RESPONSE_HEADERS["rateLimitLimit"])),
+            remaining=_header_number(headers.get(KANEME_RESPONSE_HEADERS["rateLimitRemaining"])),
+            window=headers.get(KANEME_RESPONSE_HEADERS["rateLimitWindow"]),
+        ),
+    )
+
+
+class KanemeAPIError(RuntimeError):
+    def __init__(self, status: int, code: Optional[str], message: str, response: Any = None,
+                 metadata: Optional[KanemeResponseMetadata] = None):
+        super().__init__(message)
+        self.status, self.code, self.response = status, code, response
+        # L'enveloppe du refus. Sur un 429, `metadata.retry_after` porte les
+        # secondes à attendre — sans elle, un client refusé ne peut que deviner,
+        # et un client qui devine réessaie trop tôt.
+        self.metadata = metadata
+
+
+class KanemeTransportError(RuntimeError):
+    """Échec local avant qu'une réponse Kaneme fiable soit disponible."""
+
+
+class KanemeRedirectError(KanemeTransportError):
+    """Redirection refusée pour ne pas divulguer la clé API à un autre origin."""
+
+
+class KanemeResponseTooLarge(KanemeTransportError):
+    """Réponse interrompue avant qu'elle n'épuise la mémoire du processus."""
+
+
+def _origin(raw_url: str) -> tuple[str, str, int]:
+    parsed = urlsplit(raw_url)
+    scheme = parsed.scheme.lower()
+    host = (parsed.hostname or "").lower()
+    port = parsed.port or (443 if scheme == "https" else 80)
+    return scheme, host, port
+
+
+def _validate_base_url(raw_url: str) -> str:
+    parsed = urlsplit(raw_url)
+    host = (parsed.hostname or "").lower()
+    local = host in {"localhost", "127.0.0.1", "::1"}
+    if parsed.scheme not in ({"http", "https"} if local else {"https"}):
+        raise ValueError("Kaneme base_url must use HTTPS (HTTP is allowed only for localhost)")
+    if not host or parsed.username is not None or parsed.password is not None:
+        raise ValueError("Kaneme base_url must be an absolute URL without credentials")
+    if parsed.query or parsed.fragment:
+        raise ValueError("Kaneme base_url must not contain a query or fragment")
+    return raw_url.rstrip("/")
+
+
+class _SameOriginRedirectHandler(HTTPRedirectHandler):
+    """Autorise seulement les redirections qui gardent exactement le même origin."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: ANN001
+        target = urljoin(req.full_url, newurl)
+        if _origin(req.full_url) != _origin(target):
+            raise KanemeRedirectError(
+                "Kaneme refused a cross-origin redirect to protect the Authorization header"
+            )
+        if urlsplit(req.full_url).scheme == "https" and urlsplit(target).scheme != "https":
+            raise KanemeRedirectError("Kaneme refused an HTTPS downgrade redirect")
+        return super().redirect_request(req, fp, code, msg, headers, target)
+
+
+# Nom volontairement patchable dans les tests, comme l'ancien `urlopen`.
+urlopen = build_opener(_SameOriginRedirectHandler()).open
+
+
+def _read_bounded(response: Any, max_bytes: int) -> bytes:
+    content_length = response.headers.get("Content-Length")
+    if content_length:
+        try:
+            if int(content_length) > max_bytes:
+                raise KanemeResponseTooLarge(
+                    f"Kaneme response exceeds the {max_bytes}-byte limit"
+                )
+        except ValueError:
+            pass
+    raw = response.read(max_bytes + 1)
+    if len(raw) > max_bytes:
+        raise KanemeResponseTooLarge(
+            f"Kaneme response exceeds the {max_bytes}-byte limit"
+        )
+    return raw
+
+
+class KanemeClient:
+    def __init__(self, api_key: str, base_url: str = "https://kaneme.com", timeout: float = 30.0,
+                 on_response: Optional[Callable[[KanemeResponseMetadata], None]] = None,
+                 max_response_bytes: int = DEFAULT_MAX_RESPONSE_BYTES):
+        """`on_response` est appelé sur CHAQUE réponse, succès comme erreur.
+
+        ⚠️ Il se pose sur le client, là où le SDK TypeScript l'accepte aussi par
+        appel. Ce n'est pas un oubli : ici les méthodes passent leurs `**kwargs`
+        au corps de la requête ou à sa query, donc un paramètre réservé de plus
+        deviendrait un champ envoyé au serveur le jour où une opération
+        s'appellerait comme lui.
+        """
+        if not api_key:
+            raise ValueError("Kaneme api_key is required")
+        if timeout <= 0:
+            raise ValueError("Kaneme timeout must be greater than zero")
+        if not 1 <= max_response_bytes <= MAX_CONFIGURABLE_RESPONSE_BYTES:
+            raise ValueError(
+                f"Kaneme max_response_bytes must be between 1 and {MAX_CONFIGURABLE_RESPONSE_BYTES}"
+            )
+        self.api_key = api_key
+        self.base_url = _validate_base_url(base_url)
+        self.timeout = timeout
+        self.max_response_bytes = max_response_bytes
+        self.on_response = on_response
+
+    def _emit(self, metadata: KanemeResponseMetadata) -> None:
+        if self.on_response is not None:
+            self.on_response(metadata)
+
+    def _request(self, method: str, path: str, body: Optional[Dict[str, Any]] = None,
+                 idempotency_key: Optional[str] = None) -> Any:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "X-Kaneme-Client": f"kaneme-sdk-python/{SDK_VERSION}",
+            # urllib envoie sinon ``Python-urllib/x.y``. Les protections bot de
+            # Cloudflare peuvent le refuser avant même que la requête atteigne
+            # l'API. Une identité explicite et versionnée rend le SDK utilisable
+            # derrière le même edge que le client TypeScript.
+            "User-Agent": f"kaneme-sdk-python/{SDK_VERSION}",
+        }
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        request = Request(self.base_url + path, data=data, headers=headers, method=method)
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                self._emit(_metadata(response.status, response.headers))
+                raw = _read_bounded(response, self.max_response_bytes)
+                return json.loads(raw) if raw else None
+        except HTTPError as error:
+            metadata = _metadata(error.code, error.headers)
+            self._emit(metadata)
+            raw = _read_bounded(error, min(self.max_response_bytes, 1024 * 1024))
+            try:
+                payload = json.loads(raw) if raw else {}
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                payload = {}
+            raise KanemeAPIError(
+                error.code,
+                payload.get("code"),
+                payload.get("error", f"Kaneme API error {error.code}"),
+                payload,
+                metadata,
+            ) from error
+
+    @staticmethod
+    def _query(**params: Any) -> str:
+        values = {
+            key: str(value).lower() if isinstance(value, bool) else value
+            for key, value in params.items()
+            if value is not None
+        }
+        return "?" + urlencode(values) if values else ""
+
+    def list_voices(self) -> KanemeVoiceListResult:
+        return cast(KanemeVoiceListResult, self._request("GET", "/api/v1/voices"))
+
+    def get_voice(self, profile_id=None) -> KanemeVoiceResult:
+        return cast(KanemeVoiceResult, self._request("GET", "/api/v1/voice" + self._query(profileId=profile_id)))
+
+    def create_voice(self, *, idempotency_key=None, **input) -> KanemeCreateVoiceResult:
+        return cast(KanemeCreateVoiceResult, self._request("POST", "/api/v1/voices", input, idempotency_key))
+
+    def list_voice_assets(self, **params) -> KanemeVoiceAssetListResult:
+        return cast(KanemeVoiceAssetListResult, self._request("GET", "/api/v1/voice/assets" + self._query(**params)))
+
+    def add_voice_asset(self, *, idempotency_key=None, **input) -> KanemeAddVoiceAssetResult:
+        return cast(KanemeAddVoiceAssetResult, self._request("POST", "/api/v1/voice/assets", input, idempotency_key))
+
+    def list_beliefs(self, **params) -> KanemeBeliefListResult:
+        return cast(KanemeBeliefListResult, self._request("GET", "/api/v1/voice/beliefs" + self._query(**params)))
+
+    def list_subvoices(self, profile_id=None) -> KanemeSubvoiceListResult:
+        return cast(KanemeSubvoiceListResult, self._request("GET", "/api/v1/voice/subvoices" + self._query(profileId=profile_id)))
+
+    def score_text(self, text, profile_id=None) -> KanemeScoreResult:
+        return cast(KanemeScoreResult, self._request("POST", "/api/v1/score", {"text": text, "profileId": profile_id}))
+
+    def verify_authorship(self, text, question="q2", profile_id=None) -> KanemeAuthorshipResult:
+        return cast(KanemeAuthorshipResult, self._request("POST", "/api/v1/verify", {"text": text, "question": question, "profileId": profile_id}))
+
+    def compare_texts(self, text, reference=None, reference_profile_id=None, question="q2") -> KanemeComparisonResult:
+        return cast(KanemeComparisonResult, self._request("POST", "/api/v1/compare", {"text": text, "reference": reference, "referenceProfileId": reference_profile_id, "question": question}))
+
+    def certify_document(self, document_id, display_name=None, idempotency_key=None) -> KanemeCertifyResult:
+        return cast(KanemeCertifyResult, self._request("POST", "/api/v1/certify", {"documentId": document_id, "displayName": display_name}, idempotency_key))
+
+    def prepare_certificate(self, document_id, display_name=None) -> KanemeCertificatePreparationResult:
+        return cast(KanemeCertificatePreparationResult, self._request(
+            "POST", "/api/v1/certificates/prepare",
+            {"documentId": document_id, "displayName": display_name},
+        ))
+
+    def publish_certificate(self, approval_id, idempotency_key=None) -> KanemeCertifyResult:
+        return cast(KanemeCertifyResult, self._request(
+            "POST", "/api/v1/certificates/publish",
+            {"approvalId": approval_id}, idempotency_key,
+        ))
+
+    def list_project_contexts(self, project_id, include_archived=None, include_trashed=None) -> KanemeProjectContextListResult:
+        query = self._query(includeArchived=include_archived, includeTrashed=include_trashed)
+        path = "/api/v1/projects/" + quote(str(project_id), safe="") + "/contexts" + query
+        return cast(KanemeProjectContextListResult, self._request("GET", path))
+
+    def list_trash(self) -> KanemeTrashListResult:
+        return cast(KanemeTrashListResult, self._request("GET", "/api/v1/trash"))
+
+    def manage_lifecycle(self, items, dry_run=None, idempotency_key=None) -> KanemeLifecycleResult:
+        body = {"items": items}
+        if dry_run is not None:
+            body["dryRun"] = dry_run
+        return cast(KanemeLifecycleResult, self._request(
+            "POST", "/api/v1/lifecycle", body, idempotency_key,
+        ))
+
+    def generate_in_voice(self, prompt, idempotency_key=None, **input) -> KanemeGenerateResult:
+        return cast(KanemeGenerateResult, self._request("POST", "/api/v1/generate", {"prompt": prompt, **input}, idempotency_key))
+
+    def improve_in_voice(self, text, profile_id=None, idempotency_key=None) -> KanemeImproveResult:
+        return cast(KanemeImproveResult, self._request("POST", "/api/v1/improve", {"text": text, "profileId": profile_id}, idempotency_key))
+
+    def record_signal(self, kind, *, idempotency_key=None, **input) -> KanemeSignalResult:
+        """Fait APPRENDRE la voix : gratuit, et le seul geste qui la fasse evoluer.
+
+        Passe le `format` du canal — sans lui, la sous-voix de ce canal n apprend
+        rien. Sur un rejet, `proposed`/`kept` sont deux TEXTES : le signal est
+        derive serveur, jamais une liste de termes.
+        """
+        return cast(KanemeSignalResult, self._request("POST", "/api/v1/signal", {"kind": kind, **input}, idempotency_key))