@corbits/system-one

Typed choice, score and yes/no decisions about a JSON state from TypeSafe's Jev model, returned as a validated result or a typed fallback. An inference provider for Corbits and Interchange agents: registers as an @intx/inference adapter, and also works standalone through evaluate().

Why @corbits/system-one?

1. Typed decisions, not free text. You send questions with ids; you get back one validated decision per id, with probabilities and confidence. No prompt parsing.
2. Failures are data. A missing key, timeout, HTTP error or bad body returns a FallbackResult with a reason, so a gate can fail closed without a try. Only invalid caller input throws.
3. One call, many questions. Every question in a list goes out in one POST, bounded by a 1.5 s default timeout.

It evaluates structured state against questions. For open-ended chat completions, use a general inference provider such as @corbits/openai-responses.

Install

bun add @corbits/system-one @intx/inference@^0.4.0 @intx/types@^0.4.0

Runs on Bun >= 1.2 or Node >= 24.

To consume an exact Git commit before it is published, enable the package's source condition because Git dependencies do not run prepack:

bun add github:corbitsdev/corbits-system-one#<commit>
bun --conditions=corbits-system-one-src your-script.ts

Published consumers continue to use the built dist entry by default.

Quickstart

Needs TYPESAFE_API_KEY set.

import { evaluate } from "@corbits/system-one";

const result = await evaluate({
  state: { action: "deploy", env: "production" },
  questions: [
    {
      id: "escalate",
      type: "boolean",
      instructions: "Must this request be escalated for human approval?",
    },
  ],
});

console.log(result.fallback ? result.reason : result.decisions);

On success it prints one decision per question, or the fallback reason on failure:

[{ id: "escalate", type: "noul", noul: 0.91 }];

Boolean questions answer as noul, a probability from 0 to 1 that the answer is yes.

Where it fits

Interchange runs AI agents as principals (accounts that hold their own identity, permissions and credentials). Corbits packages add what an agent product needs around it.

• Runs in: the agent sidecar (the runtime next to each agent), or any process. evaluate() needs no Interchange runtime.
• Plugs into: the @intx/inference adapter registry, as the adapter for the corbits-system-one provider id.
• Pairs with: @corbits/openai-responses and @corbits/ollama-adapter, the other Corbits inference providers.

Reference

Export	Description
evaluate(input, options?)	Runs one evaluation. Returns EvaluateResult: decisions or a FallbackResult.
systemOne(input, options?)	Keyed decisions. Returns answers by question name, or the same fallback.
choice, noul, score, box	Build one keyed question. box locates a region and needs model jev-preview.
image, Image.fromBase64	PNG or JPEG bytes, a Blob, or base64. Other formats are rejected before send.
withAssets	Tag a template so interpolated images are sent. Also withAssets.join.
createSystemOneAdapter(config?)	Returns a ProviderAdapter for runInference. config is an EvaluateConfig.
createSystemOneAdapterFactory	Interchange AdapterFactory for SIDECAR_ADAPTER_MANIFEST; takes offering quirks.
SYSTEM_ONE_PROVIDER	The "corbits-system-one" provider id.
DEFAULT_TIMEOUT_MS	1500, the default timeoutMs.
SystemOneError	Thrown for invalid input or a custom endpoint without a url.
SystemOneTelemetryEvent	Schema and type for events passed to onTelemetry.
EvaluateOptions, EvaluateDeps	Types for options: onTelemetry, and deps: { fetch, scheduler }.

Question, QuestionList, Decision, EvaluateInput, EvaluateConfig, EndpointConfig, EvaluateResult and FallbackResult are exported as arktype schemas and types.

Questions

type	Fields	Decision fields
choice	instructions, criteria (option name → description or null, 1–255 options)	choice, probabilities, confidence
score	instructions, criteria (2–10 descriptions)	score, legend, probabilities, confidence
boolean	instructions, optional criteria: { true?, false? }	noul
noul	Same as boolean	noul
box	instructions describing what to locate. Use model jev-preview.	box (top, bottom, left, right as fractions), confidence

