# System One

> Ask typed questions about a state and get a calibrated answer to each.

Source: https://codiv.ai/docs/api-reference/system-one

## Create a decision

Endpoint:


```text
POST https://api.codiv.ai/v1/systemone
```

Evaluates every question against the state and returns one answer per question. Authenticate with `Authorization: Bearer <key>`.

### Request body

- `state` (string, object or array, required)

  What the questions are about. Objects and arrays are sent to the model as JSON.

- `model` (string, required)

  The model to use: `openjev-latest`, or any id from [List models](https://codiv.ai/docs/api-reference/models.md). `jev-latest` is accepted as an alias.

- `questions` (map of question objects, required)

  Question id → question. At least one question is required. Ids key the answers in the response and are never shown to the model.

  Question object properties:

  - `type` ("noul", "choice" or "score", required)

    The question type. See [Writing questions](https://codiv.ai/docs/guides/questions.md).

  - `instructions` (string, object or array, optional)

    What to decide about the state.

  - `criteria` (object or array)

    - **noul** (optional): `{"true": description, "false": description}`.
    - **choice** (required): `{option: description or null}`, with 1 to 128 options.
    - **score** (required): `[level, …]`, 2 to 10 levels ordered from lowest to highest.

### Returns

A [response object](#response). The `x-typesafe-request-id` header identifies the request; include it when you report a problem.

curl:

```bash
curl https://api.codiv.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openjev-latest",
    "state": "Hi, my Stripe connection keeps failing with a 403 and we launch tomorrow.",
    "questions": {
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this",
        "criteria": {
          "billing": "Payment or subscription issues",
          "technical": "Bugs or integration problems",
          "sales": "Pricing or account questions"
        }
      },
      "frustration": {
        "type": "score",
        "instructions": "How frustrated the customer appears",
        "criteria": ["Calm, just stating facts", "Frustrated but civil", "Very angry, strong language"]
      },
      "is_urgent": {"type": "noul", "instructions": "The message conveys urgency"}
    }
  }'
```

Python:

```python
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

# Reads TYPESAFE_API_KEY and TYPESAFE_BASE_URL=https://api.codiv.ai
client = TypeSafeClient()

response = client.system_one(
    "Hi, my Stripe connection keeps failing with a 403 and we launch tomorrow.",
    {
        "department": Choice(
            instructions="Which team should handle this",
            criteria={
                "billing": "Payment or subscription issues",
                "technical": "Bugs or integration problems",
                "sales": "Pricing or account questions",
            },
        ),
        "frustration": Score(
            instructions="How frustrated the customer appears",
            criteria=["Calm, just stating facts", "Frustrated but civil", "Very angry, strong language"],
        ),
        "is_urgent": Noul(instructions="The message conveys urgency"),
    },
    model="openjev-latest",
)

print(response.choices["department"].choice)   # "technical"
print(response.scores["frustration"].score)     # 1.0
print(response.nouls["is_urgent"].noul)        # 1.0
```

TypeScript:

```ts
import { TypeSafeClient, choice, noul, score } from "@typesafe-ai/sdk";

// Reads TYPESAFE_API_KEY; baseURL can also come from TYPESAFE_BASE_URL
const client = new TypeSafeClient({ baseURL: "https://api.codiv.ai" });

const response = await client.systemOne({
  model: "openjev-latest",
  state: "Hi, my Stripe connection keeps failing with a 403 and we launch tomorrow.",
  questions: {
    department: choice("Which team should handle this", {
      billing: "Payment or subscription issues",
      technical: "Bugs or integration problems",
      sales: "Pricing or account questions",
    }),
    frustration: score("How frustrated the customer appears", [
      "Calm, just stating facts",
      "Frustrated but civil",
      "Very angry, strong language",
    ]),
    is_urgent: noul("The message conveys urgency"),
  },
});

console.log(response.answers.department.choice); // "technical"
```

Response:

```json
{
  "model": "openjev-0.1",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "probabilities": {"billing": 0.0, "technical": 1.0, "sales": 0.0},
      "confidence": 1.0
    },
    "frustration": {
      "type": "score",
      "score": 1.0,
      "legend": {"0": "Calm, just stating facts", "1": "Frustrated but civil", "2": "Very angry, strong language"},
      "probabilities": {"0": 0.0, "1": 1.0, "2": 0.0},
      "confidence": 0.97
    },
    "is_urgent": {"type": "noul", "noul": 1.0}
  },
  "usage": {"input_tokens": 175, "output_tokens": 0}
}
```

## The response object

- `model` (string)

  The exact model version that answered, for example `openjev-0.1`.

- `answers` (map of answer objects)

  Answers keyed by your question ids. Every answer has a `type` matching its question.

  noul answer:

  - `noul` (number)

    Probability of yes, between 0 and 1.

  choice answer:

  - `choice` (string)

    The most likely option.

  - `probabilities` (map of number)

    The probability of every option. The values sum to 1.

  - `confidence` (number)

    `1 − H(p)/ln K`: 1 when certain and 0 when uniform. See [Probabilities & confidence](https://codiv.ai/docs/guides/confidence.md).

  score answer:

  - `score` (number)

    The expected level, `Σ i·pᵢ`, with levels numbered from 0.

  - `legend` (map of string)

    Your levels, keyed `"0"`, `"1"`, and so on.

  - `probabilities` (map of number)

    The probability of each level, keyed like `legend`.

  - `confidence` (number)

    As for choice.

- `usage` (object)

  `input_tokens` is what counts against your quota. `output_tokens` is always 0.

Answer objects:

```json
{"type": "noul", "noul": 0.93}

{"type": "choice", "choice": "bug",
 "probabilities": {"billing": 0.04, "bug": 0.95, "other": 0.01},
 "confidence": 0.81}

{"type": "score", "score": 1.62,
 "legend": {"0": "negative", "1": "neutral", "2": "positive"},
 "probabilities": {"0": 0.03, "1": 0.32, "2": 0.65},
 "confidence": 0.62}
```