Client Migration.mdc

description: globs: alwaysApply: false

Client Migration

The

arize-phoenix

package consists of a sub-package named

arize-phoenix-client

which has the full functionality to communicate to the phoenix server. There is a legacy client exported at the top level of the

arize-phoenix

package that is being deprecated. Here are common migration patterns.

Quick Reference for LLMs

Automatic Migration Rules:

Replace:

import phoenix as px

→

from phoenix.client import Client

(or

AsyncClient

)

Replace:
```
px.Client()
```
→
```
Client()
```
(variable name:
```
px_client
```
)

Replace:

client.query_spans(...)

→

client.spans.get_spans_dataframe(...)

Replace:

client.get_spans_dataframe()

→

client.spans.get_spans_dataframe()

Replace:

client.upload_dataset(...)

→

client.datasets.create_dataset(...)

Replace:

client.get_dataset(...)

→

client.datasets.get_dataset(...)

Replace:

px.Client().log_evaluations(SpanEvaluations(...))

→

px_client.spans.log_span_annotations_dataframe(...)

Replace:

px.Client().log_evaluations(DocumentEvaluations(...))

→

px_client.spans.log_document_annotations_dataframe(...)

Replace:

from phoenix.experiments import

→

from phoenix.client.experiments import

Replace:

from phoenix.trace.dsl import SpanQuery

→

from phoenix.client.types.spans import SpanQuery

Replace:

get_spans_dataframe(query="filter_string")

→

get_spans_dataframe(query=SpanQuery().where("filter_string"))

Parameter:
```
project_name=
```
→
```
project_identifier=
```
Parameter:
```
dataset_name=
```
→
```
name=
```
Parameter:
```
eval_name=
```
→
```
annotation_name=
```

Pattern Matching for LLMs

Identify Legacy Patterns (RegEx-like matching):

```
import phoenix as px
```
```
px\.Client\(\)
```
```
\.query_spans\(
```
```
\.get_spans_dataframe\(\)
```
```
\.upload_dataset\(
```
```
\.get_dataset\(
```
```
\.log_evaluations\(SpanEvaluations\(
```

