System One Decision Models

Spring AI supports the System One protocol through the Decision Models API. A decision model picks one result from a known set of possible results, such as yes or no, one of a few categories, or a level on a scale, and tells you how likely each result is.

System One is the POST /v1/systemone protocol of the decision models of TypeSafe. Laya, llmman and Ollama serve it too, so one implementation works with all four. SystemOneDecisionModel is built on the SystemOneClient, the client of the protocol that ships in the spring-ai-systemone module.

Prerequisites

  1. A System One server, for example:

    • TypeSafe: create an account and an API key at typesafe.ai;

    • Ollama 0.35 or later, with a decision model such as d1-omni:600m. We recommend Ollama 0.40.4 or later;

    • Laya, with laya-serve;

    • llmman 0.1.497 or later, with llmman serve.

  2. The spring-ai-starter-model-systemone dependency, as described in Auto-configuration, or the spring-ai-systemone dependency for a manual configuration.

Auto-configuration

Spring AI provides Spring Boot auto-configuration for the System One decision model. To enable it, add the following dependency to your Maven pom.xml or Gradle build.gradle build files:

  • Maven

  • Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-systemone</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-systemone'
}
Refer to the Dependency Management section to add the Spring AI BOM to your build file.

The auto-configuration creates a SystemOneClient and a SystemOneDecisionModel over it. Both are regular beans: inject the client to call listModels(), and define your own bean of either type to replace the auto-configured one.

If your application doesn’t use the decision model, turn off its auto-configuration with spring.ai.model.decision=none, as described in Decision Properties.

Connection Properties

The prefix spring.ai.systemone is the property prefix to configure the connection to the System One server.

Property

Description

Default

spring.ai.systemone.api-key

The API key. Required for the auto-configured client, which is not created without it. Not needed when you define your own SystemOneClient bean, or a SystemOneDecisionModel bean over a client of its own.

-

spring.ai.systemone.base-url

The API root. Point it at Laya, llmman or another server of the protocol.

https://api.typesafe.ai

spring.ai.systemone.timeout

The read timeout of each attempt. Unset, the spring.http.clients.read-timeout of your application applies, or 10s when the client builds its own transport.

-

spring.ai.systemone.retry.max-retries

Retries after the initial attempt. 0 disables retrying.

2

spring.ai.systemone.retry.initial-backoff

The first wait, doubled on each further retry.

500ms

spring.ai.systemone.retry.max-backoff

The upper bound on a single wait.

5s

spring.ai.systemone.retry.timeout

No further attempt is started once this much time has passed since the first.

30s

The client sends its requests through the RestClient.Builder of your application when there is one, so your RestClientCustomizer beans and the spring.http.clients settings, such as the connect timeout, redirects and the SSL bundle, apply. When you set spring.ai.systemone.timeout, the request factory of the client is built again from the ClientHttpRequestFactoryBuilder and the spring.http.clients settings of your application, with that read timeout. This replaces a request factory that a RestClientCustomizer installed, so in that case leave the property unset and set the timeout on your own factory. Retries cover connection failures, request timeouts, rate limits and server errors, and wait as long as the server asks on a rate limit. The spring.ai.retry properties of the other models do not apply to this client.

Decision Properties

The spring.ai.model.decision property enables and disables the decision auto-configuration.

To enable it, set spring.ai.model.decision=systemone (this is the default).

To disable it, set spring.ai.model.decision=none, or any value other than systemone.

The prefix spring.ai.systemone.decision is the property prefix to configure the System One decision model.

Property

Description

Default

spring.ai.model.decision

Enables the System One decision model.

systemone

spring.ai.systemone.decision.model

The model name or alias. Unset, the default model of the SystemOneClient applies: jev-latest for the auto-configured client, or the defaultModel(…​) of a client bean you define. Ollama, Laya and llmman have no jev-latest, so set it when you point at one of them.

-

spring.ai.systemone.decision.provider

The provider name recorded in observations, such as laya or llmman.

systemone

When the Ollama or OpenAI starter is on the classpath too, each auto-configures its own decision model by default. Select one with spring.ai.model.decision, or qualify the injection point.
You can change the model for one call, with the Runtime Options of the DecisionPrompt.

