language-operator 0.1.58 → 0.1.61

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

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+require_relative 'base_adapter'
+
+module LanguageOperator
+  module Learning
+    module Adapters
+      # Grafana Tempo backend adapter for trace queries
+      #
+      # Queries Tempo's Parquet-backed trace storage via the /api/search
+      # HTTP endpoint with TraceQL query language support.
+      #
+      # TraceQL provides powerful span filtering with structural operators:
+      # - { span.attribute = "value" } - Basic attribute filtering
+      # - { span.foo = "bar" && span.baz > 100 } - Multiple conditions
+      # - { span.parent } >> { span.child } - Structural relationships
+      #
+      # @example Basic usage
+      #   adapter = TempoAdapter.new('http://tempo:3200')
+      #
+      #   spans = adapter.query_spans(
+      #     filter: { task_name: 'fetch_data' },
+      #     time_range: (Time.now - 3600)..Time.now,
+      #     limit: 100
+      #   )
+      class TempoAdapter < BaseAdapter
+        # Tempo search endpoint
+        SEARCH_PATH = '/api/search'
+
+        # Check if Tempo is available at endpoint
+        #
+        # @param endpoint [String] Tempo endpoint URL
+        # @param _api_key [String, nil] API key (unused, Tempo typically doesn't require auth)
+        # @return [Boolean] True if Tempo API is reachable
+        def self.available?(endpoint, _api_key = nil)
+          uri = URI.join(endpoint, SEARCH_PATH)
+          # Test with minimal query
+          uri.query = URI.encode_www_form(q: '{ }', limit: 1)
+
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', open_timeout: 2, read_timeout: 2) do |http|
+            request = Net::HTTP::Get.new(uri.request_uri)
+            http.request(request)
+          end
+
+          response.is_a?(Net::HTTPSuccess)
+        rescue StandardError
+          false
+        end
+
+        # Query spans from Tempo using TraceQL
+        #
+        # @param filter [Hash] Filter criteria
+        # @option filter [String] :task_name Task name to filter by
+        # @param time_range [Range<Time>] Time range for query
+        # @param limit [Integer] Maximum traces to return
+        # @return [Array<Hash>] Normalized span data
+        def query_spans(filter:, time_range:, limit:)
+          times = parse_time_range(time_range)
+          traceql_query = build_traceql_query(filter)
+          traces = search_traces(traceql_query, times, limit)
+          extract_spans_from_traces(traces)
+        end
+
+        private
+
+        # Build TraceQL query from filter
+        #
+        # @param filter [Hash] Filter criteria
+        # @return [String] TraceQL query string
+        def build_traceql_query(filter)
+          conditions = []
+
+          # Filter by task name
+          conditions << "span.\"task.name\" = \"#{escape_traceql_value(filter[:task_name])}\"" if filter[:task_name]
+
+          # Filter by agent name
+          conditions << "span.\"agent.name\" = \"#{escape_traceql_value(filter[:agent_name])}\"" if filter[:agent_name]
+
+          # Additional attribute filters
+          if filter[:attributes].is_a?(Hash)
+            filter[:attributes].each do |key, value|
+              conditions << "span.\"#{escape_traceql_key(key)}\" = \"#{escape_traceql_value(value)}\""
+            end
+          end
+
+          # Combine conditions with AND
+          query = conditions.any? ? conditions.join(' && ') : ''
+          "{ #{query} }"
+        end
+
+        # Escape TraceQL attribute key
+        #
+        # @param key [String, Symbol] Attribute key
+        # @return [String] Escaped key
+        def escape_traceql_key(key)
+          key.to_s.gsub('"', '\"')
+        end
+
+        # Escape TraceQL value
+        #
+        # @param value [Object] Attribute value
+        # @return [String] Escaped value
+        def escape_traceql_value(value)
+          value.to_s.gsub('"', '\"').gsub('\\', '\\\\')
+        end
+
+        # Search traces via Tempo HTTP API
+        #
+        # @param traceql_query [String] TraceQL query
+        # @param times [Hash] Start and end times
+        # @param limit [Integer] Result limit
+        # @return [Array<Hash>] Trace data
+        def search_traces(traceql_query, times, limit)
+          uri = build_search_uri(traceql_query, times, limit)
+
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', open_timeout: 5, read_timeout: 30) do |http|
+            request = Net::HTTP::Get.new(uri.request_uri)
+            request['Accept'] = 'application/json'
+
+            response = http.request(request)
+
+            raise "Tempo query failed: #{response.code} #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+
+            result = JSON.parse(response.body, symbolize_names: true)
+            result[:traces] || []
+          end
+        end
+
+        # Build Tempo search URI with query parameters
+        #
+        # @param traceql_query [String] TraceQL query
+        # @param times [Hash] Start and end times
+        # @param limit [Integer] Result limit
+        # @return [URI] Complete URI with query params
+        def build_search_uri(traceql_query, times, limit)
+          params = {
+            q: traceql_query,
+            limit: limit,
+            start: times[:start].to_i, # Unix seconds
+            end: times[:end].to_i
+          }
+
+          uri = URI.join(@endpoint, SEARCH_PATH)
+          uri.query = URI.encode_www_form(params)
+          uri
+        end
+
+        # Extract all spans from traces
+        #
+        # @param traces [Array<Hash>] Tempo trace data
+        # @return [Array<Hash>] Normalized spans
+        def extract_spans_from_traces(traces)
+          spans = []
+
+          traces.each do |trace|
+            trace_id = trace[:traceID]
+
+            # Tempo returns spanSets (matched span groups)
+            (trace[:spanSets] || []).each do |span_set|
+              (span_set[:spans] || []).each do |span_data|
+                spans << normalize_span(span_data, trace_id)
+              end
+            end
+          end
+
+          spans
+        end
+
+        # Normalize Tempo span to common format
+        #
+        # @param span_data [Hash] Raw Tempo span
+        # @param trace_id [String] Trace ID
+        # @return [Hash] Normalized span
+        def normalize_span(span_data, trace_id)
+          {
+            span_id: span_data[:spanID],
+            trace_id: trace_id,
+            name: span_data[:name] || 'unknown',
+            timestamp: parse_timestamp(span_data[:startTimeUnixNano]),
+            duration_ms: parse_duration(span_data[:durationNanos]),
+            attributes: parse_attributes(span_data[:attributes])
+          }
+        end
+
+        # Parse Tempo timestamp (nanoseconds) to Time
+        #
+        # @param timestamp [String, Integer] Timestamp in nanoseconds
+        # @return [Time] Parsed time
+        def parse_timestamp(timestamp)
+          return Time.now unless timestamp
+
+          nanos = timestamp.is_a?(String) ? timestamp.to_i : timestamp
+          Time.at(nanos / 1_000_000_000.0)
+        end
+
+        # Parse Tempo duration (nanoseconds) to milliseconds
+        #
+        # @param duration [Integer] Duration in nanoseconds
+        # @return [Float] Duration in milliseconds
+        def parse_duration(duration)
+          return 0.0 unless duration
+
+          duration / 1_000_000.0
+        end
+
+        # Parse Tempo attributes into flat hash
+        #
+        # Tempo attributes format:
+        # [
+        #   { key: "http.method", value: { stringValue: "GET" } },
+        #   { key: "http.status_code", value: { intValue: 200 } }
+        # ]
+        #
+        # @param attributes [Array<Hash>] Attribute array
+        # @return [Hash] Flat attributes
+        def parse_attributes(attributes)
+          return {} unless attributes.is_a?(Array)
+
+          attributes.each_with_object({}) do |attr, hash|
+            key = attr[:key].to_s
+            value_obj = attr[:value] || {}
+
+            # Extract value based on type
+            value = value_obj[:stringValue] ||
+                    value_obj[:intValue] ||
+                    value_obj[:doubleValue] ||
+                    value_obj[:boolValue] ||
+                    value_obj[:bytesValue]
+
+            hash[key] = value if value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/learning/optimizer.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module LanguageOperator
+  module Learning
+    # Orchestrates the optimization of neural tasks to symbolic implementations
+    #
+    # The Optimizer analyzes running agents, identifies optimization opportunities,
+    # proposes code changes, and applies them with user approval. It integrates
+    # TraceAnalyzer (pattern detection) and PatternDetector (code generation) to
+    # provide a complete optimization workflow.
+    #
+    # @example Basic usage
+    #   optimizer = Optimizer.new(
+    #     agent_name: 'github-monitor',
+    #     agent_definition: agent_def,
+    #     trace_analyzer: TraceAnalyzer.new(endpoint: ENV['OTEL_QUERY_ENDPOINT']),
+    #     pattern_detector: PatternDetector.new(...)
+    #   )
+    #
+    #   opportunities = optimizer.analyze
+    #   opportunities.each do |opp|
+    #     proposal = optimizer.propose(task_name: opp[:task_name])
+    #     # Show to user, get approval
+    #     optimizer.apply(proposal) if approved
+    #   end
+    class Optimizer
+      # Minimum consistency score required for optimization
+      DEFAULT_MIN_CONSISTENCY = 0.85
+
+      # Minimum executions required for optimization
+      DEFAULT_MIN_EXECUTIONS = 10
+
+      # Initialize optimizer
+      #
+      # @param agent_name [String] Name of the agent to optimize
+      # @param agent_definition [Dsl::AgentDefinition] Agent definition object
+      # @param trace_analyzer [TraceAnalyzer] Analyzer for querying execution traces
+      # @param pattern_detector [PatternDetector] Detector for generating symbolic code
+      # @param task_synthesizer [TaskSynthesizer, nil] Optional LLM-based synthesizer
+      # @param logger [Logger, nil] Logger instance (creates default if nil)
+      def initialize(agent_name:, agent_definition:, trace_analyzer:, pattern_detector:, task_synthesizer: nil,
+                     logger: nil)
+        @agent_name = agent_name
+        @agent_definition = agent_definition
+        @trace_analyzer = trace_analyzer
+        @pattern_detector = pattern_detector
+        @task_synthesizer = task_synthesizer
+        @logger = logger || ::Logger.new($stdout, level: ::Logger::WARN)
+      end
+
+      # Analyze agent for optimization opportunities
+      #
+      # Queries execution traces for each neural task and determines which tasks
+      # are eligible for optimization based on consistency and execution count.
+      #
+      # @param min_consistency [Float] Minimum consistency threshold (0.0-1.0)
+      # @param min_executions [Integer] Minimum execution count required
+      # @param time_range [Integer, Range<Time>, nil] Time range for trace queries
+      # @return [Array<Hash>] Array of optimization opportunities
+      def analyze(min_consistency: DEFAULT_MIN_CONSISTENCY, min_executions: DEFAULT_MIN_EXECUTIONS, time_range: nil)
+        opportunities = []
+
+        # Find all neural tasks in the agent
+        neural_tasks = find_neural_tasks
+
+        if neural_tasks.empty?
+          @logger.info("No neural tasks found in agent '#{@agent_name}'")
+          return opportunities
+        end
+
+        # Analyze each neural task
+        neural_tasks.each do |task|
+          analysis = @trace_analyzer.analyze_patterns(
+            task_name: task[:name],
+            agent_name: @agent_name,
+            min_executions: min_executions,
+            consistency_threshold: min_consistency,
+            time_range: time_range
+          )
+
+          next unless analysis
+
+          opportunities << {
+            task_name: task[:name],
+            task_definition: task[:definition],
+            execution_count: analysis[:execution_count],
+            consistency_score: analysis[:consistency_score],
+            ready_for_learning: analysis[:ready_for_learning],
+            common_pattern: analysis[:common_pattern],
+            reason: analysis[:reason]
+          }
+        end
+
+        opportunities
+      end
+
+      # Generate optimization proposal for a specific task
+      #
+      # Uses PatternDetector to generate symbolic code and calculates
+      # the performance impact of the optimization. Falls back to TaskSynthesizer
+      # (LLM-based) if pattern detection fails and synthesizer is available.
+      #
+      # @param task_name [String] Name of task to optimize
+      # @param use_synthesis [Boolean] Force use of LLM synthesis instead of pattern detection
+      # @return [Hash] Optimization proposal with code, metrics, and metadata
+      def propose(task_name:, use_synthesis: false)
+        task_def = find_task_definition(task_name)
+        raise ArgumentError, "Task '#{task_name}' not found" unless task_def
+
+        analysis = @trace_analyzer.analyze_patterns(task_name: task_name, agent_name: @agent_name)
+        raise ArgumentError, "No execution data found for task '#{task_name}'" unless analysis
+
+        traces = @trace_analyzer.query_task_traces(task_name: task_name, agent_name: @agent_name, limit: 20)
+        detection_result = @pattern_detector.detect_pattern(analysis_result: analysis) unless use_synthesis
+
+        return propose_via_synthesis(task_name, task_def, analysis, traces) if should_use_synthesis?(use_synthesis, detection_result)
+
+        unless detection_result&.dig(:success)
+          raise ArgumentError, "Cannot optimize task '#{task_name}': #{detection_result&.dig(:reason) || 'No common pattern found'}"
+        end
+
+        build_pattern_proposal(task_name, task_def, analysis, detection_result)
+      end
+
+      # Apply optimization proposal
+      #
+      # This method would update the agent definition in Kubernetes.
+      # For now, it returns the updated agent code that would be applied.
+      #
+      # @param proposal [Hash] Proposal from #propose
+      # @return [Hash] Result with updated agent definition
+      def apply(proposal:)
+        # In a real implementation, this would:
+        # 1. Update the agent CRD with new task definition
+        # 2. Create new ConfigMap version
+        # 3. Trigger pod restart
+        # For now, we return what would be applied
+
+        {
+          success: true,
+          task_name: proposal[:task_name],
+          updated_code: proposal[:proposed_code],
+          action: 'would_update_agent_definition',
+          message: "Optimization for '#{proposal[:task_name]}' ready to apply"
+        }
+      end
+
+      private
+
+      def should_use_synthesis?(use_synthesis, detection_result)
+        (use_synthesis || !detection_result&.dig(:success)) && @task_synthesizer
+      end
+
+      def propose_via_synthesis(task_name, task_def, analysis, traces)
+        @logger.info("Using LLM synthesis for task '#{task_name}'")
+        synthesis_result = @task_synthesizer.synthesize(
+          task_definition: task_def,
+          traces: traces,
+          available_tools: detect_available_tools,
+          consistency_score: analysis[:consistency_score],
+          common_pattern: analysis[:common_pattern]
+        )
+
+        raise ArgumentError, "Cannot optimize task '#{task_name}': #{synthesis_result[:explanation]}" unless synthesis_result[:is_deterministic]
+
+        build_synthesis_proposal(task_name: task_name, task_def: task_def, analysis: analysis,
+                                 synthesis_result: synthesis_result)
+      end
+
+      def build_pattern_proposal(task_name, task_def, analysis, detection_result)
+        impact = calculate_impact(execution_count: analysis[:execution_count],
+                                  consistency_score: analysis[:consistency_score])
+        {
+          task_name: task_name, current_code: format_current_code(task_def),
+          proposed_code: extract_task_code(detection_result[:generated_code]),
+          full_generated_code: detection_result[:generated_code],
+          consistency_score: analysis[:consistency_score], execution_count: analysis[:execution_count],
+          pattern: analysis[:common_pattern], performance_impact: impact,
+          validation_violations: detection_result[:validation_violations],
+          ready_to_deploy: detection_result[:ready_to_deploy], synthesis_method: :pattern_detection
+        }
+      end
+
+      # Find all neural tasks in the agent definition
+      #
+      # @return [Array<Hash>] Array of neural task info
+      def find_neural_tasks
+        return [] unless @agent_definition.respond_to?(:tasks)
+
+        neural_tasks = @agent_definition.tasks.select do |_name, task_def|
+          # Neural tasks have instructions but no code block
+          task_def.neural?
+        end
+
+        neural_tasks.map do |name, task_def|
+          {
+            name: name.to_s,
+            definition: task_def
+          }
+        end
+      end
+
+      # Find a specific task definition by name
+      #
+      # @param task_name [String] Task name
+      # @return [Dsl::TaskDefinition, nil] Task definition or nil
+      def find_task_definition(task_name)
+        return nil unless @agent_definition.respond_to?(:tasks)
+
+        @agent_definition.tasks[task_name.to_sym]
+      end
+
+      # Format current task code for display
+      #
+      # @param task_def [Dsl::TaskDefinition] Task definition
+      # @return [String] Formatted code
+      def format_current_code(task_def)
+        inputs_str = (task_def.inputs || {}).map { |k, v| "#{k}: '#{v}'" }.join(', ')
+        outputs_str = (task_def.outputs || {}).map { |k, v| "#{k}: '#{v}'" }.join(', ')
+
+        <<~RUBY
+          task :#{task_def.name},
+            instructions: "#{task_def.instructions}",
+            inputs: { #{inputs_str} },
+            outputs: { #{outputs_str} }
+        RUBY
+      end
+
+      # Extract task code from full agent definition
+      #
+      # @param full_code [String] Complete agent definition
+      # @return [String] Just the task definition portion
+      def extract_task_code(full_code)
+        # Extract just the task definition from the full agent code
+        lines = full_code.lines
+        task_start = lines.index { |l| l.strip.start_with?('task :') }
+        task_end = lines.index { |l| l.strip == 'end' && l.start_with?('      end') }
+
+        return full_code unless task_start && task_end
+
+        lines[task_start..task_end].join
+      end
+
+      # Calculate performance impact of optimization
+      #
+      # @param execution_count [Integer] Number of executions observed
+      # @param consistency_score [Float] Pattern consistency
+      # @return [Hash] Impact metrics
+      def calculate_impact(execution_count:, consistency_score:)
+        # Estimates based on typical LLM vs symbolic execution
+        avg_neural_time = 2.5 # seconds
+        avg_neural_cost = 0.003 # dollars
+        avg_symbolic_time = 0.1 # seconds
+        avg_symbolic_cost = 0.0 # dollars
+
+        time_saved = avg_neural_time - avg_symbolic_time
+        cost_saved = avg_neural_cost - avg_symbolic_cost
+
+        {
+          current_avg_time: avg_neural_time,
+          optimized_avg_time: avg_symbolic_time,
+          time_reduction_pct: ((time_saved / avg_neural_time) * 100).round(1),
+          current_avg_cost: avg_neural_cost,
+          optimized_avg_cost: avg_symbolic_cost,
+          cost_reduction_pct: ((cost_saved / avg_neural_cost) * 100).round(1),
+          projected_monthly_savings: (cost_saved * execution_count * 30).round(2)
+        }
+      end
+
+      # Build proposal from synthesis result
+      #
+      # @param task_name [String] Task name
+      # @param task_def [Dsl::TaskDefinition] Task definition
+      # @param analysis [Hash] Pattern analysis result
+      # @param synthesis_result [Hash] LLM synthesis result
+      # @return [Hash] Optimization proposal
+      def build_synthesis_proposal(task_name:, task_def:, analysis:, synthesis_result:)
+        impact = calculate_impact(
+          execution_count: analysis[:execution_count],
+          consistency_score: synthesis_result[:confidence]
+        )
+
+        {
+          task_name: task_name,
+          current_code: format_current_code(task_def),
+          proposed_code: synthesis_result[:code],
+          full_generated_code: synthesis_result[:code],
+          consistency_score: analysis[:consistency_score],
+          execution_count: analysis[:execution_count],
+          pattern: analysis[:common_pattern],
+          performance_impact: impact,
+          validation_violations: synthesis_result[:validation_errors] || [],
+          ready_to_deploy: synthesis_result[:validation_errors].nil?,
+          synthesis_method: :llm_synthesis,
+          synthesis_confidence: synthesis_result[:confidence],
+          synthesis_explanation: synthesis_result[:explanation]
+        }
+      end
+
+      # Detect available tools from agent definition
+      #
+      # @return [Array<String>] Tool names
+      def detect_available_tools
+        return [] unless @agent_definition.respond_to?(:mcp_servers)
+
+        # Extract tool names from MCP server configurations
+        tools = []
+        @agent_definition.mcp_servers.each_value do |server|
+          tools.concat(server[:tools] || []) if server.is_a?(Hash)
+        end
+        tools.uniq
+      rescue StandardError
+        []
+      end
+    end
+  end
+end