@arizeai/phoenix-client 3.0.0 → 3.2.0

package/src/spans/logDocumentAnnotations.ts

@@ -0,0 +1,79 @@
+import { createClient } from "../client";
+import { ClientFn } from "../types/core";
+import { DocumentAnnotation, toDocumentAnnotationData } from "./types";
+
+/**
+ * Parameters to log multiple document annotations
+ */
+export interface LogDocumentAnnotationsParams extends ClientFn {
+  /**
+   * The document annotations to log
+   */
+  documentAnnotations: DocumentAnnotation[];
+  /**
+   * If true, the request will be fulfilled synchronously and return the annotation IDs.
+   * If false, the request will be processed asynchronously and return null.
+   * @default false
+   */
+  sync?: boolean;
+}
+
+/**
+ * Log multiple document annotations in a single request.
+ *
+ * Each annotation can be of type "LLM", "CODE", or "HUMAN" and can include a label, score, explanation, and metadata.
+ * At least one of label, score, or explanation must be provided for each annotation.
+ *
+ * @param params - The parameters to log document annotations
+ * @returns The IDs of the created annotations
+ *
+ * @example
+ * ```ts
+ * const results = await logDocumentAnnotations({
+ *   documentAnnotations: [
+ *     {
+ *       spanId: "123abc",
+ *       documentPosition: 0,
+ *       name: "relevance_score",
+ *       label: "relevant",
+ *       score: 0.95,
+ *       annotatorKind: "LLM",
+ *       explanation: "Document is highly relevant to the query",
+ *       metadata: {
+ *         model: "gpt-4"
+ *       }
+ *     },
+ *     {
+ *       spanId: "123abc",
+ *       documentPosition: 1,
+ *       name: "relevance_score",
+ *       label: "somewhat_relevant",
+ *       score: 0.6,
+ *       annotatorKind: "LLM"
+ *     }
+ *   ]
+ * });
+ * ```
+ */
+export async function logDocumentAnnotations({
+  client: _client,
+  documentAnnotations,
+  sync = false,
+}: LogDocumentAnnotationsParams): Promise<{ id: string }[]> {
+  const client = _client ?? createClient();
+
+  const { data, error } = await client.POST("/v1/document_annotations", {
+    params: {
+      query: { sync },
+    },
+    body: {
+      data: documentAnnotations.map(toDocumentAnnotationData),
+    },
+  });
+
+  if (error) {
+    throw new Error(`Failed to log document annotations: ${error}`);
+  }
+
+  return data?.data || [];
+}

package/src/spans/logSpanAnnotations.ts

@@ -10,6 +10,12 @@ export interface LogSpanAnnotationsParams extends ClientFn {
    * The span annotations to log
    */
   spanAnnotations: SpanAnnotation[];
+  /**
+   * If true, the request will be fulfilled synchronously and return the annotation IDs.
+   * If false, the request will be processed asynchronously and return null.
+   * @default false
+   */
+  sync?: boolean;
 }
 
 /**
@@ -50,10 +56,14 @@ export interface LogSpanAnnotationsParams extends ClientFn {
 export async function logSpanAnnotations({
   client: _client,
   spanAnnotations,
+  sync = false,
 }: LogSpanAnnotationsParams): Promise<{ id: string }[]> {
   const client = _client ?? createClient();
 
   const { data, error } = await client.POST("/v1/span_annotations", {
+    params: {
+      query: { sync },
+    },
     body: {
       data: spanAnnotations.map(toSpanAnnotationData),
     },
@@ -63,9 +73,5 @@ export async function logSpanAnnotations({
     throw new Error(`Failed to log span annotations: ${error}`);
   }
 
-  if (!data?.data?.length) {
-    throw new Error("No annotation IDs returned from server");
-  }
-
-  return data.data;
+  return data?.data || [];
 }

package/src/spans/types.ts

@@ -3,6 +3,9 @@ import { paths } from "../__generated__/api/v1";
 type SpanAnnotationData =
   paths["/v1/span_annotations"]["post"]["requestBody"]["content"]["application/json"]["data"][0];
 
+type SpanDocumentAnnotationData =
+  paths["/v1/document_annotations"]["post"]["requestBody"]["content"]["application/json"]["data"][0];
+
 /**
  * Parameters for a single span annotation
  */
