@arizeai/phoenix-client 7.1.1 → 7.3.0

package/src/experiments/resumeEvaluation.ts

@@ -31,7 +31,11 @@ import { getExperimentInfo } from "./getExperimentInfo.js";
 import { getExperimentEvaluators } from "./helpers";
 import { getExampleGlobalId } from "./helpers/getExampleGlobalId";
 import { logEvalResumeSummary, PROGRESS_PREFIX } from "./logging";
-import { cleanupOwnedTracerProvider } from "./tracing";
+import {
+  cleanupOwnedTracerProvider,
+  getTraceExportUrl,
+  MISSING_BASE_URL_MESSAGE,
+} from "./tracing";
 
 /**
  * Error thrown when evaluation is aborted due to a failure in stopOnFirstError mode.
@@ -199,14 +203,15 @@ async function handleEvaluationFetchError(
  */
 function setupEvaluationTracer({
   projectName,
-  baseUrl,
+  traceExportUrl,
   headers,
   useBatchSpanProcessor,
   diagLogLevel,
   setGlobalTracerProvider,
 }: {
   projectName: string | null;
-  baseUrl: string;
+  /** Where spans are exported; omit to let `register()` read the environment. */
+  traceExportUrl?: string;
   headers?: Record<string, string>;
   useBatchSpanProcessor: boolean;
   diagLogLevel?: DiagLogLevel;
@@ -222,7 +227,7 @@ function setupEvaluationTracer({
 
   const provider = register({
     projectName,
-    url: baseUrl,
+    url: traceExportUrl,
     headers,
     batch: useBatchSpanProcessor,
     diagLogLevel,
@@ -323,14 +328,11 @@ export async function resumeEvaluation({
 
   // Initialize tracer (only if experiment has a project_name)
   const baseUrl = client.config.baseUrl;
-  invariant(
-    baseUrl,
-    "Phoenix base URL not found. Please set PHOENIX_HOST or set baseUrl on the client."
-  );
+  invariant(baseUrl, MISSING_BASE_URL_MESSAGE);
 
   const tracerSetup = setupEvaluationTracer({
     projectName: experiment.projectName,
-    baseUrl,
+    traceExportUrl: getTraceExportUrl(client.config),
     headers: client.config.headers
       ? toObjectHeaders(client.config.headers)
       : undefined,

package/src/experiments/resumeExperiment.ts

@@ -35,7 +35,11 @@ import {
   PROGRESS_PREFIX,
 } from "./logging";
 import { resumeEvaluation } from "./resumeEvaluation";
-import { cleanupOwnedTracerProvider } from "./tracing";
+import {
+  cleanupOwnedTracerProvider,
+  getTraceExportUrl,
+  MISSING_BASE_URL_MESSAGE,
+} from "./tracing";
 
 /**
  * Error thrown when task is aborted due to a failure in stopOnFirstError mode.
@@ -182,14 +186,15 @@ async function handleFetchError(
  */
 function setupTracer({
   projectName,
-  baseUrl,
+  traceExportUrl,
   headers,
   useBatchSpanProcessor,
   diagLogLevel,
   setGlobalTracerProvider,
 }: {
   projectName: string | null;
-  baseUrl: string;
+  /** Where spans are exported; omit to let `register()` read the environment. */
+  traceExportUrl?: string;
   headers?: Record<string, string>;
   useBatchSpanProcessor: boolean;
   diagLogLevel?: DiagLogLevel;
@@ -205,7 +210,7 @@ function setupTracer({
 
   const provider = register({
     projectName,
-    url: baseUrl,
+    url: traceExportUrl,
     headers,
     batch: useBatchSpanProcessor,
     diagLogLevel,
@@ -307,15 +312,12 @@ export async function resumeExperiment({
 
   // Get base URL for tracing and URL generation
   const baseUrl = client.config.baseUrl;
-  invariant(
-    baseUrl,
-    "Phoenix base URL not found. Please set PHOENIX_HOST or set baseUrl on the client."
-  );
+  invariant(baseUrl, MISSING_BASE_URL_MESSAGE);
 
   // Initialize tracer (only if experiment has a project_name)
   const tracerSetup = setupTracer({
     projectName: experiment.projectName,
-    baseUrl,
+    traceExportUrl: getTraceExportUrl(client.config),
     headers: client.config.headers
       ? toObjectHeaders(client.config.headers)
       : undefined,

package/src/experiments/runExperiment.ts

@@ -54,7 +54,11 @@ import {
   logTaskSummary,
   PROGRESS_PREFIX,
 } from "./logging";
-import { cleanupOwnedTracerProvider } from "./tracing";
+import {
+  cleanupOwnedTracerProvider,
+  getTraceExportUrl,
+  MISSING_BASE_URL_MESSAGE,
+} from "./tracing";
 
 /**
  * Validate that a repetition is valid
@@ -270,14 +274,11 @@ export async function runExperiment({
     };
     // Initialize the tracer, now that we have a project name
     const baseUrl = client.config.baseUrl;
-    invariant(
-      baseUrl,
-      "Phoenix base URL not found. Please set PHOENIX_HOST or set baseUrl on the client."
-    );
+    invariant(baseUrl, MISSING_BASE_URL_MESSAGE);
 
     taskProvider = register({
       projectName,
-      url: baseUrl,
+      url: getTraceExportUrl(client.config),
       headers: client.config.headers
         ? toObjectHeaders(client.config.headers)
         : undefined,
@@ -621,10 +622,7 @@ export async function evaluateExperiment({
   const isDryRun = typeof dryRun === "number" || dryRun === true;
   const client = _client ?? createClient();
   const baseUrl = client.config.baseUrl;
-  invariant(
-    baseUrl,
-    "Phoenix base URL not found. Please set PHOENIX_HOST or set baseUrl on the client."
-  );
+  invariant(baseUrl, MISSING_BASE_URL_MESSAGE);
   let provider: NodeTracerProvider;
   let globalRegistration: GlobalTracerProviderRegistration | null = null;
   const ownsProvider = !paramsTracerProvider;
@@ -635,7 +633,7 @@ export async function evaluateExperiment({
   } else if (!isDryRun) {
     provider = register({
       projectName: "evaluators",
-      url: baseUrl,
+      url: getTraceExportUrl(client.config),
       headers: client.config.headers
         ? toObjectHeaders(client.config.headers)
         : undefined,

package/src/experiments/tracing.ts

@@ -3,6 +3,41 @@ import type {
   NodeTracerProvider,
 } from "@arizeai/phoenix-otel";
 
+import type { BaseUrlSource } from "../config";
+
+/**
+ * Message for the invariant shared by every experiment entry point: a base URL
+ * must be resolvable before a tracer can be registered.
+ */
+export const MISSING_BASE_URL_MESSAGE =
+  "Phoenix base URL not found. Please set PHOENIX_ENDPOINT (or PHOENIX_COLLECTOR_ENDPOINT) or set baseUrl on the client.";
+
+/**
+ * Resolves the URL experiment spans are exported to, as the `url` argument to
+ * `register()`.
+ *
+ * Explicit code-level configuration outranks the ambient environment: a client
+ * created with an explicit `baseUrl` exports its spans to that server, so a
+ * `PHOENIX_COLLECTOR_ENDPOINT` left in the shell cannot silently retarget it.
+ * When the base URL itself came from the environment, so does trace export:
+ * returning `undefined` hands resolution to `register()`, which reads the
+ * trace-export chain (`PHOENIX_COLLECTOR_ENDPOINT`, the OTel-standard
+ * variables, then `PHOENIX_ENDPOINT`) exactly as a standalone `register()`
+ * call would.
+ *
+ * A base URL of unknown provenance — a hand-built client rather than one from
+ * `createClient()` — counts as explicit, since only deliberate configuration
+ * puts a URL there.
+ */
+export function getTraceExportUrl(config: {
+  baseUrl?: string;
+  baseUrlSource?: BaseUrlSource;
+}): string | undefined {
+  return (config.baseUrlSource ?? "explicit") === "explicit"
+    ? config.baseUrl
+    : undefined;
+}
+
 /**
  * Flushes and shuts down a tracer provider that this package created, then
  * detaches any global OTEL registration it owns so another provider can be mounted.

package/src/projects/getProjects.ts

@@ -0,0 +1,69 @@
+import invariant from "tiny-invariant";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+import type { Project } from "../types/projects";
+
+export interface GetProjectsParams extends ClientFn {
+  /**
+   * Return only projects whose name contains this substring
+   * (case-insensitive). The match is performed server-side.
+   *
+   * @requires Phoenix server >= 17.16.0
+   */
+  nameContains?: string;
+}
+
+type ProjectsResponse = components["schemas"]["GetProjectsResponseBody"];
+
+const DEFAULT_PAGE_SIZE = 100;
+
+/**
+ * List projects with automatic pagination handling.
+ *
+ * @example
+ * ```ts
+ * import { getProjects } from "@arizeai/phoenix-client/projects";
+ *
+ * // Every project
+ * const projects = await getProjects();
+ *
+ * // Only projects whose name contains "agent" (requires Phoenix server >= 17.16.0)
+ * const agentProjects = await getProjects({ nameContains: "agent" });
+ *
+ * for (const project of agentProjects) {
+ *   console.log(`Project: ${project.name} (${project.id})`);
+ * }
+ * ```
+ */
+export async function getProjects(
+  params: GetProjectsParams = {}
+): Promise<Project[]> {
+  const client = params.client || createClient();
+  const { nameContains } = params;
+
+  const projects: Project[] = [];
+  let cursor: string | null | undefined = null;
+
+  do {
+    const response: { data?: ProjectsResponse; error?: unknown } =
+      await client.GET("/v1/projects", {
+        params: {
+          query: {
+            cursor,
+            limit: DEFAULT_PAGE_SIZE,
+            name_contains: nameContains,
+          },
+        },
+      });
+
+    if (response.error) throw response.error;
+    invariant(response.data?.data, "Failed to list projects");
+
+    cursor = response.data.next_cursor ?? null;
+    projects.push(...response.data.data);
+  } while (cursor != null);
+
+  return projects;
+}

package/src/projects/index.ts

@@ -0,0 +1 @@
+export * from "./getProjects";

package/src/prompts/createPrompt.ts

@@ -301,6 +301,6 @@ export function promptVersion(params: PromptVersionInput): PromptVersionData {
         },
       };
     default:
-      assertUnreachable(model_provider);
+      return assertUnreachable(model_provider);
   }
 }

package/src/prompts/sdks/toSDK.ts

@@ -42,7 +42,7 @@ const getTargetSDK = <SDK extends SupportedSDK>(sdk: SDK) => {
     case "ai":
       return PROVIDER_TO_SDK.ai;
     default:
-      assertUnreachable(sdk);
+      return assertUnreachable(sdk);
   }
 };
 

package/src/schemas/llm/converters.ts

@@ -294,7 +294,7 @@ export const fromOpenAIToolCall = <
         toolCall
       ) as ReturnType;
     default:
-      assertUnreachable(targetProvider);
+      return assertUnreachable(targetProvider);
   }
 };
 
@@ -328,7 +328,7 @@ export const toOpenAIToolChoice = (
         validatedToolChoice
       );
     default:
-      assertUnreachable(provider);
+      return assertUnreachable(provider);
   }
 };
 
@@ -373,7 +373,7 @@ export const fromOpenAIToolChoice = <
         toolChoice
       ) as ReturnType;
     default:
-      assertUnreachable(targetProvider);
+      return assertUnreachable(targetProvider);
   }
 };
 
@@ -406,7 +406,7 @@ export const toOpenAIToolDefinition = (
     case null:
       return null;
     default:
-      assertUnreachable(provider);
+      return assertUnreachable(provider);
   }
 };
 
@@ -447,7 +447,7 @@ export const fromOpenAIToolDefinition = <
         toolDefinition
       ) as ReturnType;
     default:
-      assertUnreachable(targetProvider);
+      return assertUnreachable(targetProvider);
   }
 };
 

package/src/schemas/llm/openai/converters.ts

@@ -324,7 +324,7 @@ export const openAIMessageToVercelAI = openAIMessageSchema.transform(
           content: [],
         };
       default:
-        assertUnreachable(role);
+        return assertUnreachable(role);
     }
   }
 );
