SDK de la Navin Platform

Cette rubrique documente les quatre SDK et la ligne de commande qui appellent le Control Plane de la Navin Platform et le Navin Manager. Chaque SDK n'appelle que les routes documentées de l'API v1, renvoie des erreurs typées avec des messages en anglais et en français, reprend les échecs transitoires avec une clé d'idempotence, et valide les documents contre les mêmes contrats v1.

English version: README.md

SDK et CLI

SDK	Paquet	Installation	Environnement	Guide	Référence
Python	enterprise-ai (import enterprise_ai)	Harbor sdk/python, puis pip install de la wheel	Python 3.10+	SDK Python	référence
TypeScript	@enterprise-ai/sdk	Harbor sdk/typescript, puis npm install de l'archive	Node.js 18+, navigateurs, Deno, Bun	SDK TypeScript	référence
Go	module de sdks/go (paquet eai)	Harbor sdk/go, puis une directive replace dans go.mod	Go 1.26+	SDK Go	référence
Java	io.enterpriseai:enterprise-ai-java (starter Spring Boot enterprise-ai-spring)	Harbor sdk/java, puis une dépendance Maven ou Gradle	Java 17+	SDK Java	référence
CLI	commande enterprise-ai (dans le paquet Python)	Harbor sdk/python, puis pipx install de la wheel	Python 3.10+	guide de la CLI	référence de la CLI

Où les SDK sont hébergés

Les paquets des SDK sont hébergés dans le registre Harbor de l'organisation, dans le projet sdk, sous forme d'artefacts OCI : sdk/python, sdk/typescript, sdk/go et sdk/java. Le tag d'un artefact est la version du SDK (par exemple 1.0.2). Rien n'est téléchargé depuis un registre public ni depuis un dépôt de sources.

Le registre Navinspire est registry.navinspire.ai. L'équipe plateforme fournit un compte robot qui a le droit de lecture (pull) sur le projet sdk. Si votre organisation réplique le projet sdk dans son propre Harbor, remplacez l'adresse par celle du miroir.

oras login registry.navinspire.ai
oras pull registry.navinspire.ai/sdk/python:1.0.2 -o sdk-python

Guides associés :

Guide	Contenu
SDK et CLI du Navin Manager	Le client du manager de chaque SDK et enterprise-ai manager : hôtes, clusters, services, HA, sauvegardes, restaurations, PRA.
Voix en temps réel	@enterprise-ai/realtime et les clients vocaux en direct de Python et de Go.
Contrats v1	Les contrats JSON Schema et leur validation, en ligne et hors ligne.

Les références générées listent chaque classe, méthode, paramètre, modèle et champ public de chaque SDK, en anglais et en français ; python3 tools/docs/gen_sdk_reference.py les écrit et --check signale une page périmée.

Comportement commun

Sujet	Règle dans chaque SDK
URL de base	https obligatoire, http seulement pour localhost, 127.0.0.1 et ::1 ; redirections jamais suivies
Authentification	clé API (X-API-Key) ou jeton OIDC (Authorization: Bearer) ; le tenant vient de l'identifiant
Erreurs	enveloppe {"error": {"code", "message", "message_i18n", "details", "request_id"}} traduite en erreurs typées
Reprises	délai exponentiel avec aléa, Retry-After respecté ; les appels POST portent une Idempotency-Key
Pagination	limit et cursor, réponse {items, next_cursor}, avec un itérateur sur toutes les pages
Traçage	traceparent W3C sur chaque appel, X-Request-Id exposé sur les erreurs
Secrets	clés API et jetons masqués dans les journaux et les représentations texte ; clés details d'allure secrète remplacées par ***

Matrice de choix

Usage	Recommandé	Pourquoi
Agents, RAG, évaluation, data science, notebooks	Python	Arborescence complète (boucle d'agent, sous-agents, évaluation, finops), client asynchrone
Applications web, portails, backends Node, edge	TypeScript	Client typé en camelCase, mode OIDC sûr pour le navigateur
Agents vocaux dans le navigateur ou une passerelle Node	TypeScript + @enterprise-ai/realtime	LiveKit et WebRTC avec repli WebSocket
Backends d'entreprise, Spring Boot, systèmes bancaires et d'assurance	Java	Client à builder, starter Spring Boot, réservations en try-with-resources
Gateways, proxys, workers média, agents d'infrastructure	Go	Paquets gatewaymw (middleware de quotas), worker, usage, realtime
CI/CD, GitOps, exploitation, vérifications rapides	CLI	validate, test, deploy, finops, audit verify avec sortie json et yaml
Tout langage sans SDK	HTTP + contrats	OpenAPI sur /openapi.json, JSON Schemas dans contracts/v1

Adoption par un client de client

Plateforme complète. Le client final reçoit un tenant (POST /v1/tenants par l'opérateur de la plateforme), des projets et des environnements, une fédération OIDC ou des clés API, puis utilise le SDK Python ou TypeScript pour ses agents et la CLI pour ses manifestes GitOps. Quotas, FinOps, audit et quality gates s'appliquent automatiquement à tout ce qui passe par le gateway.

Une seule brique. Chaque brique est accessible seule avec une clé API limitée à ses scopes :

• FinOps seule : émettre des Usage Events (POST /v1/finops/usage, paquet Go usage) depuis toute pile IA existante et lire /v1/finops/summary.
• Quotas seuls : envelopper un proxy LLM existant avec gatewaymw en Go (POST /v1/quotas/reserve, confirmation, libération).
• STT ou vision seuls : POST /v1/media puis POST /v1/multimodal/stt ou POST /v1/multimodal/vision.
• Audit seul : lire et exporter la chaîne de preuves (/v1/audit/events, /v1/audit/verify, /v1/audit/export).
• Évaluation seule : enregistrer un endpoint fournisseur et appeler /v1/evaluations/runs et /v1/evaluations/gates/check depuis la CI.