@arizeai/phoenix-client 1.2.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "A client for the Phoenix API",
   "main": "dist/src/index.js",
   "module": "dist/esm/index.js",
@@ -22,6 +22,10 @@
       "import": "./dist/esm/experiments/index.js",
       "require": "./dist/src/experiments/index.js"
     },
+    "./datasets": {
+      "import": "./dist/esm/datasets/index.js",
+      "require": "./dist/src/datasets/index.js"
+    },
     "./utils/*": {
       "import": "./dist/esm/utils/*.js",
       "require": "./dist/src/utils/*.js"
@@ -52,6 +56,14 @@
     "vitest": "^2.1.9"
   },
   "dependencies": {
+    "@arizeai/openinference-semantic-conventions": "^1.1.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^1.25.1",
+    "@opentelemetry/instrumentation": "^0.57.2",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.57.2",
+    "@opentelemetry/resources": "^2.0.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.1",
+    "@opentelemetry/sdk-trace-node": "^1.30.1",
     "async": "^3.2.6",
     "openapi-fetch": "^0.12.5",
     "tiny-invariant": "^1.3.3",

package/src/client.ts

@@ -79,7 +79,10 @@ export const createClient = (
   } = {}
 ) => {
   const mergedOptions = getMergedOptions(config);
-  return createOpenApiClient<pathsV1>(mergedOptions);
+  return {
+    ...createOpenApiClient<pathsV1>(mergedOptions),
+    config: mergedOptions,
+  };
 };
 
 /**

package/src/datasets/appendDatasetExamples.ts

@@ -0,0 +1,55 @@
+import { createClient } from "../client";
+import { ClientFn } from "../types/core";
+import { Example, DatasetSelector } from "../types/datasets";
+import invariant from "tiny-invariant";
+
+export type AppendDatasetExamplesParams = ClientFn & {
+  /**
+   * The dataset to append examples to
+   */
+  dataset: DatasetSelector;
+  /**
+   * The examples to append to the dataset
+   */
+  examples: Example[];
+};
+
+export type AppendDatasetExamplesResponse = {
+  datasetId: string;
+  // TODO: respond with the versionId
+  // versionId: string;
+};
+
+/**
+ * Append examples to an existing dataset
+ * @experimental this interface may change in the future
+ */
+export async function appendDatasetExamples({
+  client: _client,
+  dataset,
+  examples,
+}: AppendDatasetExamplesParams): Promise<AppendDatasetExamplesResponse> {
+  const client = _client || createClient();
+  const inputs = examples.map((example) => example.input);
+  const outputs = examples.map((example) => example.output ?? {}); // Treat null as an empty object
+  const metadata = examples.map((example) => example.metadata);
+  const appendResponse = await client.POST("/v1/datasets/upload", {
+    params: {
+      query: {
+        sync: true,
+      },
+    },
+    body: {
+      name: dataset.datasetId,
+      action: "append",
+      inputs,
+      outputs,
+      metadata,
+    },
+  });
+  invariant(appendResponse.data?.data, "Failed to append dataset examples");
+  const datasetId = appendResponse.data.data.dataset_id;
+  return {
+    datasetId,
+  };
+}

package/src/datasets/createDataset.ts

@@ -0,0 +1,60 @@
+import { createClient } from "../client";
+import { ClientFn } from "../types/core";
+import { Example } from "../types/datasets";
+import invariant from "tiny-invariant";
+
+export type CreateDatasetParams = ClientFn & {
+  /**
+   * The name of the dataset
+   */
+  name: string;
+  /**
+   * The description of the dataset
+   */
+  description: string;
+  /**
+   * The examples to create in the dataset
+   */
+  examples: Example[];
+};
+
+export type CreateDatasetResponse = {
+  datasetId: string;
+};
+
+/**
+ * Create a new dataset
+ * @experimental this interface may change in the future
+ */
+export async function createDataset({
+  client: _client,
+  name,
+  description,
+  examples,
+}: CreateDatasetParams): Promise<CreateDatasetResponse> {
+  const client = _client || createClient();
+  const inputs = examples.map((example) => example.input);
+  const outputs = examples.map((example) => example.output ?? {}); // Treat null as an empty object
+  const metadata = examples.map((example) => example.metadata);
+  const createDatasetResponse = await client.POST("/v1/datasets/upload", {
+    params: {
+      query: {
+        // TODO: parameterize this
+        sync: true,
+      },
+    },
+    body: {
+      name,
+      description,
+      action: "create",
+      inputs,
+      outputs,
+      metadata,
+    },
+  });
+  invariant(createDatasetResponse.data?.data, "Failed to create dataset");
+  const datasetId = createDatasetResponse.data.data.dataset_id;
+  return {
+    datasetId,
+  };
+}

package/src/datasets/getDataset.ts

@@ -0,0 +1,27 @@
+import { createClient } from "../client";
+import { ClientFn } from "../types/core";
+import { DatasetSelector, Dataset } from "../types/datasets";
+import { getDatasetExamples } from "./getDatasetExamples";
+import { getDatasetInfo } from "./getDatasetInfo";
+
+export type GetDatasetParams = ClientFn & {
+  dataset: DatasetSelector;
+};
+
+/**
+ * Get dataset info and the examples from the latest version of the dataset
+ */
+export async function getDataset({
+  client: _client,
+  dataset,
+}: GetDatasetParams): Promise<Dataset> {
+  const client = _client || createClient();
+  const [datasetInfo, datasetExamples] = await Promise.all([
+    getDatasetInfo({ client, dataset }),
+    getDatasetExamples({ client, dataset }),
+  ]);
+  return {
+    ...datasetInfo,
+    ...datasetExamples,
+  };
+}

package/src/datasets/getDatasetExamples.ts

@@ -0,0 +1,34 @@
+import invariant from "tiny-invariant";
+import { createClient } from "../client";
+import { ClientFn } from "../types/core";
+import { DatasetSelector, DatasetExamples } from "../types/datasets";
+
+export type GetDatasetExamplesParams = ClientFn & {
+  dataset: DatasetSelector;
+};
+
+/**
+ * Get the latest examples from a dataset
+ */
+export async function getDatasetExamples({
+  client: _client,
+  dataset,
+}: GetDatasetExamplesParams): Promise<DatasetExamples> {
+  const client = _client || createClient();
+  const response = await client.GET("/v1/datasets/{id}/examples", {
+    params: {
+      path: {
+        id: dataset.datasetId,
+      },
+    },
+  });
+  invariant(response.data?.data, "Failed to get dataset examples");
+  const examplesData = response.data.data;
+  return {
+    versionId: examplesData.version_id,
+    examples: examplesData.examples.map((example) => ({
+      ...example,
+      updatedAt: new Date(example.updated_at),
+    })),
+  };
+}

package/src/datasets/getDatasetInfo.ts

@@ -0,0 +1,34 @@
+import invariant from "tiny-invariant";
+import { createClient } from "../client";
+import { ClientFn } from "../types/core";
+import { DatasetSelector, DatasetInfo } from "../types/datasets";
+
+export type GetDatasetInfoParams = ClientFn & {
+  dataset: DatasetSelector;
+};
+
+/**
+ * Get an overview of the information in a dataset
+ * Note: this does not include the examples contained in the dataset
+ */
+export async function getDatasetInfo({
+  client: _client,
+  dataset,
+}: GetDatasetInfoParams): Promise<DatasetInfo> {
+  const client = _client || createClient();
+  const datasetResponse = await client.GET("/v1/datasets/{id}", {
+    params: {
+      path: {
+        id: dataset.datasetId,
+      },
+    },
+  });
+  invariant(datasetResponse.data?.data, "Failed to get dataset info");
+  const datasetInfo = datasetResponse.data.data;
+  return {
+    id: datasetInfo.id,
+    name: datasetInfo.name,
+    description: datasetInfo.description || undefined,
+    metadata: datasetInfo.metadata,
+  };
+}

package/src/datasets/index.ts

@@ -0,0 +1,6 @@
+export * from "./createDataset";
+export * from "./getDataset";
+export * from "./getDatasetExamples";
+export * from "./appendDatasetExamples";
+export * from "./getDatasetExamples";
+export * from "./getDatasetInfo";

package/src/datasets/listDatasets.ts

@@ -0,0 +1,37 @@
+import { createClient } from "../client";
+import { DatasetInfo } from "../types/datasets";
+import { ClientFn } from "../types/core";
+import invariant from "tiny-invariant";
+
+export type ListDatasetsParams = ClientFn;
+
+type FullDatasetInfo = DatasetInfo & {
+  startDate: Date;
+  endDate: Date;
+};
+
+/**
+ * List the information about all datasets available to the client.
+ *
+ * @example
+ * ```ts
+ * import { listDatasets } from "@arizeai/phoenix-client/datasets";
+ *
+ * const datasets = await listDatasets({});
+ * console.log(datasets);
+ * ```
+ *
+ * @throws {Error} If the datasets cannot be listed or the response is invalid.
+ */
+export async function listDatasets({
+  client: _client,
+}: ListDatasetsParams): Promise<FullDatasetInfo[]> {
+  const client = _client || createClient();
+  const response = await client.GET("/v1/datasets");
+  invariant(response.data?.data, "Failed to list datasets");
+  return response.data.data.map((dataset) => ({
+    ...dataset,
+    startDate: new Date(dataset.created_at),
+    endDate: new Date(dataset.updated_at),
+  }));
+}

package/src/experiments/getExperiment.ts

