Jev vs Perplexity Decisions API: GA, Priced, and Compared

import requests

JEV_ENDPOINT = "https://api.typesafe.ai/v1/jev/evaluate"
AUTO_ROUTE_CONFIDENCE = 0.85

QUESTIONS = {
    "routing": {
        "type": "choice",
        "instructions": "Which queue should this ticket go to?",
        "criteria": {
            "billing": "Payment, invoice or refund issue",
            "technical": "Product malfunction or bug",
            "sales": "Buying or upgrade question",
            "abuse": "Safety or abuse report",
        },
    },
    "needs_safety_escalation": {
        "type": "noul",
        "instructions": "Does this ticket require a safety escalation regardless of queue?",
    },
    "urgency": {
        "type": "score",
        "instructions": "Rate how urgent a human reply is, 1 (routine) to 5 (business-stopping)",
    },
}

resp = requests.post(
    JEV_ENDPOINT,
    json={"state": {"ticket": "..."}, "questions": QUESTIONS},
    timeout=5,
)
resp.raise_for_status()
data = resp.json()

route = data["routing"]  # typed answer + calibrated confidence, no generation
if (
    route["confidence"] >= AUTO_ROUTE_CONFIDENCE
    and not data["needs_safety_escalation"]["answer"]
):
    lane = f"auto:{route['answer']}"  # single pass, input tokens only
else:
    lane = "review"  # 0.60-0.85 band or safety flag

import os

import requests

# POST /v1/decisions - no trailing slash (a trailing slash returns 404).
# Auth is Bearer only: a key in x-api-key is not read and returns 401.
PPLX_ENDPOINT = "https://api.perplexity.ai/v1/decisions"
AUTO_ROUTE_CONFIDENCE = 0.85

resp = requests.post(
    PPLX_ENDPOINT,
    headers={"Authorization": f"Bearer {os.environ['PERPLEXITY_API_KEY']}"},
    json={
        # model is REQUIRED on every request; missing/unknown returns 400
        "model": "pplx-decider-v1-27b",
        "state": {
            "ticket": "Checkout has been failing for every customer "
            "for the last hour."
        },
        "questions": {
            "routing": {
                "type": "choice",
                "instructions": "Which queue should this ticket go to?",
                "criteria": {
                    "billing": "Payment, invoice or refund issue",
                    "technical": "Product malfunction or bug",
                    "sales": "Buying or upgrade question",
                    "abuse": "Safety or abuse report",
                },
            },
            "needs_safety_escalation": {
                "type": "noul",
                "instructions": "Does this ticket require a safety "
                "escalation regardless of queue?",
            },
            "urgency": {
                "type": "score",
                "instructions": "Rate how urgent a human reply is, "
                "routine to business-stopping",
                # score: 1-10 ordered levels, answered with the
                # probability-weighted average of level indices (0-based)
                "criteria": ["Routine", "Minor", "Elevated", "Urgent",
                             "Business-stopping"],
            },
        },
    },
    timeout=30,  # docs: small inputs answer under 2s; 30s covers the limit
)
resp.raise_for_status()
data = resp.json()

answers = data["answers"]  # keyed by question name, typed like its question
route = answers["routing"]  # choice + confidence + per-option probabilities
if (
    route["confidence"] >= AUTO_ROUTE_CONFIDENCE
    and answers["needs_safety_escalation"]["noul"] < 0.5  # P(yes)
):
    lane = f"auto:{route['choice']}"
else:
    lane = "review"  # low confidence or safety flag

# Honest-boundary notes from the docs:
# - confidence is "the model's own certainty estimate", NOT the top
#   probability; it drops when the runner-up option closes in.
# - identical requests usually return identical numbers, but they can
#   differ in the second decimal place - validate before automating.
# - usage.input_tokens is billed at $0.04/M; output_tokens are free.
# - rate limit: 10 requests/second on every plan (429 + Retry-After).

const JEV_ENDPOINT = "https://api.typesafe.ai/v1/jev/evaluate";
const AUTO_ROUTE_CONFIDENCE = 0.85;

const QUESTIONS = {
  routing: {
    type: "choice",
    instructions: "Which queue should this ticket go to?",
    criteria: {
      billing: "Payment, invoice or refund issue",
      technical: "Product malfunction or bug",
      sales: "Buying or upgrade question",
      abuse: "Safety or abuse report",
    },
  },
  needs_safety_escalation: {
    type: "noul",
    instructions:
      "Does this ticket require a safety escalation regardless of queue?",
  },
  urgency: {
    type: "score",
    instructions:
      "Rate how urgent a human reply is, 1 (routine) to 5 (business-stopping)",
  },
} as const;

const resp = await fetch(JEV_ENDPOINT, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ state: { ticket: "..." }, questions: QUESTIONS }),
});
const data = await resp.json();

const lane =
  data.routing.confidence >= AUTO_ROUTE_CONFIDENCE &&
  !data.needs_safety_escalation.answer
    ? `auto:${data.routing.answer}`
    : "review";

// Same primitive names, different contracts - adapt both shapes behind
// one interface. Differences this adapter absorbs: Perplexity requires
// model: "pplx-decider-v1-27b" on every call (400 otherwise), nests
// answers under `answers`, uses Bearer auth only, rejects unknown fields
// and trailing slashes, and documents 10 requests/second on every plan.
// Its confidence is the model's own certainty estimate, not the top
// probability - validate calibration per vendor before automating on it.
const JEV_ENDPOINT = "https://api.typesafe.ai/v1/jev/evaluate";
const PPLX_ENDPOINT = "https://api.perplexity.ai/v1/decisions";

const QUESTIONS = {
  routing: {
    type: "choice",
    instructions: "Which queue should this ticket go to?",
    criteria: {
      billing: "Payment, invoice or refund issue",
      technical: "Product malfunction or bug",
      sales: "Buying or upgrade question",
      abuse: "Safety or abuse report",
    },
  },
} as const;

type TypedAnswer = { answer: string; confidence: number };

export async function routeTicket(ticket: string): Promise<TypedAnswer> {
  if (process.env.DECISION_BACKEND === "perplexity") {
    const resp = await fetch(PPLX_ENDPOINT, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.PERPLEXITY_API_KEY!}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        model: "pplx-decider-v1-27b", // required on every request
        state: { ticket },
        questions: QUESTIONS,
      }),
    });
    if (!resp.ok) throw new Error("decision call failed");
    const data = await resp.json();
    const a = data.answers.routing as {
      choice: string;
      confidence: number;
      probabilities: Record<string, number>;
    };
    return { answer: a.choice, confidence: a.confidence };
  }

  const resp = await fetch(JEV_ENDPOINT, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ state: { ticket }, questions: QUESTIONS }),
  });
  if (!resp.ok) throw new Error("decision call failed");
  const data = await resp.json();
  return data.routing as TypedAnswer;
}