language-operator 0.1.57 → 0.1.59

data/lib/language_operator/cli/formatters/optimization_formatter.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require 'pastel'
+
+module LanguageOperator
+  module CLI
+    module Formatters
+      # Formats optimization analysis and proposals for CLI display
+      class OptimizationFormatter
+        def initialize
+          @pastel = Pastel.new
+        end
+
+        # Format analysis results showing optimization opportunities
+        #
+        # @param agent_name [String] Name of the agent
+        # @param opportunities [Array<Hash>] Optimization opportunities
+        # @return [String] Formatted output
+        def format_analysis(agent_name:, opportunities:)
+          output = []
+          output << ''
+          output << @pastel.bold("Analyzing agent '#{agent_name}'...")
+          output << @pastel.dim('─' * 70)
+          output << ''
+
+          if opportunities.empty?
+            output << @pastel.yellow('No optimization opportunities found.')
+            output << ''
+            output << 'Possible reasons:'
+            output << '  • All tasks are already symbolic'
+            output << "  • Neural tasks haven't executed enough times (need 10+)"
+            output << '  • Execution patterns are too inconsistent (<85%)'
+            output << ''
+            return output.join("\n")
+          end
+
+          # Group by status
+          ready = opportunities.select { |opp| opp[:ready_for_learning] }
+          not_ready = opportunities.reject { |opp| opp[:ready_for_learning] }
+
+          output << @pastel.bold("Found #{opportunities.size} neural task(s)\n")
+
+          # Show ready tasks
+          if ready.any?
+            output << @pastel.green.bold("✓ Ready for Optimization (#{ready.size})")
+            output << ''
+            ready.each do |opp|
+              output << format_opportunity(opp, ready: true)
+              output << ''
+            end
+          end
+
+          # Show not ready tasks
+          if not_ready.any?
+            output << @pastel.yellow.bold("⚠ Not Ready (#{not_ready.size})")
+            output << ''
+            not_ready.each do |opp|
+              output << format_opportunity(opp, ready: false)
+              output << ''
+            end
+          end
+
+          # Summary
+          output << @pastel.dim('─' * 70)
+          output << if ready.any?
+                      @pastel.green.bold("#{ready.size}/#{opportunities.size} tasks eligible for optimization")
+                    else
+                      @pastel.yellow("0/#{opportunities.size} tasks ready - check requirements above")
+                    end
+          output << ''
+
+          output.join("\n")
+        end
+
+        # Format a single optimization opportunity
+        #
+        # @param opp [Hash] Opportunity data
+        # @param ready [Boolean] Whether task is ready for optimization
+        # @return [String] Formatted output
+        def format_opportunity(opp, ready:)
+          output = []
+
+          # Task name
+          status_icon = ready ? @pastel.green('✓') : @pastel.yellow('⚠')
+          output << "  #{status_icon} #{@pastel.bold(opp[:task_name])}"
+
+          # Metrics
+          exec_label = @pastel.dim('    Executions:')
+          exec_value = format_count_status(opp[:execution_count], 10, ready)
+          output << "#{exec_label} #{exec_value}"
+
+          cons_label = @pastel.dim('    Consistency:')
+          cons_value = format_percentage_status(opp[:consistency_score], 0.85, ready)
+          output << "#{cons_label} #{cons_value}"
+
+          # Pattern or reason
+          if ready && opp[:common_pattern]
+            output << "#{@pastel.dim('    Pattern:')} #{opp[:common_pattern]}"
+          elsif opp[:reason]
+            output << "#{@pastel.dim('    Reason:')} #{@pastel.yellow(opp[:reason])}"
+          end
+
+          output.join("\n")
+        end
+
+        # Format optimization proposal with diff and metrics
+        #
+        # @param proposal [Hash] Proposal data
+        # @return [String] Formatted output
+        def format_proposal(proposal:)
+          output = []
+          output << ''
+          output << @pastel.bold("Optimization Proposal: #{proposal[:task_name]}")
+          output << @pastel.dim('=' * 70)
+          output << ''
+
+          # Current code
+          output << @pastel.yellow.bold('Current (Neural):')
+          output << @pastel.dim('─' * 70)
+          proposal[:current_code].each_line do |line|
+            output << @pastel.yellow("  #{line.rstrip}")
+          end
+          output << ''
+
+          # Proposed code
+          output << @pastel.green.bold('Proposed (Symbolic):')
+          output << @pastel.dim('─' * 70)
+          proposal[:proposed_code].each_line do |line|
+            output << @pastel.green("  #{line.rstrip}")
+          end
+          output << ''
+
+          # Performance impact
+          output << @pastel.bold('Performance Impact:')
+          output << @pastel.dim('─' * 70)
+          impact = proposal[:performance_impact]
+          output << format_impact_line('Execution Time:', impact[:current_avg_time], impact[:optimized_avg_time], 's', impact[:time_reduction_pct])
+          output << format_impact_line('Cost Per Call:', impact[:current_avg_cost], impact[:optimized_avg_cost], '$', impact[:cost_reduction_pct])
+          output << ''
+          output << "  #{@pastel.dim('Projected Monthly Savings:')} #{@pastel.green.bold("$#{impact[:projected_monthly_savings]}")}"
+          output << ''
+
+          # Metadata
+          output << @pastel.bold('Analysis:')
+          output << @pastel.dim('─' * 70)
+          output << "  #{@pastel.dim('Executions Observed:')} #{proposal[:execution_count]}"
+          output << "  #{@pastel.dim('Pattern Consistency:')} #{format_percentage(proposal[:consistency_score])}"
+          output << "  #{@pastel.dim('Tool Sequence:')} #{proposal[:pattern]}"
+          output << "  #{@pastel.dim('Validation:')} #{proposal[:validation_violations].empty? ? @pastel.green('✓ Passed') : @pastel.red('✗ Failed')}"
+          output << ''
+
+          output.join("\n")
+        end
+
+        # Format success message after applying optimization
+        #
+        # @param result [Hash] Application result
+        # @return [String] Formatted output
+        def format_success(result:)
+          output = []
+          output << ''
+
+          if result[:success]
+            output << @pastel.green.bold('✓ Optimization applied successfully!')
+            output << ''
+            output << "  Task '#{result[:task_name]}' has been optimized to symbolic execution."
+            output << ''
+            output << @pastel.dim('Next steps:')
+            output << "  • Monitor performance: aictl agent logs #{result[:task_name]}"
+            output << "  • View changes: aictl agent code #{result[:task_name]}"
+          else
+            output << @pastel.red.bold('✗ Optimization failed!')
+            output << ''
+            output << "  Task: #{result[:task_name]}"
+            output << "  Error: #{result[:error]}"
+          end
+
+          output << ''
+          output.join("\n")
+        end
+
+        private
+
+        # Format a count with status indicator
+        def format_count_status(count, threshold, ready)
+          if count >= threshold
+            @pastel.green("#{count} (≥#{threshold})")
+          else
+            ready ? @pastel.yellow("#{count}/#{threshold}") : @pastel.red("#{count}/#{threshold}")
+          end
+        end
+
+        # Format a percentage with status indicator
+        def format_percentage_status(score, threshold, ready)
+          return @pastel.red('N/A') if score.nil?
+
+          pct = (score * 100).round(1)
+          threshold_pct = (threshold * 100).round(1)
+
+          if score >= threshold
+            @pastel.green("#{pct}% (≥#{threshold_pct}%)")
+          else
+            ready ? @pastel.yellow("#{pct}%/#{threshold_pct}%") : @pastel.red("#{pct}%/#{threshold_pct}%")
+          end
+        end
+
+        # Format percentage value
+        def format_percentage(score)
+          return @pastel.red('N/A') if score.nil?
+
+          pct = (score * 100).round(1)
+          @pastel.green("#{pct}%")
+        end
+
+        # Format performance impact line
+        def format_impact_line(label, current, optimized, unit, reduction_pct)
+          current_str = unit == '$' ? format('$%.4f', current) : "#{current}#{unit}"
+          optimized_str = unit == '$' ? format('$%.4f', optimized) : "#{optimized}#{unit}"
+
+          "  #{@pastel.dim(label)} #{current_str} → #{@pastel.green(optimized_str)} " \
+            "#{@pastel.green("(#{reduction_pct}% faster)")}"
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/cli/formatters/progress_formatter.rb

@@ -48,7 +48,7 @@ module LanguageOperator
           end
 
           def warn(message)
-            puts "#{pastel.yellow.bold(LogStyle.icon(:warn))} #{message}"
+            puts "#{LogStyle.styled_icon(:warn, pastel)} #{pastel.bold(message)}"
           end
         end
       end

data/lib/language_operator/client/base.rb

@@ -115,9 +115,18 @@ module LanguageOperator
 
       # Get all available tools from connected servers
       #
-      # @return [Array] Array of tool objects
+      # Wraps MCP tools with OpenTelemetry instrumentation to trace tool executions.
+      #
+      # @return [Array] Array of instrumented tool objects
       def tools
-        @clients.flat_map(&:tools)
+        raw_tools = @clients.flat_map(&:tools)
+
+        # Wrap each tool with instrumentation if telemetry is enabled
+        if ENV.fetch('OTEL_EXPORTER_OTLP_ENDPOINT', nil)
+          raw_tools.map { |tool| wrap_tool_with_instrumentation(tool) }
+        else
+          raw_tools
+        end
       end
 
       # Get information about connected servers
@@ -165,6 +174,67 @@ module LanguageOperator
         'Client'
       end
 
+      # Wrap an MCP tool with OpenTelemetry instrumentation
+      #
+      # Creates a wrapper that traces tool executions with proper semantic conventions.
+      # The wrapper preserves the original tool's interface while adding telemetry.
+      #
+      # @param tool [Object] Original MCP tool object
+      # @return [Object] Instrumented tool wrapper
+      def wrap_tool_with_instrumentation(tool)
+        # Create a new tool object that wraps the original
+        tool_wrapper = Object.new
+        tool_wrapper.define_singleton_method(:name) { tool.name }
+        tool_wrapper.define_singleton_method(:description) { tool.description }
+        tool_wrapper.define_singleton_method(:parameters) { tool.parameters }
+        tool_wrapper.define_singleton_method(:params_schema) { tool.params_schema }
+        tool_wrapper.define_singleton_method(:provider_params) { tool.provider_params }
+
+        # Wrap the call method with instrumentation
+        original_tool = tool
+        tool_wrapper.define_singleton_method(:call) do |arguments|
+          # Get current OpenTelemetry context at call time (not definition time)
+          # This ensures we pick up the active span from the task execution
+          tracer = OpenTelemetry.tracer_provider.tracer('language-operator')
+          tool_name = original_tool.name
+
+          # Get current span to check if we have a parent
+          current_span = OpenTelemetry::Trace.current_span
+          current_span_context = current_span.context if current_span
+
+          # Log trace ID for debugging
+          if current_span_context&.valid?
+            trace_id = current_span_context.hex_trace_id
+            LanguageOperator.logger.debug('Tool call with parent trace', tool: tool_name, trace_id: trace_id) if defined?(LanguageOperator.logger)
+          elsif defined?(LanguageOperator.logger)
+            LanguageOperator.logger.debug('Tool call without parent trace', tool: tool_name)
+          end
+
+          # Create span in the current context - this will automatically attach to
+          # the active span if one exists
+          tracer.in_span("execute_tool.#{tool_name}", attributes: {
+                           'gen_ai.operation.name' => 'execute_tool',
+                           'gen_ai.tool.name' => tool_name,
+                           'gen_ai.tool.call.arguments.size' => arguments.to_json.bytesize
+                         }) do |span|
+            # Execute the original tool
+            result = original_tool.call(arguments)
+
+            # Record the result size
+            result_str = result.is_a?(String) ? result : result.to_json
+            span.set_attribute('gen_ai.tool.call.result.size', result_str.bytesize)
+
+            result
+          rescue StandardError => e
+            span.record_exception(e)
+            span.status = OpenTelemetry::Trace::Status.error("Tool execution failed: #{e.message}")
+            raise
+          end
+        end
+
+        tool_wrapper
+      end
+
       # Configure RubyLLM with provider settings
       #
       # @raise [RuntimeError] If provider is unknown

data/lib/language_operator/client/mcp_connector.rb

@@ -12,8 +12,6 @@ module LanguageOperator
       def connect_mcp_servers
         enabled_servers = @config['mcp_servers'].select { |s| s['enabled'] }
 
-        all_tools = []
-
         if enabled_servers.empty?
           logger.info('No MCP servers configured, agent will run without tools')
         else
@@ -25,7 +23,6 @@ module LanguageOperator
 
             @clients << client
             tool_count = client.tools.length
-            all_tools.concat(client.tools)
 
             # Debug: inspect tool objects
             if @debug
@@ -50,18 +47,22 @@ module LanguageOperator
           end
 
           logger.info('MCP connection summary',
-                      connected_servers: @clients.length,
-                      total_tools: all_tools.length)
+                      connected_servers: @clients.length)
         end
 
         # Create chat with all collected tools (even if empty)
