TypeScript SDK

System One SDK is an open-source TypeScript toolkit, usable independently of the System One hosted API. Define questions with choice(), score(), and booleanQuestion(), send them with evaluate(), or define Clairic fields and send them with extract(). Use typed answers in your application or agent.

The core package is MIT-licensed with no runtime dependencies. Installing or using the library does not require a System One account. Network evaluations use the credentials, availability, and billing of the service you connect to. System One account credits apply to our hosted API, not to every SDK connection.

Published packages on npm as of 2026-10-21:

Other @system-one-ai/adapter-* packages connect the same client to additional services; each one runs under that service's own credentials and billing.

Core 0.8.0 adds Clairic extract({ state, fields }). systemOneAdapter@0.7.0 posts extract requests to POST {baseURL}/systemone with a fields body and default model clairic. See Clairic extraction. Do not pass fields to evaluate().

The deprecated @system-one-ai/sdk@0.5.3 entry point is removed. Packages release independently; install matching versions that all resolve core@^0.8.0.

Answer-ready

Q: What is the System One TypeScript SDK?
A: The System One TypeScript SDK is an open-source client for the hosted System One API. It helps you call Choice, Score, Noul, and Clairic extract with typed results.

Install and choose a runtime

For the hosted System One API (decisions and Clairic extraction):

npm install @system-one-ai/core@0.8.0 @system-one-ai/adapter-system-one@0.7.0 @system-one-ai/transport-fetch@0.8.0

The packages provide ESM, CommonJS, and TypeScript declarations. Use Node.js 20+ or a compatible runtime providing Fetch and AbortController. Keep service credentials on the server. Core does not select a protocol from a hostname or read your environment variables for you; pass the configuration explicitly.

createSystemOne(options) is the documented factory and returns a SystemOne instance. new SystemOne(options) is the same constructor.

Choose a service connection

Install the chosen adapter with core 0.8.0 and, for HTTP adapters, transport-fetch 0.8.0. These are public SDK integration choices, not a list of services or models hosted on this website. Consult the SDK README for each adapter's configuration and current support.

For our hosted API, use the hosted SDK quickstart. Select an exact model ID from the current model directory and check its capabilities, limits, and credit price. Use public names such as jev, clef, clef-flash, and clairic. To connect the SDK to another service, use that service's @system-one-ai/adapter-* package with your own credentials and your own billing. Do not assume an alias, SDK default, or a model offered by another service is accepted.

Start with the hosted API

Set SYSTEM_ONE_API_KEY to your System One platform key and SYSTEM_ONE_MODEL to an exact ID from the current model directory. YOUR_MODEL_ID below is a placeholder, not an alias. This example makes a real request billed to your System One account credits.

SYSTEM_ONE_API_KEY=replace-with-your-platform-key
SYSTEM_ONE_BASE_URL=https://system-one.dev/v1
SYSTEM_ONE_MODEL=YOUR_MODEL_ID

import { createSystemOne, choice, score, booleanQuestion } from '@system-one-ai/core';
import { systemOneAdapter } from '@system-one-ai/adapter-system-one';
import { createFetchTransport } from '@system-one-ai/transport-fetch';

const apiKey = process.env.SYSTEM_ONE_API_KEY;
const baseURL = process.env.SYSTEM_ONE_BASE_URL;
const model = process.env.SYSTEM_ONE_MODEL;
if (!apiKey || !baseURL || !model || model === 'YOUR_MODEL_ID') {
  throw new Error('Set SYSTEM_ONE_API_KEY, SYSTEM_ONE_BASE_URL, and SYSTEM_ONE_MODEL.');
}

const client = createSystemOne({
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  baseURL,
  apiKey,
  model,
  timeoutMs: 30_000,
  maxRetries: 0,
});

const result = await client.evaluate({
  state: { message: 'I was charged twice for the same order.' },
  questions: {
    team: choice('Choose the team that should review this message.', {
      billing: 'Payments and refunds',
      support: 'Technical issues',
      review: 'More information is needed',
    }),
    urgency: score('Rate urgency using this ordered rubric.', [
      'Routine review', 'Timely response', 'Immediate human attention',
    ]),
    duplicate: booleanQuestion('Does the message report a duplicate charge?'),
  },
});

const team: 'billing' | 'support' | 'review' = result.answers.team.choice;
console.log({
  team,
  urgency: result.answers.urgency.score,
  duplicateProbability: result.answers.duplicate.probability,
});

The same question factories work with the other adapters, within each service's accepted request contract. A direct service's recovery or idempotency rules are its own; do not assume our hosted API's rules apply there.

Images

ImageInput is exported by core: an embedded base64 data URL string or { mediaType: 'image/png', base64: '...' } with actual encoded bytes. images is an optional top-level sibling of state and questions (or fields). state is still required; '' is valid when images are present. images: [] is text-compatible. Remote URLs, downloads, audio and video are unsupported.

Hosted Clairic images use extract() on systemOneAdapter@0.7.0. See Clairic images.

