@arizeai/phoenix-client 6.3.0 → 6.4.0

package/dist/src/sessions/getSessionTurns.d.ts

@@ -0,0 +1,72 @@
+import type { components } from "../__generated__/api/v1";
+import type { ClientFn } from "../types/core";
+type Span = components["schemas"]["Span"];
+/**
+ * Input or output extracted from a root span's attributes.
+ *
+ * @experimental this interface is experimental and may change in the future
+ */
+export interface SessionTurnIO {
+    /** The string value of the input or output */
+    value: string;
+    /** Optional MIME type (e.g. "text/plain", "application/json") */
+    mimeType?: string;
+}
+/**
+ * A single turn in a session, representing one trace's root span input/output.
+ *
+ * **Note:** A "turn" is derived from a trace's root span. For input/output to appear,
+ * the root span must have `input.value` and `output.value` attributes set
+ * (per OpenInference semantic conventions). This typically requires instrumentation
+ * that records these attributes on the top-level span.
+ *
+ * @experimental this interface is experimental and may change in the future
+ */
+export interface SessionTurn {
+    /** The trace ID for this turn */
+    traceId: string;
+    /** ISO 8601 timestamp of when the trace started */
+    startTime: string;
+    /** ISO 8601 timestamp of when the trace ended */
+    endTime: string;
+    /** Input extracted from the root span's attributes */
+    input?: SessionTurnIO;
+    /** Output extracted from the root span's attributes */
+    output?: SessionTurnIO;
+    /** The full root span, if found */
+    rootSpan?: Span;
+}
+/**
+ * @experimental this interface is experimental and may change in the future
+ */
+export interface GetSessionTurnsParams extends ClientFn {
+    /** The session identifier: either a GlobalID or user-provided session_id string. */
+    sessionId: string;
+}
+/**
+ * Get the turns (root span I/O) for a session.
+ *
+ * Returns input/output extracted from root spans for each trace, along with
+ * the full root span. Turns are ordered by trace start_time.
+ *
+ * **Note:** A "turn" is derived from a trace's root span. For input/output to appear,
+ * the root span must have `input.value` and `output.value` attributes set
+ * (per OpenInference semantic conventions). This typically requires instrumentation
+ * that records these attributes on the top-level span.
+ *
+ * @experimental this function is experimental and may change in the future
+ *
+ * @example
+ * ```ts
+ * import { getSessionTurns } from "@arizeai/phoenix-client/sessions";
+ *
+ * const turns = await getSessionTurns({ sessionId: "my-session" });
+ * for (const turn of turns) {
+ *   console.log(`[${turn.startTime}] Input: ${turn.input?.value}`);
+ *   console.log(`[${turn.startTime}] Output: ${turn.output?.value}`);
+ * }
+ * ```
+ */
+export declare function getSessionTurns({ client: _client, sessionId, }: GetSessionTurnsParams): Promise<SessionTurn[]>;
+export {};
+//# sourceMappingURL=getSessionTurns.d.ts.map

package/dist/src/sessions/getSessionTurns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getSessionTurns.d.ts","sourceRoot":"","sources":["../../../src/sessions/getSessionTurns.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAG1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAI9C,KAAK,IAAI,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAI1C;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,uDAAuD;IACvD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,QAAQ;IACrD,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CAAC,EACpC,MAAM,EAAE,OAAO,EACf,SAAS,GACV,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAiChD"}

