Jev et System One, expliqués pas à pas

Le décalage texte / décision

La page d'introduction de la documentation résume le problème en une phrase : les grands modèles de langage sont conçus pour produire du texte que des humains lisent. Dès qu'on veut qu'un modèle rende un jugement que le code va consommer (« ce ticket est-il urgent ? », « quel service doit le traiter ? »), on force un système de génération de texte à sortir une décision structurée, puis on re-parse le résultat pour en faire quelque chose dont le code peut dépendre.

Chacun a déjà écrit ce genre de code : un prompt qui supplie le modèle de « répondre uniquement par un JSON valide », une expression régulière pour récupérer la valeur, un try/except pour le jour où le modèle ajoute une phrase de politesse. Et même quand le JSON est propre, il manque une chose : à quel point le modèle est sûr. Un LLM peut écrire « urgent » avec le même aplomb qu'il s'agisse d'une évidence ou d'un coup de dés.

Ce que Jev fait à la place

Jev est le modèle phare de TypeSafe et le premier modèle dit System One. Il évalue des questions typées contre un state (le contenu à juger) et renvoie des résultats structurés : pas de génération de texte, pas de parsing. Le code reçoit des valeurs typées et des distributions de probabilités sur lesquelles il peut brancher, trier, router. Les questions de type Choice et Score renvoient en plus une « confidence », un nombre entre 0 et 1 que le code utilise pour décider s'il agit, et comment.

Trois architectures logicielles

La page How to build with TypeSafe place Jev dans un paysage à trois cases. Il faut bien comprendre laquelle Jev vise, parce que ce n'est pas celle des agents.

Le nom vient de Kahneman

La page System One l'explique : le nom reprend le concept popularisé par Daniel Kahneman dans Thinking, Fast and Slow. Le Système 1 est rapide et intuitif ; le Système 2 est lent et délibéré. Jev se place résolument dans le premier : des jugements rapides et ciblés, le genre de chose qu'une personne compétente décide en une seconde quand on lui donne le bon contexte.

C'est une règle de conception autant qu'un nom. « Ce message exprime-t-il de l'urgence ? » est une bonne question. « Analyse ce message et détermine la meilleure marche à suivre » n'en est pas une : cela demande un raisonnement lent, et la documentation y voit le signal qu'il faut découper la tâche en petites questions, puis composer les réponses dans le code.

