Ask questions

Use client.models.list() with the same API key and base URL to check which models are available before selecting one.

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 or criteria left null is dropped from the body. Drex reads null there the same as no key.

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:

legend is always a list of labels, whichever shape the server sent: a legend keyed by level, which Drex sends when a request asks for X-Nace-Legend: object or comes from a TypeSafe client, is read as the same list. The SDK doesn't send that header.

See Reading answers for what each number means.

Request typesCopy Anchor Link

ImagesCopy Anchor Link

The served Drex Max models read images. Retired ids that resolve to Max v1.1 accept images too. 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 (upload without workspace_id). 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 one of your Workspaces or in another account's returns 422, and so does images with any model that does not support images. 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. Every workspaces, workspaces.files and search method returns an APIPromise too, except workspaces.iterAll, an async generator.

OpenAI-compatible decisionsCopy Anchor Link

client.decisions.create(params, options?) returns APIPromise<Decision>. It asks the same questions as systemOne does, in the wire shape of OpenAI's Decisions API, which POST /v1/decisions serves. Answers come back in question order rather than by name, and nothing is checked before sending: the server's 422 names the field at fault in error.param, read as the error's param.

params is a DecisionCreateParams.

const { answers } = await client.decisions.create({
  input: "I was charged twice for my March invoice.",
  questions: [
    { type: "predicate", name: "wants_refund", instructions: "Is the customer asking for a refund?" },
    { type: "choice", name: "refund", instructions: "Refund?", choices: [{ value: true }, { value: false }, { value: "partial" }] },
  ],
});

const refund = answers[1];
if (refund?.type === "choice") refund.choice; // true, false or "partial", as sent

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.