> ## Documentation Index
> Fetch the complete documentation index at: https://docs.redpill.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# System One

> Ask a model typed questions about a state and get structured decisions.

System One models answer typed questions about a piece of content instead of generating text. Each
answer is a calibrated probability, a choice among options, or a level on a scale, so software can
act on it directly. The endpoint follows the TypeSafe System One protocol, so the official TypeSafe
SDKs work with RedPill by changing the base URL.

System One models list `decisions` in `output_modalities` in [`GET /v1/models`](https://docs.redpill.ai/api-reference/models).
They do not serve chat: a chat completion request to one returns `404 model_not_found`. Responses are
never streamed.

```bash theme={null}
POST https://api.redpill.ai/v1/systemone
```

## Request body

**model** `string` *required*

Id of a model whose `output_modalities` include `decisions`, for example `jaredpalmer/kev-4b`.

**state** `string | object | array` *required*

The content the questions are about: a message, a document, or any JSON value.

**questions** `object` *required*

Questions keyed by an id you choose. Each answer is returned under the same id. Every question
has a `type` and usually `instructions` that state the question.

**question types**

**noul** `object`

A yes/no question. `criteria` optionally describes what `true` and `false` mean.

```json theme={null}
{ "type": "noul", "instructions": "Is this about billing?" }
```

**choice** `object`

Pick one option. `criteria` maps each option to a description, or to `null`.

```json theme={null}
{
  "type": "choice",
  "instructions": "What is the tone?",
  "criteria": { "calm": null, "upset": null }
}
```

**score** `object`

Rate on an ordered scale. `criteria` lists the levels from lowest to highest.

```json theme={null}
{
  "type": "score",
  "instructions": "How urgent is it?",
  "criteria": ["low", "medium", "high"]
}
```

**provider** `object`

The same `provider` routing block as chat completions. It is used for routing and is not sent to
the upstream.

Other fields are not forwarded.

## Example

```bash cURL theme={null}
curl https://api.redpill.ai/v1/systemone \
  -H "Authorization: Bearer $REDPILL_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jaredpalmer/kev-4b",
    "state": "I was charged twice this month. Please fix it today.",
    "questions": {
      "billing": { "type": "noul", "instructions": "Is this about billing?" },
      "tone": {
        "type": "choice",
        "instructions": "What is the tone?",
        "criteria": { "calm": null, "upset": null }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is it?",
        "criteria": ["low", "medium", "high"]
      }
    }
  }'
```

```python Python theme={null}
import os
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient(
    api_key=os.environ["REDPILL_AI_API_KEY"],
    base_url="https://api.redpill.ai",
    model="jaredpalmer/kev-4b",
)

result = client.system_one(
    state="I was charged twice this month. Please fix it today.",
    questions={
        "billing": Noul(instructions="Is this about billing?"),
        "tone": Choice(instructions="What is the tone?", criteria={"calm": None, "upset": None}),
        "urgency": Score(instructions="How urgent is it?", criteria=["low", "medium", "high"]),
    },
)
print(result.nouls["billing"].noul, result.choices["tone"].choice, result.scores["urgency"].score)
```

```javascript JavaScript theme={null}
import { TypeSafeClient, choice, noul, score } from "@typesafe-ai/sdk";

const client = new TypeSafeClient({
  baseURL: "https://api.redpill.ai",
  apiKey: process.env.REDPILL_AI_API_KEY,
});

const result = await client.systemOne({
  model: "jaredpalmer/kev-4b",
  state: "I was charged twice this month. Please fix it today.",
  questions: {
    billing: noul("Is this about billing?"),
    tone: choice("What is the tone?", { calm: null, upset: null }),
    urgency: score("How urgent is it?", ["low", "medium", "high"]),
  },
});
console.log(result.answers.billing.noul, result.answers.tone.choice, result.answers.urgency.score);
```

The SDKs append `/v1/systemone` themselves, so set their base URL to `https://api.redpill.ai`
without `/v1`. Install them with `pip install typesafe-sdk` or `npm install @typesafe-ai/sdk`.

## Response

```json theme={null}
{
  "model": "jaredpalmer/kev-4b",
  "answers": {
    "billing": { "type": "noul", "noul": 0.8828 },
    "tone": {
      "type": "choice",
      "choice": "upset",
      "confidence": 0.4882,
      "probabilities": { "calm": 0.2559, "upset": 0.7441 }
    },
    "urgency": {
      "type": "score",
      "score": 1.4055,
      "legend": { "0": "low", "1": "medium", "2": "high" },
      "probabilities": { "0": 0.1268, "1": 0.3408, "2": 0.5323 },
      "confidence": 0.1083
    }
  },
  "usage": { "input_tokens": 57, "output_tokens": 167, "cost": 0.000002394 }
}
```

**answers** `object`

One answer per question id, in the same type as the question:

* `noul`: `noul` is the probability that the answer is `true`.
* `choice`: `choice` is the most likely option, with `probabilities` per option and a 0 to 1
  `confidence`.
* `score`: `score` is the probability-weighted level index, with `probabilities` per level,
  `legend` mapping each index to its level, and a 0 to 1 `confidence`.

**usage** `object`

`input_tokens`, `output_tokens`, and `cost`, the charge for this request in USD.

The response carries `x-typesafe-request-id`, which the SDKs read, and the gateway's `x-receipt-id`
for [receipt verification](https://docs.redpill.ai/api-reference/receipts.md). Errors use the same error format as the other
endpoints.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.