Manual Configuration

Without the starter, configure the SystemOneDecisionModel yourself. Add the spring-ai-systemone dependency to your Maven pom.xml or Gradle build.gradle build files:

  • Maven

  • Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-systemone</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-systemone'
}
Refer to the Dependency Management section to add the Spring AI BOM to your build file.

The SystemOneClient holds the connection settings: the base URL, the API key, the default model, the timeout of the transport it builds and the retry policy. The model takes the client and, optionally, the default options and the provider name for observations.

SystemOneClient client = SystemOneClient.builder()
    .apiKey(System.getenv("SYSTEMONE_API_KEY"))
    .defaultModel("jev-latest")
    .timeout(Duration.ofSeconds(10))
    .build();

SystemOneDecisionModel decisionModel = SystemOneDecisionModel.builder(client).build();

DecisionResponse response = decisionModel.call("Where is my order? I ordered it two weeks ago.",
        Map.of("topic", ChoiceQuestion.of("What is the message about?",
                "delivery", "product", "account", "other")));

The API key is required. The base URL defaults to api.typesafe.ai, and the default model to jev-latest.

Builder method Description Default

options(SystemOneDecisionOptions)

The default options. When they set no model, the default model of the client is used.

the default model of the client

provider(String)

The provider name for observations, such as ollama, laya or llmman when the client points at one of them.

systemone

observationRegistry(ObservationRegistry)

The registry that observes the calls.

ObservationRegistry.NOOP

observationConvention(DecisionModelObservationConvention)

The convention that the observations follow.

the default convention

Backends

All backends use the same protocol. They differ in where the client points to, and in what the response leaves out.

Backend Client Model Differences

TypeSafe Jev

baseUrl api.typesafe.ai (the default), and your API key

jev-latest (the default), or another SystemOneModel alias

The reference implementation. It reports a request id, which becomes the response id.

Ollama 0.35+

baseUrl localhost:11434, and any API key that is not empty, such as ollama

A model that you pulled, such as d1-omni:600m. Ollama has no jev-latest, so set defaultModel(…​).

No request id. It rejects a yes/no question without text. It can answer differently when the order of the fields changes. It loads the model on the first call, so give that call a long timeout.

Laya 0.3.7+

baseUrl of your laya-serve, such as localhost:8002, and its LAYA_API_KEY when set

The checkpoint names of Laya, such as english. Laya routes other names automatically.

No request id. Output tokens are always 0. It serves one request at a time.

llmman 0.1.497+

baseUrl 127.0.0.1:17434 (the default of llmman serve), and one of its LLMMAN_API_KEYS when set, or else any API key that is not empty, such as llmman

A local GGUF model, such as gemma4. llmman has no jev-latest, so set defaultModel(…​).

No request id. Output tokens are always 0.

For Ollama, the OllamaDecisionModel uses the same protocol, and adds Spring Boot auto-configuration and the pulling of models.

The backends use different models, so their answers differ. When you move from one backend to another, check your thresholds again.

Set the provider name to tell the backends apart in observations:

SystemOneClient ollama = SystemOneClient.builder()
    .baseUrl("http://localhost:11434")
    .apiKey("ollama")
    .defaultModel("d1-omni:600m")
    .timeout(Duration.ofSeconds(60))
    .retryTemplate(SystemOneRetryUtils.noRetryTemplate())
    .build();

SystemOneDecisionModel decisionModel = SystemOneDecisionModel.builder(ollama)
    .provider("ollama")
    .build();

Runtime Options

SystemOneDecisionOptions holds the model name, which is the only setting that the protocol takes for each request. You can change it for one call by setting options on the prompt:

