arize-phoenix 3.16.0__py3-none-any.whl → 7.7.0__py3-none-any.whl

phoenix/trace/dsl/filter.py

@@ -1,199 +1,542 @@
 import ast
-import inspect
+import re
 import sys
+import typing
 from dataclasses import dataclass, field
 from difflib import SequenceMatcher
-from typing import (
-    Any,
-    Dict,
-    Iterable,
-    Iterator,
-    Mapping,
-    Optional,
-    Protocol,
-    Sequence,
-    Tuple,
-    cast,
-)
+from itertools import chain
+from types import MappingProxyType
+from uuid import uuid4
 
-from openinference.semconv import trace
-from typing_extensions import TypeGuard
+import sqlalchemy
+from sqlalchemy.orm import Mapped, aliased
+from sqlalchemy.orm.util import AliasedClass
+from sqlalchemy.sql.expression import Select
+from typing_extensions import TypeAlias, TypeGuard, assert_never
 
 import phoenix.trace.v1 as pb
-from phoenix.trace.dsl.missing import MISSING
-from phoenix.trace.schemas import ComputedAttributes, Span, SpanID
+from phoenix.db import models
 
-_VALID_EVAL_ATTRIBUTES: Tuple[str, ...] = tuple(
+_VALID_EVAL_ATTRIBUTES: tuple[str, ...] = tuple(
     field.name for field in pb.Evaluation.Result.DESCRIPTOR.fields
 )
 
 
-class SupportsGetSpanEvaluation(Protocol):
-    def get_span_evaluation(self, span_id: SpanID, name: str) -> Optional[pb.Evaluation]: ...
+AnnotationType: TypeAlias = typing.Literal["annotations", "evals"]
+AnnotationAttribute: TypeAlias = typing.Literal["label", "score"]
+AnnotationExpression: TypeAlias = str
+AnnotationName: TypeAlias = str
+
+EVAL_EXPRESSION_PATTERN = re.compile(
+    r"""\b((annotations|evals)\[(".*?"|'.*?')\][.](label|score))\b"""
+)
+
+
+@dataclass(frozen=True)
+class AliasedAnnotationRelation:
+    """
+    Represents an aliased `span_annotation` relation (i.e., SQL table). Used to
+    perform joins on span evaluations during filtering. An alias is required
+    because the `span_annotation` may be joined multiple times for different
+    evaluation names.
+    """
+
+    index: int
+    name: str
+    table: AliasedClass[models.SpanAnnotation] = field(init=False, repr=False)
+    _label_attribute_alias: str = field(init=False, repr=False)
+    _score_attribute_alias: str = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        table_alias = f"span_annotation_{self.index}"
+        alias_id = uuid4().hex
+        label_attribute_alias = f"{table_alias}_label_{alias_id}"
+        score_attribute_alias = f"{table_alias}_score_{alias_id}"
+
+        table = aliased(models.SpanAnnotation, name=table_alias)
+        object.__setattr__(self, "_label_attribute_alias", label_attribute_alias)
+        object.__setattr__(self, "_score_attribute_alias", score_attribute_alias)
+        object.__setattr__(self, "table", table)
+
+    @property
+    def attributes(self) -> typing.Iterator[tuple[str, Mapped[typing.Any]]]:
+        """
+        Alias names and attributes (i.e., columns) of the `span_annotation`
+        relation.
+        """
+        yield self._label_attribute_alias, self.table.label
+        yield self._score_attribute_alias, self.table.score
+
+    def attribute_alias(self, attribute: AnnotationAttribute) -> str:
+        """
+        Returns an alias for the given attribute (i.e., column).
+        """
+        if attribute == "label":
+            return self._label_attribute_alias
+        if attribute == "score":
+            return self._score_attribute_alias
+        assert_never(attribute)
+
+
+# Because postgresql is strongly typed, we cast JSON values to string
+# by default unless it's hinted otherwise as done here.
+_FLOAT_ATTRIBUTES: frozenset[str] = frozenset(
+    {
+        "llm.token_count.completion",
+        "llm.token_count.prompt",
+        "llm.token_count.total",
+    }
+)
+
+_STRING_NAMES: typing.Mapping[str, sqlalchemy.SQLColumnExpression[typing.Any]] = MappingProxyType(
+    {
+        "span_id": models.Span.span_id,
+        "trace_id": models.Trace.trace_id,
+        "context.span_id": models.Span.span_id,
+        "context.trace_id": models.Trace.trace_id,
+        "parent_id": models.Span.parent_id,
+        "span_kind": models.Span.span_kind,
+        "name": models.Span.name,
+        "status_code": models.Span.status_code,
+        "status_message": models.Span.status_message,
+    }
+)
+_FLOAT_NAMES: typing.Mapping[str, sqlalchemy.SQLColumnExpression[typing.Any]] = MappingProxyType(
+    {
+        "latency_ms": models.Span.latency_ms,
+        "cumulative_llm_token_count_completion": models.Span.cumulative_llm_token_count_completion,
+        "cumulative_llm_token_count_prompt": models.Span.cumulative_llm_token_count_prompt,
+        "cumulative_llm_token_count_total": models.Span.cumulative_llm_token_count_total,
+    }
+)
+_DATETIME_NAMES: typing.Mapping[str, sqlalchemy.SQLColumnExpression[typing.Any]] = MappingProxyType(
+    {
+        "start_time": models.Span.start_time,
+        "end_time": models.Span.end_time,
+    }
+)
+_NAMES: typing.Mapping[str, sqlalchemy.SQLColumnExpression[typing.Any]] = MappingProxyType(
+    {
+        **_STRING_NAMES,
+        **_FLOAT_NAMES,
+        **_DATETIME_NAMES,
+        "attributes": models.Span.attributes,
+        "events": models.Span.events,
+    }
+)
+_BACKWARD_COMPATIBILITY_REPLACEMENTS: typing.Mapping[str, str] = MappingProxyType(
+    {
+        # for backward-compatibility
+        "context.span_id": "span_id",
+        "context.trace_id": "trace_id",
+        "cumulative_token_count.completion": "cumulative_llm_token_count_completion",
+        "cumulative_token_count.prompt": "cumulative_llm_token_count_prompt",
+        "cumulative_token_count.total": "cumulative_llm_token_count_total",
+    }
+)
 
 
 @dataclass(frozen=True)
 class SpanFilter:
     condition: str = ""
-    evals: Optional[SupportsGetSpanEvaluation] = None
-    valid_eval_names: Optional[Sequence[str]] = None
+    valid_eval_names: typing.Optional[typing.Sequence[str]] = None
     translated: ast.Expression = field(init=False, repr=False)
-    compiled: Any = field(init=False, repr=False)
+    compiled: typing.Any = field(init=False, repr=False)
+    _aliased_annotation_relations: tuple[AliasedAnnotationRelation] = field(init=False, repr=False)
+    _aliased_annotation_attributes: dict[str, Mapped[typing.Any]] = field(init=False, repr=False)
 
     def __bool__(self) -> bool:
         return bool(self.condition)
 
     def __post_init__(self) -> None:
-        condition = self.condition or "True"  # default to no op
-        root = ast.parse(condition, mode="eval")
-        if self.condition:
-            _validate_expression(root, condition, valid_eval_names=self.valid_eval_names)
-        translated = _Translator(condition).visit(root)
+        if not (source := self.condition):
+            return
+        root = ast.parse(source, mode="eval")
+        _validate_expression(root, valid_eval_names=self.valid_eval_names)
+        source, aliased_annotation_relations = _apply_eval_aliasing(source)
+        root = ast.parse(source, mode="eval")
+        translated = _FilterTranslator(
+            reserved_keywords=(
+                alias
+                for aliased_annotation in aliased_annotation_relations
+                for alias, _ in aliased_annotation.attributes
+            ),
+        ).visit(root)
         ast.fix_missing_locations(translated)
         compiled = compile(translated, filename="", mode="eval")
+        aliased_annotation_attributes = {
+            alias: attribute
+            for aliased_annotation in aliased_annotation_relations
+            for alias, attribute in aliased_annotation.attributes
+        }
         object.__setattr__(self, "translated", translated)
         object.__setattr__(self, "compiled", compiled)
-        object.__setattr__(self, "evals", self.evals or MISSING)
+        object.__setattr__(self, "_aliased_annotation_relations", aliased_annotation_relations)
+        object.__setattr__(self, "_aliased_annotation_attributes", aliased_annotation_attributes)
 
-    def __call__(self, span: Span) -> bool:
-        return cast(
-            bool,
+    def __call__(self, select: Select[typing.Any]) -> Select[typing.Any]:
+        if not self.condition:
+            return select
+        return self._join_aliased_relations(select).where(
             eval(
                 self.compiled,
-                {"span": span, "_MISSING": MISSING, "evals": self.evals},
-            ),
+                {
+                    **_NAMES,
+                    **self._aliased_annotation_attributes,
+                    "not_": sqlalchemy.not_,
+                    "and_": sqlalchemy.and_,
+                    "or_": sqlalchemy.or_,
+                    "cast": sqlalchemy.cast,
+                    "Float": sqlalchemy.Float,
+                    "String": sqlalchemy.String,
+                    "TextContains": models.TextContains,
+                },
+            )
         )
 
-    def to_dict(self) -> Dict[str, Any]:
+    def to_dict(self) -> dict[str, typing.Any]:
         return {"condition": self.condition}
 
     @classmethod
     def from_dict(
         cls,
-        obj: Mapping[str, Any],
-        evals: Optional[SupportsGetSpanEvaluation] = None,
-        valid_eval_names: Optional[Sequence[str]] = None,
+        obj: typing.Mapping[str, typing.Any],
+        valid_eval_names: typing.Optional[typing.Sequence[str]] = None,
     ) -> "SpanFilter":
         return cls(
             condition=obj.get("condition") or "",
-            evals=evals,
             valid_eval_names=valid_eval_names,
         )
 
+    def _join_aliased_relations(self, stmt: Select[typing.Any]) -> Select[typing.Any]:
+        """
+        Joins the aliased relations to the given statement. E.g., for the filter condition:
+
+        ```
+        evals["Hallucination"].score > 0.5
+        ```
+
+        an alias (e.g., `A`) is generated for the `span_annotations` relation. An input statement
+        `select(Span)` is transformed to:
+
+        ```
+        A = aliased(SpanAnnotation)
+        select(Span).join(A, onclause=(and_(Span.id == A.span_rowid, A.name == "Hallucination")))
+        ```
+        """
+        for eval_alias in self._aliased_annotation_relations:
+            eval_name = eval_alias.name
+            AliasedSpanAnnotation = eval_alias.table
+            stmt = stmt.outerjoin(
+                AliasedSpanAnnotation,
+                onclause=(
+                    sqlalchemy.and_(
+                        AliasedSpanAnnotation.span_rowid == models.Span.id,
+                        AliasedSpanAnnotation.name == eval_name,
+                    )
+                ),
+            )
+        return stmt
 
-def _replace_none_with_missing(
-    value: ast.expr,
-    as_str: bool = False,
-) -> ast.IfExp:
-    """
-    E.g. `value` becomes
-    `_MISSING if (_VALUE := value) is None else _VALUE`
-    """
-    _store_VALUE = ast.Name(id="_VALUE", ctx=ast.Store())
-    _load_VALUE = ast.Name(id="_VALUE", ctx=ast.Load())
-    return ast.IfExp(
-        test=ast.Compare(
-            left=ast.NamedExpr(target=_store_VALUE, value=value),
-            ops=[ast.Is()],
-            comparators=[ast.Constant(value=None)],
+
+@dataclass(frozen=True)
+class Projector:
+    expression: str
+    translated: ast.Expression = field(init=False, repr=False)
+    compiled: typing.Any = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        if not (source := self.expression):
+            raise ValueError("missing expression")
+        root = ast.parse(source, mode="eval")
+        translated = _ProjectionTranslator(source).visit(root)
+        ast.fix_missing_locations(translated)
+        compiled = compile(translated, filename="", mode="eval")
+        object.__setattr__(self, "translated", translated)
+        object.__setattr__(self, "compiled", compiled)
+
+    def __call__(self) -> sqlalchemy.SQLColumnExpression[typing.Any]:
+        return typing.cast(
+            sqlalchemy.SQLColumnExpression[typing.Any],
+            eval(self.compiled, {**_NAMES}),
+        )
+
+
+def _is_string_constant(node: typing.Any) -> TypeGuard[ast.Constant]:
+    return isinstance(node, ast.Constant) and isinstance(node.value, str)
+
+
+def _is_float_constant(node: typing.Any) -> TypeGuard[ast.Constant]:
+    return isinstance(node, ast.Constant) and isinstance(node.value, typing.SupportsFloat)
+
+
+def _is_string_attribute(node: typing.Any) -> TypeGuard[ast.Call]:
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(func := node.func, ast.Attribute)
+        and func.attr == "as_string"
+        and isinstance(value := func.value, ast.Subscript)
+        and isinstance(name := value.value, ast.Name)
+        and name.id == "attributes"
+    )
+
+
+def _is_float_attribute(node: typing.Any) -> TypeGuard[ast.Call]:
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(func := node.func, ast.Attribute)
+        and func.attr == "as_float"
+        and isinstance(value := func.value, ast.Subscript)
+        and isinstance(name := value.value, ast.Name)
+        and name.id == "attributes"
+    )
+
+
+def _as_string_attribute(node: typing.Union[ast.Subscript, ast.Call]) -> ast.Call:
+    if isinstance(node, ast.Call):
+        value = typing.cast(ast.Attribute, node.func).value
+    elif isinstance(node, ast.Subscript):
+        value = node
+    else:
+        assert_never(node)
+    return ast.Call(
+        func=ast.Attribute(
+            value=value,
+            attr="as_string",
+            ctx=ast.Load(),
+        ),
+        args=[],
+        keywords=[],
+    )
+
+
+def _as_float_attribute(node: typing.Union[ast.Subscript, ast.Call]) -> ast.Call:
+    if isinstance(node, ast.Call):
+        value = typing.cast(ast.Attribute, node.func).value
+    elif isinstance(node, ast.Subscript):
+        value = node
+    else:
+        assert_never(node)
+    return ast.Call(
+        func=ast.Attribute(
+            value=value,
+            attr="as_float",
+            ctx=ast.Load(),
         ),
-        body=ast.Name(id="_MISSING", ctx=ast.Load()),
-        orelse=_as_str(_load_VALUE) if as_str else _load_VALUE,
+        args=[],
+        keywords=[],
     )
 
 
-def _as_str(value: ast.expr) -> ast.Call:
-    """E.g. `value` becomes `str(value)`"""
-    return ast.Call(func=ast.Name(id="str", ctx=ast.Load()), args=[value], keywords=[])
+def _is_cast(
+    node: typing.Any,
+    type_: typing.Optional[typing.Literal["Float", "String"]] = None,
+) -> TypeGuard[ast.Call]:
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(func := node.func, ast.Name)
+        and func.id == "cast"
+        and len(node.args) == 2
+        and isinstance(name := node.args[1], ast.Name)
+        and (not type_ or name.id == type_)
+    )
 
 
-def _ast_replacement(expression: str) -> ast.expr:
-    as_str = expression in (
-        "span.status_code",
-        "span.span_kind",
-        "span.parent_id",
-        "span.context.span_id",
-        "span.context.trace_id",
+def _remove_cast(node: typing.Any) -> typing.Any:
+    return node.args[0] if _is_cast(node) else node
+
+
+def _cast_as(
+    type_: typing.Literal["Float", "String"],
+    node: typing.Any,
+) -> ast.Call:
+    if type_ == "Float" and (_is_subscript(node, "attributes") or _is_string_attribute(node)):
+        return _as_float_attribute(node)
+    if type_ == "String" and (_is_subscript(node, "attributes") or _is_float_attribute(node)):
+        return _as_string_attribute(node)
+    return ast.Call(
+        func=ast.Name(id="cast", ctx=ast.Load()),
+        args=[
+            _remove_cast(node),
+            ast.Name(id=type_, ctx=ast.Load()),
+        ],
+        keywords=[],
     )
-    return _replace_none_with_missing(ast.parse(expression, mode="eval").body, as_str)
-
-
-def _allowed_replacements() -> Iterator[Tuple[str, ast.expr]]:
-    for source_segment, ast_replacement in {
-        "name": _ast_replacement("span.name"),
-        "status_code": _ast_replacement("span.status_code"),
-        "span_kind": _ast_replacement("span.span_kind"),
-        "parent_id": _ast_replacement("span.parent_id"),
-    }.items():
-        yield source_segment, ast_replacement
-        yield "span." + source_segment, ast_replacement
-
-    for source_segment, ast_replacement in {
-        "span_id": _ast_replacement("span.context.span_id"),
-        "trace_id": _ast_replacement("span.context.trace_id"),
-    }.items():
-        yield source_segment, ast_replacement
-        yield "context." + source_segment, ast_replacement
-        yield "span.context." + source_segment, ast_replacement
-
-    for field_name in (
-        getattr(klass, attr)
-        for name in dir(trace)
-        if name.endswith("Attributes") and inspect.isclass(klass := getattr(trace, name))
-        for attr in dir(klass)
-        if attr.isupper()
-    ):
-        source_segment = field_name
-        ast_replacement = _ast_replacement(f"span.attributes.get('{field_name}')")
-        yield source_segment, ast_replacement
-        yield "attributes." + source_segment, ast_replacement
-        yield "span.attributes." + source_segment, ast_replacement
-
-    for computed_attribute in ComputedAttributes:
-        source_segment = computed_attribute.value
-        ast_replacement = _ast_replacement(f"span.get_computed_value('{source_segment}')")
-        yield source_segment, ast_replacement
-
-
-class _Translator(ast.NodeTransformer):
-    _allowed_fields: Mapping[str, ast.expr] = dict(_allowed_replacements())
-
-    def __init__(self, source: str) -> None:
-        # Regarding the need for `source: str` for getting source segments:
-        # In Python 3.8, we have to use `ast.get_source_segment(source, node)`.
-        # In Python 3.9+, we can use `ast.unparse(node)` (no need for `source`).
-        self._source = source
-
-    def visit_Subscript(self, node: ast.Subscript) -> Any:
-        if _is_metadata(node) and (key := _get_subscript_key(node)):
-            return _ast_metadata_subscript(key)
-        source_segment: str = cast(str, ast.get_source_segment(self._source, node))
-        raise SyntaxError(f"invalid expression: {source_segment}")  # TODO: add details
-
-    def visit_Attribute(self, node: ast.Attribute) -> Any:
-        if _is_eval(node.value) and (eval_name := _get_subscript_key(node.value)):
-            # e.g. `evals["name"].score`
-            return _ast_evaluation_result_value(eval_name, node.attr)
-        source_segment: str = cast(str, ast.get_source_segment(self._source, node))
-        if replacement := self._allowed_fields.get(source_segment):
-            return replacement
-        raise SyntaxError(f"invalid expression: {source_segment}")  # TODO: add details
 
-    def visit_Name(self, node: ast.Name) -> Any:
-        source_segment: str = cast(str, ast.get_source_segment(self._source, node))
-        if replacement := self._allowed_fields.get(source_segment):
-            return replacement
-        raise SyntaxError(f"invalid expression: {source_segment}")  # TODO: add details
 
-    def visit_Constant(self, node: ast.Constant) -> Any:
-        return ast.Name(id="_MISSING", ctx=ast.Load()) if node.value is None else node
+def _is_string(node: typing.Any) -> TypeGuard[ast.Call]:
+    return (
+        isinstance(node, ast.Name)
+        and node.id in _STRING_NAMES
+        or _is_cast(node, "String")
+        or _is_string_constant(node)
+        or _is_string_attribute(node)
+        or isinstance(node, (ast.List, ast.Tuple))
+        and len(node.elts) > 0
+        and _is_string(node.elts[0])
+    )
+
+
+def _is_float(node: typing.Any) -> TypeGuard[ast.Call]:
+    return (
+        isinstance(node, ast.Name)
+        and node.id in _FLOAT_NAMES
+        or _is_cast(node, "Float")
+        or _is_float_constant(node)
+        or _is_float_attribute(node)
+        or isinstance(node, (ast.List, ast.Tuple))
+        and len(node.elts) > 0
+        and _is_float(node.elts[0])
+        or isinstance(node, ast.BinOp)
+        and (not isinstance(node.op, ast.Add) or (_is_float(node.left) or _is_float(node.right)))
+        or isinstance(node, ast.UnaryOp)
+        and isinstance(node.op, (ast.USub, ast.UAdd))
+    )
+
+
+class _ProjectionTranslator(ast.NodeTransformer):
+    def __init__(self, reserved_keywords: typing.Iterable[str] = ()) -> None:
+        self._reserved_keywords = frozenset(
+            chain(
+                reserved_keywords,
+                _STRING_NAMES.keys(),
+                _FLOAT_NAMES.keys(),
+                _DATETIME_NAMES.keys(),
+            )
+        )
+
+    def visit_generic(self, node: ast.AST) -> typing.Any:
+        raise SyntaxError(f"invalid expression: {ast.unparse(node)}")
+
+    def visit_Expression(self, node: ast.Expression) -> typing.Any:
+        return ast.Expression(body=self.visit(node.body))
+
+    def visit_Attribute(self, node: ast.Attribute) -> typing.Any:
+        source_segment = ast.unparse(node)
+        if replacement := _BACKWARD_COMPATIBILITY_REPLACEMENTS.get(source_segment):
+            return ast.Name(id=replacement, ctx=ast.Load())
+        if (keys := _get_attribute_keys_list(node)) is not None:
+            return _as_attribute(keys)
+        raise SyntaxError(f"invalid expression: {source_segment}")
+
+    def visit_Name(self, node: ast.Name) -> typing.Any:
+        source_segment = ast.unparse(node)
+        if source_segment in self._reserved_keywords:
+            return node
+        name = source_segment
+        return _as_attribute([ast.Constant(value=name, kind=None)])
+
+    def visit_Subscript(self, node: ast.Subscript) -> typing.Any:
+        if (keys := _get_attribute_keys_list(node)) is not None:
+            return _as_attribute(keys)
+        raise SyntaxError(f"invalid expression: {ast.unparse(node)}")
+
+
+class _FilterTranslator(_ProjectionTranslator):
+    def visit_Compare(self, node: ast.Compare) -> typing.Any:
+        if len(node.comparators) > 1:
+            args: list[typing.Any] = []
+            left = node.left
+            for i, (op, comparator) in enumerate(zip(node.ops, node.comparators)):
+                args.append(self.visit(ast.Compare(left=left, ops=[op], comparators=[comparator])))
+                left = comparator
+            return ast.Call(func=ast.Name(id="and_", ctx=ast.Load()), args=args, keywords=[])
+        left, op, right = self.visit(node.left), node.ops[0], self.visit(node.comparators[0])
+        if _is_subscript(left, "attributes"):
+            left = _cast_as("String", left)
+        if _is_subscript(right, "attributes"):
+            right = _cast_as("String", right)
+        if _is_float(left) and not _is_float(right):
+            right = _cast_as("Float", right)
+        elif not _is_float(left) and _is_float(right):
+            left = _cast_as("Float", left)
+        if isinstance(op, (ast.In, ast.NotIn)):
+            if _is_string_attribute(right) or ast.unparse(right) in _NAMES:
+                call = ast.Call(
+                    func=ast.Name(id="TextContains", ctx=ast.Load()),
+                    args=[right, left],
+                    keywords=[],
+                )
+                if isinstance(op, ast.NotIn):
+                    call = ast.Call(
+                        func=ast.Name(id="not_", ctx=ast.Load()), args=[call], keywords=[]
+                    )
+                return call
+            elif isinstance(right, (ast.List, ast.Tuple)):
+                attr = "in_" if isinstance(op, ast.In) else "not_in"
+                return ast.Call(
+                    func=ast.Attribute(value=left, attr=attr, ctx=ast.Load()),
+                    args=[right],
+                    keywords=[],
+                )
+            else:
+                raise SyntaxError(f"invalid expression: {ast.unparse(op)}")
+        if isinstance(op, ast.Is):
+            op = ast.Eq()
+        elif isinstance(op, ast.IsNot):
+            op = ast.NotEq()
+        return ast.Compare(left=left, ops=[op], comparators=[right])
+
+    def visit_BoolOp(self, node: ast.BoolOp) -> typing.Any:
+        if isinstance(node.op, ast.And):
+            func = ast.Name(id="and_", ctx=ast.Load())
+        elif isinstance(node.op, ast.Or):
+            func = ast.Name(id="or_", ctx=ast.Load())
+        else:
+            raise SyntaxError(f"invalid expression: {ast.unparse(node)}")
+        args = [self.visit(value) for value in node.values]
+        return ast.Call(func=func, args=args, keywords=[])
+
+    def visit_UnaryOp(self, node: ast.UnaryOp) -> typing.Any:
+        operand = self.visit(node.operand)
+        if isinstance(node.op, ast.Not):
+            return ast.Call(
+                func=ast.Name(id="not_", ctx=ast.Load()),
+                args=[operand],
+                keywords=[],
+            )
+        node = ast.UnaryOp(op=node.op, operand=operand)
+        if isinstance(node.op, (ast.USub, ast.UAdd)):
+            if not _is_float(node.operand):
+                operand = _cast_as("Float", node.operand)
+                return ast.UnaryOp(op=ast.USub(), operand=operand)
+            return node
+        return node
+
+    def visit_BinOp(self, node: ast.BinOp) -> typing.Any:
+        left, op, right = self.visit(node.left), node.op, self.visit(node.right)
+        if _is_subscript(left, "attributes"):
+            left = _cast_as("String", left)
+        if _is_subscript(right, "attributes"):
+            right = _cast_as("String", right)
+        type_: typing.Literal["Float", "String"] = "String"
+        if not isinstance(op, ast.Add) or _is_float(left) or _is_float(right):
+            type_ = "Float"
+            if not _is_float(left):
+                left = _cast_as(type_, left)
+            if not _is_float(right):
+                right = _cast_as(type_, right)
+            return ast.BinOp(left=left, op=op, right=right)
+        return _cast_as(type_, ast.BinOp(left=left, op=op, right=right))
+
+    def visit_Call(self, node: ast.Call) -> typing.Any:
+        source_segment = ast.unparse(node)
+        if len(node.args) != 1:
+            raise SyntaxError(f"invalid expression: {source_segment}")
+        if not isinstance(node.func, ast.Name) or node.func.id not in ("str", "float", "int"):
+            raise SyntaxError(f"invalid expression: {ast.unparse(node.func)}")
+        arg = self.visit(node.args[0])
+        if node.func.id in ("float", "int") and not _is_float(arg):
+            return _cast_as("Float", arg)
+        if node.func.id in ("str",) and not _is_string(arg):
+            return _cast_as("String", arg)
+        return arg
 
 
 def _validate_expression(
     expression: ast.Expression,
-    source: str,
-    valid_eval_names: Optional[Sequence[str]] = None,
-    valid_eval_attributes: Tuple[str, ...] = _VALID_EVAL_ATTRIBUTES,
+    valid_eval_names: typing.Optional[typing.Sequence[str]] = None,
+    valid_eval_attributes: tuple[str, ...] = _VALID_EVAL_ATTRIBUTES,
 ) -> None:
     """
     Validate primarily the structural (i.e. not semantic) characteristics of an
@@ -204,23 +547,26 @@ def _validate_expression(
     additional exceptions may be raised later by the NodeTransformer regarding
     either structural and semantic issues.
     """
-    # Regarding the need for `source: str` for getting source segments:
-    # In Python 3.8, we have to use `ast.get_source_segment(source, node)`.
-    # In Python 3.9+, we can use `ast.unparse(node)` (no need for `source`).
     if not isinstance(expression, ast.Expression):
-        raise SyntaxError(f"invalid expression: {source}")  # TODO: add details
+        raise SyntaxError(f"invalid expression: {ast.unparse(expression)}")
     for i, node in enumerate(ast.walk(expression.body)):
         if i == 0:
-            if isinstance(node, (ast.BoolOp, ast.Compare)):
+            if (
+                isinstance(node, (ast.BoolOp, ast.Compare))
+                or isinstance(node, ast.UnaryOp)
+                and isinstance(node.op, ast.Not)
+            ):
                 continue
-        elif _is_metadata(node):
+        elif (
+            _is_subscript(node, "metadata") or _is_subscript(node, "attributes")
+        ) and _get_attribute_keys_list(node) is not None:
             continue
-        elif _is_eval(node):
+        elif _is_annotation(node) and _get_subscript_key(node) is not None:
             # e.g. `evals["name"]`
             if not (eval_name := _get_subscript_key(node)) or (
                 valid_eval_names is not None and eval_name not in valid_eval_names
             ):
-                source_segment = cast(str, ast.get_source_segment(source, node))
+                source_segment = ast.unparse(node)
                 if eval_name and valid_eval_names:
                     # suggest a valid eval name most similar to the one given
                     choice, score = _find_best_match(eval_name, valid_eval_names)
@@ -237,10 +583,10 @@ def _validate_expression(
                     else ""
                 )
             continue
-        elif isinstance(node, ast.Attribute) and _is_eval(node.value):
+        elif isinstance(node, ast.Attribute) and _is_annotation(node.value):
             # e.g. `evals["name"].score`
             if (attr := node.attr) not in valid_eval_attributes:
-                source_segment = cast(str, ast.get_source_segment(source, node))
+                source_segment = ast.unparse(node)
                 # suggest a valid attribute most similar to the one given
                 choice, score = _find_best_match(attr, valid_eval_attributes)
                 if choice and score > 0.75:  # arbitrary threshold
@@ -256,6 +602,13 @@ def _validate_expression(
                     else ""
                 )
             continue
+        elif (
+            isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Name)
+            and node.func.id in ("str", "float", "int")
+        ):
+            # allow type casting functions
+            continue
         elif isinstance(
             node,
             (
@@ -273,86 +626,113 @@ def _validate_expression(
                 ast.cmpop,
                 ast.operator,
                 ast.unaryop,
-                # Prior to Python 3.9, `ast.Index` is part of `ast.Subscript`,
-                # so it needs to allowed here, but note that `ast.Subscript` is
-                # not allowed in general except in the case of `evals["name"]`.
-                # Note that `ast.Index` is deprecated in Python 3.9+.
-                *((ast.Index,) if sys.version_info < (3, 9) else ()),
             ),
         ):
             continue
-        source_segment = cast(str, ast.get_source_segment(source, node))
-        raise SyntaxError(f"invalid expression: {source_segment}")  # TODO: add details
-
-
-def _ast_evaluation_result_value(name: str, attr: str) -> ast.expr:
-    source = (
-        f"_RESULT.{attr}.value if ("
-        f"    _RESULT := ("
-        f"        _MISSING if ("
-        f"            _VALUE := evals.get_span_evaluation("
-        f"                 span.context.span_id, '{name}'"
-        f"            )"
-        f"        ) is None "
-        f"        else _VALUE"
-        f"    ).result"
-        f").HasField('{attr}') "
-        f"else _MISSING"
-    )
-    return ast.parse(source, mode="eval").body
-
-
-def _ast_metadata_subscript(key: str) -> ast.expr:
-    source = (
-        f"_MISSING if ("
-        f"    _MD := span.attributes.get('metadata')"
-        f") is None else ("
-        f"    _MISSING if not hasattr(_MD, 'get') or ("
-        f"        _VALUE := _MD.get('{key}')"
-        f"    ) is None else _VALUE"
-        f")"
+        source_segment = ast.unparse(node)
+        raise SyntaxError(f"invalid expression: {source_segment}")
+
+
+def _as_attribute(
+    keys: list[ast.Constant],
+    # as_float: typing.Optional[bool] = None,
+) -> ast.Subscript:
+    return ast.Subscript(
+        value=ast.Name(id="attributes", ctx=ast.Load()),
+        slice=ast.List(elts=keys, ctx=ast.Load())  # type: ignore[arg-type]
+        if sys.version_info >= (3, 9)
+        else ast.Index(value=ast.List(elts=keys, ctx=ast.Load())),  # type: ignore
+        ctx=ast.Load(),
     )
-    return ast.parse(source, mode="eval").body
 
 
-def _is_eval(node: Any) -> TypeGuard[ast.Subscript]:
+def _is_annotation(node: typing.Any) -> TypeGuard[ast.Subscript]:
     # e.g. `evals["name"]`
     return (
         isinstance(node, ast.Subscript)
         and isinstance(value := node.value, ast.Name)
-        and value.id == "evals"
+        and value.id in ["evals", "annotations"]
     )
 
 
-def _is_metadata(node: Any) -> TypeGuard[ast.Subscript]:
-    # e.g. `metadata["name"]`
-    return (
-        isinstance(node, ast.Subscript)
-        and isinstance(value := node.value, ast.Name)
-        and value.id == "metadata"
-    )
+def _is_subscript(
+    node: typing.Any,
+    id_: typing.Literal["attributes", "metadata"],
+) -> TypeGuard[ast.Subscript]:
+    # e.g. `attributes["key"]`
+    # e.g. `attributes[["a", "b.c", "d"]]`
+    # e.g. `attributes["a"]["b.c"]["d"]`
+    while isinstance(node, ast.Subscript):
+        node = node.value
+        if isinstance(node, ast.Name) and node.id == id_:
+            return True
+    return False
+
+
+def _get_attribute_keys_list(
+    node: typing.Any,
+) -> typing.Optional[list[ast.Constant]]:
+    # e.g. `attributes["key"]` -> `["key"]`
+    # e.g. `attributes["a"]["b.c"][["d"]]` -> `["a", "b.c", "d"]`
+    # e.g. `attributes["a"][["b.c", "d"]]` -> `["a", "b.c", "d"]`
+    # e.g. `metadata["key"]` -> `["metadata", "key"]`
+    # e.g. `metadata["a"]["b.c"][["d"]]` -> `["metadata", "a", "b.c", "d"]`
+    # e.g. `metadata["a"][["b.c", "d"]]` -> `["metadata", "a", "b.c", "d"]`
+    keys: list[ast.Constant] = []
+    if isinstance(node, ast.Attribute):
+        while isinstance(node, ast.Attribute):
+            keys.append(ast.Constant(value=node.attr, kind=None))
+            node = node.value
+            if isinstance(node, ast.Name):
+                keys.append(ast.Constant(value=node.id, kind=None))
+                return keys[::-1]
+    elif isinstance(node, ast.Subscript):
+        while isinstance(node, ast.Subscript):
+            if not (sub_keys := _get_subscript_keys_list(node)):
+                return None
+            keys.extend(reversed(sub_keys))
+            node = node.value
+            if isinstance(node, ast.Name):
+                if not isinstance(keys[-1].value, str):
+                    return None
+                if node.id == "metadata":
+                    keys.append(ast.Constant(value="metadata", kind=None))
+                return keys[::-1]
+    return None
+
+
+def _get_subscript_keys_list(
+    node: ast.Subscript,
+) -> typing.Optional[list[ast.Constant]]:
+    child = node.slice
+    if isinstance(child, ast.Constant):
+        if not isinstance(child.value, (str, int)) or isinstance(child.value, bool):
+            return None
+        return [child]
+    if not (
+        isinstance(child, ast.List)
+        and (elts := child.elts)
+        and all(
+            isinstance(elt, ast.Constant)
+            and isinstance(elt.value, (str, int))
+            and not isinstance(elt.value, bool)
+            for elt in elts
+        )
+    ):
+        return None
+    return [typing.cast(ast.Constant, elt) for elt in elts]
 
 
-def _get_subscript_key(node: ast.Subscript) -> Optional[str]:
-    if sys.version_info < (3, 9):
-        # Note that `ast.Index` is deprecated in Python 3.9+, but is necessary
-        # for Python 3.8 as part of `ast.Subscript`.
-        return (
-            eval_name
-            if isinstance(node_slice := node.slice, ast.Index)
-            and isinstance(slice_value := node_slice.value, ast.Constant)
-            and isinstance(eval_name := slice_value.value, str)
-            else None
-        )
-    return (
-        eval_name
-        if isinstance(node_slice := node.slice, ast.Constant)
-        and isinstance(eval_name := node_slice.value, str)
-        else None
-    )
+def _get_subscript_key(
+    node: ast.Subscript,
+) -> typing.Optional[str]:
+    child = node.slice
+    if not (isinstance(child, ast.Constant) and isinstance(child.value, str)):
+        return None
+    return child.value
 
 
-def _disjunction(choices: Sequence[str]) -> str:
+def _disjunction(choices: typing.Sequence[str]) -> str:
     """
     E.g. `["a", "b", "c"]` becomes `"one of a, b, or c"`
     """
@@ -365,10 +745,80 @@ def _disjunction(choices: Sequence[str]) -> str:
     return f"one of {', '.join(choices[:-1])}, or {choices[-1]}"
 
 
-def _find_best_match(source: str, choices: Iterable[str]) -> Tuple[Optional[str], float]:
+def _find_best_match(
+    source: str, choices: typing.Iterable[str]
+) -> tuple[typing.Optional[str], float]:
     best_choice, best_score = None, 0.0
     for choice in choices:
         score = SequenceMatcher(None, source, choice).ratio()
         if score > best_score:
             best_choice, best_score = choice, score
     return best_choice, best_score
+
+
+def _apply_eval_aliasing(
+    source: str,
+) -> tuple[
+    str,
+    tuple[AliasedAnnotationRelation, ...],
+]:
+    """
+    Substitutes `evals[<eval-name>].<attribute>` with aliases. Returns the
+    updated source code in addition to the aliased relations.
+
+    Example:
+
+    input:
+
+    ```
+    evals['Hallucination'].label == 'correct' or evals['Hallucination'].score < 0.5
+    ```
+
+    output:
+
+    ```
+    span_annotation_0_label_123 == 'correct' or span_annotation_0_score_456 < 0.5
+    ```
+    """
+    eval_aliases: dict[AnnotationName, AliasedAnnotationRelation] = {}
+    for (
+        annotation_expression,
+        annotation_type,
+        annotation_name,
+        annotation_attribute,
+    ) in _parse_annotation_expressions_and_names(source):
+        if (eval_alias := eval_aliases.get(annotation_name)) is None:
+            eval_alias = AliasedAnnotationRelation(index=len(eval_aliases), name=annotation_name)
+            eval_aliases[annotation_name] = eval_alias
+        alias_name = eval_alias.attribute_alias(annotation_attribute)
+        source = source.replace(annotation_expression, alias_name)
+    return source, tuple(eval_aliases.values())
+
+
+def _parse_annotation_expressions_and_names(
+    source: str,
+) -> typing.Iterator[
+    tuple[AnnotationExpression, AnnotationType, AnnotationName, AnnotationAttribute]
+]:
+    """
+    Parses filter conditions for evaluation expressions of the form:
+
+    ```
+    evals["<eval-name>"].<attribute>
+    annotations["eval-name"].<attribute>
+    ```
+    """
+    for match in EVAL_EXPRESSION_PATTERN.finditer(source):
+        (
+            annotation_expression,
+            annotation_type,
+            quoted_eval_name,
+            evaluation_attribute_name,
+        ) = match.groups()
+        annotation_type = typing.cast(AnnotationType, annotation_type)
+        yield (
+            annotation_expression,
+            annotation_type,
+            quoted_eval_name[1:-1],
+            typing.cast(AnnotationAttribute, evaluation_attribute_name),
+        )