@@ -354,7 +354,7 @@ export const openAIToolChoiceToAnthropic = openAIToolChoiceSchema.transform(
       case "required":
         return { type: "any" };
       default:
-        assertUnreachable(openAI);
+        return assertUnreachable(openAI);
     }
   }
 );
@@ -372,7 +372,7 @@ export const openAIToolChoiceToVercelAI = openAIToolChoiceSchema.transform(
       case "required":
         return "required";
       default:
-        assertUnreachable(openAI);
+        return assertUnreachable(openAI);
     }
   }
 );

package/src/schemas/llm/phoenixPrompt/converters.ts

@@ -172,6 +172,8 @@ export const phoenixToolChoiceToOpenAI = phoenixToolChoiceSchema.transform(
         return "required";
       case "specific_function":
         return { type: "function", function: { name: phoenix.function_name } };
+      default:
+        return assertUnreachable(phoenix);
     }
   }
 );

package/src/testing/phoenix-test-tracking.ts

@@ -16,7 +16,10 @@ import {
 import type { Span } from "@opentelemetry/api";
 
 import { createDataset } from "../datasets";
-import { cleanupOwnedTracerProvider } from "../experiments/tracing";
+import {
+  cleanupOwnedTracerProvider,
+  getTraceExportUrl,
+} from "../experiments/tracing";
 import { createClient, type PhoenixClient } from "../index";
 import { ensureString } from "../utils/ensureString";
 import { toObjectHeaders } from "../utils/toObjectHeaders";
@@ -163,9 +166,9 @@ interface TaskSpanLifecycle {
 const taskSpansByRun = new WeakMap<RunState, TaskSpanLifecycle>();
 
 /**
- * Warn once when `PHOENIX_HOST` is plain `http:` while an `Authorization`
- * header is being forwarded to the OTLP exporter — that combination
- * exfiltrates the bearer token in cleartext.
+ * Warn once when the resolved base URL is plain `http:` while an
+ * `Authorization` header is being forwarded to the OTLP exporter — that
+ * combination exfiltrates the bearer token in cleartext.
  */
 let warnedAboutHttpScheme = false;
 function maybeWarnHttpScheme(
@@ -191,9 +194,9 @@ function maybeWarnHttpScheme(
   warnedAboutHttpScheme = true;
   // eslint-disable-next-line no-console
   console.warn(
-    `[@arizeai/phoenix-client] PHOENIX_HOST="${baseUrl}" uses http:// with ` +
-      `an Authorization header set; the bearer token will travel in cleartext. ` +
-      `Use https:// for non-localhost Phoenix endpoints.`
+    `[@arizeai/phoenix-client] The Phoenix base URL "${baseUrl}" uses http:// ` +
+      `with an Authorization header set; the bearer token will travel in ` +
+      `cleartext. Use https:// for non-localhost Phoenix endpoints.`
   );
 }
 
@@ -349,7 +352,7 @@ export async function initializeSuite(suite: SuiteState): Promise<void> {
   if (!baseUrl) {
     suite.trackingDisabled = true;
     suite.setupError = new Error(
-      "Phoenix base URL not found. Set PHOENIX_HOST or pass baseUrl on the client."
+      "Phoenix base URL not found. Set PHOENIX_ENDPOINT (or PHOENIX_COLLECTOR_ENDPOINT) or pass baseUrl on the client."
     );
     suite.tracer = createNoOpProvider().getTracer("no-op");
     suite.evaluatorTracer = suite.tracer;
@@ -362,7 +365,7 @@ export async function initializeSuite(suite: SuiteState): Promise<void> {
   try {
     provider = register({
       projectName: suite.projectName,
-      url: baseUrl,
+      url: getTraceExportUrl(client.config),
       headers: client.config.headers
         ? toObjectHeaders(client.config.headers)
         : undefined,

package/src/types/projects.ts

@@ -1,3 +1,10 @@
+import type { components } from "../__generated__/api/v1";
+
+/**
+ * A project as returned by the Phoenix REST API.
+ */
+export type Project = components["schemas"]["Project"];
+
 /**
  * Identifies a project. Accepts any of:
  * - `project` — a project ID or name (the server accepts either)

package/src/utils/serverVersionUtils.ts

@@ -20,6 +20,7 @@
 
 import type { PhoenixClient } from "../client";
 import type { CapabilityRequirement } from "../types/serverRequirements";
+import { assertUnreachable } from "./assertUnreachable";
 import { formatVersion, satisfiesMinVersion } from "./semverUtils";
 
 // ---------------------------------------------------------------------------
@@ -37,6 +38,8 @@ export function capabilityLabel(req: CapabilityRequirement): string {
       return `The ${req.method} ${req.path} route`;
     case "parameter":
       return `The '${req.parameterName}' ${req.parameterLocation} parameter on ${req.route}`;
+    default:
+      return assertUnreachable(req);
   }
 }