Using TypeSafe Jev with Vercel AI SDK: experimental_evaluate Guide

TypeSafe Jev integrates into the Vercel ecosystem through Vercel AI SDK 7+ using the dedicated experimental_evaluate function and the @ai-sdk/typesafe-ai provider. Because Jev is a structured decision model rather than an autoregressive text generator, it uses evaluate() rather than generateText() or streamText(). Routing requests either directly with TYPESAFE_API_KEY or through Vercel AI Gateway under model identifier typesafe-ai/jev, it returns typed choices, rubric scores, and calibrated probabilities directly into Next.js Route Handlers and Server Actions in 70ms to 500ms according to TypeSafe specifications.

Installation and Package Setup

In your Next.js application, install the Vercel AI SDK along with the official TypeSafe provider adapter:

npm install ai @ai-sdk/typesafe-ai

Environment Configuration

Configure your environment credentials in .env.local:

# Option A: Direct TypeSafe API Key
TYPESAFE_API_KEY="ts_live_your_typesafe_key"

# Option B: Vercel AI Gateway (if routing through Vercel telemetry)
AI_GATEWAY_TOKEN="your_vercel_ai_gateway_token"

Complete Next.js Route Handler Example

The following route handler (app/api/triage/route.ts) evaluates incoming user tickets using experimental_evaluate:

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 });
    }

    // Call Jev using Vercel AI SDK 7
    const evaluation = await evaluate({
      model: typeSafeAi.evaluationModel("jev-latest"),
      state: {
        ticket: ticketText,
        tier: customerTier || "standard",
      },
      questions: {
        team: {
          type: "choice",
          options: ["billing", "technical", "fraud", "general"],
          instructions: "Route this inquiry to the responsible engineering or operations team.",
        },
        riskScore: {
          type: "score",
          levels: ["no_risk", "minor_concern", "potential_chargeback", "critical_security"],
          instructions: "Evaluate the financial and security risk level of this transaction.",
        },
        isUrgent: {
          type: "noul",
          instructions: "Does this ticket demand immediate response within 15 minutes?",
        },
      },
    });

    // Access typed answers directly
    return NextResponse.json({
      team: evaluation.answers.team.choice,
      confidence: evaluation.answers.team.confidence,
      riskScore: evaluation.answers.riskScore.score,
      isUrgentProbability: evaluation.answers.isUrgent.noul,
      latencyMs: evaluation.usage.latencyMs,
    });
  } catch (error: unknown) {
    console.error("Jev evaluation failed:", error);
    return NextResponse.json(
      { error: "Failed to evaluate ticket" },
      { status: 500 }
    );
  }
}

Using Vercel AI Gateway

If your application routes requests through Vercel AI Gateway for unified telemetry, caching, and rate-limit buffering, use the Gateway model identifier:

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

const result = await evaluate({
  // Routes through Vercel AI Gateway
  model: typeSafeAi.evaluationModel("typesafe-ai/jev", {
    gateway: {
      id: "my-gateway-project",
    },
  }),
  state: { event: "Payment attempt failed with code ERR_CARD_DECLINED" },
  questions: {
    action: {
      type: "choice",
      options: ["retry_immediately", "prompt_user_update", "block_card"],
      instructions: "Determine immediate payment retry strategy.",
    },
  },
});

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	800ms – 4,000ms	70ms – 500ms (TypeSafe reported)
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