> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zelinqa.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Référence SDK
> Installer les clients officiels, conduire une session et gérer une configuration.
Les SDK officiels appellent la même [API REST](/fr/integrations/rest-api). Ils gèrent les identifiants de décision et la version d'état pendant une conversation. Votre application conserve seulement l'identifiant de session si elle veut reprendre après un redémarrage.
| | Python | TypeScript |
| - | - | - |
| Paquet | [`zelinqa` sur PyPI](https://pypi.org/project/zelinqa/) | [`@zelinqa/sdk` sur npm](https://www.npmjs.com/package/@zelinqa/sdk) |
| Installation | `uv add zelinqa` ; alternative : `python -m pip install zelinqa` | `npm install @zelinqa/sdk` |
| Environnement | Python 3.11+ | Node.js 22+, ESM ou CommonJS |
| Client runtime | `ZelinqaClient` ou `AsyncZelinqaClient` | `ZelinqaClient` |
| Client de configuration | `ZelinqaConfigurationClient` ou sa variante asynchrone | `ZelinqaConfigurationClient` |
Installez le SDK et réalisez votre premier échange dans le langage de votre choix.
## Mise à jour et versions
**Les SDK installés ne se mettent pas à jour automatiquement.** Exécutez les commandes depuis votre projet, puis redémarrez ou redéployez votre application.
Dans un projet uv qui utilise déjà `zelinqa`, mettez à jour le verrouillage et l'environnement, puis affichez la version installée :
```bash theme={null}
uv sync --upgrade-package zelinqa
uv run python -c "from importlib.metadata import version; print(version('zelinqa'))"
```
La mise à jour respecte la contrainte de `pyproject.toml`. Si elle fixe une version exacte, changez-la explicitement. Par exemple, pour choisir `1.0.1` :
```bash theme={null}
uv add "zelinqa==1.0.1"
```
Si vous utilisez pip plutôt que uv, dans l'environnement virtuel de votre application :
```bash theme={null}
python -m pip install --upgrade zelinqa
python -c "from importlib.metadata import version; print(version('zelinqa'))"
```
Avec pip, mettez aussi à jour votre fichier de dépendances ou votre verrouillage selon votre outil : cette commande ne les réécrit pas.
Dans le projet npm qui utilise déjà `@zelinqa/sdk` :
```bash theme={null}
npm update @zelinqa/sdk
npm ls @zelinqa/sdk --depth=0
```
La mise à jour respecte la plage de versions de `package.json` et met à jour `package-lock.json`. Une version exacte reste fixe. Pour choisir explicitement `1.0.1` :
```bash theme={null}
npm install --save-exact @zelinqa/sdk@1.0.1
```
### Vérifier avant de déployer
1. Lisez le [changelog](/fr/changelog) et les [changements du SDK](https://github.com/Zelinqa/zelinqa-sdk/blob/main/CHANGELOG.md).
2. Testez une [conversation complète](/fr/guides/complete-conversation) sur un domaine de démonstration : démarrage, réponse libre ou choix selon votre usage, progression et arrêt. Testez aussi la reprise et les erreurs que votre application gère.
3. Versionnez le manifeste et le verrouillage (`pyproject.toml` + `uv.lock`, ou `package.json` + `package-lock.json`) pour déployer les mêmes dépendances que celles testées. En production, évitez une mise à jour non contrôlée vers la dernière version.
Les commandes de version ci-dessus n'appellent pas l'API Zelinqa ; une conversation de test utilise votre clé et vos quotas. **Mettre à jour le SDK ne republie pas votre domaine** et ne change pas la version de configuration attachée à une session existante. Le MCP a son [propre environnement et sa propre mise à jour](/fr/integrations/mcp#versions).
## Clés et permissions
Créez une clé dans [Zelinqa Studio](/fr/studio/api-keys) pour un **domaine publié**. Une clé est liée à ce domaine et à des permissions :
| Client | Permission nécessaire | Usage |
| - | - | - |
| Runtime | `runtime` | Sessions, prochaine question, contexte, état, feedback |
| Configuration | `configuration:read` | Lire la version publiée et les questions |
| Configuration | `configuration:read` **et** `configuration:write` | Lire ou modifier le brouillon |
| Configuration | `configuration:publish` + `configuration:read` | Publier, puis suivre la compilation ; le journal d'audit utilise `configuration:publish` |
La clé runtime ne donne pas accès à la configuration. Vous pouvez créer plusieurs clés pour un même domaine, avec les seules permissions utiles à chaque service. Pour plusieurs domaines, utilisez une clé par domaine.
Ces clients s'exécutent côté serveur. Ne placez jamais une clé API dans un navigateur, une application mobile, un dépôt public ou une conversation avec un modèle.
En Python, `ZelinqaClient()` lit `ZELINQA_API_KEY`. Pour la configuration, `ZelinqaConfigurationClient()` cherche d'abord `ZELINQA_CONFIGURATION_API_KEY`, puis `ZELINQA_API_KEY`. En TypeScript, fournissez explicitement `apiKey` au constructeur. L'URL par défaut est `https://api.zelinqa.ai` ; une URL HTTP locale peut être passée pour le développement, pas pour une clé réelle sur un réseau non fiable.
## Cycle d'une conversation
1. `start_session` / `startSession` crée une session sur la version publiée active.
2. `session.next()` renvoie la première décision, sans réponse précédente.
3. Votre application affiche `candidates[0].text` et recueille la réponse réelle.
4. `session.answer(...)` rattache cette réponse à la décision en attente **et renvoie la décision suivante**. Ne rappelez pas `next()` juste pour obtenir cette question.
5. `session.refresh()` relit l'état ; `session.submit_feedback(...)` enregistre un résultat métier réellement observé.
Pour une question ouverte, envoyez les mots de la personne (`user_text` / `userText`). Pour une question fermée ou semi-ouverte, `choice_labels` / `choiceLabels` accepte les **libellés exacts affichés** ; les identifiants des choix sont résolus localement. Une semi-ouverte peut ajouter `free_text` / `freeText`. Pour une absence de réponse ou un refus réels, utilisez `asked_no_answer` ou `refused` sans texte. Les choix seuls et ces deux issues ne nécessitent pas d'analyse par modèle ; le texte libre peut en nécessiter une.
Le handle conserve `state_version`. Utilisez-le séquentiellement : deux mutations concurrentes de la même session peuvent produire un conflit. Après une interruption ou un `ZelinqaStateVersionConflictError`, relisez l'état et réconciliez la réponse avant de réessayer ; ne la rejouez pas à l'aveugle. Une session déjà ouverte reste attachée à sa version publiée même après une nouvelle publication.
## Autres opérations
| Besoin | Python | TypeScript |
| - | - | - |
| Reprendre une session | `resume_session(id)` | `resumeSession(id)` |
| Ajouter du contexte ou des données confirmées sans tour | `session.apply_events(...)` | `session.applyEvents(...)` |
| Relire la progression | `session.refresh()` | `session.refresh()` |
| Enregistrer le résultat | `session.submit_feedback(...)` | `session.submitFeedback(...)` |
| Lire la configuration | `get_configuration`, `list_questions`, `iter_questions` | `getConfiguration`, `listQuestions`, `iterateQuestions` |
| Modifier et publier un brouillon | `apply_changes`, `publish`, `wait_for_compilation` | `applyChanges`, `publish`, `waitForCompilation` |
| Exporter les questions, lire l'audit | `export_questions_csv`, `list_audit` | `exportQuestionsCsv`, `listAudit` |
Une publication est asynchrone : vérifiez le statut terminal de compilation avant de considérer la nouvelle version active. Les erreurs HTTP ont des classes typées, notamment pour l'authentification, les permissions, les données invalides, les conflits et la limitation de débit. Les SDK réessaient les erreurs transitoires avec une clé d'idempotence stable par appel logique ; un conflit métier n'est pas masqué.
Pour les options, les modèles de réponse et les exemples de configuration, consultez les [guides Python](https://github.com/Zelinqa/zelinqa-sdk/blob/main/python/docs/usage.md) et [TypeScript](https://github.com/Zelinqa/zelinqa-sdk/blob/main/typescript/docs/usage.md), ou la [référence API](/fr/api-reference/overview).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.