Comme un LLM, un modèle System One comprend le langage naturel en entrée. Contrairement à un LLM, il renvoie des décisions typées et des probabilités, pas du texte. Deux limites documentées : Jev accepte uniquement du texte (chaînes, objets JSON, tableaux de textes ; ni image, ni audio, ni vidéo « pour l'instant »), et sa langue principale d'entraînement est l'anglais, les autres langues étant acceptées avec une précision moindre.

Calibré : ce que cela veut dire, et ce que cela ne garantit pas

Le mot revient partout dans la documentation : Jev est entraîné pour des décisions calibrées. Ses probabilités sont optimisées contre des résultats réels pour refléter l'incertitude. Concrètement, sur un grand nombre de prédictions d'un modèle bien calibré :

• les issues auxquelles il attribue une probabilité de 0.2 se produisent environ 20 % du temps ;
• celles à 0.8, environ 80 % du temps ;
• celles à 1.0, 100 % du temps.

La documentation ajoute aussitôt la nuance qui compte : ces taux décrivent des groupes de prédictions. La calibration ne garantit rien sur une réponse prise isolément. Une confiance de 1,0 décrit la réponse du modèle, pas une preuve qu'elle est juste.

Trois chemins de post-entraînement

L'AI primer de la documentation pose le pari de TypeSafe : l'automatisation à grande échelle sera dominée par des interactions IA-vers-IA et IA-vers-logiciel, à peu près « 99 % machine-à-machine et 1 % humain ». L'interface machine compte donc plus que l'interface de chat. TypeSafe appelle cela Machine Native Intelligence : une IA avec des propriétés de logiciel, structure, fiabilité, observabilité, testabilité, vitesse, constance, faible coût. La formule de la page : « Building prod, not God », construire pour la production, pas un modèle qui fait tout.

Le problème du RLHF, vu par TypeSafe

Le RLHF apprend à un modèle à dire ce que les gens préfèrent. Cet objectif marche bien pour un chatbot, mais il peut aussi récompenser la flagornerie et les hallucinations dites avec assurance. L'optimisation des préférences provoque aussi ce que la page appelle le mode dropping : le modèle apprend à favoriser un style (suivre les instructions, par exemple) et réduit la probabilité des autres sorties possibles. C'est une version atténuée du mode collapse des GAN, où un générateur finit par produire toujours le même type de sortie parce qu'elle continue à tromper le discriminateur.

La conclusion de la page est mesurée : le RLHF reste un bon choix pour les modèles conversationnels. Mais une sortie peut être convaincante pour une personne sans être assez fiable pour une automatisation sans surveillance. Préférence humaine et fiabilité machine sont deux cibles d'optimisation différentes ; l'automatisation en production demande, selon TypeSafe, un objectif centré sur des décisions contraintes et une incertitude calibrée.

Une requête

Tout passe par un seul point d'entrée, POST https://api.typesafe.ai/v1/systemone, avec une clé d'API en en-tête Authorization: Bearer. Le corps JSON a toujours la même forme de haut niveau :

• state : le contenu à évaluer. Une chaîne, un objet ou un tableau (chapitre 4).
• model : le modèle qui traite la requête, par exemple "jev-latest" (chapitre 17).
• questions : une map d'objets question. Vous choisissez chaque clé ; les réponses reviennent sous les mêmes clés.

Chaque question a un type (choice, score ou noul), des instructions (la question posée) et, selon le type, des criteria (les options, les niveaux, ou la définition du oui et du non).

Une réponse

La réponse contient trois champs : model, l'identifiant versionné du modèle qui a répondu (par exemple jev-1.13.0, même si vous avez demandé jev-latest) ; answers, une entrée par question, sous vos identifiants ; et usage, le nombre de tokens en entrée et en sortie. Chaque réponse porte un type qui correspond au type de la question, puis des champs propres au type :

Deux propriétés rendent ces réponses composables, et la documentation les met en avant :

• Chaque réponse est contrainte aux options fournies. Le modèle renvoie une distribution sur vos options ou niveaux, jamais une valeur en dehors. Le code n'a jamais à récupérer une valeur dans de la prose.
• Chaque réponse est indépendante. La réponse à une question n'est pas un contexte caché pour une autre. On peut ajouter ou retirer des questions sans changer les résultats des autres.

Chaîne, objet ou tableau

Le state le plus simple est une chaîne : "My card was charged twice.". Mais il peut aussi être un objet ou un tableau JSON contenant du contexte, des exemples, des enregistrements liés. L'image proposée par la page State : pensez au state comme au dossier que vous présenteriez à un panel d'experts avant de leur demander un jugement.

Le conseil de la documentation : utilisez un objet pour la plupart des requêtes, pour que chaque partie du state porte un nom descriptif et que ses relations restent claires. La chaîne convient quand le cas est simple et ne demande qu'un seul texte. Une requête évalue un state contre une ou plusieurs questions ; toutes les questions voient le même state et sont évaluées indépendamment.

Séparer le contenu des questions

Le state contient le contenu et les faits d'appui ; les questions définissent les jugements à porter dessus. L'exemple de la doc : gardez la demande de remboursement et la politique de remboursement dans le state, puis demandez d'un côté si le client demande un remboursement, de l'autre si la politique le permet. Deux Nouls, un seul state.

Référencer un champ précis

Quand le state est un objet à plusieurs parties, une question porte souvent sur l'une d'elles. La page Primitives demande de la nommer dans les instructions avec un chemin « point et index » vers sa clé, accents graves compris : `ticket.messages[0].text`, `order.charges`. Le modèle sait alors quelle partie du state juger.

Quand

Un Choice sert quand la réponse est l'une d'un ensemble fixe d'options : quelle équipe traite un ticket, à quelle catégorie appartient un produit, dans quel langage est écrit un extrait de code. Si la réponse est une position sur un spectre, c'est un Score ; si c'est oui ou non, un Noul. Exemples de questions donnés par la page :

• « What programming language is this code written in » → python, javascript, typescript, go, rust, other
• « What type of meeting is this based on the title and description » → standup, planning, retrospective, one on one, brainstorm, none of the above
• « Which product category does this item belong to » → electronics, clothing, home garden, food and beverage

Notez les options other et none of the above : la doc recommande d'en ajouter une quand la liste pourrait ne pas couvrir toutes les entrées, pour que le modèle puisse dire qu'aucune ne convient.

La forme

Un Choice a trois champs : type (toujours "choice"), instructions (la question) et criteria, une map dont chaque clé est un nom d'option et chaque valeur une description. Les noms et les descriptions sont tous deux envoyés au modèle : écrivez des descriptions qui séparent les options les unes des autres. Une description peut être null quand le nom se suffit (exemple de la doc : {"calm": None, "frustrated": None, "angry": None}). Un Choice accepte jusqu'à 255 options.

Lire une réponse partagée

Dans l'exemple à cinq questions, department revient returns à 0,61, mais billing a 0,35 à cause d'un double débit mentionné dans le ticket. Le ticket appartient à deux équipes, et la confiance de 0,42 reflète ce partage. La question requested_resolution est encore plus indécise : refund 0,40, replacement 0,34, exchange 0,24, confiance 0,20 ; le client ne dit pas ce qu'il veut. Le code de la doc en tire trois conséquences :

• sous 0,3 de confiance sur department, on n'assigne pas : une personne trie ;
• une seconde équipe qui a plus de 0,25 de probabilité reçoit une copie ;
• sous 0,5 de confiance sur requested_resolution, on demande au client au lieu de deviner.

Descriptions structurées

Commencez par une ligne de description par option. Quand deux options se ressemblent et que le modèle les confond, la doc conseille de décrire chacune par un objet plutôt qu'une chaîne : un champ pour ce que l'option couvre, un pour ce qui appartient à l'option voisine, quelques exemples. Les noms de champs (what, not_for, examples, question, focus…) ne font pas partie de l'API et ne sont pas réservés : vous les choisissez, le modèle les voit avec les valeurs, donc préférez des noms courts qui étiquettent ce qui suit. L'exemple de la doc oppose return_policy et return_status, deux options qui parlent toutes deux de retours ; avec des objets contrastés, la réponse est return_status à confiance 1,0.

Quand

Un Score sert quand la réponse est une position sur un spectre que vous pouvez décrire par paliers : la gravité d'un bug, la satisfaction d'un client, l'expérience Python d'un candidat. Chaque entrée de criteria est un niveau, décrit en mots. Le numéro d'un niveau est sa position dans le tableau à partir de 0 : trois entrées font les niveaux 0, 1 et 2. Il faut au moins deux niveaux ; l'API en accepte jusqu'à 10.

Détail important donné par la page : le modèle reçoit les descriptions et rien d'autre, et chaque niveau est jugé séparément contre le state. Il ne voit ni le numéro du niveau ni ses voisins. « Pire que le niveau précédent » ne veut donc rien dire pour lui.

Écrire de bons niveaux

• Décrivez des situations, pas des degrés. « Fonction cassée ou dégradée, mais un contournement existe » donne au modèle quelque chose à comparer au state. « Modérément grave » ne donne rien.
• Pas de chiffres. Avec criteria: ["0", "1", "2"] et l'instruction « Rate severity from 0 to 2 », le rapport du bouton mal aligné obtient 0,55 à confiance 0,33 (probabilité partagée entre 0 et 1). Avec les trois niveaux descriptifs, il obtient 0,0 à confiance 1,0.
• Autant de niveaux que vous pouvez décrire distinctement, jusqu'à 10. Trois, c'est bien. N'ajoutez pas de niveau que vous ne savez pas distinguer.
• Une dimension par Score. « Ponctuel et brillant et expérimenté » mesure trois choses ; une entrée haute sur l'une et basse sur l'autre ne peut pas être placée, la confiance chute, le score perd son sens. Séparez et combinez dans le code.
• Donnez son propre niveau à un cas extrême rare sur lequel vous devez agir différemment : une échelle de sentiment qui finit à « très en colère » peut ajouter « abusif ou menaçant ».
• Testez sur vos données. Deux formulations de la même échelle peuvent se comporter différemment. Une confiance plus haute ne prouve pas à elle seule qu'une description est meilleure.

Découper un jugement complexe en plusieurs Scores

Un jugement qui dépend de plusieurs choses se découpe en un Score par chose, envoyés dans la même requête (ils sont évalués en parallèle, cela coûte quelques tokens de question). Le code combine ensuite les scores avec des poids qui lui appartiennent. L'exemple de la doc : la priorité d'un ticket à partir de trois Scores, gravité (3 niveaux), frustration (3 niveaux) et qualité du rapport (4 niveaux). Comme les échelles n'ont pas la même longueur, on normalise chaque score en le divisant par son numéro de niveau maximal, len(criteria) - 1, pour tout ramener entre 0 et 1.

Niveaux structurés

Quand le modèle continue à placer entre deux niveaux voisins des entrées qui vous paraissent claires, donnez à chaque niveau un objet : un champ pour ce que le niveau couvre, un autre avec quelques situations d'exemple, les mêmes noms de champs sur tous les niveaux. Le tableau de la doc sur le rapport Safari est éloquent :

L'exemple qui ressemble aux vraies entrées concentre presque toute la probabilité sur un niveau ; l'exemple sans rapport ne change rien. Et la mise en garde de la page : une confiance plus haute n'établit pas quelle réponse est correcte. Choisissez des exemples dont vous connaissez le niveau attendu, puis testez les descriptions révisées sur d'autres entrées avant de les garder.

Quand

Un Noul sert quand la réponse est oui ou non : ce message demande-t-il un remboursement, ce CV mentionne-t-il les systèmes distribués, ce commentaire contient-il des données personnelles. Les champs : type ("noul"), instructions (la question, ou une affirmation à juger) et, en option, criteria, un objet avec des descriptions true et false de ce que signifient un oui et un non.

Lire un Noul : la réponse et la certitude en un seul nombre

Près de 1, un oui franc. Près de 0, un non franc. Près de 0,5, le modèle donne au oui et au non une probabilité voisine. Il n'y a pas de confidence séparée, contrairement à Choice et Score : la distribution d'un Noul n'a que deux issues, donc la seule valeur noul la décrit complètement. La page donne six messages enregistrés pour la question « Is the customer asking for a human agent? » ; le module ci-dessous les reprend.

Un Noul n'est pas une échelle

La valeur va de 0 à 1, mais ce n'est pas une mesure de la chose demandée : c'est la probabilité que la réponse soit oui. Si la question est en réalité une question de degré, la valeur ne mesure pas le degré. La doc compare, sur quatre candidats, le Noul « Is the candidate strong in Python? » et un Score à quatre niveaux (aucune expérience, quelque familiarité, usage régulier au travail, expertise profonde) :

On pourrait, dans le code, découper l'intervalle 0–1 en tranches (« 0,3 à 0,7 = quelque expérience »), mais le modèle ne les verrait pas : rien dans sa réponse n'a été jugé contre elles. Une valeur médiane peut vouloir dire « expérience moyenne » ou « cas flou », et l'espacement entre candidats n'est pas quelque chose que vous avez choisi. Avec le Score, chaque candidat atterrit sur ou près d'un niveau que vous avez écrit, et si vous n'êtes pas d'accord, vous reformulez un niveau et relancez.

Écrire une question Noul

• Une question par Noul. « Le client est-il en colère et demande-t-il un remboursement ? » force le modèle à juger deux choses à la fois. Deux Nouls, combinés dans le code.
• Une valeur haute doit vouloir dire oui. « Does the message contain personal data? » est clair. « Is the message free of personal data? » inverse le sens et le code qui le lit se trompera.
• Une affirmation marche aussi bien. Pour « The customer is requesting a refund », une valeur près de 1 signifie que l'affirmation est vraie. Essayez les deux sur vos données.
• Rendez la frontière nette. « Does this candidate have any Python experience? » ne laisse pas de milieu. Quand la frontière est subtile, ajoutez criteria avec true et false ; sinon l'instruction suffit souvent.

Instructions structurées, questions générées par le code

Les instructions peuvent être un objet : la question dans un champ, des données de référence dans les autres. L'exemple de la page compare un CV qui vient d'arriver à des fiches d'une base de candidats, une question Noul par fiche, toutes dans une seule requête, avec l'identifiant de la fiche dans la clé de la question. Réponses rapportées : la fiche 18 (nom orthographié différemment, même ville, même employeur) obtient 0,74 ; la fiche 42 (même nom, autre ville, autre employeur) 0,09 ; la fiche 77 (nom proche, même lieu, autre employeur) 0,08.

La règle

• Choice quand la réponse est une option d'un ensemble connu, sans ordre entre elles. Donnez la liste complète, plus other si elle peut ne pas tout couvrir.
• Score quand la réponse tombe sur un spectre dont vous pouvez décrire chaque point.
• Noul pour un oui/non net où la probabilité elle-même est le signal utile.

Si deux types semblent convenir, préférez celui dont la réponse s'utilise directement : un Choice entre refund, rebook et information se branche sur trois chemins de code ; un Score de frustration se compare à un seuil ; un Noul se branche sur un if.

Où la structure est acceptée

La page Advanced: structure dit que les modèles System One sont entraînés à comprendre la structure, et liste les champs qui l'acceptent. Chacun est un EntryType : string, object, array ou null.

Quand structurer

La page How to build donne trois situations : la question a besoin de contexte ou d'exemples (une longue phrase de contexte ou une liste d'exemples va dans des champs nommés à côté de la question, que le code peut modifier sans réécrire la question) ; une partie de la question vient du code (une valeur lue en base va dans son propre champ plutôt que dans un template de chaîne) ; plusieurs questions ont des instructions voisines (des données supplémentaires les rendent distinctes). Une question courte et sans ambiguïté reste une chaîne.

