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.
Prerequisites
-
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.
-
-
The
spring-ai-starter-model-systemonedependency, as described in Auto-configuration, or thespring-ai-systemonedependency 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 |
- |
spring.ai.systemone.base-url |
The API root. Point it at Laya, llmman or another server of the protocol. |
|
spring.ai.systemone.timeout |
The read timeout of each attempt.
Unset, the |
- |
spring.ai.systemone.retry.max-retries |
Retries after the initial attempt.
|
|
spring.ai.systemone.retry.initial-backoff |
The first wait, doubled on each further retry. |
|
spring.ai.systemone.retry.max-backoff |
The upper bound on a single wait. |
|
spring.ai.systemone.retry.timeout |
No further attempt is started once this much time has passed since the first. |
|
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 To enable it, set To disable it, set |
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. |
|
spring.ai.systemone.decision.model |
The model name or alias.
Unset, the default model of the |
- |
spring.ai.systemone.decision.provider |
The provider name recorded in observations, such as |
|
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 |
|---|---|---|
|
The default options. When they set no model, the default model of the client is used. |
the default model of the client |
|
The provider name for observations, such as |
|
|
The registry that observes the calls. |
|
|
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 |
|
|
The reference implementation. It reports a request id, which becomes the response id. |
Ollama 0.35+ |
|
A model that you pulled, such as |
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+ |
|
The checkpoint names of Laya, such as |
No request id.
Output tokens are always |
llmman 0.1.497+ |
|
A local GGUF model, such as |
No request id.
Output tokens are always |
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 |
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 |
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 |
|---|---|---|
|
|
When set, |
|
|
Each option becomes a criterion with the name of the option, and its description or |
|
|
Each level becomes a criterion, from the lowest to the highest: its label, or a |
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 theroleof the message, its text ascontent, its tool calls astool_calls, and its tool results astool_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 |
|---|---|---|
|
The API key, sent as a bearer token.
Required, unless |
- |
|
Consulted on every request, so a rotated key takes effect without rebuilding the client. |
- |
|
The API root. |
|
|
The model applied to a request that names none. |
|
|
The read timeout of the transport the client builds. Not applied when you supply the transport. |
|
|
How transient failures are retried.
See |
|
|
Headers sent on every request.
Calling it twice sends both sets.
|
none |
|
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 |
|
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 |
|---|---|
|
An HTTP error response.
It carries the |
|
A 400, 401, 403, 404 or 422 response. |
|
A 429 response.
|
|
A 5xx response.
|
|
No HTTP response at all.
|
|
A successful response that misses what the client needs, such as an empty body or no answers. |
|
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.