@introspection-sdk/introspection-node 0.20.0 → 0.21.1

package/src/converters/claude.ts

@@ -1,343 +0,0 @@
-/**
- * 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 "@introspection-sdk/types";
-import { toAttributes } from "@introspection-sdk/types";
-
-/** 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: "reasoning",
-        content: thinking || "[redacted]",
-        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;
-  /** Tokens read from the LLM prompt cache */
-  cacheReadInputTokens?: number;
-  /** Tokens written to the LLM prompt cache */
-  cacheCreationInputTokens?: number;
-}
-
-/**
- * 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 = {};
-
-  result.providerName = "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;
-  }
-  if (data.cacheReadInputTokens !== undefined) {
-    result.cacheReadInputTokens = data.cacheReadInputTokens;
-  }
-  if (data.cacheCreationInputTokens !== undefined) {
-    result.cacheCreationInputTokens = data.cacheCreationInputTokens;
-  }
-
-  // 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 => ({
-      type: "function",
-      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 | 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/gemini.ts

@@ -1,243 +0,0 @@
-/**
- * Google Gemini (`@google/genai`) format conversion functions for OTel Gen AI
- * Semantic Conventions.
- *
- * Gemini 3.x / Gemini 3.5+ models emit per-part `thoughtSignature` payloads
- * that carry encrypted reasoning context which MUST be passed back on
- * subsequent turns (especially around tool calls) for the model to maintain
- * its chain of thought.
- *
- * @see https://ai.google.dev/gemini-api/docs/thought-signatures
- *
- * Whenever a Gemini part carries a `thoughtSignature`, this converter emits a
- * `reasoning` gen_ai part preceding the visible content. If the part is itself a
- * thought summary (`thought: true`), the visible thought text is used as the
- * thinking content; otherwise the signed-but-redacted sentinel
- * `REDACTED_THINKING_CONTENT` (`"[redacted]"`) is used — mirroring the way the
- * Anthropic instrumentor handles `redacted_thinking` blocks.
- */
-
-import type {
-  InputMessage,
-  OutputMessage,
-  MessagePart,
-  ReasoningPart,
-  SystemInstruction,
-  ToolDefinition,
-} from "@introspection-sdk/types";
-
-/** Sentinel for parts that carry a thought signature but no visible thought content. */
-const REDACTED_THINKING_CONTENT = "[redacted]";
-
-/** Provider name reported on Gemini-produced thinking parts. */
-export const GEMINI_PROVIDER_NAME = "gemini";
-
-/** A single content part as returned by the `@google/genai` SDK. */
-export interface GeminiPart {
-  text?: string;
-  thought?: boolean;
-  thoughtSignature?: string;
-  functionCall?: {
-    id?: string;
-    name?: string;
-    args?: unknown;
-  };
-  functionResponse?: {
-    id?: string;
-    name?: string;
-    response?: unknown;
-  };
-  [key: string]: unknown;
-}
-
-/** A Content envelope as used in Gemini `contents` requests and candidate outputs. */
-export interface GeminiContent {
-  role?: string;
-  parts?: GeminiPart[];
-}
-
-/** A single candidate from a `generateContent` response. */
-export interface GeminiCandidate {
-  content?: GeminiContent;
-  finishReason?: string;
-  index?: number;
-}
-
-/** A Gemini tool function declaration. */
-export interface GeminiFunctionDeclaration {
-  name?: string;
-  description?: string;
-  parameters?: unknown;
-  parametersJsonSchema?: unknown;
-}
-
-/** A Gemini tool entry — `{ functionDeclarations: [...] }`. */
-export interface GeminiTool {
-  functionDeclarations?: GeminiFunctionDeclaration[];
-}
-
-/** Normalize roles from Gemini to gen_ai. Gemini uses `model` for assistant turns. */
-function normalizeRole(role: string | undefined): InputMessage["role"] {
-  if (role === "model") return "assistant";
-  if (role === "user" || role === "system" || role === "tool") return role;
-  return "user";
-}
-
-/**
- * Convert a single Gemini part into zero-or-more gen_ai message parts.
- *
- * A part carrying a `thoughtSignature` always produces a leading `reasoning`
- * part so the signed reasoning payload is preserved alongside whatever visible
- * content the part contains.
- */
-function partToGenAiParts(part: GeminiPart): MessagePart[] {
-  const out: MessagePart[] = [];
-  const signature = part.thoughtSignature || undefined;
-  const isThought = part.thought === true;
-
-  if (isThought) {
-    // Visible thought summary (Gemini emits these when `includeThoughts: true`).
-    const reasoning: ReasoningPart = {
-      type: "reasoning",
-      content: part.text || REDACTED_THINKING_CONTENT,
-      signature,
-      provider_name: GEMINI_PROVIDER_NAME,
-    };
-    out.push(reasoning);
-    return out;
-  }
-
-  if (signature) {
-    // Signed but non-thought part — emit a redacted reasoning prefix carrying the signature.
-    const reasoning: ReasoningPart = {
-      type: "reasoning",
-      content: REDACTED_THINKING_CONTENT,
-      signature,
-      provider_name: GEMINI_PROVIDER_NAME,
-    };
-    out.push(reasoning);
-  }
-
-  if (typeof part.text === "string" && part.text.length > 0) {
-    out.push({ type: "text", content: part.text });
-  }
-
-  if (part.functionCall) {
-    out.push({
-      type: "tool_call",
-      id: part.functionCall.id,
-      name: part.functionCall.name || "",
-      arguments: part.functionCall.args,
-    });
-  }
-
-  if (part.functionResponse) {
-    out.push({
-      type: "tool_call_response",
-      id: part.functionResponse.id,
-      name: part.functionResponse.name,
-      response: part.functionResponse.response,
-    });
-  }
-
-  return out;
-}
-
-/**
- * Convert a `contents` array from a Gemini request to gen_ai input messages.
- *
- * Accepts a plain string (the convenience form `generateContent({ contents: "hi" })`)
- * or an array of {@link GeminiContent} objects. Roles are normalized: Gemini's
- * `model` becomes `assistant`.
- *
- * @param contents - The Gemini request's `contents` field.
- * @returns Array of {@link InputMessage} objects.
- */
-export function convertGeminiContentsToInputMessages(
-  contents: string | GeminiContent[] | GeminiContent | undefined,
-): InputMessage[] {
-  if (!contents) return [];
-
-  if (typeof contents === "string") {
-    return [{ role: "user", parts: [{ type: "text", content: contents }] }];
-  }
-
-  const list: GeminiContent[] = Array.isArray(contents) ? contents : [contents];
-
-  const result: InputMessage[] = [];
-  for (const c of list) {
-    const parts = (c.parts || []).flatMap(partToGenAiParts);
-    if (parts.length === 0) continue;
-    result.push({ role: normalizeRole(c.role), parts });
-  }
-  return result;
-}
-
-/**
- * Convert Gemini response candidates to gen_ai output messages.
- *
- * @param candidates - The `candidates` array from a `generateContent` response.
- * @returns Array of {@link OutputMessage} objects (one per candidate that has content).
- */
-export function convertGeminiCandidatesToOutputMessages(
-  candidates: GeminiCandidate[] | undefined,
-): OutputMessage[] {
-  if (!candidates || candidates.length === 0) return [];
-
-  const result: OutputMessage[] = [];
-  for (const cand of candidates) {
-    const role = normalizeRole(cand.content?.role || "model");
-    const parts = (cand.content?.parts || []).flatMap(partToGenAiParts);
-    if (parts.length === 0 && !cand.finishReason) continue;
-    const msg: OutputMessage = { role, parts };
-    if (cand.finishReason) msg.finish_reason = cand.finishReason;
-    result.push(msg);
-  }
-  return result;
-}
-
-/**
- * Convert a Gemini `systemInstruction` field to gen_ai SystemInstruction[].
- *
- * Gemini accepts either a plain string or a {@link GeminiContent} object.
- */
-export function convertGeminiSystemInstructionToSemconv(
-  systemInstruction: string | GeminiContent | undefined,
-): SystemInstruction[] | undefined {
-  if (!systemInstruction) return undefined;
-
-  if (typeof systemInstruction === "string") {
-    return [{ type: "text", content: systemInstruction }];
-  }
-
-  const result = (systemInstruction.parts || []).flatMap(
-    (p): SystemInstruction[] =>
-      typeof p.text === "string" && p.text.length > 0
-        ? [{ type: "text", content: p.text }]
-        : [],
-  );
-  return result.length > 0 ? result : undefined;
-}
-
-/**
- * Convert Gemini `tools` (array of `{functionDeclarations}` entries) to gen_ai
- * ToolDefinition[].
- */
-export function convertGeminiToolsToToolDefinitions(
-  tools: GeminiTool[] | undefined,
-): ToolDefinition[] | undefined {
-  if (!tools || tools.length === 0) return undefined;
-
-  const defs: ToolDefinition[] = [];
-  for (const tool of tools) {
-    for (const fn of tool.functionDeclarations || []) {
-      if (!fn.name) continue;
-      const def: ToolDefinition = { type: "function", name: fn.name };
-      if (fn.description) def.description = fn.description;
-      const params = fn.parametersJsonSchema ?? fn.parameters;
-      if (params) def.parameters = params;
-      defs.push(def);
-    }
-  }
-  return defs.length > 0 ? defs : undefined;
-}

package/src/converters/index.ts

@@ -1,50 +0,0 @@
-/**
- * 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 {
-  convertClaudePromptToInputMessages,
-  convertClaudeResponseToOutputMessages,
-  convertClaudeMessagesToInputMessages,
-  convertClaudeSessionToGenAI,
-  convertClaudeSessionToOtelAttributes,
-  type ClaudeContentBlock,
-  type ClaudeMessage,
-  type ClaudeResponse,
-  type ClaudeSessionData,
-} from "./claude.js";
-
-export {
-  convertGeminiContentsToInputMessages,
-  convertGeminiCandidatesToOutputMessages,
-  convertGeminiSystemInstructionToSemconv,
-  convertGeminiToolsToToolDefinitions,
-  GEMINI_PROVIDER_NAME,
-  type GeminiCandidate,
-  type GeminiContent,
-  type GeminiFunctionDeclaration,
-  type GeminiPart,
-  type GeminiTool,
-} from "./gemini.js";