Un tableau marche aussi, quand l'instruction est une liste de choses à vérifier ou à comparer :

Parcourir une taxonomie avec des Choices

Pour classer dans une taxonomie profonde, la doc propose un Choice par niveau, en parcourant l'arbre dans le code : à chaque étape, les options sont les enfants du nœud courant, et la valeur de chaque option est le sous-arbre de l'enfant. Le modèle voit ainsi ce qui vit sous une branche avant de s'y engager, ce qui compte quand l'article appartient à une feuille dont le nom ne se devine pas depuis la branche. L'exemple : une gourde qui peut aller sous Sporting Goods > Cycling > Bike Bottles & Cages ou Home & Kitchen > Drinkware > Water Bottles ; les probabilities disent si le partage est assez serré pour explorer les deux branches. Si un sous-arbre est trop gros, on le réduit à ses enfants directs et à un échantillon de feuilles.

Dérivée des probabilités

La page Confidence le dit sans détour : confidence est une statistique calculée à partir de la distribution que la réponse contient déjà. TypeSafe la calcule et la renvoie sur chaque Choice et chaque Score, donc le cas courant ne demande rien de plus. Pour un Choice, la distribution porte sur vos options ; pour un Score, sur vos niveaux. Dans les deux cas, plus elle est plate, plus la confiance est basse : sur un Choice, aucune option ne l'emporte nettement ; sur un Score, les niveaux sont ambigus, la question mesure plusieurs choses, ou le state ne dit pas assez.

