Skip to content

Python SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI

22.9 KB
Raw Blame
import { ISpan } from '@/types/ISpan';
import { extractAG2ToolName } from '@/utils/ag2.utils';

export interface ProcessedSpan {
  name: string;
  index: number;
  id: string;
  start: number;
  end: number;
  value: number[];
  duration: number;
  type: string;
  originalSpan: ISpan | null;
  isFiller?: boolean;
  previewText?: string;
}

/**
 * Determines the visual type for ADK spans based on the span name pattern
 * @param spanName - The span name (e.g., "adk.agent.HumanApprovalWorkflow")
 * @param span - The full span object for accessing attributes
 * @returns Object with visualType and previewText
 */
export function processAdkSpan(
  spanName: string,
  span?: ISpan,
): { visualType: string; previewText: string } {
  const adkParts = spanName.split('.');

  if (adkParts.length >= 3) {
    const adkType = adkParts[1]; // Extract type from adk.{type}.{name}
    const adkName = adkParts.slice(2).join('.'); // Get the name part

    // Map ADK types to existing visual types
    switch (adkType) {
      case 'agent':
        // Check if this ADK agent has sub_agents, making it a workflow
        if (span?.span_attributes?.agent?.sub_agents?.length > 0) {
          return { visualType: 'workflow', previewText: adkName || spanName };
        }
        return { visualType: 'agent', previewText: adkName || spanName };
      case 'tool':
        return { visualType: 'tool', previewText: adkName || spanName };
      case 'llm':
        // For ADK LLM spans, try to extract completion message first
        if (span?.span_attributes?.gen_ai) {
          const { previewText: llmPreviewText, contentFound } = processLlmSpanContent(
            span.span_attributes.gen_ai,
          );
          if (contentFound && llmPreviewText) {
            return { visualType: 'llm', previewText: llmPreviewText };
          }
        }
        // Fallback to model name if no completion found
        return { visualType: 'llm', previewText: adkName || spanName };
      case 'task':
        return { visualType: 'task', previewText: adkName || spanName };
      case 'workflow':
        return { visualType: 'workflow', previewText: adkName || spanName };
      case 'operation':
        return { visualType: 'operation', previewText: adkName || spanName };
      default:
        return { visualType: 'other', previewText: adkName || spanName };
    }
  } else {
    // Malformed ADK span name, treat as other
    return { visualType: 'other', previewText: spanName };
  }
}

/**
 * Processes LLM span attributes to extract preview text
 * @param genAi - The gen_ai attributes from the span
 * @returns Object with previewText and whether content was found
 */
