use-jev-cli

Usando jev-cli

jev-cli le pide a Jev, un modelo de evaluación "System One", que juzgue un estado compartido contra un conjunto de preguntas tipadas. Devuelve JSON estructurado — una elección, una puntuación o una probabilidad — nunca prosa.

Úsalo cuando necesites una decisión en la que tu código pueda ramificarse. Es mucho más rápido y barato que una llamada completa a un LLM (se cobra por token de entrada, con cero tokens de salida), por lo que verificar diez propiedades de un diff, un log o una transcripción de soporte es barato.

No lo uses para escribir, resumir, traducir o reescribir nada. No puede producir texto.

Simplemente ejecuta la evaluación. No hay ninguna verificación de configuración que realizar primero — eval falla rápido con un mensaje procesable y un código de salida distinto cuando algo está mal, y jev-cli doctor es el diagnóstico al que recurres entonces, no antes de cada llamada.

Ejecutando una evaluación

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

jev-cli eval -s "El agente de soporte emitió un reembolso completo de $40 y se disculpó." -q '{
  "reembolsado": {"type": "boolean", "instructions": "¿Se emitió un reembolso?"},
  "tono":     {"type": "choice",  "instructions": "¿Qué tono usó el agente?",
               "criteria": {"cálido": "amable y personal", "seco": "brusco o despectivo"}},
  "calidad":  {"type": "score",   "instructions": "Califica qué tan bien se manejó esto.",
               "criteria": ["pobre", "aceptable", "excelente"]}
}'

{
  "reembolsado": { "type": "boolean", "probability": 0.99 },
  "tono": { "type": "choice", "choice": "cálido", "probabilities": { "seco": 0.02, "cálido": 0.98 } },
  "calidad": { "type": "score", "score": 1.78, "probabilities": { "0": 0, "1": 0.22, "2": 0.78 } }
}

Esa forma en línea es adecuada para una oración que estás escribiendo tú mismo. Para cualquier cosa que ya exista en un archivo o en la salida de un comando, lee Pasando entrada a continuación — es lo que la mayoría de los llamadores hacen mal.

Pasando entrada: mantén el contenido fuera de la línea de comandos

Por defecto, usa --state-file / --questions-file, o un pipe a -. Las opciones en línea -s / -q son para texto corto que realmente estás creando, no para contenido que ya existe en algún lugar.

Esto importa más de lo que parece cuando un agente es el llamador:

1. El contenido en línea debe generarse token por token. Pegar un diff de 50 KB en -s significa emitir ~15k tokens de salida — facturados a tarifas de salida, lentos porque la generación es en serie, y una retranscripción del contenido que ya tienes, lo que invita a la truncación silenciosa y a la deriva. Una ruta cuesta ~10 tokens, y un pipe mantiene el contenido completamente fuera de tu ventana de contexto.
2. El shell reescribe el contenido en línea, a veces ejecutándolo. En comillas dobles, `cmd` es sustitución de comando y ${VAR} se expande. Pasar -s "const m = `echo hi`; const p = ${HOME}" envía al modelo const m = hi; const p = /Users/you — la comilla invertida se ejecutó. Con entrada no confiable (un diff de PR, un log de usuario) eso es una superficie de ejecución de comandos, no solo corrupción. En comillas simples, un apóstrofe en el contenido rompe el comando directamente.

El tamaño no es el factor decisivo: ~150 KB pasa a través del shell sin problemas, y el presupuesto propio de Jev es el primero en limitar. La seguridad del contenido y el costo de los tokens son las razones.

# Mejor — el contenido nunca entra en el contexto del modelo
git diff | jev-cli eval --state-file - --questions-file ./checks.json

# Bueno — prepara con un comando, pasa rutas
git log -20 --oneline > /tmp/state.txt
jev-cli eval --state-file /tmp/state.txt --questions-file ./checks.json

# Aceptable — texto corto que realmente estás escribiendo
jev-cli eval -s "El agente emitió un reembolso completo." -q '{"r":{"type":"boolean","instructions":"¿Reembolsado?"}}'

# Incorrecto — retranscribiendo un archivo que ya tienes, a través del shell
jev-cli eval -s "$(cat huge-diff.txt)" -q ...

Solo una entrada puede leer stdin. Cuando ambas son grandes, canaliza una y pasa la otra como ruta. Reutiliza un archivo de preguntas en varias llamadas en lugar de volver a emitirlo.

Añade --state-json cuando el estado sea JSON en lugar de texto plano.

Los tres tipos de preguntas

Toda pregunta necesita instructions. instructions y cada descripción de criterio pueden ser una cadena, un objeto JSON o un array JSON — pero nunca un número o booleano simple.

Tipo	criteria	Respuesta
boolean	Opcional {"true": ..., "false": ...}, cualquier lado omitible	{"type":"boolean","probability":0.98}
choice	Requerido. Objeto de nombre de opción → descripción (null para ninguna)	{"type":"choice","choice":"cálido","probabilities":{...}}
score	Requerido. Array de al menos dos niveles, primero el más bajo	{"type":"score","score":1.83,"probabilities":{...}}