+        # Use the tools() method which applies OpenTelemetry instrumentation wrapping
         llm_config = @config['llm']
         chat_params = build_chat_params(llm_config)
         @chat = RubyLLM.chat(**chat_params)
 
+        all_tools = tools
         @chat.with_tools(*all_tools) unless all_tools.empty?
 
-        logger.info('Chat session initialized', with_tools: !all_tools.empty?)
+        # Set up callbacks to log tool invocations
+        setup_tool_callbacks
+
+        logger.info('Chat session initialized', with_tools: !all_tools.empty?, total_tools: all_tools.length)
       end
 
       # Connect to MCP server with exponential backoff retry logic
@@ -125,6 +126,27 @@ module LanguageOperator
 
         chat_params
       end
+
+      # Set up callbacks to log tool calls and results
+      #
+      # @return [void]
+      def setup_tool_callbacks
+        @chat.on_tool_call do |tool_call|
+          logger.info('Tool call initiated by LLM',
+                      event: 'tool_call_initiated',
+                      tool_name: tool_call.name,
+                      tool_id: tool_call.id,
+                      arguments: tool_call.arguments,
+                      arguments_json: tool_call.arguments.to_json)
+        end
+
+        @chat.on_tool_result do |result|
+          logger.info('Tool call result received',
+                      event: 'tool_result_received',
+                      result: result,
+                      result_preview: result.to_s[0..500])
+        end
+      end
     end
   end
 end

