Skip to content

[BUG]: Span annotation DataFrame logging skips required-column validation that the document path enforces #17398

Closed

Description

@BlueX888

Where you use Phoenix

Self-hosted (phoenix-client library; verified against the client payload and the server's annotation schema).

Version

packages/phoenix-client on main at a73b42b (2026-10-30), Python 3.12.2, Windows 11.

What happened?

client.spans.log_span_annotations_dataframe() skips the required-column validation that its document sibling performs, so two common misuses produce confusing failures instead of the clear ValueError the document methods give.

  1. Missing annotator_kind column and no global annotator_kind. The request body carries "annotator_kind": null, which the server rejects (422, annotations.py requires the Literal). The document method raises:
    ValueError: DataFrame must contain columns: {'annotator_kind'}. Found columns: [...]
  2. Missing name / annotation_name column and no global annotation_name. The span method raises the opaque ValueError: 'Error processing row 0: '; the document method raises:
    ValueError: DataFrame must contain either 'name' or 'annotation_name' column when annotation_name_required=True

Expected: the span DataFrame methods validate the same required columns (and raise the same clear errors) as the document methods before building the request.

Reproduction

from phoenix.client import Client
client = Client(base_url="http://localhost:6006")

# (a) no annotator_kind column, no global value
client.spans.log_span_annotations_dataframe(df)   # -> payload annotator_kind=None -> server 422

# (c) no name/annotation_name column, no global value
client.spans.log_span_annotations_dataframe(df2)  # -> ValueError: 'Error processing row 0: '

Actual output:

--- (a) span annotations, no annotator_kind column, no global value ---
request payload: {'name': 'sentiment', 'annotator_kind': None, 'span_id': 'span-1', 'result': {'label': 'positive'}}
--- (b) document sibling, same situation (clear ValueError) ---
document error: ValueError DataFrame must contain columns: {'annotator_kind'}. Found columns: ['span_id', 'document_position', 'name', 'label']
--- (c) span annotations, no name column, no global annotation_name ---
span error: ValueError 'Error processing row 0: '
--- (d) document sibling, no name column (clear ValueError) ---
document error: ValueError "DataFrame must contain either 'name' or 'annotation_name' column when annotation_name_required=True"

The script is self-contained (no server needed; it inspects the built payload and the raised errors); happy to attach it.

Additional information

  • The document path passes annotation_name_required / annotator_kind_required into its validation (packages/phoenix-client/src/phoenix/client/resources/spans/__init__.py:1401-1405 sync, :2727-2731 async); the span DataFrame path at :1027 / :2328 does not.
  • Server-side requirement: src/phoenix/server/api/routers/v1/annotations.py:64 (annotator_kind: AnnotatorKind).
  • Related precedent: [BUG]: Document annotation dataframe validation skips document_position type checks #13771 fixed a missing document_position type check in the document path; this is the analogous gap on the span path.
  • Searched open and closed issues/PRs for span annotation DataFrame validation and annotator_kind: no duplicate.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    triageissues that need triage

    Type

    No type

    Projects

    • Status
      ✅ Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions