@arizeai/phoenix-client 2.3.4 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "2.3.4",
+  "version": "2.4.0",
   "description": "A client for the Phoenix API",
   "main": "dist/src/index.js",
   "module": "dist/esm/index.js",
@@ -40,8 +40,17 @@
     "src",
     "package.json"
   ],
-  "keywords": [],
-  "author": "",
+  "keywords": [
+    "phoenix",
+    "arize",
+    "llm",
+    "tracing",
+    "evaluation",
+    "prompts",
+    "datasets",
+    "experiments"
+  ],
+  "author": "oss@arize.com",
   "license": "ELv2",
   "devDependencies": {
     "@ai-sdk/openai": "^1.1.15",
@@ -52,7 +61,6 @@
     "openai": "^4.77.0",
     "openapi-typescript": "^7.6.1",
     "tsx": "^4.19.3",
-    "typedoc": "^0.27.9",
     "vitest": "^2.1.9"
   },
   "dependencies": {
@@ -86,8 +94,6 @@
     "build": "tsc --build tsconfig.json tsconfig.esm.json && tsc-alias -p tsconfig.esm.json",
     "postbuild": "echo '{\"type\": \"module\"}' > ./dist/esm/package.json && rimraf dist/test dist/examples",
     "type:check": "tsc --noEmit",
-    "test": "vitest --typecheck",
-    "docs": "typedoc",
-    "docs:preview": "pnpx http-server ./docs -p 8080 -o"
+    "test": "vitest --typecheck"
   }
 }

package/src/client.ts

@@ -9,9 +9,9 @@ import {
   makeDefaultClientOptions,
 } from "./config";
 