data/lib/language_operator/instrumentation/task_tracer.rb

@@ -26,6 +26,7 @@ module LanguageOperator
     #   Instrumentation adds <5% overhead with default settings
     #   Overhead may increase to ~10% with full data capture enabled
     #
+    # rubocop:disable Metrics/ModuleLength
     module TaskTracer
       # Maximum length for captured data before truncation
       MAX_CAPTURED_LENGTH = 1000
@@ -169,6 +170,11 @@ module LanguageOperator
         return unless response.respond_to?(:tool_calls)
         return unless response.tool_calls&.any?
 
+        logger&.info('Tool calls detected in LLM response',
+                     event: 'tool_calls_detected',
+                     tool_call_count: response.tool_calls.length,
+                     tool_names: response.tool_calls.map { |tc| extract_tool_name(tc) })
+
         response.tool_calls.each do |tool_call|
           record_single_tool_call(tool_call, parent_span)
         end
@@ -182,11 +188,26 @@ module LanguageOperator
       # @param parent_span [OpenTelemetry::Trace::Span] Parent span
       def record_single_tool_call(tool_call, _parent_span)
         tool_name = extract_tool_name(tool_call)
+        tool_id = tool_call.respond_to?(:id) ? tool_call.id : nil
+
+        # Extract and log tool arguments
+        arguments = extract_tool_arguments(tool_call)
 
