use-jev-cli

Utilisation de jev-cli

jev-cli demande à Jev, un modèle d'évaluation « Système Un », de juger un état partagé par rapport à un ensemble de questions typées. Il renvoie du JSON structuré — un choix, un score ou une probabilité — jamais de prose.

Utilisez-le lorsque vous avez besoin d'une décision sur laquelle votre code peut bifurquer. Il est bien plus rapide et moins coûteux qu'un appel LLM complet (facturé par jeton d'entrée, avec zéro jeton de sortie), donc vérifier dix propriétés d'un diff, d'un journal ou d'une transcription de support est peu coûteux.

Ne l'utilisez pas pour écrire, résumer, traduire ou reformuler quoi que ce soit. Il ne peut pas produire de texte.

Exécutez simplement l'évaluation. Il n'y a aucune vérification préalable à effectuer — eval échoue rapidement avec un message exploitable et un code de sortie distinct en cas de problème, et jev-cli doctor est le diagnostic auquel vous avez recours ensuite, pas avant chaque appel.

Exécuter une évaluation

jev-cli eval --state <text> --questions <json>

jev-cli eval -s "L'agent de support a émis un remboursement complet de 40 $ et s'est excusé." -q '{
  "rembourse": {"type": "boolean", "instructions": "Un remboursement a-t-il été émis ?"},
  "ton":     {"type": "choice",  "instructions": "Quel ton l'agent a-t-il utilisé ?",
               "criteria": {"chaleureux": "amical et personnalisé", "sec": "laconique ou dédaigneux"}},
  "qualité":  {"type": "score",   "instructions": "Évaluez comment cela a été géré.",
               "criteria": ["médiocre", "acceptable", "excellent"]}
}'

{
  "rembourse": { "type": "boolean", "probability": 0.99 },
  "ton": { "type": "choice", "choice": "chaleureux", "probabilities": { "sec": 0.02, "chaleureux": 0.98 } },
  "qualité": { "type": "score", "score": 1.78, "probabilities": { "0": 0, "1": 0.22, "2": 0.78 } }
}

Cette forme en ligne convient pour une phrase que vous rédigez vous-même. Pour tout ce qui existe déjà dans un fichier ou dans la sortie d'une commande, lisez Passage des entrées ensuite — c'est ce que la plupart des appelants font mal.

Passage des entrées : gardez le contenu en dehors de la ligne de commande

Par défaut, utilisez --state-file / --questions-file, ou un tube vers -. Les options en ligne -s / -q sont réservées aux textes courts que vous rédigez véritablement, pas pour du contenu qui existe déjà ailleurs.

Cela importe plus quand un agent est l'appelant qu'il n'y paraît :

1. Le contenu en ligne doit être généré jeton par jeton. Coller un diff de 50 Ko dans -s signifie émettre ~15 000 jetons de sortie — facturés aux tarifs de sortie, lent car la génération est séquentielle, et une retranscription d'un contenu que vous avez déjà, ce qui invite à la troncature et à la dérive silencieuses. Un chemin coûte ~10 jetons, et un tube maintient le contenu complètement hors de votre fenêtre de contexte.
2. Le shell réécrit le contenu en ligne, parfois en l'exécutant. Entre guillemets doubles, `cmd` est une substitution de commande et ${VAR} se développe. Passer -s "const m = `echo hi`; const p = ${HOME}" envoie au modèle const m = hi; const p = /Users/vous — l'accent grave a été exécuté. Avec une entrée non fiable (un diff PR, un journal utilisateur), c'est une surface d'exécution de commande, pas seulement une corruption. Entre guillemets simples, une apostrophe dans le contenu casse la commande.

La taille n'est pas le facteur déterminant : ~150 Ko passent bien dans le shell, et le budget propre de Jev s'épuise en premier. La sécurité du contenu et le coût des jetons en sont les raisons.

# Meilleur — le contenu n'entre jamais dans le contexte du modèle
git diff | jev-cli eval --state-file - --questions-file ./checks.json

# Bien — préparez avec une commande, passez des chemins
git log -20 --oneline > /tmp/state.txt
jev-cli eval --state-file /tmp/state.txt --questions-file ./checks.json

# Correct — texte court que vous écrivez réellement
jev-cli eval -s "L'agent a émis un remboursement complet." -q '{"r":{"type":"boolean","instructions":"Remboursé ?"}}'

# Erroné — retranscrire un fichier que vous avez déjà, via le shell
jev-cli eval -s "$(cat huge-diff.txt)" -q ...

Une seule entrée peut lire l'entrée standard. Quand les deux sont volumineuses, pipez l'une et passez l'autre comme chemin. Réutilisez un fichier de questions entre les appels plutôt que de le réémettre.

Ajoutez --state-json quand l'état est du JSON plutôt que du texte brut.

Les trois types de questions

Chaque question a besoin d'instructions. instructions et chaque description de critère peut être une chaîne, un objet JSON ou un tableau JSON — mais jamais un nombre nu ou un booléen.

Type	criteria	Réponse
boolean	Optionnel {"true": ..., "false": ...}, chaque côté peut être omis	{"type":"boolean","probability":0.98}
choice	Requis. Objet nom d'option → description (null pour aucun)	{"type":"choice","choice":"chaleureux","probabilities":{...}}
score	Requis. Tableau d'au moins deux niveaux, le plus bas en premier	{"type":"score","score":1.83,"probabilities":{...}}

Trois choses qui surprennent :

