TypeSafe Jev steg-för-steg-guide. Praktisk guide till TypeSafe Jev, System One-modellen för typade programvarubeslut.
01
Rama in uppgiften
Bestäm om Jev passar
Jev är ingen chattmodell. Det förvandlar befintligt tillstånd till ett stängt val, poäng eller nol-beslut och returnerar en sannolikhetsfördelning.
En bra passform
Använd Jev för begränsade beslut
Dirigera en begäran till en namngiven kö.
Placera en post på en beställd risk- eller kvalitetsskala.
Uppskatta om ett tydligt uttalat villkor är sant.
Passar inte bra
Använd en generativ modell istället
Skriv, sammanfatta, översätt eller skriv om öppen text.
Håll en naturlig konversation i flera svängar.
Skapa ett svar när de giltiga utgångarna inte kan namnges i förväg.
Den officiella mentala modellen
STATE
En stat att utvärdera
Skicka en sträng, ett objekt eller en array som innehåller texten och relaterade fakta som bedömningen behöver. Använd namngivna objektfält för de flesta verkliga förfrågningar.
QUESTIONS
En snabbdom per fråga
Varje fråga bör ställa en fokuserad sak som en kunnig person snabbt kan bedöma utifrån det angivna tillståndet.
PARALLEL
Oberoende frågor parallellt
Frågor i en begäran ser samma tillstånd, körs oberoende och läcker inte ett svar till ett annat.
CODE
Skriv svar i kod
Vikt, tröskel, gren och kombinera inskrivna svar i vanlig kod istället för att dölja arbetsflödeslogik i en prompt.
Nedbrytningstest: Om bedömningen väger flera oberoende faktorer eller kräver utökade resonemang, dela upp det i atomfrågor och kombinera svaren i kod.
Efter detta kapitel:Du kan separera innehållsgenererande uppgifter från strukturerade beslutsuppgifter.
Använd Choice för ömsesidigt exklusiva etiketter, Score för ordnade nivåer och Noul för en sann-eller-falsk bedömning.
Typ
Du levererar
Du tar emot
Använd när
choice
Namngivna alternativ → beskrivningar
Vald nyckel + sannolikheter per alternativ (+ konfidens)
Ömsesidigt exklusiva etiketter/rutter
score
Beställda nivåer (2–10), låg → hög
Sannolikhetsvägd nivåpoäng + rung probs
Allvarlighet, kvalitet, riskrubriker
noul
Ja/nej förslag (+ valfria kriterier)
Sannolikhet för sant
Enstaka faktakontroller
choiceUpp till 255 alternativ
En vinnare plus hela distributionen
Används för oordnade, fasta alternativ. Lägg till annan/ingen när listan kanske inte täcker alla stater. Det valda värdet är alternativet med högst sannolikhet.
Använd för en ren ja/nej-bedömning. Nära 0,5 betyder osäkerhet, inte en medelstor del av fastigheten. Noul har inget separat förtroendefält.
{
"type": "noul",
"noul": 0.95
}
Poäng är inte noggrannhet. En poäng på 1,5 på en 0–2 rubrik är en förväntad nivå, inte "75% korrekt." Behandla inte poäng eller valförtroende som ett löfte om noggrannhet.
Efter detta kapitel:Du kan välja rätt svarsform för routing, moderering och riskpoäng.
Håll alternativnamn stabila, definiera ömsesidigt uteslutande gränser, inkludera en restväg och ge varje fråga ett beslut.
Skriver starka kriterier
Osammanhängande alternativ. Om två valnycklar båda kan vara sanna kommer operatörerna att bekämpa modellen.
Beskriv kanter. Säg vad buy_intent inkluderar (lager, ship-to) kontra price_question.
Håll resterna sist. Använd andra / mänskliga som utrymningsluckor, inte lata catch-alls.
Ordningspoäng stigande. Kriteriematriser är lägsta → högsta.
Ett beslut per fråga. Dela upp "rutt" från "brådskande" i separata nycklar.
Anatomi av en fråga
question_id
En svarssökningsnyckel för din kod. Den skickas inte till modellen, så instruktioner måste fortfarande innehålla hela frågan.
type
val, poäng eller noul. Välj den form som din kod kan agera på direkt.
instructions
Den fullständiga, specifika bedömningen. Det kan vara en sträng, ett objekt eller en array och kan referera till namngivna tillståndsvägar.
criteria
Valmöjligheter, ordnade poängnivåer eller valfritt sant/falskt förtydligande för Noul.
Exempel · ett beslut, osammanhängande gränser
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'
}
}
Strukturtillstånd och referens till exakta fält
Förvara bevis i namngivna tillståndsfält och peka instruktioner på dem med punkt-och-index-sökvägar. Detta minskar oklarheten om vilken text, post eller policy som ska styra svaret.
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 som standard: Ställ alla frågor som använder samma tillstånd i en begäran – även spekulativa frågor. Gör en andra begäran endast när dess tillstånd eller alternativ verkligen beror på ett tidigare svar.
Efter detta kapitel:Du kan skriva en stabil, testbar frågedefinition som koden kan konsumera.
Ring den officiella System One-slutpunkten eller SDK från din server, inspektera det inskrivna svaret och hantera validerings-, hastighets- och överbelastningsfel. Gateway förblir en valfri åtkomstväg.
Börja med den officiella HTTP-slutpunkten
Behåll TYPESAFE_API_KEY på servern. Skicka tillstånd, modell och en karta med namngivna frågor till 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?"
}
}
}'
Använd den officiella SDK:n för maskinskrivna svar och återförsök
Python-SDK:n läser TYPESAFE_API_KEY från miljön, förinställer jev-senaste, exponerar skrivna fråge-/svar-klasser och tillämpar sin standardpolicy för återförsök.
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)
Saknas eller ogiltig API-nyckel. Kontrollera bärarens token.
422
Ogiltig form för begäran. Inspektera svaret för det kränkande fältet.
429
Prisgränsen har överskridits. Backa innan du försöker igen.
529
Tjänsten tillfälligt överbelastad. Backa innan du försöker igen.
För 429 och 529, använd exponentiell backoff istället för omedelbart försök igen. De officiella SDK:erna gör detta automatiskt under deras standardförsökspolicy.
Alternativ: Vercel AI Gateway
Den här webbplatsen dokumenterar också Gateway som ett åtkomstlager för AI SDK-utvärdering. Det är en alternativ integrationsväg, inte en del av Jev eller 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,
});
Efter detta kapitel:Du kan behålla inloggningsuppgifter på serversidan och få maskinskrivna svar med sannolikheter.
Förvandla inte den högsta sannolikheten direkt till en slutlig handling. Sätt band för förslag, bekräftelse och mänsklig granskning baserat på affärsrisk.
PROBABILITY
Bevis för varje alternativ eller nivå
Val och poäng returnerar hela distributionen. Använd den när tvåan alternativ, oklarheter eller anpassade osäkerhetsmått är viktiga.
CONFIDENCE
En sammanfattning av fördelningsformen
Förtroende komprimerar hur koncentrerad eller platt fördelningen är till 0–1. Det är inte detsamma som det valda alternativets sannolikhet.
Noul: Noul returnerar redan P(true), så det har inget separat förtroende. Värden nära 0,5 är osäkra; tröskel både ja- och nej-sidan efter risk.
TypeSafe avslöjar förtroende från optiondistributionen. En praktisk policy är:
01
Högt självförtroende
Föreslå automatiskt valet (tagg, rutt eller dom) i ditt användargränssnitt.
02
Medellång självförtroende
Visa förslaget, men begär att en operatör bekräftar det innan du fortsätter.
03
Lågt självförtroende
Skicka till en mänsklig kö utan standardåtgärd.
Kalibrera cutoffs på märkta exempel från din stream eller inkorg. Tröskelvärdena är specifika för användningsfall. Överför aldrig förslag till pengar eller återbetalningsbiverkningar.
Tröskel handlingen, inte modellen globalt
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
Kalibrera före automatisering
Samla representativa, märkta exempel från det verkliga arbetsflödet.
Spela in svar, distributioner, förtroende, latens och det mänskliga beslutet.
Välj trösklar separat för reversibla, kostsamma och oåterkalleliga åtgärder.
Övervaka drift och omvärdera efter att ha ändrat tillstånd, instruktioner, kriterier eller modellalias.
Statliga tips
Skicka en sträng, ett objekt eller en array som tillstånd. Föredrar strukturerade poster (kommentartext + metadata) framför att dumpa en hel chattlogg när bara ett meddelande spelar roll.
Efter detta kapitel:Du kan designa en reserv med låg förtroende och kalibrera trösklar med märkta data.
Behåll autentiseringsuppgifter och modellanrop på serversidan.
Validera tillståndsstorlek, obligatoriska fält och frågedefinitioner innan du anropar API:et.
Lagra modellversionen, frågeversionen, sannolikheter, förtroende och slutlig åtgärd.
Ge en explicit annan/mänsklig väg och uppfinn aldrig en standard på osäkerhet.
Försök igen 429 och 529 med begränsad exponentiell backoff; försök inte igen valideringsfel.
Testa mot märkta kantfall och kalibrera om tröskelvärden innan du aktiverar automatisering.
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.