opendunes
Embeddings, rerank, classification
Copy page ▾

Typed answers

POST /v1/systemone sends a case and your typed questions to a System One model, and answers each question, under the name you gave it, with a score.

Request

Send it with an API keyAPI keyThe key you create and send with every request that calls a model.More on API keys →. The route takes the same case, questions and answers as Decisions, on the same meter, and a model's bare name as well as its lab/model ID. A chat library cannot call it: send it with any HTTP client. The Classification guide walks through a first call.

Yacine runs Souk Bot, which answers the customers of a clothing shop in Oran. Before a message reaches a person, Souk Bot asks System One two questions about it: is it a defect, and which team owns it.

FieldNeededYou send
modelyesa System One model, lab/model, or its bare name, such as jev-1.13 for typesafe/jev-1.13
stateyesthe case to judge: a string, an object or a list
questionsyesone or more questions, each under a name you choose
providernowhich providers may serve it: only and order name them, sort ranks them by price, throughput or latency, and max_price caps the price the router may pick, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →
session_idnoyour own id grouping related requests, never sent to the model
usernoyour own id for the person behind the request, never sent to the model
tracenoyour own tracing fields, never sent to the model

Each question:

FieldNeededYou send
typeyesnoul for yes or no, choice for one of your criteria, score for a place on your scale
instructionsyesthe question, in words
criteriayes for choice and scorenoul: what true and false mean · choice: one entry per option, keyed by its name · score: the levels of your scale, lowest first
import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/systemone"
MODEL = "typesafe/jev-1.13"
TICKET = "Edahabia payment went through. Order still pending since yesterday."

request_body = {
    "model": MODEL,
    "state": {"ticket": TICKET},
    "questions": {
        "is_bug": {
            "type": "noul",
            "instructions": "Is the customer reporting a defect?",
            "criteria": {
                "true": "The customer describes broken behaviour.",
                "false": "The customer is asking a question.",
            },
        },
        "team": {
            "type": "choice",
            "instructions": "Which team owns this ticket?",
            "criteria": {
                "payments": "Checkout, billing or payment processing.",
                "delivery": "Pickup, transit or hand-over.",
            },
        },
    },
}

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(request_body).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    answer = json.load(response)

print(answer["answers"]["team"]["choice"], answer["usage"]["cost"])

Response

One answer per question, under the name you gave it. The type you sent decides its fields: a choice never carries a score, and a score never carries a choice.

FieldHolds
idthe receipt handle, read back with GET /v1/generation
modelthe model that served it, lab/model with its dated version
providerthe provider that served it
answersone answer per question, keyed by the names you sent
typethe question's type, as you sent it
noulon a noul answer: the probability of yes, from 0 to 1
choiceon a choice answer: the criterion the model picked, the one with the most weight
scoreon a score answer: your scale's weighted position, each level's place times its probability, added up
probabilitieson a choice or a score answer: one entry per criterion or level, keyed by its name or its place from 0; they add up to 1
confidenceon a choice or a score answer: how sure the model is of that pick or that position; its own reading, not the winning probability
legendon a score answer: each place spelled back out as your level
usagewhat was counted, and the charge
input_tokensthe case and every question, instruction and criterion, counted together
output_tokensthe answer's tokens, reported and never charged
costthe charge, in DA

Two headers ride the answer: X-Generation-Id, the receipt handle, and X-Balance-Available, your balanceBalanceWhat you can spend, in DA.More on Balance and charges → after this charge, in µDAµDAA millionth of a DA: 1 DA = 1 000 000 µDA.More on Balance and charges →.

What it cost

Charged in DA from your balance the moment the answer ends: the tokens you sent, usage.input_tokens, at the model's input rate. usage.output_tokens is reported and never charged. usage.cost carries the charge; the model's rate is on the model's page.

Nothing is charged when the provider fails before it answers, or when a question is refused.

Errors

error.code carries the status, and error.message says why.

StatusWhen
400model, state or questions is missing, or a question has no type, or no criteria where its type needs them
401the key is missing, wrong, disabled or expired
402your balance is at zero or below, cannot pay the request's hold, or the key's cap is spent; error.metadata.limit_source names which, and deposit_url or key_url says where to lift it. After up to 60 seconds of waiting for money your running requests hold, the 402 carries Retry-After: 60
403the key is kept to other models or other addresses, a guardrail's budget is spent, or a guardrail or a filter blocked the request
404model is not a System One or classification model on sale
408 · 504the provider did not answer in time
413the body is too large
429the provider is limiting its rate; Retry-After says how many seconds to wait
500an unexpected error
502the model is down, or answered with nothing usable
503no provider meets the provider routing you asked for

Last modified on