Come si usa Jev: guida pratica alle tre domande tipizzate di TypeSafe

Chi arriva a Jev dopo anni di prompt engineering fa quasi sempre lo stesso errore: scrive un prompt lungo, chiede una risposta in JSON e spera che il parser regga. Con Jev non funziona così, e non perché sia una versione più severa di un modello linguistico: è proprio un’altra interfaccia. Come si usa Jev è una domanda che si risolve in una frase, si manda uno stato e una lista di domande tipizzate, e tornano valori su cui il codice può ramificare. Qui non ripetiamo cos’è la categoria dei System One Model: entriamo direttamente nell’uso.

In questo articolo scoprirai:

• Come si usa Jev: si manda uno stato e una lista di domande, non un prompt
• Le tre domande tipizzate di Jev: Choice, Score e Noul
• Domande atomiche e componibili: la regola che distingue chi ha capito Jev
• Come provare Jev senza accesso diretto: Pydantic AI, liteLLM, AI/ML API e Cloudflare
• Quando Jev non serve: i limiti da mettere in conto prima di integrarlo

Come si usa Jev: si manda uno stato e una lista di domande, non un prompt

La chiamata è una sola, su un endpoint solo: POST https://api.typesafe.ai/v1/systemone. Il corpo della richiesta ha tre campi, state (una stringa, un oggetto o un array: il contesto su cui si decide), model (per esempio jev-latest) e questions, una mappa di domande con identificatori scelti da te. Non esiste un campo “prompt”, e questa assenza è il punto: lo stato descrive la situazione, le domande descrivono le decisioni.

Ecco come si presenta un corpo di richiesta minimo, un ticket di assistenza da smistare, con una Choice, una Score e una Noul nella stessa chiamata:

{
  "model": "jev-latest",
  "state": {
    "oggetto": "Impossibile accedere dopo il cambio password",
    "messaggio": "Ho reimpostato la password ieri e ora il login restituisce errore 403. Mi serve entrare entro stasera, ho una consegna.",
    "piano_cliente": "business"
  },
  "questions": {
    "reparto_di_destinazione": {
      "type": "choice",
      "criteria": {
        "accessi": "problemi di login, password, autenticazione a due fattori, sessioni scadute",
        "fatturazione": "pagamenti, rinnovi, fatture, cambi di piano",
        "bug_prodotto": "funzionalita che non si comporta come documentato",
        "richiesta_commerciale": "domande su prezzi, preventivi, contratti"
      }
    },
    "urgenza_dichiarata": {
      "type": "score",
      "criteria": [
        "nessuna urgenza espressa",
        "urgenza generica senza scadenza",
        "scadenza indicata entro qualche giorno",
        "scadenza indicata entro poche ore",
        "blocco operativo in corso"
      ]
    },
    "richiede_intervento_umano": {
      "type": "noul",
      "criteria": "vero se il messaggio descrive un blocco dell'account che l'assistenza automatica non puo sbloccare da sola; falso se esiste una procedura self-service applicabile"
    }
  }
}

E questa è la forma della risposta corrispondente: una chiave per ogni identificatore che hai scelto tu, con il tipo di valore fissato dal tipo di domanda.

{
  "results": {
    "reparto_di_destinazione": {
      "choice": "accessi",
      "probabilities": {
        "accessi": 0.94,
        "bug_prodotto": 0.04,
        "fatturazione": 0.01,
        "richiesta_commerciale": 0.01
      },
      "confidence": 0.91
    },
    "urgenza_dichiarata": {
      "score": 3.7,
      "levels": [
        "nessuna urgenza espressa",
        "urgenza generica senza scadenza",
        "scadenza indicata entro qualche giorno",
        "scadenza indicata entro poche ore",
        "blocco operativo in corso"
      ],
      "probabilities": [0.01, 0.04, 0.28, 0.58, 0.09],
      "confidence": 0.82
    },
    "richiede_intervento_umano": {
      "value": 0.76
    }
  }
}

Si vede subito la differenza con un JSON strappato a un modello linguistico: non c’è testo da ripulire, le chiavi sono quelle che hai dichiarato tu, e ogni valore è già nella forma su cui il codice può fare un if.

Come Jev valuta le domande: in parallelo e in isolamento

