integrations / provider evaluation & setup

Jev integrations for TypeSafe, OpenRouter, and Vercel

Compare REST payload models, model IDs, usage fields, and runtime environments before abstracting provider differences behind a clean backend adapter.

Quick Guide: How to choose your Jev provider integration?

Teams integrate Jev through three main channels: 1) TypeSafe AI directly for lowest latency and earliest feature access; 2) OpenRouter for consolidated multi-model billing and keys; or 3) Vercel AI Gateway for edge caching, telemetry, and rate limiting in Next.js stacks. Production best practice is encapsulating these services behind a unified backend adapter with automated failover.

Provider Capabilities & Comparison Matrix

Compare authentication, model naming, billing pipelines, and latency profiles:

FeatureTypeSafe AI (Direct)OpenRouter (Gateway)Vercel AI Gateway
Service RolePrimary model developer & hostMulti-provider proxy & unified routerServerless / Edge observability & cache gateway
Target Model ID`jev-1` / `jev-mini``typesafe/jev-1`Configurable upstream mapping
Latency OverheadLowest (direct inference cluster link)Low (+20–50ms proxy hops)Edge-dependent routing latency
Billing ModelDirect TypeSafe invoice / balanceConsolidated OpenRouter creditsBundled into Vercel team invoices
Recommended ForLatency-critical synchronous automationsMulti-model systems sharing one billing keyServerless Next.js edge deployments

Architecture Pattern: Unified Backend Adapter

Shield your application domain code from provider variances while securing secrets on the server:

// lib/jev-adapter.ts
export type JevProvider = 'typesafe' | 'openrouter' | 'vercel';

interface EvaluatePayload {
  state: string;
  questions: Record<string, unknown>;
  provider?: JevProvider;
}

export async function evaluateJevDecision(payload: EvaluatePayload) {
  const provider = payload.provider || (process.env.JEV_PROVIDER as JevProvider) || 'typesafe';
  
  const config = {
    typesafe: {
      url: 'https://api.typesafe.ai/v1/evaluate',
      key: process.env.TYPESAFE_API_KEY,
      model: 'jev-1',
    },
    openrouter: {
      url: 'https://openrouter.ai/api/v1/chat/completions',
      key: process.env.OPENROUTER_API_KEY,
      model: 'typesafe/jev-1',
    },
    vercel: {
      url: process.env.VERCEL_AI_GATEWAY_URL || '',
      key: process.env.VERCEL_AI_GATEWAY_KEY,
      model: 'jev-1',
    },
  }[provider];

  const res = await fetch(config.url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${config.key}`,
    },
    body: JSON.stringify({
      model: config.model,
      state: payload.state,
      questions: payload.questions,
    }),
  });

  if (!res.ok) {
    throw new Error(`Jev evaluate failed via ${provider}: ${res.statusText}`);
  }

  return res.json();
}

Production Deployment Environments

Node.js Container / Dedicated Server (Docker / K8s)

Excellent HTTP keep-alive reuse for high throughput; ideal for asynchronous queue workers processing lead scoring or batch audits.

Cloudflare Workers / Edge Runtime

Near-instant global cold starts. Perfect as an API perimeter gate performing quick state sanitization and traffic routing.

Serverless Functions (Vercel / AWS Lambda)

Zero-maintenance auto-scaling. Always enforce strict connection timeouts (< 5s) to avoid unhandled pipeline hangs.

Frequently Asked Questions (FAQ)

Should I invoke TypeSafe AI directly or through OpenRouter?

Choose TypeSafe AI directly if latency is your top constraint (e.g. real-time inbound chat triage). Choose OpenRouter if you already manage API keys for various LLMs under one dashboard and want unified billing without managing separate merchant accounts.

Why must Jev API calls be restricted to backend servers?

Exposing secret API keys in browser JavaScript invites credential theft and runaway billing. Furthermore, frontend clients cannot reliably execute sensitive fallback actions or sanitize PII from the state input.

Do different providers yield different decisions or confidence ratings?

No. All providers forward requests to the same underlying Jev model weights, producing identical choices and confidence values. Discrepancies are limited to HTTP headers, usage tracking formats, and transient network latency.

How do I engineer automatic provider failover?

Construct an adapter that sends requests to your primary provider (e.g. TypeSafe AI) with a 1500ms timeout. If a network timeout or 5xx error occurs, catch the exception and immediately replay the decision to OpenRouter.

What is the recommended code organization for Jev in modern web stacks?

Keep Jev integration logic isolated in `src/modules/jev/` or `src/core/`. Application pages should only interact with internal API endpoints via `@/lib/api-client`, keeping secrets protected and simplifying migrations.