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

# Decision models

> Get typed answers with probabilities about text and JSON, billed on input tokens only

A **decision model** answers questions about a piece of context with probabilities instead of generated text. You send the context, called the **state**, and a set of named questions. Each answer comes back as a probability, one of your options or a score, so you can route, classify and triage without parsing a chat model's output.

Decision models use the **System One API**, not the OpenAI API. A client written for another System One host only needs our base URL, a Lyceum API key and one of the model IDs below.

## Models

| Model ID | Model |
| - | - |
| `cloudflare/clef` | Clef |
| `cloudflare/clef-flash` | Clef Flash, the smaller and cheaper model |

Try both on a few of your own labelled examples and keep the cheaper one if its answers are good enough.

## Endpoint and authentication

```http theme={null}
POST https://api.lyceum.technology/v1/systemone
```

Authenticate with your Lyceum API key (`lk_...`) as a Bearer token, the same key you use for chat.

> [!NOTE]
>
> The endpoint isn't under `/openai/v1`. If your app already uses `https://api.lyceum.technology/openai/v1` for chat, send decisions to `https://api.lyceum.technology/v1/systemone` instead. The OpenAI SDKs have no System One client, so send a plain HTTP request.

## Quickstart

> [tab] Python
>
> ```python theme={null}
> import requests
>
> resp = requests.post(
>     "https://api.lyceum.technology/v1/systemone",
>     headers={"Authorization": "Bearer lk_..."},
>     json={
>         "model": "cloudflare/clef",
>         "state": "Hi, I was charged twice for my October invoice. Can you refund one of them?",
>         "questions": {
>             "is_billing": {
>                 "type": "noul",
>                 "instructions": "Is this message about billing or payments?",
>             },
>         },
>     },
>     timeout=60,
> )
> resp.raise_for_status()
> print(resp.json()["answers"]["is_billing"]["noul"])
> ```

> [tab] curl
>
> ```bash theme={null}
> curl https://api.lyceum.technology/v1/systemone \
>   -H "Authorization: Bearer lk_..." \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "cloudflare/clef",
>     "state": "Hi, I was charged twice for my October invoice. Can you refund one of them?",
>     "questions": {
>       "is_billing": {
>         "type": "noul",
>         "instructions": "Is this message about billing or payments?"
>       }
>     }
>   }'
> ```

The response has exactly three fields: the model, the answers keyed by your question names, and the token usage:

```json theme={null}
{
  "model": "cloudflare/clef",
  "answers": {
    "is_billing": {"type": "noul", "noul": 0.9916}
  },
  "usage": {"input_tokens": 163, "output_tokens": 0}
}
```

There's no streaming. Each request returns one JSON object.

## Request fields

