@arizeai/phoenix-client 7.2.0 → 7.3.0

package/docs/ci-evals-jest.mdx

@@ -23,7 +23,7 @@ module.exports = {
 - `testMatch` keeps eval suites separate from regular tests.
 - `reporters` keeps Jest's default reporter and adds the Phoenix
   summary block at the end of the run.
-- `setupFiles: ["dotenv/config"]` loads `PHOENIX_HOST`, `PHOENIX_API_KEY`,
+- `setupFiles: ["dotenv/config"]` loads `PHOENIX_ENDPOINT`, `PHOENIX_API_KEY`,
   and other env vars from `.env`.
 - `testTimeout` is bumped because LLM calls can be slow.
 

package/docs/ci-evals-vitest.mdx

@@ -28,7 +28,7 @@ export default defineConfig({
   `*.eval.ts` convention.
 - `reporters` keeps Vitest's default diagnostics and enables the Phoenix
   summary block.
-- `setupFiles: ["dotenv/config"]` loads `PHOENIX_HOST`, `PHOENIX_API_KEY`,
+- `setupFiles: ["dotenv/config"]` loads `PHOENIX_ENDPOINT`, `PHOENIX_API_KEY`,
   and any other env vars from `.env`.
 - `testTimeout` is bumped because LLM calls can be slow.
 

package/docs/ci-evals.mdx

@@ -94,7 +94,7 @@ standard Phoenix env vars.
 
 | Variable | Purpose |
 | --- | --- |
-| `PHOENIX_HOST` | Phoenix base URL |
+| `PHOENIX_ENDPOINT` | Phoenix base URL |
 | `PHOENIX_API_KEY` | Bearer token for Phoenix |
 | `PHOENIX_CLIENT_HEADERS` | Optional JSON headers forwarded to the Phoenix client and tracer |
 | `PHOENIX_TEST_TRACKING=false` | Disable sync to Phoenix for the current run (tracking is on by default) |

package/docs/overview.mdx

@@ -50,18 +50,18 @@ That gives the agent version-matched docs plus the exact implementation and gene
 
 ## Configuration
 
-`createClient()` resolves Phoenix client options in this order: library defaults, environment variables, then explicit options. In most applications, the normal setup is to set `PHOENIX_HOST` and `PHOENIX_API_KEY` in the environment and call `createClient()` with no overrides.
+`createClient()` resolves Phoenix client options in this order: library defaults, environment variables, then explicit options. In most applications, the normal setup is to set `PHOENIX_ENDPOINT` and `PHOENIX_API_KEY` in the environment and call `createClient()` with no overrides.
 
 ### Recommended Setup
 
 Use the environment-driven path unless you have a specific reason to override client options in code.
 
 ```bash
-export PHOENIX_HOST=http://localhost:6006
+export PHOENIX_ENDPOINT=http://localhost:6006
 export PHOENIX_API_KEY=<your-api-key>
 ```
 
-For a remote deployment, `PHOENIX_HOST` is that instance's base URL, e.g. `https://your-phoenix.example.com`.
+For a remote deployment, `PHOENIX_ENDPOINT` is that instance's base URL, e.g. `https://your-phoenix.example.com`.
 
 ```ts
 import { createClient } from "@arizeai/phoenix-client";
@@ -103,7 +103,7 @@ These are the Phoenix-specific options this package resolves before creating the
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `baseUrl` | `string` | Base Phoenix URL. Defaults to `http://localhost:6006`, or `PHOENIX_HOST` when that environment variable is set. |
+| `baseUrl` | `string` | Base Phoenix URL. Defaults to `http://localhost:6006`, or `PHOENIX_ENDPOINT` when that environment variable is set. |
 | `headers` | `ClientOptions["headers"]` | Headers sent on every request. `PHOENIX_API_KEY` populates `Authorization` automatically. Explicit `headers` replace environment-derived headers. |
 
 ### Header Override Rule
@@ -124,7 +124,7 @@ const client = createClient({
 
 | Variable | Maps to | Description |
 |--------|---------|-------------|
-| `PHOENIX_HOST` | `options.baseUrl` | Base Phoenix URL, for example `http://localhost:6006`. |
+| `PHOENIX_ENDPOINT` | `options.baseUrl` | Base Phoenix URL, for example `http://localhost:6006`. |
 | `PHOENIX_API_KEY` | `options.headers.Authorization` | Bearer token for authenticated environments. |
 | `PHOENIX_CLIENT_HEADERS` | `options.headers` | Optional JSON-encoded object of additional headers to send on every request. Most setups do not need this. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -104,8 +104,8 @@
     "openapi-fetch": "^0.17.0",
     "tiny-invariant": "^1.3.3",
     "zod": "^4.4.3",
-    "@arizeai/phoenix-otel": "2.1.0",
-    "@arizeai/phoenix-config": "0.4.0"
+    "@arizeai/phoenix-config": "0.5.0",
+    "@arizeai/phoenix-otel": "2.2.0"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^4.0.27",
@@ -122,8 +122,8 @@
     "openapi-typescript": "^7.13.0",
     "tsx": "^4.23.1",
     "vitest": "^4.1.10",
-    "@arizeai/phoenix-evals": "2.2.0",
-    "@arizeai/phoenix-testing": "0.0.0"
+    "@arizeai/phoenix-testing": "0.0.0",
+    "@arizeai/phoenix-evals": "2.2.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": "^0.35.0",

package/src/client.ts

@@ -9,6 +9,7 @@ import type {
   paths as oapiPathsV1,
 } from "./__generated__/api/v1.d.ts";
 import {
+  type BaseUrlSource,
   defaultGetEnvironmentOptions,
   makeDefaultClientOptions,
 } from "./config";
@@ -36,6 +37,14 @@ export type Types = {
   };
 };
 
+/**
+ * The client's resolved options, tagged with where the base URL came from so
+ * consumers can tell deliberate configuration from an ambient environment.
+ */
+export type PhoenixClientOptions = ClientOptions & {
+  baseUrlSource: BaseUrlSource;
+};
+
 /**
  * Merge all configuration options according to priority:
  * defaults < environment < explicit options
@@ -51,13 +60,20 @@ export const getMergedOptions = ({
 }: {
   options?: Partial<ClientOptions>;
   getEnvironmentOptions?: () => Partial<ClientOptions>;
-} = {}): ClientOptions => {
+} = {}): PhoenixClientOptions => {
   const defaultOptions = makeDefaultClientOptions();
   const environmentOptions = getEnvironmentOptions();
+  const baseUrlSource: BaseUrlSource =
+    options.baseUrl !== undefined
+      ? "explicit"
+      : environmentOptions.baseUrl !== undefined
+        ? "environment"
+        : "default";
   return {
     ...defaultOptions,
     ...environmentOptions,
     ...options,
+    baseUrlSource,
   };
 };
 

package/src/config.ts

@@ -1,25 +1,24 @@
-import type { EnvironmentConfig } from "@arizeai/phoenix-config";
 import {
   DEFAULT_PHOENIX_BASE_URL,
-  getEnvironmentConfig,
+  getBaseUrlFromEnvironment,
+  getCredentialsFromEnvironment,
 } from "@arizeai/phoenix-config";
 import type { ClientOptions } from "openapi-fetch";
 
 /**
- * Convert a EnvironmentConfig object into a ClientOptions object.
+ * Convert resolved Phoenix credentials into a ClientOptions object.
  *
- * @param environment - The EnvironmentConfig object to convert.
+ * @param credentials - The API key and headers resolved from the environment.
  * @returns The converted ClientOptions object.
  */
-const phoenixEnvironmentToClientOptions = (
-  environment: EnvironmentConfig
+const phoenixCredentialsToClientOptions = (
+  credentials: ReturnType<typeof getCredentialsFromEnvironment>
 ): Partial<ClientOptions> => {
   const options: Partial<ClientOptions> = {
-    baseUrl: environment.PHOENIX_HOST,
     headers: {
-      ...(environment.PHOENIX_CLIENT_HEADERS ?? {}),
-      ...(environment.PHOENIX_API_KEY
-        ? { Authorization: `Bearer ${environment.PHOENIX_API_KEY}` }
+      ...(credentials.headers ?? {}),
+      ...(credentials.apiKey
+        ? { Authorization: `Bearer ${credentials.apiKey}` }
         : {}),
     },
   };
@@ -36,6 +35,17 @@ const phoenixEnvironmentToClientOptions = (
   );
 };
 
+/**
+ * Where a client's base URL came from: an explicit `baseUrl` option
+ * (`"explicit"`), a Phoenix environment variable (`"environment"`), or the
+ * built-in localhost default (`"default"`).
+ *
+ * Explicit configuration outranks the ambient environment, so this is what
+ * decides whether an environment variable may retarget the client's trace
+ * export.
+ */
+export type BaseUrlSource = "default" | "environment" | "explicit";
+
 /**
  * Get the environment options from the environment.
  *
@@ -46,7 +56,14 @@ export const defaultGetEnvironmentOptions = (): Partial<ClientOptions> => {
   if (typeof process !== "object" || typeof process.env !== "object") {
     return {};
   }
-  return phoenixEnvironmentToClientOptions(getEnvironmentConfig());
+  const options = phoenixCredentialsToClientOptions(
+    getCredentialsFromEnvironment()
+  );
+  // The base URL resolves as a tier group (PHOENIX_ENDPOINT first, inferring
+  // from the trace-export variables, then legacy PHOENIX_HOST) rather than
+  // variable by variable.
+  const baseUrl = getBaseUrlFromEnvironment();
+  return baseUrl !== undefined ? { ...options, baseUrl } : options;
 };
 
 /**

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/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,