« Je ne sais pas » est un signal utile

La phrase de la page vaut la peine d'être citée : si un système intelligent, humain ou machine, ne peut pas exprimer une incertitude honnête, on ne peut pas lui faire confiance. La confiance est le mécanisme intégré par lequel le modèle dit « pas sûr pour celui-là ». C'est ce qui permet au code d'avoir des comportements différents selon le degré de certitude, et c'est, selon TypeSafe, le fondement des systèmes sur lesquels on peut réellement s'appuyer.

Retenez aussi la limite : une confiance de 1,0 signifie que la distribution renvoyée met toute la probabilité sur une issue. Elle décrit la réponse du modèle, pas une garantie qu'elle soit juste.

Trois chemins

• Confiance haute : agir automatiquement. Le modèle a une lecture claire.
• Confiance moyenne : avancer avec prudence. Demander confirmation à l'utilisateur, signaler pour relecture, ou collecter plus d'information avant d'agir.
• Confiance basse : ne pas agir. Router vers une personne, demander une clarification, ou basculer sur un autre système. Le modèle dit qu'il manque d'information ou que la question lui convient mal.

Où tracer ces frontières dépend des enjeux. Et dans un même système, des actions différentes doivent être gardées à des niveaux différents. La page Confidence-gated routing le montre avec une interface bancaire vocale : consulter un solde à 0,6 de confiance, c'est acceptable (au pire, l'utilisateur entend un solde qu'il n'a pas demandé) ; approuver un virement demande plus de 0,85, sinon on fait confirmer.

