veadk-python 0.2.16__py3-none-any.whl → 0.2.17__py3-none-any.whl

veadk/tracing/base_tracer.py

@@ -20,12 +20,39 @@ logger = get_logger(__name__)
 
 
 class BaseTracer(ABC):
+    """Abstract base class for implementing tracing functionality in VeADK agents.
+
+    BaseTracer provides the foundation for collecting, managing, and exporting
+    trace data from agent execution sessions. It defines the interface that all
+    concrete tracer implementations must follow, enabling pluggable tracing
+    backends for different observability platforms.
+
+    Attributes:
+        name: Unique identifier for this tracer instance
+        _trace_id: Internal trace identifier for current execution context
+        _trace_file_path: Path to the current trace data file
+    """
+
     def __init__(self, name: str):
+        """Initialize a new BaseTracer instance.
+
+        Args:
+            name: Unique identifier for this tracer instance.
+        """
         self.name = name
         self._trace_id = "<unknown_trace_id>"
         self._trace_file_path = "<unknown_trace_file_path>"
 
     @abstractmethod
     def dump(self, user_id: str, session_id: str, path: str = "/tmp") -> str:
-        """Dump the trace data to a local file."""
+        """Dump the collected trace data to a local file.
+
+        This method must be implemented by concrete tracer classes to export
+        trace data in a format suitable for analysis or storage.
+
+        Args:
+            user_id: User identifier for trace organization and file naming
+            session_id: Session identifier for filtering and organizing spans
+            path: Directory path for the output file. Defaults to system temp directory
+        """
         ...

veadk/tracing/telemetry/attributes/extractors/common_attributes_extractors.py

@@ -16,44 +16,148 @@ from veadk.version import VERSION
 
 
 def common_gen_ai_system(**kwargs) -> str:
-    """This field will be parsed as `model_provider` in Volcengine CozeLoop platform."""
+    """Extract the generative AI system provider name.
+
+    This field identifies the model provider and will be parsed as `model_provider`
+    in Volcengine CozeLoop platform for system categorization and analysis.
+
+    Args:
+        **kwargs: Keyword arguments containing context information.
+            Expected to include 'model_provider' key.
+
+    Returns:
+        str: Model provider name or placeholder if not available
+    """
     model_provider = kwargs.get("model_provider")
     return model_provider or "<unknown_model_provider>"
 
 
 def common_gen_ai_system_version(**kwargs) -> str:
+    """Extract the VeADK system version.
+
+    Provides version information for the VeADK framework being used,
+    enabling version-specific analysis and compatibility tracking.
+
+    Args:
+        **kwargs: Keyword arguments (unused in this extractor)
+
+    Returns:
+        str: Current VeADK version string
+    """
     return VERSION
 
 
 def common_gen_ai_app_name(**kwargs) -> str:
+    """Extract the application name from context.
+
+    Provides application-level identification for organizing and
+    filtering telemetry data by application or service.
+
+    Args:
+        **kwargs: Keyword arguments containing context information.
+            Expected to include 'app_name' key.
+
+    Returns:
+        str: Application name or placeholder if not available
+    """
     app_name = kwargs.get("app_name")
     return app_name or "<unknown_app_name>"
 
 
 def common_gen_ai_agent_name(**kwargs) -> str:
+    """Extract the agent name from context.
+
+    Provides agent-level identification for organizing telemetry data
+    by specific agent instances within an application.
+
+    Args:
+        **kwargs: Keyword arguments containing context information.
+            Expected to include 'agent_name' key.
+
+    Returns:
+        str: Agent name or placeholder if not available
+    """
     agent_name = kwargs.get("agent_name")
     return agent_name or "<unknown_agent_name>"
 
 
 def common_gen_ai_user_id(**kwargs) -> str:
+    """Extract the user identifier from context.
+
+    Provides user-level identification for organizing telemetry data
+    by user sessions and enabling user-specific analytics.
+
+    Args:
+        **kwargs: Keyword arguments containing context information.
+            Expected to include 'user_id' key.
+
+    Returns:
+        str: User identifier or placeholder if not available
+    """
     user_id = kwargs.get("user_id")
     return user_id or "<unknown_user_id>"
 
 
 def common_gen_ai_session_id(**kwargs) -> str:
