evalshift
// docs
EvalShift
docs · v0.4.0-alpha

Run your prompts on two LLMs and find out, with statistical confidence, what regressed.

EvalShift is a local-first CLI that helps engineering teams migrate safely between LLM versions. Point it at your prompts and a golden suite of inputs; it runs both models, scores the outputs with structural / semantic / LLM-as-judge evaluators, and produces a single-file HTML report with defensible statistics: paired tests, Cohen’s d, 95% CIs, and Benjamini–Hochberg correction across every (prompt × evaluator × slice) comparison.

## the 60-second start

bash
pip install evalshift
evalshift demo                        # scaffold a runnable demo project
evalshift all --offline --yes --open  # full pipeline — free, no keys, no account

all chains the pipeline — doctor → run → evaluate → analyze → report. Each stage writes its artefact under .evalshift/runs/<run-id>/:

StageArtefact
runraw.jsonl
evaluatescores.jsonl
analyzeanalysis.json
reportreport.html + report.json

## two ways to use it

Local, free, no account — the default. Runs, scoring, statistics, and reports all happen on your machine under .evalshift/; the only network traffic is the model API calls you asked for, with your own provider keys. Start at Getting started, and pair the CLI with the capture SDK for the recommended workflow: record real agent behaviour in production, promote it into a golden suite, evaluate candidates against it.

Hosted, opt-in — for teams. Push immutable run bundles so everyone can view timelines, reports, diffs, and PR comments in one place. Model calls still run locally or in your CI; nothing is uploaded unless you run push. See Hosted setup.

## where to next

+Getting started
first run in 60 seconds — free, offline, no account.
+Recommended workflow
capture with the SDK, evaluate with the CLI — the full loop.
+CLI overview
the five-stage pipeline, run artefacts, cache, and resume.
+Configuration
every evalshift.yaml field, type, and default.
+Golden suite
the JSONL example format — inputs, tags, expected tools, history.
+Evaluators
structural, semantic, llm-judge, tool-call — and when to use each.
+Agent migrations (v0.2)
compare which tools fired, what args, and how they sequenced.
+Offline mode & fixtures
deterministic replay from canned fixtures — no keys, no cost.
+Command reference
every evalshift command and its flags, in one place.
+Capture SDK
record real agent behavior in-process with the evalshift-sdk library.
+Instrumenting agents
@capture.agent, tools, model calls — sync, async, and streaming.
+Framework adapters
zero-instrument capture for LangChain via a callback handler.
+Redaction & data boundary
mask PII in-process before any byte hits disk.
+Config, sinks & hygiene
env gate, sinks, sampling, dedup, and capture GC.
+Captures → golden cases
evalshift capture list / promote / clean / diff — the promote loop.
+GitHub Action
optional: turn the golden suite into a merge gate on every PR.
+Inputs & outputs
every input, output, and permission — plus version pinning.
+Gating & PR feedback
fail-on modes, the PR comment, commit status, baseline resolution.
+Cost control & recipes
path filters, CI-sized suites, two-suite repos, required checks.
+Security & troubleshooting
secret redaction, known edges, and what each failure message means.
+Hosted setup
opt-in: account, token, first push, and the GitHub Action.
+Verdicts & gating
PASS / CONDITIONAL / FAIL / INCONCLUSIVE — what each means and the gate rule.
+Baselines & diffs
pin a baseline run; every new run auto-diffs against it.
+Trends & slices
verdict, regression, and cost/latency over time + the slice heatmap.
+Migration policy & PR gating
the six governed budgets, re-evaluation, and per-PR enforcement.
+Share links
public, expiring, revocable links to a run report.
+Account & organizations
renaming, transferring ownership, and what each deletion removes.
+Methodology
paired tests, Cohen's d, BH-FDR correction, severity tiers.
+FAQ
the questions that come up after first run.
+Changelog
release notes — mirrored from GitHub.

Or jump straight to the landing page for the elevator pitch and a live diff.