0
# Phoenix Client
1
2
Phoenix Client is a comprehensive TypeScript client library for the Arize Phoenix API, an open-source AI observability platform. It provides a complete interface for prompt management with version control, dataset creation and management, experiment execution and evaluation, span tracing and annotation, and direct access to all Phoenix REST API endpoints through strongly-typed interfaces.
3
4
## Overview
5
6
Phoenix Client enables seamless integration with the Arize Phoenix AI observability platform through a strongly-typed TypeScript client. Key features include:
7
8
- **Prompt Management**: Create, version, and retrieve prompt templates with multi-provider support
9
- **Dataset Operations**: Manage evaluation datasets with structured examples and metadata
10
- **Experiment Execution**: Run evaluations with parallel execution and OpenTelemetry instrumentation
11
- **Span Tracing**: Access and annotate trace data for AI application observability
12
- **SDK Integration**: Format conversion utilities for OpenAI, Anthropic, and Vercel AI SDK
13
- **Type Safety**: Complete TypeScript definitions generated from OpenAPI specifications
14
15
## Package Information
16
17
- **Package Name**: @arizeai/phoenix-client
18
- **Package Type**: npm
19
- **Language**: TypeScript
20
- **Installation**: `npm install @arizeai/phoenix-client`
21
22
## Core Imports
23
24
```typescript
25
import { createClient } from "@arizeai/phoenix-client";
26
```
27
28
For specialized modules:
29
30
```typescript
31
import { getPrompt, createPrompt } from "@arizeai/phoenix-client/prompts";
32
import { createDataset, getDataset } from "@arizeai/phoenix-client/datasets";
33
import { runExperiment } from "@arizeai/phoenix-client/experiments";
34
import { getSpans, addSpanAnnotation } from "@arizeai/phoenix-client/spans";
35
```
36
37
For CommonJS:
38
39
```javascript
40
const { createClient } = require("@arizeai/phoenix-client");
41
const { getPrompt, createPrompt } = require("@arizeai/phoenix-client/prompts");
42
```
43
44
## Basic Usage
45
46
```typescript
47
import { createClient } from "@arizeai/phoenix-client";
48
49
// Create a Phoenix client with default configuration
50
const client = createClient();
51
52
// Or with custom configuration
53
const client = createClient({
54
options: {
55
baseUrl: "https://your-phoenix-instance.com",
56
headers: {
57
Authorization: "Bearer your-api-key"
58
}
59
}
60
});
61
62
// Make API calls using strongly-typed methods
63
const traces = await client.GET("/v1/traces", {
64
params: {
65
query: {
66
limit: 10
67
}
68
}
69
});
70
```
71
72
## Architecture
73
74
Phoenix Client is built around several key components:
75
76
- **OpenAPI Client**: Auto-generated strongly-typed client from Phoenix's OpenAPI specification
77
- **Configuration System**: Environment-based configuration with flexible override options
78
- **Module Organization**: Specialized modules for prompts, datasets, experiments, and spans
79
- **SDK Integrations**: Format conversion utilities for OpenAI, Anthropic, and Vercel AI SDK
80
- **OpenTelemetry Integration**: Built-in tracing and instrumentation capabilities
81
- **Type Safety**: Complete TypeScript type definitions for all API interactions
82
83
## Capabilities
84
85
### Core Client
86
87
Foundation client providing direct access to all Phoenix API endpoints with strongly-typed interfaces and automatic configuration management.
88
89
```typescript { .api }
90
function createClient(config?: {
91
options?: Partial<ClientOptions>;
92
getEnvironmentOptions?: () => Partial<ClientOptions>;
93
}): PhoenixClient;
94
95
interface PhoenixClient {
96
GET<T>(path: string, options?: RequestOptions): Promise<T>;
97
POST<T>(path: string, options?: RequestOptions): Promise<T>;
98
PUT<T>(path: string, options?: RequestOptions): Promise<T>;
99
DELETE<T>(path: string, options?: RequestOptions): Promise<T>;
100
config: ClientOptions;
101
}
102
103
function getMergedOptions(params?: {
104
options?: Partial<ClientOptions>;
105
getEnvironmentOptions?: () => Partial<ClientOptions>;
106
}): ClientOptions;
107
```
108
109
[Core Client](./client.md)
110
111
### Prompt Management
112
113
Comprehensive prompt management system with version control, tagging, and multi-provider support. Enables creation, retrieval, and management of prompt templates with format conversion for popular LLM SDKs.
114
115
```typescript { .api }
116
function getPrompt(params: {
117
client?: PhoenixClient;
118
prompt: PromptSelector;
119
}): Promise<PromptVersion | null>;
120
121
function createPrompt(params: {
122
client?: PhoenixClient;
123
name: string;
124
description?: string;
125
version: PromptVersionData;
126
}): Promise<PromptVersion>;
127
128
function promptVersion(params: PromptVersionInput): PromptVersionData;
129
130
interface PromptVersion {
131
id: string;
132
prompt_id: string;
133
version: number;
134
model_name: string;
135
model_provider: PromptModelProvider;
136
template: PromptTemplate;
137
invocation_parameters: InvocationParameters;
138
tools?: PromptTools | null;
139
response_format?: PromptResponseFormat | null;
140
}
141
142
interface PromptTools {
143
type: "tools";
144
tools: PromptToolFunction[];
145
tool_choice?: PromptToolChoice;
146
disable_parallel_tool_calls?: boolean;
147
}
148
149
interface PromptResponseFormat {
150
type: "json_schema";
151
json_schema: {
152
name: string;
153
schema: Record<string, unknown>;
154
strict?: boolean;
155
};
156
}
157
```
158
159
[Prompt Management](./prompts.md)
160
161
### Dataset Management
162
163
Dataset creation, management, and versioning system for AI evaluation and experimentation workflows. Supports structured examples with input/output pairs and metadata.
164
165
```typescript { .api }
166
function createDataset(params: {
167
client?: PhoenixClient;
168
name: string;
169
description: string;
170
examples: Example[];
171
}): Promise<CreateDatasetResponse>;
172
173
function getDataset(params: {
174
client?: PhoenixClient;
175
dataset: DatasetSelector;
176
versionId?: string;
177
}): Promise<Dataset>;
178
179
interface Dataset {
180
id: string;
181
name: string;
182
description?: string;
183
examples: ExampleWithId[];
184
versionId: string;
185
}
186
187
interface Example {
188
input: Record<string, unknown>;
189
output?: Record<string, unknown> | null;
190
metadata?: Record<string, unknown> | null;
191
}
192
```
193
194
[Dataset Management](./datasets.md)
195
196
### Experiment Execution
197
198
Comprehensive experiment execution system with evaluation capabilities, progress tracking, and OpenTelemetry instrumentation for AI model testing and evaluation.
199
200
```typescript { .api }
201
function runExperiment(params: {
202
client?: PhoenixClient;
203
dataset: DatasetSelector;
204
task: ExperimentTask;
205
evaluators?: Evaluator[];
206
metadata?: Record<string, unknown>;
207
concurrency?: number;
208
repetitions?: number;
209
}): Promise<RanExperiment>;
210
211
interface ExperimentTask {
212
(example: Example): Promise<Record<string, unknown>>;
213
}
214
215
interface Evaluator {
216
name: string;
217
evaluate: (example: Example, output: Record<string, unknown>) => Promise<EvaluationResult>;
218
}
219
```
220
221
[Experiment Execution](./experiments.md)
222
223
### Span Tracing and Annotation
224
225
Tracing data access and annotation system for observability, debugging, and evaluation of AI applications with OpenTelemetry integration.
226
227
```typescript { .api }
228
function getSpans(params: {
229
client?: PhoenixClient;
230
project: ProjectSelector;
231
startTime?: Date | string;
232
endTime?: Date | string;
233
cursor?: string;
234
limit?: number;
235
}): Promise<GetSpansResult>;
236
237
function addSpanAnnotation(params: {
238
client?: PhoenixClient;
239
spanId: string;
240
name: string;
241
label?: string;
242
score?: number;
243
explanation?: string;
244
annotatorKind?: AnnotatorKind;
245
}): Promise<void>;
246
```
247
248
[Span Tracing](./spans.md)
249
250
### SDK Format Conversion
251
252
Format conversion utilities for seamless integration with popular LLM provider SDKs including OpenAI, Anthropic, and Vercel AI SDK.
253
254
```typescript { .api }
255
function toSDK<T extends SupportedSDK, V extends Variables = Variables>(
256
params: ToSDKParams<T, V> & SDKParams<T>
257
): ReturnType<SDKConverter<T>>;
258
259
type Variables = Record<string, string | { toString: () => string }>;
260
261
type SupportedSDK = "openai" | "anthropic" | "ai";
262
```
263
264
[SDK Integration](./sdk-integration.md)