La differenza operativa più importante arriva subito dopo. La documentazione di TypeSafe spiega che le domande vengono valutate «in parallelo e in isolamento contro lo stesso stato, in un colpo solo», e che aggiungere domande non fa quasi variare il tempo di risposta. In isolamento significa che la quinta domanda non vede le risposte delle prime quattro: non c’è una catena di ragionamento che si autoconvince, e non c’è ordine che conti. Se ti serve che la domanda B dipenda dalla risposta di A, quella dipendenza la scrivi tu nel tuo codice, non nel prompt.

Quanto costa usare Jev: latenza e prezzo per decisione

Il budget è la seconda sorpresa. TypeSafe dichiara nel blog di lancio un tempo di risposta end-to-end fra 70 e 500 ms e un prezzo di 0,042 dollari per milione di token in ingresso, con l’output gratuito. Poiché l’output è tipizzato e minuscolo, il costo di una decisione coincide praticamente con il costo di rileggere lo stato: dieci domande sullo stesso stato costano quanto una, più i pochi token delle istruzioni. È l’esatto contrario dell’economia a cui abituano le API dei modelli linguistici, dove la generazione è la voce di spesa che cresce.

Le tre domande tipizzate di Jev: Choice, Score e Noul

Tre primitive, e nient’altro. Si possono mescolare liberamente nella stessa chiamata, e ciascuna ha una forma di risposta fissa.

Choice: scegliere un’opzione da una lista di massimo 255

Choice serve quando la decisione è «quale fra questi». Il campo criteria è obbligatorio ed è una mappa opzione → descrizione: la descrizione non è documentazione per il lettore umano, è la rubrica che il modello usa per assegnare l’opzione. Torna l’opzione scelta, la distribuzione di probabilità su tutte le opzioni e un punteggio di confidenza fra 0 e 1. L’API reference fissa il tetto: massimo 255 opzioni per ogni Choice. È il caso classico dello smistamento, categoria di un ticket, reparto, modello a cui instradare una richiesta.

Score: una rubrica ordinata da 2 a 10 livelli

Score valuta lo stato su una scala ordinata. Qui criteria è un array ordinato di descrizioni dei livelli, e secondo l’API reference i livelli ammessi vanno da 2 a 10. Torna un punteggio pesato sulle probabilità, la legenda dei livelli, le probabilità e la confidenza. Il valore pesato è la parte interessante: se il modello è indeciso fra il livello 2 e il 3, il numero che ricevi lo dice, invece di nasconderlo dietro un’etichetta secca.

Noul: la domanda vero/falso senza confidence score

Noul è la domanda sì/no: torna un solo valore fra 0 e 1, cioè la probabilità che l’affermazione sia vera. Un dettaglio che vale la pena riportare per bene: per Noul la documentazione non prevede il punteggio di confidenza, che secondo l’API reference di TypeSafe esiste solo per Choice e Score. Il campo criteria qui è facoltativo, ma conviene comunque compilarlo con la descrizione di cosa conta come true e cosa come false: è quello che trasforma una domanda vaga in una domanda decidibile.

Domande atomiche e componibili: la regola che distingue chi ha capito Jev

Questa è la buona pratica centrale, e non è un consiglio di stile. La documentazione chiede domande atomiche e ben delimitate: singole determinazioni che una persona competente prenderebbe in pochi secondi. Se una domanda pesa più fattori indipendenti, o richiederebbe un ragionamento esteso, va scomposta, un fattore per domanda, e i risultati si ricombinano con la logica nel proprio codice.

La motivazione dichiarata è il context rot: la precisione degrada quando lo stato contiene materiale irrilevante, un effetto che si capisce meglio sapendo come funziona un modello di AI, mentre secondo la documentazione TypeSafe aggiungere domande indipendenti non produce degrado, perché ogni valutazione è isolata. Tradotto in pratica: non c’è nessun risparmio nel comprimere tre decisioni in una domanda sola, e c’è un guadagno misurabile nello spezzarle.