export function processLlmSpanContent(genAi: any): { previewText: string; contentFound: boolean } {
  let previewText = '';
  let contentFound = false;

  const getContentFromNestedKeyedObject = (keyedObject: any): string | null => {
    // keyedObject is like genAi.completion[0] which is expected to be an object like { "0": { content: "..." } }
    if (keyedObject && typeof keyedObject === 'object' && !Array.isArray(keyedObject)) {
      const keys = Object.keys(keyedObject);
      if (keys.length > 0) {
        const innerKey = keys[0]; // e.g., "0"
        const messageObject = keyedObject[innerKey];
        if (messageObject && typeof messageObject.content === 'string') {
          return messageObject.content;
        }
      }
    }
    return null;
  };

  if (genAi.completion) {
    // Attempt 1: OpenAI style (first item in completion array)
    if (Array.isArray(genAi.completion) && genAi.completion.length > 0) {
      const content = getContentFromNestedKeyedObject(genAi.completion[0]);
      if (content !== null) {
        previewText = content;
        contentFound = true;
      }
    }

    // Attempt 2: Existing "specific structure" (last item in completion array for tool_calls or content)
    if (!contentFound && Array.isArray(genAi.completion) && genAi.completion.length > 0) {
      const lastMessageContainer = genAi.completion[genAi.completion.length - 1];
      // lastMessageContainer is like { "0": { tool_calls: [], content: "..." } }
      if (
        lastMessageContainer &&
        typeof lastMessageContainer === 'object' &&
        !Array.isArray(lastMessageContainer)
      ) {
        const keys = Object.keys(lastMessageContainer);
        if (keys.length > 0) {
          const firstKey = keys[0]; // This is the "0" or similar key
          const messageObject = lastMessageContainer[firstKey]; // This is the { tool_calls: [], content: "" } object

          if (messageObject && typeof messageObject === 'object') {
            // Check for tool calls first
            if (
              messageObject.tool_calls &&
              Array.isArray(messageObject.tool_calls) &&
              messageObject.tool_calls.length > 0
            ) {
              const toolCall = messageObject.tool_calls[0];
              if (toolCall && typeof toolCall === 'object') {
                const toolCallKeys = Object.keys(toolCall);
                if (toolCallKeys.length > 0) {
                  const toolCallData = toolCall[toolCallKeys[0]];
                  if (toolCallData && toolCallData.name) {
                    let toolPreview = `${toolCallData.name}`;
                    if (toolCallData.arguments) {
                      try {
                        const args = JSON.parse(toolCallData.arguments);
                        const argSummary = Object.entries(args)
                          .slice(0, 2)
                          .map(([k, v]) => `${k}: ${v}`)
                          .join(', ');
                        if (argSummary) {
                          toolPreview += ` (${argSummary})`;
                        }
                      } catch {
                        // If JSON parsing fails, just show the tool name
                      }
                    }
                    previewText = toolPreview;
                    contentFound = true;
                  }
                }
              }
            }
            // Check for regular content if no tool calls found or processed
            else if (typeof messageObject.content === 'string') {
              previewText = messageObject.content;
              contentFound = true;
            }
          }
        }
      }
    }

    // Further Fallback for existing completion structures if new one not found
    if (!contentFound) {
      if (typeof genAi.completion === 'string') {
        previewText = genAi.completion;
        contentFound = true;
      } else if (
        Array.isArray(genAi.completion) &&
        genAi.completion.length > 0 &&
        typeof genAi.completion[0] === 'string'
      ) {
        previewText = genAi.completion[0];
        contentFound = true;
      } else if (
        Array.isArray(genAi.completion) &&
        genAi.completion.length > 0 &&
        typeof genAi.completion[0] === 'object' &&
        genAi.completion[0].content
      ) {
        // Handle array of message objects with content property
        previewText = genAi.completion[0].content;
        contentFound = true;
      } else if (typeof genAi.completion === 'object' && genAi.completion !== null) {
        // Check for direct content property
        if (genAi.completion.content && typeof genAi.completion.content === 'string') {
          previewText = genAi.completion.content;
          contentFound = true;
        } else {
          // Look for any string value in the completion object
          const firstStringVal = Object.values(genAi.completion).find((v) => typeof v === 'string');
          if (firstStringVal && typeof firstStringVal === 'string') {
            previewText = firstStringVal;
            contentFound = true;
          }
        }
      }
    }
  }

  // If no content from completion, try prompt as last resort
  if (!contentFound && genAi.prompt) {
    if (typeof genAi.prompt === 'string') {
      previewText = genAi.prompt;
      contentFound = true;
    } else if (
      Array.isArray(genAi.prompt) &&
      genAi.prompt.length > 0 &&
      typeof genAi.prompt[0] === 'string'
    ) {
      previewText = genAi.prompt[0];
      contentFound = true;
    } else if (
      Array.isArray(genAi.prompt) &&
      genAi.prompt.length > 0 &&
      typeof genAi.prompt[0] === 'object' &&
      genAi.prompt[0].content
    ) {
      // Handle array of message objects with content property
      previewText = genAi.prompt[0].content;
      contentFound = true;
    } else if (typeof genAi.prompt === 'object' && genAi.prompt !== null) {
      // Check for direct content property
      if (genAi.prompt.content && typeof genAi.prompt.content === 'string') {
        previewText = genAi.prompt.content;
        contentFound = true;
      } else {
        // Look for any string value in the prompt object
        const firstStringVal = Object.values(genAi.prompt).find((v) => typeof v === 'string');
        if (firstStringVal && typeof firstStringVal === 'string') {
          previewText = firstStringVal;
          contentFound = true;
        }
      }
    }
  }

  return { previewText, contentFound };
}

/**
 * Determines the span visualization type and preview text based on span properties
 * @param span - The span object to process
 * @returns Object with visualType and previewText
 */
