Write the decision once. Run it on any System One provider.
system-one is a small, provider-neutral TypeScript runtime for bounded AI decisions.
Use TypeSafe Jev today, Reflex locally, any compatible /v1/systemone endpoint, or your own SystemOneProvider tomorrow. Your application keeps the same choice, noul, and score code.
System One is the abstraction. Providers are implementation details.
Website · Pi integration · Pi-Bifrost
System One is already becoming an ecosystem.
Different implementations can make the same kind of bounded decision:
+-- TypeSafe Jev
+-- Reflex
application / agent ---> |-- compatible /v1/systemone endpoint
+-- custom SystemOneProvider
Your application should not have to couple itself to whichever provider it starts with.
system-one gives the application a stable boundary:
SystemOneProvider
|
v
SystemOne
/ | \
choice noul score
|
v
application / agent / router
Change the provider. Keep the decision code.
system-one owns the mechanism:
- a provider-neutral
SystemOneProviderinterface - one
SystemOneclient - typed
choice,noul, andscorebuilders - heterogeneous questions over shared state
- HTTP support for compatible
/v1/systemoneendpoints - strict, fail-closed protocol validation
- deterministic mock providers for tests
It deliberately does not own policy:
- no routing strategy
- no model tiers
- no confidence thresholds
- no automatic escalation
- no hidden retries or fallback behavior
Those decisions belong to the application.
For example, Pi-Bifrost consumes system-one-core for routing, but routing is not part of the core runtime.
Jev-focused libraries make Jev easier to use.
system-onemakes the underlying System One provider replaceable.
| Package | npm | What it is |
|---|---|---|
system-one-core |
system-one-core |
Provider-neutral runtime: SystemOneProvider, SystemOne, typed builders, compatible HTTP provider, strict validation, and deterministic test support |
pi-system-one |
pi-system-one |
Pi extension exposing one system_one tool for batched choice, noul, and score decisions |
Dependency direction stays one-way:
system-one-core
^
|
pi-system-one
Pi-Bifrost is a separate consumer:
system-one-core
^ ^
| |
pi-system-one pi-bifrost
Nothing in system-one-core depends on Pi, routing, Bifrost, or a specific model vendor.
Tested against jev-latest (resolved jev-1.13.0):
- live contract tests
- golden fixtures
- end-to-end Pi agent run
Tested locally with Qwen3.5-2B:
- live contract tests
- golden fixtures
- end-to-end Pi agent run
Same client. Same provider class. Only configuration changes.
Compatibility with other
/v1/systemoneimplementations is protocol-level unless explicitly listed here as tested.
Install the core runtime:
npm install system-one-coreCreate the questions once:
import {
SystemOne,
HttpSystemOneProvider,
choice,
noul,
score,
} from "system-one-core";
const provider = new HttpSystemOneProvider({
baseUrl: "http://localhost:8008",
});
const systemOne = new SystemOne({ provider });
const result = await systemOne.evaluate({
state: "The export button crashes in Safari.",
questions: {
team: choice("Which team should investigate?", {
frontend: null,
backend: null,
}),
browserSpecific: noul("Is this bug browser specific?"),
severity: score("How severe is the impact?", [
"minor",
"degraded",
"blocking",
]),
},
});
console.log(result.answers);That example can use Reflex locally.
To use TypeSafe Jev, keep the evaluation code and change the provider configuration:
const provider = new HttpSystemOneProvider({
baseUrl: "https://api.typesafe.ai",
apiKey: process.env.TYPESAFE_API_KEY,
defaultModel: "jev-latest",
});The rest of the application stays the same.
HTTP is only one provider implementation.
Anything can implement the boundary:
interface SystemOneProvider {
evaluate(request: SystemOneRequest): Promise<SystemOneResponse>;
}That means the runtime can sit in front of:
- a hosted System One service
- a local model server
- a compatible
/v1/systemoneendpoint - an in-process implementation
- a deterministic test double
The runtime normalizes the boundary. It does not decide which provider is "best" for your application.
Install the Pi extension:
pi install npm:pi-system-onePoint it at a local compatible provider:
export SYSTEM_ONE_BASE_URL=http://localhost:8008Or configure TypeSafe Jev:
export SYSTEM_ONE_BASE_URL=https://api.typesafe.ai
export SYSTEM_ONE_API_KEY=YOUR_KEY
export SYSTEM_ONE_MODEL=jev-latestpi-system-one registers one system_one tool and exposes the same bounded decision surface to the agent.
Source: pi-system-one
You can.
If your application is intentionally tied to one provider, the provider's SDK may be the simplest option.
system-one becomes useful when you want this dependency direction:
your application
|
v
SystemOneProvider
|
+-- Jev
+-- Reflex
+-- compatible endpoint
+-- custom implementation
instead of:
your application
|
v
specific provider SDK
The goal is not to hide System One. The goal is to make its implementation replaceable.
Provider-neutral
Application code depends on the System One primitive, not a vendor.
Protocol-first
Compatible /v1/systemone implementations can sit behind the same HTTP provider.
Typed
Question builders infer the answer shape they produce.
Policy-free
Thresholds, escalation, routing, retries, and fallback stay outside the core.
Fail-closed
Malformed provider responses are rejected instead of being silently normalized into something plausible.
Testable
Deterministic providers make bounded-decision code testable without a live model.
npm install # workspaces
npm test # all unit tests
npm run typecheckLive contract tests are skipped by default.
TypeSafe:
SYSTEM_ONE_TEST_TYPESAFE=1
TYPESAFE_API_KEY=...Reflex:
SYSTEM_ONE_TEST_REFLEX=1
# local Reflex server on :8008- system-one website
- pi-system-one
- pi-bifrost - model routing for Pi; consumes
system-one-core - TypeSafe JavaScript SDK - official TypeSafe API SDK
- Reflex - open/local Jev / System One recreation
A small provider-neutral TypeScript runtime for System One: write the decision once, then run it on Jev, Reflex, compatible endpoints, or your own provider.