Every list question has an id, unique within the list. box edges outside [0, 1] are rejected.

Keyed questions

systemOne takes the same state and a record of questions built with choice, noul, score, and box. The names are the answer keys. Those helpers compile to the list evaluate already sends. The same fallback reasons apply, and those failures do not throw. The helpers are also exported from @corbits/system-one/decisions.

import { choice, noul, score, systemOne } from "@corbits/system-one";

const result = await systemOne({
  state: { document: "I was charged twice." },
  questions: {
    category: choice("What is this?", { billing: null, technical: null }),
    escalate: noul("Must this be escalated?"),
    severity: score("How severe?", ["none", "cosmetic", "unusable"]),
  },
});

On success, read result.answers.category.choice (plus probabilities and confidence), result.answers.escalate.noul, and result.answers.severity.score.

image() accepts a Blob or Uint8Array. Image.fromBase64() accepts base64 file bytes. Only PNG and JPEG are sent. Place an image in state, instructions, or criteria, or interpolate it with withAssets (and withAssets.join for a list). An image in an ordinary template string is rejected before the request. assets maps a name to an image for plain strings; every name must appear as its own token in the request. A request with any image is multipart/form-data and sends TypeSafe-Danger-Zone-Images: true. Otherwise the body stays JSON.

import { box, image, systemOne, withAssets } from "@corbits/system-one";

const photo = image(pngBytes);
const result = await systemOne({
  state: withAssets`Returned item: ${photo}`,
  questions: { damage: box("The damaged area") },
  model: "jev-preview",
});

providerOptions.systemOne.questions accepts this keyed record as well as a question list.

Config

input.config for evaluate, or the argument to createSystemOneAdapter:

Field	Type	Default	Description
endpoint	EndpointConfig	{ kind: "official" }	official, gateway, or custom with a url. Each takes an optional model. custom may set auth: "none".
timeoutMs	number	1500	Bound for the whole round trip.
apiKey	string	from the environment	Overrides the environment key.

Endpoints and keys

kind	URL	Default model	Key from the environment
official	https://api.typesafe.ai/v1/systemone	jev-latest	TYPESAFE_API_KEY
gateway	https://ai-gateway.vercel.sh/typesafe/v1/systemone	typesafe-ai/jev	AI_GATEWAY_API_KEY, then VERCEL_OIDC_TOKEN
custom	url	typesafe-ai/jev	SYSTEM_ONE_API_KEY, unless auth: "none"

SYSTEM_ONE_API_KEY is also a supported alias on every endpoint, read after the endpoint's own key. A custom endpoint with auth: "none" does not require a key and does not send Authorization. Official and gateway always require a key. Any other auth value is invalid input and throws.

Fallback reasons

reason	When
no-key	No key in apiKey or the environment, and the endpoint is not custom with auth: "none". No request is sent.
timeout	The round trip, including the body read, exceeds timeoutMs.
network	The request fails before a response.
http-error	Non-2xx response. httpStatus holds the status.
parse-error	The body is not JSON or fails validation.

detail carries the underlying message.

Using with Interchange

Register the adapter under SYSTEM_ONE_PROVIDER and pass questions per call in providerOptions.systemOne ({ state?, questions? }). Without state, the adapter sends the transcript text as state. Without questions, it asks one boolean question with id response.

import { createDependencies, runInference } from "@intx/inference";
import {
  createSystemOneAdapter,
  SYSTEM_ONE_PROVIDER,
  type QuestionList,
} from "@corbits/system-one";

const deps = createDependencies({
  has: (provider) => provider === SYSTEM_ONE_PROVIDER,
  resolve: () => createSystemOneAdapter(),
});

const questions = [
  {
    id: "escalate",
    type: "boolean",
    instructions: "Must this request be escalated for human approval?",
  },
] satisfies QuestionList;