+        logger&.info('Tool invoked by LLM',
+                     event: 'tool_call_invoked',
+                     tool_name: tool_name,
+                     tool_id: tool_id,
+                     arguments: arguments,
+                     arguments_json: (arguments.is_a?(Hash) ? JSON.generate(arguments) : arguments.to_s))
+
+        start_time = Time.now
         tracer.in_span("execute_tool #{tool_name}", attributes: build_tool_call_attributes(tool_call)) do |tool_span|
           # Tool execution already completed by ruby_llm
           # Just record the metadata
-          record_tool_result(tool_call.result, tool_span) if tool_call.respond_to?(:result) && tool_call.result
+          if tool_call.respond_to?(:result) && tool_call.result
+            duration_ms = ((Time.now - start_time) * 1000).round(2)
+            record_tool_result(tool_call.result, tool_span, tool_name, tool_id, duration_ms)
+          end
         end
       rescue StandardError => e
         logger&.warn('Failed to record tool call span', error: e.message, tool: tool_name)
@@ -206,6 +227,34 @@ module LanguageOperator
         end
       end
 
+      # Extract tool arguments from tool call object
+      #
+      # @param tool_call [Object] Tool call object
+      # @return [Hash, String] Tool arguments
+      def extract_tool_arguments(tool_call)
+        if tool_call.respond_to?(:arguments)
+          args = tool_call.arguments
+          parse_json_args(args)
+        elsif tool_call.respond_to?(:function) && tool_call.function.respond_to?(:arguments)
+          args = tool_call.function.arguments
+          parse_json_args(args)
+        else
+          {}
+        end
+      end
+
+      # Parse JSON arguments safely
+      #
+      # @param args [String, Object] Arguments to parse
+      # @return [Hash, String] Parsed arguments or original
+      def parse_json_args(args)
+        return args unless args.is_a?(String)
+
+        JSON.parse(args)
+      rescue JSON::ParserError
+        args
+      end
+
       # Build attributes for tool call span
       #
       # @param tool_call [Object] Tool call object
