@arizeai/phoenix-client 6.5.3 → 6.5.5

package/docs/overview.mdx

@@ -0,0 +1,176 @@
+---
+title: "Overview"
+description: "Typed TypeScript client for Phoenix platform APIs"
+---
+
+`@arizeai/phoenix-client` is the typed TypeScript client for Phoenix platform APIs. It ships a small root REST client plus focused module entrypoints for prompts, datasets, experiments, spans, sessions, and traces.
+
+## Install
+
+```bash
+npm install @arizeai/phoenix-client
+```
+
+## Minimal Example
+
+```ts
+import { createClient } from "@arizeai/phoenix-client";
+import { listDatasets } from "@arizeai/phoenix-client/datasets";
+
+const client = createClient();
+const datasets = await listDatasets({ client });
+```
+
+## Docs And Source In `node_modules`
+
+After install, a coding agent can inspect the installed package directly:
+
+```text
+node_modules/@arizeai/phoenix-client/docs/
+node_modules/@arizeai/phoenix-client/src/
+```
+
+That gives the agent version-matched docs plus the exact implementation and generated API types that shipped with your project.
+
+## Module Map
+
+| Import | Purpose |
+|--------|---------|
+| `@arizeai/phoenix-client` | `createClient`, generated OpenAPI types, config helpers |
+| `@arizeai/phoenix-client/prompts` | Prompt CRUD plus `toSDK` conversion |
+| `@arizeai/phoenix-client/datasets` | Dataset creation and retrieval |
+| `@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 |
+
+## Configuration
+
+`createClient()` resolves Phoenix client options in this order: library defaults, environment variables, then explicit options. In most applications, the normal setup is to set `PHOENIX_HOST` and `PHOENIX_API_KEY` in the environment and call `createClient()` with no overrides.
+
+### Recommended Setup
+
+Use the environment-driven path unless you have a specific reason to override client options in code.
+
+```bash
+export PHOENIX_HOST=http://localhost:6006
+export PHOENIX_API_KEY=<your-api-key>
+```
+
+If you're using Phoenix Cloud, `PHOENIX_HOST` may look like `https://app.phoenix.arize.com/s/my-space`.
+
+```ts
+import { createClient } from "@arizeai/phoenix-client";
+
+const client = createClient();
+
+const datasets = await client.GET("/v1/datasets");
+```
+
+`PHOENIX_API_KEY` is converted into `Authorization: Bearer <key>` automatically. You do not need to build that header yourself unless you are explicitly overriding `headers`.
+
+### Explicit Overrides
+
+```ts
+import { createClient } from "@arizeai/phoenix-client";
+
+const client = createClient({
+  options: {
+    baseUrl: "https://phoenix.example.com",
+    headers: {
+      Authorization: `Bearer ${process.env.PHOENIX_API_KEY}`,
+    },
+  },
+});
+```
+
+Use explicit options when you want configuration to live in code or when you need to override the environment for a specific client instance.
+
+### createClient Parameters
+
+| Field | Type | Description |
+|--------|------|-------------|
+| `options` | `Partial<ClientOptions>` | Explicit options passed to the underlying `openapi-fetch` client. |
+| `getEnvironmentOptions` | `() => Partial<ClientOptions>` | Optional resolver for environment-derived options. The default implementation reads `process.env` when available. |
+
+### Resolved Phoenix Options
+
+These are the Phoenix-specific options this package resolves before creating the underlying OpenAPI client:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `baseUrl` | `string` | Base Phoenix URL. Defaults to `http://localhost:6006`, or `PHOENIX_HOST` when that environment variable is set. |
+| `headers` | `ClientOptions["headers"]` | Headers sent on every request. `PHOENIX_API_KEY` populates `Authorization` automatically. Explicit `headers` replace environment-derived headers. |
+
+### Header Override Rule
+
+If you pass `options.headers`, they replace the environment-derived header object rather than deep-merging with it. That means if you override `headers` and still want API key authentication, include `Authorization` yourself:
+
+```ts
+const client = createClient({
+  options: {
+    headers: {
+      Authorization: `Bearer ${process.env.PHOENIX_API_KEY}`,
+    },
+  },
+});
+```
+
+### Environment Variables
+
+| Variable | Maps to | Description |
+|--------|---------|-------------|
+| `PHOENIX_HOST` | `options.baseUrl` | Base Phoenix URL, for example `http://localhost:6006`. |
+| `PHOENIX_API_KEY` | `options.headers.Authorization` | Bearer token for authenticated environments. |
+| `PHOENIX_CLIENT_HEADERS` | `options.headers` | Optional JSON-encoded object of additional headers to send on every request. Most setups do not need this. |
+
+## API Client
+
+`createClient()` returns an `openapi-fetch` client that is typed against Phoenix's generated OpenAPI schema. Use this layer when you need an endpoint that does not yet have a high-level helper.
+
+```ts
+import { createClient } from "@arizeai/phoenix-client";
+
+const client = createClient();
+
+const datasets = await client.GET("/v1/datasets");
+
+const prompt = await client.GET("/v1/prompts/{prompt_identifier}/latest", {
+  params: {
+    path: {
+      prompt_identifier: "support-response",
+    },
+  },
+});
+```
+
+The root export exposes generated API types: `pathsV1`, `componentsV1`, `operationsV1`, `Types`, and `PhoenixClient`.
+
+Prefer this layer when:
+
+- you need a newly added endpoint before a helper exists
+- you want direct control over route, body, and query params
+- you are building thin wrappers around Phoenix routes in your own codebase
+
+## Where To Start
+
+- [Prompts](./prompts), [Datasets](./datasets), [Experiments](./experiments) — higher-level workflows
+- [Annotations](./annotations) — annotation concepts, then [Span](./span-annotations), [Document](./document-annotations), and [Session](./session-annotations) annotations for detailed usage
+- [Spans](./spans), [Sessions](./sessions), [Traces](./traces) — retrieval and maintenance
+
+<section className="hidden" data-agent-context="source-map" aria-label="Source map">
+  <h2>Source Map</h2>
+  <ul>
+    <li><code>src/client.ts</code></li>
+    <li><code>src/config.ts</code></li>
+    <li><code>src/__generated__/api/v1.ts</code></li>
+    <li><code>src/types/core.ts</code></li>
+    <li><code>src/prompts/</code></li>
+    <li><code>src/datasets/</code></li>
+    <li><code>src/experiments/</code></li>
+    <li><code>src/spans/</code></li>
+    <li><code>src/sessions/</code></li>
+    <li><code>src/traces/</code></li>
+    <li><code>src/types/</code></li>
+  </ul>
+</section>

