Jev Examples & Tips
Practical examples, tips, and recommendations for building structured decision workflows with Jev.
Jev is a System One decision model. It evaluates a state against one or more typed questions and returns structured answers that your application can use directly.
Use Jev for focused decisions such as classification, routing, scoring, and yes-or-no checks. It is not a chat, code-generation, or general text-generation model.
For the endpoint, authentication, headers, and complete request schema, see the System One API reference.
Choose a question type
Choose the type whose result maps most directly to your application logic.
| Type | Use it when | Returns |
|---|---|---|
choice |
The answer must be one option from a fixed set | The selected option, probabilities, and confidence |
score |
The answer belongs on an ordered scale | A score, probabilities, a legend, and confidence |
noul |
You need the probability that a statement is true | A value from 0 to 1 |
Choice
Use choice for routing and classification. Describe each option clearly, and include an other or none_of_the_above option when your list may not cover every input.
{
"department": {
"type": "choice",
"instructions": "Which team should handle the customer message?",
"criteria": {
"billing": "Payments, invoices, refunds, or subscriptions",
"technical": "Bugs, outages, or integration problems",
"sales": "Pricing, upgrades, or new accounts",
"other": "The request does not fit another option"
}
}
}Score
Use score for an ordered spectrum. Write distinct descriptions for every level instead of relying on labels such as "low," "medium," and "high" alone.
{
"frustration": {
"type": "score",
"instructions": "How frustrated does the customer appear?",
"criteria": [
"Calm and matter-of-fact",
"Concerned or frustrated but civil",
"Very angry or threatening to leave"
]
}
}Noul
Use noul for a precise yes-or-no judgment. The returned noul value is the probability that the statement is true: values near 1 indicate yes, values near 0 indicate no, and values near 0.5 indicate uncertainty.
{
"is_urgent": {
"type": "noul",
"instructions": "Does the customer message express urgency or time sensitivity?",
"criteria": {
"true": "The message explicitly describes urgency or immediate impact",
"false": "The message does not indicate urgency"
}
}
}Complete example
Ask independent questions about the same state in one request. Jev evaluates them in parallel, and each answer is returned under the question ID you supplied.
curl -X POST 'https://enterprise.blackbox.ai/typesafe/v1/systemone' \
-H "Authorization: Bearer ${BLACKBOX_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"state": {
"customer_message": "Our payment integration has returned errors for 20 minutes, and we cannot process orders. Please help immediately.",
"account": {
"plan": "enterprise"
}
},
"model": "jev-latest",
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle `customer_message`?",
"criteria": {
"billing": "Payments, invoices, refunds, or subscriptions",
"technical": "Bugs, outages, or integration problems",
"sales": "Pricing, upgrades, or new accounts",
"other": "The request does not fit another option"
}
},
"frustration": {
"type": "score",
"instructions": "How frustrated does the customer appear in `customer_message`?",
"criteria": [
"Calm and matter-of-fact",
"Concerned or frustrated but civil",
"Very angry or threatening to leave"
]
},
"is_urgent": {
"type": "noul",
"instructions": "Does `customer_message` express urgency or immediate business impact?",
"criteria": {
"true": "The message describes urgency or immediate business impact",
"false": "The message does not require immediate action"
}
}
}
}'import os
import requests
response = requests.post(
"https://enterprise.blackbox.ai/typesafe/v1/systemone",
headers={
"Authorization": f"Bearer {os.environ['BLACKBOX_API_KEY']}",
"Content-Type": "application/json",
},
json={
"state": {
"customer_message": "Our payment integration has returned errors for 20 minutes, and we cannot process orders. Please help immediately.",
"account": {"plan": "enterprise"},
},
"model": "jev-latest",
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle `customer_message`?",
"criteria": {
"billing": "Payments, invoices, refunds, or subscriptions",
"technical": "Bugs, outages, or integration problems",
"sales": "Pricing, upgrades, or new accounts",
"other": "The request does not fit another option",
},
},
"frustration": {
"type": "score",
"instructions": "How frustrated does the customer appear in `customer_message`?",
"criteria": [
"Calm and matter-of-fact",
"Concerned or frustrated but civil",
"Very angry or threatening to leave",
],
},
"is_urgent": {
"type": "noul",
"instructions": "Does `customer_message` express urgency or immediate business impact?",
"criteria": {
"true": "The message describes urgency or immediate business impact",
"false": "The message does not require immediate action",
},
},
},
},
timeout=30,
)
response.raise_for_status()
print(response.json())const response = await fetch(
"https://enterprise.blackbox.ai/typesafe/v1/systemone",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BLACKBOX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
state: {
customer_message:
"Our payment integration has returned errors for 20 minutes, and we cannot process orders. Please help immediately.",
account: { plan: "enterprise" },
},
model: "jev-latest",
questions: {
department: {
type: "choice",
instructions: "Which team should handle `customer_message`?",
criteria: {
billing: "Payments, invoices, refunds, or subscriptions",
technical: "Bugs, outages, or integration problems",
sales: "Pricing, upgrades, or new accounts",
other: "The request does not fit another option",
},
},
frustration: {
type: "score",
instructions:
"How frustrated does the customer appear in `customer_message`?",
criteria: [
"Calm and matter-of-fact",
"Concerned or frustrated but civil",
"Very angry or threatening to leave",
],
},
is_urgent: {
type: "noul",
instructions:
"Does `customer_message` express urgency or immediate business impact?",
criteria: {
true: "The message describes urgency or immediate business impact",
false: "The message does not require immediate action",
},
},
},
}),
},
);
if (!response.ok) {
throw new Error(`System One request failed: ${response.status}`);
}
console.log(await response.json());An example response has one typed answer for each question:
{
"model": "jev-1.13.0",
"answers": {
"department": {
"type": "choice",
"choice": "technical",
"probabilities": {
"billing": 0.08,
"technical": 0.88,
"sales": 0.01,
"other": 0.03
},
"confidence": 0.84
},
"frustration": {
"type": "score",
"score": 1.1,
"legend": {
"0": "Calm and matter-of-fact",
"1": "Concerned or frustrated but civil",
"2": "Very angry or threatening to leave"
},
"probabilities": {
"0": 0.02,
"1": 0.86,
"2": 0.12
},
"confidence": 0.79
},
"is_urgent": {
"type": "noul",
"noul": 0.97
}
},
"usage": {
"input_tokens": 418,
"output_tokens": 72
}
}Response values above are illustrative. Validate behavior and thresholds using examples from your own application.
Recommendations
Ask atomic questions
Each question should ask for one focused judgment that a knowledgeable person could make quickly from the supplied state.
Avoid a broad question such as:
Analyze this support request and decide what we should do.Instead, ask separate questions about the request type, urgency, frustration, policy eligibility, or risk. Combine those answers with application logic.
Keep code in control
Use Jev where semantic judgment is necessary. Keep deterministic work, arithmetic, database operations, side effects, and control flow in code.
const topic = result.answers.department;
const urgent = result.answers.is_urgent.noul >= 0.8;
if (topic.confidence < 0.7) {
await sendToHumanReview(ticket);
} else {
await routeToTeam(topic.choice, { urgent });
}Send only relevant state
Large amounts of unrelated context can reduce accuracy. Filter records first and send only the text and structured fields required to answer the questions.
Prefer descriptive JSON fields over one long string when the decision depends on several related values:
{
"state": {
"ticket_message": "I was charged twice for order A-104.",
"charges": [
{ "order_id": "A-104", "amount": 49, "status": "captured" },
{ "order_id": "A-104", "amount": 49, "status": "captured" }
],
"refund_policy": "Duplicate captured charges are eligible for a refund."
}
}Reference the relevant paths explicitly in the question, such as ticket_message, charges, and refund_policy.
Batch independent questions
Questions that use the same state are evaluated independently and in parallel. Put them in one request instead of making one request per question. Use another request only when a later question genuinely depends on an earlier answer or on data fetched because of that answer.
Write explicit criteria
Define what every Choice option or Score level means. Add examples and boundary conditions when categories overlap. Keep instructions and criteria consistent, and avoid double negatives or implied rules.
Route uncertainty
Do not treat every result as equally certain. Use Choice and Score confidence, or the distance of a Noul value from 0.5, to decide whether to act automatically, request confirmation, or escalate.
Start with conservative thresholds, evaluate them against representative data, and use stricter thresholds for actions that are expensive, destructive, or difficult to reverse.
Pin a model for stable behavior
jev-latest follows the latest stable Jev release. If your application is calibrated against specific answers or confidence thresholds, use a supported versioned model ID and evaluate a newer version before switching.
What to avoid
| Avoid | Recommended approach |
|---|---|
| Asking Jev to generate prose, code, or chat responses | Use a generative model and use Jev for bounded decisions |
| Asking one question that contains several judgments | Split it into atomic questions and combine answers in code |
| Using Jev for counting, arithmetic, or exact comparisons | Calculate deterministic values in code |
| Asking Jev to compare or calculate dates | Extract relevant date parts, then compare them in code |
| Sending an entire document store or application state | Retrieve and filter relevant context first |
| Using vague or contradictory criteria | Define explicit, mutually understandable options and boundaries |
| Assuming the first Choice result is always reliable | Test representative inputs and verify that option ordering does not change results |
| Automatically acting on uncertain answers | Add confidence thresholds and a review or fallback path |
Treat untrusted content in state as potentially adversarial. Use precise questions and criteria, test prompt-injection-style inputs, and keep sensitive side effects behind deterministic checks.
Common use cases
Jev works well as a decision layer for:
- Intent classification and request routing
- Support ticket triage
- Content moderation and application guardrails
- Document and retrieval-result scoring
- Policy or citation checks
- Risk, urgency, quality, and relevance assessment
- Selecting among predefined tools or handlers