Registry / llm-agents / autoevals

autoevals

JSON →
library0.3.0pypypi✓ verified 24d ago

Autoevals is a universal library for quickly and easily evaluating AI model outputs. Developed by the team at Braintrust, it bundles together a variety of automatic evaluation methods including LLM-as-a-judge, heuristic (e.g., Levenshtein distance), and statistical (e.g., BLEU) evaluations. Currently at version 0.2.0, the library is actively maintained with frequent updates.

pip install autoevals
INSTALL
IMPORT
SIG · AUTOEVALS
A
autoevals
llm-agentspythonv0.3.0
Install
2.7s avg
Import
585ms
Disk
23MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.606s · 24.5MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.7s · import 0.564s · 25MB
23MB installed
● package 23MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Factuality
from autoevals.llm import Factuality
Commonly used for LLM-as-a-judge evaluations related to factual accuracy.
Relevance
from autoevals.llm import Relevance
Another common LLM-as-a-judge evaluator for assessing output relevance.
Levenshtein
from autoevals import Levenshtein
For heuristic evaluations based on Levenshtein distance.
NumericDiff
from autoevals.number import NumericDiff
For evaluating numerical differences with a normalized score.

This quickstart demonstrates how to use various autoevals scorers, including an LLM-as-a-judge evaluator (Factuality), a heuristic evaluator (Levenshtein), and a numeric evaluator (NumericDiff). It covers both synchronous and asynchronous evaluation patterns for LLM-based scorers and includes a placeholder for the OpenAI API key, which is essential for LLM evaluations.

import os import asyncio from autoevals.llm import Factuality from autoevals import Levenshtein from autoevals.number import NumericDiff # Set up your OpenAI API key (or compatible service) for LLM evaluators # In a production environment, ensure this is loaded securely from an environment variable. os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'YOUR_OPENAI_API_KEY_HERE') async def main(): # Example 1: LLM-as-a-judge evaluation (requires an LLM API key) print("--- LLM Factuality Evaluation ---") factuality_evaluator = Factuality() input_text = "Which country has the highest population?" output_text = "People's Republic of China" expected_text = "China" # Synchronous evaluation if os.environ['OPENAI_API_KEY'] != 'YOUR_OPENAI_API_KEY_HERE': llm_result_sync = factuality_evaluator(output_text, expected_text, input=input_text) print(f"Factuality score (sync): {llm_result_sync.score}") print(f"Factuality rationale (sync): {llm_result_sync.metadata.get('rationale')}") # Asynchronous evaluation llm_result_async = await factuality_evaluator.eval_async(output_text, expected_text, input=input_text) print(f"Factuality score (async): {llm_result_async.score}") print(f"Factuality rationale (async): {llm_result_async.metadata.get('rationale')}") else: print("Skipping LLM Factuality evaluation: OPENAI_API_KEY not set.") # Example 2: Heuristic evaluation (Levenshtein distance) print("\n--- Levenshtein Distance Evaluation ---") levenshtein_evaluator = Levenshtein() output_str = "hello world" expected_str = "hallo world" lev_result = levenshtein_evaluator(output_str, expected_str) print(f"Levenshtein score: {lev_result.score}") print(f"Levenshtein metadata: {lev_result.metadata}") # Example 3: Numeric difference evaluation print("\n--- Numeric Difference Evaluation ---") numeric_evaluator = NumericDiff() output_num = 105 expected_num = 100 num_result = numeric_evaluator(output_num, expected_num) print(f"NumericDiff score: {num_result.score}") print(f"NumericDiff metadata: {num_result.metadata}") if __name__ == "__main__": asyncio.run(main())
Debug
Known issues
gotchaLLM-as-a-judge evaluation methods (e.g., `Factuality`, `Relevance`) require an OpenAI API key (or a compatible API endpoint). Ensure the `OPENAI_API_KEY` environment variable is set. If `OPENAI_BASE_URL` is not specified, it defaults to an internal AI proxy.
fix
Set `OPENAI_API_KEY` in your environment variables. For custom endpoints, also set `OPENAI_BASE_URL`.
affects: All versions
gotchaBe aware of potential name collisions: this `autoevals` library (from Braintrust) is distinct from other Python packages like `auto-eval` (a CLI tool), `autoevaluator` (another LLM evaluation framework), or `oak-ai-autoeval-tools`, as well as unrelated robotics projects named 'AutoEval'. Always verify the package source and import paths.
fix
Ensure you `pip install autoevals` (from `braintrustdata`) and use import paths like `from autoevals.llm import Factuality`.
affects: All versions
gotchaThe `NumericDiff` evaluator requires an `expected` value to be passed during evaluation; otherwise, it will raise a `ValueError`.
fix
Always provide the `expected` argument when using `NumericDiff`, e.g., `numeric_evaluator(output=105, expected=100)`.
affects: All versions
gotchaWhile many evaluation concepts are adapted from OpenAI's `evals` project, Autoevals implements them to offer greater flexibility for individual examples, prompt tweaking, and output debugging. Users accustomed to OpenAI's `evals` might find the API and usage patterns different.
fix
Refer to the official Autoevals documentation for the correct API usage and examples.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'autoevals'
The 'autoevals' package is not installed in the Python environment.
fix
Install the package using 'pip install autoevals'.
ImportError: cannot import name 'Factuality' from 'autoevals'
The 'Factuality' class is not available in the 'autoevals' module, possibly due to an outdated version.
fix
Ensure you have the latest version by running 'pip install --upgrade autoevals'.
TypeError: Factuality() takes no arguments
Incorrect instantiation of the 'Factuality' class without required parameters.
fix
Initialize 'Factuality' with the necessary parameters as per the documentation.
ValueError: Invalid input provided to Factuality evaluator
The input provided to the 'Factuality' evaluator does not meet the expected format or type.
fix
Verify that the input, output, and expected parameters are correctly formatted and of the correct type.
AttributeError: module 'autoevals' has no attribute 'init'
The 'init' function is not present in the 'autoevals' module, possibly due to an outdated version.
fix
Update to the latest version of 'autoevals' using 'pip install --upgrade autoevals'.
Upgrade
Version history
0.3.0latest on PyPI · released Jun 9, 2026
Audit
Dependencies
openaioptionalRequired for using LLM-as-a-judge evaluation methods (e.g., Factuality, Relevance), which rely on the OpenAI API or compatible services. Compatible with both OpenAI Python SDK v0.x and v1.x.
Agent activity
24 hits · last 30 days
node
20
OpenAI (training)
1
Resources
autoevals — pip install autoevals · libregistry