@arizeai/phoenix-client 5.9.0 → 6.1.0

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

@@ -13,7 +13,7 @@ export const phoenixResponseFormatSchema =
       json_schema: z.object({
         name: z.string(),
         description: z.string().optional(),
-        schema: z.record(z.unknown()).optional(),
+        schema: z.record(z.string(), z.unknown()).optional(),
         strict: z.boolean().optional(),
       }),
     })

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

@@ -12,7 +12,7 @@ export const phoenixToolDefinitionSchema = schemaMatches<PromptTool>()(
     function: z.object({
       name: z.string(),
       description: z.string().optional(),
-      parameters: z.record(z.unknown()).optional(),
+      parameters: z.record(z.string(), z.unknown()).optional(),
       strict: z.boolean().optional(),
     }),
   })

package/src/schemas/llm/schemas.ts

@@ -61,11 +61,11 @@ export type LlmProviderToolCalls = z.infer<typeof llmProviderToolCallsSchema>;
 export const toolCallHeuristicSchema = z.object({
   id: z.string().optional(),
   name: z.string().optional(),
-  arguments: z.record(z.unknown()).optional(),
+  arguments: z.record(z.string(), z.unknown()).optional(),
   function: z
     .object({
       name: z.string().optional(),
-      arguments: z.record(z.unknown()).optional(),
+      arguments: z.record(z.string(), z.unknown()).optional(),
     })
     .optional(),
 });

package/src/schemas/llm/types.ts

@@ -1,4 +1,4 @@
-import type { ZodType, ZodTypeAny, ZodTypeDef } from "zod";
+import type { ZodType } from "zod";
 
 import type { PromptProviderSDKs, PromptToolChoice } from "../../types/prompts";
 import type { AnthropicMessagePart } from "./anthropic/messagePartSchemas";
@@ -33,35 +33,35 @@ export type LLMMessagePart =
   | VercelAIChatPart;
 
 export type SDKConverters<
-  MessageSchema extends ZodTypeAny = never,
-  MessagePartSchema extends ZodTypeAny = never,
-  ToolChoiceSchema extends ZodTypeAny = never,
-  ToolCallSchema extends ZodTypeAny = never,
-  ToolDefinitionSchema extends ZodTypeAny = never,
-  ResponseFormatSchema extends ZodTypeAny = never,
+  MessageSchema extends ZodType = never,
+  MessagePartSchema extends ZodType = never,
+  ToolChoiceSchema extends ZodType = never,
+  ToolCallSchema extends ZodType = never,
+  ToolDefinitionSchema extends ZodType = never,
+  ResponseFormatSchema extends ZodType = never,
 > = {
   messages: {
-    toOpenAI: ZodType<OpenAIMessage | null, ZodTypeDef, unknown>;
+    toOpenAI: ZodType<OpenAIMessage | null, unknown>;
     fromOpenAI: MessageSchema;
   };
   messageParts: {
-    toOpenAI: ZodType<OpenAIChatPart | null, ZodTypeDef, unknown>;
+    toOpenAI: ZodType<OpenAIChatPart | null, unknown>;
     fromOpenAI: MessagePartSchema;
   };
   toolChoices: {
-    toOpenAI: ZodType<OpenaiToolChoice | null, ZodTypeDef, unknown>;
+    toOpenAI: ZodType<OpenaiToolChoice | null, unknown>;
     fromOpenAI: ToolChoiceSchema;
   };
   toolCalls: {
-    toOpenAI: ZodType<OpenAIToolCall | null, ZodTypeDef, unknown>;
+    toOpenAI: ZodType<OpenAIToolCall | null, unknown>;
     fromOpenAI: ToolCallSchema;
   };
   toolDefinitions: {
-    toOpenAI: ZodType<OpenAIToolDefinition | null, ZodTypeDef, unknown>;
+    toOpenAI: ZodType<OpenAIToolDefinition | null, unknown>;
     fromOpenAI: ToolDefinitionSchema;
   };
   responseFormat?: {
-    toOpenAI: ZodType<OpenAIResponseFormat | null, ZodTypeDef, unknown>;
+    toOpenAI: ZodType<OpenAIResponseFormat | null, unknown>;
     fromOpenAI: ResponseFormatSchema;
   };
 };

package/src/schemas/llm/utils.ts

@@ -1,4 +1,4 @@
-import type { ZodTypeAny } from "zod";
+import type { ZodType } from "zod";
 
 import { isObject } from "../../utils/isObject";
 import { anthropicMessagePartSchema } from "./anthropic/messagePartSchemas";
