Registry / llm-agents / arize-phoenix-evals

arize-phoenix-evals

JSON →
library3.5.1pypypi✓ verified 22d ago

Phoenix Evals provides lightweight, composable building blocks for writing and running evaluations on LLM applications. It offers tools for determining relevance, toxicity, hallucination detection, and more. The library is actively developed, with version 3.0.0 being the current release, and features frequent updates as part of the broader Arize Phoenix ecosystem.

pip install arize-phoenix-evals
INSTALL
IMPORT
SIG · ARIZE-PHOENIX-EVAL
A
arize-phoenix-evals
llm-agentspythonv3.5.1
Install
11.9s avg
Import
1825ms
Disk
209MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.5.1 · 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.910 runs
installs and imports cleanly · install 0.0s · import 1.871s · 207.8MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 11.9s · import 1.779s · 199MB
209MB installed
● package 209MB
Code
Verified usage

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

create_classifier
from phoenix.evals import create_classifier
LLM
from phoenix.evals.llm import LLM
from phoenix.evals import LLM
LLM class is specifically located in the phoenix.evals.llm submodule.
evaluate_dataframe
from phoenix.evals import evaluate_dataframe

This quickstart demonstrates how to set up an LLM-based classification evaluator using the `arize-phoenix-evals` library with an OpenAI model. It covers defining an evaluator with a prompt template and performing evaluations on both simple and nested input data, showcasing input mapping.

import os from phoenix.evals import create_classifier from phoenix.evals.llm import LLM # Set your OpenAI API key from environment variable os.environ["OPENAI_API_KEY"] = os.environ.get('OPENAI_API_KEY', 'sk-your-openai-key') # Replace with actual key or ensure env var is set # Create an LLM instance (ensure OPENAI_API_KEY is set in environment) llm = LLM(provider="openai", model="gpt-4o") # Create a custom classification evaluator evaluator = create_classifier( name="helpfulness", prompt_template="Rate the response to the user query as helpful or not:\n\nQuery: {input}\nResponse: {output}", llm=llm, choices={"helpful": 1.0, "not_helpful": 0.0}, ) # Simple evaluation on a single record scores = evaluator.evaluate({"input": "How do I reset the device?", "output": "Go to settings > reset."}) print(f"Simple evaluation score: {scores[0].score}, label: {scores[0].label}") # Evaluation with input mapping for nested data scores_nested = evaluator.evaluate( {"data": {"query": "How do I restart the app?", "response": "Close and reopen the application."}}, input_mapping={"input": "data.query", "output": "data.response"} ) print(f"Nested evaluation score: {scores_nested[0].score}, label: {scores_nested[0].label}")
Debug
Known issues
breakingVersion 3.0.0 of `arize-phoenix-evals` (and Phoenix v14.0.0) deprecates and removes the 'evals 1.0' module and the legacy experiments module. The `/v1/evaluations` REST endpoint has also been removed from the Phoenix server.
fix
Migrate to the new evaluation APIs and client-side experiments module. Refer to the official Phoenix migration guide for detailed instructions. If interacting with the Phoenix server directly, use the annotations API instead of `/v1/evaluations`.
affects: >=3.0.0
breakingThe legacy `phoenix.session.client.Client` (accessed as `px.Client()`) has been removed in Phoenix v14.0.0. All client interactions now go through `arize-phoenix-client`.
fix
Update your client instantiation from `import phoenix as px; client = px.Client(endpoint=...)` to `from phoenix.client import Client; client = Client(base_url=...)`. The `endpoint` parameter is now `base_url`.
affects: arize-phoenix-evals>=3.0.0 (due to dependency on Phoenix v14.0.0+)
gotchaWhen using LLM-based evaluators, you must separately install the SDK for your chosen LLM vendor (e.g., `openai` for OpenAI models, `langchain` for LangChain integrations). `arize-phoenix-evals` does not bundle these dependencies.
fix
Install the required LLM SDK, for example: `pip install openai>=1.0.0`.
affects: All versions
gotchaStarting with `arize-phoenix-evals` 2.12.0, evaluators automatically JSON-serialize structured data (dicts, lists) passed as template variable values. Manually `str()`-ing complex objects is no longer necessary and could lead to incorrect prompt rendering.
fix
Pass structured data directly to the evaluator; manual serialization is now handled.
affects: >=2.12.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'phoenix.evals'
The 'phoenix.evals' module is not found because the 'arize-phoenix-evals' package is not installed.
fix
Install the package using 'pip install arize-phoenix-evals'.
ImportError: cannot import name 'LLM' from 'phoenix.evals'
The 'LLM' class is not found in 'phoenix.evals' due to an outdated or incorrect installation.
fix
Ensure you have the latest version by running 'pip install --upgrade arize-phoenix-evals'.
TypeError: evaluate_dataframe() missing 1 required positional argument: 'evaluators'
The 'evaluate_dataframe' function is called without the required 'evaluators' argument.
fix
Provide the 'evaluators' argument when calling 'evaluate_dataframe', e.g., 'evaluate_dataframe(dataframe=df, evaluators=[relevance_evaluator])'.
AttributeError: module 'phoenix.evals' has no attribute 'FaithfulnessEvaluator'
The 'FaithfulnessEvaluator' is not found in 'phoenix.evals' due to an incorrect import or outdated version.
fix
Import 'FaithfulnessEvaluator' from 'phoenix.evals.metrics', e.g., 'from phoenix.evals.metrics import FaithfulnessEvaluator'.
ValueError: LLM provider 'openai' requires an API key
The 'openai' provider is used without setting the required API key.
fix
Set the OpenAI API key by assigning it to the 'OPENAI_API_KEY' environment variable, e.g., 'os.environ["OPENAI_API_KEY"] = "your-api-key"'.
Upgrade
Version history
3.5.1latest on PyPI · released Aug 25, 2026
Audit
Dependencies
openaioptionalRequired for LLM-based evaluators using OpenAI models.
arize-phoenix-clientrequiredUsed for interacting with a running Phoenix session (e.g., logging evaluation results or fetching trace data).
Agent activity
37 hits · last 30 days
node
28
Perplexity
1
OpenAI (training)
1
Resources
arize-phoenix-evals — pip install arize-phoenix-evals · libregistry