DecisionResponse response = decisionModel.call(DecisionPrompt.builder()
    .text("My new headphones arrived yesterday, but the left side doesn't work. Can I get my money back?")
    .question("defect", YesNoQuestion.builder()
        .text("Does the customer report a defect?")
        .whenYes("Part of the item does not work as it should")
        .whenNo("The item works, and the message is about something else")
        .build())
    .question("topic", ChoiceQuestion.builder()
        .text("What is the message about?")
        .option("delivery", "Where an order is, or when it will arrive")
        .option("product", "A problem with an item the customer received")
        .option("account", "Login, address or payment details")
        .option("other", "None of the above")
        .build())
    .question("satisfaction", ScoreQuestion.of("How satisfied is the customer?", "unhappy", "neutral", "happy"))
    .options(SystemOneDecisionOptions.builder()
        .model("jev-preview")
        .build())
    .build());

boolean defect = response.getYesNo("defect").isYes();
String topic = response.getChoice("topic").getValue();
int satisfaction = response.getScore("satisfaction").getNearestLevel();

The portable DecisionOptions work too. The timeout, the retry policy and the headers are settings of the SystemOneClient, and they apply to every call.

Supported Features

Feature Supported Notes

Text input

Yes

Text with images

No

System One decides about text only, so an image in the input makes the call fail.

Fields input

Yes

Use a LinkedHashMap to keep the fields in order.

Conversation input

Yes

Tool calls and tool results are sent, reasoning is not.

Probabilities

Yes

For all three kinds of questions.

Confidence

Yes

For choice and score answers. A confidence of 0 can mean that the server reported none.

Refusals

No

Response id

Depends on the backend

Only TypeSafe Jev reports one. See Backends.

Request Mapping

Each question becomes one entry of the questions of the request, under the name of the question.

Spring AI question System One question Notes

YesNoQuestion

noul

When set, whenYes and whenNo are sent as the true and false criteria.

ChoiceQuestion

choice

Each option becomes a criterion with the name of the option, and its description or null.

ScoreQuestion

score

Each level becomes a criterion, from the lowest to the highest: its label, or a {"label", "description"} object when it has a description.

The input becomes the state of the request:

  • for DecisionInput.text(…​), or an input made of text parts only: the text, as a string;

  • for DecisionInput.fields(…​): a JSON object, with the fields in the order of the map. A field that holds content parts becomes their text;

  • for DecisionInput.conversation(…​): a {"messages": […​]} object, with one entry for each message that has something to send. Each entry has the role of the message, its text as content, its tool calls as tool_calls, and its tool results as tool_results. The arguments of a tool call are sent as a nested object when they are JSON.

System One decides about text only. A MediaPart anywhere in the input makes the call fail. In a conversation, the reasoning parts and unknown parts of a message are not sent. A message with nothing left to send, such as a message with only reasoning, is left out.

Response Mapping

A noul answer becomes a YesNoAnswer. A choice answer becomes a ChoiceAnswer, with the probability of each option and the confidence. A score answer becomes a ScoreAnswer, with the probability of each level and the confidence.

Spring AI checks the answers against the prompt. An answer for a question that the prompt didn’t ask, or an answer of the wrong kind, makes the call fail. An answer of a kind that the client doesn’t know makes the call fail too.

The client reports a confidence of 0 when the server sends none, so a confidence of 0 can mean that there is no confidence.

The model that answered and the token usage come from the response body. When the server sends a request id in the x-typesafe-request-id header, Spring AI records it as the id of the response. You get it from response.getMetadata().getId() and from the gen_ai.response.id observation key. Ollama, Laya and llmman send no request id, so the id is null, and the observation has no such key.

Errors come as exceptions of the SystemOneException hierarchy, such as SystemOneBadRequestException or SystemOneRateLimitException, listed in Low-level SystemOneClient. They come after the retries of the RetryTemplate of the client, which retries connection failures, request timeouts, rate limits and server errors twice by default, and waits as long as the server asks on a rate limit. See SystemOneRetryUtils for the default policy, and for the predicate and the wrapper that a policy of your own should use.

Low-level SystemOneClient

SystemOneClient is the client of the /v1/systemone protocol that the decision model is built on. With the starter it is a regular bean, and SystemOneDecisionModel is the recommended way to use it. Reach for the client itself to list the models of a server, or to send a request of the protocol as it is.

Builder

Builder method Description Default

apiKey(String)

The API key, sent as a bearer token. Required, unless systemOneApi supplies the transport.

-

