arize-phoenix 4.4.4rc6__tar.gz → 4.6.1__tar.gz

{arize_phoenix-4.4.4rc6 → arize_phoenix-4.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: arize-phoenix
-Version: 4.4.4rc6
+Version: 4.6.1
 Summary: AI Observability and Evaluation
 Project-URL: Documentation, https://docs.arize.com/phoenix/
 Project-URL: Issues, https://github.com/Arize-ai/phoenix/issues
@@ -41,6 +41,7 @@ Requires-Dist: protobuf<6.0,>=3.20
 Requires-Dist: psutil
 Requires-Dist: pyarrow
 Requires-Dist: python-multipart
+Requires-Dist: pyyaml
 Requires-Dist: scikit-learn
 Requires-Dist: scipy
 Requires-Dist: sqlalchemy[asyncio]<3,>=2.0.4
@@ -94,9 +95,10 @@ Requires-Dist: types-tabulate; extra == 'dev'
 Provides-Extra: evals
 Provides-Extra: experimental
 Provides-Extra: llama-index
-Requires-Dist: llama-index-embeddings-openai; extra == 'llama-index'
-Requires-Dist: llama-index-llms-openai; extra == 'llama-index'
-Requires-Dist: llama-index-readers-file; extra == 'llama-index'
+Requires-Dist: llama-index-agent-openai==0.2.7; extra == 'llama-index'
+Requires-Dist: llama-index-embeddings-openai==0.1.10; extra == 'llama-index'
+Requires-Dist: llama-index-llms-openai==0.1.24; extra == 'llama-index'
+Requires-Dist: llama-index-readers-file==0.1.25; extra == 'llama-index'
 Requires-Dist: llama-index==0.10.51; extra == 'llama-index'
 Provides-Extra: pg
 Requires-Dist: asyncpg; extra == 'pg'

{arize_phoenix-4.4.4rc6 → arize_phoenix-4.6.1}/pyproject.toml

@@ -59,6 +59,7 @@ dependencies = [
   "cachetools",
   "python-multipart",  # see https://www.starlette.io/#dependencies
   "arize-phoenix-evals>=0.13.1",
+  "pyyaml", # for OpenAPI
 ]
 dynamic = ["version"]
 
@@ -94,9 +95,10 @@ evals = []
 experimental = []
 llama-index = [
   "llama-index==0.10.51",  # always pin to a version that keeps our notebooks working
-  "llama-index-readers-file",
-  "llama-index-llms-openai",
-  "llama-index-embeddings-openai",
+  "llama-index-readers-file==0.1.25",
+  "llama-index-llms-openai==0.1.24",
+  "llama-index-embeddings-openai==0.1.10",
+  "llama-index-agent-openai==0.2.7",
 ]
 pg = [
   "asyncpg",

{arize_phoenix-4.4.4rc6 → arize_phoenix-4.6.1}/src/phoenix/db/models.py

@@ -91,8 +91,8 @@ class UtcTimeStamp(TypeDecorator[datetime]):
         return normalize_datetime(value, timezone.utc)
 
 
-class ExperimentResult(TypedDict, total=False):
-    result: Any
+class ExperimentRunOutput(TypedDict, total=False):
+    task_output: Any
 
 
 class Base(DeclarativeBase):
@@ -110,7 +110,7 @@ class Base(DeclarativeBase):
     type_annotation_map = {
         Dict[str, Any]: JsonDict,
         List[Dict[str, Any]]: JsonList,
-        ExperimentResult: JsonDict,
+        ExperimentRunOutput: JsonDict,
     }
 
 
@@ -561,7 +561,7 @@ class ExperimentRun(Base):
     )
     repetition_number: Mapped[int]
     trace_id: Mapped[Optional[str]]
-    output: Mapped[ExperimentResult]
+    output: Mapped[ExperimentRunOutput]
     start_time: Mapped[datetime] = mapped_column(UtcTimeStamp)
     end_time: Mapped[datetime] = mapped_column(UtcTimeStamp)
     prompt_token_count: Mapped[Optional[int]]

{arize_phoenix-4.4.4rc6 → arize_phoenix-4.6.1}/src/phoenix/experiments/evaluators/base.py

@@ -6,7 +6,7 @@ from typing import Any, Awaitable, Callable, Optional, Union
 
 from typing_extensions import TypeAlias
 
-from phoenix.experiments.evaluators.utils import validate_signature
+from phoenix.experiments.evaluators.utils import validate_evaluator_signature
 from phoenix.experiments.types import (
     AnnotatorKind,
     EvaluationResult,
@@ -108,7 +108,7 @@ class Evaluator(ABC):
 
 def _validate_sig(fn: Callable[..., Any], fn_name: str) -> None:
     sig = inspect.signature(fn)
-    validate_signature(sig)
+    validate_evaluator_signature(sig)
     for param in sig.parameters.values():
         if param.kind is inspect.Parameter.VAR_KEYWORD:
             return

{arize_phoenix-4.4.4rc6 → arize_phoenix-4.6.1}/src/phoenix/experiments/evaluators/utils.py

@@ -8,6 +8,7 @@ from phoenix.experiments.types import (
     EvaluationResult,
     JSONSerializable,
 )
+from phoenix.experiments.utils import get_func_name
 
 if TYPE_CHECKING:
     from phoenix.experiments.evaluators.base import Evaluator
@@ -25,11 +26,11 @@ def unwrap_json(obj: JSONSerializable) -> JSONSerializable:
     return obj
 
 
-def validate_signature(sig: inspect.Signature) -> None:
+def validate_evaluator_signature(sig: inspect.Signature) -> None:
     # Check that the wrapped function has a valid signature for use as an evaluator
     # If it does not, raise an error to exit early before running evaluations
     params = sig.parameters
-    valid_named_params = {"input", "output", "expected", "metadata"}
+    valid_named_params = {"input", "output", "expected", "reference", "metadata"}
     if len(params) == 0:
         raise ValueError("Evaluation function must have at least one parameter.")
     if len(params) > 1:
@@ -49,11 +50,12 @@ def validate_signature(sig: inspect.Signature) -> None:
             )
 
 
-def _bind_signature(sig: inspect.Signature, **kwargs: Any) -> inspect.BoundArguments:
+def _bind_evaluator_signature(sig: inspect.Signature, **kwargs: Any) -> inspect.BoundArguments:
     parameter_mapping = {
         "input": kwargs.get("input"),
         "output": kwargs.get("output"),
         "expected": kwargs.get("expected"),
+        "reference": kwargs.get("reference"),  # `reference` is an alias for `expected`
         "metadata": kwargs.get("metadata"),
     }
     params = sig.parameters
@@ -82,16 +84,11 @@ def create_evaluator(
     def wrapper(func: Callable[..., Any]) -> "Evaluator":
         nonlocal name
         if not name:
-            if hasattr(func, "__self__"):
-                name = func.__self__.__class__.__name__
-            elif hasattr(func, "__name__"):
-                name = func.__name__
-            else:
-                name = str(func)
+            name = get_func_name(func)
         assert name is not None
 
         wrapped_signature = inspect.signature(func)
-        validate_signature(wrapped_signature)
+        validate_evaluator_signature(wrapped_signature)
 
         if inspect.iscoroutinefunction(func):
             return _wrap_coroutine_evaluation_function(name, kind, wrapped_signature, scorer)(func)
@@ -120,7 +117,7 @@ def _wrap_coroutine_evaluation_function(
                 return await func(*args, **kwargs)
 
             async def async_evaluate(self, **kwargs: Any) -> EvaluationResult:
-                bound_signature = _bind_signature(sig, **kwargs)
+                bound_signature = _bind_evaluator_signature(sig, **kwargs)
                 result = await func(*bound_signature.args, **bound_signature.kwargs)
                 return convert_to_score(result)
 
@@ -148,7 +145,7 @@ def _wrap_sync_evaluation_function(
                 return func(*args, **kwargs)
 
             def evaluate(self, **kwargs: Any) -> EvaluationResult:
-                bound_signature = _bind_signature(sig, **kwargs)
+                bound_signature = _bind_evaluator_signature(sig, **kwargs)
                 result = func(*bound_signature.args, **bound_signature.kwargs)
                 return convert_to_score(result)
 

{arize_phoenix-4.4.4rc6 → arize_phoenix-4.6.1}/src/phoenix/experiments/functions.py

@@ -1,5 +1,7 @@
 import functools
+import inspect
 import json
+import traceback
 from binascii import hexlify
 from contextlib import ExitStack
 from copy import deepcopy
@@ -10,6 +12,7 @@ from typing import (
     Any,
     Awaitable,
     Dict,
+    Literal,
     Mapping,
     Optional,
     Sequence,
@@ -58,8 +61,8 @@ from phoenix.experiments.types import (
     Experiment,
     ExperimentEvaluationRun,
     ExperimentParameters,
-    ExperimentResult,
     ExperimentRun,
+    ExperimentRunOutput,
     ExperimentTask,
     RanExperiment,
     TaskSummary,
@@ -67,7 +70,7 @@ from phoenix.experiments.types import (
     _asdict,
     _replace,
 )
-from phoenix.experiments.utils import get_dataset_experiments_url, get_experiment_url
+from phoenix.experiments.utils import get_dataset_experiments_url, get_experiment_url, get_func_name
 from phoenix.trace.attributes import flatten
 from phoenix.utilities.json import jsonify
 
@@ -105,6 +108,61 @@ def run_experiment(
     dry_run: Union[bool, int] = False,
     print_summary: bool = True,
 ) -> RanExperiment:
+    """
+    Runs an experiment using a given set of dataset of examples.
+
+    An experiment is a user-defined task that runs on each example in a dataset. The results from
+    each experiment can be evaluated using any number of evaluators to measure the behavior of the
+    task. The experiment and evaluation results are stored in the Phoenix database for comparison
+    and analysis.
+
+    A `task` is either a synchronous or asynchronous function that returns a JSON serializable
+    output. If the `task` is a function of one argument then that argument will be bound to the
+    `input` field of the dataset example. Alternatively, the `task` can be a function of any
+    combination of specific argument names that will be bound to special values:
+        `input`: The input field of the dataset example
+        `expected`: The expected or reference output of the dataset example
+        `reference`: An alias for `expected`
+        `metadata`: Metadata associated with the dataset example
+        `example`: The dataset `Example` object with all associated fields
+
+    An `evaluator` is either a synchronous or asynchronous function that returns either a boolean
+    or numeric "score". If the `evaluator` is a function of one argument then that argument will be
+    bound to the `output` of the task. Alternatively, the `evaluator` can be a function of any
+    combination of specific argument names that will be bound to special values:
+        `input`: The input field of the dataset example
+        `output`: The output of the task
+        `expected`: The expected or reference output of the dataset example
+        `reference`: An alias for `expected`
+        `metadata`: Metadata associated with the dataset example
+
+    Phoenix also provides pre-built evaluators in the `phoenix.experiments.evaluators` module.
+
+    Args:
+        dataset (Dataset): The dataset on which to run the experiment.
+        task (ExperimentTask): The task to run on each example in the dataset.
+        evaluators (Optional[Evaluators]): A single evaluator or sequence of evaluators used to
+            evaluate the results of the experiment. Defaults to None.
+        experiment_name (Optional[str]): The name of the experiment. Defaults to None.
+        experiment_description (Optional[str]): A description of the experiment. Defaults to None.
+        experiment_metadata (Optional[Mapping[str, Any]]): Metadata to associate with the
+            experiment. Defaults to None.
+        rate_limit_errors (Optional[BaseException | Sequence[BaseException]]): An exception or
+            sequence of exceptions to adaptively throttle on. Defaults to None.
+        dry_run (bool | int): R the experiment in dry-run mode. When set, experiment results will
+            not be recorded in Phoenix. If True, the experiment will run on a random dataset
+            example. If an integer, the experiment will run on a random sample of the dataset
+            examples of the given size. Defaults to False.
+        print_summary (bool): Whether to print a summary of the experiment and evaluation results.
+            Defaults to True.
+
+    Returns:
+        RanExperiment: The results of the experiment and evaluation. Additional evaluations can be
+            added to the experiment using the `evaluate_experiment` function.
+    """
+    task_signature = inspect.signature(task)
+    _validate_task_signature(task_signature)
+
     if not dataset.examples:
         raise ValueError(f"Dataset has no examples: {dataset.id=}, {dataset.version_id=}")
     # Add this to the params once supported in the UI
@@ -146,7 +204,7 @@ def run_experiment(
         )
 
     tracer, resource = _get_tracer(experiment.project_name)
-    root_span_name = f"Task: {_get_task_name(task)}"
+    root_span_name = f"Task: {get_func_name(task)}"
     root_span_kind = CHAIN
 
     print("🧪 Experiment started.")
@@ -183,25 +241,37 @@ def run_experiment(
                 # Do not use keyword arguments, which can fail at runtime
                 # even when function obeys protocol, because keyword arguments
                 # are implementation details.
-                _output = task(example)
+                bound_task_args = _bind_task_signature(task_signature, example)
+                _output = task(*bound_task_args.args, **bound_task_args.kwargs)
                 if isinstance(_output, Awaitable):
-                    raise RuntimeError("Task is async but running in sync context")
+                    sync_error_message = (
+                        "Task is async and cannot be run within an existing event loop. "
+                        "Consider the following options:\n\n"
+                        "1. Pass in a synchronous task callable.\n"
+                        "2. Use `nest_asyncio.apply()` to allow nesting event loops."
+                    )
+                    raise RuntimeError(sync_error_message)
                 else:
                     output = _output
             except BaseException as exc:
                 span.record_exception(exc)
                 status = Status(StatusCode.ERROR, f"{type(exc).__name__}: {exc}")
                 error = exc
+                _print_experiment_error(
+                    exc,
+                    example_id=example.id,
+                    repetition_number=repetition_number,
+                    kind="task",
+                )
             output = jsonify(output)
             span.set_attribute(INPUT_VALUE, json.dumps(example.input, ensure_ascii=False))
             span.set_attribute(INPUT_MIME_TYPE, JSON.value)
-            if result := ExperimentResult(result=output) if output is not None else None:
+            if output is not None:
                 if isinstance(output, str):
                     span.set_attribute(OUTPUT_VALUE, output)
                 else:
                     span.set_attribute(OUTPUT_VALUE, json.dumps(output, ensure_ascii=False))
                     span.set_attribute(OUTPUT_MIME_TYPE, JSON.value)
-                span.set_attributes(dict(flatten(jsonify(result), recurse_on_sequence=True)))
             span.set_attribute(SpanAttributes.OPENINFERENCE_SPAN_KIND, root_span_kind)
             span.set_status(status)
 
@@ -214,7 +284,7 @@ def run_experiment(
             experiment_id=experiment.id,
             dataset_example_id=example.id,
             repetition_number=repetition_number,
-            output=result,
+            experiment_run_output=ExperimentRunOutput(task_output=output),
             error=repr(error) if error else None,
             trace_id=_str_trace_id(span.get_span_context().trace_id),  # type: ignore[no-untyped-call]
         )
@@ -238,7 +308,8 @@ def run_experiment(
                 # Do not use keyword arguments, which can fail at runtime
                 # even when function obeys protocol, because keyword arguments
                 # are implementation details.
-                _output = task(example)
+                bound_task_args = _bind_task_signature(task_signature, example)
+                _output = task(*bound_task_args.args, **bound_task_args.kwargs)
                 if isinstance(_output, Awaitable):
                     output = await _output
                 else:
@@ -247,16 +318,21 @@ def run_experiment(
                 span.record_exception(exc)
                 status = Status(StatusCode.ERROR, f"{type(exc).__name__}: {exc}")
                 error = exc
+                _print_experiment_error(
+                    exc,
+                    example_id=example.id,
+                    repetition_number=repetition_number,
+                    kind="task",
+                )
             output = jsonify(output)
             span.set_attribute(INPUT_VALUE, json.dumps(example.input, ensure_ascii=False))
             span.set_attribute(INPUT_MIME_TYPE, JSON.value)
-            if result := ExperimentResult(result=output) if output is not None else None:
+            if output is not None:
                 if isinstance(output, str):
                     span.set_attribute(OUTPUT_VALUE, output)
                 else:
                     span.set_attribute(OUTPUT_VALUE, json.dumps(output, ensure_ascii=False))
                     span.set_attribute(OUTPUT_MIME_TYPE, JSON.value)
-                span.set_attributes(dict(flatten(jsonify(result), recurse_on_sequence=True)))
             span.set_attribute(OPENINFERENCE_SPAN_KIND, root_span_kind)
             span.set_status(status)
 
@@ -269,7 +345,7 @@ def run_experiment(
             experiment_id=experiment.id,
             dataset_example_id=example.id,
             repetition_number=repetition_number,
-            output=result,
+            experiment_run_output=ExperimentRunOutput(task_output=output),
             error=repr(error) if error else None,
             trace_id=_str_trace_id(span.get_span_context().trace_id),  # type: ignore[no-untyped-call]
         )
@@ -422,8 +498,9 @@ def evaluate_experiment(
             stack.enter_context(capture_spans(resource))
             try:
                 result = evaluator.evaluate(
-                    output=experiment_run.task_output,
+                    output=experiment_run.output,
                     expected=example.output,
+                    reference=example.output,
                     input=example.input,
                     metadata=example.metadata,
                 )
@@ -431,6 +508,12 @@ def evaluate_experiment(
                 span.record_exception(exc)
                 status = Status(StatusCode.ERROR, f"{type(exc).__name__}: {exc}")
                 error = exc
+                _print_experiment_error(
+                    exc,
+                    example_id=example.id,
+                    repetition_number=experiment_run.repetition_number,
+                    kind="evaluator",
+                )
             if result:
                 span.set_attributes(dict(flatten(jsonify(result), recurse_on_sequence=True)))
             span.set_attribute(OPENINFERENCE_SPAN_KIND, root_span_kind)
@@ -467,8 +550,9 @@ def evaluate_experiment(
             stack.enter_context(capture_spans(resource))
             try:
                 result = await evaluator.async_evaluate(
-                    output=experiment_run.task_output,
+                    output=experiment_run.output,
                     expected=example.output,
+                    reference=example.output,
                     input=example.input,
                     metadata=example.metadata,
                 )
@@ -476,6 +560,12 @@ def evaluate_experiment(
                 span.record_exception(exc)
                 status = Status(StatusCode.ERROR, f"{type(exc).__name__}: {exc}")
                 error = exc
+                _print_experiment_error(
+                    exc,
+                    example_id=example.id,
+                    repetition_number=experiment_run.repetition_number,
+                    kind="evaluator",
+                )
             if result:
                 span.set_attributes(dict(flatten(jsonify(result), recurse_on_sequence=True)))
             span.set_attribute(OPENINFERENCE_SPAN_KIND, root_span_kind)
@@ -584,20 +674,71 @@ def _decode_unix_nano(time_unix_nano: int) -> datetime:
     return datetime.fromtimestamp(time_unix_nano / 1e9, tz=timezone.utc)
 
 
-def _get_task_name(task: ExperimentTask) -> str:
-    """
-    Makes a best-effort attempt to get the name of the task.
-    """
+def _is_dry_run(obj: Any) -> bool:
+    return hasattr(obj, "id") and isinstance(obj.id, str) and obj.id.startswith(DRY_RUN)
 
-    if isinstance(task, functools.partial):
-        return task.func.__qualname__
-    if hasattr(task, "__qualname__"):
-        return task.__qualname__
-    return str(task)
 
+def _validate_task_signature(sig: inspect.Signature) -> None:
+    # Check that the function signature has a valid signature for use as a task
+    # If it does not, raise an error to exit early before running an experiment
+    params = sig.parameters
+    valid_named_params = {"input", "expected", "reference", "metadata", "example"}
+    if len(params) == 0:
+        raise ValueError("Task function must have at least one parameter.")
+    if len(params) > 1:
+        for not_found in set(params) - valid_named_params:
+            param = params[not_found]
+            if (
+                param.kind is inspect.Parameter.VAR_KEYWORD
+                or param.default is not inspect.Parameter.empty
+            ):
+                continue
+            raise ValueError(
+                (
+                    f"Invalid parameter names in task function: {', '.join(not_found)}. "
+                    "Parameters names for multi-argument functions must be "
+                    f"any of: {', '.join(valid_named_params)}."
+                )
+            )
 
-def _is_dry_run(obj: Any) -> bool:
-    return hasattr(obj, "id") and isinstance(obj.id, str) and obj.id.startswith(DRY_RUN)
+
+def _bind_task_signature(sig: inspect.Signature, example: Example) -> inspect.BoundArguments:
+    parameter_mapping = {
+        "input": example.input,
+        "expected": example.output,
+        "reference": example.output,  # Alias for "expected"
+        "metadata": example.metadata,
+        "example": example,
+    }
+    params = sig.parameters
+    if len(params) == 1:
+        parameter_name = next(iter(params))
+        if parameter_name in parameter_mapping:
+            return sig.bind(parameter_mapping[parameter_name])
+        else:
+            return sig.bind(parameter_mapping["input"])
+    return sig.bind_partial(
+        **{name: parameter_mapping[name] for name in set(parameter_mapping).intersection(params)}
+    )
+
+
+def _print_experiment_error(
+    error: BaseException,
+    /,
+    *,
+    example_id: str,
+    repetition_number: int,
+    kind: Literal["evaluator", "task"],
+) -> None:
+    """
+    Prints an experiment error.
+    """
+    display_error = RuntimeError(
+        f"{kind} failed for example id {repr(example_id)}, " f"repetition {repr(repetition_number)}"
+    )
+    display_error.__cause__ = error
+    formatted_exception = "".join(traceback.format_exception(display_error))  # type: ignore[arg-type, call-arg, unused-ignore]
+    print("\033[91m" + formatted_exception + "\033[0m")  # prints in red
 
 
 class _NoOpProcessor(trace_sdk.SpanProcessor):

{arize_phoenix-4.4.4rc6 → arize_phoenix-4.6.1}/src/phoenix/experiments/types.py

@@ -103,9 +103,9 @@ class Example:
         identifiers = [f'{spaces}id="{self.id}",']
         contents = [
             spaces
-            + f"{k}="
+            + f"{_blue(key)}="
             + json.dumps(
-                _shorten(v),
+                _shorten(value),
                 ensure_ascii=False,
                 sort_keys=True,
                 indent=len(spaces),
@@ -113,8 +113,8 @@ class Example:
             .replace("\n", f"\n{spaces}")
             .replace(' "..."\n', " ...\n")
             + ","
-            for k in ("input", "output", "metadata")
-            if (v := getattr(self, k, None))
+            for key in ("input", "output", "metadata")
+            if (value := getattr(self, key, None))
         ]
         return "\n".join([f"{name}(", *identifiers, *contents, ")"])
 
@@ -199,17 +199,17 @@ class Experiment:
 
 
 @dataclass(frozen=True)
-class ExperimentResult:
-    result: TaskOutput
+class ExperimentRunOutput:
+    task_output: TaskOutput
 
     def __post_init__(self) -> None:
-        object.__setattr__(self, "result", _make_read_only(self.result))
+        object.__setattr__(self, "task_output", _make_read_only(self.task_output))
 
     @classmethod
-    def from_dict(cls, obj: Optional[Mapping[str, Any]]) -> Optional[ExperimentResult]:
+    def from_dict(cls, obj: Optional[Mapping[str, Any]]) -> ExperimentRunOutput:
         if not obj:
-            return None
-        return cls(result=obj["result"])
+            return cls(task_output=None)
+        return cls(task_output=obj["task_output"])
 
 
 @dataclass(frozen=True)
@@ -219,14 +219,14 @@ class ExperimentRun:
     experiment_id: ExperimentId
     dataset_example_id: ExampleId
     repetition_number: RepetitionNumber
-    output: Optional[ExperimentResult] = None
+    experiment_run_output: ExperimentRunOutput
     error: Optional[str] = None
     id: ExperimentRunId = field(default_factory=_dry_run_id)
     trace_id: Optional[TraceId] = None
 
     @property
-    def task_output(self) -> Optional[TaskOutput]:
-        return deepcopy(self.output.result) if self.output else None
+    def output(self) -> Optional[TaskOutput]:
+        return deepcopy(self.experiment_run_output.task_output)
 
     @classmethod
     def from_dict(cls, obj: Mapping[str, Any]) -> ExperimentRun:
@@ -236,15 +236,15 @@ class ExperimentRun:
             experiment_id=obj["experiment_id"],
             dataset_example_id=obj["dataset_example_id"],
             repetition_number=obj.get("repetition_number") or 1,
-            output=ExperimentResult.from_dict(obj["output"]),
+            experiment_run_output=ExperimentRunOutput.from_dict(obj["experiment_run_output"]),
             error=obj.get("error"),
             id=obj["id"],
             trace_id=obj.get("trace_id"),
         )
 
     def __post_init__(self) -> None:
-        if bool(self.output) == bool(self.error):
-            ValueError("Must specify either result or error")
+        if bool(self.experiment_run_output) == bool(self.error):
+            ValueError("Must specify exactly one of experiment_run_output or error")
 
 
 @dataclass(frozen=True)
@@ -571,7 +571,7 @@ class RanExperiment(Experiment):
                 {
                     "run_id": run.id,
                     "error": run.error,
-                    "result": deepcopy(run.output.result) if run.output else None,
+                    "output": deepcopy(run.experiment_run_output.task_output),
                     "input": deepcopy((ex := self.dataset.examples[run.dataset_example_id]).input),
                     "expected": deepcopy(ex.output),
                     "metadata": deepcopy(ex.metadata),
@@ -688,6 +688,10 @@ class _ExperimentRunWithExample(ObjectProxy):  # type: ignore[misc]
     def expected(self) -> ExampleOutput:
         return deepcopy(self._self_example.output)
 
+    @property
+    def reference(self) -> ExampleOutput:
+        return deepcopy(self._self_example.output)
+
     @property
     def input(self) -> ExampleInput:
         return deepcopy(self._self_example.input)
@@ -703,20 +707,47 @@ class _ExperimentRunWithExample(ObjectProxy):  # type: ignore[misc]
             f'{spaces}id="{self.id}",',
             f'{spaces}example_id="{self.dataset_example_id}",',
         ]
-        contents = [
+        outputs = [
+            *([f'{spaces}error="{self.error}",'] if self.error else []),
+            *(
+                [
+                    f"{spaces}{_blue('output')}="
+                    + json.dumps(
+                        _shorten(self.output),
+                        ensure_ascii=False,
+                        sort_keys=True,
+                        indent=len(spaces),
+                    )
+                    .replace("\n", f"\n{spaces}")
+                    .replace(' "..."\n', " ...\n")
+                ]
+                if not self.error
+                else []
+            ),
+        ]
+        dicts = [
             spaces
-            + f"{k}="
-            + json.dumps(_shorten(v), ensure_ascii=False, sort_keys=True, indent=len(spaces))
+            + f"{_blue(alias)}={{"
+            + (f" # {comment}" if comment else "")
+            + json.dumps(
+                _shorten(value),
+                ensure_ascii=False,
+                sort_keys=True,
+                indent=len(spaces),
+            )[1:]
             .replace("\n", f"\n{spaces}")
             .replace(' "..."\n', " ...\n")
             + ","
-            for k, v in {
-                "error": self.error,
-                "output": self.task_output,
-                "expected": self.expected,
-                "input": self.input,
-                "metadata": self.metadata,
-            }.items()
-            if v
+            for alias, value, comment in (
+                ("expected", self.expected, f"alias for the example.{_blue('output')} dict"),
+                ("reference", self.reference, f"alias for the example.{_blue('output')} dict"),
+                ("input", self.input, f"alias for the example.{_blue('input')} dict"),
+                ("metadata", self.metadata, f"alias for the example.{_blue('metadata')} dict"),
+            )
+            if value
         ]
-        return "\n".join([f"{name}(", *identifiers, *contents, ")"])
+        return "\n".join([f"{name}(", *identifiers, *outputs, *dicts, ")"])
+
+
+def _blue(text: str) -> str:
+    return f"\033[1m\033[94m{text}\033[0m"