System One SDK

System One SDK is an open-source TypeScript toolkit for adding structured decisions to Agents and applications. Define questions with choice(), score(), and booleanQuestion(), send them with evaluate(), and use typed answers in your code.

The core package is MIT-licensed and has no runtime dependencies. Install the adapter and transport for your chosen service alongside core. Each connection uses that service's credentials and billing.

Install

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

Use Node.js 20+ or a runtime with Fetch and AbortController, such as Cloudflare Workers. Keep credentials on the server.

SDK 0.6.0 replaces the old single package with independently installed packages. HTTP clients require an explicit adapter and transport; custom Fetch belongs in createFetchTransport(customFetch). See the 0.6 migration guide.

Choose a connection

For our hosted service, follow Connect the SDK to hosted API. See the SDK 0.6.0 README for adapter configuration. The SDK does not switch protocols based on a hostname.

Start with TypeSafe

Set the server environment variable TYPESAFE_API_KEY, then run this TypeScript example. It calls TypeSafe directly and does not use a System One platform key or credits.

import { SystemOne, 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 client = new SystemOne({
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  baseURL: 'https://api.typesafe.ai/v1',
  apiKey: process.env.TYPESAFE_API_KEY!,
  maxRetries: 0,
});

const result = await client.evaluate({
  state: { message: 'I was charged twice.' },
  questions: {
    team: choice('Who should handle this?', {
      billing: 'Payments and refunds',
      support: 'Technical issues',
    }),
    urgency: score('How urgent?', ['Routine', 'Soon', 'Immediate']),
    refund: booleanQuestion('Does the user request a refund?'),
  },
});

result.answers.team.choice;         // 'billing' | 'support'
result.answers.urgency.score;       // number, starting at 0
result.answers.refund.probability;  // P(true), from 0 to 1

Understand typed answers

choice() preserves literal option types, score() returns a number that can be fractional, and booleanQuestion() returns a probability, not a boolean. The native protocol names boolean questions noul; the SDK maps the answer to probability. See Decision primitives.

SDK 0.6.0 accepts a string, object, or array as State. Its validation is stricter than the hosted native HTTP API: do not assume every nullable native input can be sent through this SDK. For original HTTP JSON, response headers, or exact decimal values, see the API reference.

Control requests

Use timeoutMs, maxRetries, and the call option signal to control request budgets, retries, and cancellation. The example disables automatic retries. The SDK does not generate idempotency keys automatically. When using hosted API, follow Idempotency and retries and check request records before repeating an uncertain result.

See the SDK source and README for error types, adapters, and release details.