@arizeai/phoenix-client 2.1.1 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "A client for the Phoenix API",
   "main": "dist/src/index.js",
   "module": "dist/esm/index.js",

package/src/__generated__/api/v1.ts

@@ -327,7 +327,7 @@ export interface paths {
         };
         /**
          * Search spans with simple filters (no DSL)
-         * @description Return spans within a project filtered by time range, annotation names, and ordered by start_time. Supports cursor-based pagination.
+         * @description Return spans within a project filtered by time range. Supports cursor-based pagination.
          */
         get: operations["spanSearch"];
         put?: never;
@@ -338,6 +338,30 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/projects/{project_identifier}/spans": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List spans with simple filters (no DSL)
+         * @description Return spans within a project filtered by time range. Supports cursor-based pagination.
+         */
+        get: operations["getSpans"];
+        put?: never;
+        /**
+         * Create spans
+         * @description Submit spans to be inserted into a project. If any spans are invalid or duplicates, no spans will be inserted.
+         */
+        post: operations["createSpans"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/span_annotations": {
         parameters: {
             query?: never;
@@ -803,6 +827,24 @@ export interface components {
         CreatePromptResponseBody: {
             data: components["schemas"]["PromptVersion"];
         };
+        /** CreateSpansRequestBody */
+        CreateSpansRequestBody: {
+            /** Data */
+            data: components["schemas"]["Span"][];
+        };
+        /** CreateSpansResponseBody */
+        CreateSpansResponseBody: {
+            /**
+             * Total Received
+             * @description Total number of spans received
+             */
+            total_received: number;
+            /**
+             * Total Queued
+             * @description Number of spans successfully queued for insertion
+             */
+            total_queued: number;
+        };
         /** CreateUserRequestBody */
         CreateUserRequestBody: {
             /** User */
@@ -1221,7 +1263,7 @@ export interface components {
          * ModelProvider
          * @enum {string}
          */
-        ModelProvider: "OPENAI" | "AZURE_OPENAI" | "ANTHROPIC" | "GOOGLE" | "DEEPSEEK" | "XAI";
+        ModelProvider: "OPENAI" | "AZURE_OPENAI" | "ANTHROPIC" | "GOOGLE" | "DEEPSEEK" | "XAI" | "OLLAMA" | "AWS";
         /** OAuth2User */
         OAuth2User: {
             /** Id */
@@ -1463,6 +1505,16 @@ export interface components {
              */
             trace_state?: string | null;
         };
+        /**
+         * OtlpSpansResponseBody
+         * @description Paginated response where each span follows OTLP JSON structure.
+         */
+        OtlpSpansResponseBody: {
+            /** Data */
+            data: components["schemas"]["OtlpSpan"][];
+            /** Next Cursor */
+            next_cursor: string | null;
+        };
         /** OtlpStatus */
         OtlpStatus: {
             /**
@@ -1535,6 +1587,24 @@ export interface components {
             /** Budget Tokens */
             budget_tokens: number;
         };
+        /** PromptAwsInvocationParameters */
+        PromptAwsInvocationParameters: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "aws";
+            aws: components["schemas"]["PromptAwsInvocationParametersContent"];
+        };
+        /** PromptAwsInvocationParametersContent */
+        PromptAwsInvocationParametersContent: {
+            /** Max Tokens */
+            max_tokens?: number;
+            /** Temperature */
+            temperature?: number;
+            /** Top P */
+            top_p?: number;
+        };
         /** PromptAzureOpenAIInvocationParameters */
         PromptAzureOpenAIInvocationParameters: {
             /**
@@ -1651,6 +1721,37 @@ export interface components {
             /** Content */
             content: string | (components["schemas"]["TextContentPart"] | components["schemas"]["ToolCallContentPart"] | components["schemas"]["ToolResultContentPart"])[];
         };
+        /** PromptOllamaInvocationParameters */
+        PromptOllamaInvocationParameters: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "ollama";
+            ollama: components["schemas"]["PromptOllamaInvocationParametersContent"];
+        };
+        /** PromptOllamaInvocationParametersContent */
+        PromptOllamaInvocationParametersContent: {
+            /** Temperature */
+            temperature?: number;
+            /** Max Tokens */
+            max_tokens?: number;
+            /** Max Completion Tokens */
+            max_completion_tokens?: number;
+            /** Frequency Penalty */
+            frequency_penalty?: number;
+            /** Presence Penalty */
+            presence_penalty?: number;
+            /** Top P */
+            top_p?: number;
+            /** Seed */
+            seed?: number;
+            /**
+             * Reasoning Effort
+             * @enum {string}
+             */
+            reasoning_effort?: "low" | "medium" | "high";
+        };
         /** PromptOpenAIInvocationParameters */
         PromptOpenAIInvocationParameters: {
             /**
@@ -1806,7 +1907,7 @@ export interface components {
             template_type: components["schemas"]["PromptTemplateType"];
             template_format: components["schemas"]["PromptTemplateFormat"];
             /** Invocation Parameters */
-            invocation_parameters: components["schemas"]["PromptOpenAIInvocationParameters"] | components["schemas"]["PromptAzureOpenAIInvocationParameters"] | components["schemas"]["PromptAnthropicInvocationParameters"] | components["schemas"]["PromptGoogleInvocationParameters"] | components["schemas"]["PromptDeepSeekInvocationParameters"] | components["schemas"]["PromptXAIInvocationParameters"];
+            invocation_parameters: components["schemas"]["PromptOpenAIInvocationParameters"] | components["schemas"]["PromptAzureOpenAIInvocationParameters"] | components["schemas"]["PromptAnthropicInvocationParameters"] | components["schemas"]["PromptGoogleInvocationParameters"] | components["schemas"]["PromptDeepSeekInvocationParameters"] | components["schemas"]["PromptXAIInvocationParameters"] | components["schemas"]["PromptOllamaInvocationParameters"] | components["schemas"]["PromptAwsInvocationParameters"];
             tools?: components["schemas"]["PromptTools"] | null;
             /** Response Format */
             response_format?: components["schemas"]["PromptResponseFormatJSONSchema"] | null;
@@ -1825,7 +1926,7 @@ export interface components {
             template_type: components["schemas"]["PromptTemplateType"];
             template_format: components["schemas"]["PromptTemplateFormat"];
             /** Invocation Parameters */
-            invocation_parameters: components["schemas"]["PromptOpenAIInvocationParameters"] | components["schemas"]["PromptAzureOpenAIInvocationParameters"] | components["schemas"]["PromptAnthropicInvocationParameters"] | components["schemas"]["PromptGoogleInvocationParameters"] | components["schemas"]["PromptDeepSeekInvocationParameters"] | components["schemas"]["PromptXAIInvocationParameters"];
+            invocation_parameters: components["schemas"]["PromptOpenAIInvocationParameters"] | components["schemas"]["PromptAzureOpenAIInvocationParameters"] | components["schemas"]["PromptAnthropicInvocationParameters"] | components["schemas"]["PromptGoogleInvocationParameters"] | components["schemas"]["PromptDeepSeekInvocationParameters"] | components["schemas"]["PromptXAIInvocationParameters"] | components["schemas"]["PromptOllamaInvocationParameters"] | components["schemas"]["PromptAwsInvocationParameters"];
             tools?: components["schemas"]["PromptTools"] | null;
             /** Response Format */
             response_format?: components["schemas"]["PromptResponseFormatJSONSchema"] | null;
@@ -1875,6 +1976,67 @@ export interface components {
              */
             reasoning_effort?: "low" | "medium" | "high";
         };
+        /** Span */
+        Span: {
+            /**
+             * Id
+             * @description Span Global ID, distinct from the OpenTelemetry span ID
+             * @default
+             */
+            id?: string;
+            /**
+             * Name
+             * @description Name of the span operation
+             */
+            name: string;
+            /** @description Span context containing trace_id and span_id */
+            context: components["schemas"]["SpanContext"];
+            /**
+             * Span Kind
+             * @description Type of work that the span encapsulates
+             */
+            span_kind: string;
+            /**
+             * Parent Id
+             * @description OpenTelemetry span ID of the parent span
+             */
+            parent_id?: string | null;
+            /**
+             * Start Time
+             * Format: date-time
+             * @description Start time of the span
+             */
+            start_time: string;
+            /**
+             * End Time
+             * Format: date-time
+             * @description End time of the span
+             */
+            end_time: string;
+            /**
+             * Status Code
+             * @description Status code of the span
+             */
+            status_code: string;
+            /**
+             * Status Message
+             * @description Status message
+             * @default
+             */
+            status_message?: string;
+            /**
+             * Attributes
+             * @description Span attributes
+             */
+            attributes?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Events
+             * @description Span events
+             */
+            events?: components["schemas"]["SpanEvent"][];
+        };
         /** SpanAnnotation */
         SpanAnnotation: {
             /**
@@ -1987,13 +2149,44 @@ export interface components {
             /** Next Cursor */
             next_cursor: string | null;
         };
-        /**
-         * SpanSearchResponseBody
-         * @description Paginated response where each span follows OTLP JSON structure.
-         */
-        SpanSearchResponseBody: {
+        /** SpanContext */
+        SpanContext: {
+            /**
+             * Trace Id
+             * @description OpenTelemetry trace ID
+             */
+            trace_id: string;
+            /**
+             * Span Id
+             * @description OpenTelemetry span ID
+             */
+            span_id: string;
+        };
+        /** SpanEvent */
+        SpanEvent: {
+            /**
+             * Name
+             * @description Name of the event
+             */
+            name: string;
+            /**
+             * Timestamp
+             * Format: date-time
+             * @description When the event occurred
+             */
+            timestamp: string;
+            /**
+             * Attributes
+             * @description Event attributes
+             */
+            attributes?: {
+                [key: string]: unknown;
+            };
+        };
+        /** SpansResponseBody */
+        SpansResponseBody: {
             /** Data */
-            data: components["schemas"]["OtlpSpan"][];
+            data: components["schemas"]["Span"][];
             /** Next Cursor */
             next_cursor: string | null;
         };
@@ -2367,6 +2560,10 @@ export interface operations {
             query: {
                 /** @description One or more span id to fetch annotations for */
                 span_ids: string[];
+                /** @description 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. */
+                include_annotation_names?: string[] | null;
+                /** @description Optional list of annotation names to exclude from results. */
+                exclude_annotation_names?: string[] | null;
                 /** @description A cursor for pagination */
                 cursor?: string | null;
                 /** @description The maximum number of annotations to return in a single request */
@@ -3263,18 +3460,73 @@ export interface operations {
     spanSearch: {
         parameters: {
             query?: {
-                /** @description Pagination cursor (GlobalID of Span) */
+                /** @description Pagination cursor (Span Global ID) */
+                cursor?: string | null;
+                /** @description Maximum number of spans to return */
+                limit?: number;
+                /** @description Inclusive lower bound time */
+                start_time?: string | null;
+                /** @description Exclusive upper bound time */
+                end_time?: string | null;
+            };
+            header?: never;
+            path: {
+                /** @description The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters. */
+                project_identifier: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OtlpSpansResponseBody"];
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Not Found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Unprocessable Entity */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+        };
+    };
+    getSpans: {
+        parameters: {
+            query?: {
+                /** @description Pagination cursor (Span Global ID) */
                 cursor?: string | null;
                 /** @description Maximum number of spans to return */
                 limit?: number;
-                /** @description Sort direction for the sort field */
-                sort_direction?: "asc" | "desc";
                 /** @description Inclusive lower bound time */
                 start_time?: string | null;
                 /** @description Exclusive upper bound time */
                 end_time?: string | null;
-                /** @description If provided, only include spans that have at least one annotation with one of these names. */
-                annotationNames?: string[] | null;
             };
             header?: never;
             path: {
@@ -3291,7 +3543,7 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["SpanSearchResponseBody"];
+                    "application/json": components["schemas"]["SpansResponseBody"];
                 };
             };
             /** @description Forbidden */
@@ -3323,6 +3575,69 @@ export interface operations {
             };
         };
     };
+    createSpans: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters. */
+                project_identifier: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateSpansRequestBody"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CreateSpansResponseBody"];
+                };
+            };
+            /** @description Bad Request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Not Found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
     annotateSpans: {
         parameters: {
             query?: {

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,12 +108,22 @@ interface GooglePromptVersionInput extends PromptVersionInputBase {
 
 interface DeepSeekPromptVersionInput extends PromptVersionInputBase {
   modelProvider: "DEEPSEEK";
-  invocationParameters?: OpenAIInvocationParameters;
+  invocationParameters?: DeepSeekInvocationParameters;
 }
 
 interface XAIPromptVersionInput extends PromptVersionInputBase {
   modelProvider: "XAI";
-  invocationParameters?: OpenAIInvocationParameters;
+  invocationParameters?: XAIInvocationParameters;
+}
+
+interface OllamaPromptVersionInput extends PromptVersionInputBase {
+  modelProvider: "OLLAMA";
+  invocationParameters?: OllamaInvocationParameters;
+}
+
+interface AwsPromptVersionInput extends PromptVersionInputBase {
+  modelProvider: "AWS";
+  invocationParameters?: AwsInvocationParameters;
 }
 
 type PromptVersionInput =
@@ -118,7 +132,9 @@ type PromptVersionInput =
   | AnthropicPromptVersionInput
   | GooglePromptVersionInput
   | DeepSeekPromptVersionInput
-  | XAIPromptVersionInput;
+  | XAIPromptVersionInput
+  | OllamaPromptVersionInput
+  | AwsPromptVersionInput;
 
 /**
  * A helper function to construct a prompt version declaratively.
@@ -234,6 +250,38 @@ export function promptVersion(params: PromptVersionInput): PromptVersionData {
           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,
+  };
+}