@arizeai/phoenix-client 0.0.1 → 1.0.0

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

@@ -0,0 +1,178 @@
+import { assertUnreachable } from "../../../utils/assertUnreachable";
+import { OpenAIToolDefinition } from "../openai/toolSchemas";
+import { OpenAIMessage } from "../openai/messageSchemas";
+import { OpenAIToolCall } from "../openai/toolCallSchemas";
+import { OpenaiToolChoice } from "../openai/toolChoiceSchemas";
+import { phoenixMessageSchema } from "./messageSchemas";
+import {
+  ToolCallPart,
+  ToolResultPart,
+  asToolResultPart,
+  phoenixContentPartSchema,
+} from "./messagePartSchemas";
+import { phoenixToolCallSchema } from "./toolCallSchemas";
+import { safelyStringifyJSON } from "../../../utils/safelyStringifyJSON";
+import { OpenAIChatPartText } from "../openai/messagePartSchemas";
+import { phoenixResponseFormatSchema } from "./responseFormatSchema";
+import { OpenAIResponseFormat } from "../openai/responseFormatSchema";
+import { phoenixToolDefinitionSchema } from "./toolSchemas";
+import { phoenixToolChoiceSchema } from "./toolChoiceSchemas";
+import { jsonSchemaZodSchema } from "../../jsonSchema";
+
+/*
+ * Conversion Functions
+ *
+ * These follow a hub-and-spoke model where OpenAI is the hub format.
+ * All conversions between different formats go through OpenAI as an intermediate step.
+ */
+
+export const phoenixMessagePartToOpenAI = phoenixContentPartSchema.transform(
+  (part) => {
+    const type = part.type;
+    switch (type) {
+      case "text":
+        return {
+          type: "text",
+          text: part.text,
+        } satisfies OpenAIChatPartText;
+      case "tool_call":
+        return null;
+      case "tool_result":
+        return null;
+      default:
+        return assertUnreachable(type);
+    }
+  }
+);
+
+/**
+ * Spoke → Hub: Convert a Prompt message to OpenAI format
+ */
+export const phoenixMessageToOpenAI = phoenixMessageSchema.transform(
+  (prompt) => {
+    const content =
+      typeof prompt.content == "string"
+        ? [{ type: "text", text: prompt.content }]
+        : prompt.content;
+    // Special handling for TOOL role messages
+    if (prompt.role === "tool") {
+      const toolResult = content
+        .map((part) => asToolResultPart(part))
+        .find((part): part is ToolResultPart => !!part);
+
+      if (!toolResult) {
+        throw new Error("TOOL role message must have a ToolResultContentPart");
+      }
+
+      return {
+        role: "tool",
+        content:
+          typeof toolResult.tool_result === "string"
+            ? toolResult.tool_result
+            : safelyStringifyJSON(toolResult.tool_result).json || "",
+        tool_call_id: toolResult.tool_call_id,
+      } satisfies OpenAIMessage;
+    }
+
+    // Handle other roles
+    const role = prompt.role;
+    switch (role) {
+      case "system":
+      case "developer":
+        return {
+          role: "system",
+          content: content
+            .map((part) => phoenixMessagePartToOpenAI.parse(part))
+            .filter(
+              (part): part is OpenAIChatPartText =>
+                part !== null && part.type === "text"
+            ),
+        } satisfies OpenAIMessage;
+      case "user":
+        return {
+          role: "user",
+          content: content
+            .map((part) => phoenixMessagePartToOpenAI.parse(part))
+            .filter(
+              (part): part is OpenAIChatPartText =>
+                part !== null && part.type === "text"
+            ),
+        } satisfies OpenAIMessage;
+      case "assistant":
+      case "ai":
+      case "model":
+        return {
+          role: "assistant",
+          content: content
+            .map((part) => phoenixMessagePartToOpenAI.parse(part))
+            .filter(
+              (part): part is OpenAIChatPartText =>
+                part !== null && part.type === "text"
+            ),
+          tool_calls: content.some((part) => part.type === "tool_call")
+            ? content
+                .filter(
+                  (part): part is ToolCallPart => part.type === "tool_call"
+                )
+                .map((part) => phoenixToolCallToOpenAI.parse(part))
+                .filter((part): part is OpenAIToolCall => part !== null)
+            : undefined,
+        } satisfies OpenAIMessage;
+      default:
+        return assertUnreachable(role);
+    }
+  }
+);
+
+export const phoenixResponseFormatToOpenAI =
+  phoenixResponseFormatSchema.transform(
+    (phoenix): OpenAIResponseFormat => ({
+      type: "json_schema",
+      json_schema: {
+        name: phoenix.json_schema.name,
+        description: phoenix.json_schema.description,
+        schema: jsonSchemaZodSchema.parse(phoenix.json_schema.schema),
+      },
+    })
+  );
+
+export const phoenixToolCallToOpenAI = phoenixToolCallSchema.transform(
+  (prompt): OpenAIToolCall => ({
+    type: "function",
+    id: prompt.tool_call_id,
+    function: {
+      ...prompt.tool_call,
+      arguments:
+        typeof prompt.tool_call.arguments === "string"
+          ? prompt.tool_call.arguments
+          : (safelyStringifyJSON(prompt.tool_call.arguments).json ?? ""),
+    },
+  })
+);
+
+export const phoenixToolDefinitionToOpenAI =
+  phoenixToolDefinitionSchema.transform(
+    (phoenix): OpenAIToolDefinition => ({
+      type: "function",
+      function: {
+        name: phoenix.function.name,
+        description: phoenix.function.description,
+        parameters: jsonSchemaZodSchema.parse(phoenix.function.parameters),
+      },
+    })
+  );
+
+export const phoenixToolChoiceToOpenAI = phoenixToolChoiceSchema.transform(
+  (phoenix): OpenaiToolChoice => {
+    switch (phoenix.type) {
+      case "none":
+        return "none";
+      case "zero_or_more":
+        return "auto";
+      case "one_or_more":
+        return "required";
+      case "specific_function":
+        return { type: "function", function: { name: phoenix.function_name } };
+    }
+  }
+);

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

