<h1 align="center" style="border-bottom: none">
<div>
<a href="https://phoenix.arize.com/?utm_medium=github&utm_content=header_img&utm_campaign=phoenix-client">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix-white.svg">
<img alt="Arize Phoenix logo" src="https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix.svg" width="100" />
</picture>
</a>
<br>
arize-phoenix-client
</div>
</h1>
<p align="center">
<a href="https://pypi.org/project/arize-phoenix-client/">
<img src="https://img.shields.io/pypi/v/arize-phoenix-client" alt="PyPI Version">
</a>
<a href="https://arize-phoenix.readthedocs.io/projects/client/en/latest/index.html">
<img src="https://img.shields.io/badge/docs-blue?logo=readthedocs&logoColor=white" alt="Documentation">
</a>
</p>
Phoenix Client provides a interface for interacting with the Phoenix platform via its REST API, enabling you to manage datasets, run experiments, analyze traces, and collect feedback programmatically.
## Features
- **REST API Interface** - Interact with Phoenix's OpenAPI REST interface
- **Prompts** - Create, version, and invoke prompt templates
- **Datasets** - Create and append to datasets from DataFrames, CSV files, or dictionaries
- **Experiments** - Run evaluations and track experiment results
- **Spans** - Query and analyze traces with powerful filtering
- **Annotations** - Add human feedback and automated evaluations
## Installation
Install the Phoenix Client using pip:
```bash
pip install arize-phoenix-client
```
## Getting Started
### Environment Variables
Configure the Phoenix Client using environment variables for seamless use across different environments:
```bash
# For local Phoenix server (default)
export PHOENIX_BASE_URL="http://localhost:6006"
# Cloud Instance
export PHOENIX_API_KEY="your-api-key"
export PHOENIX_BASE_URL="https://app.phoenix.arize.com/s/your-space"
# For custom Phoenix instances with API key authentication
export PHOENIX_BASE_URL="https://your-phoenix-instance.com"
export PHOENIX_API_KEY="your-api-key"
# Customize headers
export PHOENIX_CLIENT_HEADERS="Authorization=Bearer your-api-key,custom-header=value"
```
### Client Initialization
The client automatically reads environment variables, or you can override them:
```python
from phoenix.client import Client, AsyncClient
# Automatic configuration from environment variables
client = Client()
client = Client(base_url="http://localhost:6006") # Local Phoenix server
# Cloud instance with API key
client = Client(
base_url="https://app.phoenix.arize.com/s/your-space",
api_key="your-api-key"
)
# Custom authentication headers
client = Client(
base_url="https://your-phoenix-instance.com",
headers={"Authorization": "Bearer your-api-key"}
)
# Asynchronous client (same configuration options)
async_client = AsyncClient()
async_client = AsyncClient(base_url="http://localhost:6006")
async_client = AsyncClient(
base_url="https://app.phoenix.arize.com/s/your-space",
api_key="your-api-key"
)
```
## Resources
The Phoenix Client organizes functionality into resources that correspond to key Phoenix platform features. Each resource provides specialized methods for managing different types of data:
### Prompts
Manage prompt templates and versions:
```python
from phoenix.client import Client
from phoenix.client.types import PromptVersion
content = """
You're an expert educator in {{ topic }}. Summarize the following article
in a few concise bullet points that are easy for beginners to understand.
{{ article }}
"""
prompt = client.prompts.create(
name="article-bullet-summarizer",
version=PromptVersion(
messages=[{"role": "user", "content": content}],
model_name="gpt-4o-mini",
),
prompt_description="Summarize an article in a few bullet points"
)
# Retrieve and use prompts
prompt = client.prompts.get(prompt_identifier="article-bullet-summarizer")
# Format the prompt with variables
prompt_vars = {
"topic": "Sports",
"article": "Moises Henriques, the Australian all-rounder, has signed to play for Surrey in this summer's NatWest T20 Blast. He will join after the IPL and is expected to strengthen the squad throughout the campaign."
}
formatted_prompt = prompt.format(variables=prompt_vars)
# Make a request with your Prompt using OpenAI
from openai import OpenAI
oai_client = OpenAI()
resp = oai_client.chat.completions.create(**formatted_prompt)
print(resp.choices[0].message.content)
```
### Datasets
Manage evaluation datasets and examples for experiments and evaluation:
```python
import pandas as pd
# List all available datasets
datasets = client.datasets.list()
for dataset in datasets:
print(f"Dataset: {dataset['name']} ({dataset['example_count']} examples)")
# Get a specific dataset with all examples
dataset = client.datasets.get_dataset(dataset="qa-evaluation")
print(f"Dataset {dataset.name} has {len(dataset)} examples")
# Convert dataset to pandas DataFrame for analysis
df = dataset.to_dataframe()
print(df.columns) # Index(['input', 'output', 'metadata'], dtype='object')
# Create a new dataset from dictionaries
dataset = client.datasets.create_dataset(
name="customer-support-qa",
dataset_description="Q&A dataset for customer support evaluation",
inputs=[
{"question": "How do I reset my password?"},
{"question": "What's your return policy?"},
{"question": "How do I track my order?"}
],
outputs=[
{"answer": "You can reset your password by clicking the 'Forgot Password' link on the login page."},
{"answer": "We offer 30-day returns for unused items in original packaging."},
{"answer": "You can track your order using the tracking number sent to your email."}
],
metadata=[
{"category": "account", "difficulty": "easy"},
{"category": "policy", "difficulty": "medium"},
{"category": "orders", "difficulty": "easy"}
]
)
# Create dataset from pandas DataFrame
df = pd.DataFrame({
"prompt": ["Hello", "Hi there", "Good morning"],
"response": ["Hi! How can I help?", "Hello! What can I do for you?", "Good morning! How may I assist?"],
"sentiment": ["neutral", "positive", "positive"],
"length": [20, 25, 30]
})
dataset = client.datasets.create_dataset(
name="greeting-responses",
dataframe=df,
input_keys=["prompt"], # Columns to use as input
output_keys=["response"], # Columns to use as expected output
metadata_keys=["sentiment", "length"] # Additional metadata columns
)
```
### Spans
Query for spans and annotations from your projects for custom evaluation and annotation workflows:
```python
from datetime import datetime, timedelta
# Get spans as pandas DataFrame for analysis
spans_df = client.spans.get_spans_dataframe(
project_identifier="my-llm-app",
limit=1000,
root_spans_only=True, # Only get top-level spans
start_time=datetime.now() - timedelta(hours=24)
)
# Get span annotations as DataFrame
annotations_df = client.spans.get_span_annotations_dataframe(
spans_dataframe=spans_df, # Use spans from previous query
project_identifier="my-llm-app",
include_annotation_names=["relevance", "accuracy"], # Only specific annotations
exclude_annotation_names=["note"] # Exclude UI notes
)
```
### Annotations
Add annotations to spans for evaluation, user feedback, and custom annotation workflows:
```python
# Add a single annotation with human feedback
client.annotations.add_span_annotation(
span_id="span-123",
annotation_name="helpfulness",
annotator_kind="HUMAN",
label="helpful",
score=0.9,
explanation="Response directly answered the user's question"
)
# Bulk annotation logging for multiple spans
annotations = [
{
"name": "sentiment",
"span_id": "span-123",
"annotator_kind": "LLM",
"result": {"label": "positive", "score": 0.8}
},
{
"name": "accuracy",
"span_id": "span-456",
"annotator_kind": "HUMAN",
"result": {"label": "accurate", "score": 0.95}
},
]
client.annotations.log_span_annotations(span_annotations=annotations)
```
### Projects
Manage Phoenix projects that organize your AI application data:
```python
# List all projects
projects = client.projects.list()
for project in projects:
print(f"Project: {project['name']} (ID: {project['id']})")
# Create a new project
new_project = client.projects.create(
name="Customer Support Bot",
description="Traces and evaluations for our customer support chatbot"
)
print(f"Created project with ID: {new_project['id']}")
```
## Documentation
- **[Full Documentation](https://arize-phoenix.readthedocs.io/projects/client/en/latest/index.html)** - Complete API reference and guides
- **[Phoenix Docs](https://arize.com/docs/phoenix)** - Main Phoenix documentation
- **[GitHub Repository](https://github.com/Arize-ai/phoenix)** - Source code and examples
## Community
Join our community to connect with thousands of AI builders:
- π Join our [Slack community](https://arize-ai.slack.com/join/shared_invite/zt-11t1vbu4x-xkBIHmOREQnYnYDH1GDfCg).
- π‘ Ask questions and provide feedback in the _#phoenix-support_ channel.
- π Leave a star on our [GitHub](https://github.com/Arize-ai/phoenix).
- π Report bugs with [GitHub Issues](https://github.com/Arize-ai/phoenix/issues).
- π Follow us on [π](https://twitter.com/ArizePhoenix).
- πΊοΈ Check out our [roadmap](https://github.com/orgs/Arize-ai/projects/45) to see where we're heading next.
Raw data
{
"_id": null,
"home_page": null,
"name": "arize-phoenix-client",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.9",
"maintainer_email": null,
"keywords": "Explainability, Monitoring, Observability",
"author": null,
"author_email": "Arize AI <phoenix-devs@arize.com>",
"download_url": "https://files.pythonhosted.org/packages/47/c5/f4d99be5434a1725e23fa655acd34c8abd51d70e76329147f66ba93a9237/arize_phoenix_client-1.18.1.tar.gz",
"platform": null,
"description": "<h1 align=\"center\" style=\"border-bottom: none\">\n <div>\n <a href=\"https://phoenix.arize.com/?utm_medium=github&utm_content=header_img&utm_campaign=phoenix-client\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix.svg\">\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix-white.svg\">\n <img alt=\"Arize Phoenix logo\" src=\"https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix.svg\" width=\"100\" />\n </picture>\n </a>\n <br>\n arize-phoenix-client\n </div>\n</h1>\n<p align=\"center\">\n <a href=\"https://pypi.org/project/arize-phoenix-client/\">\n <img src=\"https://img.shields.io/pypi/v/arize-phoenix-client\" alt=\"PyPI Version\">\n </a>\n <a href=\"https://arize-phoenix.readthedocs.io/projects/client/en/latest/index.html\">\n <img src=\"https://img.shields.io/badge/docs-blue?logo=readthedocs&logoColor=white\" alt=\"Documentation\">\n </a>\n</p>\nPhoenix Client provides a interface for interacting with the Phoenix platform via its REST API, enabling you to manage datasets, run experiments, analyze traces, and collect feedback programmatically.\n\n## Features\n\n- **REST API Interface** - Interact with Phoenix's OpenAPI REST interface\n- **Prompts** - Create, version, and invoke prompt templates\n- **Datasets** - Create and append to datasets from DataFrames, CSV files, or dictionaries\n- **Experiments** - Run evaluations and track experiment results\n- **Spans** - Query and analyze traces with powerful filtering\n- **Annotations** - Add human feedback and automated evaluations\n\n## Installation\n\nInstall the Phoenix Client using pip:\n\n```bash\npip install arize-phoenix-client\n```\n\n## Getting Started\n\n### Environment Variables\n\nConfigure the Phoenix Client using environment variables for seamless use across different environments:\n\n```bash\n# For local Phoenix server (default)\nexport PHOENIX_BASE_URL=\"http://localhost:6006\"\n\n# Cloud Instance\nexport PHOENIX_API_KEY=\"your-api-key\"\nexport PHOENIX_BASE_URL=\"https://app.phoenix.arize.com/s/your-space\"\n\n# For custom Phoenix instances with API key authentication\nexport PHOENIX_BASE_URL=\"https://your-phoenix-instance.com\"\nexport PHOENIX_API_KEY=\"your-api-key\"\n\n# Customize headers\nexport PHOENIX_CLIENT_HEADERS=\"Authorization=Bearer your-api-key,custom-header=value\"\n```\n\n### Client Initialization\n\nThe client automatically reads environment variables, or you can override them:\n\n```python\nfrom phoenix.client import Client, AsyncClient\n\n# Automatic configuration from environment variables\nclient = Client()\n\nclient = Client(base_url=\"http://localhost:6006\") # Local Phoenix server\n\n# Cloud instance with API key\nclient = Client(\n base_url=\"https://app.phoenix.arize.com/s/your-space\",\n api_key=\"your-api-key\"\n)\n\n# Custom authentication headers\nclient = Client(\n base_url=\"https://your-phoenix-instance.com\",\n headers={\"Authorization\": \"Bearer your-api-key\"}\n)\n\n# Asynchronous client (same configuration options)\nasync_client = AsyncClient()\nasync_client = AsyncClient(base_url=\"http://localhost:6006\")\nasync_client = AsyncClient(\n base_url=\"https://app.phoenix.arize.com/s/your-space\",\n api_key=\"your-api-key\"\n)\n```\n\n## Resources\n\nThe Phoenix Client organizes functionality into resources that correspond to key Phoenix platform features. Each resource provides specialized methods for managing different types of data:\n\n### Prompts\n\nManage prompt templates and versions:\n\n```python\nfrom phoenix.client import Client\nfrom phoenix.client.types import PromptVersion\n\ncontent = \"\"\"\nYou're an expert educator in {{ topic }}. Summarize the following article\nin a few concise bullet points that are easy for beginners to understand.\n\n{{ article }}\n\"\"\"\n\nprompt = client.prompts.create(\n name=\"article-bullet-summarizer\",\n version=PromptVersion(\n messages=[{\"role\": \"user\", \"content\": content}],\n model_name=\"gpt-4o-mini\",\n ),\n prompt_description=\"Summarize an article in a few bullet points\"\n)\n\n# Retrieve and use prompts\nprompt = client.prompts.get(prompt_identifier=\"article-bullet-summarizer\")\n\n# Format the prompt with variables\nprompt_vars = {\n \"topic\": \"Sports\",\n \"article\": \"Moises Henriques, the Australian all-rounder, has signed to play for Surrey in this summer's NatWest T20 Blast. He will join after the IPL and is expected to strengthen the squad throughout the campaign.\"\n}\nformatted_prompt = prompt.format(variables=prompt_vars)\n\n# Make a request with your Prompt using OpenAI\nfrom openai import OpenAI\noai_client = OpenAI()\nresp = oai_client.chat.completions.create(**formatted_prompt)\nprint(resp.choices[0].message.content)\n```\n\n### Datasets\n\nManage evaluation datasets and examples for experiments and evaluation:\n\n```python\nimport pandas as pd\n\n# List all available datasets\ndatasets = client.datasets.list()\nfor dataset in datasets:\n print(f\"Dataset: {dataset['name']} ({dataset['example_count']} examples)\")\n\n# Get a specific dataset with all examples\ndataset = client.datasets.get_dataset(dataset=\"qa-evaluation\")\nprint(f\"Dataset {dataset.name} has {len(dataset)} examples\")\n\n# Convert dataset to pandas DataFrame for analysis\ndf = dataset.to_dataframe()\nprint(df.columns) # Index(['input', 'output', 'metadata'], dtype='object')\n\n# Create a new dataset from dictionaries\ndataset = client.datasets.create_dataset(\n name=\"customer-support-qa\",\n dataset_description=\"Q&A dataset for customer support evaluation\",\n inputs=[\n {\"question\": \"How do I reset my password?\"},\n {\"question\": \"What's your return policy?\"},\n {\"question\": \"How do I track my order?\"}\n ],\n outputs=[\n {\"answer\": \"You can reset your password by clicking the 'Forgot Password' link on the login page.\"},\n {\"answer\": \"We offer 30-day returns for unused items in original packaging.\"},\n {\"answer\": \"You can track your order using the tracking number sent to your email.\"}\n ],\n metadata=[\n {\"category\": \"account\", \"difficulty\": \"easy\"},\n {\"category\": \"policy\", \"difficulty\": \"medium\"},\n {\"category\": \"orders\", \"difficulty\": \"easy\"}\n ]\n)\n\n# Create dataset from pandas DataFrame\ndf = pd.DataFrame({\n \"prompt\": [\"Hello\", \"Hi there\", \"Good morning\"],\n \"response\": [\"Hi! How can I help?\", \"Hello! What can I do for you?\", \"Good morning! How may I assist?\"],\n \"sentiment\": [\"neutral\", \"positive\", \"positive\"],\n \"length\": [20, 25, 30]\n})\n\ndataset = client.datasets.create_dataset(\n name=\"greeting-responses\",\n dataframe=df,\n input_keys=[\"prompt\"], # Columns to use as input\n output_keys=[\"response\"], # Columns to use as expected output\n metadata_keys=[\"sentiment\", \"length\"] # Additional metadata columns\n)\n```\n\n### Spans\n\nQuery for spans and annotations from your projects for custom evaluation and annotation workflows:\n\n```python\nfrom datetime import datetime, timedelta\n\n# Get spans as pandas DataFrame for analysis\nspans_df = client.spans.get_spans_dataframe(\n project_identifier=\"my-llm-app\",\n limit=1000,\n root_spans_only=True, # Only get top-level spans\n start_time=datetime.now() - timedelta(hours=24)\n)\n\n# Get span annotations as DataFrame\nannotations_df = client.spans.get_span_annotations_dataframe(\n spans_dataframe=spans_df, # Use spans from previous query\n project_identifier=\"my-llm-app\",\n include_annotation_names=[\"relevance\", \"accuracy\"], # Only specific annotations\n exclude_annotation_names=[\"note\"] # Exclude UI notes\n)\n```\n\n### Annotations\n\nAdd annotations to spans for evaluation, user feedback, and custom annotation workflows:\n\n```python\n# Add a single annotation with human feedback\nclient.annotations.add_span_annotation(\n span_id=\"span-123\",\n annotation_name=\"helpfulness\",\n annotator_kind=\"HUMAN\",\n label=\"helpful\",\n score=0.9,\n explanation=\"Response directly answered the user's question\"\n)\n\n# Bulk annotation logging for multiple spans\nannotations = [\n {\n \"name\": \"sentiment\",\n \"span_id\": \"span-123\",\n \"annotator_kind\": \"LLM\",\n \"result\": {\"label\": \"positive\", \"score\": 0.8}\n },\n {\n \"name\": \"accuracy\",\n \"span_id\": \"span-456\",\n \"annotator_kind\": \"HUMAN\",\n \"result\": {\"label\": \"accurate\", \"score\": 0.95}\n },\n]\nclient.annotations.log_span_annotations(span_annotations=annotations)\n```\n\n### Projects\n\nManage Phoenix projects that organize your AI application data:\n\n```python\n# List all projects\nprojects = client.projects.list()\nfor project in projects:\n print(f\"Project: {project['name']} (ID: {project['id']})\")\n\n# Create a new project\nnew_project = client.projects.create(\n name=\"Customer Support Bot\",\n description=\"Traces and evaluations for our customer support chatbot\"\n)\nprint(f\"Created project with ID: {new_project['id']}\")\n```\n\n## Documentation\n\n- **[Full Documentation](https://arize-phoenix.readthedocs.io/projects/client/en/latest/index.html)** - Complete API reference and guides\n- **[Phoenix Docs](https://arize.com/docs/phoenix)** - Main Phoenix documentation\n- **[GitHub Repository](https://github.com/Arize-ai/phoenix)** - Source code and examples\n\n## Community\n\nJoin our community to connect with thousands of AI builders:\n\n- \ud83c\udf0d Join our [Slack community](https://arize-ai.slack.com/join/shared_invite/zt-11t1vbu4x-xkBIHmOREQnYnYDH1GDfCg).\n- \ud83d\udca1 Ask questions and provide feedback in the _#phoenix-support_ channel.\n- \ud83c\udf1f Leave a star on our [GitHub](https://github.com/Arize-ai/phoenix).\n- \ud83d\udc1e Report bugs with [GitHub Issues](https://github.com/Arize-ai/phoenix/issues).\n- \ud835\udd4f Follow us on [\ud835\udd4f](https://twitter.com/ArizePhoenix).\n- \ud83d\uddfa\ufe0f Check out our [roadmap](https://github.com/orgs/Arize-ai/projects/45) to see where we're heading next.\n",
"bugtrack_url": null,
"license": "Elastic-2.0",
"summary": "LLM Observability",
"version": "1.18.1",
"project_urls": {
"Documentation": "https://arize.com/docs/phoenix/",
"Issues": "https://github.com/Arize-ai/phoenix/issues",
"Source": "https://github.com/Arize-ai/phoenix"
},
"split_keywords": [
"explainability",
" monitoring",
" observability"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3d531436070e954c1799beffad603a71665277cf34a6862fa2e337310df6129e",
"md5": "3797810b59640e52b00dd298b0b0460b",
"sha256": "dc1632feeaa0b2cab36bb4ea9abdc5e77a5410ba81c01aa28e9f39a1edd75507"
},
"downloads": -1,
"filename": "arize_phoenix_client-1.18.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3797810b59640e52b00dd298b0b0460b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.9",
"size": 123564,
"upload_time": "2025-09-10T19:36:55",
"upload_time_iso_8601": "2025-09-10T19:36:55.574800Z",
"url": "https://files.pythonhosted.org/packages/3d/53/1436070e954c1799beffad603a71665277cf34a6862fa2e337310df6129e/arize_phoenix_client-1.18.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "47c5f4d99be5434a1725e23fa655acd34c8abd51d70e76329147f66ba93a9237",
"md5": "30306a3de656b33649c8a9456cdbef7b",
"sha256": "8e1aab8b503c217e519f3257d8cd390f2470c98a64a969feefca6b3d648f1497"
},
"downloads": -1,
"filename": "arize_phoenix_client-1.18.1.tar.gz",
"has_sig": false,
"md5_digest": "30306a3de656b33649c8a9456cdbef7b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.9",
"size": 118906,
"upload_time": "2025-09-10T19:36:56",
"upload_time_iso_8601": "2025-09-10T19:36:56.893397Z",
"url": "https://files.pythonhosted.org/packages/47/c5/f4d99be5434a1725e23fa655acd34c8abd51d70e76329147f66ba93a9237/arize_phoenix_client-1.18.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 19:36:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Arize-ai",
"github_project": "phoenix",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "arize-phoenix-client"
}
JSON
