language-operator 0.1.31 → 0.1.35

data/lib/language_operator/dsl/task_definition.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require_relative '../loggable'
+require_relative '../type_coercion'
+
+module LanguageOperator
+  module Dsl
+    # Task definition for organic functions (DSL v1)
+    #
+    # Represents an organic function with a stable contract (inputs/outputs) where
+    # the implementation can evolve from neural (instructions-based) to symbolic
+    # (explicit code) without breaking callers.
+    #
+    # @example Neural task (LLM-based)
+    #   task :analyze_data,
+    #     instructions: "Analyze the data for anomalies",
+    #     inputs: { data: 'array' },
+    #     outputs: { issues: 'array', summary: 'string' }
+    #
+    # @example Symbolic task (explicit code)
+    #   task :calculate_total,
+    #     inputs: { items: 'array' },
+    #     outputs: { total: 'number' }
+    #   do |inputs|
+    #     { total: inputs[:items].sum { |i| i['amount'] } }
+    #   end
+    #
+    # @example Hybrid task (both instructions and code)
+    #   task :fetch_user,
+    #     instructions: "Fetch user data from database",
+    #     inputs: { user_id: 'integer' },
+    #     outputs: { user: 'hash', preferences: 'hash' }
+    #   do |inputs|
+    #     execute_tool('database', 'get_user', id: inputs[:user_id])
+    #   end
+    class TaskDefinition
+      include LanguageOperator::Loggable
+
+      attr_reader :name, :inputs_schema, :outputs_schema, :instructions_text, :execute_block
+
+      # Supported types for input/output validation
+      SUPPORTED_TYPES = %w[string integer number boolean array hash any].freeze
+
+      # Initialize a new task definition
+      #
+      # @param name [Symbol] Task name
+      def initialize(name)
+        @name = name
+        @inputs_schema = {}
+        @outputs_schema = {}
+        @instructions_text = nil
+        @execute_block = nil
+      end
+
+      # Define or retrieve the input contract
+      #
+      # @param schema [Hash, nil] Input schema (param_name => type_string)
+      # @return [Hash] Current input schema
+      # @example
+      #   inputs { user_id: 'integer', filter: 'string' }
+      def inputs(schema = nil)
+        return @inputs_schema if schema.nil?
+
+        validate_schema!(schema, 'inputs')
+        @inputs_schema = schema
+      end
+
+      # Define or retrieve the output contract
+      #
+      # @param schema [Hash, nil] Output schema (field_name => type_string)
+      # @return [Hash] Current output schema
+      # @example
+      #   outputs { user: 'hash', success: 'boolean' }
+      def outputs(schema = nil)
+        return @outputs_schema if schema.nil?
+
+        validate_schema!(schema, 'outputs')
+        @outputs_schema = schema
+      end
+
+      # Define or retrieve the instructions (neural implementation)
+      #
+      # @param text [String, nil] Natural language instructions
+      # @return [String, nil] Current instructions
+      # @example
+      #   instructions "Fetch user data from the database"
+      def instructions(text = nil)
+        return @instructions_text if text.nil?
+
+        @instructions_text = text
+      end
+
+      # Define the symbolic implementation
+      #
+      # @yield [inputs] Block that receives validated inputs and returns outputs
+      # @yieldparam inputs [Hash] Validated and coerced input parameters
+      # @yieldreturn [Hash] Output values matching the outputs schema
+      # @example
+      #   execute do |inputs|
+      #     { total: inputs[:items].sum { |i| i['amount'] } }
+      #   end
+      def execute(&block)
+        @execute_block = block if block
+      end
+
+      # Check if this is a neural task (instructions-based)
+      #
+      # @return [Boolean] True if instructions are defined
+      def neural?
+        !@instructions_text.nil?
+      end
+
+      # Check if this is a symbolic task (code-based)
+      #
+      # @return [Boolean] True if execute block is defined
+      def symbolic?
+        !@execute_block.nil?
+      end
+
+      # Execute the task with given inputs
+      #
+      # @param input_params [Hash] Input parameters
+      # @param context [Object, nil] Execution context (optional)
+      # @return [Hash] Validated output matching outputs schema
+      # @raise [ArgumentError] If inputs or outputs don't match schema
+      def call(input_params, context = nil)
+        # Validate and coerce inputs
+        validated_inputs = validate_inputs(input_params)
+
+        # Execute based on implementation type
+        result = if symbolic?
+                   # Symbolic execution (explicit code)
+                   logger.debug('Executing symbolic task', task: @name)
+                   execute_symbolic(validated_inputs, context)
+                 elsif neural?
+                   # Neural execution (LLM-based)
+                   logger.debug('Executing neural task', task: @name, instructions: @instructions_text)
+                   execute_neural(validated_inputs, context)
+                 else
+                   raise "Task #{@name} has no implementation (neither neural nor symbolic)"
+                 end
+
+        # Validate outputs
+        validate_outputs(result)
+      end
+
+      # Validate input parameters against schema
+      #
+      # @param params [Hash] Input parameters
+      # @return [Hash] Validated and coerced parameters
+      # @raise [ArgumentError] If validation fails
+      def validate_inputs(params)
+        params = params.transform_keys(&:to_sym)
+        validated = {}
+
+        @inputs_schema.each do |key, type|
+          key_sym = key.to_sym
+          value = params[key_sym]
+
+          raise ArgumentError, "Missing required input parameter: #{key}" if value.nil?
+
+          validated[key_sym] = coerce_value(value, type, "input parameter '#{key}'")
+        end
+
+        # Check for unexpected parameters
+        extra_keys = params.keys - @inputs_schema.keys.map(&:to_sym)
+        logger.warn('Unexpected input parameters', task: @name, extra: extra_keys) unless extra_keys.empty?
+
+        validated
+      end
+
+      # Validate output values against schema
+      #
+      # @param result [Hash] Output values
+      # @return [Hash] Validated and coerced outputs
+      # @raise [ArgumentError] If validation fails
+      def validate_outputs(result)
+        return result if @outputs_schema.empty? # No schema = no validation
+
+        result = result.transform_keys(&:to_sym)
+        validated = {}
+
+        @outputs_schema.each do |key, type|
+          key_sym = key.to_sym
+          value = result[key_sym]
+
+          raise ArgumentError, "Missing required output field: #{key}" if value.nil?
+
+          validated[key_sym] = coerce_value(value, type, "output field '#{key}'")
+        end
+
+        validated
+      end
+
+      # Export task as JSON schema
+      #
+      # @return [Hash] JSON Schema representation
+      def to_schema
+        {
+          'name' => @name.to_s,
+          'type' => implementation_type,
+          'instructions' => @instructions_text,
+          'inputs' => schema_to_json(@inputs_schema),
+          'outputs' => schema_to_json(@outputs_schema)
+        }
+      end
+
+      private
+
+      def logger_component
+        "Task:#{@name}"
+      end
+
+      # Determine implementation type
+      #
+      # @return [String] 'neural', 'symbolic', or 'hybrid'
+      def implementation_type
+        if neural? && symbolic?
+          'hybrid'
+        elsif neural?
+          'neural'
+        elsif symbolic?
+          'symbolic'
+        else
+          'undefined'
+        end
+      end
+
+      # Execute symbolic implementation
+      #
+      # @param inputs [Hash] Validated inputs
+      # @param context [Object, nil] Execution context
+      # @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)
+        else
+          @execute_block.call
+        end
+      end
+
+      # Execute neural implementation (stub for now)
+      #
+      # @param inputs [Hash] Validated inputs
+      # @param context [Object, nil] Execution context
+      # @return [Hash] Result from LLM
+      # @note This is a placeholder - actual neural execution happens in agent runtime
+      def execute_neural(inputs, context)
+        raise NotImplementedError, 'Neural task execution requires agent runtime context. ' \
+                                   "Task #{@name} should be executed via execute_task() in agent main block."
+      end
+
+      # Validate a schema hash
+      #
+      # @param schema [Hash] Schema to validate
+      # @param name [String] Schema name (for error messages)
+      # @raise [ArgumentError] If schema is invalid
+      def validate_schema!(schema, name)
+        raise ArgumentError, "#{name} schema must be a Hash, got #{schema.class}" unless schema.is_a?(Hash)
+
+        schema.each do |key, type|
+          unless type.is_a?(String) && SUPPORTED_TYPES.include?(type)
+            raise ArgumentError, "#{name} schema type for '#{key}' must be one of #{SUPPORTED_TYPES.join(', ')}, " \
+                                 "got '#{type}'"
+          end
+        end
+      end
+
+      # Coerce a value to the specified type
+      #
+      # @param value [Object] Value to coerce
+      # @param type [String] Target type
+      # @param context [String] Context for error messages
+      # @return [Object] Coerced value
+      # @raise [ArgumentError] If coercion fails
+      def coerce_value(value, type, context)
+        TypeCoercion.coerce(value, type)
+      rescue ArgumentError => e
+        # Re-raise with context added
+        raise ArgumentError, "#{e.message} for #{context}"
+      end
+
+      # Convert schema hash to JSON Schema format
+      #
+      # @param schema [Hash] Type schema
+      # @return [Hash] JSON Schema
+      def schema_to_json(schema)
+        {
+          'type' => 'object',
+          'properties' => schema.transform_values { |type| { 'type' => map_type_to_json_schema(type) } },
+          'required' => schema.keys.map(&:to_s)
+        }
+      end
+
+      # Map internal type to JSON Schema type
+      #
+      # @param type [String] Internal type name
+      # @return [String] JSON Schema type
+      def map_type_to_json_schema(type)
+        case type
+        when 'integer' then 'integer'
+        when 'number' then 'number'
+        when 'string' then 'string'
+        when 'boolean' then 'boolean'
+        when 'array' then 'array'
+        when 'hash' then 'object'
+        when 'any' then 'any'
+        else type
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/dsl.rb

