SDK TypeScript

Le SDK System One est une boîte à outils TypeScript open source, utilisable indépendamment de l’API System One hébergée. Définissez des questions avec choice(), score() et booleanQuestion(), envoyez-les avec evaluate(), ou définissez des champs Clairic et envoyez-les avec extract(). Utilisez les réponses typées dans votre application ou votre agent.

Prêt pour les questions

Qu’est-ce que le SDK TypeScript System One ? Un client open source pour l’API System One hébergée, qui permet d’appeler Choice, Score, Noul et l’extraction Clairic avec des résultats typés.

Installer et choisir un runtime

Pour l’API System One hébergée (décisions et extraction Clairic) :

npm install @system-one-ai/core@0.8.0 @system-one-ai/adapter-system-one@0.7.0 @system-one-ai/transport-fetch@0.8.0

Les paquets fournissent ESM, CommonJS et les déclarations TypeScript. Utilisez Node.js 20+ ou un runtime compatible fournissant Fetch et AbortController. Gardez les identifiants de service sur le serveur. Core ne déduit pas un protocole d’un nom d’hôte et ne lit pas vos variables d’environnement à votre place : passez la configuration explicitement.

createSystemOne(options) est la fabrique documentée et renvoie une instance SystemOne. new SystemOne(options) est le même constructeur.

Le paquet core est sous licence MIT et sans dépendance d’exécution. Installer ou utiliser la bibliothèque ne nécessite pas de compte System One : les évaluations réseau utilisent les identifiants, la disponibilité et la facturation du service auquel vous vous connectez. Les crédits de compte System One s’appliquent à notre API hébergée, pas à chaque connexion du SDK.

Choisir une connexion

Ce sont des choix d’intégration SDK publics, pas une liste des services ou des modèles hébergés sur ce site. Pour notre API hébergée, suivez le démarrage rapide avec le SDK hébergé et choisissez un identifiant exact dans le répertoire des modèles. Pour connecter le SDK à un autre service, utilisez le paquet @system-one-ai/adapter-* de ce service avec vos propres identifiants et votre propre facturation.

Préserver les types de questions et de réponses

choice() préserve les noms d’options littéraux. score() renvoie un nombre qui peut être fractionnaire. booleanQuestion() renvoie P(true), pas un booléen ; le protocole HTTP natif appelle cette question noul et l’adaptateur convertit entre les deux représentations.

import { choice, defineQuestions } from '@system-one-ai/core';
import type { Answers, EvaluateRequest, EvaluationResult } from '@system-one-ai/core';

const questions = defineQuestions({
  team: choice('Choose the reviewing team.', {
    billing: 'Payments and invoices',
    support: 'Technical help',
  }),
});

type TeamRequest = EvaluateRequest<typeof questions>;
type TeamResult = EvaluationResult<typeof questions>;
type TeamAnswers = Answers<typeof questions>;

Les résultats sont normalisés entre les adaptateurs, pas le corps HTTP d’origine. Les distributions, la confiance et les comptes de jetons peuvent être absents : une valeur inconnue n’est pas zéro. La confiance n’est pas nécessairement la probabilité de l’option sélectionnée. result.model peut indiquer un nom résolu différent de l’identifiant demandé.

Images

ImageInput est exporté par core : une chaîne data URL base64 intégrée ou { mediaType: 'image/png', base64: '...' } avec de vrais octets encodés. images est un frère optionnel de premier niveau de state et questions (ou fields). state reste obligatoire ; '' est valide quand des images sont présentes. images: [] est compatible texte. Les URL distantes, les téléchargements, l’audio et la vidéo ne sont pas pris en charge.

Les images Clairic hébergées utilisent extract() sur systemOneAdapter@0.7.0 : voir Extraire des champs avec Clairic. Les images de décision Clef, Clef Flash ou Clef Omni hébergées utilisent encore Fetch/HTTP.

Délais, annulation, reprises et erreurs

timeoutMs de core est un budget total d’évaluation, y compris la résolution des identifiants, les reprises, les délais et la lecture de la réponse. La valeur par défaut est de 10 000 ms. maxRetries au niveau du client fixe les tentatives supplémentaires (2 par défaut, de 0 à 100) ; par appel, timeoutMs, maxRetries, headers et signal complètent ou remplacent ces réglages.

const resultWithDeadline = await client.evaluate(request, {
  timeoutMs: 15_000,
  maxRetries: 0,
  signal: AbortSignal.timeout(15_000),
});

Le transport Fetch peut réessayer les échecs de connexion, le HTTP 408, le 429 et les 5xx. Commencez par maxRetries: 0 tant que votre application ne gère pas elle-même la reprise. Le SDK ne génère pas de clé d’idempotence. Core exporte SystemOneError, ConfigurationError, ValidationError, UnsupportedFeatureError, ResponseValidationError, APIError, ConnectionError, BindingError, TimeoutError et RequestAbortedError. Dans core 0.8.0 publié, APIError expose statusCode, requestId et retryAfterMs, pas le corps complet ni tous les en-têtes de réponse.

Migrer depuis l’ancien paquet

@system-one-ai/sdk@0.5.3 est déprécié.

Étapes suivantes

• Extraire des champs avec Clairic
• Connecter le SDK à l’API hébergée
• Choisir un modèle