or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client.mddatasets.mdexperiments.mdindex.mdprompts.mdsdk-integration.mdspans.md
tile.json

tessl/npm-arizeai--phoenix-client

A TypeScript client for the Phoenix API providing AI observability, prompt management, datasets, experiments, and tracing capabilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@arizeai/phoenix-client@4.0.x

To install, run

npx @tessl/cli install tessl/npm-arizeai--phoenix-client@4.0.0

index.mddocs/

Phoenix Client

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.

Overview

Phoenix Client enables seamless integration with the Arize Phoenix AI observability platform through a strongly-typed TypeScript client. Key features include:

  • Prompt Management: Create, version, and retrieve prompt templates with multi-provider support
  • Dataset Operations: Manage evaluation datasets with structured examples and metadata
  • Experiment Execution: Run evaluations with parallel execution and OpenTelemetry instrumentation
  • Span Tracing: Access and annotate trace data for AI application observability
  • SDK Integration: Format conversion utilities for OpenAI, Anthropic, and Vercel AI SDK
  • Type Safety: Complete TypeScript definitions generated from OpenAPI specifications

Package Information

  • Package Name: @arizeai/phoenix-client
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @arizeai/phoenix-client

Core Imports

import { createClient } from "@arizeai/phoenix-client";

For specialized modules:

import { getPrompt, createPrompt } from "@arizeai/phoenix-client/prompts";
import { createDataset, getDataset } from "@arizeai/phoenix-client/datasets";
import { runExperiment } from "@arizeai/phoenix-client/experiments";
import { getSpans, addSpanAnnotation } from "@arizeai/phoenix-client/spans";

For CommonJS:

const { createClient } = require("@arizeai/phoenix-client");
const { getPrompt, createPrompt } = require("@arizeai/phoenix-client/prompts");

Basic Usage

import { createClient } from "@arizeai/phoenix-client";

// Create a Phoenix client with default configuration
const client = createClient();

// Or with custom configuration
const client = createClient({
  options: {
    baseUrl: "https://your-phoenix-instance.com",
    headers: {
      Authorization: "Bearer your-api-key"
    }
  }
});

// Make API calls using strongly-typed methods
const traces = await client.GET("/v1/traces", {
  params: {
    query: {
      limit: 10
    }
  }
});

Architecture

Phoenix Client is built around several key components:

  • OpenAPI Client: Auto-generated strongly-typed client from Phoenix's OpenAPI specification
  • Configuration System: Environment-based configuration with flexible override options
  • Module Organization: Specialized modules for prompts, datasets, experiments, and spans
  • SDK Integrations: Format conversion utilities for OpenAI, Anthropic, and Vercel AI SDK
  • OpenTelemetry Integration: Built-in tracing and instrumentation capabilities
  • Type Safety: Complete TypeScript type definitions for all API interactions

Capabilities

Core Client

Foundation client providing direct access to all Phoenix API endpoints with strongly-typed interfaces and automatic configuration management.

function createClient(config?: {
  options?: Partial<ClientOptions>;
  getEnvironmentOptions?: () => Partial<ClientOptions>;
}): PhoenixClient;

interface PhoenixClient {
  GET<T>(path: string, options?: RequestOptions): Promise<T>;
  POST<T>(path: string, options?: RequestOptions): Promise<T>;
  PUT<T>(path: string, options?: RequestOptions): Promise<T>;
  DELETE<T>(path: string, options?: RequestOptions): Promise<T>;
  config: ClientOptions;
}

function getMergedOptions(params?: {
  options?: Partial<ClientOptions>;
  getEnvironmentOptions?: () => Partial<ClientOptions>;
}): ClientOptions;

Core Client

Prompt Management

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.

function getPrompt(params: {
  client?: PhoenixClient;
  prompt: PromptSelector;
}): Promise<PromptVersion | null>;

function createPrompt(params: {
  client?: PhoenixClient;
  name: string;
  description?: string;
  version: PromptVersionData;
}): Promise<PromptVersion>;

function promptVersion(params: PromptVersionInput): PromptVersionData;

interface PromptVersion {
  id: string;
  prompt_id: string;
  version: number;
  model_name: string;
  model_provider: PromptModelProvider;
  template: PromptTemplate;
  invocation_parameters: InvocationParameters;
  tools?: PromptTools | null;
  response_format?: PromptResponseFormat | null;
}

interface PromptTools {
  type: "tools";
  tools: PromptToolFunction[];
  tool_choice?: PromptToolChoice;
  disable_parallel_tool_calls?: boolean;
}

interface PromptResponseFormat {
  type: "json_schema";
  json_schema: {
    name: string;
    schema: Record<string, unknown>;
    strict?: boolean;
  };
}

Prompt Management

Dataset Management

Dataset creation, management, and versioning system for AI evaluation and experimentation workflows. Supports structured examples with input/output pairs and metadata.

function createDataset(params: {
  client?: PhoenixClient;
  name: string;
  description: string;
  examples: Example[];
}): Promise<CreateDatasetResponse>;

function getDataset(params: {
  client?: PhoenixClient;
  dataset: DatasetSelector;
  versionId?: string;
}): Promise<Dataset>;

interface Dataset {
  id: string;
  name: string;
  description?: string;
  examples: ExampleWithId[];
  versionId: string;
}

interface Example {
  input: Record<string, unknown>;
  output?: Record<string, unknown> | null;
  metadata?: Record<string, unknown> | null;
}

Dataset Management

Experiment Execution

Comprehensive experiment execution system with evaluation capabilities, progress tracking, and OpenTelemetry instrumentation for AI model testing and evaluation.

function runExperiment(params: {
  client?: PhoenixClient;
  dataset: DatasetSelector;
  task: ExperimentTask;
  evaluators?: Evaluator[];
  metadata?: Record<string, unknown>;
  concurrency?: number;
  repetitions?: number;
}): Promise<RanExperiment>;

interface ExperimentTask {
  (example: Example): Promise<Record<string, unknown>>;
}

interface Evaluator {
  name: string;
  evaluate: (example: Example, output: Record<string, unknown>) => Promise<EvaluationResult>;
}

Experiment Execution

Span Tracing and Annotation

Tracing data access and annotation system for observability, debugging, and evaluation of AI applications with OpenTelemetry integration.

function getSpans(params: {
  client?: PhoenixClient;
  project: ProjectSelector;
  startTime?: Date | string;
  endTime?: Date | string;
  cursor?: string;
  limit?: number;
}): Promise<GetSpansResult>;

function addSpanAnnotation(params: {
  client?: PhoenixClient;
  spanId: string;
  name: string;
  label?: string;
  score?: number;
  explanation?: string;
  annotatorKind?: AnnotatorKind;
}): Promise<void>;

Span Tracing

SDK Format Conversion

Format conversion utilities for seamless integration with popular LLM provider SDKs including OpenAI, Anthropic, and Vercel AI SDK.

function toSDK<T extends SupportedSDK, V extends Variables = Variables>(
  params: ToSDKParams<T, V> & SDKParams<T>
): ReturnType<SDKConverter<T>>;

type Variables = Record<string, string | { toString: () => string }>;

type SupportedSDK = "openai" | "anthropic" | "ai";

SDK Integration