Tutorial TypeSafe Jev passo dopo passo. Guida pratica a TypeSafe Jev, il modello IA System One per decisioni software tipizzate.
01
Inquadra il compito
Decidi se Jev è adatto
Jev non è un modello di chat. Trasforma lo stato esistente in una decisione Scelta, Punteggio o Noul chiusa e restituisce una distribuzione di probabilità.
Una buona soluzione
Usa Jev per decisioni limitate
Instrada una richiesta a una coda denominata.
Inserire un record su una scala ordinata di rischio o qualità.
Stimare se una condizione chiaramente definita è vera.
Non è una buona soluzione
Utilizzare invece un modello generativo
Scrivere, riassumere, tradurre o riscrivere testi a risposta aperta.
Tieni una conversazione naturale a più turni.
Creare una risposta quando non è possibile nominare in anticipo gli output validi.
Il modello mentale ufficiale
STATE
Uno Stato da valutare
Passa una stringa, un oggetto o un array contenente il testo e i fatti correlati necessari al giudizio. Utilizza i campi oggetto denominati per la maggior parte delle richieste reali.
QUESTIONS
Un giudizio immediato per domanda
Ogni domanda dovrebbe porre una cosa mirata che una persona esperta potrebbe giudicare rapidamente dallo stato fornito.
PARALLEL
Domande indipendenti in parallelo
Le domande in una richiesta vedono lo stesso stato, vengono eseguite in modo indipendente e non diffondono una risposta in un'altra.
CODE
Componi le risposte in codice
Peso, soglia, diramazione e combinazione delle risposte digitate nel codice ordinario invece di nascondere la logica del flusso di lavoro in un unico prompt.
Prova di decomposizione: Se il giudizio pesa su più fattori indipendenti o richiede un ragionamento esteso, suddividilo in domande atomiche e combina le risposte in codice.
Dopo questo capitolo:È possibile separare le attività di generazione di contenuti dalle attività con decisioni strutturate.
Utilizzare Scelta per etichette mutuamente esclusive, Punteggio per livelli ordinati e Noul per un giudizio vero o falso.
Digitare
Tu fornisci
Ricevi
Utilizzare quando
choice
Opzioni denominate → descrizioni
Chiave selezionata + probabilità per opzione (+ confidenza)
Etichette/percorsi reciprocamente esclusivi
score
Livelli ordinati (2–10), basso → alto
Punteggio di livello ponderato in base alla probabilità + probabilità del ramo
Gravità, qualità, rubriche di rischio
noul
Proposta sì/no (+ criteri facoltativi)
Probabilità di vero
Verifiche dei singoli fatti
choiceFino a 255 opzioni
Un vincitore più la distribuzione completa
Utilizzare per alternative fisse e non ordinate. Aggiungi altro/nessuno quando l'elenco potrebbe non coprire tutti gli stati. Il valore scelto è l'opzione con la probabilità più alta.
Utilizzare per un giudizio sì/no pulito. Vicino a 0,5 significa incertezza, non un importo medio della proprietà. Noul non ha un campo di confidenza separato.
{
"type": "noul",
"noul": 0.95
}
Il punteggio non è la precisione. Un punteggio di 1,5 su una rubrica 0-2 è un livello previsto, non "corretto al 75%". Non considerare la sicurezza del punteggio o della scelta come una promessa di accuratezza.
Dopo questo capitolo:Puoi selezionare la forma di risposta corretta per il routing, la moderazione e il punteggio di rischio.
Mantieni stabili i nomi delle opzioni, definisci i confini che si escludono a vicenda, includi un percorso residuo e assegna a ciascuna domanda una decisione.
Scrivere criteri forti
Opzioni disgiunte. Se due chiavi di scelta possono essere entrambe vere, gli operatori combatteranno il modello.
Descrivere i bordi. Indica cosa include buy_intent (stock, spedizione) rispetto a price_question.
Mantieni il residuo per ultimo. Usa gli altri/umani come vie di fuga, non come pigri raccoglitori di tutto.
Ordina il punteggio in modo crescente. Gli array di criteri sono più bassi → più alti.
Una decisione per domanda. Dividere il "percorso" da "urgenza" in chiavi separate.
Anatomia di una domanda
question_id
Una chiave di ricerca della risposta per il tuo codice. Non viene inviato al modello, quindi le istruzioni devono contenere comunque la domanda completa.
type
scelta, punteggio o noul. Scegli la forma su cui il tuo codice può agire direttamente.
instructions
Il giudizio completo e specifico. Può essere una stringa, un oggetto o un array e può fare riferimento a percorsi di stato denominati.
criteria
Opzioni di scelta, livelli di punteggio ordinati o chiarimenti facoltativi vero/falso per Noul.
Esempio · una decisione, confini disgiunti
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'
}
}
Stato della struttura e campi esatti di riferimento
Conserva le prove nei campi di stato denominati e indica loro le istruzioni con percorsi punto e indice. Ciò riduce l'ambiguità su quale testo, record o policy dovrebbe controllare la risposta.
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`?'
}
};
Batch per impostazione predefinita: Poni tutte le domande che utilizzano lo stesso stato in un'unica richiesta, anche domande speculative. Effettua una seconda richiesta solo quando il suo stato o le sue opzioni dipendono veramente da una risposta precedente.
Dopo questo capitolo:È possibile scrivere una definizione di domanda stabile e verificabile che il codice possa utilizzare.
Chiama l'endpoint o l'SDK System One ufficiale dal tuo server, esamina la risposta digitata e gestisci gli errori di convalida, limite di velocità e sovraccarico. Il gateway rimane un percorso di accesso facoltativo.
Inizia con l'endpoint HTTP ufficiale
Mantieni TYPESAFE_API_KEY sul server. Invia stato, modello e una mappa di domande con nome a 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?"
}
}
}'
Utilizza l'SDK ufficiale per le risposte digitate e i tentativi
L'SDK Python legge TYPESAFE_API_KEY dall'ambiente, per impostazione predefinita è jev-latest, espone classi di domande/risposte digitate e applica la policy di ripetizione predefinita.
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)
Chiave API mancante o non valida. Controlla il gettone Portatore.
422
Forma della richiesta non valida. Esaminare la risposta per il campo offensivo.
429
Limite di velocità superato. Fare marcia indietro prima di riprovare.
529
Servizio temporaneamente sovraccarico. Fare marcia indietro prima di riprovare.
Per 429 e 529, utilizzare il backoff esponenziale anziché il nuovo tentativo immediato. Gli SDK ufficiali lo fanno automaticamente in base alla politica di ripetizione predefinita.
Alternativa: Vercel AI Gateway
Questo sito documenta inoltre Gateway come livello di accesso per la valutazione dell'SDK AI. È un percorso di integrazione alternativo, non parte di Jev o 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,
});
Dopo questo capitolo:Puoi mantenere le credenziali lato server e ricevere risposte digitate con probabilità.
Non trasformare la massima probabilità direttamente in un'azione finale. Imposta fasce per suggerimenti, conferme e revisione umana in base al rischio aziendale.
PROBABILITY
Prove per ogni opzione o livello
Scelta e Punteggio restituiscono la distribuzione completa. Usalo quando contano le opzioni del secondo classificato, l'ambiguità o le misure di incertezza personalizzate.
CONFIDENCE
Una sintesi della forma della distribuzione
La fiducia comprime la concentrazione o la piatta distribuzione in 0–1. Non è la stessa cosa della probabilità dell'opzione selezionata.
Noul: Noul restituisce già P(vero), quindi non ha confidenza separata. Valori prossimi a 0,5 sono incerti; soglia sia il lato sì che quello no in base al rischio.
TypeSafe espone la fiducia dalla distribuzione delle opzioni. Una politica pratica è:
01
Alta fiducia
Suggerisci automaticamente la scelta (tag, percorso o verdetto) nella tua interfaccia utente.
02
Confidenza media
Mostra il suggerimento, ma richiedi la conferma da parte di un operatore prima di continuare.
03
Bassa fiducia
Invia a una coda umana senza alcuna azione predefinita.
Calibra i limiti sugli esempi etichettati dal tuo stream o dalla tua casella di posta. Le soglie sono specifiche del caso d'uso. Non trasferire mai suggerimenti in denaro o rimborsare effetti collaterali.
Limita l’azione, non il modello a livello globale
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
Calibrare prima dell'automazione
Raccogli esempi rappresentativi ed etichettati dal flusso di lavoro reale.
Registra risposte, distribuzioni, confidenza, latenza e decisione umana.
Scegli le soglie separatamente per azioni reversibili, costose e irreversibili.
Monitora la deriva e rivaluta la situazione dopo aver modificato lo stato, le istruzioni, i criteri o l'alias del modello.
Consigli statali
Passa una stringa, un oggetto o un array come stato. Preferisci record strutturati (testo del commento + metadati) rispetto al dump di un intero registro della chat quando conta solo un messaggio.
Dopo questo capitolo:È possibile progettare un fallback a bassa confidenza e calibrare le soglie con dati etichettati.
Costruisci un flusso di lavoro completo con stato strutturato, domande parallele, policy di proprietà del codice, prove di audit, nuovi tentativi e un fallback umano.
Crea un flusso di lavoro completo di valutazione del supporto
Invia uno stato del ticket strutturato e poni tre domande indipendenti in parallelo. Mantieni la politica di routing e sicurezza nel codice.
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?'
}
};
Trasforma le risposte digitate in una decisione verificabile
Conserva le credenziali e le chiamate dei modelli lato server.
Convalida la dimensione dello stato, i campi obbligatori e le definizioni delle domande prima di chiamare l'API.
Memorizza la versione del modello, la versione della domanda, le probabilità, la confidenza e l'azione finale.
Fornire un percorso altro/umano esplicito e non inventare mai un default sull’incertezza.
Riprovare 429 e 529 con backoff esponenziale limitato; non riprovare gli errori di convalida.
Testare i casi limite etichettati e ricalibrare le soglie prima di abilitare l'automazione.
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.