export function determineSpanType(span: ISpan): { visualType: string; previewText: string } {
  let visualType = 'other';
  let previewText = span.span_name || '';

  // Check for ADK spans first (highest priority)
  if (span.span_name.startsWith('adk.')) {
    return processAdkSpan(span.span_name, span);
  }

  // ===== AG2 (AutoGen2) Specific Processing =====
  // AG2 is a multi-agent framework with specific patterns for span names and data storage
  if (span.span_name.startsWith('ag2.')) {
    const ag2Parts = span.span_name.split('.');
    if (ag2Parts.length >= 3) {
      const ag2Type = ag2Parts[1]; // Extract type from ag2.{type}.{name}

      if (ag2Type === 'agent') {
        visualType = 'agent';
        // Use agent name as preview text
        previewText = span.span_attributes?.agent?.name || span.span_name;
        return { visualType, previewText };
      } else if (ag2Type === 'tool') {
        visualType = 'tool';
        // Use AG2-specific tool name extraction
        const ag2ToolName = extractAG2ToolName(span);
        if (ag2ToolName) {
          previewText = ag2ToolName;
        } else {
          // Fallback to tool.name, but avoid showing "function"
          const toolName = span.span_attributes?.tool?.name;
          previewText = (toolName && toolName !== 'function') ? toolName : span.span_name;
        }
        return { visualType, previewText };
      }
    }
  }

  // Check for Agno spans
  if (span.span_name.startsWith('agno.')) {
    const agnoParts = span.span_name.split('.');
    if (agnoParts.length >= 3) {
      const agnoType = agnoParts[1]; // Extract type from agno.{type}.{action}.{name}

      if (agnoType === 'tool') {
        visualType = 'tool';
        // Use tool parameters or name as preview text
        if (span.span_attributes?.tool?.parameters) {
          try {
            const params = JSON.parse(span.span_attributes.tool.parameters);
            const paramSummary = Object.entries(params)
              .slice(0, 2)
              .map(([k, v]) => `${k}: ${v}`)
              .join(', ');
            previewText = `${span.span_attributes?.tool?.name || 'tool'} (${paramSummary})`;
          } catch {
            previewText = span.span_attributes?.tool?.name || span.span_name;
          }
        } else {
          previewText = span.span_attributes?.tool?.name || span.span_name;
        }
        return { visualType, previewText };
      } else if (agnoType === 'agent') {
        visualType = 'agent';
        // Use agent input as preview text
        if (span.span_attributes?.agent?.input) {
          previewText = span.span_attributes.agent.input;
        } else if (span.span_attributes?.agentops?.entity?.input) {
          previewText = span.span_attributes.agentops.entity.input;
        } else {
          previewText = span.span_name;
        }
        return { visualType, previewText };
      } else if (agnoType === 'team') {
        // Agno team workflows 
        visualType = 'workflow';
        previewText = span.span_attributes?.team?.display_name || span.span_attributes?.team?.name || span.span_name;
        return { visualType, previewText };
      }
    }
  }

  // Check for specific name endings - these take highest priority for non-ADK spans
  if (span.span_name.endsWith('.session')) {
    visualType = 'session';
  } else if (span.span_name.endsWith('.agent')) {
    visualType = 'agent';
    // Check for agent input field first (for Agno and other agents that have input)
    if (span.span_attributes?.agent?.input) {
      previewText = span.span_attributes.agent.input;
    } else if (span.span_attributes?.agentops?.entity?.input) {
      // Fallback to agentops entity input if available
      previewText = span.span_attributes.agentops.entity.input;
    } else {
      previewText = span.span_attributes?.agent?.name || span.span_name;
    }
  } else if (span.span_name.endsWith('.operation')) {
    visualType = 'operation';
  } else if (span.span_name.endsWith('.task')) {
    visualType = 'task';
    previewText =
      span.span_attributes?.task?.input ||
      span.span_attributes?.task?.description ||
      span.span_name;
  } else if (span.span_name.endsWith('.workflow')) {
    visualType = 'workflow';
    // Check if it's an Agno workflow with team data
    if (span.span_attributes?.gen_ai?.system === 'agno' && span.span_attributes?.team) {
      previewText = span.span_attributes.team.display_name || span.span_attributes.team.name || span.span_name;
    }
  } else if (span.span_name.endsWith('.tool')) {
    visualType = 'tool';
    // Check for tool input or name
    if (span.span_attributes?.tool?.input) {
      previewText = span.span_attributes.tool.input;
    } else if (span.span_attributes?.agentops?.entity?.input) {
      // Fallback to agentops entity input for generic tools
      previewText = span.span_attributes.agentops.entity.input;
    } else {
      previewText = span.span_attributes?.tool?.name || span.span_name;
    }
  }
  // Check if it's an Agno tool (has gen_ai.system='agno' and span.kind='tool')
  else if (
    span.span_attributes?.gen_ai?.system === 'agno' &&
    span.span_attributes?.agentops?.span?.kind === 'tool'
  ) {
    visualType = 'tool';
    // Use tool parameters or name as preview text
    if (span.span_attributes?.tool?.parameters) {
      try {
        const params = JSON.parse(span.span_attributes.tool.parameters);
        const paramSummary = Object.entries(params)
          .slice(0, 2)
          .map(([k, v]) => `${k}: ${v}`)
          .join(', ');
        previewText = `${span.span_attributes?.tool?.name || 'tool'} (${paramSummary})`;
      } catch {
        previewText = span.span_attributes?.tool?.name || span.span_name;
      }
    } else {
      previewText = span.span_attributes?.tool?.name || span.span_name;
    }
  }
  // Only mark as 'request' (LLM) if it's a request type AND has gen_ai attributes
  else if (span.span_type === 'request' && !span.span_attributes?.gen_ai) {
    visualType = 'other';
  }
  // Then check if it's an LLM based on gen_ai attributes (but not Agno tools)
  else if (span.span_attributes?.gen_ai) {
    visualType = 'llm';
    const { previewText: llmPreviewText, contentFound } = processLlmSpanContent(
      span.span_attributes.gen_ai,
    );
    if (contentFound && llmPreviewText) {
      previewText = llmPreviewText;
    } else {
      // Fallback to span name if no completion content found
      previewText = span.span_name;
    }
  } else {
    // Default to span_type if no specific ending matches
    visualType = span.span_type;

    // Special handling for agents identified by span_type with input field
    if (span.span_type === 'agent') {
      if (span.span_attributes?.agent?.input) {
        previewText = span.span_attributes.agent.input;
      } else if (span.span_attributes?.agentops?.entity?.input) {
        // Fallback to agentops entity input if available
        previewText = span.span_attributes.agentops.entity.input;
      }
    }

    // Special handling for workflows identified by span type or span kind
    if (span.span_type === 'workflow' || span.span_attributes?.agentops?.span?.kind === 'workflow') {
      visualType = 'workflow';
      // Check if it's an Agno workflow with team data
      if (span.span_attributes?.gen_ai?.system === 'agno' && span.span_attributes?.team) {
        previewText = span.span_attributes.team.display_name || span.span_attributes.team.name || span.span_name;
      }
    }

    // Special handling for tools identified by span_type
    if (span.span_type === 'tool' || span.span_attributes?.agentops?.span?.kind === 'tool') {
      visualType = 'tool';
      // Use tool parameters or name as preview text
      if (span.span_attributes?.tool?.parameters) {
        try {
          const params = JSON.parse(span.span_attributes.tool.parameters);
          const paramSummary = Object.entries(params)
            .slice(0, 2)
            .map(([k, v]) => `${k}: ${v}`)
            .join(', ');
          previewText = `${span.span_attributes?.tool?.name || 'tool'} (${paramSummary})`;
        } catch {
          previewText = span.span_attributes?.tool?.name || span.span_name;
        }
      } else {
        previewText = span.span_attributes?.tool?.name || span.span_name;
      }
    }
  }

  // Mark spans with ERROR status code as errors (overrides other categorizations)
  if (span.status_code === 'ERROR') {
    visualType = 'error';
    previewText = span.status_message || 'Error';
  }

  return { visualType, previewText };
}