package/docs/prompts.mdx

@@ -0,0 +1,73 @@
+---
+title: "Prompts"
+description: "Manage prompts with @arizeai/phoenix-client"
+---
+
+The prompts module lets you create prompt versions in Phoenix, fetch them back by selector, list prompts, and adapt prompt versions to supported provider SDKs.
+
+<section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
+  <h2>Relevant Source Files</h2>
+  <ul>
+    <li><code>src/prompts/getPrompt.ts</code> for the exact selector shape</li>
+  </ul>
+</section>
+
+## Create A Prompt
+
+```ts
+import {
+  createPrompt,
+  promptVersion,
+} from "@arizeai/phoenix-client/prompts";
+
+await createPrompt({
+  name: "support-response",
+  description: "Customer support reply prompt",
+  version: promptVersion({
+    modelProvider: "OPENAI",
+    modelName: "gpt-4o-mini",
+    template: [{ role: "user", content: "Reply to {{question}}" }],
+  }),
+});
+```
+
+## Fetch By Selector
+
+```ts
+import { getPrompt } from "@arizeai/phoenix-client/prompts";
+
+const prompt = await getPrompt({
+  prompt: { name: "support-response", tag: "production" },
+});
+```
+
+`prompt` can be selected by `{ name }`, `{ name, tag }`, or `{ versionId }`.
+
+## Convert To Another SDK
+
+```ts
+import { toSDK } from "@arizeai/phoenix-client/prompts";
+
+const promptAsAI = toSDK({
+  sdk: "ai",
+  prompt,
+  variables: { question: "Where is my order?" },
+});
+```
+
+Supported `sdk` targets:
+
+- `ai`
+- `openai`
+- `anthropic`
+
+<section className="hidden" data-agent-context="source-map" aria-label="Source map">
+  <h2>Source Map</h2>
+  <ul>
+    <li><code>src/prompts/createPrompt.ts</code></li>
+    <li><code>src/prompts/getPrompt.ts</code></li>
+    <li><code>src/prompts/listPrompts.ts</code></li>
+    <li><code>src/prompts/sdks/toSDK.ts</code></li>
+    <li><code>src/types/prompts.ts</code></li>
+  </ul>
+</section>