@@ -0,0 +1,95 @@
+import z from "zod";
+import { schemaMatches } from "../../../utils/schemaMatches";
+import type { PromptChatMessagePart } from "../../../types/prompts";
+
+export const textPartSchema = schemaMatches<
+  Extract<PromptChatMessagePart, { type: "text" }>
+>()(
+  z.object({
+    type: z.literal("text"),
+    text: z.string(),
+  })
+);
+
+export type TextPart = z.infer<typeof textPartSchema>;
+
+export const toolCallPartSchema = schemaMatches<
+  Extract<PromptChatMessagePart, { type: "tool_call" }>
+>()(
+  z.object({
+    type: z.literal("tool_call"),
+    tool_call_id: z.string(),
+    tool_call: z.object({
+      type: z.literal("function"),
+      name: z.string(),
+      arguments: z.string(),
+    }),
+  })
+);
+
+export type ToolCallPart = z.infer<typeof toolCallPartSchema>;
+
+export const toolResultPartSchema = schemaMatches<
+  Extract<PromptChatMessagePart, { type: "tool_result" }>
+>()(
+  z.object({
+    type: z.literal("tool_result"),
+    tool_call_id: z.string(),
+    tool_result: z.union([
+      z.string(),
+      z.number(),
+      z.boolean(),
+      z.null(),
+      z.record(z.unknown()),
+      z.array(z.unknown()),
+    ]),
+  })
+);
+
+export type ToolResultPart = z.infer<typeof toolResultPartSchema>;
+
+export const phoenixContentPartSchema = schemaMatches<PromptChatMessagePart>()(
+  z.discriminatedUnion("type", [
+    textPartSchema,
+    toolCallPartSchema,
+    toolResultPartSchema,
+  ])
+);
+
+export type PhoenixContentPart = z.infer<typeof phoenixContentPartSchema>;
+
+/*
+ *
+ * Creation helpers
+ *
+ */
+
+export const asTextPart = (maybePart: unknown): TextPart | null => {
+  const parsed = textPartSchema.safeParse(maybePart);
+  return parsed.success ? parsed.data : null;
+};
+
+export const makeTextPart = (text?: string | null) => {
+  const optimisticTextPart = { text: { text } };
+  const parsed = textPartSchema.safeParse(optimisticTextPart);
+  return parsed.success ? parsed.data : null;
+};
+
+export const asToolCallPart = (maybePart: unknown): ToolCallPart | null => {
+  const parsed = toolCallPartSchema.safeParse(maybePart);
+  return parsed.success ? parsed.data : null;
+};
+
+export const asToolResultPart = (maybePart: unknown): ToolResultPart | null => {
+  const parsed = toolResultPartSchema.safeParse(maybePart);
+  return parsed.success ? parsed.data : null;
+};
+
+export const makeToolResultPart = (
+  toolCallId?: string | null,
+  result?: unknown
+) => {
+  const optimisticToolResultPart = { toolResult: { toolCallId, result } };
+  const parsed = toolResultPartSchema.safeParse(optimisticToolResultPart);
+  return parsed.success ? parsed.data : null;
+};

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

