Decision primitives

Shared state, independent questions

The native state field is required; its value may be a string, JSON object, array, or null. An array is one shared state, not a batch of unrelated requests. Each named question evaluates that state. Make separate calls for independent states.

Instructions may be omitted or null; supplied descriptions accept strings, objects and arrays as well. Noul criteria may be omitted or null, or describe true and false. These native forms match official @typesafe-ai/sdk@0.6.0 declarations and are forwarded for the provider to accept or reject. State itself must not be omitted. Send ordinary JSON; questions and choices need non-blank names of at most 128 characters.

The factories below use the project @system-one-ai/sdk@0.3.0, which requires non-null state and explicit instructions and does not accept null Noul criteria. Use the official-client example or native HTTP for the broader nullable forms. Do not silently replace null with an empty string.

Choice

import { choice } from '@system-one-ai/sdk';

const team = choice('Select a team.', {
  billing: 'Payments and invoices',
  support: 'Technical help',
  review: 'Needs human review',
});

A native TypeSafe choice answer requires type, choice, the original probabilities map and provider confidence. The selected option must be one of your declared keys, and the distribution must contain exactly those keys. There must be 1–255 options. For the request above, a complete illustrative answer is:

{
  "type": "choice",
  "choice": "review",
  "probabilities": { "billing": 0.1, "support": 0.2, "review": 0.7 },
  "confidence": 0.5
}

A confidence statistic is not necessarily the probability of the selected option. Neither value is a universal action threshold. Missing required native statistics produce an invalid-response error, not an invented distribution. OpenRouter-adapted and legacy cached results have separate compatibility behavior; inspect the response mode.

Score

import { score } from '@system-one-ai/sdk';

const quality = score('Evaluate this answer using the rubric.', [
  'Does not address the question',
  'Partially addresses the question',
  'Fully addresses the question',
]);

Rubric positions are numbered from 0 to levels - 1. There must be 2–10 ordered levels. A native TypeSafe score answer requires type, score, probabilities, confidence and legend; the probabilities and legend maps use rubric indices as keys. A score can be fractional and represents the weighted rubric result:

score = sum(levelIndex * probabilityAtThatLevel)

For example, an illustrative distribution of [0.1, 0.3, 0.6] over three levels has a weighted score of 1.5. This arithmetic example is not a recorded model response. Reordering the rubric changes its meaning and changes the canonical request used for billing and idempotency.

{
  "type": "score",
  "score": 1.5,
  "probabilities": { "0": 0.1, "1": 0.3, "2": 0.6 },
  "confidence": 0.3,
  "legend": { "0": "Does not address the question", "1": "Partially addresses the question", "2": "Fully addresses the question" }
}

Boolean / Noul

import { booleanQuestion } from '@system-one-ai/sdk';

const duplicate = booleanQuestion('Does this report a duplicate charge?', {
  true: 'The same order was charged more than once',
  false: 'No duplicate charge is reported',
});

The number is P(true), bounded from 0 to 1. It is never automatically converted into true or false. Your application chooses a threshold, review policy, or abstention behavior appropriate to its task.

Validation and application policy

The gateway observes native answer types, option keys, required statistics, probability bounds and sums, and rubric ranges/weighted scores. It uses declared rounding or Jev's two-decimal display tolerance without inserting a rounding field or changing numbers. Valid TypeSafe JSON and extensions are returned unchanged. Missing usage, token counts, warnings and rounding are not synthesized; null token counts stay unknown in the ledger. Invalid responses fail with 502 and trigger reservation refund rather than producing a default action; immediate refund failure is reported separately.

Project SDK 0.3.0 normalizes its own result and can add default rounding/warnings. Its result is not the raw gateway body. Platform charges and request IDs always come from response headers, even if the provider body contains fields named billing or request_id.

Probabilities describe predictions. They do not establish that a particular action is safe, correct, or authorized. You can include a review or think option, then implement review or a separate planning call in your application. System One does not run that workflow for you.

The request bounds in the API reference are this platform’s limits, not promises about every Jev release or provider.