Un esempio concreto viene da Langfuse, che ha costruito valutatori automatici su Jev: per capire se un utente sta contestando la risposta precedente dell’assistente, definiscono in modo esplicito cosa conta come «vero», rifiuta, corregge, chiede di annullare, reindirizza più volte, e cosa no, come il chiarimento educato o il follow-up neutro. Nello stesso lavoro riportano una soglia di confidenza fissata a 0,7, con tre esiti: sopra si agisce, nella fascia intermedia si passa a un umano, sotto si scarta. La scomposizione serve anche a questo: una domanda atomica ha una confidenza interpretabile, una domanda-minestrone no.

Come provare Jev senza accesso diretto: Pydantic AI, liteLLM, AI/ML API e Cloudflare

L’accesso diretto a TypeSafe è ancora in early access con lista d’attesa. Esistono però strade documentate da terze parti, che restano servizi terzi, quindi vanno verificate al momento in cui le usi.

La più comoda per chi lavora in Python è Pydantic AI, che espone Jev come modello con gli alias jev-latest, jev-preview e versioni pinnabili, si installa con pip install "pydantic-ai-slim[typesafe]" e legge la chiave da TYPESAFE_API_KEY. La mappatura è elegante: ogni campo dell’output_type diventa una domanda. L’esempio della documentazione è proprio un gate su comandi di shell pericolosi, lo stesso problema di chi si chiede quali permessi dare a un agente di coding.

Chi ha già un proxy può usare il pass-through di liteLLM su /typesafe/v1/systemone, che inoltra la richiesta sostituendo la base URL e restituisce anche l’uso dei token per la contabilità. AI/ML API espone il modello come typesafe/jev su /v1/decisions, con esempi in Python e JavaScript su tutte e tre le domande. Su Cloudflare AI il modello si chiama typesafe/jev e la scheda dichiara una finestra di contesto di 32.000 token: un numero che conviene tenere a mente, perché Langfuse segnala che il limite effettivo dello stato è riportato in modo discordante fra le fonti (32k contro 64k). Su questo punto la documentazione non è allineata, e finché non lo è la stima prudente è la più bassa.

Quando Jev non serve: i limiti da mettere in conto prima di integrarlo

Una guida onesta dice anche quando lo strumento è quello sbagliato. Jev non produce testo libero: se ti serve una risposta da leggere, una sintesi o una spiegazione, non è il posto, lì restano i modelli linguistici o un motore di risposta come Perplexity. Il tetto di 255 opzioni esclude le tassonomie molto larghe: sopra quella soglia si scompone in più Choice annidate, con la gerarchia gestita dal tuo codice.

Ci sono due limiti meno ovvi, entrambi riportati da chi l’ha messo in produzione: secondo il benchmark di Langfuse Jev non si astiene, sceglie comunque la risposta «meno sbagliata», e non spiega il verdetto, quindi il debug si fa riscrivendo i criteri, non leggendo un ragionamento. Per questo la soglia di confidenza non è un dettaglio implementativo: è il meccanismo con cui l’astensione te la costruisci tu. Nello stesso benchmark il confronto economico è netto, circa 160 dollari per milione di verdetti contro i 33.000 di un modello di frontiera, con il 91,5% di accordo sui verdetti: ottimo per filtrare e instradare, non abbastanza per decidere da solo dove l’errore costa caro.

Lo stesso vincolo si sente quando Jev sta dentro un sistema agentico: LangChain racconta l’uso di Jev come harness, cioè come strato che decide se un passo dell’agente va eseguito, ripetuto o fermato, le decisioni restano a Jev, il lavoro con le parole e le chiamate agli strumenti restano altrove. È la conferma pratica del limite: utile come guardrail sul flusso, mai come motore del flusso.

Il modo giusto di collocarlo, insomma, è dentro il flusso: Jev decide i rami, l’agente o il modello generativo fa il lavoro che richiede parole. Se vuoi capire perché questa separazione regga anche sul piano dei fallimenti, abbiamo spiegato altrove perché Jev non può allucinare e cosa invece può sbagliare.

Fonti:

• TypeSafe Docs, Introduction ai System One Model
• TypeSafe Docs, API reference dell’endpoint systemone
• TypeSafe Blog, Introducing System One Models and Jev
• Langfuse, Using TypeSafe’s Jev for evals
• LangChain, Building a harness with Jev
• Pydantic AI, supporto ai modelli TypeSafe
• liteLLM, pass-through TypeSafe
• AI/ML API, decision model typesafe/jev
• Cloudflare Workers AI, scheda modello typesafe/jev