Tres cosas que confunden a la gente:

• boolean da P(verdadero), no un booleano. 0.98 significa que el modelo pone un 98% en verdadero. No es confianza ni está calibrado — elige tu propio umbral. 0.5 significa "igualmente probable verdadero o falso", no "medio".
• score es una posición fraccionaria de 0 a criteria.length - 1 — la media ponderada por probabilidad, no un índice. Úsalo, no boolean, para gradaciones.
• choice devuelve el nombre de la opción textualmente, así que nombra las opciones como los valores sobre los que tu código cambiará. Sus probabilidades suman 1, por lo que elige exactamente un ganador — para "cuáles de estos aplican, posiblemente varios", usa un boolean por candidato en su lugar.

Límites estrictos

• El estado y las preguntas comparten un presupuesto de ~32,000 tokens (~150,000 caracteres de inglés). Excederlo falla con {"error_type":"max_tokens_exceeded"} y HTTP 400.
• Solo texto. El estado debe ser una cadena, objeto JSON o array de texto. Sin imágenes, audio o video.

Por lo tanto, no puedes pasarle a Jev una base de código, un archivo de log completo o un corpus grande. Pre-construye un índice compacto o un extracto y evalúa eso. Consulta references/patterns.md para saber cómo estructurarlo.

Pregunta todo en una sola llamada

Las preguntas se evalúan en paralelo y de forma aislada — nunca se ven entre sí. El procesamiento por lotes es casi gratuito: TypeSafe mide 13 preguntas en una solicitud como 11.5x más barato y 9.6x más rápido que 13 solicitudes separadas, con respuestas idénticas. Su documentación señala que los agentes de codificación caen en el hábito de una pregunta por llamada más de lo que lo hacen las personas — no lo hagas.

Pregunta todo lo que puedas necesitar en una sola solicitud y descarta lo que no uses. Encadena una segunda solicitud solo cuando genuinamente no puedas construirla sin la primera respuesta.

Leyendo el resultado

La salida predeterminada es el objeto de respuestas simples, claveado por tus IDs de pregunta, por lo que se canaliza directamente a jq:

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

Añade --full para uso, advertencias y providerMetadata — donde TypeSafe reporta confidence para respuestas de elección y puntuación, que es independiente de las probabilidades. Añade --compact para JSON de una sola línea.

Códigos de salida y errores

eval escribe los errores en stderr como JSON ({"error":{"code","message"}}), manteniendo stdout limpio. Siempre bifurca en el código de salida:

Código	Significado	Qué hacer
0	Éxito	Analiza stdout
1	Fallo del proveedor o de red	Reintenta una vez; reporta si persiste
2	Mal uso o preguntas inválidas	Arregla el JSON — el mensaje nombra el ID de la pregunta y el campo ofensivo
3	Credenciales faltantes o rechazadas	Transmite el mensaje al usuario; no reintentes. Ver abajo

Un mensaje de código 2 como questions.quality.criteria must list at least two ordered levels, but got 1 apunta a la ruta exacta a corregir.

Diagnosticando un fallo

Solo cuando una llamada realmente falla, y solo para los códigos 1 y 3:

jev-cli doctor --offline   # config, proveedor, modelo, fuente de clave — sin llamada de red
jev-cli doctor             # lo anterior, más una pequeña evaluación en vivo

El código 3 lleva las propias palabras del proveedor, y distinguen casos que necesitan diferentes correcciones — una clave faltante, una clave revocada, una cuenta sin facturación configurada o un modelo que el plan no puede alcanzar se leen de manera diferente. Transmite ese mensaje en lugar de asumir que la clave está mal, y nunca inventes una clave. Si una falta genuinamente, el usuario la proporciona:

jev-cli config set providers.vercel.apiKey <clave-de-puerta-de-enlace-ai>

Nunca imprimas una clave de vuelta — config list las oculta a menos que se pase --show-secrets.

Referencia de configuración

La configuración reside en ~/.jev-cli/config.yaml (anula el directorio con JEV_CLI_HOME), escrito 0600.

jev-cli config path                       # dónde está el archivo
jev-cli config list                       # cada valor, claves ocultas
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 precedencia es bandera de CLI > entorno (JEV_CLI_API_KEY, luego AI_GATEWAY_API_KEY) > archivo de configuración. En CI, establece JEV_CLI_API_KEY y omite el archivo de configuración por completo.

provider actualmente solo acepta vercel (Vercel AI Gateway). El valor jev está reservado para la API oficial de TypeSafe y se rechaza hasta que se implemente.

Para ir más allá

• references/question-design.md — cómo redactar preguntas y estructurar el estado para que las respuestas sean utilizables: preguntas atómicas, dividir juicios compuestos, etiquetado único vs múltiple, elegir entre los tres tipos.
• references/patterns.md — arquitecturas para problemas más grandes: abanico especulativo, preselección en dos etapas, clasificación jerárquica sobre taxonomías y bases de código, enrutamiento controlado por confianza.

Índice oficial de documentación (legible por agente): https://docs.typesafe.ai/llms.txt