tessl/npm-arizeai--phoenix-client
A TypeScript client for the Phoenix API providing AI observability, prompt management, datasets, experiments, and tracing capabilities.
client.mddocs/
Core Client
The core Phoenix client provides direct access to all Phoenix API endpoints through a strongly-typed OpenAPI interface with automatic configuration management and middleware support.
Capabilities
Client Creation
Creates a Phoenix API client with optional configuration customization.
/**
* Create a Phoenix client with strongly-typed OpenAPI interfaces
* @param config - Configuration object with options and environment function
* @returns Configured Phoenix client instance
*/
function createClient(config?: {
options?: Partial<ClientOptions>;
getEnvironmentOptions?: () => Partial<ClientOptions>;
}): PhoenixClient;
interface ClientOptions {
baseUrl?: string;
headers?: Record<string, string>;
signal?: AbortSignal;
[key: string]: unknown;
}
interface PhoenixClient {
GET<T = unknown>(
url: string,
options?: { params?: { query?: Record<string, unknown>; path?: Record<string, unknown> }; body?: unknown; headers?: Record<string, string> }
): Promise<{ data?: T; error?: unknown; response: Response }>;
POST<T = unknown>(
url: string,
options?: { params?: { query?: Record<string, unknown>; path?: Record<string, unknown> }; body?: unknown; headers?: Record<string, string> }
): Promise<{ data?: T; error?: unknown; response: Response }>;
PUT<T = unknown>(
url: string,
options?: { params?: { query?: Record<string, unknown>; path?: Record<string, unknown> }; body?: unknown; headers?: Record<string, string> }
): Promise<{ data?: T; error?: unknown; response: Response }>;
DELETE<T = unknown>(
url: string,
options?: { params?: { query?: Record<string, unknown>; path?: Record<string, unknown> }; body?: unknown; headers?: Record<string, string> }
): Promise<{ data?: T; error?: unknown; response: Response }>;
PATCH<T = unknown>(
url: string,
options?: { params?: { query?: Record<string, unknown>; path?: Record<string, unknown> }; body?: unknown; headers?: Record<string, string> }
): Promise<{ data?: T; error?: unknown; response: Response }>;
config: ClientOptions;
use(middleware: Middleware): void;
}
interface Middleware {
onRequest?: (request: { url: string; options: RequestInit }) => void | Promise<void>;
onResponse?: (response: { response: Response; url: string; options: RequestInit }) => void | Promise<void>;
}Usage Example:
import { createClient } from "@arizeai/phoenix-client";
// Default client (localhost:6006)
const client = createClient();
// Custom configuration
const client = createClient({
options: {
baseUrl: "https://your-phoenix-instance.com",
headers: {
"Custom-Header": "value"
}
}
});
// Make API calls
const traces = await client.GET("/v1/traces", {
params: {
query: {
limit: 50,
start_time: "2024-01-01T00:00:00Z"
}
}
});Configuration Merging
Utility for merging configuration options with priority handling.
/**
* Merge configuration options with priority: defaults < environment < explicit options
* @param params - Configuration parameters
* @returns Merged configuration options
*/
function getMergedOptions(params?: {
options?: Partial<ClientOptions>;
getEnvironmentOptions?: () => Partial<ClientOptions>;
}): ClientOptions;Usage Example:
import { getMergedOptions } from "@arizeai/phoenix-client";
// Get merged configuration before creating client
const config = getMergedOptions({
options: {
baseUrl: "https://custom-phoenix.com",
headers: { "X-API-Version": "v1" }
}
});
const client = createClient({ options: config });Environment Configuration
Default environment configuration system that reads from process environment variables.
/**
* Get environment-based configuration from process.env
* Supports PHOENIX_API_KEY, PHOENIX_HOST, PHOENIX_CLIENT_HEADERS
* @returns Configuration options from environment variables
*/
function defaultGetEnvironmentOptions(): Partial<ClientOptions>;
/**
* Create default client configuration
* @returns Default configuration with localhost:6006 as baseUrl
*/
function makeDefaultClientOptions(): Partial<ClientOptions>;Environment Variables:
PHOENIX_API_KEY: Sets Authorization header as Bearer tokenPHOENIX_HOST: Sets the baseUrl for the clientPHOENIX_CLIENT_HEADERS: JSON string of additional headers
Usage Example:
// Environment variables:
// PHOENIX_HOST=https://phoenix.company.com
// PHOENIX_API_KEY=your-secret-key
// PHOENIX_CLIENT_HEADERS={"X-Team": "ai-platform"}
import { createClient } from "@arizeai/phoenix-client";
// Automatically uses environment configuration
const client = createClient();Type Definitions
Complete OpenAPI-generated type definitions for all Phoenix API interactions.
/**
* Generated OpenAPI types organized by API version
*/
interface Types {
V1: {
paths: pathsV1;
components: componentsV1;
operations: operationsV1;
};
}
type pathsV1 = {
"/v1/traces": {
get: operations["getTraces"];
};
"/v1/prompts": {
get: operations["getPrompts"];
post: operations["createPrompt"];
};
"/v1/datasets": {
get: operations["getDatasets"];
post: operations["createDataset"];
};
// ... all other API endpoints
};
type componentsV1 = {
schemas: {
Prompt: { /* OpenAPI schema */ };
Dataset: { /* OpenAPI schema */ };
Experiment: { /* OpenAPI schema */ };
// ... all other component schemas
};
};
type operationsV1 = {
getTraces: {
parameters: { /* parameter definitions */ };
responses: { /* response definitions */ };
};
// ... all other operations
};Error Handling
The client includes built-in error handling middleware that throws errors for non-successful responses.
Error Format:
Errors thrown by the client follow the format: "<URL>: <status> <statusText>"
Usage Example:
import { createClient } from "@arizeai/phoenix-client";
const client = createClient();
try {
const result = await client.GET("/v1/nonexistent-endpoint");
} catch (error) {
console.error(error.message);
// Output: "http://localhost:6006/v1/nonexistent-endpoint: 404 Not Found"
}Install with Tessl CLI
npx tessl i tessl/npm-arizeai--phoenix-client