package/dist/src/sessions/getSessionTurns.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSessionTurns = getSessionTurns;
+const openinference_semantic_conventions_1 = require("@arizeai/openinference-semantic-conventions");
+const client_1 = require("../client");
+const getSpans_1 = require("../spans/getSpans");
+const getSession_1 = require("./getSession");
+const MAX_TRACE_IDS_PER_BATCH = 50;
+/**
+ * Get the turns (root span I/O) for a session.
+ *
+ * Returns input/output extracted from root spans for each trace, along with
+ * the full root span. Turns are ordered by trace start_time.
+ *
+ * **Note:** A "turn" is derived from a trace's root span. For input/output to appear,
+ * the root span must have `input.value` and `output.value` attributes set
+ * (per OpenInference semantic conventions). This typically requires instrumentation
+ * that records these attributes on the top-level span.
+ *
+ * @experimental this function is experimental and may change in the future
+ *
+ * @example
+ * ```ts
+ * import { getSessionTurns } from "@arizeai/phoenix-client/sessions";
+ *
+ * const turns = await getSessionTurns({ sessionId: "my-session" });
+ * for (const turn of turns) {
+ *   console.log(`[${turn.startTime}] Input: ${turn.input?.value}`);
+ *   console.log(`[${turn.startTime}] Output: ${turn.output?.value}`);
+ * }
+ * ```
+ */
+async function getSessionTurns({ client: _client, sessionId, }) {
+    const client = _client !== null && _client !== void 0 ? _client : (0, client_1.createClient)();
+    const session = await (0, getSession_1.getSession)({ client, sessionId });
+    const traces = session.traces;
+    if (traces.length === 0) {
+        return [];
+    }
+    const projectId = session.projectId;
+    const traceInfo = new Map(traces.map((t) => [t.traceId, t]));
+    const allTraceIds = [...traceInfo.keys()];
+    // Fetch root spans in batches
+    const rootSpansByTrace = new Map();
+    for (let i = 0; i < allTraceIds.length; i += MAX_TRACE_IDS_PER_BATCH) {
+        const traceIdBatch = allTraceIds.slice(i, i + MAX_TRACE_IDS_PER_BATCH);
+        const spans = await getAllRootSpansForBatch({
+            client,
+            projectId,
+            traceIdBatch,
+        });
+        for (const span of spans) {
+            const traceId = span.context.trace_id;
+            if (!rootSpansByTrace.has(traceId)) {
+                rootSpansByTrace.set(traceId, span);
+            }
+        }
+    }
+    return buildSessionTurns({ allTraceIds, traceInfo, rootSpansByTrace });
+}
+/**
+ * Fetch all root spans for a batch of trace IDs, handling pagination.
+ */
+async function getAllRootSpansForBatch({ client, projectId, traceIdBatch, }) {
+    const allSpans = [];
+    let cursor = null;
+    do {
+        const result = await (0, getSpans_1.getSpans)(Object.assign({ client, project: { projectId }, traceIds: traceIdBatch, parentId: null, limit: traceIdBatch.length }, (cursor ? { cursor } : {})));
+        allSpans.push(...result.spans);
+        cursor = result.nextCursor;
+    } while (cursor != null);
+    return allSpans;
+}
+/**
+ * Extract a SessionTurnIO from span attributes for a given prefix.
+ */
+function extractIO({ attrs, valueKey, mimeTypeKey, }) {
+    const value = attrs[valueKey];
+    if (value == null)
+        return undefined;
+    const io = { value: String(value) };
+    const mimeType = attrs[mimeTypeKey];
+    if (mimeType != null) {
+        io.mimeType = String(mimeType);
+    }
+    return io;
+}
+/**
+ * Build session turns from trace info and root spans, ordered by start_time.
+ */
+function buildSessionTurns({ allTraceIds, traceInfo, rootSpansByTrace, }) {
+    var _a;
+    const turns = [];
+    for (const traceId of allTraceIds) {
+        const info = traceInfo.get(traceId);
+        if (!info)
+            continue;
+        const turn = {
+            traceId,
+            startTime: info.startTime,
+            endTime: info.endTime,
+        };
+        const rootSpan = rootSpansByTrace.get(traceId);
+        if (rootSpan) {
+            turn.rootSpan = rootSpan;
+            const attrs = (_a = rootSpan.attributes) !== null && _a !== void 0 ? _a : {};
+            turn.input = extractIO({
+                attrs,
+                valueKey: openinference_semantic_conventions_1.SemanticConventions.INPUT_VALUE,
+                mimeTypeKey: openinference_semantic_conventions_1.SemanticConventions.INPUT_MIME_TYPE,
+            });
+            turn.output = extractIO({
+                attrs,
+                valueKey: openinference_semantic_conventions_1.SemanticConventions.OUTPUT_VALUE,
+                mimeTypeKey: openinference_semantic_conventions_1.SemanticConventions.OUTPUT_MIME_TYPE,
+            });
+        }
+        turns.push(turn);
+    }
+    turns.sort((a, b) => a.startTime.localeCompare(b.startTime));
+    return turns;
+}
+//# sourceMappingURL=getSessionTurns.js.map

package/dist/src/sessions/getSessionTurns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getSessionTurns.js","sourceRoot":"","sources":["../../../src/sessions/getSessionTurns.ts"],"names":[],"mappings":"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"}

package/dist/src/sessions/index.d.ts

@@ -2,6 +2,7 @@ export * from "./addSessionAnnotation";
 export * from "./deleteSession";
 export * from "./deleteSessions";
 export * from "./getSession";
+export * from "./getSessionTurns";
 export * from "./listSessions";
 export * from "./logSessionAnnotations";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/sessions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sessions/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sessions/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC"}

package/dist/src/sessions/index.js

@@ -18,6 +18,7 @@ __exportStar(require("./addSessionAnnotation"), exports);
 __exportStar(require("./deleteSession"), exports);
 __exportStar(require("./deleteSessions"), exports);
 __exportStar(require("./getSession"), exports);
+__exportStar(require("./getSessionTurns"), exports);
 __exportStar(require("./listSessions"), exports);
 __exportStar(require("./logSessionAnnotations"), exports);
 //# sourceMappingURL=index.js.map

package/dist/src/sessions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sessions/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,kDAAgC;AAChC,mDAAiC;AACjC,+CAA6B;AAC7B,iDAA+B;AAC/B,0DAAwC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sessions/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,kDAAgC;AAChC,mDAAiC;AACjC,+CAA6B;AAC7B,oDAAkC;AAClC,iDAA+B;AAC/B,0DAAwC"}