/**
 * Processes preview text by removing trailing periods for non-ADK spans
 * @param previewText - The preview text to process
 * @param spanName - The original span name to check if it's an ADK span
 * @returns Processed preview text
 */
export function processPreviewText(previewText: string, spanName: string): string {
  // General rule: If previewText contains a period, chop off text after the last period.
  // Skip this for ADK spans since they have meaningful periods in their names
  if (previewText && previewText.includes('.') && !spanName.startsWith('adk.')) {
    const lastPeriodIndex = previewText.lastIndexOf('.');
    return previewText.substring(0, lastPeriodIndex);
  }
  return previewText;
}

/**
 * Sanitizes timing values to prevent NaN errors
 * @param offsetFromTraceStartMs - The offset from trace start
 * @param durationMs - The duration in milliseconds
 * @returns Object with sanitized values
 */
export function sanitizeTimingValues(offsetFromTraceStartMs: number, durationMs: number) {
  const sanitizedOffsetFromTraceStartMs = isNaN(offsetFromTraceStartMs)
    ? 0
    : offsetFromTraceStartMs;
  const sanitizedDurationMs = isNaN(durationMs) ? 1 : durationMs;
  const sanitizedEnd = sanitizedOffsetFromTraceStartMs + sanitizedDurationMs;

  return {
    sanitizedOffsetFromTraceStartMs,
    sanitizedDurationMs,
    sanitizedEnd,
  };
}