let seq = 0;
for await (const event of runInference({
  deps,
  source: {
    id: "system-one",
    provider: SYSTEM_ONE_PROVIDER,
    baseURL: "https://api.typesafe.ai/v1/systemone",
    credentialId: "TYPESAFE_API_KEY",
    model: "jev-latest",
  },
  turns: [
    {
      role: "user",
      timestamp: Date.now(),
      content: [{ type: "text", text: "Deploy to production?" }],
    },
  ],
  inferenceOptions: { providerOptions: { systemOne: { questions } } },
  nextSeq: () => seq++,
  readMaterial: (id) => {
    const secret = process.env[id];
    if (secret === undefined) throw new Error(`${id} is not set`);
    return { secret };
  },
})) {
  if (event.type === "inference.text.delta")
    console.log(JSON.parse(event.data.token));
}

The adapter emits one inference.text.delta per decision, whose token is the decision as JSON, then an inference.usage event. The harness supplies the credential through readMaterial and owns retries. A malformed response body is a ProtocolMismatchError, not a fallback.

Manifest factory

createSystemOneAdapterFactory(source, quirks?) is an Interchange AdapterFactory, so a stock sidecar loads it from SIDECAR_ADAPTER_MANIFEST with no custom code:

[
  {
    "provider": "corbits-system-one",
    "specifier": "@corbits/system-one",
    "export": "createSystemOneAdapterFactory"
  }
]

The hub offering's quirks are validated and all optional:

{
  "endpoint": {
    "kind": "custom",
    "url": "https://opencode.ai/zen/v1/systemone"
  },
  "model": "jev-1.13",
  "questions": [{ "type": "boolean", "id": "gate", "instructions": "Allow?" }],
  "state": {}
}

Without endpoint, the adapter posts to the catalog provider's baseURL + /systemone, the host the offering's credential was issued for. A model quirk (top level or on endpoint) is the model sent on the wire, so one catalog model can be served by providers that name it differently. questions and state are per-call defaults; providerOptions.systemOne on a call wins field by field. Unknown keys throw. The adapter sends the bearer sentinel and the harness injects the offering's credential, except a custom endpoint with auth: "none", which omits Authorization so the host does not attach a key.

Provider	Provider baseURL	model quirk
TypeSafe	https://api.typesafe.ai/v1	jev-latest
Vercel AI Gateway	https://ai-gateway.vercel.sh/typesafe/v1	typesafe-ai/jev
OpenRouter	https://openrouter.ai/api/v1	typesafe/jev-1.13
OpenCode Zen	https://opencode.ai/zen/v1	jev-1.13 or jev-1.13-free

Upgrading to 0.3.1

• createSystemOneAdapterFactory without an endpoint quirk now posts to the catalog provider's baseURL + /systemone instead of the official TypeSafe URL. Set the provider baseURL to the API root (for example https://api.typesafe.ai/v1), or keep the old behavior with {"endpoint":{"kind":"official"}}. The harness sends the offering's credential to whatever URL the adapter returns, so only set an explicit endpoint on a host that credential belongs to.
• A model quirk now overrides the model the harness passes (the catalog canonical name).
• createSystemOneAdapter and evaluate accept auth: "none" on a custom endpoint and omit Authorization. Any other auth value throws SystemOneError before a request is built.

Upgrading from 0.1

• HttpError, NetworkError and TimeoutError are removed. Transport failures return a FallbackResult.
• A 2xx body that is not JSON is parse-error (was network). A timeout during the body read is timeout.
• recordTelemetryEvent and drainTelemetryEvents are removed. Pass evaluate(input, { onTelemetry }).
• Wire helpers, quirks presets, JsonRecord, Confidence and the env-var name constants are no longer exported.
• A custom endpoint without a model sends typesafe-ai/jev.
• Peers are @intx/inference and @intx/types ^0.4.0.
• Environment variables are unchanged, including SYSTEM_ONE_API_KEY.

License

LGPL-2.1-only