@@ -13,7 +13,6 @@ require_relative 'dsl/context'
 require_relative 'dsl/execution_context'
 require_relative 'dsl/agent_definition'
 require_relative 'dsl/agent_context'
-require_relative 'dsl/workflow_definition'
 require_relative 'dsl/schema'
 require_relative 'agent/safety/ast_validator'
 require_relative 'agent/safety/safe_executor'

data/lib/language_operator/instrumentation/task_tracer.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require 'opentelemetry/sdk'
+require 'json'
+
+module LanguageOperator
+  module Instrumentation
+    # OpenTelemetry instrumentation for task execution
+    #
+    # Provides comprehensive tracing for DSL v1 task execution including:
+    # - Neural task execution (LLM calls with tool access)
+    # - Symbolic task execution (direct Ruby code)
+    # - Input/output validation
+    # - Retry attempts
+    # - Tool call tracking (when available)
+    #
+    # Follows OpenTelemetry Semantic Conventions for GenAI:
+    # https://opentelemetry.io/docs/specs/semconv/gen-ai/
+    #
+    # @example Enable full data capture
+    #   ENV['CAPTURE_TASK_INPUTS'] = 'true'
+    #   ENV['CAPTURE_TASK_OUTPUTS'] = 'true'
+    #   ENV['CAPTURE_TOOL_ARGS'] = 'true'
+    #
+    # @example Performance overhead
+    #   Instrumentation adds <5% overhead with default settings
+    #   Overhead may increase to ~10% with full data capture enabled
+    #
+    module TaskTracer
+      # Maximum length for captured data before truncation
+      MAX_CAPTURED_LENGTH = 1000
+
+      private
+
+      # Check if data capture is enabled for a specific type
+      #
+      # @param type [Symbol] Type of data (:inputs, :outputs, :tool_args, :tool_results)
+      # @return [Boolean] Whether capture is enabled
+      def capture_enabled?(type)
+        case type
+        when :inputs
+          ENV['CAPTURE_TASK_INPUTS'] == 'true'
+        when :outputs
+          ENV['CAPTURE_TASK_OUTPUTS'] == 'true'
+        when :tool_args
+          ENV['CAPTURE_TOOL_ARGS'] == 'true'
+        when :tool_results
+          ENV['CAPTURE_TOOL_RESULTS'] == 'true'
+        else
+          false
+        end
+      end
+
+      # Sanitize data for span attributes
+      #
+      # By default, only captures metadata (sizes, counts).
+      # Full data capture requires explicit opt-in via environment variables.
+      #
+      # @param data [Object] Data to sanitize
+      # @param type [Symbol] Type of data for capture control
+      # @param max_length [Integer] Maximum length before truncation
+      # @return [String, nil] Sanitized string or nil if capture disabled
+      def sanitize_data(data, type, max_length: MAX_CAPTURED_LENGTH)
+        return nil unless capture_enabled?(type)
+
+        str = case data
+              when String then data
+              when Hash then JSON.generate(data)
+              else data.to_s
+              end
+
+        # Truncate if too long
+        if str.length > max_length
+          "#{str[0...max_length]}... (truncated #{str.length - max_length} chars)"
+        else
+          str
+        end
+      rescue StandardError => e
+        logger&.warn('Failed to sanitize data for tracing', error: e.message)
+        nil
+      end
+
+      # Build attributes for neural task span following GenAI semantic conventions
+      #
+      # @param task [TaskDefinition] The task definition
+      # @param prompt [String] The generated prompt
+      # @param validated_inputs [Hash] Validated input parameters
+      # @return [Hash] Span attributes
+      def neural_task_attributes(_task, prompt, validated_inputs)
+        attributes = {
+          'gen_ai.operation.name' => 'chat',
+          'gen_ai.system' => determine_genai_system,
+          'gen_ai.prompt.size' => prompt.bytesize
+        }
+
+        # Add model if available
+        if @agent.respond_to?(:config) && @agent.config
+          model = @agent.config.dig('llm', 'model') || @agent.config['model']
+          attributes['gen_ai.request.model'] = model if model
+        end
+
+        # Add sanitized prompt if capture enabled
+        if (sanitized_prompt = sanitize_data(prompt, :inputs))
+          attributes['gen_ai.prompt'] = sanitized_prompt
+        end
+
+        # Add input metadata
+        attributes['task.input.keys'] = validated_inputs.keys.map(&:to_s).join(',')
+        attributes['task.input.count'] = validated_inputs.size
+
+        attributes
+      end
+
+      # Determine GenAI system identifier from agent configuration
+      #
+      # @return [String] GenAI system identifier
+      def determine_genai_system
+        return 'ruby_llm' unless @agent.respond_to?(:config)
+
+        provider = @agent.config.dig('llm', 'provider') ||
+                   @agent.config['provider'] ||
+                   'ruby_llm'
+
+        provider.to_s
+      end
+
+      # Build attributes for symbolic task span
+      #
+      # @param task [TaskDefinition] The task definition
+      # @return [Hash] Span attributes
+      def symbolic_task_attributes(task)
+        {
+          'task.execution.type' => 'symbolic',
+          'task.execution.has_block' => task.execute_block ? 'true' : 'false'
+        }
+      end
+
+      # Record token usage from LLM response on span
+      #
+      # @param response [Object] LLM response object
+      # @param span [OpenTelemetry::Trace::Span] The span to update
+      def record_token_usage(response, span)
+        return unless response
+
+        span.set_attribute('gen_ai.usage.input_tokens', response.input_tokens.to_i) if response.respond_to?(:input_tokens) && response.input_tokens
+
+        span.set_attribute('gen_ai.usage.output_tokens', response.output_tokens.to_i) if response.respond_to?(:output_tokens) && response.output_tokens
+
+        # Try to get model from response if available
+        span.set_attribute('gen_ai.response.model', response.model.to_s) if response.respond_to?(:model) && response.model
+
+        # Try to get response ID if available
+        span.set_attribute('gen_ai.response.id', response.id.to_s) if response.respond_to?(:id) && response.id
+
+        # Try to get finish reason if available
+        span.set_attribute('gen_ai.response.finish_reasons', response.stop_reason.to_s) if response.respond_to?(:stop_reason) && response.stop_reason
+      rescue StandardError => e
+        logger&.warn('Failed to record token usage', error: e.message)
+      end
+
+      # Record tool calls from LLM response
+      #
+      # Attempts to extract tool call information from the response object
+      # and create child spans for each tool invocation.
+      #
+      # @param response [Object] LLM response object
+      # @param parent_span [OpenTelemetry::Trace::Span] Parent span
+      def record_tool_calls(response, parent_span)
+        return unless response.respond_to?(:tool_calls)
+        return unless response.tool_calls&.any?
+
+        response.tool_calls.each do |tool_call|
+          record_single_tool_call(tool_call, parent_span)
+        end
+      rescue StandardError => e
+        logger&.warn('Failed to record tool calls', error: e.message)
+      end
+
+      # Record a single tool call as a span
+      #
+      # @param tool_call [Object] Tool call object
+      # @param parent_span [OpenTelemetry::Trace::Span] Parent span
+      def record_single_tool_call(tool_call, _parent_span)
+        tool_name = extract_tool_name(tool_call)
+
+        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
+        end
+      rescue StandardError => e
+        logger&.warn('Failed to record tool call span', error: e.message, tool: tool_name)
+      end
+
+      # Extract tool name from tool call object
+      #
+      # @param tool_call [Object] Tool call object
+      # @return [String] Tool name
+      def extract_tool_name(tool_call)
+        if tool_call.respond_to?(:name)
+          tool_call.name.to_s
+        elsif tool_call.respond_to?(:function) && tool_call.function.respond_to?(:name)
+          tool_call.function.name.to_s
+        else
+          'unknown'
+        end
+      end
+
+      # Build attributes for tool call span
+      #
+      # @param tool_call [Object] Tool call object
+      # @return [Hash] Span attributes
+      def build_tool_call_attributes(tool_call)
+        attributes = {
+          'gen_ai.operation.name' => 'execute_tool',
+          'gen_ai.tool.name' => extract_tool_name(tool_call)
+        }
+
+        # Add tool call ID if available
+        attributes['gen_ai.tool.call.id'] = tool_call.id.to_s if tool_call.respond_to?(:id) && tool_call.id
+
+        # Add arguments if available and capture enabled
+        if tool_call.respond_to?(:arguments) && tool_call.arguments
+          args_str = tool_call.arguments.is_a?(String) ? tool_call.arguments : JSON.generate(tool_call.arguments)
+          attributes['gen_ai.tool.call.arguments.size'] = args_str.bytesize
+
+          if (sanitized_args = sanitize_data(tool_call.arguments, :tool_args))
+            attributes['gen_ai.tool.call.arguments'] = sanitized_args
+          end
+        elsif tool_call.respond_to?(:function) && tool_call.function.respond_to?(:arguments)
+          args = tool_call.function.arguments
+          args_str = args.is_a?(String) ? args : JSON.generate(args)
+          attributes['gen_ai.tool.call.arguments.size'] = args_str.bytesize
+
+          if (sanitized_args = sanitize_data(args, :tool_args))
+            attributes['gen_ai.tool.call.arguments'] = sanitized_args
+          end
+        end
+
+        attributes
+      end
+
+      # Record tool call result on span
+      #
+      # @param result [Object] Tool call result
+      # @param span [OpenTelemetry::Trace::Span] The span to update
+      def record_tool_result(result, span)
+        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
+      rescue StandardError => e
+        logger&.warn('Failed to record tool result', error: e.message)
+      end
+
+      # Record response parsing metadata
+      #
+      # @param response_text [String] Raw response text
+      # @param span [OpenTelemetry::Trace::Span] The span to update
+      def record_parse_metadata(response_text, span)
+        span.set_attribute('gen_ai.completion.size', response_text.bytesize)
+
+        # Add sanitized completion if capture enabled
+        if (sanitized_completion = sanitize_data(response_text, :outputs))
+          span.set_attribute('gen_ai.completion', sanitized_completion)
+        end
+      rescue StandardError => e
+        logger&.warn('Failed to record parse metadata', error: e.message)
+      end
+
+      # Record output validation metadata
+      #
+      # @param outputs [Hash] Task outputs
+      # @param span [OpenTelemetry::Trace::Span] The span to update
+      def record_output_metadata(outputs, span)
+        span.set_attribute('task.output.keys', outputs.keys.map(&:to_s).join(','))
+        span.set_attribute('task.output.count', outputs.size)
+      rescue StandardError => e
+        logger&.warn('Failed to record output metadata', error: e.message)
+      end
+    end
+  end
+end

data/lib/language_operator/logger.rb

@@ -23,10 +23,10 @@ module LanguageOperator
     }.freeze
 
     LEVEL_EMOJI = {
-      'DEBUG' => '', # 🔍
-      'INFO' => '', # ℹ️
-      'WARN' => '', # ⚠️
-      'ERROR' => '' # ❌
+      'DEBUG' => "\e[1;90m·\e[0m",   # Bold gray middot
+      'INFO' => "\e[1;36m·\e[0m",    # Bold cyan middot
+      'WARN' => "\e[1;33m·\e[0m",    # Bold yellow middot
+      'ERROR' => "\e[1;31m·\e[0m"    # Bold red middot
     }.freeze
 
     attr_reader :logger, :format, :show_timing