-type pathsV1 = oapiPathsV1;
-type componentsV1 = oapiComponentsV1;
-type operationsV1 = oapiOperationsV1;
+export type pathsV1 = oapiPathsV1;
+export type componentsV1 = oapiComponentsV1;
+export type operationsV1 = oapiOperationsV1;
 
 /**
  * Generated openapi types for the Phoenix client, by API version.

package/src/datasets/getDataset.ts

@@ -6,19 +6,23 @@ import { getDatasetInfo } from "./getDatasetInfo";
 
 export type GetDatasetParams = ClientFn & {
   dataset: DatasetSelector;
+  versionId?: string;
 };
 
 /**
- * Get dataset info and the examples from the latest version of the dataset
+ * Get dataset info and examples from the dataset
+ * @param dataset - Dataset selector (ID or name)
+ * @param versionId - Optional specific version ID (if omitted, returns data from the latest version)
  */
 export async function getDataset({
   client: _client,
   dataset,
+  versionId,
 }: GetDatasetParams): Promise<Dataset> {
   const client = _client || createClient();
   const [datasetInfo, datasetExamples] = await Promise.all([
     getDatasetInfo({ client, dataset }),
-    getDatasetExamples({ client, dataset }),
+    getDatasetExamples({ client, dataset, versionId }),
   ]);
   return {
     ...datasetInfo,

package/src/datasets/getDatasetExamples.ts

@@ -6,17 +6,23 @@ import { getDatasetInfoByName } from "./getDatasetInfoByName";
 
 export type GetDatasetExamplesParams = ClientFn & {
   dataset: DatasetSelector;
+  versionId?: string;
 };
 
 /**
- * Get the latest examples from a dataset
+ * Get examples from a dataset
+ * @param dataset - Dataset selector (ID, name, or version ID)
+ * @param versionId - Optional specific version ID (ignored if dataset selector is datasetVersionId)
  */
 export async function getDatasetExamples({
   client: _client,
   dataset,
+  versionId,
 }: GetDatasetExamplesParams): Promise<DatasetExamples> {
   const client = _client || createClient();
+
   let datasetId: string;
+
   if ("datasetName" in dataset) {
     const datasetInfo = await getDatasetInfoByName({
       client,
@@ -26,13 +32,20 @@ export async function getDatasetExamples({
   } else {
     datasetId = dataset.datasetId;
   }
+
   const response = await client.GET("/v1/datasets/{id}/examples", {
     params: {
       path: {
         id: datasetId,
       },
+      query: versionId
+        ? {
+            version_id: versionId,
+          }
+        : undefined,
     },
   });
+
   invariant(response.data?.data, "Failed to get dataset examples");
   const examplesData = response.data.data;
   return {

package/src/datasets/getDatasetInfo.ts

@@ -11,12 +11,14 @@ export type GetDatasetInfoParams = ClientFn & {
 /**
  * Get an overview of the information in a dataset
  * Note: this does not include the examples contained in the dataset
+ * Dataset info is not version-specific, only examples are versioned
  */
 export async function getDatasetInfo({
   client: _client,
   dataset,
 }: GetDatasetInfoParams): Promise<DatasetInfo> {
   const client = _client || createClient();
+
   if ("datasetName" in dataset) {
     return await getDatasetInfoByName({
       client,

package/src/datasets/index.ts

@@ -2,5 +2,4 @@ export * from "./createDataset";
 export * from "./getDataset";
 export * from "./getDatasetExamples";
 export * from "./appendDatasetExamples";
-export * from "./getDatasetExamples";
 export * from "./getDatasetInfo";

package/src/datasets/listDatasets.ts

@@ -5,7 +5,7 @@ import invariant from "tiny-invariant";
 
 export type ListDatasetsParams = ClientFn;
 
-type FullDatasetInfo = DatasetInfo & {
+export type FullDatasetInfo = DatasetInfo & {
   startDate: Date;
   endDate: Date;
 };

package/src/experiments/runExperiment.ts

@@ -684,8 +684,10 @@ async function runEvaluator({
  *
  * @experimental This feature is not complete, and will change in the future.
  *
- * @param name - The name of the evaluator.
- * @param evaluate - The evaluator function.
+ * @param params - The parameters for creating the evaluator
+ * @param params.name - The name of the evaluator.
+ * @param params.kind - The kind of evaluator (e.g., "CODE", "LLM")
+ * @param params.evaluate - The evaluator function.
  * @returns The evaluator object.
  */
 export function asEvaluator({

package/src/prompts/createPrompt.ts

@@ -82,17 +82,17 @@ interface PromptVersionInputBase {
   templateFormat?: PromptVersionData["template_format"];
 }
 
-interface OpenAIPromptVersionInput extends PromptVersionInputBase {
+export interface OpenAIPromptVersionInput extends PromptVersionInputBase {
   modelProvider: "OPENAI";
   invocationParameters?: OpenAIInvocationParameters;
 }
 
-interface AzureOpenAIPromptVersionInput extends PromptVersionInputBase {
+export interface AzureOpenAIPromptVersionInput extends PromptVersionInputBase {
   modelProvider: "AZURE_OPENAI";
   invocationParameters?: AzureOpenAIInvocationParameters;
 }
 
-interface AnthropicPromptVersionInput extends PromptVersionInputBase {
+export interface AnthropicPromptVersionInput extends PromptVersionInputBase {
   modelProvider: "ANTHROPIC";
   /**
    * The invocation parameters for the prompt version.
@@ -101,32 +101,32 @@ interface AnthropicPromptVersionInput extends PromptVersionInputBase {
   invocationParameters: AnthropicInvocationParameters;
 }
 
-interface GooglePromptVersionInput extends PromptVersionInputBase {
+export interface GooglePromptVersionInput extends PromptVersionInputBase {
   modelProvider: "GOOGLE";
   invocationParameters?: GoogleInvocationParameters;
 }
 
-interface DeepSeekPromptVersionInput extends PromptVersionInputBase {
+export interface DeepSeekPromptVersionInput extends PromptVersionInputBase {
   modelProvider: "DEEPSEEK";
   invocationParameters?: DeepSeekInvocationParameters;
 }
 
-interface XAIPromptVersionInput extends PromptVersionInputBase {
+export interface XAIPromptVersionInput extends PromptVersionInputBase {
   modelProvider: "XAI";
   invocationParameters?: XAIInvocationParameters;
 }
 
-interface OllamaPromptVersionInput extends PromptVersionInputBase {
+export interface OllamaPromptVersionInput extends PromptVersionInputBase {
   modelProvider: "OLLAMA";
   invocationParameters?: OllamaInvocationParameters;
 }
 
-interface AwsPromptVersionInput extends PromptVersionInputBase {
+export interface AwsPromptVersionInput extends PromptVersionInputBase {
   modelProvider: "AWS";
   invocationParameters?: AwsInvocationParameters;
 }
 
-type PromptVersionInput =
+export type PromptVersionInput =
   | OpenAIPromptVersionInput
   | AzureOpenAIPromptVersionInput
   | AnthropicPromptVersionInput

package/src/prompts/sdks/toSDK.ts

@@ -23,7 +23,7 @@ export type SDKParams<T extends SupportedSDK> = Parameters<
 /**
  * Map of SDK names to their corresponding conversion functions
  */
-const PROVIDER_TO_SDK = {
+export const PROVIDER_TO_SDK = {
   openai: toOpenAI,
   anthropic: toAnthropic,
   ai: toAI,
@@ -48,7 +48,10 @@ const getTargetSDK = <T extends SupportedSDK>(sdk: T) => {
 /**
  * Parameters specific to the toSDK function
  */
-type ToSDKParams<T extends SupportedSDK, V extends Variables = Variables> = {
+export type ToSDKParams<
+  T extends SupportedSDK,
+  V extends Variables = Variables,
+> = {
   /**
    * String representing the SDK to convert to
    */

package/src/schemas/jsonLiteralSchema.ts

@@ -4,8 +4,13 @@ import z from "zod";
  * The zod schema for JSON literal primitives
  * @see {@link https://zod.dev/?id=json-type|Zod Documentation}
  */
-const literalSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
-type Literal = z.infer<typeof literalSchema>;
+export const literalSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+]);
+export type Literal = z.infer<typeof literalSchema>;
 export type JSONLiteral =
   | Literal
   | { [key: string]: JSONLiteral }

package/src/schemas/llm/converters.ts

@@ -211,7 +211,7 @@ export const fromOpenAIMessage = <
 
 /**
  * Converts a tool call to the OpenAI format if possible
- * @param toolCall a tool call from an unknown LlmProvider
+ * @param maybeToolCall a tool call from an unknown LlmProvider
  * @returns the tool call parsed to the OpenAI format
  */
 export const toOpenAIToolCall = (
@@ -243,8 +243,9 @@ export const toOpenAIToolCall = (
 
 /**
  * Converts a tool call to a target provider format
- * @param toolCall the tool call to convert
- * @param targetProvider the provider to convert the tool call to
+ * @param params the parameters object
+ * @param params.toolCall the tool call to convert
+ * @param params.targetProvider the provider to convert the tool call to
  * @returns the tool call in the target provider format
  */
 export const fromOpenAIToolCall = <
@@ -316,10 +317,11 @@ export const toOpenAIToolChoice = (
 };
 
 /**
- * Converts a tool call to a target provider format
- * @param toolCall the tool call to convert
- * @param targetProvider the provider to convert the tool call to
- * @returns the tool call in the target provider format
+ * Converts a tool choice to a target provider format
+ * @param params the parameters object
+ * @param params.toolChoice the tool choice to convert
+ * @param params.targetProvider the provider to convert the tool choice to
+ * @returns the tool choice in the target provider format
  */
 export const fromOpenAIToolChoice = <
   TargetProviderSDK extends NonNullable<PromptSDKFormat>,

package/src/spans/addSpanAnnotation.ts

@@ -5,7 +5,7 @@ import { SpanAnnotation, toSpanAnnotationData } from "./types";
 /**
  * Parameters to add a span annotation
  */
-interface AddSpanAnnotationParams extends ClientFn {
+export interface AddSpanAnnotationParams extends ClientFn {
   spanAnnotation: SpanAnnotation;
 }
 

package/src/spans/getSpanAnnotations.ts

@@ -6,7 +6,7 @@ import { ProjectSelector } from "../types/projects";
 /**
  * Parameters to get span annotations from a project using auto-generated types
  */
-interface GetSpanAnnotationsParams extends ClientFn {
+export interface GetSpanAnnotationsParams extends ClientFn {
   /** The project to get span annotations from */
   project: ProjectSelector;
   /** One or more span IDs to fetch annotations for */
@@ -21,7 +21,7 @@ interface GetSpanAnnotationsParams extends ClientFn {
   limit?: number;
 }
 
-type GetSpanAnnotationsResponse =
+export type GetSpanAnnotationsResponse =
   operations["listSpanAnnotationsBySpanIds"]["responses"]["200"];
 
 export type GetSpanAnnotationsResult = {

package/src/spans/getSpans.ts

@@ -6,7 +6,7 @@ import { ProjectSelector } from "../types/projects";
 /**
  * Parameters to get spans from a project using auto-generated types
  */
-interface GetSpansParams extends ClientFn {
+export interface GetSpansParams extends ClientFn {
   /** The project to get spans from */
   project: ProjectSelector;
   /** Inclusive lower bound time. Must be a valid ISO 8601 string or Date object. */
@@ -19,7 +19,7 @@ interface GetSpansParams extends ClientFn {
   limit?: number;
 }
 
-type GetSpansResponse = operations["getSpans"]["responses"]["200"];
+export type GetSpansResponse = operations["getSpans"]["responses"]["200"];
 
 export type GetSpansResult = {
   spans: GetSpansResponse["content"]["application/json"]["data"];

package/src/spans/logSpanAnnotations.ts

@@ -5,7 +5,7 @@ import { SpanAnnotation, toSpanAnnotationData } from "./types";
 /**
  * Parameters to log multiple span annotations
  */
-interface LogSpanAnnotationsParams extends ClientFn {
+export interface LogSpanAnnotationsParams extends ClientFn {
   /**
    * The span annotations to log
    */

package/src/types/datasets.ts

@@ -1,11 +1,18 @@
 import { Node } from "./core";
 
 /**
- * A dataset can be identified by its datasetId
- * TODO: add support for datasetVersionId via discriminated union
+ * A dataset can be identified by its datasetId, datasetName, or datasetVersionId
  */
 export type DatasetSelector = { datasetId: string } | { datasetName: string };
 
+/**
+ * Parameters for selecting a specific version of a dataset
+ */
+export interface DatasetVersionSelector {
+  dataset: DatasetSelector;
+  versionId?: string;
+}
+
 /**
  * Overview information about a dataset
  */
@@ -15,6 +22,15 @@ export interface DatasetInfo extends Node {
   metadata?: Record<string, unknown>;
 }
 
+/**
+ * Information about a dataset version
+ */
+export interface DatasetVersionInfo extends Node {
+  description?: string | null;
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+}
+
 /**
  * A dataset's examples
  */
@@ -46,3 +62,10 @@ export interface ExampleWithId extends Example, Node {
  * A dataset is a collection of examples for an AI task
  */
 export interface Dataset extends DatasetInfo, DatasetExamples, Node {}
+
+/**
+ * A dataset with its version information
+ */
+export interface DatasetWithVersion extends Dataset {
+  versionInfo: DatasetVersionInfo;
+}

package/src/utils/urlUtils.ts

@@ -13,9 +13,10 @@ function getWebBaseUrl(baseUrl: string): string {
 
 /**
  * Get the URL to view a specific experiment in the Phoenix web UI
- * @param baseUrl The base URL of the Phoenix API
- * @param datasetId The ID of the dataset
- * @param experimentId The ID of the experiment
+ * @param params - The parameters for generating the experiment URL
+ * @param params.baseUrl - The base URL of the Phoenix API
+ * @param params.datasetId - The ID of the dataset
+ * @param params.experimentId - The ID of the experiment
  * @returns The URL to view the experiment
  */
 export function getExperimentUrl({
@@ -32,8 +33,9 @@ export function getExperimentUrl({
 
 /**
  * Get the URL to view experiments for a dataset in the Phoenix web UI
- * @param baseUrl The base URL of the Phoenix API
- * @param datasetId The ID of the dataset
+ * @param params - The parameters for generating the dataset experiments URL
+ * @param params.baseUrl - The base URL of the Phoenix API
+ * @param params.datasetId - The ID of the dataset
  * @returns The URL to view dataset experiments
  */
 export function getDatasetExperimentsUrl({
@@ -48,8 +50,9 @@ export function getDatasetExperimentsUrl({
 
 /**
  * Get the URL to view a dataset in the Phoenix web UI
- * @param baseUrl The base URL of the Phoenix API
- * @param datasetId The ID of the dataset
+ * @param params - The parameters for generating the dataset URL
+ * @param params.baseUrl - The base URL of the Phoenix API
+ * @param params.datasetId - The ID of the dataset
  * @returns The URL to view the dataset
  */
 export function getDatasetUrl({