Metadata-Version: 2.4
Name: kaneme
Version: 2.10.0
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.