La page ajoute une cible : un rapport intelligence / (vitesse et coût) supérieur à 100×, avec le pari qu'une intelligence moins chère créera beaucoup plus de demande.

Concevoir un flux en huit étapes

L'exemple complet : trier un ticket

Le flux triage_ticket.py de la page garde le déterminisme dans le code (un ticket fermé sort tout de suite, sans modèle), n'envoie que le contexte structuré utile (message, expéditeur, liens, plan du client, commandes ouvertes, liste des identifiants sensibles), pose sept questions atomiques dans une seule requête (un Choice de sujet, cinq Nouls, un Score de frustration), puis compose les réponses avec des portes de confiance explicites. Le module suivant isole la partie « risque de spam » : trois Nouls pondérés dans le code.

Deux détails du même fichier méritent l'attention. Les questions y sont toutes structurées : chaque Noul a un objet instructions avec question, compare ou inspect, et focus, et des criteria dont true et false sont des objets avec what, not_for, examples. Et les chemins vers le state y sont cités entre accents graves (`ticket.message`, `policy.sensitive_credentials`), comme au chapitre 4.

1 · Speculative fan-out

Parce qu'une requête accepte beaucoup de questions, la doc recommande d'y mettre toutes celles dont le système pourrait avoir besoin, puis de trier dans le code. Toutes sont évaluées en parallèle, donc en ajouter change peu le temps de réponse. L'exemple : trier un ticket de support. Au lieu de demander la catégorie, puis la gravité dans un second appel si c'est un bug, on demande les deux à la fois ; si ce n'est pas un bug, on ignore la gravité.

Tout ce qu'il faut pour l'arbre de décision complet vient d'un seul appel. Les questions spéculatives sont ignorées quand elles ne servent pas, et économisent un aller-retour quand elles servent. La page Primitives renvoie au cookbook Parallel questions : treize questions en un appel contre treize appels, environ dix fois moins cher et dix fois plus rapide, sans changement des réponses (les deux pages donnent des multiplicateurs légèrement différents, 11,5×/9,6× et 12,2×/10,0×, sans doute deux exécutions).

