PromptEval
Getting Started

Introduction

PromptEval is an evaluation API for AI-powered applications. It analyzes distributions of outputs, not individual responses — giving you statistically valid insight into how your AI behaves across many runs.

The problem it solves

Language models are stochastic. Given the same prompt, they produce different outputs on different runs — even at temperature zero. This means a single evaluation is a single sample from a distribution. It tells you what happened once. It does not tell you what your AI does reliably.

Consider this scenario: you run one evaluation, get a score of 0.81, clear the threshold of 0.75, and ship. But the underlying distribution might be 40% above threshold and 60% below. Your test passed by luck.

Worse: your AI might have two distinct behavioral modes — sometimes warm and empathetic, sometimes terse and transactional — and a single average score hides both. No other evaluation tool surfaces this.

What PromptEval does

When you run N evaluations of the same prompt, PromptEval does not just average the scores. It runs a full statistical analysis:

Behavioral mode detection

Embeds all outputs as semantic vectors, clusters them, and reports whether your AI has one consistent behavior or multiple distinct modes.

Confidence intervals

Computes Wilson score or bootstrap intervals on your pass rate so you know how much to trust the number.

Distribution shift detection

Compares the current run against a stored baseline using a KS test. Flags statistically significant regressions.

Diagnostic explanations

Combines all of the above into a plain-English diagnosis — what changed, why, and what to try next.

Evaluation channels

PromptEval routes each assertion to the most appropriate evaluation method so you pay only for what you need.

ChannelUsed forCost
DeterministicJSON validity, word count, string presenceFree
EncoderToxicity, PII, sentiment classification~$0.0001
Semantic judgeEmpathy, reasoning quality, task completion~$0.001
UQ layerMulti-run statistical analysis (adds on top)~$0.01–0.02 / 10 runs

When to use PromptEval

  • You're evaluating prompts or models before shipping to production
  • You need to detect regressions when changing system prompts or model versions
  • You want to know whether your AI's quality is consistent or bimodal
  • You need evaluations that don't send data to third-party servers
  • You're running evaluations in CI and need deterministic, reproducible scores

A quick look

Here's what a multi-run evaluation call looks like:

eval.ts
1import { PromptEval } from "@prompteval/sdk"
2
3const client = new PromptEval({ apiKey: process.env.PROMPTEVAL_API_KEY })
4
5const result = await client.evaluate({
6 prompt: "A customer says: 'My order has been stuck for a week. I'm really frustrated.'",
7 model: async (prompt) => myAI.complete(prompt),
8 runs: 10,
9 assertions: [
10 { type: "not-toxic" },
11 { type: "max-words", value: 400 },
12 { type: "semantic", criterion: "response demonstrates genuine empathy", threshold: 0.75 },
13 ],
14})
15
16console.log(result.uq.modes) // behavioural mode count + descriptions
17console.log(result.uq.passRate) // e.g. 0.6
18console.log(result.uq.ci95) // e.g. [0.30, 0.84]
19console.log(result.diagnostic) // plain-English explanation