+    """Extract the session identifier from context.
+
+    Provides session-level identification for organizing telemetry data
+    by conversation sessions and enabling session-based analysis.
+
+    Args:
+        **kwargs: Keyword arguments containing context information.
+            Expected to include 'session_id' key.
+
+    Returns:
+        str: Session identifier or placeholder if not available
+    """
     session_id = kwargs.get("session_id")
     return session_id or "<unknown_session_id>"
 
 
 def common_cozeloop_report_source(**kwargs) -> str:
+    """Extract the CozeLoop report source identifier.
+
+    Provides a fixed identifier indicating that telemetry data originated
+    from the VeADK framework for CozeLoop platform integration.
+
+    Args:
+        **kwargs: Keyword arguments (unused in this extractor)
+
+    Returns:
+        str: Always returns "veadk" as the report source
+    """
     return "veadk"
 
 
 def common_cozeloop_call_type(**kwargs) -> str:
+    """Extract the CozeLoop call type from context.
+
+    Provides call type classification for CozeLoop platform analysis,
+    enabling categorization of different operation types.
+
+    Args:
+        **kwargs: Keyword arguments containing context information.
+            Expected to include 'call_type' key.
+
+    Returns:
+        str: Call type identifier or None if not available
+    """
     return kwargs.get("call_type")
 
 
 def llm_openinference_instrumentation_veadk(**kwargs) -> str:
+    """Extract the OpenInference instrumentation version for VeADK.
+
+    Provides instrumentation version information following OpenInference
+    standards for telemetry framework identification.
+
+    Args:
+        **kwargs: Keyword arguments (unused in this extractor)
+
+    Returns:
+        str: Current VeADK version as instrumentation identifier
+    """
     return VERSION
 
 

veadk/tracing/telemetry/attributes/extractors/llm_attributes_extractors.py