package/docs/session-annotations.mdx

@@ -0,0 +1,158 @@
+---
+title: "Session Annotations"
+description: "Log session-level annotations for conversation evaluation with @arizeai/phoenix-client"
+---
+
+Session annotations attach feedback to multi-turn conversations or threads. Use them for conversation-level quality signals: whether the session achieved its goal, whether a human handoff was needed, overall satisfaction scores.
+
+All functions are imported from `@arizeai/phoenix-client/sessions`. See [Annotations](./annotations) for the shared annotation model and concepts.
+
+<Note>
+  Requires **Phoenix Server &ge; 12.0.0**. The client will throw an error with the minimum required version if the server is too old.
+</Note>
+
+<section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
+  <h2>Relevant Source Files</h2>
+  <ul>
+    <li><code>src/sessions/addSessionAnnotation.ts</code> for the single-annotation API</li>
+    <li><code>src/sessions/logSessionAnnotations.ts</code> for batch logging</li>
+    <li><code>src/sessions/types.ts</code> for the <code>SessionAnnotation</code> interface</li>
+  </ul>
+</section>
+
+## Add A Single Session Annotation
+
+Mark a support session as resolved after human review:
+
+```ts
+import { addSessionAnnotation } from "@arizeai/phoenix-client/sessions";
+
+await addSessionAnnotation({
+  sessionAnnotation: {
+    sessionId: "cst_abc123",
+    name: "resolution",
+    annotatorKind: "HUMAN",
+    label: "resolved",
+    score: 1,
+    explanation: "User confirmed their issue was resolved.",
+  },
+});
+```
+
+## Batch Log Session Annotations
+
+Use `logSessionAnnotations` to annotate multiple sessions in a single request. This example scores a batch of support sessions for handoff detection:
+
+```ts
+import { logSessionAnnotations } from "@arizeai/phoenix-client/sessions";
+
+await logSessionAnnotations({
+  sessionAnnotations: [
+    {
+      sessionId: "cst_abc123",
+      name: "handoff-required",
+      annotatorKind: "CODE",
+      score: 0,
+      label: "no",
+    },
+    {
+      sessionId: "cst_def456",
+      name: "handoff-required",
+      annotatorKind: "CODE",
+      score: 1,
+      label: "yes",
+      explanation: "Sentiment dropped below threshold at turn 4.",
+    },
+  ],
+});
+```
+
+## Conversation Quality Scoring
+
+After a multi-turn conversation ends, use an LLM to evaluate overall coherence and goal completion:
+
+```ts
+import { addSessionAnnotation } from "@arizeai/phoenix-client/sessions";
+
+// evaluationResult comes from your LLM judge pipeline
+await addSessionAnnotation({
+  sessionAnnotation: {
+    sessionId: sessionId,
+    name: "conversation-quality",
+    annotatorKind: "LLM",
+    score: evaluationResult.score,
+    label: evaluationResult.score > 0.7 ? "good" : "needs-improvement",
+    explanation: evaluationResult.reasoning,
+    metadata: { model: "gpt-4o", evaluatorVersion: "v2" },
+  },
+});
+```
+
+## End-User Satisfaction (CSAT)
+
+Log customer satisfaction at the end of a chat session. Normalize the raw rating to a 0–1 scale for consistent scoring:
+
+```ts
+import { addSessionAnnotation } from "@arizeai/phoenix-client/sessions";
+
+// User submitted a 1-5 star rating at end of chat
+await addSessionAnnotation({
+  sessionAnnotation: {
+    sessionId: sessionId,
+    name: "csat",
+    annotatorKind: "HUMAN",
+    score: userRating / 5,
+    label: userRating >= 4 ? "satisfied" : "unsatisfied",
+    metadata: { rawRating: userRating, channel: "mobile-app" },
+  },
+});
+```
+
+## Idempotent Upserts With `identifier`
+
+Session annotations are unique by `(name, sessionId, identifier)`. The `identifier` field controls whether a write creates a new annotation or updates an existing one.
+
+Without `identifier`, a session can only have one annotation per name. Adding an `identifier` lets you store **multiple annotations with the same name** on the same session, each keyed by a different identifier. Re-sending the same tuple updates that specific annotation in place.
+
+```ts
+import { addSessionAnnotation } from "@arizeai/phoenix-client/sessions";
+
+await addSessionAnnotation({
+  sessionAnnotation: {
+    sessionId: sessionId,
+    name: "goal-completion",
+    annotatorKind: "LLM",
+    score: 0.85,
+    identifier: "goal-eval-v3",
+  },
+});
+// Running this again updates the existing annotation.
+// Using identifier: "goal-eval-v4" would create a second annotation.
+```
+
+## Parameter Reference
+
+### `SessionAnnotation`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `sessionId` | `string` | Yes | Session / conversation / thread identifier |
+| `name` | `string` | Yes | Annotation name (e.g. `"csat"`) |
+| `annotatorKind` | `"HUMAN" \| "LLM" \| "CODE"` | No | Defaults to `"HUMAN"` |
+| `label` | `string` | No* | Categorical label |
+| `score` | `number` | No* | Numeric score |
+| `explanation` | `string` | No* | Free-text explanation |
+| `identifier` | `string` | No | For idempotent upserts |
+| `metadata` | `Record<string, unknown>` | No | Arbitrary metadata |
+
+\*At least one of `label`, `score`, or `explanation` is required.
+
+<section className="hidden" data-agent-context="source-map" aria-label="Source map">
+  <h2>Source Map</h2>
+  <ul>
+    <li><code>src/sessions/addSessionAnnotation.ts</code></li>
+    <li><code>src/sessions/logSessionAnnotations.ts</code></li>
+    <li><code>src/sessions/types.ts</code></li>
+    <li><code>src/types/annotations.ts</code></li>
+  </ul>
+</section>