@@ -0,0 +1,34 @@
+import z from "zod";
+
+import { phoenixContentPartSchema } from "./messagePartSchemas";
+import type { PromptChatMessage } from "../../../types/prompts";
+import { schemaMatches } from "../../../utils/schemaMatches";
+
+/**
+ *
+ * Prompt Message Schemas
+ *
+ */
+
+export const phoenixMessageRoleSchema = z.enum([
+  "system",
+  "developer",
+  "user",
+  "assistant",
+  "model",
+  "ai",
+  "tool",
+]);
+
+export type PhoenixMessageRole = z.infer<typeof phoenixMessageRoleSchema>;
+
+export const phoenixMessageSchema = schemaMatches<PromptChatMessage>()(
+  z.object({
+    role: phoenixMessageRoleSchema,
+    content: z.union([z.string(), phoenixContentPartSchema.array()]),
+  })
+);
+
+export type PhoenixMessage = z.infer<typeof phoenixMessageSchema>;
+
+export const phoenixMessagesSchema = z.array(phoenixMessageSchema);

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

@@ -0,0 +1,21 @@
+import z from "zod";
+import { schemaMatches } from "../../../utils/schemaMatches";
+import { PromptResponseFormat } from "../../../types/prompts";
+
+/**
+ * Phoenix response format schema
+ */
+export const phoenixResponseFormatSchema =
+  schemaMatches<PromptResponseFormat>()(
+    z.object({
+      type: z.literal("json_schema"),
+      json_schema: z.object({
+        name: z.string(),
+        description: z.string().optional(),
+        schema: z.record(z.unknown()).optional(),
+        strict: z.boolean().optional(),
+      }),
+    })
+  );
+
+export type PhoenixResponseFormat = z.infer<typeof phoenixResponseFormatSchema>;

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

@@ -0,0 +1,7 @@
+import z from "zod";
+
+import { toolCallPartSchema } from "./messagePartSchemas";
+
+export const phoenixToolCallSchema = toolCallPartSchema;
+
+export type PhoenixToolCall = z.infer<typeof phoenixToolCallSchema>;

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

@@ -0,0 +1,26 @@
+import z from "zod";
+import { schemaMatches } from "../../../utils/schemaMatches";
+import { PromptToolChoice } from "../../../types/prompts";
+
+/**
+ * Phoenix's tool choice schema
+ */
+export const phoenixToolChoiceSchema = schemaMatches<PromptToolChoice>()(
+  z.union([
+    z.object({
+      type: z.literal("none"),
+    }),
+    z.object({
+      type: z.literal("zero_or_more"),
+    }),
+    z.object({
+      type: z.literal("one_or_more"),
+    }),
+    z.object({
+      type: z.literal("specific_function"),
+      function_name: z.string(),
+    }),
+  ])
+);
+
+export type PhoenixToolChoice = z.infer<typeof phoenixToolChoiceSchema>;

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

@@ -0,0 +1,20 @@
+import z from "zod";
+import { schemaMatches } from "../../../utils/schemaMatches";
+import { PromptTool } from "../../../types/prompts";
+
+/**
+ * The Phoenix tool definition schema
+ */
+export const phoenixToolDefinitionSchema = schemaMatches<PromptTool>()(
+  z.object({
+    type: z.literal("function"),
+    function: z.object({
+      name: z.string(),
+      description: z.string().optional(),
+      parameters: z.record(z.unknown()).optional(),
+      strict: z.boolean().optional(),
+    }),
+  })
+);
+
+export type PhoenixToolDefinition = z.infer<typeof phoenixToolDefinitionSchema>;

package/src/schemas/llm/schemas.ts

