Conception du SDK TypeScript

laya-client est un client HTTP sans dépendance pour un serveur laya-serve auto-hébergé. Il utilise l’endpoint POST /v1/systemone et n’ajoute ni code Python de production ni dépendance serveur. Le paquet npm démarre à la version 0.1.0, indépendamment des publications Python.

Frontières

Composant	Responsabilité
`sdk/typescript`	Types question/réponse, presets, validation, fetch natif, erreurs et annulation
`laya/serve.py`	Endpoint HTTP existant, authentification Bearer, santé et limites de requêtes
`laya/router.py`	Sélection de checkpoint, chargement et routage d’inférence
`laya/agent.py`	Découpage en jetons, inférence PyTorch et mise en forme des réponses calibrées
`laya/presets.py`	Source des cinq presets de questions TypeScript générés

flowchart LR
    A[JavaScript or TypeScript application] --> B[laya-client]
    B -->|POST /v1/systemone| C[Existing Laya server]
    C --> E[Router and local checkpoint]

Le SDK exporte predict et une sonde health propre à Laya. Il est distribué en ESM, CommonJS et déclarations, en conservant les ids de question et les libellés de choice inférés. Utilise laya-client quand une application JavaScript ou TypeScript parle en HTTP à un serveur Python laya-serve auto-hébergé. Utilise laya-ts quand l’inférence doit tourner directement dans JavaScript via son runtime ONNX local, sans serveur Python.

Contrat partagé

Les requêtes contiennent state et questions. Sauf configuration ou valeur fournie pour une prédiction, laya-client omet model, laissant laya-serve choisir automatiquement un checkpoint local. Un model global au client ou par appel peut sélectionner un checkpoint local, comme les autres contrôles par requête du tableau ci-dessous. Les tableaux de libellés choice sont normalisés en maps avec des descriptions nulles avant l’envoi.

Les réponses conservent model, answers et l’usage des jetons. Les champs routing et action de réponse de Laya sont des extensions optionnelles ; la confiance Noul l’est aussi. La confiance Choice et Score, les distributions et les légendes Score restent obligatoires. Chaque réponse porte answer_confidence, la masse max(p) sur la réponse rapportée, qui est la même quantité sur les trois types de question. Un appel auquel min_confidence a été passé rapporte abstention et abstention_threshold sur chacune de ses réponses et low_confidence: true sur celles sous le seuil ; sans seuil défini, aucune de ces trois clés n’est envoyée, et cette absence est le rapport. Les extensions optionnelles sont validées quand elles sont présentes.

/v1/systemone est le seul endpoint que le client appelle, et il n’a pas de méthode de routage autonome : laya-client expose predict et health et rien d’autre, et le test d’intégration en direct vérifie que le serveur répond 404 pour /v1/route. Les contrôles que l’endpoint honore sont par requête, et chacun n’est envoyé que lorsque l’appelant a fourni l’option – une option absente laisse les propres réglages Router(...) du déploiement aux commandes au lieu de les remplacer par un défaut côté client :

option	champ de requête
`model`	`model`
`task`	`task`
`lang`	`lang`
`langGuess`	`lang_guess`
`maxLen`	`max_len`
`headMaxLen`	`head_max_len`
`minConfidence`	`min_confidence`

Une option qui ne peut rien signifier est refusée localement, avant que la requête ne parte : un task vide, un budget qui n’est pas un entier positif, un seuil hors de [0, 1], ou une table de seuils vide ou contenant une valeur hors de [0, 1]. Rien n’est ignoré silencieusement. Le /health public de Laya renvoie status, loaded et device. La prédiction ne sonde jamais la santé en premier.

Les chaînes de détail FastAPI et les tableaux de validation sont conservés comme messages/détails de LayaAPIError. Les enveloppes d’erreur structurées de backends compatibles sont aussi acceptées. Les requêtes ont des délais configurables et une annulation par l’appelant, et ne sont jamais réessayées automatiquement.

Vérification et publication

Les tests unitaires couvrent la construction des requêtes, toutes les formes de réponse, les extensions Laya, les erreurs FastAPI, la validation JSON, les délais et l’annulation, et rattachent la table de contrôles de cette page aux champs que le client met réellement sur le fil. Les vérifications de types couvrent les métadonnées optionnelles, les types de réponse inférés et les consommateurs ESM/CommonJS. Le test d’intégration en direct démarre l’application laya.serve inchangée avec un petit checkpoint hors ligne, compare les prédictions du SDK à l’inférence Python directe, et exerce le routage, les presets, l’authentification et les limites de requêtes. La CI lance les vérifications du SDK sur Node.js 22 et 24.

De minuscules poids aléatoires vérifient le transport et la parité numérique, pas la qualité pré-entraînée ni les performances.

Voir le guide du SDK pour l’installation, des exemples et la publication npm. Le paquet sera publié sous le nom laya-client. Les workflows de publication Python sont inchangés.