package/docs/sessions.mdx

@@ -0,0 +1,87 @@
+---
+title: "Sessions"
+description: "Work with sessions in @arizeai/phoenix-client"
+---
+
+The sessions module groups multi-turn activity under a project and supports retrieval, annotations, and cleanup.
+
+<section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
+  <h2>Relevant Source Files</h2>
+  <ul>
+    <li>
+      <code>src/sessions/listSessions.ts</code> for the exact project selector
+      shape
+    </li>
+    <li>
+      <code>src/sessions/getSessionTurns.ts</code> for how turns are derived
+      from root spans
+    </li>
+  </ul>
+</section>
+
+## List Sessions
+
+```ts
+import { listSessions } from "@arizeai/phoenix-client/sessions";
+
+const sessions = await listSessions({
+  projectName: "support-bot",
+});
+
+for (const session of sessions) {
+  console.log(session.sessionId);
+}
+```
+
+## Retrieve A Session And Its Turns
+
+```ts
+import {
+  getSession,
+  getSessionTurns,
+} from "@arizeai/phoenix-client/sessions";
+
+const session = await getSession({
+  sessionId: "cst_123",
+});
+
+const turns = await getSessionTurns({
+  sessionId: "cst_123",
+});
+```
+
+`getSession()` and `getSessionTurns()` only need `sessionId`. They do not take a `project` selector.
+
+## Annotate Sessions
+
+Session annotations are covered in depth in [Session Annotations](./session-annotations). Quick example:
+
+```ts
+import { addSessionAnnotation } from "@arizeai/phoenix-client/sessions";
+
+await addSessionAnnotation({
+  sessionAnnotation: {
+    sessionId: "cst_123",
+    name: "handoff-required",
+    annotatorKind: "CODE",
+    score: 1,
+    label: "yes",
+  },
+});
+```
+
+## Cleanup
+
+Use `deleteSession` or `deleteSessions` when you need to remove session records by identifier.
+
+<section className="hidden" data-agent-context="source-map" aria-label="Source map">
+  <h2>Source Map</h2>
+  <ul>
+    <li><code>src/sessions/listSessions.ts</code></li>
+    <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/deleteSession.ts</code></li>
+    <li><code>src/sessions/deleteSessions.ts</code></li>
+  </ul>
+</section>