Using TypeSafe Jev with Vercel AI SDK: experimental_evaluate Guide

TypeSafe Jev integrates into Next.js applications through AI SDK 7's experimental_evaluate API (AI SDK 7.0.105 or later). You can call it directly with the @ai-sdk/typesafe-ai provider or through Vercel AI Gateway as typesafe-ai/jev. Because Jev is a non-autoregressive decision model, use experimental_evaluate rather than generateText() or streamText().

Installation and Provider Setup

npm install ai @ai-sdk/typesafe-ai

Pick one way to authenticate:

# Option A: Direct TypeSafe provider (.env.local)
TYPESAFE_AI_API_KEY="your_typesafe_key"

# Option B: Vercel AI Gateway
# `vercel link` then `vercel env pull` writes VERCEL_OIDC_TOKEN to your env file.
# Vercel deployments receive the token automatically.

Complete Next.js Route Handler Example

The following route handler (app/api/triage/route.ts) evaluates incoming user tickets with the direct TypeSafe provider:

import { NextResponse } from "next/server";
import { experimental_evaluate as evaluate } from "ai";
import { typeSafeAi } from "@ai-sdk/typesafe-ai";

export async function POST(request: Request) {
  try {
    const body = await request.json();
    const { ticketText, customerTier } = body;

    if (!ticketText) {
      return NextResponse.json({ error: "Missing ticketText" }, { status: 400 });
    }

    const evaluation = await evaluate({
      model: typeSafeAi.evaluationModel("jev-latest"),
      state: {
        ticket: ticketText,
        tier: customerTier || "standard",
      },
      questions: {
        team: {
          type: "choice",
          instructions: "Route this inquiry to the responsible team.",
          criteria: {
            billing: "Charges, invoices, and refunds",
            technical: "Bugs, outages, and integration failures",
            fraud: "Suspected unauthorized or fraudulent activity",
            general: "Anything that does not fit the other teams",
          },
        },
        riskScore: {
          type: "score",
          instructions: "Evaluate the financial and security risk level of this ticket.",
          criteria: [
            "No risk",
            "Minor concern",
            "Potential chargeback",
            "Critical security issue",
          ],
        },
        isUrgent: {
          type: "boolean",
          instructions: "Does this ticket demand a response within 15 minutes?",
        },
      },
    });

    // TypeSafe's confidence statistic is provider metadata, keyed by question ID
    const confidence = evaluation.providerMetadata?.typesafe?.confidence as
      | Record<string, number>
      | undefined;

    return NextResponse.json({
      team: evaluation.answers.team.choice,
      teamConfidence: confidence?.team,
      riskScore: evaluation.answers.riskScore.score,
      isUrgentProbability: evaluation.answers.isUrgent.probability,
      usage: evaluation.usage,
    });
  } catch (error: unknown) {
    console.error("Jev evaluation failed:", error);
    return NextResponse.json(
      { error: "Failed to evaluate ticket" },
      { status: 500 }
    );
  }
}

The AI SDK calls Noul questions boolean and returns probability, the chance the statement is true. TypeSafe rounds probabilities and scores to two decimal places, so a distribution may not sum to exactly 1.

Using Vercel AI Gateway

To route through AI Gateway for its logs, budgets, and per-request Zero Data Retention option, pass the Gateway model ID as a plain string:

import { experimental_evaluate as evaluate } from "ai";

const result = await evaluate({
  // A plain model string routes through AI Gateway
  model: "typesafe-ai/jev",
  state: { event: "Payment attempt failed with code ERR_CARD_DECLINED" },
  questions: {
    action: {
      type: "choice",
      instructions: "Determine immediate payment retry strategy.",
      criteria: {
        retry_immediately: "Transient decline that a retry may clear",
        prompt_user_update: "The card needs new details from the user",
        block_card: "Signs of fraud or a card that should not be charged",
      },
    },
  },
  providerOptions: {
    gateway: { zeroDataRetention: true },
  },
});

If you need an explicit provider object, gateway.evaluationModel("typesafe-ai/jev") from @ai-sdk/gateway does the same thing.

Differences from Traditional AI SDK Usage

If you have used generateObject with Zod schemas in Vercel AI SDK, note how experimental_evaluate differs:

Feature	`generateObject` (with LLMs)	`experimental_evaluate` (with Jev)
Provider	OpenAI, Anthropic, Google	`@ai-sdk/typesafe-ai`
Model Class	Autoregressive LLM	Non-autoregressive System One
Output Type	Extracted JSON object	Typed mathematical decisions with probabilities
Latency	Depends on model and output length (Gemini 3.8 Flash: 1,204ms median in our Banking77 test)	70ms – 500ms (TypeSafe reported); 188ms median in our Banking77 test
Output Billing	Billed per generated token	$0.00 (unmetered output rate)
Zod Schema Parse Failures	Occasional syntax breaks	Impossible (strictly typed primitive output)

Related Context

reference implementation alternative

Sources & Documentation

AI SDK Providers: TypeSafe — @ai-sdk/typesafe-ai setup, TYPESAFE_AI_API_KEY, question types, boolean-to-Noul mapping, and confidence under providerMetadata. Checked September 26, 2026.
AI SDK Core Reference: experimental_evaluate — API reference for the evaluate function.
Vercel Knowledge Base: How to classify, route, and score with Jev and AI SDK — Gateway model ID typesafe-ai/jev, OIDC authentication, Zero Data Retention option, and routing examples (September 19, 2026).
Vercel Changelog: TypeSafe AI's Jev now available on AI Gateway — September 16, 2026 launch; AI SDK 7.0.105 or later supports the evaluate API.