@@ -0,0 +1,40 @@
+import { createClient } from "../client";
+import { ClientFn } from "../types/core";
+import { ExperimentRunsMap, RanExperiment } from "../types/experiments";
+import { getExperimentInfo } from "./getExperimentInfo";
+import { getExperimentRuns } from "./getExperimentRuns";
+
+export type GetExperimentResultParams = ClientFn & {
+  /**
+   * The experiment ID.
+   */
+  experimentId: string;
+};
+
+/**
+ * A function that gets the result of a experiment.
+ * Fetches the experiment data as well as the runs.
+ */
+export async function getExperiment({
+  client: _client,
+  experimentId,
+}: GetExperimentResultParams): Promise<RanExperiment> {
+  const client = _client || createClient();
+  const [experiment, experimentRuns] = await Promise.all([
+    getExperimentInfo({ client, experimentId }),
+    getExperimentRuns({ client, experimentId }),
+  ]);
+  const experimentRunsMap: ExperimentRunsMap = {
+    runs: experimentRuns.runs.reduce(
+      (acc, run) => {
+        acc[run.id] = run;
+        return acc;
+      },
+      {} as ExperimentRunsMap["runs"]
+    ),
+  };
+  return {
+    ...experiment,
+    ...experimentRunsMap,
+  };
+}

package/src/experiments/getExperimentInfo.ts

@@ -0,0 +1,39 @@
+import invariant from "tiny-invariant";
+import { createClient } from "../client";
+import { ClientFn } from "../types/core";
+import { type ExperimentInfo } from "../types/experiments";
+
+export type GetExperimentParams = ClientFn & {
+  /**
+   * The experiment ID
+   */
+  experimentId: string;
+};
+
+/**
+ * Returns an object containing the high-level info about an experiment
+ */
+export async function getExperimentInfo({
+  client: _client,
+  experimentId: experiment_id,
+}: GetExperimentParams): Promise<ExperimentInfo> {
+  const client = _client || createClient();
+  const { data: { data: experimentData } = {} } = await client.GET(
+    "/v1/experiments/{experiment_id}",
+    {
+      params: {
+        path: {
+          experiment_id,
+        },
+      },
+    }
+  );
+  invariant(experimentData, "Failed to get experiment");
+  return {
+    id: experimentData.id,
+    datasetId: experimentData.dataset_id,
+    datasetVersionId: experimentData.dataset_version_id,
+    projectName: experimentData.project_name || "", // This will never happen
+    metadata: experimentData.metadata,
+  };
+}

package/src/experiments/getExperimentRuns.ts

@@ -0,0 +1,45 @@
+import { createClient } from "../client";
+import invariant from "tiny-invariant";
+import { ClientFn } from "../types/core";
+import { ExperimentRun } from "../types/experiments";
+
+export type GetExperimentRunsParams = ClientFn & {
+  /**
+   * The experiment ID.
+   */
+  experimentId: string;
+};
+
+/**
+ * A function that gets the runs (e.g. the results) of a experiment
+ */
+export async function getExperimentRuns({
+  client: _client,
+  experimentId,
+}: GetExperimentRunsParams): Promise<{ runs: ExperimentRun[] }> {
+  const client = _client || createClient();
+  const getRunsPromise = client.GET("/v1/experiments/{experiment_id}/runs", {
+    params: {
+      path: {
+        experiment_id: experimentId,
+      },
+    },
+  });
+  const [experimentRunResponse] = await Promise.all([getRunsPromise]);
+  const { data: { data: experimentRunsData } = {} } = experimentRunResponse;
+  invariant(experimentRunsData, "Failed to retrieve experiment runs");
+  return {
+    runs: experimentRunsData.map((run) => {
+      return {
+        id: run.id,
+        traceId: run.trace_id || null,
+        experimentId: run.experiment_id,
+        datasetExampleId: run.dataset_example_id,
+        startTime: new Date(run.start_time),
+        endTime: new Date(run.end_time),
+        output: run.output as ExperimentRun["output"],
+        error: run.error || null,
+      };
+    }),
+  };
+}

package/src/experiments/index.ts

@@ -1 +1,4 @@
+export * from "./getExperimentInfo";
+export * from "./getExperiment";
+export * from "./getExperimentRuns";
 export * from "./runExperiment";

package/src/experiments/instrumention.ts

@@ -0,0 +1,52 @@
+import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { SEMRESATTRS_PROJECT_NAME } from "@arizeai/openinference-semantic-conventions";
+import { HeadersOptions } from "openapi-fetch";
+
+/**
+ * Creates a provider that exports traces to Phoenix.
+ */
+export function createProvider({
+  projectName,
+  baseUrl,
+  headers,
+}: {
+  projectName: string;
+  headers: HeadersOptions;
+  /**
+   * The base URL of the Phoenix. Doesn't include the /v1/traces path.
+   */
+  baseUrl: string;
+}) {
+  diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR);
+
+  const provider = new NodeTracerProvider({
+    resource: resourceFromAttributes({
+      [SEMRESATTRS_PROJECT_NAME]: projectName,
+    }),
+    spanProcessors: [
+      new SimpleSpanProcessor(
+        new OTLPTraceExporter({
+          url: `${baseUrl}/v1/traces`,
+          headers: Array.isArray(headers)
+            ? Object.fromEntries(headers)
+            : headers,
+        })
+      ),
+    ],
+  });
+
+  return provider;
+}
+
+/**
+ * For dry runs we create a provider that doesn't export traces.
+ */
+export function createNoOpProvider() {
+  const provider = new NodeTracerProvider({});
+
+  return provider;
+}