| Field | Required | Description |
| - | - | - |
| `model` | Yes | A decision model ID from the [table above](#models). |
| `state` | Yes | The context the questions are about: a string, a JSON object or an array. A JSON record can go in as it is. |
| `questions` | Yes | An object of 1 to 32 questions. The key is the question's name, and the answer comes back under the same name. |

Every question has a `type` and `instructions`, the question itself in plain words. Give every question non-empty `instructions`.

## Question types

| Type | Use it for | `criteria` | Answer |
| - | - | - | - |
| `noul` | A yes or no question | Optional: an object with a `true` and a `false` key, each describing when that answer applies | `noul`: the probability that the answer is yes, from 0 to 1 |
| `choice` | Picking one of several categories that have no order | Required: an object of 2 to 255 options, label as key and description as value | `choice`: the picked label, `probabilities` per label (they add up to 1) and `confidence` |
| `score` | Rating on an ordered scale | Required: an array of 2 to 10 levels, lowest first | `score`: the probability-weighted mean of the level positions, `probabilities` per position, `confidence` and a `legend` that maps positions to your levels |

A `score` answer can be a decimal. With 3 levels it lies between 0 and 2: probabilities of 0.1, 0.7 and 0.2 give a score of 1.1.

## Ask several questions at once

All questions in a request are about the same state, so you pay for the state once. This example sends a JSON record and asks one question of each type:

```python theme={null}
resp = requests.post(
    "https://api.lyceum.technology/v1/systemone",
    headers={"Authorization": "Bearer lk_..."},
    json={
        "model": "cloudflare/clef",
        "state": {
            "ticket": "Our whole team is locked out since this morning and the invoice run is due today.",
            "customer": {"plan": "business", "seats": 40},
        },
        "questions": {
            "is_billing": {
                "type": "noul",
                "instructions": "Is the customer asking about a charge, a refund or an invoice?",
            },
            "team": {
                "type": "choice",
                "instructions": "Which team should handle this ticket?",
                "criteria": {
                    "billing": "Charges, refunds, invoices and plan changes",
                    "access": "Login, SSO, roles and locked accounts",
                    "other": "Anything that fits none of the teams above",
                },
            },
            "urgency": {
                "type": "score",
                "instructions": "How urgent is this ticket?",
                "criteria": ["Can wait a week", "Needs an answer this week", "Needs an answer today"],
            },
        },
    },
    timeout=60,
)
print(resp.json()["answers"])
```

The answers come back under the question names. Values are shortened to 4 decimals here:

```json theme={null}
{
  "is_billing": {"type": "noul", "noul": 0.2031},
  "team": {
    "type": "choice",
    "choice": "access",
    "probabilities": {"access": 0.9694, "billing": 0.0152, "other": 0.0154},
    "confidence": 0.9541
  },
  "urgency": {
    "type": "score",
    "score": 1.8724,
    "probabilities": {"0": 0.0285, "1": 0.0706, "2": 0.9009},
    "confidence": 0.8086,
    "legend": {"0": "Can wait a week", "1": "Needs an answer this week", "2": "Needs an answer today"}
  }
}
```

## Use the answers

* **Set thresholds from your own data.** Run a set of labelled examples and pick the `noul` cut-off where the cost of a wrong yes and a wrong no balance for your use case. A spam filter and a fraud alert need different cut-offs.
* **Act on `confidence`.** Send answers with low confidence to a person or a fallback path, and act automatically on the rest.
* **Read the full distribution when it matters.** Two close `probabilities` tell you the state fits both options, which a single label hides.

## Write good questions

* Ask about something the state shows, such as "Does the message mention a refund?", rather than something the model has to guess.
* Give options and levels labels that don't overlap, and describe each one in its value.
* Add a fallback option such as `other` to every `choice` question, so a state that fits no option has somewhere to go.
* Name questions with letters, digits, `.`, `_` and `-` only.

## Limits

| Limit | Value |
| - | - |
| Questions per request | 1 to 32 |
| Question names | 1 to 100 characters |
| `choice` options | 2 to 255, with labels of up to 128 characters |
| `score` levels | 2 to 10 |
| Request body | Up to 12,000 bytes, about 3,000 tokens of English text |

A request over a limit gets a `413` or `422` error, see [Errors](#errors).

## Pricing

Decision models bill **input tokens only**: the `usage.input_tokens` of each response. Output tokens are free, and a request that ends in an error isn't billed. Your organization needs credit, the same as for chat.

| Model | USD per 1M input tokens | EUR per 1M input tokens |
| - | - | - |
| `cloudflare/clef` | \$0.29 | €0.25 |
| `cloudflare/clef-flash` | \$0.05 | €0.04 |

## Errors

Errors use this shape:

```json theme={null}
{"error": {"code": "invalid_api_key", "message": "not authenticated", "param": null, "type": "unauthorized_error"}}
```

Branch on `error.code` in the body, not on `message`:

| Status | `code` | Meaning | What to do |
| - | - | - | - |
| 400 | `invalid_json` | The body isn't valid JSON | Fix the request |
| 400, 422 | `invalid_request` | A field is missing or malformed, or the request is over a [limit](#limits). `message` says which | Fix the request |
| 401 | `invalid_api_key` | Missing or invalid API key | Check the key |
| 402 | `insufficient_credits` | Your organization has no credit left | Top up |
| 404 | `unsupported_model` | Unknown model ID | Use an ID from [Models](#models) |
| 413 | `request_too_large` | The request body is too large | Shorten the state |
| 422 | `unsupported_model` | The model exists but isn't a decision model, such as a chat model | Use an ID from [Models](#models) |
| 429 | `rate_limit_exceeded` | Too many requests right now | Retry with backoff |
| 502 | `invalid_provider_response` | The model returned an answer we couldn't use | Retry with backoff |
| 503 | `service_unavailable` | The model is unavailable right now | Retry with backoff |
| 504 | `provider_timeout` | The model took too long to answer | Retry with backoff |

The decision models work only on this endpoint. Sending one to `/openai/v1/chat/completions` returns a `400`.

## Coming from the OpenAI Decisions API

The question types match, but the request and the answers have a different shape:

| OpenAI Decisions API | System One API |
| - | - |
| `POST /v1/decisions` | `POST /v1/systemone` |
| `input` | `state` |
| `questions` is an array, each item with a `name` | `questions` is an object keyed by name |
| `predicate` question, answered with `probability` | `noul` question, answered with `noul` |
| `choices`: an array of `value` and `description` | `criteria`: an object of label and description |
| `levels`: an array of `label` and `description` | `criteria`: an array of levels |
| `answers` is an array | `answers` is an object keyed by question name |

> [card] [Serverless inference](https://docs.lyceum.technology/docs/inference/serverless.md)
>
> Chat and embeddings with the same API key.

> [card] [API keys](https://docs.lyceum.technology/docs/configuration/api-keys.md)
>
> Create the key you send as the Bearer token.


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