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)