Make System One the base protocol for decision models

[jimador]

Stacked on #2139. The diff is against feature/decision-model-providers.

System One is the JSON protocol decision models speak. One request asks several typed questions about one piece of state, and each answer comes back as a probability, a distribution or a confidence. This PR makes it the base for every decision model endpoint. TypeSafe becomes a preset over it, and any other System One endpoint, such as CLEF in a local Ollama, works through the same client.

flowchart LR
    S[DecisionService] --> F[SystemOneModelFactory]
    F --> C[SystemOneCodec<br/>embabel-agent-ai]
    F --> T[SystemOneTransport]
    T --> E[(System One endpoint)]
    TS[TypeSafeModelFactory] -- extends --> F

Loading

Surfaces

Type	Module	What it does
SystemOneCodec	embabel-agent-ai	Writes requests and reads responses. Questions go out keyed q1 to qN, so caller question names never leave the process. Reads model listings as {"models": [{"name"}]} or the OpenAI shape {"data": [{"id"}]}.
SystemOneEndpoint	embabel-agent-systemone	Provider name, base address, timeouts, response size limit and request id header. Rejects addresses that could carry credentials.
SystemOneModelFactory	embabel-agent-systemone	Builds a DecisionService per model and implements ByokFactory. Reads the key on every call.
TypeSafeModelFactory	embabel-agent-typesafe	Extends SystemOneModelFactory with TypeSafe's address, provider name, x-typesafe-request-id and a required key. Constructors, build, buildValidated, PROVIDER and DEFAULT_MODEL keep their signatures.
ClassificationResult.Selected	embabel-agent-ai	Carries the per-category distribution a model reported. It must cover exactly the question's options and sum to 1.

Running a model locally needs no key:

var ollama = new SystemOneEndpoint("Ollama", URI.create("http://localhost:11434"));
DecisionService clefFlash = new SystemOneModelFactory(ollama, "clef-flash", () -> null).build();

The System One reference page covers pulling clef or clef-flash into Ollama, a curl check, plain Java and Spring wiring, and the smoke test.

Transport

• An error status fails without the body being parsed or logged. A success body is read up to the endpoint's limit.
• No redirects on the factory's own client, and no retries.
• An application RestClient.Builder is cloned, so its interceptors and timeouts apply. The key is set by the last interceptor and replaces any Authorization header the application adds.
• Each call is observed as embabel.systemone.request with a provider tag.

Failure behaviour

• A failed call returns failure outcomes with one WARN line: the call kind, the reason, then service, provider, operation, cause, status, attempts, elapsed time and request id. The line never holds the key or the request content.
• A missing or unusable key fails as UNAVAILABLE with cause credential before anything is sent.
• A response that can't be read as a whole fails the request as INVALID_RESPONSE. A malformed answer fails only its own question.
• An interrupted caller is cancelled before anything is sent and keeps its interrupt flag, including during buildValidated().

Behaviour changes

• Single classify and assess calls go out keyed q1, like every other question set.
• The observation is embabel.systemone.request. It was embabel.typesafe.request.
• A missing or unusable TypeSafe key fails as UNAVAILABLE with cause credential.
• Selected is a plain class like RatingResult.Answered, with an unmodifiable copy of the distribution. It loses copy and destructuring. It has not been released.
• The typesafe-java-sdk dependency is gone.

@igordayen

[igordayen]

@jimador solid design/code. first round of manual review. coding agent review to follow. thanks

[igordayen]

A few non-blocking points from CODEX

• Rating legend validation is limited. SystemOneAnswers.kt:157 checks the legend’s indexes, but not its values. A response with reversed descriptions
  would still be interpreted using the requested level order. This behavior existed in the previous adapter; consider validating it or explicitly
  documenting that indexes alone are authoritative.

• Exception traversal should be cycle-safe. SystemOneTransport.kt:323 walks causes without tracking visited exceptions. An application-supplied client or
  credential supplier returning a cyclic cause chain could hang error handling. Low-frequency hardening, not a normal-path blocker.

• Add an interrupted-validation edge-case test. buildValidated() resolves credentials before reaching the transport’s interrupt check. Test an already-
  interrupted caller with a missing credential: currently it can receive InvalidApiKeyException rather than cancellation.

Thanks

[jimador]

on these three points

kept the mapping positional and documented it. added a reversed-label test so it's clear that returned labels don't change the requested level order

fixed, cause traversal now tracks exception identity so cycles terminate. added tests for client and credential failures, including a timeout inside a cycle

good catch, validation now checks for interruption before touching credentials. added coverage for missing and blank keys too

[igordayen]

@jimador - looks good, thanks for addressing feedback.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud