@arizeai/phoenix-client 6.9.1 → 6.9.3

package/docs/annotations.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Annotations"
-description: "Attach structured feedback to spans, documents, and sessions with @arizeai/phoenix-client"
+description: "Attach structured feedback to spans, documents, traces, and sessions with @arizeai/phoenix-client"
 ---
 
 Annotations are structured feedback records — labels, scores, and explanations — attached to observability artifacts in Phoenix. They are the primary mechanism for recording quality signals, whether those signals come from end-users, LLM judges, or programmatic checks.
@@ -11,6 +11,7 @@ Annotations are structured feedback records — labels, scores, and explanations
     <li><code>src/types/annotations.ts</code> for the shared <code>Annotation</code> base interface</li>
     <li><code>src/spans/types.ts</code> for <code>SpanAnnotation</code> and <code>DocumentAnnotation</code></li>
     <li><code>src/sessions/types.ts</code> for <code>SessionAnnotation</code></li>
+    <li><code>src/traces/types.ts</code> for <code>TraceAnnotation</code></li>
   </ul>
 </section>
 
@@ -26,11 +27,12 @@ Once attached, annotations appear in the Phoenix UI alongside traces and can be
 
 ## Annotation Targets
 
-Phoenix supports three annotation targets, each focused on a different level of your application:
+Phoenix supports four annotation targets, each focused on a different level of your application:
 
 - **[Span Annotations](./span-annotations)** — Feedback on individual traced operations: an LLM call, a tool invocation, a retrieval step. The most common annotation target.
 - **[Document Annotations](./document-annotations)** — Feedback on specific retrieved documents within a retriever span, indexed by position. Essential for evaluating RAG pipeline quality.
 - **[Session Annotations](./session-annotations)** — Feedback on multi-turn conversations or threads as a whole. Use for conversation-level quality signals like resolution rate or customer satisfaction.
+- **[Trace Annotations](./traces#annotate-a-single-trace)** — Feedback attached to a single trace, identified by its trace ID. Use `addTraceAnnotation` or `logTraceAnnotations` from `@arizeai/phoenix-client/traces` when scoring an end-to-end request. Reach for session annotations instead when scoring a multi-turn conversation as a whole.
 
 ## Annotator Kinds
 
@@ -59,7 +61,7 @@ interface Annotation {
 
 At least one of `label`, `score`, or `explanation` must be provided.
 
-Each target adds its own identifier field — `spanId` for spans, `spanId` + `documentPosition` for documents, and `sessionId` for sessions.
+Each target adds its own identifier field — `spanId` for spans, `spanId` + `documentPosition` for documents, `traceId` for traces, and `sessionId` for sessions.
 
 ## Sync vs. Async
 
@@ -79,5 +81,7 @@ All annotation write functions accept an optional `sync` parameter:
     <li><code>src/spans/getSpanAnnotations.ts</code></li>
     <li><code>src/sessions/addSessionAnnotation.ts</code></li>
     <li><code>src/sessions/logSessionAnnotations.ts</code></li>
+    <li><code>src/traces/addTraceAnnotation.ts</code></li>
+    <li><code>src/traces/logTraceAnnotations.ts</code></li>
   </ul>
 </section>

package/docs/overview.mdx

@@ -42,7 +42,7 @@ That gives the agent version-matched docs plus the exact implementation and gene
 | `@arizeai/phoenix-client/experiments` | Experiment execution and lifecycle |
 | `@arizeai/phoenix-client/spans` | Span search, notes, and span/document annotations |
 | `@arizeai/phoenix-client/sessions` | Session listing, retrieval, and session annotations |
-| `@arizeai/phoenix-client/traces` | Project trace retrieval |
+| `@arizeai/phoenix-client/traces` | Project trace retrieval and trace annotations |
 
 ## Configuration
 

package/docs/sessions.mdx

@@ -70,6 +70,25 @@ await addSessionAnnotation({
 });
 ```
 
+## Add a Note to a Session
+
+Use `addSessionNote` to append a free-text note to a session. Multiple notes can be added to the same session; each receives a unique UUIDv4 identifier.
+
+Requires Phoenix server `>= 14.17.0`.
+
+```ts
+import { addSessionNote } from "@arizeai/phoenix-client/sessions";
+
+const result = await addSessionNote({
+  sessionNote: {
+    sessionId: "cst_123",
+    note: "Needs review — retrieval returned empty results on turn 3",
+  },
+});
+
+console.log(result.id); // UUIDv4 for the created note
+```
+
 ## Cleanup
 
 Use `deleteSession` or `deleteSessions` when you need to remove session records by identifier.
@@ -81,6 +100,7 @@ Use `deleteSession` or `deleteSessions` when you need to remove session records
     <li><code>src/sessions/getSession.ts</code></li>
     <li><code>src/sessions/getSessionTurns.ts</code></li>
     <li><code>src/sessions/addSessionAnnotation.ts</code></li>
+    <li><code>src/sessions/addSessionNote.ts</code></li>
     <li><code>src/sessions/deleteSession.ts</code></li>
     <li><code>src/sessions/deleteSessions.ts</code></li>
   </ul>

package/docs/traces.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Traces"
-description: "Retrieve traces with @arizeai/phoenix-client"
+description: "Retrieve traces and annotate them with @arizeai/phoenix-client"
 ---
 
-Use `getTraces` when you want trace-centric pagination by project, optional inline spans, or filtering by session.
+The traces module provides trace retrieval and trace-level annotation functions.
 
 <section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
   <h2>Relevant Source Files</h2>
@@ -12,10 +12,21 @@ Use `getTraces` when you want trace-centric pagination by project, optional inli
       <code>src/traces/getTraces.ts</code> for the exact query shape and server
       requirement
     </li>
+    <li>
+      <code>src/traces/addTraceAnnotation.ts</code> for single annotation writes
+    </li>
+    <li>
+      <code>src/traces/logTraceAnnotations.ts</code> for batched annotation writes
+    </li>
+    <li>
+      <code>src/traces/types.ts</code> for the <code>TraceAnnotation</code> type
+    </li>
   </ul>
 </section>
 
-## Example
+## Retrieve Traces
+
+Use `getTraces` when you want trace-centric pagination by project, optional inline spans, or filtering by session.
 
 ```ts
 import { getTraces } from "@arizeai/phoenix-client/traces";
@@ -35,7 +46,7 @@ for (const trace of result.traces) {
 console.log(result.nextCursor);
 ```
 
-## Supported Filters
+### Supported Filters
 
 - `project`
 - `startTime`
@@ -47,17 +58,77 @@ console.log(result.nextCursor);
 - `includeSpans`
 - `sessionId`
 
-## Notes
+### Notes
 
 - `getTraces` requires a Phoenix server that supports project trace listing
 - Use the returned `nextCursor` to continue pagination
 - Set `includeSpans` when you need a trace-centric fetch that also contains span details
 - `project` accepts `{ project }`, `{ projectId }`, or `{ projectName }`
 
+## Annotate a Single Trace
+
+Use `addTraceAnnotation` to attach a label, score, or explanation to one trace. If you supply an `identifier`, Phoenix upserts the annotation when an annotation with that identifier already exists.
+
+```ts
+import { addTraceAnnotation } from "@arizeai/phoenix-client/traces";
+
+const result = await addTraceAnnotation({
+  traceAnnotation: {
+    traceId: "abc123",
+    name: "correctness",
+    label: "correct",
+    score: 1.0,
+    annotatorKind: "HUMAN",
+  },
+});
+
+// result is { id: string } when sync: true, or null when sync: false (default)
+```
+
+Set `sync: true` to receive the annotation ID immediately; omit it (or pass `false`) for higher-throughput async writes.
+
+### TraceAnnotation Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `traceId` | `string` | Yes | OpenTelemetry Trace ID (hex, no `0x` prefix) |
+| `name` | `string` | Yes | What is being measured (e.g. `"groundedness"`). The name `"note"` is reserved — use `addTraceNote` instead. |
+| `annotatorKind` | `"HUMAN" \| "LLM" \| "CODE"` | No | Defaults to `"HUMAN"` |
+| `label` | `string` | At least one of label/score/explanation | Categorical result (e.g. `"correct"`) |
+| `score` | `number` | At least one of label/score/explanation | Numeric result (e.g. `0.95`) |
+| `explanation` | `string` | At least one of label/score/explanation | Free-text justification |
+| `identifier` | `string` | No | Stable ID for idempotent upserts |
+| `metadata` | `Record<string, unknown>` | No | Arbitrary context |
+
+## Annotate Multiple Traces
+
+Use `logTraceAnnotations` to batch-write annotations across many traces in a single request.
+
+```ts
+import { logTraceAnnotations } from "@arizeai/phoenix-client/traces";
+
+const results = await logTraceAnnotations({
+  traceAnnotations: [
+    { traceId: "abc123", name: "faithfulness", score: 0.9, annotatorKind: "LLM" },
+    { traceId: "def456", name: "faithfulness", score: 0.7, annotatorKind: "LLM" },
+  ],
+  sync: true,
+});
+
+for (const r of results) {
+  console.log(r.id);
+}
+```
+
+`logTraceAnnotations` sends all annotations in a single POST and returns an array of `{ id: string }` objects (or an empty array when `sync: false`).
+
 <section className="hidden" data-agent-context="source-map" aria-label="Source map">
   <h2>Source Map</h2>
   <ul>
     <li><code>src/traces/getTraces.ts</code></li>
+    <li><code>src/traces/addTraceAnnotation.ts</code></li>
+    <li><code>src/traces/logTraceAnnotations.ts</code></li>
+    <li><code>src/traces/types.ts</code></li>
     <li><code>src/types/projects.ts</code></li>
   </ul>
 </section>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "6.9.1",
+  "version": "6.9.3",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -76,11 +76,11 @@
     "@arizeai/openinference-semantic-conventions": "^2.1.7",
     "@arizeai/openinference-vercel": "^2.7.0",
     "async": "^3.2.6",
-    "openapi-fetch": "^0.12.5",
+    "openapi-fetch": "^0.17.0",
     "tiny-invariant": "^1.3.3",
     "zod": "^4.0.14",
     "@arizeai/phoenix-config": "0.1.4",
-    "@arizeai/phoenix-otel": "1.0.1"
+    "@arizeai/phoenix-otel": "1.0.2"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^3.0.29",