Ask questions

client.systemOne(request, options?) returns APIPromise<SystemOneResult<Q>>, where Q is the type of your questions.

request is a SystemOneRequest<Q>. Any other field on it is sent in the body as it is.

import { choice, NaceClient, noul, score } from "nace-sdk";

const client = new NaceClient();

const { answers, usage, request_id } = await client.systemOne({
  state: "I was charged twice for my March invoice.",
  questions: {
    wants_refund: noul("Is the customer asking for a refund?"),
    topic: choice("Which topic is it?", { billing: null, shipping: null, other: null }),
    urgency: score("How urgent is it?", ["low", "medium", "high"]),
  },
});

answers.wants_refund.noul; // number
answers.topic.choice; // "billing" | "shipping" | "other"
answers.urgency.probabilities["2"]; // probability of "high"
console.log(usage.input_tokens, request_id);

The answer types come from your questions, so a misspelled question name or label is a compile error. A decision is billed per input token, and only when it returns 200, so the client's retries never bill twice.

systemOne checks the questions before it sends anything, and throws a NaceError for:

• no questions, or more than 512;
• a noul with neither instructions nor a non-empty true or false criterion;
• a choice whose criteria aren't a non-empty map of labels;
• a score whose criteria aren't a non-empty list.

An instructions left null is dropped from the body, since Drex refuses null there. A criteria left null is dropped too; on a noul, Drex reads that the same as no criteria.

Question helpersCopy Anchor Link

instructions is a string or null. Plain objects work too, such as { type: "noul", instructions: "Is it urgent?" }.

Answer typesCopy Anchor Link

SystemOneResult<Q> is what systemOne resolves to:

See Reading answers for what each number means.

Request typesCopy Anchor Link

ImagesCopy Anchor Link

Drex Max (drex-max) is the only model that reads images. Pass them in images and refer to them as "Image 1", "Image 2" and so on in the state or the instructions; media inside state or questions returns 422. Each entry, an ImageInput, is one of:

• a WorkspaceFileSource for a file you uploaded with documents.upload. It doesn't count toward the 4 MiB request body, so use it for anything but small images;
• a standard base64 string, or a data URL such as data:image/jpeg;base64,....

A file in another account's returns 422, and so does images with any model but drex-max. Images are PNG, JPEG or WebP, up to 8 per request, 16 MiB each and 32 MiB in all. Their tokens are in usage.image_tokens, already counted in input_tokens.

import { readFile } from "node:fs/promises";
import { imageInput, NaceClient, noul } from "nace-sdk";

const client = new NaceClient();

const receipt = await client.documents.upload(await readFile("receipt.jpg"), { file_name: "receipt.jpg" });
const { answers, usage } = await client.systemOne({
  model: "drex-max",
  state: "Image 1 is a scanned receipt. Image 2 is the shop's logo.",
  images: [imageInput(receipt), imageInput(await readFile("logo.png"))],
  questions: {
    same_shop: noul("Was the receipt in Image 1 issued by the shop whose logo is Image 2?"),
  },
});

console.log(answers.same_shop.noul, usage.image_tokens);

Read the raw responseCopy Anchor Link

Most methods return an APIPromise<T>. Await it for the parsed body, or call one of its methods:

const { data, response, requestId } = await client
  .systemOne({ state: "Refund my order", questions: { refund: noul("Is it a refund request?") } })
  .withResponse();

console.log(response.status, requestId, data.answers.refund.noul);

systemOne, models.list, the document creates, createUploadGrant, createUploadSession, getUploadSession, deleteFile, jobs.get, jobs.list, jobs.getRequest, jobs.rows, jobs.fileLink and the extractionSchemas reads and creates return an APIPromise. documents.upload, uploadPart, completeUploadSession, abortUploadSession, jobs.wait, jobs.delete, jobs.fetchFile, jobs.download and extractionSchemas.delete return a plain Promise, and the iter, iterVersions and events methods are async generators.

List modelsCopy Anchor Link

client.models.list(options?) returns APIPromise<ModelCard[]>, the models your key can use. It's free and works at any balance, so it doubles as a key check.

for (const model of await client.models.list()) {
  console.log(model.name, model.alias_for);
}

See Models.