\.log_evaluations\(DocumentEvaluations\(

```
from phoenix\.experiments import
```

from phoenix\.trace\.dsl import SpanQuery

```
get_spans_dataframe\(query=".*"\)
```
```
project_name\s*=
```
```
dataset_name\s*=
```
```
eval_name\s*=
```

Validation Rules After Migration:

✅ Must have:
```
from phoenix.client import
```
at top
✅ Must use:
```
px_client
```
as variable name (preferred)
✅ Must add:
```
annotator_kind="LLM"
```
for span evaluations
✅ Must await:
```
AsyncClient
```
method calls with
```
await
```
❌ No more:
```
import phoenix as px
```
(unless used for other purposes)
❌ No more:
```
SpanEvaluations
```
or
```
DocumentEvaluations
```
imports

Decision Tree for LLMs

Client Type Selection:

IF file extension == ".ipynb":
    USE AsyncClient
    ADD await before method calls
ELIF file extension == ".py":
    USE Client (synchronous)
    NO await needed

Evaluations Migration:

IF found "log_evaluations(SpanEvaluations(":
    MIGRATE to "spans.log_span_annotations_dataframe("
    ADD "annotator_kind='LLM'," parameter
    CHANGE "eval_name=" to "annotation_name="

IF found "log_evaluations(DocumentEvaluations(":
    MIGRATE to "spans.log_document_annotations_dataframe("
    ADD "annotator_kind='LLM'," parameter
    CHANGE "eval_name=" to "annotation_name="

Import Consolidation:

IF file contains multiple phoenix.client imports:
    CONSOLIDATE to single line: "from phoenix.client import Client, AsyncClient"

IF file uses both Client and other legacy phoenix features:
    KEEP both imports:
    - "import phoenix as px" (for legacy features like launch_app)
    - "from phoenix.client import Client" (for new client)

Common Error Patterns to Avoid

❌ Wrong Patterns:

# DON'T mix old and new imports incorrectly
import phoenix as px
from phoenix.client import Client
client = px.Client()  # Should use Client()

# DON'T forget await with AsyncClient
px_client = AsyncClient()
px_client.spans.get_spans_dataframe()  # Missing await

# DON'T use wrong resource path for annotations
px_client.annotations.log_span_annotations_dataframe(  # Wrong! Should be spans.log_span_annotations_dataframe
    dataframe=df,
    annotation_name="test"
)

# DON'T forget required annotator_kind
px_client.spans.log_span_annotations_dataframe(
    dataframe=df,
    annotation_name="test"  # Missing annotator_kind="LLM"
)

Basic Client Import Patterns

Legacy Pattern

# Complete context - typical legacy file header
import phoenix as px

# Legacy client instantiation
client = px.Client()
# or
px_client = px.Client()

New Patterns

Synchronous Client (for .py files):

# Complete context - new file header
from phoenix.client import Client

# New client instantiation
px_client = Client()

Asynchronous Client (for .ipynb notebooks):

# Complete context - new notebook cell
from phoenix.client import AsyncClient

# New async client instantiation
px_client = AsyncClient()

Key Changes

Import path:

import phoenix as px

→

from phoenix.client import Client/AsyncClient

Client instantiation:
```
px.Client()
```
→
```
Client()
```
or
```
AsyncClient()
```
Recommended variable name:
```
px_client
```
(instead of generic
```
client
```
)

Client Query Patterns

Legacy Pattern

import phoenix as px

# Querying spans
spans_df = px.Client().query_spans(query, project_name="my-project")

# Getting spans dataframe
spans_df = px.Client().get_spans_dataframe()

New Patterns

Synchronous:

from phoenix.client import Client

px_client = Client()
spans_df = px_client.spans.get_spans_dataframe(query=query, project_identifier="my-project")

Asynchronous:

from phoenix.client import AsyncClient

px_client = AsyncClient()
spans_df = await px_client.spans.get_spans_dataframe(query=query, project_identifier="my-project")

Key Changes

query_spans()

→

spans.get_spans_dataframe()

get_spans_dataframe()

→

spans.get_spans_dataframe()

```
project_name
```
→
```
project_identifier
```
Resource-based API: methods now accessed via
```
client.spans.*
```

Experiments Migration

Legacy Pattern

from phoenix.experiments import run_experiment, evaluate_experiment

New Pattern

from phoenix.client.experiments import run_experiment, evaluate_experiment

Key Changes

Import path:

phoenix.experiments

→

phoenix.client.experiments

SpanQuery Migration

Legacy Pattern

from phoenix.trace.dsl import SpanQuery

# Old way with string query filters
spans_df = px.Client().get_spans_dataframe(query="span_kind == 'LLM'")

# Or with SpanQuery object (older import)
query = SpanQuery().where("span_kind == 'LLM'").select(input="input.value")
spans_df = px.Client().query_spans(query)

New Pattern

from phoenix.client import AsyncClient
from phoenix.client.types.spans import SpanQuery

px_client = AsyncClient()

# New way: SpanQuery object only (no string queries)
query = SpanQuery().where("span_kind == 'LLM'")
spans_df = await px_client.spans.get_spans_dataframe(query=query)

Key Changes

Import path:

phoenix.trace.dsl

→

phoenix.client.types.spans

SpanQuery usage remains the same after import
No more string query filters: Use SpanQuery object instead of query string parameters

Datasets Migration

Legacy Pattern

import phoenix as px

dataset = px.Client().upload_dataset(
    dataframe=df,
    dataset_name="my-dataset",
    input_keys=["question"],
    output_keys=["answer"]
)

dataset = px.Client().get_dataset(name="my-dataset")

New Pattern

from phoenix.client import Client

px_client = Client()
dataset = px_client.datasets.create_dataset(
    dataframe=df,
    name="my-dataset",
    input_keys=["question"],
    output_keys=["answer"]
)

dataset = px_client.datasets.get_dataset(dataset="my-dataset")

Key Changes

upload_dataset()

→

datasets.create_dataset()

```
get_dataset()
```
→
```
datasets.get_dataset()
```
```
dataset_name
```
→
```
name
```
```
name
```
parameter →
```
dataset
```
parameter (for get_dataset)

Log Evaluation Migration

Span Evaluations (MIGRATE)

Legacy Pattern (Complete Example):

# Complete legacy file context
import phoenix as px
from phoenix.trace import SpanEvaluations
import pandas as pd

# Some evaluation dataframe
relevance_df = pd.DataFrame({"score": [0.8, 0.9], "label": ["good", "excellent"]})
hallucination_df = pd.DataFrame({"score": [0.1, 0.2], "label": ["low", "low"]})

# Legacy single evaluation
px.Client().log_evaluations(
    SpanEvaluations(
        dataframe=relevance_df,
        eval_name="Recommendation Relevance",
    ),
)

# Legacy multiple evaluations (single call)
px.Client().log_evaluations(
    SpanEvaluations(eval_name="Hallucination", dataframe=hallucination_df),
    SpanEvaluations(eval_name="QA Correctness", dataframe=qa_correctness_df),
)

New Pattern (Synchronous - for .py files):

# Complete new file context
from phoenix.client import Client
import pandas as pd

# Same evaluation dataframes
relevance_df = pd.DataFrame({"score": [0.8, 0.9], "label": ["good", "excellent"]})
hallucination_df = pd.DataFrame({"score": [0.1, 0.2], "label": ["low", "low"]})

# New single evaluation
px_client = Client()
px_client.annotations.log_span_annotations_dataframe(
    dataframe=relevance_df,
    annotation_name="Recommendation Relevance",
    annotator_kind="LLM",
)

# New multiple evaluations (separate calls)
px_client.annotations.log_span_annotations_dataframe(
    dataframe=hallucination_df,
    annotation_name="Hallucination",
    annotator_kind="LLM",
)
px_client.annotations.log_span_annotations_dataframe(
    dataframe=qa_correctness_df,
    annotation_name="QA Correctness",
    annotator_kind="LLM",
)

New Pattern (Asynchronous - for .ipynb notebooks):

# Complete new notebook cell context
from phoenix.client import AsyncClient
import pandas as pd

# Same evaluation dataframes
relevance_df = pd.DataFrame({"score": [0.8, 0.9], "label": ["good", "excellent"]})
hallucination_df = pd.DataFrame({"score": [0.1, 0.2], "label": ["low", "low"]})

# New async single evaluation
px_client = AsyncClient()
await px_client.annotations.log_span_annotations_dataframe(
    dataframe=relevance_df,
    annotation_name="Recommendation Relevance",
    annotator_kind="LLM",
)

# New async multiple evaluations (separate calls with await)
await px_client.annotations.log_span_annotations_dataframe(
    dataframe=hallucination_df,
    annotation_name="Hallucination",
    annotator_kind="LLM",
)
await px_client.annotations.log_span_annotations_dataframe(
    dataframe=qa_correctness_df,
    annotation_name="QA Correctness",
    annotator_kind="LLM",
)

Key Changes

log_evaluations(SpanEvaluations(...))

→

annotations.log_span_annotations_dataframe(...)

```
eval_name
```
→
```
annotation_name
```
Added required
```
annotator_kind
```
parameter
Multiple evaluations require separate function calls
Import: Remove
```
SpanEvaluations
```
import

Document Evaluations (MIGRATE)

Legacy Pattern (Complete Example):

# Complete legacy file context
import phoenix as px
from phoenix.trace import DocumentEvaluations
import pandas as pd

# Document evaluation dataframe with required columns: span_id, document_position
document_relevance_df = pd.DataFrame({
    "span_id": ["span_1", "span_1", "span_2"],
    "document_position": [0, 1, 0],
    "score": [1, 1, 0],
    "label": ["relevant", "relevant", "irrelevant"],
    "explanation": ["it's apropos", "it's germane", "it's rubbish"]
})

# Legacy single document evaluation
px.Client().log_evaluations(
    DocumentEvaluations(
        dataframe=document_relevance_df,
        eval_name="Relevance",
    ),
)

# Legacy multiple evaluations (single call)
px.Client().log_evaluations(
    DocumentEvaluations(eval_name="Relevance", dataframe=document_relevance_df),
    DocumentEvaluations(eval_name="Accuracy", dataframe=document_accuracy_df),
)

New Pattern (Synchronous - for .py files):

# Complete new file context
from phoenix.client import Client
import pandas as pd

# Same document evaluation dataframe
document_relevance_df = pd.DataFrame({
    "span_id": ["span_1", "span_1", "span_2"],
    "document_position": [0, 1, 0],
    "score": [1, 1, 0],
    "label": ["relevant", "relevant", "irrelevant"],
    "explanation": ["it's apropos", "it's germane", "it's rubbish"]
})

# New single document evaluation
px_client = Client()
px_client.spans.log_document_annotations_dataframe(
    dataframe=document_relevance_df,
    annotation_name="Relevance",
    annotator_kind="LLM",
)

# New multiple evaluations (separate calls)
px_client.spans.log_document_annotations_dataframe(
    dataframe=document_relevance_df,
    annotation_name="Relevance",
    annotator_kind="LLM",
)
px_client.spans.log_document_annotations_dataframe(
    dataframe=document_accuracy_df,
    annotation_name="Accuracy",
    annotator_kind="LLM",
)

New Pattern (Asynchronous - for .ipynb notebooks):

# Complete new notebook cell context
from phoenix.client import AsyncClient
import pandas as pd

# Same document evaluation dataframe
document_relevance_df = pd.DataFrame({
    "span_id": ["span_1", "span_1", "span_2"],
    "document_position": [0, 1, 0],
    "score": [1, 1, 0],
    "label": ["relevant", "relevant", "irrelevant"],
    "explanation": ["it's apropos", "it's germane", "it's rubbish"]
})

# New async single document evaluation
px_client = AsyncClient()
await px_client.spans.log_document_annotations_dataframe(
    dataframe=document_relevance_df,
    annotation_name="Relevance",
    annotator_kind="LLM",
)

# New async multiple evaluations (separate calls with await)
await px_client.spans.log_document_annotations_dataframe(
    dataframe=document_relevance_df,
    annotation_name="Relevance",
    annotator_kind="LLM",
)
await px_client.spans.log_document_annotations_dataframe(
    dataframe=document_accuracy_df,
    annotation_name="Accuracy",
    annotator_kind="LLM",
)

Key Changes for Document Evaluations

log_evaluations(DocumentEvaluations(...))

→

spans.log_document_annotations_dataframe(...)

```
eval_name
```
→
```
annotation_name
```
Added required
```
annotator_kind
```
parameter
Multiple evaluations require separate function calls
DataFrame must include
```
span_id
```
and
```
document_position
```
columns
Import: Remove
```
DocumentEvaluations
```
import

Complete Parameter Mapping Table for LLMs

Evaluations Parameter Changes:

Legacy Parameter	New Parameter	Notes
`eval_name`	`annotation_name`	Name of the evaluation
N/A	`annotator_kind`	Required: typically "LLM"
`dataframe`	`dataframe`	Same parameter name

DocumentEvaluations DataFrame Requirements:

Required Column	Description
`span_id`	ID of the span containing the documents
`document_position`	0-based index of document within the span
`score`	Optional: numeric evaluation score
`label`	Optional: categorical evaluation label
`explanation`	Optional: text explanation of the evaluation

Complete API Transformation Table:

Legacy Pattern	New Pattern	Key Changes
`px.Client().query_spans(project_name=...)`	`px_client.spans.get_spans_dataframe(project_identifier=...)`	Resource path + parameter name
`px.Client().get_spans_dataframe()`	`px_client.spans.get_spans_dataframe()`	Resource path only
`px.Client().upload_dataset(dataset_name=...)`	`px_client.datasets.create_dataset(name=...)`	Resource path + parameter name
`px.Client().get_dataset(name=...)`	`px_client.datasets.get_dataset(dataset=...)`	Resource path + parameter name
`px.Client().log_evaluations(SpanEvaluations(eval_name=...))`	`px_client.spans.log_span_annotations_dataframe(annotation_name=..., annotator_kind="LLM")`	Resource path + parameters + required field
`px.Client().log_evaluations(DocumentEvaluations(eval_name=...))`	`px_client.spans.log_document_annotations_dataframe(annotation_name=..., annotator_kind="LLM")`	Resource path + parameters + required field
`from phoenix.trace.dsl import SpanQuery`	`from phoenix.client.types.spans import SpanQuery`	Import path only
`get_spans_dataframe(query="filter_string")`	`get_spans_dataframe(query=SpanQuery().where("filter_string"))`	String queries → SpanQuery objects

Import Statement Cleanup

Remove unused imports after migration:

# Remove these after migration:
from phoenix.trace import SpanEvaluations  # ❌ Remove
from phoenix.trace import DocumentEvaluations  # ❌ Remove
from phoenix.trace.dsl import SpanQuery  # ❌ Remove
import phoenix as px  # ❌ Remove if only used for Client()

# Keep these:
import phoenix as px  # ✅ Keep if used for other functionality (launch_app, etc.)

# Replace with new imports:
from phoenix.client import Client  # ✅ New client import
from phoenix.client import AsyncClient  # ✅ New async client import
from phoenix.client.types.spans import SpanQuery  # ✅ New SpanQuery import

description: globs: alwaysApply: false