@@ -23,6 +26,10 @@ export interface SpanAnnotation {
    * The score assigned by the annotation
    */
   score?: number;
+  /**
+   * Explanation of the annotation result
+   */
+  explanation?: string;
   /**
    * The identifier of the annotation. If provided, the annotation will be updated if it already exists.
    */
@@ -39,22 +46,119 @@ export interface SpanAnnotation {
   annotatorKind?: SpanAnnotationData["annotator_kind"];
 }
 
+/**
+ * Parameters for a single document annotation
+ */
+export interface DocumentAnnotation {
+  /**
+   * The OpenTelemetry Span ID (hex format without 0x prefix)
+   */
+  spanId: string;
+  /**
+   * The 0-based index of the document within the span
+   */
+  documentPosition: number;
+  /**
+   * The name of the annotation
+   */
+  name: string;
+  /**
+   * The label assigned by the annotation
+   */
+  label?: string;
+  /**
+   * The score assigned by the annotation
+   */
+  score?: number;
+  /**
+   * Explanation of the annotation result
+   */
+  explanation?: string;
+  /**
+   * Metadata for the annotation
+   */
+  metadata?: Record<string, unknown>;
+  /**
+   * The kind of annotator used for the annotation
+   * Can be "HUMAN", "LLM", or "CODE"
+   * @default "HUMAN"
+   */
+  annotatorKind?: SpanDocumentAnnotationData["annotator_kind"];
+}
+
+type AnnotationResult = {
+  label?: string | null;
+  score?: number | null;
+  explanation?: string | null;
+};
+
+/**
+ * Build and validate annotation result fields
+ */
+function buildAnnotationResult(
+  annotation: Pick<
+    SpanAnnotation | DocumentAnnotation,
+    "label" | "score" | "explanation"
+  >,
+  annotationType: "span" | "document"
+): AnnotationResult {
+  const result: AnnotationResult = {};
+
+  // Build result with trimming for string fields
+  if (annotation.label !== undefined) {
+    result.label = annotation.label.trim() || null;
+  }
+  if (annotation.score !== undefined) {
+    result.score = annotation.score;
+  }
+  if (annotation.explanation !== undefined) {
+    result.explanation = annotation.explanation.trim() || null;
+  }
+
+  // Validate that at least one result field is provided
+  const hasValidResult =
+    result.label || result.score !== undefined || result.explanation;
+  if (!hasValidResult) {
+    throw new Error(
+      `At least one of label, score, or explanation must be provided for ${annotationType} annotation`
+    );
+  }
+
+  return result;
+}
+
 /**
  * Convert a SpanAnnotation to the API format
  */
 export function toSpanAnnotationData(
   annotation: SpanAnnotation
 ): SpanAnnotationData {
+  const result = buildAnnotationResult(annotation, "span");
+
+  return {
+    span_id: annotation.spanId.trim(),
+    name: annotation.name.trim(),
+    annotator_kind: annotation.annotatorKind ?? "HUMAN",
+    result,
+    metadata: annotation.metadata ?? null,
+    identifier: annotation.identifier?.trim() ?? "",
+  };
+}
+
+/**
+ * Convert a DocumentAnnotation to the API format
+ */
+export function toDocumentAnnotationData(
+  annotation: DocumentAnnotation
+): SpanDocumentAnnotationData {
+  const result = buildAnnotationResult(annotation, "document");
+
   return {
-    span_id: annotation.spanId,
-    name: annotation.name,
+    span_id: annotation.spanId.trim(),
+    document_position: annotation.documentPosition,
+    name: annotation.name.trim(),
     annotator_kind: annotation.annotatorKind ?? "HUMAN",
-    result: {
-      label: annotation.label ?? null,
-      score: annotation.score ?? null,
-      explanation: null,
-    },
+    result,
     metadata: annotation.metadata ?? null,
-    identifier: annotation.identifier ?? "",
   };
 }