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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.606s · 24.5MB
glibcpy 3.10–3.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())
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'autoevals'
The 'autoevals' package is not installed in the Python environment.
fixInstall 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.
fixEnsure 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.
fixInitialize '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.
fixVerify 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.
fixUpdate 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.