TYPESAFE AI: Jev Decision Models
TYPESAFE AI builds models for focused judgments that software can consume as typed values. Its flagship, Jev, evaluates supplied information against explicit questions and returns choices, scores, or yes/no probabilities. Your application combines those answers with its own rules to route, rank, or flag work for review.
AvalAI provides access through /v1/decisions with the OpenAI decision schema and /v1/systemone with the native TYPESAFE AI schema. Both routes returned successful responses for both Jev aliases in live tests of the core typed-text examples on October 23, 2026. Use your AvalAI API key and https://api.avalai.ir; a separate TYPESAFE AI key is not needed for these AvalAI requests. Choose the endpoint before copying an example, because the request and response structures differ.
Available Models
These are the AvalAI alias mappings as of October 23, 2026. Send the alias in the model field:
| AvalAI model alias | Underlying version | AvalAI endpoints | Intended use |
|---|---|---|---|
jev-preview | jev-1.13.0 | /v1/decisions, /v1/systemone | Typed judgments over text and structured text data |
jev-latest | jev-1.14.0 | /v1/decisions, /v1/systemone | Typed judgments using AvalAI's newer Jev version |
AvalAI mappings are specific to AvalAI. The upstream provider may assign its aliases differently. The underlying versions identify the models behind the aliases; this table does not establish that those version strings are accepted as direct AvalAI request IDs. Use the two documented aliases for this release.
An alias can move to a different version without a client-code change. Keep the selected alias, question definitions, rubric, decision thresholds, and available response model metadata in your evaluation records. Re-run representative tests before changing an alias or relying on an updated mapping. See the workflow evaluation cookbook for a practical comparison process.
The Model Explorer and generated pricing tables can lag a newly enabled route. This provider page records the announced Jev aliases; use the endpoint-specific examples below to check your account's live behavior.
Pricing
Both aliases use the same AvalAI rates. Prices are in USD per 1 million tokens:
| Model | Input | Cached input | Output |
|---|---|---|---|
jev-preview | $0.042 | $0.00 | $0.00 |
jev-latest | $0.042 | $0.00 | $0.00 |
Zero output pricing means the returned decision values have no output-token charge; it does not make the request free. For example, 100,000 uncached billable input tokens cost $0.0042, and 1 million cost $0.042 at these rates. Count the actual input reported for the request, including the data and question material that the service bills, rather than estimating from character count.
The cached-input rate applies to input actually accounted for as cached. A zero cached-input price does not promise a cache hit, define a cache lifetime, or establish support for an OpenAI or native cache-control parameter. See Pricing, Response Headers, and the User API for billing and request reconciliation.
What a Decision Model Does
A decision workflow has three parts:
- Evidence: the text or structured text data to evaluate, such as a support message, a product description, or an extracted document section.
- Questions: narrow judgments with explicit options, conditions, or ordered rubric levels.
- Application policy: code that validates the results and decides what to do with them.
For example, a support application can ask which department owns a ticket, whether the customer requested a refund, and how urgent the message sounds. Its code can then select a queue and mark the ticket for review. Detecting a refund request does not authorize issuing a refund; that action still depends on the application's account checks, business policy, and approval process.
Jev is designed for these bounded judgments, rather than open-ended answer generation or extended multi-step reasoning. If a task asks the model to investigate, retrieve missing information, write a long explanation, or plan a sequence of actions, use an appropriate text or reasoning model for that part. A useful combined workflow has a text model prepare or retrieve relevant evidence, Jev evaluate specific dimensions, and application code apply the final rules.
Native Decision Primitives
The native System One API names the evidence state and the judgments questions. Each question has an ID, a type, and instructions; criteria defines the available choices or score levels where required. The response associates each typed answer with the question ID. See the System One API reference for the exact request and response schema.
| Primitive | Use it for | How to interpret the native answer |
|---|---|---|
Choice (choice) | Selecting one option from an unordered set, such as billing, technical, or other | choice identifies the selected option. probabilities describes the options, and confidence summarizes the distribution. |
Score (score) | Measuring a position on ordered, described levels, such as ticket severity | score can fall between levels. legend identifies the levels; probabilities and confidence help interpret the result. |
Noul (noul) | Evaluating a clearly defined yes/no condition, such as whether a message explicitly requests cancellation | noul is a value from 0 to 1 representing the model's probability of yes. It has no separate confidence field. |
Use Choice when labels have no meaningful order. Use Score when you can define what every level means. Use Noul when the condition itself is binary. A Noul value near 0.5 means uncertainty about yes versus no; it does not mean a medium amount of urgency, quality, or skill. Use a Score for those spectra.
Native question IDs are identifiers for your code, not a replacement for the question's instructions. Write the full judgment in instructions, even if the ID seems descriptive. Include other or a suitable unknown option when a Choice list does not cover every plausible input.
Choosing an AvalAI Endpoint
| Endpoint | Purpose and verification scope | Implementation reference |
|---|---|---|
/v1/decisions | OpenAI decision schema; the documented Choice, Predicate, and Score text payloads returned HTTP 200 for both aliases | Decisions API |
/v1/systemone | Native TYPESAFE AI state, questions, and typed primitive answers; the documented Choice, Noul, and Score text payloads returned HTTP 200 for both aliases | System One API |
The model's purpose is similar across the two routes, but schema compatibility is an endpoint contract. Do not send native state and questions to the Decisions route or assume the two response envelopes are interchangeable. These Jev endpoints also do not establish Chat Completions, Messages, Responses, streaming, tools, multimodal input, or stored-conversation support.
On October 23, 2026, all 16 synthetic live checks returned HTTP 200 with valid typed answers. The checks covered both aliases, both endpoints, core question types, and the cookbook's support, retrieval, guardrail, weighted-score, and function-selection payloads. This verifies those text request bodies and response shapes; it does not establish image support, context-boundary behavior, or execution of every SDK language example. The endpoint references include captured responses and explain the verified scope.
For the first request, follow the decision-model guide, then run the endpoint's small synthetic example against api.avalai.ir. Check the complete response before adapting its field access. The Jev cookbook develops this into a practical workflow with validation, review paths, and error handling.
Probabilities, Confidence, and Review
For native Choice and Score answers, TYPESAFE AI computes confidence from the shape of the returned probability distribution. A concentrated distribution produces higher confidence; an even or widely spread distribution produces lower confidence. The formulas differ between Choice and Score because Score levels are ordered.
Confidence is not a measured probability that an answer is correct. A confident answer can still be wrong, especially when evidence is missing, the question is ambiguous, or the input differs from the data used to evaluate your workflow. Treat probability and confidence as model signals, then check whether they predict useful outcomes on your own labeled examples.
Check the AvalAI response before assuming a complete probability map. The captured native support Choice responses omitted the selected label billing from probabilities while returning confidence: 1.0; other tested native Choice cases included their selected labels. Do not infer that an absent option has zero probability or recompute confidence from a partial map. See the captured native response and validation guidance before choosing which fields your application depends on.
Choose thresholds per question and action. Use representative correct, incorrect, ambiguous, and out-of-scope inputs to measure false positives, false negatives, and the share sent for review. Do not copy a threshold from a different task simply because both values use a 0-to-1 scale. For Noul, define a yes range, a no range, and a middle range that requests more information or human review.
Keep consequential actions behind application authorization and validation. Confidence may help decide which ticket to show a reviewer first; it does not replace a refund policy, payment confirmation, permission check, or verification of a factual claim.
Implementation Best Practices
- Ask one judgment per question. Separate urgency, category, and policy eligibility. Combine the answers with explicit code instead of asking one question to balance all three.
- Define observable criteria. “Does the supplied message explicitly ask for a refund?” is easier to assess than “Is the customer unhappy?” A Score needs concrete descriptions for every level.
- Provide relevant evidence. Preserve record IDs and field boundaries in structured data. Identify the field a question concerns, and do not ask the model to infer facts that are absent.
- Group independent questions over the same evidence. Native System One evaluates them against the same
state. When a later question needs an earlier answer to fetch new evidence or build its options, make the dependency explicit in a subsequent request. - Validate typed results in application code. Check answer IDs, allowed labels, expected numeric ranges, and finite numeric values. A structured result reduces prose parsing; it does not remove schema or policy validation.
- Evaluate English and Persian separately. TYPESAFE AI describes English as Jev's primary training language. Test real Persian wording, mixed-script identifiers, ambiguity, and domain vocabulary before selecting review thresholds.
- Keep a review and fallback path. Missing evidence, unknown labels, low confidence, or an invalid response should have an intentional outcome rather than silently selecting a default action.
Text and Context Limits
TYPESAFE AI documents text input for Jev 1.13 and 1.14, including strings, JSON objects, and arrays containing text. Convert audio, video, or scanned-document content into appropriate text evidence using a separate service before asking Jev to evaluate it.
The upstream default limits are 64k tokens per request (state plus all questions) and 32k tokens per question (state plus one question). These are two constraints, not two capacities to add together. Upstream also describes an opt-in long-context header, but its forwarding and behavior through AvalAI have not been established by this announcement. Do not rely on that header or a larger limit without a separate compatibility check. Keep requests small and relevant, and handle context errors through the debugging guide.
Practical Use Cases
| Workflow | Focused questions | What application code does next |
|---|---|---|
| Support triage | Department, urgency, explicit refund request | Routes the ticket and highlights cases that need a person |
| Product feedback | Feature category, actionable detail, severity | Groups records while preserving source IDs for review |
| Document classification | Document type, presence of a required section | Selects a processing path or requests missing information |
| Search and retrieval | Whether each candidate answers a defined need | Ranks candidates for a later grounded answer |
| Agent routing | Which permitted tool or workflow matches the request | Checks permissions and invokes an allowed path |
| Content review | Whether supplied content matches a clearly stated criterion | Flags material for review without treating the flag as proof |
These are implementation patterns, not guarantees of accuracy. Start with a labeled sample from the intended workflow, compare against existing rules or models, and retain examples of the failures your review path must catch.
Errors and Debugging
Begin with the endpoint-specific references and decision-model guide for request fields and error handling. Common first checks are the selected endpoint, alias, JSON shape, question type, criteria shape, and evidence size.
For the OpenAI-schema Decisions route, define named alternatives in choices, not options. For native System One, use the documented criteria shape for the selected primitive. Similar concepts do not make the two request schemas interchangeable.
Keep your key server-side in AVALAI_API_KEY. Record the HTTP status, endpoint, selected alias, latency, retry count, and returned avalai-request-id when present. Preserve a sanitized error body so you can distinguish authentication, permission, schema, context, rate-limit, and service failures. Avoid recording the key or unnecessary raw evidence.
Correct invalid requests before retrying them. For transient rate-limit or service failures, use bounded retries with backoff and respect Retry-After when supplied; see Error Handling. A timeout does not prove the service never processed the request, so avoid unbounded retries and keep the decision request separate from any downstream action.
Related Documentation
- Decision-model concepts, best practices, and debugging
- Decisions API reference
- Native System One API reference
- Decision workflows with Jev cookbook
- Workflow evaluation before model changes
Official TYPESAFE AI Sources
The following sources describe upstream concepts and behavior. AvalAI alias mappings, prices, and enabled endpoints above describe AvalAI's announced integration.