@@ -0,0 +1,94 @@
+import z from "zod";
+import { anthropicMessageSchema } from "./anthropic/messageSchemas";
+import { openAIMessageSchema } from "./openai/messageSchemas";
+import { phoenixMessageSchema } from "./phoenixPrompt/messageSchemas";
+import { openAIToolCallSchema } from "./openai/toolCallSchemas";
+import { anthropicToolCallSchema } from "./anthropic/toolCallSchemas";
+import { openAIToolChoiceSchema } from "./openai/toolChoiceSchemas";
+import { anthropicToolChoiceSchema } from "./anthropic/toolChoiceSchemas";
+import { openAIToolDefinitionSchema } from "./openai/toolSchemas";
+import { anthropicToolDefinitionSchema } from "./anthropic/toolSchemas";
+import { phoenixToolDefinitionSchema } from "./phoenixPrompt/toolSchemas";
+import { phoenixToolChoiceSchema } from "./phoenixPrompt/toolChoiceSchemas";
+import { vercelAIToolChoiceSchema } from "./vercel/toolChoiceSchemas";
+import { phoenixToolCallSchema } from "./phoenixPrompt/toolCallSchemas";
+import { vercelAIChatPartToolCallSchema } from "./vercel/messagePartSchemas";
+import { vercelAIMessageSchema } from "./vercel/messageSchemas";
+
+/**
+ * Union of all message formats
+ */
+export const llmProviderMessageSchema = z.union([
+  openAIMessageSchema,
+  anthropicMessageSchema,
+  phoenixMessageSchema,
+  vercelAIMessageSchema,
+]);
+
+export type LlmProviderMessage = z.infer<typeof llmProviderMessageSchema>;
+
+/**
+ * Union of all tool call formats
+ *
+ * This is useful for functions that need to accept any tool call format
+ */
+export const llmProviderToolCallSchema = z.union([
+  openAIToolCallSchema,
+  anthropicToolCallSchema,
+  phoenixToolCallSchema,
+  vercelAIChatPartToolCallSchema,
+]);
+
+export type LlmProviderToolCall = z.infer<typeof llmProviderToolCallSchema>;
+
+/**
+ * A union of all the lists of tool call formats
+ *
+ * This is useful for parsing all of the tool calls in a message
+ */
+export const llmProviderToolCallsSchema = z.array(llmProviderToolCallSchema);
+
+export type LlmProviderToolCalls = z.infer<typeof llmProviderToolCallsSchema>;
+
+/**
+ * A schema for a tool call that is not in the first class supported format
+ *
+ * This is used to heuristically find the id, name, and arguments of a tool call
+ * based on common patterns in tool calls, allowing us to poke around in an unknown tool call
+ * and extract the id, name, and arguments
+ */
+export const toolCallHeuristicSchema = z.object({
+  id: z.string().optional(),
+  name: z.string().optional(),
+  arguments: z.record(z.unknown()).optional(),
+  function: z
+    .object({
+      name: z.string().optional(),
+      arguments: z.record(z.unknown()).optional(),
+    })
+    .optional(),
+});
+
+export const llmProviderToolChoiceSchema = z.union([
+  openAIToolChoiceSchema,
+  anthropicToolChoiceSchema,
+  phoenixToolChoiceSchema,
+  vercelAIToolChoiceSchema,
+]);
+
+export type LlmProviderToolChoice = z.infer<typeof llmProviderToolChoiceSchema>;
+
+/**
+ * Union of all tool call formats
+ *
+ * This is useful for functions that need to accept any tool definition format
+ */
+export const llmProviderToolDefinitionSchema = z.union([
+  openAIToolDefinitionSchema,
+  anthropicToolDefinitionSchema,
+  phoenixToolDefinitionSchema,
+]);
+
+export type LlmProviderToolDefinition = z.infer<
+  typeof llmProviderToolDefinitionSchema
+>;

package/src/schemas/llm/types.ts