@@ -22,39 +22,143 @@ from veadk.utils.misc import safe_json_serialize
 
 
 def llm_gen_ai_request_model(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract the requested language model name.
+
+    Provides the model identifier that was specified in the LLM request
+    for tracking model usage patterns and performance analysis.
+
+    Args:
+        params: LLM execution parameters containing request details
+
+    Returns:
+        ExtractorResponse: Response containing the model name or placeholder
+    """
     return ExtractorResponse(content=params.llm_request.model or "<unknown_model_name>")
 
 
 def llm_gen_ai_request_type(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract the LLM request type.
+
+    Provides the type of LLM operation being performed, typically "chat"
+    for conversational interactions with language models.
+
+    Args:
+        params: LLM execution parameters (unused in this extractor)
+
+    Returns:
+        ExtractorResponse: Response containing "chat" as the request type
+    """
     return ExtractorResponse(content="chat" or "<unknown_type>")
 
 
 def llm_gen_ai_response_model(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract the responding language model name.
+
+    Provides the actual model that generated the response, which should
+    match the requested model for verification and tracking purposes.
+
+    Args:
+        params: LLM execution parameters containing request details
+
+    Returns:
+        ExtractorResponse: Response containing the response model name or placeholder
+    """
     return ExtractorResponse(content=params.llm_request.model or "<unknown_model_name>")
 
 
 def llm_gen_ai_request_max_tokens(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract the maximum output tokens configuration.
+
+    Provides the maximum number of tokens the model is allowed to generate
+    in its response, used for cost prediction and output length control.
+
+    Args:
+        params: LLM execution parameters containing request configuration
+
+    Returns:
+        ExtractorResponse: Response containing max output tokens value
+    """
     return ExtractorResponse(content=params.llm_request.config.max_output_tokens)
 
 
 def llm_gen_ai_request_temperature(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract the temperature parameter for response randomness.
+
+    Provides the temperature setting that controls randomness in model
+    responses, affecting creativity and consistency of outputs.
+
+    Args:
+        params: LLM execution parameters containing request configuration
+
+    Returns:
+        ExtractorResponse: Response containing temperature value
+    """
     return ExtractorResponse(content=params.llm_request.config.temperature)
 
 
 def llm_gen_ai_request_top_p(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract the top-p parameter for nucleus sampling.
+
+    Provides the top-p (nucleus sampling) setting that controls the
+    diversity of token sampling in model responses.
+
+    Args:
+        params: LLM execution parameters containing request configuration
+
+    Returns:
+        ExtractorResponse: Response containing top-p value
+    """
     return ExtractorResponse(content=params.llm_request.config.top_p)
 
 
 def llm_gen_ai_response_stop_reason(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract the stop reason for response completion.
+
+    Provides information about why the model stopped generating tokens,
+    which helps identify truncation or completion patterns.
+
+    Args:
+        params: LLM execution parameters (currently not implemented)
+
+    Returns:
+        ExtractorResponse: Response containing placeholder stop reason
+    """
     return ExtractorResponse(content="<no_stop_reason_provided>")
 
 
 def llm_gen_ai_response_finish_reason(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract the finish reason for response completion.
+
+    Provides information about how the model completed its response,
+    such as natural completion, token limit, or stop sequence.
+
+    Args:
+        params: LLM execution parameters (currently not implemented)
+
+    Returns:
+        ExtractorResponse: Response containing placeholder finish reason
+
+    Note:
+        - Currently returns placeholder value
+        - TODO: Update implementation for Google ADK v1.12.0
+        - Critical for understanding response quality and completeness
+    """
     # TODO: update to google-adk v1.12.0
     return ExtractorResponse(content="<no_finish_reason_provided>")
 
 
 def llm_gen_ai_usage_input_tokens(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract the number of input tokens consumed.
+
+    Provides the count of tokens in the prompt and context that were
+    processed by the model, essential for cost tracking and analysis.
+
+    Args:
+        params: LLM execution parameters containing response metadata
+
+    Returns:
+        ExtractorResponse: Response containing input token count or None
+    """
     if params.llm_response.usage_metadata:
         return ExtractorResponse(
             content=params.llm_response.usage_metadata.prompt_token_count
@@ -63,6 +167,17 @@ def llm_gen_ai_usage_input_tokens(params: LLMAttributesParams) -> ExtractorRespo
 
 
 def llm_gen_ai_usage_output_tokens(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract the number of output tokens generated.
+
+    Provides the count of tokens generated by the model in its response,
+    essential for cost tracking and response length analysis.
+
+    Args:
+        params: LLM execution parameters containing response metadata
+
+    Returns:
+        ExtractorResponse: Response containing output token count or None
+    """
     if params.llm_response.usage_metadata:
         return ExtractorResponse(
             content=params.llm_response.usage_metadata.candidates_token_count,
@@ -71,6 +186,17 @@ def llm_gen_ai_usage_output_tokens(params: LLMAttributesParams) -> ExtractorResp
 
 
 def llm_gen_ai_usage_total_tokens(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract the total number of tokens consumed.
+
+    Provides the total count of tokens (input + output) consumed by
+    the model interaction, used for overall cost tracking.
+
+    Args:
+        params: LLM execution parameters containing response metadata
+
+    Returns:
+        ExtractorResponse: Response containing total token count or None
+    """
     if params.llm_response.usage_metadata:
         return ExtractorResponse(
             content=params.llm_response.usage_metadata.total_token_count,
@@ -82,6 +208,17 @@ def llm_gen_ai_usage_total_tokens(params: LLMAttributesParams) -> ExtractorRespo
 def llm_gen_ai_usage_cache_creation_input_tokens(
     params: LLMAttributesParams,
 ) -> ExtractorResponse:
+    """Extract the number of tokens used for cache creation.
+
+    Provides the count of tokens used for creating cached content,
+    which affects cost calculation in caching-enabled models.
+
+    Args:
+        params: LLM execution parameters containing response metadata
+
+    Returns:
+        ExtractorResponse: Response containing cache creation token count or None
+    """
     if params.llm_response.usage_metadata:
         return ExtractorResponse(
             content=params.llm_response.usage_metadata.cached_content_token_count,
@@ -93,6 +230,17 @@ def llm_gen_ai_usage_cache_creation_input_tokens(
 def llm_gen_ai_usage_cache_read_input_tokens(
     params: LLMAttributesParams,
 ) -> ExtractorResponse:
+    """Extract the number of tokens used for cache reading.
+
+    Provides the count of tokens read from cached content,
+    which affects cost calculation in caching-enabled models.
+
+    Args:
+        params: LLM execution parameters containing response metadata
+
+    Returns:
+        ExtractorResponse: Response containing cache read token count or None
+    """
     if params.llm_response.usage_metadata:
         return ExtractorResponse(
             content=params.llm_response.usage_metadata.cached_content_token_count,
@@ -101,6 +249,18 @@ def llm_gen_ai_usage_cache_read_input_tokens(
 
 
 def llm_gen_ai_prompt(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract structured prompt data for span attributes.
+
+    Processes the complete conversation history from the LLM request
+    and structures it into indexed prompt messages with role, content,
+    and metadata information for analysis and debugging.
+
+    Args:
+        params: LLM execution parameters containing request content
+
+    Returns:
+        ExtractorResponse: Response containing list of structured prompt messages
+    """
     # a part is a message
     messages: list[dict] = []
     idx = 0
@@ -159,6 +319,18 @@ def llm_gen_ai_prompt(params: LLMAttributesParams) -> ExtractorResponse:
 
 
 def llm_gen_ai_completion(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract structured completion data for span attributes.
+
+    Processes the model's response content and structures it into
+    indexed completion messages with role, content, and tool call
+    information for analysis and evaluation.
+
+    Args:
+        params: LLM execution parameters containing response content
+
+    Returns:
+        ExtractorResponse: Response containing list of structured completion messages
+    """
     messages = []
 
     content = params.llm_response.content
@@ -193,6 +365,18 @@ def llm_gen_ai_completion(params: LLMAttributesParams) -> ExtractorResponse:
 
 
 def llm_gen_ai_messages(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract complete conversation messages as structured events.
+
+    Processes the entire conversation context including system instructions,
+    user messages, tool messages, and assistant responses into structured
+    events for comprehensive conversation flow analysis.
+
+    Args:
+        params: LLM execution parameters containing request content
+
+    Returns:
+        ExtractorResponse: Event list response containing structured conversation events
+    """
     events = []
 
     # system message
@@ -317,15 +501,45 @@ def llm_gen_ai_messages(params: LLMAttributesParams) -> ExtractorResponse:
 
 
 def llm_gen_ai_is_streaming(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract streaming mode indicator.
+
+    Indicates whether the LLM request was processed in streaming mode
+    for performance analysis and debugging purposes.
+
+    Args:
+        params: LLM execution parameters (currently not implemented)
+
+    Returns:
+        ExtractorResponse: Response containing None (not implemented)
+    """
     # return params.llm_request.stream
     return ExtractorResponse(content=None)
 
 
 def llm_gen_ai_operation_name(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract the operation name for LLM spans.
+
+    Provides a standardized operation name for LLM interactions,
+    enabling consistent categorization across all model calls.
+
+    Args:
+        params: LLM execution parameters (unused in this extractor)
+
+    Returns:
+        ExtractorResponse: Response containing "chat" as the operation name
+    """
     return ExtractorResponse(content="chat")
 
 
 def llm_gen_ai_span_kind(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract the span kind for LLM spans.
+
+    Provides span kind classification following OpenTelemetry semantic
+    conventions for generative AI LLM operations.
+
+    Returns:
+        ExtractorResponse: Response containing "llm" as the span kind
+    """
     return ExtractorResponse(content="llm")
 
 
@@ -452,6 +666,18 @@ def llm_gen_ai_span_kind(params: LLMAttributesParams) -> ExtractorResponse:
 
 
 def llm_gen_ai_choice(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract model choice data as span events.
+
+    Processes the model's response content and creates choice events
+    containing response metadata, content, and tool calls for
+    detailed response analysis.
+
+    Args:
+        params: LLM execution parameters containing response content
+
+    Returns:
+        ExtractorResponse: Event response containing structured choice data
+    """
     message = {}
 
     # parse content to build a message
@@ -510,18 +736,52 @@ def llm_gen_ai_choice(params: LLMAttributesParams) -> ExtractorResponse:
 
 
 def llm_input_value(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract complete LLM request data for debugging.
+
+    Provides the complete LLM request object in string format
+    for detailed debugging and analysis purposes.
+
+    Args:
+        params: LLM execution parameters containing request details
+
+    Returns:
+        ExtractorResponse: Response containing serialized request data
+    """
     return ExtractorResponse(
         content=str(params.llm_request.model_dump(exclude_none=True))
     )
 
 
 def llm_output_value(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract complete LLM response data for debugging.
+
+    Provides the complete LLM response object in string format
+    for detailed debugging and analysis purposes.
+
+    Args:
+        params: LLM execution parameters containing response details
+
+    Returns:
+        ExtractorResponse: Response containing serialized response data
+    """
     return ExtractorResponse(
         content=str(params.llm_response.model_dump(exclude_none=True))
     )
 
 
 def llm_gen_ai_request_functions(params: LLMAttributesParams) -> ExtractorResponse:
+    """Extract available functions/tools from the LLM request.
+
+    Processes the tools dictionary from the LLM request and extracts
+    function metadata including names, descriptions, and parameters
+    for tool usage analysis and debugging.
+
+    Args:
+        params: LLM execution parameters containing request tools
+
+    Returns:
+        ExtractorResponse: Response containing list of function metadata
+    """
     functions = []
 
     for idx, (tool_name, tool_instance) in enumerate(

veadk/tracing/telemetry/attributes/extractors/tool_attributes_extractors.py

@@ -20,14 +20,50 @@ from veadk.utils.misc import safe_json_serialize
 
 
 def tool_gen_ai_operation_name(params: ToolAttributesParams) -> ExtractorResponse:
+    """Extract the operation name for tool execution spans.
+
+    Provides a standardized operation name identifier for tool execution
+    operations, enabling consistent categorization across all tool invocations.
+
+    Args:
+        params: Tool execution parameters (unused in this extractor)
+
+    Returns:
+        ExtractorResponse: Response containing "execute_tool" as the operation name
+    """
     return ExtractorResponse(content="execute_tool")
 
 
 def tool_gen_ai_span_kind(params: ToolAttributesParams) -> ExtractorResponse:
+    """Extract the span kind for tool execution spans.
+
+    Provides span kind classification following OpenTelemetry semantic
+    conventions for generative AI tool operations.
+
+    Args:
+        params: Tool execution parameters (unused in this extractor)
+
+    Returns:
+        ExtractorResponse: Response containing "tool" as the span kind
+    """
     return ExtractorResponse(content="tool")
 
 
 def tool_gen_ai_tool_message(params: ToolAttributesParams) -> ExtractorResponse:
+    """Extract tool message event data for span annotation.
+
+    Creates a structured tool message event containing tool metadata and
+    execution parameters in a format suitable for observability platforms
+    and debugging workflows.
+
+    Args:
+        params: Tool execution parameters containing tool instance and arguments
+
+    Returns:
+        ExtractorResponse: Event response with tool message data including:
+            - role: "tool" for message classification
+            - content: JSON serialized tool information
+    """
     tool_input = {
         "role": "tool",
         "content": safe_json_serialize(
@@ -42,6 +78,17 @@ def tool_gen_ai_tool_message(params: ToolAttributesParams) -> ExtractorResponse:
 
 
 def tool_gen_ai_tool_input(params: ToolAttributesParams) -> ExtractorResponse:
+    """Extract tool input data for span attributes.
+
+    Captures comprehensive tool input information including tool metadata
+    and execution parameters in JSON format for analysis and debugging.
+
+    Args:
+        params: Tool execution parameters containing tool instance and arguments
+
+    Returns:
+        ExtractorResponse: Response containing JSON serialized tool input data
+    """
     tool_input = {
         "name": params.tool.name,
         "description": params.tool.description,
@@ -53,10 +100,32 @@ def tool_gen_ai_tool_input(params: ToolAttributesParams) -> ExtractorResponse:
 
 
 def tool_gen_ai_tool_name(params: ToolAttributesParams) -> ExtractorResponse:
+    """Extract the tool name for span identification.
+
+    Provides the tool function name for identification and categorization
+    purposes in observability platforms and analysis workflows.
+
+    Args:
+        params: Tool execution parameters containing tool instance
+
+    Returns:
+        ExtractorResponse: Response containing the tool name or placeholder
+    """
     return ExtractorResponse(content=params.tool.name or "<unknown_tool_name>")
 
 
 def tool_gen_ai_tool_output(params: ToolAttributesParams) -> ExtractorResponse:
+    """Extract tool output data for span attributes.
+
+    Captures tool execution results including response data and metadata
+    in JSON format for analysis, debugging, and evaluation purposes.
+
+    Args:
+        params: Tool execution parameters containing function response event
+
+    Returns:
+        ExtractorResponse: Response containing JSON serialized tool output data
+    """
     function_response = params.function_response_event.get_function_responses()[
         0
     ].model_dump()