Create Decision

POST /v1/systemone Models: Decisions View .md

Answer typed questions about a state with a decision ("System One") model, in TypeSafe's /v1/systemone shape, so clients written for TypeSafe work by changing their base URL and key.

A decision model generates no text: each answer is a probability distribution over the question's allowed answers. The served models, clef and clef-flash, read the state and every question in one pass and score all the answers at once.

Question types: noul (yes/no) answers noul, the probability of yes. choice picks one of 1 to 255 options and answers the most likely choice, every option's probabilities and a confidence. score rates on 1 to 10 ordered levels and answers score, the probability-weighted level (it can land between levels), with a legend, probabilities and confidence.

Confidence is 1 when the distribution is on one answer and 0 when it is spread evenly: (k * p_max - 1) / (k - 1) for k answers. noul answers carry none; read noul itself.

Long inputs over the model's maximum input length are rejected with 422, never truncated.

Billing: the tokens the model read are billed as input tokens. clef and clef-flash read the request once, so the state is billed once however many questions ask about it. No output tokens are billed.

Images: send them in assets with the TypeSafe-Danger-Zone-Images: true header, inline as base64 or as the multipart form TypeSafe's SDKs send (a part named request with the JSON body, then a part per image). TypeSafe calls images experimental. A model reads images when GET /v1/models lists image among its input_modalities, and at most as many per request as that input's supported_inputs.references.max says (8 for clef-flash).

Compression: a body may be sent compressed with Content-Encoding: zstd or gzip (one layer; a zstd window of at most 8 MiB), as TypeSafe's SDKs send bodies of 1 KiB or more. A body may be at most 32 MB, compressed and decompressed.

Header parameters

Content-Encoding string

The body's compression, if any. One of zstd, gzip or x-gzip; no stacked encodings.

zstdgzipx-gzipidentity
TypeSafe-Danger-Zone-Images string

true to send images in assets, as TypeSafe requires; a request with assets without it is a 400.

true

Body

application/json

TypeSafe's /v1/systemone request. A request with images also sends assets and the TypeSafe-Danger-Zone-Images: true header, and goes to a model that reads images (its input_modalities in GET /v1/models list image).

model string required

The decision model to use.
state string or object or array of any required

What to decide about. A string, or structured data (an object or array), which the model reads as JSON.
One of 3
- string
- object
- array of any
questions object required

Up to 64 questions, by id. Each answer comes back under its question's id.
assets object

Images, keyed by a reference of your choosing (a per-image UUID is a good one; at most 1,024 bytes, and 65,536 for all of them). Write the reference into state, a question's instructions or its criteria where the image belongs: a string that is exactly the reference is the image, and inside longer strings references are found left to right without overlap. Object keys are never read. Every asset must be referenced.

The model reads the images in the order their references first appear, and sees each reference as [image N], N that place. The images count toward the model's input and are billed as input tokens. The images together may be at most 32 MiB, and so may the expanded request: the state and questions with each image counted at every place it is referenced. assets itself is not counted, so an image sent inline in base64 counts the same as one sent as a multipart part.

A model reads at most a set number of images per request, its image input's supported_inputs.references.max in GET /v1/models (8 for clef-flash); a request with more is refused with 400.

Body

multipart/form-data

Fields as multipart/form-data

request object required

TypeSafe's /v1/systemone request. A request with images also sends assets and the TypeSafe-Danger-Zone-Images: true header, and goes to a model that reads images (its input_modalities in GET /v1/models list image).
4 fields
- model string required
  
  The decision model to use.
- state string or object or array of any required
  
  What to decide about. A string, or structured data (an object or array), which the model reads as JSON.
  One of 3
  - string
  - object
  - array of any
- questions object required
  
  Up to 64 questions, by id. Each answer comes back under its question's id.
- assets object
  
  Images, keyed by a reference of your choosing (a per-image UUID is a good one; at most 1,024 bytes, and 65,536 for all of them). Write the reference into state, a question's instructions or its criteria where the image belongs: a string that is exactly the reference is the image, and inside longer strings references are found left to right without overlap. Object keys are never read. Every asset must be referenced.
  
  The model reads the images in the order their references first appear, and sees each reference as [image N], N that place. The images count toward the model's input and are billed as input tokens. The images together may be at most 32 MiB, and so may the expanded request: the state and questions with each image counted at every place it is referenced. assets itself is not counted, so an image sent inline in base64 counts the same as one sent as a multipart part.
  
  A model reads at most a set number of images per request, its image input's supported_inputs.references.max in GET /v1/models (8 for clef-flash); a request with more is refused with 400.

Responses

application/json · systemone-response-payload

3 fields

model string required
answers object required

One answer per question, by question id.
usage object required
2 fields
- input_tokens integer
  
  The tokens the model read, the billed count.
- output_tokens integer
  
  Always 0.

curl https://api.vultrinference.com/v1/systemone \
  -H "Authorization: Bearer $VULTR_INFERENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "clef",
    "state": {
      "ticket": "Everything is down and we have a demo at noon."
    },
    "questions": {
      "urgent": {
        "type": "noul",
        "instructions": "Does the customer need a reply within the hour?"
      },
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {
          "billing": "invoices, payments, refunds",
          "technical": "bugs, outages, errors"
        }
      },
      "frustration": {
        "type": "score",
        "instructions": "How frustrated is the customer?",
        "criteria": [
          "Calm",
          "Frustrated",
          "Very angry"
        ]
      }
    }
  }'

import os
import requests

response = requests.post(
    "https://api.vultrinference.com/v1/systemone",
    headers={"Authorization": f"Bearer {os.environ['VULTR_INFERENCE_API_KEY']}"},
    json={
        "model": "clef",
        "state": {
            "ticket": "Everything is down and we have a demo at noon.",
        },
        "questions": {
            "urgent": {
                "type": "noul",
                "instructions": "Does the customer need a reply within the hour?",
            },
            "department": {
                "type": "choice",
                "instructions": "Which team should handle this?",
                "criteria": {
                    "billing": "invoices, payments, refunds",
                    "technical": "bugs, outages, errors",
                },
            },
            "frustration": {
                "type": "score",
                "instructions": "How frustrated is the customer?",
                "criteria": [
                    "Calm",
                    "Frustrated",
                    "Very angry",
                ],
            },
        },
    },
)
print(response.json())

const response = await fetch("https://api.vultrinference.com/v1/systemone", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VULTR_INFERENCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "clef",
    "state": {
      "ticket": "Everything is down and we have a demo at noon."
    },
    "questions": {
      "urgent": {
        "type": "noul",
        "instructions": "Does the customer need a reply within the hour?"
      },
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {
          "billing": "invoices, payments, refunds",
          "technical": "bugs, outages, errors"
        }
      },
      "frustration": {
        "type": "score",
        "instructions": "How frustrated is the customer?",
        "criteria": [
          "Calm",
          "Frustrated",
          "Very angry"
        ]
      }
    }
  }),
});
console.log(await response.json());

Response · 200

{
    "model": "string",
    "answers": {},
    "usage": {
        "input_tokens": 0,
        "output_tokens": 0
    }
}