@@ -0,0 +1,161 @@
+import { ZodType, ZodTypeAny, ZodTypeDef } from "zod";
+
+import type { OpenAIChatPart } from "./openai/messagePartSchemas";
+import type { AnthropicMessagePart } from "./anthropic/messagePartSchemas";
+import type {
+  VercelAIChatPart,
+  VercelAIChatPartToolCall,
+} from "./vercel/messagePartSchemas";
+import { PromptProviderSDKs, PromptToolChoice } from "../../types/prompts";
+import { OpenAIMessage } from "./openai/messageSchemas";
+import { AnthropicMessage } from "./anthropic/messageSchemas";
+import { OpenAIToolCall } from "./openai/toolCallSchemas";
+import { AnthropicToolCall } from "./anthropic/toolCallSchemas";
+import { OpenaiToolChoice } from "./openai/toolChoiceSchemas";
+import { AnthropicToolChoice } from "./anthropic/toolChoiceSchemas";
+import { VercelAIMessage } from "./vercel/messageSchemas";
+import { PhoenixToolCall } from "./phoenixPrompt/toolCallSchemas";
+import { PhoenixMessage } from "./phoenixPrompt/messageSchemas";
+import { VercelAIToolChoice } from "./vercel/toolChoiceSchemas";
+import { OpenAIToolDefinition } from "./openai/toolSchemas";
+import { OpenAIResponseFormat } from "./openai/responseFormatSchema";
+import { AnthropicToolDefinition } from "./anthropic/toolSchemas";
+import { PhoenixToolDefinition } from "./phoenixPrompt/toolSchemas";
+import { PhoenixContentPart } from "./phoenixPrompt/messagePartSchemas";
+
+export type PromptSDKFormat = PromptProviderSDKs | null;
+
+export type LLMMessagePart =
+  | OpenAIChatPart
+  | AnthropicMessagePart
+  | PhoenixContentPart
+  | 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,
+> = {
+  messages: {
+    toOpenAI: ZodType<OpenAIMessage | null, ZodTypeDef, unknown>;
+    fromOpenAI: MessageSchema;
+  };
+  messageParts: {
+    toOpenAI: ZodType<OpenAIChatPart | null, ZodTypeDef, unknown>;
+    fromOpenAI: MessagePartSchema;
+  };
+  toolChoices: {
+    toOpenAI: ZodType<OpenaiToolChoice | null, ZodTypeDef, unknown>;
+    fromOpenAI: ToolChoiceSchema;
+  };
+  toolCalls: {
+    toOpenAI: ZodType<OpenAIToolCall | null, ZodTypeDef, unknown>;
+    fromOpenAI: ToolCallSchema;
+  };
+  toolDefinitions: {
+    toOpenAI: ZodType<OpenAIToolDefinition | null, ZodTypeDef, unknown>;
+    fromOpenAI: ToolDefinitionSchema;
+  };
+  responseFormat?: {
+    toOpenAI: ZodType<OpenAIResponseFormat | null, ZodTypeDef, unknown>;
+    fromOpenAI: ResponseFormatSchema;
+  };
+};
+
+export type MessagePartWithProvider =
+  | {
+      provider: Extract<PromptSDKFormat, "OPENAI" | "AZURE_OPENAI">;
+      validatedMessage: OpenAIChatPart;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "ANTHROPIC">;
+      validatedMessage: AnthropicMessagePart;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "PHOENIX">;
+      validatedMessage: PhoenixContentPart;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "VERCEL_AI">;
+      validatedMessage: VercelAIChatPart;
+    }
+  | { provider: null; validatedMessage: null };
+
+export type MessageWithProvider =
+  | {
+      provider: Extract<PromptSDKFormat, "OPENAI" | "AZURE_OPENAI">;
+      validatedMessage: OpenAIMessage;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "ANTHROPIC">;
+      validatedMessage: AnthropicMessage;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "PHOENIX">;
+      validatedMessage: PhoenixMessage;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "VERCEL_AI">;
+      validatedMessage: VercelAIMessage;
+    }
+  | { provider: null; validatedMessage: null };
+
+export type ToolDefinitionWithProvider =
+  | {
+      provider: Extract<PromptSDKFormat, "OPENAI" | "AZURE_OPENAI">;
+      validatedToolDefinition: OpenAIToolDefinition;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "ANTHROPIC">;
+      validatedToolDefinition: AnthropicToolDefinition;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "PHOENIX">;
+      validatedToolDefinition: PhoenixToolDefinition;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "VERCEL_AI">;
+      validatedToolDefinition: null;
+    }
+  | { provider: null; validatedToolDefinition: null };
+
+export type ToolCallWithProvider =
+  | {
+      provider: Extract<PromptSDKFormat, "OPENAI" | "AZURE_OPENAI">;
+      validatedToolCall: OpenAIToolCall;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "ANTHROPIC">;
+      validatedToolCall: AnthropicToolCall;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "PHOENIX">;
+      validatedToolCall: PhoenixToolCall;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "VERCEL_AI">;
+      validatedToolCall: VercelAIChatPartToolCall;
+    }
+  | { provider: null; validatedToolCall: null };
+
+export type ToolChoiceWithProvider =
+  | {
+      provider: Extract<PromptSDKFormat, "OPENAI" | "AZURE_OPENAI">;
+      toolChoice: OpenaiToolChoice;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "ANTHROPIC">;
+      toolChoice: AnthropicToolChoice;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "PHOENIX">;
+      toolChoice: PromptToolChoice;
+    }
+  | {
+      provider: Extract<PromptSDKFormat, "VERCEL_AI">;
+      toolChoice: VercelAIToolChoice;
+    }
+  | { provider: null; toolChoice: null };