Registry / llm-agents / deepeval

deepeval

JSON →
library4.2.0pypypi✓ verified 25d ago

DeepEval is an LLM evaluation framework that helps developers evaluate any LLM workflow, from simple prompt chains to complex multi-step agents. It provides a suite of metrics for various evaluation aspects like relevancy, faithfulness, hallucination, and agentic task completion. Currently at version 3.9.6, the library maintains a frequent release cadence, often introducing new metrics, test case types, and developer experience improvements.

pip install deepeval
INSTALL
IMPORT
SIG · DEEPEVAL
D
deepeval
llm-agentspythonv4.2.0
Install
15.4s avg
Import
7169ms
Disk
149MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.2.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 5.944s · 146.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 15.4s · import 5.526s · 145MB
149MB installed
● package 149MB
Code
Verified usage

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

evaluate
from deepeval import evaluate
LLMTestCase
from deepeval.test_case import LLMTestCase
Turn
from deepeval.test_case import Turn
list[LLMTestCase]
For conversational test cases, DeepEval v3.0.8+ requires `list[Turn]` instead of a `list[LLMTestCase]`.
AnswerRelevancyMetric
from deepeval.metrics import AnswerRelevancyMetric
Most metrics follow this import pattern.

This quickstart demonstrates how to define a basic text-based LLMTestCase, initialize an `AnswerRelevancyMetric`, and run an asynchronous evaluation using `deepeval.evaluate`. Remember to set an LLM API key (e.g., `OPENAI_API_KEY`) as an environment variable or directly in the code, as most metrics rely on an external LLM for their evaluation logic.

import os import asyncio from deepeval import evaluate from deepeval.test_case import LLMTestCase from deepeval.metrics import AnswerRelevancyMetric # Configure your LLM API key (e.g., OpenAI, Cohere, etc.) # Most metrics require an LLM to run. Replace with your actual key or set as env var. # os.environ["OPENAI_API_KEY"] = os.environ.get('OPENAI_API_KEY', 'your_openai_api_key_here') async def main(): # Define a simple LLM test case test_case = LLMTestCase( input="What is the capital of France?", actual_output="Paris is the capital of France.", expected_output="Paris", context=["France is a country in Western Europe. Its capital is Paris."], retrieval_context=["Paris is known for the Eiffel Tower."] ) # Initialize a metric, e.g., AnswerRelevancyMetric # Some metrics can take additional parameters or a specific LLM model. answer_relevancy_metric = AnswerRelevancyMetric(threshold=0.7) # Run the evaluation results = await evaluate( [test_case], metrics=[answer_relevancy_metric] ) print("Evaluation Results:") for result in results: print(f" Input: {result.input}") print(f" Actual Output: {result.actual_output}") for m in result.metrics_results: print(f" Metric: {m.metric_name}, Score: {m.score}, Pass: {m.success}") if __name__ == '__main__': asyncio.run(main())
deepeval --version
Debug
Known issues
breakingBreaking change in v3.0.8: Conversational test cases must now use a `list[Turn]` instead of `list[LLMTestCase]`.
fix
Migrate your conversational test cases from a list of `LLMTestCase` objects to a list of `Turn` objects, where each `Turn` has a `role` (e.g., 'user', 'assistant') and `content` attribute.
affects: >=3.0.8
breakingMajor API overhaul in v3.0: Significant changes for defining complex LLM workflows and agents.
fix
Review the official DeepEval v3.0 migration guide and documentation. Existing evaluation setups for multi-step or agentic workflows may require substantial refactoring due to the introduction of 'component-level granularity'.
affects: >=3.0.0
gotchaDeepEval provides multiple `TestCase` types (`LLMTestCase`, `MLLMTestCase`, `ArenaTestCase`, `Turn`). Using the incorrect `TestCase` type for a specific evaluation scenario (e.g., `LLMTestCase` for multi-turn conversations after v3.0.8) is a common error.
fix
Carefully select the appropriate `TestCase` type based on your evaluation need: `LLMTestCase` for single-turn text, `Turn` for conversational turns, `MLLMTestCase` for multimodal inputs, and `ArenaTestCase` for pairwise comparisons.
affects: All versions
gotchaMost DeepEval metrics rely on an underlying Large Language Model (LLM) for their evaluation logic, requiring an API key (e.g., `OPENAI_API_KEY`, `COHERE_API_KEY`) to be set.
fix
Ensure the necessary LLM API key is configured as an environment variable (e.g., `os.environ["OPENAI_API_KEY"] = "..."`) or passed explicitly via the `model` parameter when initializing metrics or running `evaluate`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'deepeval.integrations.integrations'
This error often occurs because the module path has changed in newer versions of DeepEval, or a necessary optional dependency for a specific feature (like a benchmark or a specific metric) is not installed.
fix
First, ensure you have the latest version of deepeval: `pip install -U deepeval`. If the issue persists, check the official DeepEval documentation for updated import paths or install specific extra dependencies, e.g., `pip install deepeval[benchmark]` or `pip install pandas` if related to benchmarks like MMLU.
AttributeError: 'NoneType' object has no attribute 'verdict'
This error typically arises when the evaluation process, especially in parallel evaluations or with certain metrics, fails to produce a valid verdict or result, leading an expected object to be `None` instead of a populated result object.
fix
Ensure your evaluation model is robust enough and consider increasing timeouts (`DEEPEVAL_PER_TASK_TIMEOUT_SECONDS_OVERRIDE`, `DEEPEVAL_PER_ATTEMPT_TIMEOUT_SECONDS_OVERRIDE`) to prevent premature termination. Also, enable verbose logging (`export LOG_LEVEL=DEBUG`) to get more context on why the verdict might be missing.
ValueError: Evaluation LLM outputted an invalid JSON. Please use a better evaluation model.
This error indicates that the LLM used by DeepEval as a 'judge' for evaluation (e.g., for metrics like GEval) failed to return its output in the expected JSON format, often due to weaker models, overly complex prompts, or truncation.
fix
Try using a more capable LLM for evaluation (e.g., `gpt-4o-mini` or `gpt-4`). You can also enable JSON confinement for your custom LLM judge, customize the evaluation template to include clearer formatting instructions, or use `error_config=ErrorConfig(ignore_errors=True)` to skip failing test cases if immediate robustness is preferred.
SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate.
This is an SSL certificate verification error, usually indicating a problem with the local environment's certificate setup, preventing secure communication with the Confident AI API or other external services.
fix
First, ensure your `certifi` package is up to date: `python -m pip install -U certifi`. If the issue persists, clear any custom `REQUESTS_CA_BUNDLE`, `SSL_CERT_FILE`, or `SSL_CERT_DIR` environment variables, and verify your system's certificate store. Run `curl -v https://api.confident-ai.com/` and a `requests.get` check from Python to diagnose the underlying SSL issue in your environment.
Upgrade
Version history
4.2.0latest on PyPI · released Aug 24, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
49 hits · last 30 days
node
44
OpenAI (training)
1
Resources
deepeval — pip install deepeval · libregistry