@@ -30,12 +30,12 @@ import { vercelAIMessageSchema } from "./vercel/messageSchemas";
 import { vercelAIToolDefinitionSchema } from "./vercel/toolSchemas";
 
 export const makeSDKConverters = <
-  MessageSchema extends ZodTypeAny,
-  MessagePartSchema extends ZodTypeAny,
-  ToolChoiceSchema extends ZodTypeAny,
-  ToolCallSchema extends ZodTypeAny,
-  ToolDefinitionSchema extends ZodTypeAny,
-  ResponseFormatSchema extends ZodTypeAny,
+  MessageSchema extends ZodType,
+  MessagePartSchema extends ZodType,
+  ToolChoiceSchema extends ZodType,
+  ToolCallSchema extends ZodType,
+  ToolDefinitionSchema extends ZodType,
+  ResponseFormatSchema extends ZodType,
 >({
   messages,
   messageParts,

package/src/sessions/getSession.ts

@@ -0,0 +1,44 @@
+import invariant from "tiny-invariant";
+
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+import type { Session } from "../types/sessions";
+import { toSession } from "./sessionUtils";
+
+export type GetSessionParams = ClientFn & {
+  /**
+   * The session identifier: either a GlobalID or user-provided session_id string.
+   */
+  sessionId: string;
+};
+
+/**
+ * Fetch a single session by its GlobalID or user-provided session_id string.
+ *
+ * @example
+ * ```ts
+ * import { getSession } from "@arizeai/phoenix-client/sessions";
+ *
+ * const session = await getSession({ sessionId: "my-session-id" });
+ * console.log(session.traces.length);
+ * ```
+ */
+export async function getSession({
+  client: _client,
+  sessionId,
+}: GetSessionParams): Promise<Session> {
+  const client = _client || createClient();
+  const { data, error } = await client.GET(
+    "/v1/sessions/{session_identifier}",
+    {
+      params: {
+        path: {
+          session_identifier: sessionId,
+        },
+      },
+    }
+  );
+  if (error) throw error;
+  invariant(data?.data, "Failed to get session");
+  return toSession(data.data);
+}

package/src/sessions/index.ts

@@ -1,2 +1,4 @@
 export * from "./addSessionAnnotation";
+export * from "./getSession";
+export * from "./listSessions";
 export * from "./logSessionAnnotations";

package/src/sessions/listSessions.ts

@@ -0,0 +1,64 @@
+import invariant from "tiny-invariant";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
+import type { Session } from "../types/sessions";
+import { toSession } from "./sessionUtils";
+
+export type ListSessionsParams = ClientFn & ProjectIdentifier;
+
+type SessionsResponse = components["schemas"]["GetSessionsResponseBody"];
+
+const DEFAULT_PAGE_SIZE = 100;
+
+/**
+ * List all sessions for a project with automatic pagination handling.
+ *
+ * @example
+ * ```ts
+ * import { listSessions } from "@arizeai/phoenix-client/sessions";
+ *
+ * const sessions = await listSessions({
+ *   project: "my-project",
+ * });
+ *
+ * for (const session of sessions) {
+ *   console.log(`Session: ${session.sessionId}, Traces: ${session.traces.length}`);
+ * }
+ * ```
+ */
+export async function listSessions(
+  params: ListSessionsParams
+): Promise<Session[]> {
+  const client = params.client || createClient();
+  const projectIdentifier = resolveProjectIdentifier(params);
+
+  const sessions: Session[] = [];
+  let cursor: string | null | undefined = null;
+
+  do {
+    const response: { data?: SessionsResponse; error?: unknown } =
+      await client.GET("/v1/projects/{project_identifier}/sessions", {
+        params: {
+          path: {
+            project_identifier: projectIdentifier,
+          },
+          query: {
+            cursor,
+            limit: DEFAULT_PAGE_SIZE,
+          },
+        },
+      });
+
+    if (response.error) throw response.error;
+    invariant(response.data?.data, "Failed to list sessions");
+
+    cursor = response.data.next_cursor ?? null;
+    sessions.push(...response.data.data.map(toSession));
+  } while (cursor != null);
+
+  return sessions;
+}

package/src/sessions/sessionUtils.ts

@@ -0,0 +1,23 @@
+import type { components } from "../__generated__/api/v1";
+import type { Session } from "../types/sessions";
+
+type SessionData = components["schemas"]["SessionData"];
+
+/**
+ * Convert an API SessionData response to a user-facing Session object.
+ */
+export function toSession(data: SessionData): Session {
+  return {
+    id: data.id,
+    sessionId: data.session_id,
+    projectId: data.project_id,
+    startTime: data.start_time,
+    endTime: data.end_time,
+    traces: data.traces.map((trace) => ({
+      id: trace.id,
+      traceId: trace.trace_id,
+      startTime: trace.start_time,
+      endTime: trace.end_time,
+    })),
+  };
+}

package/src/spans/getSpanAnnotations.ts

@@ -1,14 +1,15 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
 import type { ClientFn } from "../types/core";
-import type { ProjectSelector } from "../types/projects";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
 
 /**
  * Parameters to get span annotations from a project using auto-generated types
  */
 export interface GetSpanAnnotationsParams extends ClientFn {
   /** The project to get span annotations from */
-  project: ProjectSelector;
+  project: ProjectIdentifier;
   /** One or more span IDs to fetch annotations for */
   spanIds: string[];
   /** Optional list of annotation names to include. If provided, only annotations with these names will be returned. 'note' annotations are excluded by default unless explicitly included in this list. */
@@ -89,8 +90,7 @@ export async function getSpanAnnotations({
   limit = 100,
 }: GetSpanAnnotationsParams): Promise<GetSpanAnnotationsResult> {
   const client = _client ?? createClient();
-  const projectIdentifier =
-    "projectId" in project ? project.projectId : project.projectName;
+  const projectIdentifier = resolveProjectIdentifier(project);
 
   const params: NonNullable<
     operations["listSpanAnnotationsBySpanIds"]["parameters"]["query"]

package/src/spans/getSpans.ts

@@ -1,14 +1,15 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
 import type { ClientFn } from "../types/core";
-import type { ProjectSelector } from "../types/projects";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
 
 /**
  * Parameters to get spans from a project using auto-generated types
  */
 export interface GetSpansParams extends ClientFn {
   /** The project to get spans from */
-  project: ProjectSelector;
+  project: ProjectIdentifier;
   /** Inclusive lower bound time. Must be a valid ISO 8601 string or Date object. */
   startTime?: Date | string | null;
   /** Exclusive upper bound time. Must be a valid ISO 8601 string or Date object. */
@@ -87,8 +88,7 @@ export async function getSpans({
   endTime,
 }: GetSpansParams): Promise<GetSpansResult> {
   const client = _client ?? createClient();
-  const projectIdentifier =
-    "projectId" in project ? project.projectId : project.projectName;
+  const projectIdentifier = resolveProjectIdentifier(project);
 
   const params: NonNullable<operations["getSpans"]["parameters"]["query"]> = {
     limit,

package/src/types/projects.ts

@@ -1,5 +1,22 @@
 /**
- * A project can be identified by its projectId or projectName
- * In the case of a projectName, the name must be url encodable
+ * Identifies a project. Accepts any of:
+ * - `project` — a project ID or name (the server accepts either)
+ * - `projectId` — an explicit project ID
+ * - `projectName` — an explicit project name
  */
-export type ProjectSelector = { projectId: string } | { projectName: string };
+export type ProjectIdentifier =
+  | { project: string }
+  | { projectId: string }
+  | { projectName: string };
+
+/**
+ * Resolves a {@link ProjectIdentifier} union to a plain string
+ * suitable for the REST `project_identifier` path parameter.
+ */
+export function resolveProjectIdentifier(
+  identifier: ProjectIdentifier
+): string {
+  if ("project" in identifier) return identifier.project;
+  if ("projectId" in identifier) return identifier.projectId;
+  return identifier.projectName;
+}

package/src/types/sessions.ts

@@ -0,0 +1,29 @@
+import type { Node } from "./core";
+
+/**
+ * A trace that belongs to a session.
+ */
+export interface SessionTrace extends Node {
+  /** The unique trace identifier (e.g. OpenTelemetry trace ID) */
+  traceId: string;
+  /** ISO 8601 timestamp of when the trace started */
+  startTime: string;
+  /** ISO 8601 timestamp of when the trace ended */
+  endTime: string;
+}
+
+/**
+ * A session representing a group of related traces (e.g. a multi-turn conversation).
+ */
+export interface Session extends Node {
+  /** The user-provided session identifier */
+  sessionId: string;
+  /** The ID of the project this session belongs to */
+  projectId: string;
+  /** ISO 8601 timestamp of when the first trace in the session started */
+  startTime: string;
+  /** ISO 8601 timestamp of when the last trace in the session ended */
+  endTime: string;
+  /** The traces that belong to this session */
+  traces: SessionTrace[];
+}

package/src/utils/schemaMatches.ts

@@ -15,7 +15,7 @@ export type AssertEqual<T, U> =
  */
 export const schemaMatches =
   <T>() =>
-  <S extends z.ZodType<T, z.ZodTypeDef, unknown>>(
+  <S extends z.ZodType<T, unknown>>(
     schema: AssertEqual<S["_output"], T> extends true
       ? S
       : S & {