Python and TypeScript

Both clients are published as sqwishai: the Python client on PyPI and the TypeScript client on npm. They call the HTTP API for you, with retries and helpers that wait for jobs. You can also call the API over HTTP, as in the quickstart.

Install

pip install sqwishai

npm install sqwishai

The Python client needs Python 3.11 or newer. The TypeScript client needs Node 20 or newer. Its package is JavaScript with its type declarations, so it needs no build step of your own. It has no dependencies: the client uses the standard fetch API. PyPI and npm list every release: sqwishai on PyPI and sqwishai on npm.

Make a first call

Set SQWISH_API_KEY to an API key, then run this. It asks one yes-or-no question and prints the probability of yes.

from sqwishai import OneHot

with OneHot() as client:  # reads SQWISH_API_KEY
    result = client.decide(
        model="kettei-core",
        context="Please refund the duplicate charge.",
        decisions=[{"id": "refund", "kind": "binary", "question": "Is a refund requested?"}],
    )
    print(result["decisions"]["refund"]["probabilities"]["yes"])

import { OneHot } from "sqwishai";

const client = new OneHot(); // reads SQWISH_API_KEY
const result = await client.decide({
  model: "kettei-core",
  context: "Please refund the duplicate charge.",
  decisions: [{ id: "refund", kind: "binary", question: "Is a refund requested?" }],
});
console.log(result.decisions.refund.probabilities.yes);

In Python, responses are typed dictionaries. In TypeScript, wire fields keep their snake_case names, and methods use camelCase. Read the response explains what comes back. The shorter examples below use this client. In them, context and decisions hold the values above, and dataset_id (datasetId in TypeScript) is the ID of one of your datasets.

Configure the client

Both clients read the key from SQWISH_API_KEY, and the address from SQWISH_BASE_URL when you set it. An argument you pass wins.

Setting	Python	TypeScript	If you leave it out
API key	`api_key`	`apiKey`	`SQWISH_API_KEY`
Address	`base_url`	`baseUrl`	`SQWISH_BASE_URL`, or `https://api.sqwish.ai` when that is unset
Retries after the first attempt	`max_retries`	`maxRetries`	`2`
Seconds a whole call may take, retries included	`timeout`	`timeout`	`120`. Uploads and calls that wait for a model to load get longer
Your own HTTP client	`http_client`	`fetch`	The client opens its own connections

client = OneHot(max_retries=4)  # the key still comes from SQWISH_API_KEY

const client = new OneHot({ maxRetries: 4 }); // the key still comes from SQWISH_API_KEY

Close a Python client when you are done with it, so its HTTP connections are released. A with block closes it for you.

Proxies and certificates

Version 0.5.0 of the Python client doesn’t read proxy settings or certificate files from the environment, such as HTTPS_PROXY or SSL_CERT_FILE. Behind a corporate proxy, pass an httpx.Client of your own. It keeps its own settings:

import ssl
import httpx
from sqwishai import OneHot

company_ca = ssl.create_default_context(cafile="/etc/ssl/certs/company-ca.pem")
client = OneHot(http_client=httpx.Client(proxy="http://proxy.example.com:8080", verify=company_ca))

httpx.Client() with no arguments reads HTTPS_PROXY and SSL_CERT_FILE itself. For AsyncOneHot, pass an httpx.AsyncClient. In TypeScript, pass fetch: a fetch of your own, such as one that sends through your proxy. Node trusts the extra certificate authorities listed in NODE_EXTRA_CA_CERTS.

Async Python

AsyncOneHot has the same methods as OneHot. Open it with async with, and await each call.

import asyncio

from sqwishai import AsyncOneHot


async def main():
    async with AsyncOneHot() as client:  # reads SQWISH_API_KEY
        result = await client.decide(
            model="kettei-core",
            context="Please refund the duplicate charge.",
            decisions=[{"id": "refund", "kind": "binary", "question": "Is a refund requested?"}],
        )
        print(result["decisions"]["refund"]["probabilities"]["yes"])


asyncio.run(main())

Resource groups

Both clients have resource groups for datasets and their versions, families, models, fine-tuning, labelling and accounts. Where a list comes in pages, list returns one page and iter follows the cursors through the rest. The OpenAPI document is the contract. The SDK types are convenience views, and they may not have every field or route of the API. For anything the clients don’t wrap yet, call the API over HTTP.

Wait for a job or a family

A job’s wait polls until the job ends. When its timeout runs out, the waiting stops, but the job carries on. In both clients, the fine-tuning wait returns a fine-tune that succeeded, whatever its outcome. The outcome is joined when the model passed its gate. A model that joins its family doesn’t answer calls to the family’s name at once. A family that is switched on first loads the model and checks that it answers. Then it moves to it (how a family moves). families.wait(family, model) waits for that move, in both clients. It returns the family once the family serves model. Pass the job’s output_model, or the model’s number such as support-router@2.

job = client.families.create("support-router", dataset_id)
job = client.fine_tuning.wait(job["id"])
if job["outcome"] == "joined":  # it passed its gate
    client.families.wait("support-router", job["output_model"])
    # From here, calls to "support-router" get this model.