/**
 * Processes a single span into the format needed for the gantt chart
 * @param span - The span to process
 * @param index - The index of the span
 * @param traceStartTimeMs - The start time of the trace in milliseconds
 * @returns Processed span object
 */
export function processSpan(span: ISpan, index: number, traceStartTimeMs: number): ProcessedSpan {
  const spanStartTimeMs = new Date(span.start_time).getTime();
  const offsetFromTraceStartMs = spanStartTimeMs - traceStartTimeMs;
  const durationMs = span.duration / 1000000;

  // Determine the span visualization type and preview text
  const { visualType, previewText: rawPreviewText } = determineSpanType(span);

  // Process the preview text
  const previewText = processPreviewText(rawPreviewText, span.span_name);

  // Sanitize timing values
  const { sanitizedOffsetFromTraceStartMs, sanitizedDurationMs, sanitizedEnd } =
    sanitizeTimingValues(offsetFromTraceStartMs, durationMs);

  return {
    name: span.span_name,
    index,
    id: span.span_id,
    start: sanitizedOffsetFromTraceStartMs,
    end: sanitizedEnd,
    value: [sanitizedOffsetFromTraceStartMs, sanitizedEnd],
    duration: sanitizedDurationMs,
    type: visualType,
    originalSpan: span,
    previewText: previewText,
  };
}

/**
 * Creates filler spans when there are fewer than the minimum required
 * @param processedSpans - The already processed spans
 * @param minSpans - The minimum number of spans required
 * @returns Array of filler spans to add
 */
export function createFillerSpans(
  processedSpans: ProcessedSpan[],
  minSpans: number = 10,
): ProcessedSpan[] {
  if (processedSpans.length >= minSpans) {
    return [];
  }

  const lastBarEnd = processedSpans.length > 0 ? processedSpans[processedSpans.length - 1].end : 0;
  const fillerBarsNeeded = minSpans - processedSpans.length;
  const fillerSpans: ProcessedSpan[] = [];

  for (let i = 0; i < fillerBarsNeeded; i++) {
    fillerSpans.push({
      name: `Filler ${i + 1}`,
      index: processedSpans.length + i,
      id: `filler-${i}`,
      start: lastBarEnd,
      end: lastBarEnd,
      value: [lastBarEnd, lastBarEnd],
      duration: 0,
      type: 'default',
      originalSpan: null,
      isFiller: true,
      previewText: '',
    });
  }

  return fillerSpans;
}

/**
 * Configuration for span type filtering
 */
export const SPAN_TYPE_FILTER_CONFIG = {
  // Define the order of span types
  orderedTypes: [
    'agent',
    'llm',
    'tool',
    'operation',
    'task',
    'error',
    'workflow',
    'other',
    'session',
  ],
  // Always include these types in filters
  alwaysIncluded: new Set(['agent', 'tool', 'llm']),
  // Fallback type when no types are available
  fallbackType: 'session',
};

/**
 * Gets the display types for span type filters
 * @param availableTypes - Set of types that exist in the data
 * @returns Array of types to display in filters
 */
export function getDisplayTypes(availableTypes: Set<string>): string[] {
  const { orderedTypes, alwaysIncluded, fallbackType } = SPAN_TYPE_FILTER_CONFIG;

  // Filter to show always included types and other types that exist in the data, maintaining the order
  const typesToShow = orderedTypes.filter(
    (type) => alwaysIncluded.has(type) || availableTypes.has(type),
  );

  // If no types are available, at least show fallback
  return typesToShow.length > 0 ? typesToShow : [fallbackType];
}

/**
 * Calculates the latest span end time, ensuring it's always at least 1
 * @param processedSpans - Array of processed spans
 * @returns The latest end time
 */
export function calculateLatestSpanEnd(processedSpans: ProcessedSpan[]): number {
  return Math.max(1, ...processedSpans.map((span) => (isNaN(span.end) ? 0 : span.end)));
}

/**
 * Creates a fallback span for when all types are filtered out
 * @returns A fallback ProcessedSpan object
 */
export function createFallbackSpan(): ProcessedSpan {
  return {
    name: 'No spans visible',
    index: 0,
    id: 'no-data',
    start: 0,
    end: 1,
    value: [0, 1],
    duration: 1,
    type: 'default',
    originalSpan: null,
    isFiller: true,
    previewText: '',
  };
}