# Decisions

Scribase Decisions is a typed AI judgment primitive, meant to sit next to
Postgres, Auth, Storage, Email and MCP in a Scribase-backed app: ask a
question, get back a **Choice** (one of a fixed set of labels), a **Score**
(a calibrated 0-1 probability or number), or a **Noul** (open-ended) answer —
a type your code branches on, not a string you parse.

It is built on **OpenJev** (`caelum0x/openjev`, Apache-2.0), an independent
open-source fork of TypeSafe AI's **Jev** ("System One") engine and SDKs. The
wire contract (`POST /v1/systemone`) is **Jev-compatible** — unchanged from
TypeSafe's own API — so the same client code runs against either backend.
OpenJev is maintained by the Scribase team; it is not a TypeSafe product, and
Scribase did not build Jev itself.

There is no hosted `api.scribase.com` Decisions endpoint yet. Today this page
documents two paths that both work against the real OpenJev engine right now:
self-hosting the engine, or pointing an SDK at a hosted Jev-compatible API
key. A first-party hosted endpoint is tracked on the
[Roadmap](https://scribase.com/roadmap).

## Question types

| Type | Shape | Example use |
|---|---|---|
| `Choice` | One label from a fixed set | "What is this support ticket about?" → `billing` \| `technical` \| `other` |
| `Score` | A calibrated 0-1 probability or number | "How likely is this transaction fraud?" → `0.82` |
| `Noul` | Open-ended text | "Summarize this ticket in one sentence" |

## Install an SDK

Three packages ship from `caelum0x/openjev`, all speaking the same contract
(checked 2026-11-11):

| Package | Ecosystem | Version | License |
|---|---|---|---|
| `@openjev/sdk` | npm | 0.6.1 | MIT |
| `@openjev/lite` | npm | 0.2.1 | MIT |
| `openjev-client` (imports as `openjev`) | PyPI | 0.7.2 | MIT |

```sh
npm install @openjev/sdk
# or
pip install openjev-client
```

## Quickstart — self-hosted (no API key)

Clone and run the engine. No API key is required unless you configure one:

```sh
git clone https://github.com/caelum0x/openjev
cd openjev && npm install
npm run dev   # serves POST /v1/systemone on :8080
```

```ts
import { choice, OpenJevClient } from "@openjev/sdk";

const client = new OpenJevClient(); // defaults to http://localhost:8080

const response = await client.systemOne({
  state: { document: "I was charged twice. Please fix this ASAP." },
  questions: {
    category: choice("What is this support ticket about?", {
      billing: null,
      technical: null,
      other: null,
    }),
  },
});

console.log(response.answers.category.choice); // "billing"
```

```python
from openjev import Choice, TypeSafeClient

with TypeSafeClient() as client:  # defaults to http://localhost:8080
    response = client.system_one(
        state={"document": "I was charged twice. Please fix this ASAP."},
        questions={"category": Choice("What is this support ticket about?", ["billing", "technical", "other"])},
    )
    print(response.answers["category"].choice)
```

## Quickstart — hosted Jev-compatible key

Instead of self-hosting, point the same SDK at a hosted Jev-compatible
endpoint and API key (for example, TypeSafe AI's own hosted API):

```sh
OPENJEV_BASE_URL=https://api.typesafe.ai/v1
OPENJEV_API_KEY=jev_...
```

```ts
const client = new OpenJevClient({
  baseUrl: "https://api.typesafe.ai/v1",
  apiKey: process.env.OPENJEV_API_KEY,
});
```

No code changes beyond configuration — the request and response shapes are
identical either way.

## What's in the box

- Calibration fitting, drift detection, eval import and a gold-set test
  harness (`npm run gold`) ship in the engine, so a `Score` answer is checked
  against real outcomes.
- Cookbooks (worked examples for common judgment tasks) live in the
  repository under `skills/` and `otsone/`.
- Apache-2.0: the full engine, cookbooks and SDKs are public source.

## Honest status

- **Self-hosting**: works today against the real, public `caelum0x/openjev`
  repository.
- **Hosted Jev-compatible key**: works today against any endpoint that speaks
  the same `/v1/systemone` contract (for example TypeSafe AI's hosted API).
  Scribase does not yet operate its own hosted Decisions endpoint.
- **A first-party `api.scribase.com/v1/decisions` endpoint**: not built yet.
  See the Roadmap and the design note in the Scribase control-api plan.

See also: [Scribase Decisions on scribase.com](https://scribase.com/decisions).