@@ -244,13 +293,25 @@ module LanguageOperator
       #
       # @param result [Object] Tool call result
       # @param span [OpenTelemetry::Trace::Span] The span to update
-      def record_tool_result(result, span)
+      # @param tool_name [String] Tool name (for logging)
+      # @param tool_id [String] Tool call ID (for logging)
+      # @param duration_ms [Float] Execution duration in milliseconds (for logging)
+      def record_tool_result(result, span, tool_name = nil, tool_id = nil, duration_ms = nil)
         result_str = result.is_a?(String) ? result : JSON.generate(result)
         span.set_attribute('gen_ai.tool.call.result.size', result_str.bytesize)
 
         if (sanitized_result = sanitize_data(result, :tool_results))
           span.set_attribute('gen_ai.tool.call.result', sanitized_result)
         end
+
+        # Log tool execution completion
+        logger&.info('Tool execution completed',
+                     event: 'tool_call_completed',
+                     tool_name: tool_name,
+                     tool_id: tool_id,
+                     result_size: result_str.bytesize,
+                     result: sanitize_data(result, :tool_results),
+                     duration_ms: duration_ms)
       rescue StandardError => e
         logger&.warn('Failed to record tool result', error: e.message)
       end
@@ -281,5 +342,6 @@ module LanguageOperator
         logger&.warn('Failed to record output metadata', error: e.message)
       end
     end
+    # rubocop:enable Metrics/ModuleLength
   end
 end

data/lib/language_operator/kubernetes/resource_builder.rb

@@ -25,7 +25,7 @@ module LanguageOperator
 
         # Build a LanguageAgent resource
         def language_agent(name, instructions:, cluster: nil, schedule: nil, persona: nil, tools: [], models: [],
-                           mode: nil, labels: {})
+                           mode: nil, workspace: true, labels: {})
           # Determine mode: reactive, scheduled, or autonomous
           spec_mode = mode || (schedule ? 'scheduled' : 'autonomous')
 
@@ -41,6 +41,8 @@ module LanguageOperator
           spec['toolRefs'] = tools.map { |t| { 'name' => t } } unless tools.empty?
           # Convert model names to modelRef objects
           spec['modelRefs'] = models.map { |m| { 'name' => m } } unless models.empty?