• boolean donne P(true), pas un booléen. 0.98 signifie que le modèle met 98% sur vrai. Ce n'est pas une confiance et ce n'est pas calibré — choisissez votre propre seuil. 0.5 signifie « tout aussi probable vrai ou faux », pas « moyen ».
• score est une position fractionnaire de 0 à criteria.length - 1 — la moyenne pondérée par la probabilité, pas un index. Utilisez-le, pas boolean, pour les graduations.
• choice renvoie le nom de l'option textuellement, donc nommez les options comme les valeurs sur lesquelles votre code basculera. Leurs probabilités totalisent 1, donc il choisit exactement un gagnant — pour « lesquels de ceux-ci s'appliquent, possiblement plusieurs », utilisez un boolean par candidat à la place.

Limites strictes

• L'état et les questions partagent un budget d'environ 32 000 jetons (~150 000 caractères d'anglais). Le dépassement échoue avec {"error_type":"max_tokens_exceeded"} et un code HTTP 400.
• Texte uniquement. L'état doit être une chaîne, un objet JSON ou un tableau de texte. Pas d'images, audio ou vidéo.

Vous ne pouvez donc pas donner un codebase, une archive complète de journaux ou un grand corpus à Jev. Construisez à l'avance un index compact ou un extrait et évaluez cela. Voir references/patterns.md pour savoir comment structurer cela.

Demandez tout en un seul appel

Les questions sont évaluées en parallèle et isolément — elles ne se voient jamais entre elles. Le groupement est presque gratuit : TypeSafe mesure 13 questions dans une requête comme 11,5x moins cher et 9,6x plus rapide que 13 requêtes séparées, avec des réponses identiques. Leur documentation note que les agents de codage tombent dans l'habitude d'une question par appel plus que les humains — ne faites pas cela.

Demandez tout ce dont vous pourriez avoir besoin en une seule requête et jetez ce que vous n'utilisez pas. Enchaînez une deuxième requête seulement lorsque vous ne pouvez vraiment pas la construire sans la première réponse.

Lire le résultat

La sortie par défaut est l'objet de réponses brutes, indexé par vos identifiants de question, donc il passe directement dans jq :

jev-cli eval --state-file - -q "$CHECKS" | jq -e '.deploy_ok.probability > 0.9' >/dev/null && echo sain

Ajoutez --full pour l'utilisation, les avertissements et providerMetadata — où TypeSafe rapporte la confidence pour les réponses de choix et de score, qui est distincte des probabilités. Ajoutez --compact pour du JSON sur une seule ligne.

Codes de sortie et erreurs

eval écrit les erreurs sur stderr en JSON ({"error":{"code","message"}}), gardant stdout propre. Toujours bifurquer sur le code de sortie :

Code	Signification	Que faire
0	Succès	Analyser stdout
1	Échec du fournisseur ou réseau	Réessayer une fois ; signaler si persiste
2	Mauvaise utilisation ou questions invalides	Corriger le JSON — le message nomme l'identifiant de question et le champ en cause
3	Identifiants manquants ou rejetés	Relayer le message à l'utilisateur ; ne pas réessayer. Voir ci-dessous

Un message de code 2 comme questions.quality.criteria must list at least two ordered levels, but got 1 pointe vers le chemin exact à corriger.

Diagnostiquer un échec

Uniquement quand un appel échoue réellement, et seulement pour les codes 1 et 3 :

jev-cli doctor --offline   # config, fournisseur, modèle, source de clé — aucun appel réseau
jev-cli doctor             # ce qui précède, plus une petite évaluation en direct

Le code 3 porte les propres mots du fournisseur, et ils distinguent les cas qui nécessitent des correctifs différents — une clé manquante, une clé révoquée, un compte sans facturation configurée, ou un modèle que le plan ne peut pas atteindre se lisent tous différemment. Relayer ce message plutôt que de supposer que la clé est erronée, et n'inventez jamais de clé. Si l'une est vraiment manquante, l'utilisateur la fournit :

jev-cli config set providers.vercel.apiKey <clé-passrelle-ia>

N'affichez jamais de clé en retour — config list les masque sauf si --show-secrets est passé.

Référence de configuration

La configuration se trouve dans ~/.jev-cli/config.yaml (remplacez le répertoire avec JEV_CLI_HOME), écrit 0600.

jev-cli config path                       # où se trouve le fichier
jev-cli config list                       # chaque valeur, clés masquées
jev-cli config get providers.vercel.model
jev-cli config set providers.vercel.model typesafe-ai/jev
jev-cli config unset providers.vercel.baseURL

La priorité est drapeau CLI > environnement (JEV_CLI_API_KEY, puis AI_GATEWAY_API_KEY) > fichier de configuration. En CI, définissez JEV_CLI_API_KEY et ignorez le fichier de configuration.

provider n'accepte actuellement que vercel (Vercel AI Gateway). La valeur jev est réservée pour l'API officielle de TypeSafe et est rejetée jusqu'à implémentation.

Pour aller plus loin

• references/question-design.md — comment formuler les questions et structurer l'état pour que les réponses soient exploitables : questions atomiques, division des jugements composites, mono- vs multi-étiquettes, choix entre les trois types.
• references/patterns.md — architectures pour des problèmes plus grands : évaluation spéculative, présélection en deux étapes, classification hiérarchique sur des taxonomies et des codebases, routage contrôlé par la confiance.

Index officiel de la documentation (lisible par agent) : https://docs.typesafe.ai/llms.txt