Hosted Clef / Clef Flash / Clef Omni decision images still use standard Fetch/HTTP. systemOneAdapter implements evaluate({ state, questions }) without encoding images. Changing supportsImages or upgrading core alone does not add that encoder. Use a System One key and an image-capable catalog model (clef, clef-flash, or clef-omni when listed). Hosted admission also enforces the complete UTF-8 JSON limit (up to 13MB for image-capable Clef entries) and any tighter catalog limits. Playground shows HTTP/curl guidance instead of a text-only SDK snippet when decision images are attached.

Clef and Clef Flash accept PNG, JPEG and WebP, at most four images, 4MB decoded per image and 8MB decoded total. Discover image in capabilities.inputs rather than inferring support from a package version.

Preserve question and answer types

choice() preserves literal option names. score() returns a number that can be fractional. booleanQuestion() returns P(true), not a boolean; the native HTTP protocol calls this question noul and the adapter converts between the two representations.

Use defineQuestions() when sharing definitions, and derive request/result types from that question set:

import { choice, defineQuestions } from '@system-one-ai/core';
import type { Answers, EvaluateRequest, EvaluationResult } from '@system-one-ai/core';

const questions = defineQuestions({
  team: choice('Choose the reviewing team.', {
    billing: 'Payments and invoices',
    support: 'Technical help',
  }),
});

type TeamRequest = EvaluateRequest<typeof questions>;
type TeamResult = EvaluationResult<typeof questions>;
type TeamAnswers = Answers<typeof questions>;

const request: TeamRequest = {
  state: { message: 'Please explain this invoice.' },
  questions,
};

Core requires non-null state for evaluate() and an explicit instructions field. Its Description type permits null, but a selected service/model may not. Boolean criteria may be omitted or an object, not null. The official TypeSafe client has a broader nullable input contract; see primitives. Use explicit text and non-null descriptions for the portable examples in these docs.

Results are normalized across adapters, not the original HTTP body. Distributions, confidence, and token counts may be absent: unknown is not zero. Confidence is not necessarily the selected option's probability. result.model may report a resolved name different from the requested ID. For raw text, precise decimal handling, and hosted accounting headers, use the HTTP API or the official client alternative.

Fetch transport

createFetchTransport() from @system-one-ai/transport-fetch@0.8.0 sends prepared adapter requests with authentication, the total timeout, cancellation, retries, and a successful-response size limit (maxResponseBytes, default 8MB). Pass a custom Fetch implementation as the first argument, not as a SystemOneOptions field:

import type { Fetch } from '@system-one-ai/core';

const customFetch: Fetch = (input, init) =>
  globalThis.fetch(input, { ...init, cache: 'no-store' });

const customClient = createSystemOne({
  apiKey,
  model,
  baseURL: 'https://system-one.dev/v1',
  adapter: systemOneAdapter,
  transport: createFetchTransport(customFetch),
  maxRetries: 0,
});

A custom implementation must preserve the request, authentication headers, cancellation signal, and real Response. Do not log credentials or submitted content in a transport wrapper.

protocol-system-one@0.8.0 converts this library's questions and answers to the native System One wire format. The hosted adapter and other compatible HTTP adapters install it automatically.

Timeouts, cancellation, retries, and errors

Core's timeoutMs is a total evaluation budget, including credential resolution, retries, delays, and response reading. The default is 10,000 ms. Client-level maxRetries sets extra attempts (default 2, range 0–100); per-call timeoutMs, maxRetries, headers, and signal override or supplement the client settings.

This continuation uses client from “Start with the hosted API” and request from “Preserve question and answer types.” Running it makes a separate System One evaluation; it is not a retry of the first example.

const resultWithDeadline = await client.evaluate(request, {
  timeoutMs: 15_000,
  maxRetries: 0,
  signal: AbortSignal.timeout(15_000),
});
console.log(resultWithDeadline.answers.team.choice);

The Fetch transport can retry connection failures, HTTP 408, 429, and 5xx. Start with maxRetries: 0 until your application owns recovery. The SDK does not generate idempotency keys. For hosted API calls, save the key and effective request before sending and follow idempotency and retries. Cancellation or timeout does not prove that the service stopped or that no charge occurred.

Core exports SystemOneError, ConfigurationError, ValidationError, UnsupportedFeatureError, ResponseValidationError, APIError, ConnectionError, BindingError, TimeoutError, and RequestAbortedError. In published core 0.8.0, APIError exposes statusCode, requestId, and retryAfterMs, not the full body or all response headers. Use raw Fetch or the official client's error headers for hosted error classification.

Migrate from the former package

@system-one-ai/sdk@0.5.3 is deprecated. Replace its imports rather than keeping both client layouts:

See the maintained 0.6 migration guide, SDK source and README, and MIT license. Current hosted examples target core 0.8.0 with adapter-system-one@0.7.0 and transport-fetch@0.8.0. Package versions and hosted API/model capabilities are independent.

Next steps

• Extract typed fields with Clairic
• Connect the SDK to hosted API
• Choose a model