language-operator 0.1.58 → 0.1.61

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,69 @@ 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' => arguments.to_json[0..1000],
+                           'gen_ai.tool.call.arguments.size' => arguments.to_json.bytesize
+                         }) do |span|
+            # Execute the original tool
+            result = original_tool.call(arguments)
+
+            # Record the result (truncated for telemetry)
+            result_str = result.is_a?(String) ? result : result.to_json
+            span.set_attribute('gen_ai.tool.call.result.size', result_str.bytesize)
+            span.set_attribute('gen_ai.tool.call.result', result_str[0..2000])
+
+            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,21 +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?
 
         # Set up callbacks to log tool invocations
         setup_tool_callbacks
 
-        logger.info('Chat session initialized', with_tools: !all_tools.empty?)
+        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

data/lib/language_operator/dsl/task_definition.rb

@@ -229,15 +229,16 @@ module LanguageOperator
       # Execute symbolic implementation
       #
       # @param inputs [Hash] Validated inputs
-      # @param context [Object, nil] Execution context
+      # @param context [Object, nil] Execution context (TaskExecutor)
       # @return [Hash] Result from execute block
       def execute_symbolic(inputs, context)
-        if @execute_block.arity == 1
-          @execute_block.call(inputs)
-        elsif @execute_block.arity == 2
-          @execute_block.call(inputs, context)
+        if context
+          # Execute block in context's scope to make helper methods available
+          # (execute_tool, execute_task, execute_llm, etc.)
+          context.instance_exec(inputs, &@execute_block)
         else
-          @execute_block.call
+          # Fallback for standalone execution without context
+          @execute_block.call(inputs)
         end
       end
 

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

@@ -0,0 +1,149 @@
+# 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: tool_span.dig(:attributes, 'gen_ai.tool.call.arguments'),
+                arguments_size: tool_span.dig(:attributes, 'gen_ai.tool.call.arguments.size'),
+                result: tool_span.dig(:attributes, 'gen_ai.tool.call.result'),
+                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