@introspection-sdk/introspection-node 0.4.0

package/src/converters/ai-sdk.ts

@@ -0,0 +1,298 @@
+/**
+ * Converter for AI SDK event data → Gen AI semantic conventions.
+ *
+ * Converts typed event objects (messages, tool definitions, step results)
+ * from the AI SDK's TelemetryIntegration callbacks into the standardized
+ * gen_ai format used by the Introspection backend.
+ *
+ * Used by {@link IntrospectionAISDKIntegration}.
+ */
+
+import type {
+  InputMessage,
+  OutputMessage,
+  SystemInstruction,
+  ToolDefinition,
+  MessagePart,
+} from "../types/genai.js";
+
+// ---------------------------------------------------------------------------
+// Local types — minimal shapes matching AI SDK data structures.
+// Defined locally to avoid requiring `ai` as a compile-time dependency.
+// ---------------------------------------------------------------------------
+
+/** A content part within an AI SDK message. */
+interface ContentPart {
+  type: string;
+  text?: string;
+  toolCallId?: string;
+  toolName?: string;
+  args?: unknown;
+  input?: unknown;
+  result?: unknown;
+  output?: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Public conversion functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert AI SDK messages (ModelMessage[]) to gen_ai InputMessage[].
+ * System messages are excluded — they're handled separately via
+ * {@link extractSystemInstructions}.
+ *
+ * @param messages - Array of AI SDK ModelMessage objects.
+ * @returns Array of gen_ai InputMessage objects (without system messages).
+ */
+export function convertMessagesToInputMessages(
+  messages: readonly unknown[],
+): InputMessage[] {
+  const result: InputMessage[] = [];
+  for (const msg of messages) {
+    const m = msg as { role?: string; content?: unknown };
+    if (!m || !m.role || m.role === "system") continue;
+    result.push(convertOneMessage(m));
+  }
+  return result;
+}
+
+/**
+ * Extract gen_ai system instructions from AI SDK's system field and messages.
+ *
+ * The AI SDK provides system prompts in two places:
+ * - The `system` parameter (string, SystemModelMessage, or array)
+ * - Messages with role "system"
+ *
+ * @param system - The AI SDK `system` field.
+ * @param messages - The messages array (may contain system-role messages).
+ * @returns System instructions in gen_ai format, or undefined if none.
+ */
+export function extractSystemInstructions(
+  system: unknown,
+  messages: readonly unknown[],
+): SystemInstruction[] | undefined {
+  const instructions: SystemInstruction[] = [];
+
+  // From the `system` field
+  if (typeof system === "string" && system) {
+    instructions.push({ type: "text", content: system });
+  } else if (system && typeof system === "object") {
+    if (Array.isArray(system)) {
+      for (const s of system) {
+        const text = extractTextFromSystemMessage(s);
+        if (text) instructions.push({ type: "text", content: text });
+      }
+    } else {
+      const text = extractTextFromSystemMessage(system);
+      if (text) instructions.push({ type: "text", content: text });
+    }
+  }
+
+  // From system-role messages
+  for (const msg of messages) {
+    const m = msg as { role?: string; content?: unknown };
+    if (m?.role === "system") {
+      const content = m.content;
+      if (typeof content === "string") {
+        instructions.push({ type: "text", content });
+      } else if (Array.isArray(content)) {
+        const text = (content as ContentPart[])
+          .filter((p) => p.type === "text")
+          .map((p) => p.text || "")
+          .join("");
+        if (text) instructions.push({ type: "text", content: text });
+      }
+    }
+  }
+
+  return instructions.length > 0 ? instructions : undefined;
+}
+
+/**
+ * Build gen_ai output messages from AI SDK step result data.
+ *
+ * Combines text, reasoning, and tool call outputs into a single assistant
+ * OutputMessage, mirroring the order used by vercel.ts (reasoning → text → tool calls).
+ *
+ * @param options - Step result fields.
+ * @returns Array of gen_ai OutputMessage objects.
+ */
+export function buildOutputMessages(options: {
+  text?: string;
+  reasoningText?: string;
+  reasoning?: readonly { text?: string }[];
+  toolCalls?: readonly {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+  }[];
+  finishReason?: string;
+}): OutputMessage[] {
+  const parts: MessagePart[] = [];
+
+  // Reasoning first (mirrors vercel.ts order)
+  if (options.reasoningText) {
+    parts.push({ type: "thinking", content: options.reasoningText });
+  } else if (options.reasoning?.length) {
+    for (const r of options.reasoning) {
+      if (r.text) parts.push({ type: "thinking", content: r.text });
+    }
+  }
+
+  // Text content
+  if (options.text) {
+    parts.push({ type: "text", content: options.text });
+  }
+
+  // Tool calls
+  if (options.toolCalls?.length) {
+    for (const tc of options.toolCalls) {
+      parts.push({
+        type: "tool_call",
+        name: tc.toolName,
+        id: tc.toolCallId,
+        arguments:
+          typeof tc.input === "string" ? tc.input : JSON.stringify(tc.input),
+      });
+    }
+  }
+
+  if (parts.length === 0) return [];
+
+  return [
+    {
+      role: "assistant",
+      parts,
+      finish_reason: options.finishReason,
+    },
+  ];
+}
+
+/**
+ * Convert AI SDK ToolSet to gen_ai ToolDefinition[].
+ *
+ * The AI SDK represents tools as `Record<string, Tool>` where each Tool has
+ * description and parameters (usually a Zod schema). We extract what we can
+ * without importing Zod.
+ *
+ * @param tools - AI SDK ToolSet (Record<string, Tool>).
+ * @returns Array of gen_ai ToolDefinition objects, or undefined if no tools.
+ */
+export function convertToolsToToolDefinitions(
+  tools: unknown,
+): ToolDefinition[] | undefined {
+  if (!tools || typeof tools !== "object") return undefined;
+
+  const defs: ToolDefinition[] = [];
+  for (const [name, tool] of Object.entries(tools as Record<string, unknown>)) {
+    if (!tool || typeof tool !== "object") continue;
+    const t = tool as Record<string, unknown>;
+    defs.push({
+      name,
+      description:
+        typeof t.description === "string" ? t.description : undefined,
+      parameters: extractToolParameters(t.parameters),
+    });
+  }
+
+  return defs.length > 0 ? defs : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function convertOneMessage(msg: {
+  role?: string;
+  content?: unknown;
+}): InputMessage {
+  const role = (msg.role || "user") as InputMessage["role"];
+  const content = msg.content;
+  const parts: MessagePart[] = [];
+
+  if (typeof content === "string") {
+    parts.push({ type: "text", content });
+  } else if (Array.isArray(content)) {
+    for (const part of content as ContentPart[]) {
+      const converted = convertContentPart(part);
+      if (converted) parts.push(converted);
+    }
+  }
+
+  return { role, parts };
+}
+
+function convertContentPart(part: ContentPart): MessagePart | null {
+  switch (part.type) {
+    case "text":
+      return { type: "text", content: part.text || "" };
+
+    case "tool-call": {
+      const args = part.args ?? part.input;
+      return {
+        type: "tool_call",
+        name: part.toolName || "",
+        id: part.toolCallId || "",
+        arguments: typeof args === "string" ? args : JSON.stringify(args ?? {}),
+      };
+    }
+
+    case "tool-result": {
+      const rawResult = part.result ?? part.output;
+      let response: string;
+      if (typeof rawResult === "string") {
+        response = rawResult;
+      } else if (
+        rawResult &&
+        typeof rawResult === "object" &&
+        "value" in (rawResult as Record<string, unknown>)
+      ) {
+        response = JSON.stringify((rawResult as Record<string, unknown>).value);
+      } else {
+        response = JSON.stringify(rawResult);
+      }
+      return {
+        type: "tool_call_response",
+        id: part.toolCallId || "",
+        response,
+      };
+    }
+
+    case "reasoning":
+      return { type: "thinking", content: part.text || "" };
+
+    default:
+      // Unknown part type — serialize as text fallback
+      return { type: "text", content: JSON.stringify(part) };
+  }
+}
+
+function extractTextFromSystemMessage(msg: unknown): string | null {
+  if (typeof msg === "string") return msg;
+  if (msg && typeof msg === "object") {
+    const m = msg as Record<string, unknown>;
+    if (typeof m.content === "string") return m.content;
+    if (typeof m.text === "string") return m.text;
+  }
+  return null;
+}
+
+function extractToolParameters(
+  parameters: unknown,
+): Record<string, unknown> | undefined {
+  if (!parameters || typeof parameters !== "object") return undefined;
+  const p = parameters as Record<string, unknown>;
+
+  // jsonSchema() wrapper — has a jsonSchema property
+  if (p.jsonSchema && typeof p.jsonSchema === "object") {
+    return p.jsonSchema as Record<string, unknown>;
+  }
+
+  // Plain JSON Schema object (has 'type' and 'properties')
+  if (p.type === "object" && p.properties) {
+    return p as Record<string, unknown>;
+  }
+
+  return undefined;
+}

package/src/converters/claude.ts

@@ -0,0 +1,334 @@
+/**
+ * Claude Agent SDK format conversion functions for OTel Gen AI Semantic Conventions.
+ *
+ * These functions convert Claude Agent SDK message formats to the standardized
+ * OTel Gen AI Semantic Convention format for gen_ai.input.messages and gen_ai.output.messages.
+ */
+
+import type {
+  InputMessage,
+  OutputMessage,
+  MessagePart,
+  ReasoningPart,
+  GenAiAttributes,
+  ToolDefinition,
+} from "../types/genai.js";
+import { toAttributes } from "../types/genai.js";
+
+/** A plain-text content block from the Claude API. */
+export interface ClaudeTextBlock {
+  type: "text";
+  text: string;
+}
+
+/** A tool-use (function call) content block from the Claude API. */
+export interface ClaudeToolUseBlock {
+  type: "tool_use";
+  id: string;
+  name: string;
+  input: unknown;
+}
+
+/** A tool-result content block returned to the Claude API. */
+export interface ClaudeToolResultBlock {
+  type: "tool_result";
+  tool_use_id: string;
+  content: string | unknown[];
+  is_error?: boolean;
+}
+
+/** Union of all Claude API content block shapes. */
+export type ClaudeContentBlock =
+  | ClaudeTextBlock
+  | ClaudeToolUseBlock
+  | ClaudeToolResultBlock
+  | { type: string; [key: string]: unknown };
+
+/** A single message in a Claude multi-turn conversation. */
+export interface ClaudeMessage {
+  role: "user" | "assistant";
+  content: string | ClaudeContentBlock[];
+}
+
+/** Subset of the Claude Messages API response used for conversion. */
+export interface ClaudeResponse {
+  id?: string;
+  model?: string;
+  content?: ClaudeContentBlock[];
+  stop_reason?: string;
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+  };
+}
+
+/**
+ * Convert a user prompt string to OTel Gen AI input message format.
+ *
+ * @param prompt - The user's text prompt.
+ * @returns An array containing a single user-role {@link InputMessage}.
+ *
+ * @example
+ * ```ts
+ * const msgs = convertClaudePromptToInputMessages("Hello, Claude!");
+ * // [{ role: "user", parts: [{ type: "text", content: "Hello, Claude!" }] }]
+ * ```
+ */
+export function convertClaudePromptToInputMessages(
+  prompt: string,
+): InputMessage[] {
+  return [
+    {
+      role: "user",
+      parts: [{ type: "text", content: prompt }],
+    },
+  ];
+}
+
+/**
+ * Convert Claude content blocks to message parts.
+ */
+function convertContentBlocksToParts(
+  content: string | ClaudeContentBlock[],
+): MessagePart[] {
+  if (typeof content === "string") {
+    return [{ type: "text", content }];
+  }
+
+  const parts: MessagePart[] = [];
+
+  for (const block of content) {
+    if (block.type === "text" && "text" in block) {
+      parts.push({ type: "text", content: block.text as string });
+    } else if (block.type === "tool_use" && "name" in block) {
+      parts.push({
+        type: "tool_call",
+        id: block.id as string,
+        name: block.name as string,
+        arguments: block.input,
+      });
+    } else if (block.type === "tool_result" && "tool_use_id" in block) {
+      let response: unknown = block.content;
+      if (typeof response === "string") {
+        // Keep as string
+      } else if (Array.isArray(response)) {
+        // Extract text from content array
+        response = response
+          .filter(
+            (item): item is { type: "text"; text: string } =>
+              typeof item === "object" &&
+              item !== null &&
+              (item as Record<string, unknown>).type === "text",
+          )
+          .map((item) => item.text)
+          .join("");
+      }
+      parts.push({
+        type: "tool_call_response",
+        id: block.tool_use_id as string,
+        response,
+      });
+    } else if (block.type === "thinking" && "thinking" in block) {
+      const thinking = block.thinking as string | undefined;
+      const signature = (block as Record<string, unknown>).signature as
+        | string
+        | undefined;
+      const thinkingPart: ReasoningPart = {
+        type: "thinking",
+        content: thinking || undefined,
+        signature: signature || undefined,
+        provider_name: "anthropic",
+      };
+      parts.push(thinkingPart);
+    }
+  }
+
+  return parts;
+}
+
+/**
+ * Convert Claude assistant response content to OTel Gen AI output message format.
+ *
+ * @param content - A plain string or array of {@link ClaudeContentBlock} objects.
+ * @param stopReason - Optional stop/finish reason (e.g. `"end_turn"`).
+ * @returns An array containing a single assistant-role {@link OutputMessage}.
+ *
+ * @example
+ * ```ts
+ * const msgs = convertClaudeResponseToOutputMessages(response.content, response.stop_reason);
+ * span.setAttribute("gen_ai.output.messages", JSON.stringify(msgs));
+ * ```
+ */
+export function convertClaudeResponseToOutputMessages(
+  content: string | ClaudeContentBlock[],
+  stopReason?: string,
+): OutputMessage[] {
+  const parts = convertContentBlocksToParts(content);
+
+  const message: OutputMessage = {
+    role: "assistant",
+    parts,
+  };
+
+  if (stopReason) {
+    message.finish_reason = stopReason;
+  }
+
+  return [message];
+}
+
+/**
+ * Convert a Claude multi-turn conversation to OTel Gen AI input message format.
+ *
+ * @param messages - Array of {@link ClaudeMessage} objects (user + assistant turns).
+ * @returns An array of {@link InputMessage} objects preserving turn order.
+ *
+ * @example
+ * ```ts
+ * const msgs = convertClaudeMessagesToInputMessages(conversation);
+ * span.setAttribute("gen_ai.input.messages", JSON.stringify(msgs));
+ * ```
+ */
+export function convertClaudeMessagesToInputMessages(
+  messages: ClaudeMessage[],
+): InputMessage[] {
+  return messages.map((msg) => ({
+    role: msg.role as InputMessage["role"],
+    parts: convertContentBlocksToParts(msg.content),
+  }));
+}
+
+/**
+ * Aggregated session data from the Claude Agent SDK, used as input for
+ * the {@link convertClaudeSessionToGenAI} and
+ * {@link convertClaudeSessionToOtelAttributes} converters.
+ */
+export interface ClaudeSessionData {
+  /** Input prompt */
+  inputPrompt?: string;
+  /** Response content (text extracted from assistant messages) */
+  responseContent?: string;
+  /** Full response content blocks (if available) */
+  responseBlocks?: ClaudeContentBlock[];
+  /** Model name */
+  model?: string;
+  /** Session ID */
+  sessionId?: string;
+  /** Input token count */
+  inputTokens?: number;
+  /** Output token count */
+  outputTokens?: number;
+  /** Cost in USD */
+  costUsd?: number;
+  /** Stop/finish reason */
+  stopReason?: string;
+  /** Response ID */
+  responseId?: string;
+  /** Tool names from init message */
+  toolNames?: string[];
+  /** System instructions / system prompt */
+  systemInstructions?: string;
+}
+
+/**
+ * Convert Claude session data to camelCase {@link GenAiAttributes}.
+ *
+ * @param data - Aggregated {@link ClaudeSessionData} for one session.
+ * @returns A {@link GenAiAttributes} object ready for {@link toAttributes}.
+ *
+ * @example
+ * ```ts
+ * const genAi = convertClaudeSessionToGenAI({ model: "claude-sonnet-4-20250514", inputTokens: 100 });
+ * const otel  = toAttributes(genAi);
+ * ```
+ */
+export function convertClaudeSessionToGenAI(
+  data: ClaudeSessionData,
+): GenAiAttributes {
+  const result: GenAiAttributes = {};
+
+  // Set system
+  result.system = "anthropic";
+
+  // Set model
+  if (data.model) {
+    result.requestModel = data.model;
+  }
+
+  // Convert input to gen_ai.input.messages format
+  if (data.inputPrompt) {
+    result.inputMessages = convertClaudePromptToInputMessages(data.inputPrompt);
+  }
+
+  // Convert output to gen_ai.output.messages format
+  if (data.responseBlocks) {
+    result.outputMessages = convertClaudeResponseToOutputMessages(
+      data.responseBlocks,
+      data.stopReason,
+    );
+  } else if (data.responseContent) {
+    result.outputMessages = convertClaudeResponseToOutputMessages(
+      data.responseContent,
+      data.stopReason,
+    );
+  }
+
+  // Set token counts
+  if (data.inputTokens !== undefined) {
+    result.inputTokens = data.inputTokens;
+  }
+  if (data.outputTokens !== undefined) {
+    result.outputTokens = data.outputTokens;
+  }
+
+  // Set response ID
+  if (data.responseId) {
+    result.responseId = data.responseId;
+  }
+
+  // Set tool definitions from tool names
+  if (data.toolNames && data.toolNames.length > 0) {
+    result.toolDefinitions = data.toolNames.map(
+      (name): ToolDefinition => ({ name }),
+    );
+  }
+
+  // Set system instructions
+  if (data.systemInstructions) {
+    result.systemInstructions = [
+      { type: "text" as const, content: data.systemInstructions },
+    ];
+  }
+
+  return result;
+}
+
+/**
+ * Convert Claude session data directly to OTel span attributes with `gen_ai.*`
+ * dot-notation keys, plus Claude-specific keys like `claude.session_id`.
+ *
+ * @param data - Aggregated {@link ClaudeSessionData} for one session.
+ * @returns A flat dictionary suitable for `span.setAttributes()`.
+ *
+ * @example
+ * ```ts
+ * const attrs = convertClaudeSessionToOtelAttributes(sessionData);
+ * for (const [k, v] of Object.entries(attrs)) span.setAttribute(k, v);
+ * ```
+ */
+export function convertClaudeSessionToOtelAttributes(
+  data: ClaudeSessionData,
+): Record<string, string | number> {
+  const genaiAttrs = convertClaudeSessionToGenAI(data);
+  const result = toAttributes(genaiAttrs);
+
+  // Add Claude-specific attributes
+  if (data.sessionId) {
+    result["claude.session_id"] = data.sessionId;
+  }
+  if (data.costUsd !== undefined) {
+    result["gen_ai.cost.usd"] = data.costUsd;
+  }
+
+  return result;
+}

package/src/converters/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Converters for transforming various API formats to OTel Gen AI Semantic Conventions.
+ */
+
+export {
+  convertResponsesInputsToSemconv,
+  convertResponsesOutputsToSemconv,
+  convertResponsesToolsToSemconv,
+  convertResponsesInstructionsToSemconv,
+  type ResponseInputItem,
+  type ResponseOutputItem,
+  type ResponseTool,
+  type ResponseUsage,
+  type Response as OpenAIResponse,
+} from "./openai.js";
+
+export {
+  isOpenInferenceSpan,
+  convertOpenInferenceToGenAI,
+  replaceOpenInferenceWithGenAI,
+  addOpenInferenceAttributes,
+  OpenInferenceSpanExporter,
+} from "./openinference.js";
+
+export { isVercelAISpan, convertVercelAIToGenAI } from "./vercel.js";
+
+export {
+  convertMessagesToInputMessages as convertAISDKMessagesToInputMessages,
+  extractSystemInstructions as extractAISDKSystemInstructions,
+  buildOutputMessages as buildAISDKOutputMessages,
+  convertToolsToToolDefinitions as convertAISDKToolsToToolDefinitions,
+} from "./ai-sdk.js";
+
+export {
+  convertClaudePromptToInputMessages,
+  convertClaudeResponseToOutputMessages,
+  convertClaudeMessagesToInputMessages,
+  convertClaudeSessionToGenAI,
+  convertClaudeSessionToOtelAttributes,
+  type ClaudeContentBlock,
+  type ClaudeMessage,
+  type ClaudeResponse,
+  type ClaudeSessionData,
+} from "./claude.js";