System 1 Decisions
Typed decisions in one forward pass. Send a state and a map of named questions -- choice, score, noul -- and get one answer per question with its probabilities. POST /v1/systemone is TypeSafe's Jev API, served by open Laya-format models on Erebine Inference Microservices (EIMs) that run the Laya engine. The TypeSafe SDK works once base_url and model point here.
- route
POST /v1/systemone- protocol
- TypeSafe Jev
- task mode
systemone- billed
- input tokens
Overview
A System 1 model answers typed questions about a state and never
generates text. The state is a string, a JSON object, or a JSON array: a
support ticket, a record, a conversation, the current state of your
application. You name each question; its answer comes back under the same
name, with a probability for every option and, for choice and
score, a confidence between 0 and 1.
| Type | Asks | Answers with |
|---|---|---|
choice |
Pick one option from a set you define. | The chosen option, a probability per option, a confidence. |
score |
Rate the state against ordered levels. | The probability-weighted level (it can land between levels), a probability per level, a legend, a confidence. |
noul |
A yes/no question. | The probability that the answer is yes. |
Extension outside the OpenAI specification.
/v1/systemone reimplements TypeSafe's Jev API the way
/v1/rerank follows Cohere's. The OpenAI SDKs have no method
for it. Call it with the TypeSafe SDK, any Jev
client, or plain HTTP.
It is served by endpoints whose task_mode is
systemone, backed by a Laya-format model on an EIM running
the Laya engine. See Deploying a Model.
Endpoint
POST /:project_id/:endpoint_slug/v1/systemone
The endpoint-scoped route answers with the model its endpoint serves. The direct dispatch twin takes the model from the body instead of the path:
POST /:project_id/:workspace_id/_direct/v1/systemone
curl -X POST https://api.erebine.ai/proj_ABC123/my-decisions/v1/systemone \
-H "Authorization: Bearer ere_myproject_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"model": "laya-bundle",
"state": "Help! My payouts have been failing for 3 days.",
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this?",
"criteria": {
"billing": "Payments, invoicing, refunds",
"technical": "Bugs, outages, integrations",
"sales": "Pricing, upgrades, new accounts"
}
},
"frustration": {
"type": "score",
"instructions": "How frustrated is the customer?",
"criteria": ["Calm", "Frustrated", "Very angry"]
},
"is_urgent": {
"type": "noul",
"instructions": "Does this convey urgency?",
"criteria": {
"true": "Explicitly time-sensitive",
"false": "No urgency expressed"
}
}
}
}'
Request
The body is forwarded to the model byte for byte: key order, number text, and escapes reach it exactly as you sent them, so question ids and option names in any language and any escape form come back unchanged. Top-level fields not listed here are ignored.
| Parameter | Type | Description |
|---|---|---|
| modelrequired | string | On the endpoint route, the model the endpoint serves, by name or id as GET /v1/models publishes them; surrounding whitespace and letter case are ignored. On _direct, the namespaced id of a System 1 deployment. Any other value, TypeSafe's jev-latest included, answers 404 model_not_found (see Errors and Retries). The response echoes the value you sent; it names a deployment and never selects a checkpoint inside one. |
| staterequired | string | object | array | What the questions are about. Not null. An array is read as a conversation. |
| questionsrequired | object | A map of question id to question. Up to 64 entries. An empty object is accepted, answers with an empty answers, and costs nothing. |
| max_lenoptional | integer | Extension. Tokens per question row, state included, from 1 to the deployment's context length. See Long Documents. |
| head_max_lenoptional | integer | Extension. Tokens per row reserved for the question and its options, from 1 to the deployment's context length. Each checkpoint sets its own default: 192 for Laya's English checkpoint, 256 for the multilingual one. |
Question Types
Every question carries type and instructions.
instructions is a string, an object, or an array: put the
question in one field and the data it refers to in others, and name those
fields in backticks.
"instructions": {
"potential_duplicate": {
"name": "John Smith",
"location": "Oakland, California",
"last_employer": "Google"
},
"question": "Is the resume for the same person as `potential_duplicate`?"
}
choice
criteria is required: an object of option to description, where
a description is a string, an object, an array, or null. From 1
to 100 options (Jev allows 255). A list of unique, non-empty option names is
accepted as well; the TypeSafe SDK always sends the object form.
"department": {
"type": "choice",
"instructions": "Which team should handle this?",
"criteria": {
"billing": "Payments, invoicing, refunds",
"technical": "Bugs, outages, integrations",
"sales": null
}
}
score
criteria is required: an ordered array of 2 to 10 level
descriptions, none of them null. Level 0 is the first.
"frustration": {
"type": "score",
"instructions": "How frustrated is the customer?",
"criteria": ["Calm", "Frustrated", "Very angry"]
}
noul
criteria is optional: an object with only the keys
true and false, describing what a yes and a no
mean. labels is an optional extension passed to the model
unchanged.
"is_urgent": {
"type": "noul",
"instructions": "Does this convey urgency?",
"criteria": {
"true": "Explicitly time-sensitive",
"false": "No urgency expressed"
}
}
Response
Response
{
"model": "laya-bundle",
"answers": {
"department": {
"type": "choice",
"choice": "billing",
"probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
"confidence": 0.81
},
"frustration": {
"type": "score",
"score": 1.05,
"legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
"probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
"confidence": 0.92
},
"is_urgent": {
"type": "noul",
"noul": 0.95
}
},
"usage": { "input_tokens": 142, "output_tokens": 0 }
}
| Field | Type | Description |
|---|---|---|
| model | string | The model value you sent. |
| answers | object | One answer per question, keyed by your question ids, each with a type matching its question. |
| answers.<id>.choice | string | choice answers: the most probable option, spelled as in criteria. |
| answers.<id>.score | number | score answers: the probability-weighted level, from 0 to the last level; legend maps each level number back to its description. |
| answers.<id>.probabilities | object | choice and score answers: every option or level mapped to its probability; they sum to 1. |
| answers.<id>.confidence | number | choice and score answers: how certain the model is, from 0 to 1, derived from the probabilities. |
| answers.<id>.noul | number | noul answers: the probability of yes, from 0 to 1. |
| usage.input_tokens | integer | Tokens the model read. This is the billed quantity; see Billing. |
| usage.output_tokens | integer | Reported by the model. Not billed. |
Laya-format models add fields Jev does not define: answer_confidence
and action on answers, confidence on
noul answers, and options in
usage. They are additive; the TypeSafe SDK ignores them, and so
can you. Nothing streams.
Limits
| Limit | Value | Over the limit |
|---|---|---|
| Request body | 2 MiB (2,097,152 bytes) of valid JSON, no duplicate key in any object, no escaped lone surrogate such as \ud800, nested at most 64 levels deep |
422 |
| Questions per request | 64 | 422, param: "questions" |
Options per choice |
1 to 100 (Jev allows 255) | 422, param: "questions.<id>.criteria" |
Levels per score |
2 to 10 | 422, param: "questions.<id>.criteria" |
| Options across all questions | 512 choice options and score levels in total | 422, param: "questions" |
state |
50,000 Unicode scalars for a string; 50,000 Unicode scalars of compact JSON for an object or array | 422, param: "state" |
max_len, head_max_len |
An integer from 1 to the deployment's context length | 422, param names the field |
| Context length | 512 to 8,192 tokens per question row, set per model | Input past it is truncated; see Long Documents |
| Request size on a CPU deployment | 24,576 estimated input tokens by default; the EIM's operator can change it, and can set one on a GPU deployment too | 422, request too large for this deployment: about <n> tokens, limit <m> |
The model applies its own count to an object or array state, which reads longer than compact JSON. A structured state close to 50,000 scalars can pass the router and still be refused by the model with 422.
Long Documents
Each question is read as its own row: the state, then the question and its
options. A row holds at most the deployment's context length in tokens: the
model's context_length, or the window its engine started with
when that is smaller (served_context_length, see
Model Management). Upload
records context_length from the checkpoint: 512 for Laya's
English checkpoint, and 1,024 for the multilingual one and for the bundle,
which takes its multilingual checkpoint's. A System 1 model takes 512 to
8,192. Raise it on the model page, with PATCH /v1/models/{id}
{"context_length": 8192}, or with
erectl models update <id> --context-length 8192. Through
the API the change needs a key with the management scope, and
saving it restarts the engine on every endpoint serving the model (see
Update Model Metadata).
- Truncation. Input past the row's limit is cut. An array state (a conversation) loses its earliest items first; any other state loses its end.
usage.input_tokensshows what was read. - Per request.
max_lenasks for a shorter or longer row, up to the context length. When you omit it, the checkpoint that answers reads its full row: the deployment's context length, or 512 on the bundle's English checkpoint. - Bundles. A deployment of the Laya bundle loads its English and multilingual checkpoints. English text goes to the English checkpoint, whose own limit stays 512; a state that does not fit it, or a
max_lenabove it, is answered by the multilingual checkpoint instead. Non-English text goes to the multilingual checkpoint. - Single checkpoints. A deployment of one checkpoint, a fine-tune for example, answers every request with that checkpoint, in any language.
- Accuracy. Laya documents 8,192 tokens for its multilingual checkpoint. Accuracy on long English input is yours to measure on your data.
- Short inputs. A larger limit does not change answers for inputs that already fit, and speed follows the real input length.
Billing
A System 1 request is billed on usage.input_tokens at the
endpoint's per-token rate (see Usage and
Billing). Answers are not billed.
- The state is counted once per question. Every question is its own row carrying the state, so
input_tokensis the sum over questions of the state plus that question and its options, each row capped at the context length. Jev counts the state once, so the same multi-question request reports more input tokens here. Asking ten questions in one request still costs the same tokens as ten one-question requests, in one round trip. - Free outcomes. A busy engine or a model still loading (529 and 503, or 429 on
_direct), an invalid request (422), an engine error (500), a lost connection to the EIM or its engine (503), and every refusal before the router dispatches the request are not charged. They still appear in your request logs. - Timeouts and disconnects. The engine cannot stop a forward pass once it starts. A request that times out (408), or whose client disconnects after the router dispatched it, is charged at its estimate: the sum over questions of the state plus the question, estimated from character counts, each capped at the context length.
- A 408 the engine never ran. Some timeouts are charged at the estimate although the engine never started the request: one that waited at the EIM while the model loaded until its deadline passed, and one that reached the EIM after its deadline had already passed.
- CPU deployments. A CPU deployment refuses, with 422, a request estimated above its limit (24,576 tokens by default). The limit is sized so a request it accepts finishes inside the 240 seconds the EIM waits for an answer, instead of timing out and being charged; a shorter tier request timeout, such as Free's 30 seconds, still applies.
Before dispatch the router reserves credit for the estimate and settles it on the reported count, or releases it for a free outcome.
Errors and Retries
Errors use the standard error body. A
validation failure names the offending path in param:
{
"error": {
"message": "A choice question takes at most 100 options, got 101.",
"type": "invalid_request_error",
"param": "questions.department.criteria",
"code": "invalid_request"
}
}
A failure of the body as a whole -- over 2 MiB, not valid JSON, nested too
deep -- carries no param. The endpoint route checks the body before its
model, so an invalid body answers 422 whatever model it
names. The endpoint route answers:
| Status | Type or code | When |
|---|---|---|
| 400 | endpoint_task_mode_mismatch |
The endpoint's task mode is not systemone. |
| 401 | authentication_error |
Missing or invalid API key. |
| 402 | insufficient_quota |
A paid project's credit balance does not cover the request's estimate. Not charged. |
| 403 | access_denied |
The API key's IP filter refuses the client IP, or the path names a project that is not the key's own. |
| 403 | endpoint_restricted |
The key is restricted to another endpoint. |
| 404 | endpoint_not_found |
No endpoint with this slug in the project. |
| 404 | model_not_found |
The model in the body is not the model this endpoint serves, TypeSafe's jev-latest included. The body is the one the OpenAI API sends for a model you cannot use: the message names the value sent and param is null. |
| 408 | timeout |
No answer within the time limit: the endpoint tier's request timeout (30 seconds on Free; see Service Tiers), or 240 seconds once the engine has the request, whichever comes first. Charged at its estimate; see Billing. |
| 422 | invalid_request_error |
The body failed a rule under Limits, is not valid JSON, asks for max_len or head_max_len above the context length, exceeds the deployment's request size limit, or was refused by the model itself. |
| 429 | rate_limit_exceeded |
A request rate limit for this API key on this endpoint, or the key's own quota, was reached. Retry after Retry-After. |
| 429 | token_rate_limit_exceeded |
The project's tokens-per-minute budget is spent (see Rate Limits). Retry after Retry-After, 60 seconds. |
| 500 | internal_error |
The model failed while answering. Not charged. |
| 501 | backend_unavailable |
The router has no model storage configured: a fault in the deployment, not in the request. |
| 503 | model_provisioning |
The model is loading. Retry after Retry-After. |
| 503 | backend_unavailable |
No EIM the endpoint is bound to can take traffic, or the connection to the EIM or the EIM's engine failed mid-request. Not charged. |
| 503 | capacity_exceeded |
No EIM is available for the endpoint, or its EIM is unhealthy. Retry after Retry-After. |
| 503 | endpoint_inactive |
The endpoint is not active. It may be provisioning or disabled. |
| 504 | timeout |
The router found no EIM before its routing deadline. Retry after Retry-After. |
| 529 | overloaded_error, code capacity_exceeded |
The engine is busy or no EIM has room. Retry after Retry-After. |
On _direct the router admits the request first. A body with no
usable model, one that is not JSON included, is 400
invalid_request with param: "model"; a body over
2 MiB is 422; a project that is not the key's own is 403; and a
model that is not a System 1 deployment in this project -- the
TypeSafe SDK's default jev-latest included -- is 404
model_not_found. Load answers 429 with Retry-After:
capacity_exceeded for a busy engine, a model that is still
loading, or no EIM that can take the request, and
listing_concurrency_exceeded when the model already has its
published concurrency in flight. A routing timeout is 504
timeout. 503 means the service is unavailable, or the
connection to the EIM or its engine failed. A client IP the key's filter
refuses is 403 here too, and 402, 408, 422, and 500 mean what they mean on
the endpoint route. See Direct
Model Dispatch.
Retry 529, 429, and 503 with exponential backoff, honoring
Retry-After. Do not retry a 408 or a client timeout: a 408 is
charged at its estimate, and a retry runs the work again and is charged
again. The TypeSafe SDK's default policy retries 408, 429, every 5xx, and
its own timeouts; the example's
RetryPolicy drops 408 and timeouts.
TypeSafe SDK
The TypeSafe Python SDK calls base_url plus
/v1/systemone. Point it at the endpoint without
/v1, set model, and raise the timeout:
pip install typesafe-sdk
from typesafe_sdk import Choice, Noul, RetryPolicy, Score, TypeSafeClient
client = TypeSafeClient(
api_key="ere_myproject_your_api_key",
base_url="https://api.erebine.ai/proj_ABC123/my-decisions",
model="laya-bundle",
timeout=250.0,
retry=RetryPolicy(http_statuses={429, *range(500, 600)}, api_timeout_error=False),
)
response = client.system_one(
"Help! My payouts have been failing for 3 days.",
{
"department": Choice(
instructions="Which team should handle this?",
criteria={
"billing": "Payments, invoicing, refunds",
"technical": "Bugs, outages, integrations",
"sales": "Pricing, upgrades, new accounts",
},
),
"frustration": Score(
instructions="How frustrated is the customer?",
criteria=["Calm", "Frustrated", "Very angry"],
),
"is_urgent": Noul(instructions="Does this convey urgency?"),
},
)
print(response.choices["department"].choice)
print(response.scores["frustration"].score)
print(response.nouls["is_urgent"].noul)
The same settings from the environment:
export TYPESAFE_API_KEY=ere_myproject_your_api_key
export TYPESAFE_BASE_URL=https://api.erebine.ai/proj_ABC123/my-decisions
export TYPESAFE_DEFAULT_MODEL=laya-bundle
modelis required here. The SDK's default,jev-latest, names TypeSafe's model and does not exist on this router: it answers 404model_not_found.timeout=250.0. The SDK's default is 10 seconds. A long document on a CPU deployment takes longer than that, and a request the SDK abandons still runs on the engine and is charged at its estimate. 250 seconds sits above the 240 seconds the engine has once it has the request. A request that first waits for its model to load can take longer, up to the endpoint tier's request timeout; if your engines restart often, set the timeout above that.RetryPolicy(http_statuses={429, *range(500, 600)}, api_timeout_error=False). The SDK's default policy also retries a 408 and its own timeouts, and each such retry runs the request again and is charged again. This policy drops both and keeps the retries for 429 and every 5xx, which are not charged. It also keeps the SDK's retry of a connection error: a refused connection costs nothing, but a connection that drops after the router dispatched the request is charged at its estimate, and the retry is charged again. Addapi_connection_error=Falseto rule that out._direct. Usebase_url="https://api.erebine.ai/proj_ABC123/ws_abc123/_direct"and the namespaced model id, for examplemodel="erebine/laya-bundle".- Extensions. Pass
max_lenandhead_max_lenwithextra_body={"max_len": 4096}. client.models.list()is not supported. It expects TypeSafe's model list shape; this router's GET /v1/models answers in the OpenAI shape. List models with an OpenAI client or curl.
Code Examples
Substitute your project external id, endpoint slug, an API key from your project, and the model your endpoint serves.
Structured state (Python)
import httpx
BASE_URL = "https://api.erebine.ai/proj_ABC123/my-decisions/v1"
API_KEY = "ere_myproject_your_api_key"
response = httpx.post(
f"{BASE_URL}/systemone",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"model": "laya-bundle",
"state": {"ticket": "Help! My payouts have been failing for 3 days.", "plan": "pro"},
"questions": {
"is_urgent": {"type": "noul", "instructions": "Does this convey urgency?"},
},
},
timeout=250.0,
)
response.raise_for_status()
answer = response.json()["answers"]["is_urgent"]
print(f"P(urgent) = {answer['noul']:.2f}")
Conversation state (Node.js)
const BASE_URL = "https://api.erebine.ai/proj_ABC123/my-decisions/v1";
const API_KEY = "ere_myproject_your_api_key";
const response = await fetch(`${BASE_URL}/systemone`, {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "laya-bundle",
state: [
{ role: "customer", text: "My payouts have been failing for 3 days." },
{ role: "agent", text: "Sorry about that. Checking now." },
{ role: "customer", text: "This is the third time this month." },
],
questions: {
next_step: {
type: "choice",
instructions: "What should happen next?",
criteria: { resolve: null, escalate: "Hand to a senior agent", refund: null },
},
},
}),
signal: AbortSignal.timeout(250000),
});
if (!response.ok) {
const error = await response.json();
throw new Error(`systemone failed: ${error.error.message}`);
}
const data = await response.json();
console.log(data.answers.next_step.choice, data.answers.next_step.confidence);
Non-English text (curl)
Send text in any language raw or as JSON escapes; question ids may be non-ASCII too and come back exactly as sent.
curl -X POST https://api.erebine.ai/proj_ABC123/my-decisions/v1/systemone \
-H "Authorization: Bearer ere_myproject_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"model": "laya-bundle",
"state": "\u092e\u0947\u0930\u093e \u092d\u0941\u0917\u0924\u093e\u0928 \u0935\u093f\u092b\u0932 \u0939\u0948",
"questions": {
"is_urgent": { "type": "noul", "instructions": "Does this convey urgency?" }
}
}'
Batch
/v1/systemone is a Batch API
target. Each line's body reaches the model byte for byte and is
billed like a synchronous request; a line answered 529 is requeued, and a
line answered 422 fails. A System 1 engine computes one request at a time,
so run bulk jobs on their own endpoint with its own EIM.
Deploying a Model
- A model. Any Laya-format checkpoint: a directory holding
rl_agent_config.json,model.safetensors,tokenizer/, andencoder/config.json. Theconvaiinnovations/layabundle is the English checkpoint at the root plusmultilingual/, which is loaded, andtyped-decisions/, which is accepted but not loaded; upload that folder as its own model to serve it. Upload it like any model (Model Upload). Upload records the engine aslaya, thesystem_onecapability, and the context length. - An EIM running the Laya engine. The
eim-laya-cpu,eim-laya-cuda, oreim-laya-rocmimage (Laya Images), or the macOS app with Laya selected (Inference Engine). - An endpoint. Choose the System 1 decisions task mode in the dashboard, or send
task_mode: "systemone". Creating one needs an active EIM the endpoint's tier places on (on a self-hosted tier, one of your project's own) that runs the Laya engine, and binding a Laya model to an EIM running another engine is refused with 422. Quantization override, KV cache dtype, workload profile, and speculative decoding must be empty orauto; any other value is refused with 400. The model page and the model API refuse vLLM launch settings on a System 1 model: quantization, the parsers, speculative decoding, and the other vLLM-only settings.
Image Prompt Screening
Image generation on a shared endpoint screens every prompt on a System 1
endpoint in your own project before any image is made. Only a System 1
endpoint serving an approved screening model screens. A shared image
generation endpoint cannot be created without an active one in the project
(screening_endpoint_required), and the project's last active one
cannot be deleted, suspended or moved to another task mode while a shared
image generation endpoint uses it (screening_endpoint_in_use). Image generation on your own EIMs (a
self-hosted tier) is not screened and needs none.
- Approved models. The platform approves the System 1 models that may screen; when it offers exactly one System 1 model, that model is approved automatically. On the new-endpoint page, a System 1 model card that reads "Approved for image prompt screening" is one; deploy it as a System 1 endpoint. While no model is approved, shared image generation is unavailable.
- Which endpoint. The Prompt screening choice on the workspace's Image generation card, else the project's first active System 1 endpoint serving an approved screening model. The choice lists only those endpoints.
- Billing. Each screening is an ordinary System 1 request, billed on its input tokens and listed in your request logs. A prompt longer than the model reads in one row is screened in parts, one request each.
- What is read. The prompt only. Images sent to
/v1/images/edits, and reference images passed to the image tools, are not classified. - Refused. A prompt the screen refuses answers
400with typeimage_generation_user_errorand codemoderation_blocked, as the OpenAI Images API does. No image is made, and the image is not billed. - Fails closed. With no usable System 1 endpoint serving an approved screening model, or with none approved at all, the request answers
400screening_endpoint_required, and the message says which. When screening does not answer (no capacity, an engine error, an unreadable answer, or no answer within 15 seconds at most), it answers503screening_unavailable(429on direct dispatch); retry it. - Responses and chat. The
image_generationtool on /v1/responses reports the same codes as the failedimage_generation_callitem'serror. In chat, and for x_generate_image on every surface, the tool returns a plain result with no image and the assistant says why. The Images API lists the same codes.
Research Decisions
Optional. When a workspace has a System 1 endpoint for decisions, research turns in chat and on /v1/responses check their work on it at two points. With none, nothing changes.
- Before researching. At the start of a new conversation, a request that does not say what it is about may get one clarifying question before any search, where the surface can ask one.
- Before answering. When the sources found look thin, the turn runs one more round of searches for what is missing. When they look like they disagree, the answer states the disagreement and cites both sides. Each happens at most once a turn, and the chat shows a short line when it does.
- Mockups. When a chat turn finishes a mockup with no broken links or missing files, it may check the mockup against the request once: each page, section or feature your request names is looked for in the mockup, and one more round adds any that seem missing. When nothing is missing and your request does not name your business, it may ask you for the name instead of inventing one, where the surface can ask. The chat shows a short line when it does, such as "adding the pricing page".
- Which endpoint. The Decisions (System 1) choice on the workspace's Endpoints settings: Auto (the project's first active System 1 endpoint), a specific System 1 endpoint, or Off. Any System 1 endpoint works; it does not need to be approved for image screening.
- Billing. Each check is an ordinary System 1 request, billed on its input tokens and listed in your request logs. A turn makes at most two.
- Never blocks. A check that fails or does not answer in a few seconds is skipped, and the turn goes on as if it had not been asked.