Quickstart

This page takes about five minutes. You install a client, ask three questions about a support ticket and read the answer. You need an API key from the console. New accounts may start on a waitlist (your account). Until yours is admitted, the playground runs the same requests with no account.

Install a client

pip install sqwishai

npm install sqwishai

The Python client needs Python 3.11 or newer, and the TypeScript client Node 20 or newer. You can also call the API over HTTP, as the cURL tab below does.

Set your key

export SQWISH_API_KEY='onehot_sk_...'

Both clients read the key from SQWISH_API_KEY. Keep it out of source control and out of code that runs in a browser (API keys).

Ask your first questions

One request can ask several questions about the same text, its context. This one asks three questions about a support ticket, one of each decision type:

team: which team should handle it, one of three.
urgent: whether it states a deadline within a day, yes or no.
impact: how badly the customer is affected, on a scale from 0 to 2.

from sqwishai import OneHot

ticket = "Our billing export has failed for two days. We need it for today's audit."
decisions = [
    {"id": "team", "kind": "single", "question": "Which team should handle this ticket?",
     "outcomes": {"billing": "Charges, invoices, and financial exports.",
                  "technical": "Other application failures.",
                  "sales": "New purchases."}},
    {"id": "urgent", "kind": "binary", "question": "Does the ticket state a deadline within one day?",
     "outcomes": {"yes": "An explicit deadline is today or within the next 24 hours.",
                  "no": "The deadline is later, absent, or unclear."}},
    {"id": "impact", "kind": "ordinal",
     "question": "How severe is the reported impact on the customer's work?",
     "outcomes": ["0", "1", "2"],
     "rubric": ["Minor inconvenience; the task can still be completed.",
                "The task is impaired, but a workable alternative is stated.",
                "An important task is blocked and no workable alternative is stated."]},
]

with OneHot() as client:
    result = client.decide(context=ticket, decisions=decisions, model="kettei-core")

print(result["decisions"]["team"]["probabilities"])

import { OneHot, type Decision } from "sqwishai";

const ticket = "Our billing export has failed for two days. We need it for today's audit.";
const decisions: Decision[] = [
  { id: "team", kind: "single", question: "Which team should handle this ticket?",
    outcomes: { billing: "Charges, invoices, and financial exports.",
                technical: "Other application failures.",
                sales: "New purchases." } },
  { id: "urgent", kind: "binary", question: "Does the ticket state a deadline within one day?",
    outcomes: { yes: "An explicit deadline is today or within the next 24 hours.",
                no: "The deadline is later, absent, or unclear." } },
  { id: "impact", kind: "ordinal",
    question: "How severe is the reported impact on the customer's work?",
    outcomes: ["0", "1", "2"],
    rubric: ["Minor inconvenience; the task can still be completed.",
             "The task is impaired, but a workable alternative is stated.",
             "An important task is blocked and no workable alternative is stated."] },
];

const client = new OneHot();
const result = await client.decide({ context: ticket, decisions, model: "kettei-core" });

console.log(result.decisions.team.probabilities);

curl -sS --fail-with-body https://api.sqwish.ai/v1/decide \
  -H "Authorization: Bearer $SQWISH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "kettei-core",
  "context": "Our billing export has failed for two days. We need it for today's audit.",
  "decisions": [
    {"id": "team", "kind": "single", "question": "Which team should handle this ticket?",
     "outcomes": {"billing": "Charges, invoices, and financial exports.",
                  "technical": "Other application failures.",
                  "sales": "New purchases."}},
    {"id": "urgent", "kind": "binary", "question": "Does the ticket state a deadline within one day?",
     "outcomes": {"yes": "An explicit deadline is today or within the next 24 hours.",
                  "no": "The deadline is later, absent, or unclear."}},
    {"id": "impact", "kind": "ordinal",
     "question": "How severe is the reported impact on the customer's work?",
     "outcomes": ["0", "1", "2"],
     "rubric": ["Minor inconvenience; the task can still be completed.",
                "The task is impaired, but a workable alternative is stated.",
                "An important task is blocked and no workable alternative is stated."]}
  ]
}
JSON

To run the TypeScript, save it as quickstart.mts and run npx tsx quickstart.mts.

Read the answer

This is a real answer kettei-core gave to that request, rounded to three places:

{
  "model": "kettei-core",
  "decisions": {
    "team": {
      "kind": "single",
      "probabilities": {"billing": 0.927, "technical": 0.054, "sales": 0.019},
      "top": "billing",
      "p_top": 0.927
    },
    "urgent": {
      "kind": "binary",
      "probabilities": {"yes": 0.912, "no": 0.088},
      "top": "yes",
      "p_top": 0.912
    },
    "impact": {
      "kind": "ordinal",
      "probabilities": {"0": 0.051, "1": 0.106, "2": 0.844},
      "top": "2",
      "p_top": 0.844,
      "expected_level": 1.793
    }
  }
}

Each decision’s answer is under its id.

probabilities has every outcome you allowed, with its probability. They add up to 1.
top is the likeliest outcome, and p_top its probability.
An ordinal decision adds expected_level, the probability-weighted level, counted from 0.
model names the model that answered.

The full answer also has usage, the input tokens you are billed for, and charge, what the call cost. Read the response explains every field. A request that names no model asks for kettei-core. If the model you ask for can’t answer right now, another size may answer instead, and then fallback says so (models and fallback). To ask about pictures, name kettei-fat or kettei-chub, and shrink each picture to the size the model reads (images).

Act on it

Add a policy to a decision and its answer says what to do. With abstain_below, the action is abstain when p_top is below your threshold. Otherwise it is the likeliest outcome:

decisions[0]["policy"] = {"abstain_below": 0.6}
with OneHot() as client:
    result = client.decide(context=ticket, decisions=decisions)

action = result["decisions"]["team"]["policy"]["action"]
queue = "manual_review" if action == "abstain" else action

Choose the threshold on tickets whose answers you know (act on the answer). The clients send an idempotency key with every decision and reuse it when they retry, so a retried call is not charged twice. The one exception is an organisation with zero data retention (retries and idempotency). Nothing from a request is kept for training.

Next steps

How OneHot works

The words OneHot uses, and how the pieces fit together.

Write good decisions

Wording the models read well, and the free linter that checks it.

Score many texts

Send thousands of texts within your rate limits, and price them first.

Improve a decision

Label examples, measure, tune the wording and train a model of your own.

Get started

Make decisions

Improve accuracy

Use the API

Account and billing

Privacy and security

Integrations