2 · Confidence-gated routing

C'est le chapitre 10 : la réponse dit quoi, la confiance dit s'il faut agir, et chaque action a son seuil. Rien à ajouter ici, sinon la place de ce pattern dans la liste : c'est celui qui apporte fiabilité et sécurité, pas coût ou vitesse.

3 · Composite scoring

On veut souvent classer des éléments selon plusieurs critères à la fois. Le pattern : découper le jugement en dimensions indépendantes, noter chacune séparément (un Score par dimension, dans une seule requête), normaliser entre 0 et 1, puis combiner avec des poids que le code contrôle. L'exemple de la page : des CV d'ingénieurs notés sur quatre dimensions (profondeur Python, leadership, conception de systèmes, polyvalence), avec deux jeux de poids selon le poste.

Ce que la page souligne : au-delà du classement, on voit exactement comment le score final est fabriqué. Si les meilleurs classés ne correspondent pas aux attentes, on ajuste les poids, sans perdre la nuance des scores individuels.

4 · Intent routing

Toutes les demandes ne méritent pas le même gestionnaire : certaines se règlent par une requête en base, d'autres par un LLM spécialisé avec son contexte, d'autres par un humain. TypeSafe se place devant, comme classifieur rapide et bon marché qui décide quel gestionnaire invoquer, au lieu de faire passer chaque message par un LLM coûteux juste pour savoir de quoi il parle.

Prenez la requête « Turn off all of the lights in the house ». Le code n'a besoin que de quatre réponses : la catégorie de la requête (commande domotique), le domaine visé (toute la maison), le type d'appareil (lumières), l'action (éteindre). La dernière question est écrite en supposant que l'utilisateur commande des lumières, et on la pose avant de savoir si c'est le cas. C'est une question spéculative : on l'évalue en parallèle avec les autres et le code filtre après coup. Chaque requête utilisateur est ainsi évaluée contre une longue liste de questions, dont beaucoup seront sans objet.

La mauvaise façon, dit la page, serait de découper en appels successifs : la catégorie d'abord ; puis, une fois sûr que c'est une commande, le domaine et l'appareil ; puis, une fois sûr que ce sont des lumières, l'action. Cela minimise le nombre de questions, mais c'est bien plus lent et plus cher qu'un seul appel groupé.

TypeSafe + LLM

La démo montre aussi deux façons d'associer Jev à un modèle génératif, pour un système qui a parfois besoin d'une étape de génération de texte :

• Découper une requête composée. Un Noul demande si la requête réclame plus d'une action distincte. Si oui, un LLM découpe la phrase en une liste de commandes atomiques, que TypeSafe évalue ensuite une par une.
• Basculer sur un LLM conversationnel. Quand TypeSafe détermine que la requête est une demande d'information générale ou de conversation, le système appelle un LLM pour générer une réponse libre. Les comportements déterministes connus sont traités vite et à bas coût ; la souplesse d'un LLM reste disponible quand il le faut. La réponse initiale de TypeSafe est si rapide comparée à celle du LLM qu'elle ajoute une latence négligeable.

La page indique que la démo est une application Vite/React dont le code source complet « sera disponible sur GitHub à la sortie » ; à la date de lecture, seul un enregistrement vidéo est proposé. Le cours ne décrit donc pas son code.

Par secteur

Dix-neuf accordéons dans la page. Chacun liste des décisions typiques ; en voici le contenu, condensé mais fidèle.

Par forme de décision

Le point d'entrée

La clé d'API se crée dans la console (console.typesafe.ai/keys). Le corps a les trois champs vus au chapitre 3, tous requis : state (string | object | array), model (string) et questions (map<string, Question>). Une Question est l'un des trois types ; tous partagent type et instructions, chacun a ses criteria.

Erreurs et limites de débit

Sur 429 et 529, la consigne est de réessayer avec un backoff exponentiel, pas immédiatement. Les SDK le font par défaut et respectent l'en-tête retry-after quand il est présent. Un dernier point d'API : GET /v1/models renvoie la liste des noms que votre compte peut envoyer dans model, avec description et date de sortie ; il liste actuellement les alias, mais les identifiants versionnés comme jev-1.13.0 sont acceptés qu'ils apparaissent ou non.

Python

Requiert Python 3.10 ou plus. Le client lit TYPESAFE_API_KEY dans l'environnement et appelle jev-latest par défaut. Deux clients : TypeSafeClient (synchrone) et AsyncTypeSafeClient. La réponse expose answers (toutes les réponses, par identifiant) et trois vues typées, nouls, choices, scores.