apiKey(Supplier<String>)

Consulted on every request, so a rotated key takes effect without rebuilding the client.

-

baseUrl(String)

The API root.

https://api.typesafe.ai

defaultModel(String)

The model applied to a request that names none.

jev-latest

timeout(Duration)

The read timeout of the transport the client builds. Not applied when you supply the transport.

10s

retryTemplate(RetryTemplate)

How transient failures are retried. See SystemOneRetryUtils for the default policy and for the pieces of a policy of your own.

SystemOneRetryUtils.defaultRetryTemplate()

headers(HttpHeaders)

Headers sent on every request. Calling it twice sends both sets. Authorization, Content-Type and Accept are set by the client after yours.

none

restClientBuilder(RestClient.Builder)

The builder to derive the HTTP client from. It is cloned, not changed, so you keep control of interceptors and observability.

the client builds its own

systemOneApi(SystemOneApi)

A fully assembled transport, in place of every other transport setting.

-

The client is immutable and safe to share between threads.

Sending a Request

The systemOne methods take the state as text, a map, a list or a JsonContent, with the questions as a map. A request built with SystemOneRequest.builder() can also name the model for one call:

SystemOneResponse response = client.systemOne(SystemOneRequest.builder()
    .state(JsonContent.object("message", "Help! My payouts have been failing for 3 days."))
    .model("jev-preview")
    .question("is_urgent", Noul.of("Does this convey urgency?"))
    .question("department", Choice.builder()
        .instructions("Which team should handle this?")
        .option("billing", "Payments, invoicing, refunds")
        .option("technical", "Bugs, outages, integrations")
        .build())
    .build());

The server reads the state, the questions and the criteria in the order they are sent, and a different order can change an answer. Map.of(…​) has no order, so build content with more than one key with JsonContent.object(…​), with the question(…​) calls of the builder, or with a LinkedHashMap.

Reading the Answers

double urgency = response.noulValue("is_urgent");
String department = response.choiceValue("department");

ChoiceAnswer choice = response.choice("department");
choice.confidence();
choice.probabilityOf("billing");
choice.optionsAbove(0.1); // the options above the threshold, the likeliest first

response.usage().inputTokens();
response.requestId(); // quote it when you report a problem

Asking for an answer of another kind throws SystemOneAnswerTypeException, and asking for a name the response does not carry throws SystemOneMissingAnswerException. Both say which name you asked for and what the response has.

Listing the Models

for (ModelMetadata model : client.listModels()) {
    System.out.printf("%s: %s (%s)%n", model.name(), model.description(), model.releaseDate());
}

The aliases of the hosted service are in SystemOneModel. A response reports the model it resolved an alias to, so a request for jev-latest comes back with a pinned version.

Errors

Every failure of the client is a SystemOneException, thrown after the retries.

Exception When

SystemOneApiException

An HTTP error response. It carries the status(), the raw body(), the requestId() and the parsed errorDetail().

SystemOneBadRequestException, SystemOneAuthenticationException, SystemOnePermissionDeniedException, SystemOneNotFoundException, SystemOneUnprocessableEntityException

A 400, 401, 403, 404 or 422 response.

SystemOneRateLimitException

A 429 response. retryAfter() carries the wait the server asks for, which the default retry policy honours.

SystemOneInternalServerException

A 5xx response. SystemOneOverloadedException is the non-standard 529 of the hosted service.

SystemOneApiConnectionException

No HTTP response at all. SystemOneApiTimeoutException when the attempt timed out.

SystemOneApiResponseValidationException

A successful response that misses what the client needs, such as an empty body or no answers.

SystemOneAnswerTypeException, SystemOneMissingAnswerException

Raised on the client when you read an answer of another kind, or one the response does not carry.

Observability

Spring AI observes the calls as decision operations, with the configured provider name as the gen_ai.system key. See Decision Model observability.

Example Code

The SystemOneDecisionModelIT test runs against the server that the SYSTEMONE_BASE_URL, SYSTEMONE_API_KEY and SYSTEMONE_MODEL environment variables point to. It shows the three kinds of questions, and the fields and conversation inputs.