llm-as-a-verifier/llm-as-a-verifier

llm-as-a-verifier

What it is – A Python library that turns a large language model (LLM) into a verifier for the output of AI agents. It scores candidate agent trajectories (code, commands, robot actions, etc.) with fine‑grained, probabilistic rewards and can pick the best‑of‑N candidates, track progress step‑by‑step, or run large‑scale benchmark evaluations.

Key ideas

• Fine‑grained reward – instead of a single binary judgment, the verifier computes an expectation over the full log‑probability distribution of a set of score tokens (1‑20 or A‑T). This yields a continuous reward in ([0,1]) that reflects confidence.
• Repeated evaluation & criteria decomposition – the same trajectory can be evaluated many times under multiple user‑provided criteria (e.g., correctness, root‑cause analysis). The results are averaged to reduce variance.
• Probabilistic Pivot Tournament (PPT) – an O(N k) algorithm that ranks N candidate trajectories by comparing each candidate only against a small set of “pivot” candidates, dramatically lowering the number of LLM calls compared with a full pairwise round‑robin.
• Prefix‑cache optimisation – the verification prompt is structured so that the large, common prefix (task description + both trajectories) can be cached by the LLM backend, cutting uncached input tokens by ~3.4×.
• Multi‑modal support – image inputs can be attached to any verification call, enabling verification of visual robot roll‑outs or before/after screenshots.

Installation

pip install llm-verifier          # stable release from PyPI
# or, from source for the latest code
pip install -e .

You’ll need an API key for a model that returns log‑probs (e.g., DeepSeek‑V4‑Flash, Gemini 2.5‑Flash, or a local vLLM server).

Quick‑start examples

import llm_verifier

problem = "Write a function that reverses a string."
candidates = [
    "def rev(s): return s[::-1]",
    "def rev(s): return s",
    "def rev(s): return ''.join(sorted(s))",
]

# Choose the best candidate using the verifier
result = llm_verifier.select(
    problem=problem,
    candidates=candidates,
    criteria={"Correctness": "Does the code actually reverse the string?"},
)
print(result.index)   # → 0 (the correct implementation)
print(result.scores)  # per‑candidate scores

Other entry points:

• llm_verifier.compare – returns the raw fine‑grained reward for a pairwise comparison.
• llm_verifier.track – scores a completed trajectory after each step, producing a progress curve.
• ProgressTracker – an online version that can be fed step‑by‑step during execution.

Benchmarks & results The library ships reproducible scripts for several agentic benchmarks (Terminal‑Bench, SWE‑Bench Verified, MedAgentBench, RoboRewardBench). Using Gemini 2.5‑Flash as the verifier, the reported Pass@1 scores exceed the original baselines:

Benchmark	Base model	LLM‑as‑Verifier	Oracle
Terminal‑Bench V2 (best‑of‑5)	GPT‑5.5	86.5 %	92.1 %
SWE‑Bench Verified (best‑of‑3)	Opus 4.5/4.6	78.2 %	84.4 %
MedAgentBench (best‑of‑5)	Claude Opus 4.8	73.3 %	75.0 %

Self‑verification (the same model both generates and verifies) also beats the original Pass@1 on Terminal‑Bench 2.1.

How it works under the hood

• fine_grained_reward.py implements the expectation over log‑probabilities.
• pivot_tournament.py contains the PPT algorithm.
• progress.py provides the per‑step scoring utilities.
• benchmarks.py registers each benchmark and loads the corresponding agent trajectories from data/.
• Caches are stored in cache/; results in results/.

Extending to your own task

1. Place your agent trajectories under data/<task_name>_trajs/.
2. Copy criteria/TEMPLATE.md to a new file (e.g., criteria/mytask.md) and write the evaluation criteria you care about.
3. Run llm_verifier.select with problem, candidates, and criteria=your_criteria_file – or use the Claude Code plugin (TurboAgent) to have Claude generate the criteria and invoke the verifier automatically.

Claude Code plugin (TurboAgent) A drop‑in proxy that lets Claude Code call the verifier automatically, generating multiple candidate completions in parallel and selecting the best via PPT. Install with:

pip install git+https://github.com/llm-as-a-verifier/TurboAgent

Then start the proxy (turbo-agent) and point Claude Code at http://localhost:8888.

Resources

• Documentation: https://llm-as-a-verifier.com/docs/
• Website: https://llm-as-a-verifier.com
• Paper (arXiv): https://arxiv.org/abs/2607.05391
• Slack community, Twitter/X, and the TurboAgent repo for the Claude Code integration.

Citation If you use the framework in research, cite the arXiv paper provided in the README.