+          # Enable workspace by default for state persistence
+          spec['workspace'] = { 'enabled' => workspace } if workspace
 
           {
             'apiVersion' => 'langop.io/v1alpha1',

data/lib/language_operator/learning/adapters/base_adapter.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  module Learning
+    module Adapters
+      # Abstract base class for OTLP backend query adapters
+      #
+      # Defines the interface that all backend adapters must implement.
+      # Adapters translate generic query requests into backend-specific
+      # API calls and normalize responses.
+      #
+      # @example Implementing a custom adapter
+      #   class CustomAdapter < BaseAdapter
+      #     def self.available?(endpoint, api_key = nil)
+      #       # Check if backend is reachable
+      #       true
+      #     end
+      #
+      #     def query_spans(filter:, time_range:, limit:)
+      #       # Query backend and return normalized spans
+      #       []
+      #     end
+      #   end
+      class BaseAdapter
+        # Initialize adapter with connection details
+        #
+        # @param endpoint [String] Backend endpoint URL
+        # @param api_key [String, nil] API key for authentication (if required)
+        # @param options [Hash] Additional adapter-specific options
+        def initialize(endpoint, api_key = nil, **options)
+          @endpoint = endpoint
+          @api_key = api_key
+          @logger = options[:logger] || ::Logger.new($stdout, level: ::Logger::WARN)
+          @options = options
+        end
+
+        # Check if this backend is available at the given endpoint
+        #
+        # @param endpoint [String] Backend endpoint URL
+        # @param api_key [String, nil] API key for authentication (optional)
+        # @return [Boolean] True if backend is reachable and compatible
+        def self.available?(endpoint, api_key = nil)
+          raise NotImplementedError, "#{self}.available? must be implemented"
+        end
+
+        # Query spans from the backend
+        #
+        # @param filter [Hash] Filter criteria
+        # @option filter [String] :task_name Task name to filter by
+        # @option filter [Hash] :attributes Additional span attributes to match
+        # @param time_range [Range<Time>] Time range for query
+        # @param limit [Integer] Maximum number of spans to return
+        # @return [Array<Hash>] Array of normalized span hashes
+        def query_spans(filter:, time_range:, limit:)
+          raise NotImplementedError, "#{self.class}#query_spans must be implemented"
+        end
+
+        # Extract task execution data from spans
+        #
+        # Groups spans by trace and extracts task-specific metadata:
+        # - inputs: Task input parameters
+        # - outputs: Task output values
+        # - tool_calls: Sequence of tools invoked
+        # - duration: Execution duration
+        #
+        # @param spans [Array<Hash>] Raw spans from backend
+        # @return [Array<Hash>] Task execution data grouped by trace
+        def extract_task_data(spans)
+          spans.group_by { |span| span[:trace_id] }.map do |trace_id, trace_spans|
+            task_span = trace_spans.find { |s| s[:name]&.include?('task_executor') }
+            next unless task_span
+
+            {
+              trace_id: trace_id,
+              task_name: task_span.dig(:attributes, 'task.name'),
+              inputs: extract_inputs(task_span),
+              outputs: extract_outputs(task_span),
+              tool_calls: extract_tool_calls(trace_spans),
+              duration_ms: task_span[:duration_ms],
+              timestamp: task_span[:timestamp]
+            }
+          end.compact
+        end
+
+        protected
+
+        attr_reader :endpoint, :api_key, :options
+
+        # Extract inputs from task span attributes
+        #
+        # @param span [Hash] Task execution span
+        # @return [Hash] Input parameters
+        def extract_inputs(span)
+          attrs = span[:attributes] || {}
+          input_keys = attrs['task.input.keys']&.split(',') || []
+
+          input_keys.each_with_object({}) do |key, inputs|
+            value_attr = "task.input.#{key}"
+            inputs[key.to_sym] = attrs[value_attr] if attrs[value_attr]
+          end
+        end
+
+        # Extract outputs from task span attributes
+        #
+        # @param span [Hash] Task execution span
+        # @return [Hash] Output values
+        def extract_outputs(span)
+          attrs = span[:attributes] || {}
+          output_keys = attrs['task.output.keys']&.split(',') || []
+
+          output_keys.each_with_object({}) do |key, outputs|
+            value_attr = "task.output.#{key}"
+            outputs[key.to_sym] = attrs[value_attr] if attrs[value_attr]
+          end
+        end
+
+        # Extract tool call sequence from trace spans
+        #
+        # @param trace_spans [Array<Hash>] All spans in trace
+        # @return [Array<Hash>] Ordered tool call sequence
+        def extract_tool_calls(trace_spans)
+          trace_spans
+            .select { |s| s.dig(:attributes, 'gen_ai.operation.name') == 'execute_tool' }
+            .sort_by { |s| s[:timestamp] }
+            .map do |tool_span|
+              {
+                tool_name: tool_span.dig(:attributes, 'gen_ai.tool.name'),
+                arguments_size: tool_span.dig(:attributes, 'gen_ai.tool.call.arguments.size'),
+                result_size: tool_span.dig(:attributes, 'gen_ai.tool.call.result.size')
+              }
+            end
+        end
+
+        # Parse time range into backend-specific format
+        #
+        # @param time_range [Range<Time>] Time range
+        # @return [Hash] Start and end times
+        def parse_time_range(time_range)
+          {
+            start: time_range.begin || (Time.now - (24 * 60 * 60)),
+            end: time_range.end || Time.now
+          }
+        end
+      end
+    end
+  end
+end