const job = await client.families.create({ family: "support-router", dataset_id: datasetId });
const trained = await client.fineTuning.wait(job.id);
if (trained.outcome === "joined") { // it passed its gate
  await client.families.wait("support-router", trained.output_model!);
  // From here, calls to "support-router" get this model.
}

families.wait fails at once when the wait can’t end:

The family is switched off, so it never moves.
The model failed its gate, so it never joined.
The model was deleted or discarded.
The model is not the family’s latest. A family moves only to its latest model, so it won’t move back to an older one.

If its timeout runs out first, the error says what the move waits for. Examples are the model still loading, or a place past your limit. The family carries on moving.

Retries

Both clients retry a call by themselves when it can succeed later, such as after a retryable error or a lost connection. They make two retries by default. To change that, set max_retries in Python or maxRetries in TypeScript when you make the client. It takes 0 to 10, and 0 turns retries off. Before a retry, the client waits as long as Retry-After says, when the server sends it. Otherwise it backs off exponentially, for about 4 seconds at most, with jitter. All the attempts of a call, and the waits between them, fit within its timeout. Retries and idempotency has the policy for plain HTTP calls.

Idempotency keys

Supported creates and inference send one idempotency key with every attempt of a call. Successful answers can be replayed for 24 hours. Failed or expired operations are not run again. To keep one operation across a process restart, persist a key of your own and pass it in. It is idempotency_key in Python and idempotencyKey in TypeScript. An error names the key its call sent, so you can ask about the same operation later (Errors). An organisation with zero data retention keeps no answer, so a key isn’t honoured there. A retry the client makes after a network error runs the request again, and it is charged again.

Wait for a cold model

A fine-tuned model that hasn’t been used for a while may still be loading (readiness and cold starts). With fallback set to none, a decision sent to it while it loads can fail with model_warming. That failure charged nothing, and its key keeps the failure. wait_for_warm=30 in Python, or waitForWarm: 30 in TypeScript, is the one exception to one key per call. While the model loads, the client sends the decision again after each Retry-After, for up to 30 seconds. It uses a new key each time. It does this only under a key it made itself. With your own key, it raises model_warming, and you start a new call with a new key when you choose.

result = client.decide(context, decisions, model="support-router", fallback="none", wait_for_warm=30)

const result = await client.decide(
  { context, decisions, model: "support-router", fallback: "none" },
  { waitForWarm: 30 },
);

Calls the clients don’t repeat

A family’s delete is never repeated by itself. Neither is a family’s switch that names served. A second call could find the family gone or moved. After an unclear failure, read the family before you send one again. Switches and keep warm have no idempotency-key contract. Before you repeat one yourself, read the family or the model (Retries and idempotency).

Errors

When the API answers with an error, the client raises an APIError in Python and throws one in TypeScript. Branch on its code. Errors lists every code.

Python	TypeScript	What it holds
`status`	`status`	The HTTP status
`code`	`code`	The error code, such as `insufficient_credit`
`request_id`	`requestId`	The ID of the request
`retryable`	`retryable`	Whether the same request can succeed later
`retry_after`	`retryAfter`	The seconds in `Retry-After`, when the server sent it
`details`	`details`	On a `422`, each rejected field with its path
`idempotency_key`	`idempotencyKey`	The key the call sent: yours, or the one the client made. Unset for a call that sent no key, such as a read
`idempotency_status`	`idempotencyStatus`	`pending` while the operation runs or its end isn’t known, and `terminal` once it has ended

In Python, str(error) gives the API’s sentence followed by the code, the status and the request ID. In TypeScript, message gives the same. Quote it when you ask for help. After an error that is retryable, or whose idempotency status is pending, call again with the error’s key and the same input. The same key asks about the same operation. A call without it starts another, and a decision sent that way is charged as well if the first was answered.

import time

from sqwishai import APIError

try:
    result = client.decide(context, decisions, model="kettei-core")
except APIError as error:
    if not (error.retryable or error.idempotency_status == "pending"):
        raise  # change the request or the account first
    time.sleep(error.retry_after or 2)
    # The same key asks about the same decision. Without it, this would be a second one.
    result = client.decide(context, decisions, model="kettei-core", idempotency_key=error.idempotency_key)

import { APIError } from "sqwishai";

let result;
try {
  result = await client.decide({ context, decisions, model: "kettei-core" });
} catch (error) {
  if (!(error instanceof APIError) || !(error.retryable || error.idempotencyStatus === "pending")) throw error;
  await new Promise((resolve) => setTimeout(resolve, (error.retryAfter ?? 2) * 1000));
  // The same key asks about the same decision. Without it, this would be a second one.
  result = await client.decide({ context, decisions, model: "kettei-core" }, { idempotencyKey: error.idempotencyKey });
}

A call that got no answer ends with a timeout or a connection error instead. That error carries the same key, as idempotency_key in Python or idempotencyKey in TypeScript. A wait helper raises JobFailed when its job ends failed or cancelled. Its job holds the whole job, with any error.

Get started

Make decisions

Improve accuracy

Use the API

Account and billing

Privacy and security

Integrations