Réponses typées avec response_model

Depuis la v0.7.0 (qui a remplacé msgspec par pydantic), system_one accepte un response_model : une sous-classe de SystemOneResponse qui déclare les réponses attendues, ou même un modèle pydantic entièrement à vous. Le résultat expose alors chaque réponse comme un attribut typé, et l'identifiant de requête via request_id.

Retries, erreurs, journalisation, environnement

Une RetryPolicy se passe au client ou par appel (RetryPolicy(max_retries=3, backoff_max=0.2, timeout=1.0) dans l'exemple). Les erreurs de l'API lèvent TypeSafeAPIError, avec status et request_id. Le SDK journalise sur le logger typesafe_sdk ; TYPESAFE_LOG_LEVEL accepte debug, info, warning, error ou off. En debug, les en-têtes et corps sont journalisés ; les en-têtes secrets sont masqués, les corps ne le sont pas.

Compatibilité ascendante

Le SDK continue de fonctionner quand l'API évolue : extra_body envoie des champs de requête que la version du SDK ne connaît pas encore ; des dictionnaires de questions bruts passent tels quels ; les genres de réponse inconnus sont ignorés avec un avertissement, et raw_http_response donne accès au JSON complet. La doc précise que ce sont des issues de secours et qu'il vaut mieux mettre à jour le SDK.

JavaScript / TypeScript

Requiert Node.js 20 ou plus. Le paquet fournit ESM, CommonJS et déclarations TypeScript. Trois helpers construisent les questions, choice(instructions, criteria), score(instructions, criteria) et noul(instructions?, criteria?), et les types des réponses sont inférés des questions : answers.department.choice est typé comme l'une des clés de vos options.

Le constructeur TypeSafeClient(config) accepte apiKey, baseURL, defaultModel, timeout (par tentative, 10 000 ms par défaut), retry, logLevel, logger, defaultHeaders, fetch, et dangerouslyAllowBrowser (faux par défaut : utiliser le SDK dans un navigateur expose la clé aux visiteurs). Les options explicites priment sur les variables d'environnement, elles-mêmes sur les défauts du SDK. La politique de retry par défaut : 2 tentatives supplémentaires, backoff initial 500 ms doublé jusqu'à 5 000 ms avec 25 % de gigue, sur les statuts 408, 429 et 500–599, en honorant Retry-After jusqu'à 60 s. Les erreurs sont des classes dédiées (AuthenticationError, RateLimitError, UnprocessableEntityError, APITimeoutError…), toutes dérivées de TypeSafeError.

Alias

Un alias est un nom qui résout vers un identifiant versionné. jev-latest pointe vers jev-1.13.0 : la version stable la plus récente, le défaut des SDK et le nom utilisé dans les exemples. jev-preview pointe vers la version la plus récente, officielle ou non ; il passe devant jev-latest quand une préversion existe. À la date de lecture, les deux pointent sur le même modèle : il n'y a pas de préversion disponible.

Conséquence pratique soulignée par la page : un alias bouge à chaque sortie, donc les réponses derrière peuvent changer sans rien changer chez vous. Le champ model de la réponse donne l'identifiant versionné qui a répondu, à journaliser. Et si vous avez réglé des seuils de confiance sur une version précise, épinglez son identifiant plutôt que l'alias, et migrez à votre rythme.

Personnaliser Jev

Jev n'est ni fine-tuné ni adapté par LoRA avec des données client ; les mêmes poids servent tous les comptes. On façonne ses réponses par la requête : contenu propriétaire, enregistrements et références dans le state ; règles métier et cas limites dans instructions et criteria ; jugements larges décomposés en questions atomiques combinées dans le code ; et, pour aller plus loin, un modèle classique entraîné sur les probabilités de Jev (cookbook AutoResearch).

Langues et données

L'anglais est la langue principale d'entraînement, celle où la précision est la meilleure. Les autres langues, y compris les écritures CJK, sont traitées mais moins bien : testez sur votre contenu avant de vous y fier, et surveillez la confiance de près pour le routage. Jev n'est pas entraîné sur les requêtes et réponses des clients ; la page Legal renvoie à l'accord de traitement des données, à la politique de confidentialité, et propose la rétention zéro (ZDR) aux clients entreprise.

Choisissez une seule méthode d'installation pour éviter les doublons. Le fichier SKILL.md est lisible sur GitHub (typesafe-ai/skills). Dans un prompt, nommer le skill (« use the TypeSafe skill ») marche avec tout agent ; avec le plugin Claude Code, on peut aussi invoquer /typesafe:typesafe-ai.

Trois prompts suggérés

• Explorer : « Using the TypeSafe skill, explore the project and find opportunities for using intelligent judgement to stand in for complex parsing or other fragile code. »
• Expérimenter avec une clé exportée dans TYPESAFE_API_KEY : « run some experiments… Propose changes based on the most promising results. »
• Refactorer à partir des cookbooks : « analyze my code and see if there are any applicable cookbooks… »

Principes de « vibe coding » selon la page

1. Discuter avec l'agent, à partir des prompts ci-dessus.
2. Relire le plan avant de l'implémenter.
3. Mettre les constantes (questions et seuils) à un seul endroit, faciles à relire : les agents ne sont pas très bons pour écrire des questions, attendez-vous à les éditer avec eux.
4. Ne pas prendre les affirmations pour argent comptant ; pousser l'agent à valider ses hypothèses.

Problèmes courants

• L'agent n'utilise pas le skill : l'invoquer explicitement, vérifier que l'installation ciblait bien cet agent, redémarrer.
• Le routage ne se comporte pas comme prévu : vérifier questions et seuils. Trop haut, des faux négatifs ; trop bas, des faux positifs.
• Des seuils de confiance partout : si l'on veut seulement la meilleure option, prendre celle de plus haute probabilité, sans seuil ; pour un algorithme statistique précis, utiliser les probabilités.
• Le code TypeSafe est dur à relire : ce que les humains doivent relire, ce sont les questions et les constantes de seuil ; les regrouper dans un seul fichier.
• L'agent invente des champs de requête ou de réponse : un skill périmé ; mettre à jour et réessayer.

La page Primitives ajoute une raison de plus d'installer le skill : les agents de code tombent plus que les humains dans l'habitude « une question par appel ». Le skill leur dit de grouper beaucoup de questions par appel, y compris celles qui ne comptent que pour certaines entrées.

Ce que les cookbooks enseignent, en cinq idées

1. Trouver, puis choisir. Jev ne génère pas : quand la réponse est une valeur du texte, un regex ou un autre modèle trouve les candidats et un Choice choisit (Pre-parsed value extraction, Date extraction, Function calling). La valeur retournée est copiée telle quelle, jamais inventée.
2. Une requête par document, autant de questions qu'il faut. Parallel questions mesure le gain du groupement : environ dix fois moins cher et plus rapide sur un document de 54 000 caractères, avec les mêmes réponses.
3. La confiance sépare les cas faciles des cas durs. Classification using confidence classe 60 rapports annuels en 75 groupes industriels : au seuil 0,9, la moitié confiante est juste à 90 %, l'autre à 40 % ; remontée d'un cran dans la hiérarchie, cette moitié passe à 70 %, sans second appel.
4. Vérifier, moins cher que produire. SDE cascade extrait avec un petit modèle, vérifie chaque champ avec des Nouls TypeSafe, et n'escalade vers le gros modèle de raisonnement que si un signal s'allume. Citation check et Guardrails appliquent la même idée aux citations et aux messages d'un LLM.
5. Des réponses stables. Les deux cookbooks Self-consistency rejouent quinze fois le même rubric et comparent la dispersion des réponses de Jev à celles de LLM, y compris à température 0.

Glossaire

• state : le contenu à évaluer, envoyé dans le champ state.
• question : un jugement typé demandé au modèle ; answer : la valeur typée renvoyée sous le même identifiant.
• instructions : la question posée ; criteria : les options (Choice), les niveaux (Score) ou la définition du oui et du non (Noul).
• probabilities : la distribution sur les options ou niveaux, somme 1 ; legend : les niveaux d'un Score rappelés par numéro.
• confidence : résumé de 0 à 1 de la concentration de la distribution (Choice et Score).
• question spéculative : posée d'avance, dans le même appel, avant de savoir si elle servira.
• context rot : la perte de précision quand le state contient de la matière sans rapport avec la question.
• RLCD : Reinforcement Learning for Calibrated Decisions, le post-entraînement de TypeSafe.
• calibration : sur un lot de prédictions, une probabilité annoncée de p se vérifie dans une proportion voisine de p.
• jaggedness : les « bords irréguliers », les tâches sur lesquelles le modèle est nettement moins bon que sur les autres.

Pour aller plus loin

• Le Playground : coller un texte, ajouter des questions, voir les réponses. C'est le point de départ recommandé par le Quick start.
• La documentation, dont l'index llms.txt ; chaque page existe en Markdown en ajoutant .md à son URL.
• Le manifeste de TypeSafe, et la communauté Discord où la page Jaggedness invite à signaler de nouveaux modes d'échec.