@arizeai/phoenix-client 2.1.0 → 2.2.0

package/src/prompts/constants.ts

@@ -8,4 +8,8 @@ export const PromptModelProviders: Record<PromptModelProvider, string> = {
   AZURE_OPENAI: "Azure OpenAI",
   ANTHROPIC: "Anthropic",
   GOOGLE: "Google",
+  DEEPSEEK: "DeepSeek",
+  XAI: "xAI",
+  OLLAMA: "Ollama",
+  AWS: "AWS Bedrock",
 };

package/src/prompts/createPrompt.ts

@@ -8,6 +8,10 @@ import {
   AzureOpenAIInvocationParameters,
   AnthropicInvocationParameters,
   GoogleInvocationParameters,
+  DeepSeekInvocationParameters,
+  XAIInvocationParameters,
+  OllamaInvocationParameters,
+  AwsInvocationParameters,
   PromptChatMessage,
 } from "../types/prompts";
 import { assertUnreachable } from "../utils/assertUnreachable";
@@ -104,7 +108,22 @@ interface GooglePromptVersionInput extends PromptVersionInputBase {
 
 interface DeepSeekPromptVersionInput extends PromptVersionInputBase {
   modelProvider: "DEEPSEEK";
-  invocationParameters?: OpenAIInvocationParameters;
+  invocationParameters?: DeepSeekInvocationParameters;
+}
+
+interface XAIPromptVersionInput extends PromptVersionInputBase {
+  modelProvider: "XAI";
+  invocationParameters?: XAIInvocationParameters;
+}
+
+interface OllamaPromptVersionInput extends PromptVersionInputBase {
+  modelProvider: "OLLAMA";
+  invocationParameters?: OllamaInvocationParameters;
+}
+
+interface AwsPromptVersionInput extends PromptVersionInputBase {
+  modelProvider: "AWS";
+  invocationParameters?: AwsInvocationParameters;
 }
 
 type PromptVersionInput =
@@ -112,7 +131,10 @@ type PromptVersionInput =
   | AzureOpenAIPromptVersionInput
   | AnthropicPromptVersionInput
   | GooglePromptVersionInput
-  | DeepSeekPromptVersionInput;
+  | DeepSeekPromptVersionInput
+  | XAIPromptVersionInput
+  | OllamaPromptVersionInput
+  | AwsPromptVersionInput;
 
 /**
  * A helper function to construct a prompt version declaratively.
@@ -212,6 +234,54 @@ export function promptVersion(params: PromptVersionInput): PromptVersionData {
           deepseek: invocation_parameters ?? {},
         },
       };
+    case "XAI":
+      return {
+        description,
+        model_provider,
+        model_name,
+        template_type: "CHAT",
+        template_format,
+        template: {
+          type: "chat",
+          messages: templateMessages,
+        },
+        invocation_parameters: {
+          type: "xai",
+          xai: invocation_parameters ?? {},
+        },
+      };
+    case "OLLAMA":
+      return {
+        description,
+        model_provider,
+        model_name,
+        template_type: "CHAT",
+        template_format,
+        template: {
+          type: "chat",
+          messages: templateMessages,
+        },
+        invocation_parameters: {
+          type: "ollama",
+          ollama: invocation_parameters ?? {},
+        },
+      };
+    case "AWS":
+      return {
+        description,
+        model_provider,
+        model_name,
+        template_type: "CHAT",
+        template_format,
+        template: {
+          type: "chat",
+          messages: templateMessages,
+        },
+        invocation_parameters: {
+          type: "aws",
+          aws: invocation_parameters ?? {},
+        },
+      };
     default:
       assertUnreachable(model_provider);
   }

package/src/spans/getSpanAnnotations.ts

@@ -0,0 +1,131 @@
+import { createClient } from "../client";
+import { ClientFn } from "../types/core";
+import { operations } from "../__generated__/api/v1";
+import { ProjectSelector } from "../types/projects";
+
+/**
+ * Parameters to get span annotations from a project using auto-generated types
+ */
+interface GetSpanAnnotationsParams extends ClientFn {
+  /** The project to get span annotations from */
+  project: ProjectSelector;
+  /** 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. */
+  includeAnnotationNames?: string[];
+  /** Optional list of annotation names to exclude from results. */
+  excludeAnnotationNames?: string[];
+  /** Pagination cursor */
+  cursor?: string | null;
+  /** Maximum number of annotations to return */
+  limit?: number;
+}
+
+type GetSpanAnnotationsResponse =
+  operations["listSpanAnnotationsBySpanIds"]["responses"]["200"];
+
+export type GetSpanAnnotationsResult = {
+  annotations: GetSpanAnnotationsResponse["content"]["application/json"]["data"];
+  nextCursor: GetSpanAnnotationsResponse["content"]["application/json"]["next_cursor"];
+};
+
+/**
+ * Get span annotations for a list of span IDs.
+ *
+ * This method allows you to retrieve annotations for specific spans within a project.
+ * You can filter annotations by name and support cursor-based pagination.
+ *
+ * @experimental this function is experimental and may change in the future
+ *
+ * @param params - The parameters to get span annotations
+ * @returns A paginated response containing annotations and optional next cursor
+ *
+ * @example
+ * ```ts
+ * // Get annotations for specific spans
+ * const result = await getSpanAnnotations({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   spanIds: ["span1", "span2", "span3"],
+ *   limit: 50
+ * });
+ *
+ * // Get specific annotation types
+ * const result = await getSpanAnnotations({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   spanIds: ["span1"],
+ *   includeAnnotationNames: ["quality_score", "sentiment"],
+ *   limit: 100
+ * });
+ *
+ * // Paginate through results
+ * let cursor: string | undefined;
+ * do {
+ *   const result = await getSpanAnnotations({
+ *     client,
+ *     project: { projectName: "my-project" },
+ *     spanIds: ["span1"],
+ *     cursor,
+ *     limit: 100
+ *   });
+ *
+ *   // Process annotations
+ *   result.annotations.forEach(annotation => {
+ *     console.log(`Annotation: ${annotation.name}, Label: ${annotation.result.label}`);
+ *   });
+ *
+ *   cursor = result.nextCursor || undefined;
+ * } while (cursor);
+ * ```
+ */
+export async function getSpanAnnotations({
+  client: _client,
+  project,
+  spanIds,
+  includeAnnotationNames,
+  excludeAnnotationNames,
+  cursor,
+  limit = 100,
+}: GetSpanAnnotationsParams): Promise<GetSpanAnnotationsResult> {
+  const client = _client ?? createClient();
+  const projectIdentifier =
+    "projectId" in project ? project.projectId : project.projectName;
+
+  const params: NonNullable<
+    operations["listSpanAnnotationsBySpanIds"]["parameters"]["query"]
+  > = {
+    span_ids: spanIds,
+    limit,
+  };
+
+  if (cursor) {
+    params.cursor = cursor;
+  }
+
+  if (includeAnnotationNames !== undefined) {
+    params.include_annotation_names = includeAnnotationNames;
+  }
+
+  if (excludeAnnotationNames !== undefined) {
+    params.exclude_annotation_names = excludeAnnotationNames;
+  }
+
+  const { data, error } = await client.GET(
+    "/v1/projects/{project_identifier}/span_annotations",
+    {
+      params: {
+        path: {
+          project_identifier: projectIdentifier,
+        },
+        query: params,
+      },
+    }
+  );
+
+  if (error) throw error;
+  return {
+    annotations: data?.data ?? [],
+    nextCursor: data?.next_cursor ?? null,
+  };
+}

package/src/spans/getSpans.ts

@@ -0,0 +1,127 @@
+import { createClient } from "../client";
+import { ClientFn } from "../types/core";
+import { operations } from "../__generated__/api/v1";
+import { ProjectSelector } from "../types/projects";
+
+/**
+ * Parameters to get spans from a project using auto-generated types
+ */
+interface GetSpansParams extends ClientFn {
+  /** The project to get spans from */
+  project: ProjectSelector;
+  /** 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. */
+  endTime?: Date | string | null;
+  /** Pagination cursor (Span Global ID) */
+  cursor?: string | null;
+  /** Maximum number of spans to return */
+  limit?: number;
+}
+
+type GetSpansResponse = operations["getSpans"]["responses"]["200"];
+
+export type GetSpansResult = {
+  spans: GetSpansResponse["content"]["application/json"]["data"];
+  nextCursor: GetSpansResponse["content"]["application/json"]["next_cursor"];
+};
+
+/**
+ * Get spans from a project with filtering criteria.
+ *
+ * This method allows you to search for spans within a project using various filters
+ * such as time range and supports cursor-based pagination.
+ * The spans are returned in Phoenix's standard format with human-readable timestamps
+ * and simplified attribute structures.
+ *
+ * @experimental this function is experimental and may change in the future
+ *
+ * @param params - The parameters to search for spans
+ * @returns A paginated response containing spans and optional next cursor
+ *
+ * @example
+ * ```ts
+ * // Get recent spans from a project
+ * const result = await getSpans({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   limit: 50
+ * });
+ *
+ * // Get spans in a time range
+
+ * const result = await getSpans({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   startTime: new Date("2024-01-01"),
+ *   endTime: new Date("2024-01-02"),
+ *   limit: 100
+ * });
+
+ *
+ * // Paginate through results
+ * let cursor: string | undefined;
+ * do {
+ *   const result = await getSpans({
+ *     client,
+ *     project: { projectName: "my-project" },
+ *     cursor,
+ *     limit: 100
+ *   });
+ *
+ *   // Process spans
+ *   result.spans.forEach(span => {
+ *     console.log(`Span: ${span.name}, Trace: ${span.context.trace_id}`);
+ *   });
+ *
+ *   cursor = result.nextCursor || undefined;
+ * } while (cursor);
+ * ```
+ */
+export async function getSpans({
+  client: _client,
+  project,
+  cursor,
+  limit = 100,
+  startTime,
+  endTime,
+}: GetSpansParams): Promise<GetSpansResult> {
+  const client = _client ?? createClient();
+  const projectIdentifier =
+    "projectId" in project ? project.projectId : project.projectName;
+
+  const params: NonNullable<operations["getSpans"]["parameters"]["query"]> = {
+    limit,
+  };
+
+  if (cursor) {
+    params.cursor = cursor;
+  }
+
+  if (startTime) {
+    params.start_time =
+      startTime instanceof Date ? startTime.toISOString() : startTime;
+  }
+
+  if (endTime) {
+    params.end_time = endTime instanceof Date ? endTime.toISOString() : endTime;
+  }
+
+  const { data, error } = await client.GET(
+    "/v1/projects/{project_identifier}/spans",
+    {
+      params: {
+        path: {
+          project_identifier: projectIdentifier,
+        },
+        query: params,
+      },
+    }
+  );
+
+  if (error) throw error;
+  return {
+    spans: data?.data ?? [],
+    nextCursor: data?.next_cursor ?? null,
+  };
+}

package/src/spans/index.ts

@@ -1,2 +1,4 @@
 export * from "./addSpanAnnotation";
 export * from "./logSpanAnnotations";
+export * from "./getSpans";
+export * from "./getSpanAnnotations";

package/src/types/projects.ts

@@ -0,0 +1,5 @@
+/**
+ * A project can be identified by its projectId or projectName
+ * In the case of a projectName, the name must be url encodable
+ */
+export type ProjectSelector = { projectId: string } | { projectName: string };

package/src/types/prompts.ts

@@ -7,7 +7,11 @@ export type PromptModelProvider =
   | "OPENAI"
   | "AZURE_OPENAI"
   | "ANTHROPIC"
-  | "GOOGLE";
+  | "GOOGLE"
+  | "DEEPSEEK"
+  | "XAI"
+  | "OLLAMA"
+  | "AWS";
 
 /**
  * Supported prompt provider SDKs
@@ -107,6 +111,30 @@ export type AnthropicInvocationParameters =
 export type GoogleInvocationParameters =
   components["schemas"]["PromptGoogleInvocationParametersContent"];
 
+/**
+ * The invocation parameters for a prompt version for DeepSeek.
+ */
+export type DeepSeekInvocationParameters =
+  components["schemas"]["PromptDeepSeekInvocationParametersContent"];
+
+/**
+ * The invocation parameters for a prompt version for xAI.
+ */
+export type XAIInvocationParameters =
+  components["schemas"]["PromptXAIInvocationParametersContent"];
+
+/**
+ * The invocation parameters for a prompt version for Ollama.
+ */
+export type OllamaInvocationParameters =
+  components["schemas"]["PromptOllamaInvocationParametersContent"];
+
+/**
+ * The invocation parameters for a prompt version for AWS.
+ */
+export type AwsInvocationParameters =
+  components["schemas"]["PromptAwsInvocationParametersContent"];
+
 /**
  * The format of the prompt template message(s).
  */