Integrations

Vercel AI SDK

wity-ai-provider lets you use Wity in the Vercel AI SDK. It plugs into experimental_decide, which asks a model typed questions and gets a probability for every option back.

Install#

npm install wity-ai-provider ai

Needs ai 7.0.133 or newer and Node.js 22 or newer.
ai is the Vercel AI SDK itself. wity-ai-provider adds Wity to it as a model.

API key#

Get an API key from the keys page. Save it in your environment variables as WITY_API_KEY, and the provider reads it by itself:

export WITY_API_KEY="wity_..."

To pass a key from somewhere else, see Settings.

This example reads a customer's message and asks Wity three questions about it: which team should handle it, whether it's urgent, and how much it hurts the customer. All three are answered in one request.

import { experimental_decide } from "ai";
import { wity } from "wity-ai-provider";   // reads your key from WITY_API_KEY
 
const result = await experimental_decide({
  model: wity.decisionModel("wity-1"),
  // The text you want Wity to judge.
  state: "I was charged twice for my subscription this month. Please refund one of them today.",
  questions: {
    // Pick one of these teams.
    team: {
      type: "choice",
      instructions: "Which team should handle this ticket?",
      criteria: {
        billing: "Payments, charges and refunds",
        technical: "Bugs, errors and outages",
        other: "Anything else",
      },
    },
    // Yes or no.
    urgent: {
      type: "boolean",
      instructions: "Does the customer ask for something to happen soon?",
    },
    // A level on a scale, from lowest to highest.
    severity: {
      type: "score",
      instructions: "How much is this hurting the customer?",
      criteria: ["Not at all", "A little", "A lot"],
    },
  },
});
 
result.answers.team.choice;        // "billing"
result.answers.team.probabilities; // { billing: 0.9999, technical: 0.00004, other: 0.00003 }
result.answers.urgent.probability; // 0.9999: the probability of true
result.answers.severity.score;     // 1.98: the expected level, from 0 (Not at all) to 2 (A lot)

state is the text Wity judges. questions names each question, and you use that name to find its answer in result.answers.
The AI SDK calls a yes-or-no question boolean. It's the same as Wity's noul.
Choice and score answers include the probability of every option or level.

Probabilities

Probabilities add up to 1, and a higher number means Wity is more sure. They aren't exact odds. Pick thresholds that suit your data. See Probabilities & confidence.

Settings#

The wity export uses the default settings. To change them, create your own with createWity:

import { createWity } from "wity-ai-provider";
 
const wity = createWity({
  apiKey: process.env.MY_WITY_KEY,   // default: WITY_API_KEY
  headers: { "x-team": "support" },  // sent with every request
});

apiKey

string

Your key. Default: WITY_API_KEY.

baseURL

string

The API address. Default: WITY_BASE_URL, then Wity's address.

headers

object

Extra headers sent with every request.

fetch

function

Your own fetch, for example to log requests.

Reasoning#

Wity answers most questions in one quick pass. On close calls it can think first, which usually takes 1 to 4 seconds. You choose when with reasoning:

"auto"

default

Think only when the question needs it.

"off"

fastest

Never think.

"always"

slowest

Think before every answer.

Set it per call in providerOptions.wity. maxLatencyMs caps how long the request may take:

await experimental_decide({
  model: wity.decisionModel("wity-1"),
  state,
  questions,
  providerOptions: {
    wity: {
      reasoning: "off",     // "off", "auto" (the default) or "always"
      maxLatencyMs: 2000,   // time limit, 200 to 120000 ms
    },
  },
});

Each answer's details are in result.providerMetadata.wity, under the question's name:

confidence

number

How concentrated the probabilities are, for choice and score. It's not the chosen option's probability.

reasoning

object

Whether Wity thought, why, and how many tokens it used.

directProbabilities

object

The answer before Wity thought. Only there when it thought.

Images#

state can also be a list of parts. Text parts are joined into one text, and you can add one image:

state: [
  { type: "text", text: "Is the product damaged?" },
  { type: "file", mediaType: "image/png", data: imageBytes },
],

Wity reads PNG, JPEG, WebP, GIF and BMP.
A second image, or a file that isn't an image, throws UnsupportedFunctionalityError.
See Images for what works well.

Limits#

A choice can have 2 to 128 options, and a score 2 to 10 levels.
Outside these, the call throws InvalidArgumentError before anything is sent or billed.
Wity checks the rest itself, like text length, and answers with a 400. See Errors, limits & billing.

Errors#

A failed request throws the AI SDK's APICallError, with Wity's message.
The AI SDK retries 429 and 5xx errors twice by default. Change it with maxRetries.
A wrong key (401) or an empty balance (402) isn't retried. Failed calls aren't billed.

There's no time limit by default. To stop waiting, pass an abort signal:

await experimental_decide({
  model: wity.decisionModel("wity-1"),
  state,
  questions,
  abortSignal: AbortSignal.timeout(60_000),   // stop waiting after 60 seconds
});

maxLatencyMs limits Wity's own work. The abort signal also covers the network.

The package is wity-ai-provider on npm. Questions and bugs: info@alphanimble.com. It's licensed Apache-2.0.

← LlamaIndex

DSPy →