Tutoriel TypeSafe Jev étape par étape. Guide pratique de TypeSafe Jev, le modèle IA System One pour les décisions logicielles typées.
01
Encadrez la tâche
Décidez si Jev convient
Jev n'est pas un modèle de chat. Il transforme l'état existant en une décision fermée de choix, de score ou de Noul et renvoie une distribution de probabilité.
Un bon ajustement
Utilisez Jev pour des décisions limitées
Acheminez une requête vers une file d’attente nommée.
Placez un enregistrement sur une échelle de risque ou de qualité ordonnée.
Estimez si une condition clairement énoncée est vraie.
Pas un bon ajustement
Utilisez plutôt un modèle génératif
Écrivez, résumez, traduisez ou réécrivez un texte ouvert.
Tenez une conversation naturelle à plusieurs tours.
Créez une réponse lorsque les sorties valides ne peuvent pas être nommées à l'avance.
Le modèle mental officiel
STATE
Un État à évaluer
Transmettez une chaîne, un objet ou un tableau contenant le texte et les faits associés dont le jugement a besoin. Utilisez des champs d'objet nommé pour la plupart des requêtes réelles.
QUESTIONS
Un jugement instantané par question
Chaque question doit poser une question ciblée qu'une personne bien informée peut juger rapidement à partir de l'état fourni.
PARALLEL
Questions indépendantes en parallèle
Les questions d’une requête voient le même état, s’exécutent indépendamment et ne transmettent pas de réponse à une autre.
CODE
Composer les réponses en code
Pondérez, seuil, branchez et combinez les réponses saisies dans un code ordinaire au lieu de masquer la logique du flux de travail dans une seule invite.
Test de décomposition : Si le jugement pèse plusieurs facteurs indépendants ou nécessite un raisonnement approfondi, divisez-le en questions atomiques et combinez les réponses dans le code.
Après ce chapitre :Vous pouvez séparer les tâches de génération de contenu des tâches de décision structurée.
Utilisez Choice pour les étiquettes mutuellement exclusives, Score pour les niveaux ordonnés et Noul pour un jugement vrai ou faux.
Tapez
Vous fournissez
Vous recevez
Utiliser quand
choice
Options nommées → descriptions
Clé sélectionnée + probabilités par option (+ confiance)
Labels/itinéraires mutuellement exclusifs
score
Niveaux ordonnés (2 à 10), bas → élevé
Score de niveau pondéré en fonction de la probabilité + problèmes d'échelon
Rubriques gravité, qualité, risque
noul
Proposition oui/non (+ critères optionnels)
Probabilité de vrai
Vérifications de faits uniques
choiceJusqu'à 255 options
Un gagnant et la distribution complète
À utiliser pour des alternatives fixes et non ordonnées. Ajoutez autre/aucun lorsque la liste ne couvre pas tous les états. La valeur choisie est l'option la plus probable.
À utiliser pour un jugement clair oui/non. Près de 0,5 signifie une incertitude et non une valeur moyenne de la propriété. Noul n'a pas de champ de confiance séparé.
{
"type": "noul",
"noul": 0.95
}
Le score n’est pas l’exactitude. Un score de 1,5 sur une grille de 0 à 2 est un niveau attendu et non « correct à 75 % ». Ne considérez pas la confiance Score ou Choice comme une promesse d’exactitude.
Après ce chapitre :Vous pouvez sélectionner la bonne forme de réponse pour le routage, la modération et la notation des risques.
Gardez les noms d’options stables, définissez des limites mutuellement exclusives, incluez un chemin résiduel et donnez à chaque question une décision.
Rédiger des critères forts
Options disjointes. Si deux clés de choix peuvent toutes deux être vraies, les opérateurs combattront le modèle.
Décrivez les bords. Dites ce que buy_intent inclut (stock, livraison) par rapport à price_question.
Gardez le résidu en dernier. Utilisez d'autres/humains comme trappes de secours, pas comme fourre-tout paresseux.
Score de commande croissant. Les tableaux de critères sont les plus bas → les plus élevés.
Une décision par question. Divisez « itinéraire » et « urgence » en clés distinctes.
Anatomie d'une question
question_id
Une clé de recherche de réponse pour votre code. Elle n'est pas envoyée au modèle, les instructions doivent donc toujours contenir la question complète.
type
choix, score ou noul. Choisissez la forme sur laquelle votre code peut agir directement.
instructions
Le jugement complet et précis. Il peut s'agir d'une chaîne, d'un objet ou d'un tableau et peut faire référence à des chemins d'état nommés.
criteria
Options de choix, niveaux de score ordonnés ou clarification facultative vrai/faux pour Noul.
Exemple · une décision, limites disjointes
route: {
type: 'choice',
instructions: 'Route this ticket to one queue.',
criteria: {
tech: 'Bugs, outages, API failures, or integrations',
sales: 'Pricing, plans, demos, or new-purchase intent',
billing: 'Charges, invoices, receipts, or subscriptions',
human: 'Ambiguous, sensitive, legal, or multi-issue'
}
}
Champs exacts d’état de la structure et de référence
Conservez les preuves dans les champs d'état nommés et pointez les instructions vers eux avec des chemins de points et d'index. Cela réduit l'ambiguïté quant au texte, à l'enregistrement ou à la politique qui doit contrôler la réponse.
const state = {
ticket: {
message: 'I was charged twice. Please refund the duplicate.',
orderId: 'A-104'
},
order: { charges: [49, 49] },
refundPolicy: 'Duplicate charges are eligible for a refund.'
};
const questions = {
refund_requested: {
type: 'noul',
instructions: 'Does `ticket.message` request a refund?'
},
policy_supports_refund: {
type: 'noul',
instructions: 'Does `refundPolicy` support the request given `order.charges`?'
}
};
Lot par défaut : Posez toutes les questions qui utilisent le même état dans une seule requête, même les questions spéculatives. Faites une deuxième demande uniquement lorsque son état ou ses options dépendent réellement d'une réponse antérieure.
Après ce chapitre :Vous pouvez écrire une définition de question stable et testable que le code peut utiliser.
Appelez le point de terminaison ou SDK officiel System One depuis votre serveur, inspectez la réponse saisie et gérez les erreurs de validation, de limite de débit et de surcharge. La passerelle reste un chemin d'accès facultatif.
Commencez par le point de terminaison HTTP officiel
Conservez TYPESAFE_API_KEY sur le serveur. Envoyer l'état, le modèle et une carte des questions nommées à POST /v1/systemone.
curl -X POST https://api.typesafe.ai/v1/systemone \
-H "Authorization: Bearer $TYPESAFE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"state": "Stripe has failed for 3 days. I am losing sales.",
"model": "jev-latest",
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this?",
"criteria": {
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions"
}
},
"is_urgent": {
"type": "noul",
"instructions": "Does this message convey urgency?"
}
}
}'
Utilisez le SDK officiel pour les réponses saisies et les tentatives
Le SDK Python lit TYPESAFE_API_KEY à partir de l'environnement, prend par défaut la valeur jev-latest, expose les classes de questions/réponses saisies et applique sa politique de nouvelle tentative par défaut.
pip install typesafe-sdk
from typesafe_sdk import Choice, Noul, TypeSafeClient
with TypeSafeClient() as client:
response = client.system_one(
state={"message": "Stripe has failed for 3 days.", "impact": "Losing sales"},
questions={
"department": Choice(
instructions="Which team should handle this?",
criteria={
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions",
},
),
"is_urgent": Noul(
instructions="Does `message` and `impact` convey urgency?"
),
},
)
department = response.answers["department"]
print(department.choice, department.confidence)
print(response.answers["is_urgent"].noul)
Clé API manquante ou invalide. Vérifiez le jeton du porteur.
422
Forme de requête non valide. Inspectez la réponse pour le champ incriminé.
429
Limite de débit dépassée. Reculez avant de réessayer.
529
Service temporairement surchargé. Reculez avant de réessayer.
Pour 429 et 529, utilisez une interruption exponentielle plutôt qu’une nouvelle tentative immédiate. Les SDK officiels le font automatiquement selon leur politique de nouvelle tentative par défaut.
Alternative : passerelle Vercel AI
Ce site documente également Gateway en tant que couche d'accès pour l'évaluation du SDK AI. Il s'agit d'un chemin d'intégration alternatif, ne faisant pas partie de Jev ou TypeSafe.
import { experimental_evaluate as evaluate } from 'ai';
import { gateway } from '@ai-sdk/gateway';
const result = await evaluate({
model: gateway('typesafe-ai/jev'),
state,
questions,
});
Après ce chapitre :Vous pouvez conserver les informations d'identification côté serveur et recevoir des réponses saisies avec probabilités.
Ne transformez pas la probabilité la plus élevée directement en une action finale. Définissez des fourchettes de suggestion, de confirmation et d’examen humain en fonction du risque commercial.
PROBABILITY
Preuve pour chaque option ou niveau
Choice et Score renvoient la distribution complète. Utilisez-le lorsque les options de deuxième position, l'ambiguïté ou les mesures d'incertitude personnalisées sont importantes.
CONFIDENCE
Un résumé de la forme de la distribution
La confiance compresse la concentration ou la platitude de la distribution en 0–1. Ce n'est pas la même chose que la probabilité de l'option sélectionnée.
Noul: Noul renvoie déjà P(true), il n'a donc pas de confiance séparée. Les valeurs proches de 0,5 sont incertaines ; seuil à la fois du côté oui et du côté non en fonction du risque.
TypeSafe expose la confiance de la distribution des options. Une politique pratique est la suivante :
01
Confiance élevée
Suggérez automatiquement le choix (balise, itinéraire ou verdict) dans votre interface utilisateur.
02
Confiance moyenne
Affichez la suggestion, mais demandez à un opérateur de la confirmer avant de continuer.
03
Faible confiance
Envoyez à une file d’attente humaine sans action par défaut.
Calibrez les seuils sur les exemples étiquetés de votre flux ou de votre boîte de réception. Les seuils sont spécifiques à chaque cas d'utilisation. Ne transférez jamais de suggestions en argent et ne remboursez jamais les effets secondaires.
Seuillez l’action, pas le modèle globalement
action = response.answers["action"]
if action.confidence < 0.5:
route_to_human(state) # uncertain: do not guess
elif action.choice == "check_balance":
show_balance(account_id) # reversible, low stakes
elif action.choice == "approve_transfer":
if action.confidence > 0.9:
confirm_then_execute(account_id)
else:
ask_user_to_confirm(account_id) # higher stakes, higher bar
Calibrer avant l'automatisation
Collectez des exemples représentatifs et étiquetés du flux de travail réel.
Enregistrez les réponses, les distributions, la confiance, la latence et la décision humaine.
Choisissez des seuils séparément pour les actions réversibles, coûteuses et irréversibles.
Surveillez la dérive et réévaluez après avoir modifié l'état, les instructions, les critères ou l'alias du modèle.
Conseils d'État
Passez une chaîne, un objet ou un tableau comme état. Préférez les enregistrements structurés (texte de commentaire + métadonnées) plutôt que de vider un journal de discussion complet lorsqu'un seul message compte.
Après ce chapitre :Vous pouvez concevoir une solution de repli à faible confiance et calibrer les seuils avec des données étiquetées.
Créez un flux de travail complet avec un état structuré, des questions parallèles, une politique appartenant au code, des preuves d'audit, des tentatives et une solution de secours humaine.
Créez un flux de travail complet de tri du support
Envoyez un état de ticket structuré et posez trois questions indépendantes en parallèle. Conservez la politique de routage et de sécurité dans le code.
STATE→CHOICESCORENOUL→POLICY
const questions = {
department: {
type: 'choice',
instructions: 'Which team should handle `ticket.message`?',
criteria: {
returns: 'Exchanges, wrong or damaged items',
shipping: 'Delivery status, delays, or lost packages',
billing: 'Charges, invoices, or payment problems',
other: 'None of the above'
}
},
frustration: {
type: 'score',
instructions: 'How frustrated is the customer?',
criteria: ['Calm', 'Concerned but civil', 'Very angry']
},
refund_requested: {
type: 'noul',
instructions: 'Does `ticket.message` request money back?'
}
};
Transformez les réponses saisies en une décision vérifiable
Conservez les informations d’identification et les appels de modèle côté serveur.
Validez la taille de l'état, les champs obligatoires et les définitions de questions avant d'appeler l'API.
Stockez la version du modèle, la version de la question, les probabilités, la confiance et l'action finale.
Fournissez un chemin explicite autrui/humain et n’inventez jamais un défaut sur l’incertitude.
Réessayez 429 et 529 avec un intervalle exponentiel limité ; ne réessayez pas les erreurs de validation.
Testez par rapport aux cas extrêmes étiquetés et recalibrez les seuils avant d’activer l’automatisation.
Case index
Six Jev patterns to explore next
These are research paths, not claims that this site built the projects. Each card opens the corresponding category in the open-source radar so you can inspect real implementations and source evidence.