language-operator 0.0.1 → 0.1.30

data/lib/language_operator/loggable.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  # Mixin module to provide automatic logger initialization for classes
+  # that need logging capabilities.
+  #
+  # @example
+  #   class MyClass
+  #     include LanguageOperator::Loggable
+  #
+  #     def process
+  #       logger.info("Processing started")
+  #       # ...
+  #     end
+  #   end
+  #
+  # The logger component name is automatically derived from the class name.
+  # You can override the component name by defining a `logger_component` method.
+  #
+  # @example Custom component name
+  #   class MyClass
+  #     include LanguageOperator::Loggable
+  #
+  #     def logger_component
+  #       'CustomName'
+  #     end
+  #   end
+  module Loggable
+    # Returns a logger instance for this class.
+    # Lazily initializes the logger on first access.
+    #
+    # @return [LanguageOperator::Logger] Logger instance
+    def logger
+      @logger ||= LanguageOperator::Logger.new(component: logger_component)
+    end
+
+    private
+
+    # Returns the component name to use for the logger.
+    # Defaults to the class name, but can be overridden.
+    #
+    # @return [String] Component name for the logger
+    def logger_component
+      self.class.name
+    end
+  end
+end

data/lib/language_operator/logger.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module LanguageOperator
+  # Structured logger with configurable output formats and levels
+  #
+  # Supports multiple output formats:
+  # - :pretty (default): Human-readable with emojis and colors
+  # - :text: Plain text with timestamps
+  # - :json: Structured JSON output
+  #
+  # Environment variables:
+  # - LOG_LEVEL: DEBUG, INFO, WARN, ERROR (default: INFO)
+  # - LOG_FORMAT: pretty, text, json (default: pretty)
+  # - LOG_TIMING: true/false - Include operation timing (default: true)
+  class Logger
+    LEVELS = {
+      'DEBUG' => ::Logger::DEBUG,
+      'INFO' => ::Logger::INFO,
+      'WARN' => ::Logger::WARN,
+      'ERROR' => ::Logger::ERROR
+    }.freeze
+
+    LEVEL_EMOJI = {
+      'DEBUG' => '🔍',
+      'INFO' => 'ℹ️ ',
+      'WARN' => '⚠️ ',
+      'ERROR' => '❌'
+    }.freeze
+
+    attr_reader :logger, :format, :show_timing
+
+    def initialize(component: 'Langop', format: nil, level: nil)
+      @component = component
+      @format = format || ENV.fetch('LOG_FORMAT', 'pretty').to_sym
+      @show_timing = ENV.fetch('LOG_TIMING', 'true') == 'true'
+
+      log_level_name = level || ENV.fetch('LOG_LEVEL', 'INFO')
+      log_level = LEVELS[log_level_name.upcase] || ::Logger::INFO
+
+      @logger = ::Logger.new($stdout)
+      @logger.level = log_level
+      @logger.formatter = method(:format_message)
+    end
+
+    def debug(message, **metadata)
+      log(:debug, message, **metadata)
+    end
+
+    def info(message, **metadata)
+      log(:info, message, **metadata)
+    end
+
+    def warn(message, **metadata)
+      log(:warn, message, **metadata)
+    end
+
+    def error(message, **metadata)
+      log(:error, message, **metadata)
+    end
+
+    # Log with timing information
+    def timed(message, **metadata)
+      start_time = Time.now
+      result = yield if block_given?
+      duration = Time.now - start_time
+
+      info(message, **metadata, duration_s: duration.round(3))
+      result
+    end
+
+    private
+
+    def log(severity, message, **metadata)
+      @logger.send(severity) do
+        case @format
+        when :json
+          format_json(severity, message, **metadata)
+        when :text
+          format_text(severity, message, **metadata)
+        else
+          format_pretty(severity, message, **metadata)
+        end
+      end
+    end
+
+    def format_message(_severity, _timestamp, _progname, msg)
+      "#{msg}\n" # Already formatted by log method, add newline
+    end
+
+    def format_json(severity, message, **metadata)
+      require 'json'
+      JSON.generate({
+                      timestamp: Time.now.iso8601,
+                      level: severity.to_s.upcase,
+                      component: @component,
+                      message: message,
+                      **metadata
+                    })
+    end
+
+    def format_text(severity, message, **metadata)
+      parts = [
+        Time.now.strftime('%Y-%m-%d %H:%M:%S'),
+        severity.to_s.upcase.ljust(5),
+        "[#{@component}]",
+        message
+      ]
+
+      metadata_str = format_metadata(**metadata)
+      parts << metadata_str unless metadata_str.empty?
+
+      parts.join(' ')
+    end
+
+    def format_pretty(severity, message, **metadata)
+      emoji = LEVEL_EMOJI[severity.to_s.upcase] || '•'
+      parts = [emoji, message]
+
+      metadata_str = format_metadata(**metadata)
+      parts << "(#{metadata_str})" unless metadata_str.empty?
+
+      parts.join(' ')
+    end
+
+    def format_metadata(**metadata)
+      return '' if metadata.empty?
+
+      metadata.map do |key, value|
+        if key == :duration_s && @show_timing
+          "#{value}s"
+        elsif value.is_a?(String) && value.length > 100
+          "#{key}=#{value[0..97]}..."
+        else
+          "#{key}=#{value}"
+        end
+      end.join(', ')
+    end
+  end
+end

data/lib/language_operator/retry.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  # Retry utilities with exponential backoff for handling transient failures
+  module Retry
+    # Default retry configuration
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_BASE_DELAY = 1.0
+    DEFAULT_MAX_DELAY = 10.0
+    DEFAULT_JITTER_FACTOR = 0.1
+
+    # Common retryable HTTP status codes (transient errors)
+    RETRYABLE_HTTP_CODES = [429, 500, 502, 503, 504].freeze
+
+    # Execute a block with exponential backoff retry logic
+    # @param max_retries [Integer] Maximum number of retry attempts (default: 3)
+    # @param base_delay [Float] Initial delay in seconds (default: 1.0)
+    # @param max_delay [Float] Maximum delay cap in seconds (default: 10.0)
+    # @param jitter_factor [Float] Jitter randomization factor (default: 0.1)
+    # @param on_retry [Proc] Optional callback called before each retry (receives attempt number and exception)
+    # @yield Block to execute with retry logic
+    # @return [Object] Return value of the block
+    # @raise [StandardError] Re-raises the exception if all retries are exhausted
+    #
+    # @example Basic usage
+    #   LanguageOperator::Retry.with_backoff(max_retries: 5) do
+    #     client.get_resource(name)
+    #   end
+    #
+    # @example With callback
+    #   LanguageOperator::Retry.with_backoff(on_retry: ->(attempt, e) {
+    #     puts "Retry attempt #{attempt} after error: #{e.message}"
+    #   }) do
+    #     api_call
+    #   end
+    def self.with_backoff(max_retries: DEFAULT_MAX_RETRIES,
+                          base_delay: DEFAULT_BASE_DELAY,
+                          max_delay: DEFAULT_MAX_DELAY,
+                          jitter_factor: DEFAULT_JITTER_FACTOR,
+                          on_retry: nil)
+      attempt = 0
+      begin
+        yield
+      rescue StandardError => e
+        if attempt < max_retries
+          attempt += 1
+          delay = calculate_backoff(attempt, base_delay, max_delay, jitter_factor)
+          on_retry&.call(attempt, e)
+          sleep delay
+          retry
+        end
+        raise e
+      end
+    end
+
+    # Execute a block with retry for specific exception types
+    # @param exception_types [Array<Class>] Exception types to retry on
+    # @param max_retries [Integer] Maximum number of retry attempts
+    # @param base_delay [Float] Initial delay in seconds
+    # @param max_delay [Float] Maximum delay cap in seconds
+    # @param jitter_factor [Float] Jitter randomization factor
+    # @yield Block to execute
+    # @return [Object] Return value of the block
+    # @raise [StandardError] Re-raises the exception if all retries are exhausted
+    #
+    # @example
+    #   LanguageOperator::Retry.on_exceptions([Net::OpenTimeout, Errno::ECONNREFUSED]) do
+    #     smtp.connect
+    #   end
+    def self.on_exceptions(exception_types, max_retries: DEFAULT_MAX_RETRIES,
+                           base_delay: DEFAULT_BASE_DELAY,
+                           max_delay: DEFAULT_MAX_DELAY,
+                           jitter_factor: DEFAULT_JITTER_FACTOR)
+      attempt = 0
+      begin
+        yield
+      rescue *exception_types => e
+        if attempt < max_retries
+          attempt += 1
+          delay = calculate_backoff(attempt, base_delay, max_delay, jitter_factor)
+          sleep delay
+          retry
+        end
+        raise e
+      end
+    end
+
+    # Check if an HTTP status code is retryable (transient error)
+    # @param status [Integer] HTTP status code
+    # @return [Boolean] True if status code indicates a transient error
+    #
+    # @example
+    #   LanguageOperator::Retry.retryable_http_code?(503) # => true
+    #   LanguageOperator::Retry.retryable_http_code?(404) # => false
+    def self.retryable_http_code?(status)
+      RETRYABLE_HTTP_CODES.include?(status)
+    end
+
+    # Calculate exponential backoff delay with jitter
+    # @param attempt [Integer] Retry attempt number (1-based)
+    # @param base_delay [Float] Initial delay in seconds
+    # @param max_delay [Float] Maximum delay cap in seconds
+    # @param jitter_factor [Float] Jitter randomization factor (0.0 to 1.0)
+    # @return [Float] Delay in seconds
+    #
+    # @example
+    #   LanguageOperator::Retry.calculate_backoff(1) # => ~1.0 seconds
+    #   LanguageOperator::Retry.calculate_backoff(2) # => ~2.0 seconds
+    #   LanguageOperator::Retry.calculate_backoff(3) # => ~4.0 seconds
+    def self.calculate_backoff(attempt,
+                               base_delay = DEFAULT_BASE_DELAY,
+                               max_delay = DEFAULT_MAX_DELAY,
+                               jitter_factor = DEFAULT_JITTER_FACTOR)
+      # Exponential: base * 2^(attempt-1)
+      exponential = base_delay * (2**(attempt - 1))
+      # Cap at max
+      capped = [exponential, max_delay].min
+      # Add jitter: ±(delay * jitter_factor * random)
+      jitter = capped * jitter_factor * (rand - 0.5) * 2
+      capped + jitter
+    end
+  end
+end

data/lib/language_operator/retryable.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  # Mixin module to provide retry logic with exponential backoff for operations
+  # that may fail transiently.
+  #
+  # @example Basic usage
+  #   class MyService
+  #     include LanguageOperator::Retryable
+  #
+  #     def connect
+  #       with_retry do
+  #         # Connection logic that might fail
+  #         make_connection
+  #       end
+  #     end
+  #   end
+  #
+  # @example Custom retry configuration
+  #   with_retry(max_attempts: 5, base_delay: 2.0) do
+  #     risky_operation
+  #   end
+  #
+  # @example With custom error handling
+  #   with_retry(on_retry: ->(error, attempt) { log_error(error, attempt) }) do
+  #     api_call
+  #   end
+  module Retryable
+    # Default retry configuration
+    DEFAULT_MAX_ATTEMPTS = 3
+    DEFAULT_BASE_DELAY = 1.0
+    DEFAULT_MAX_DELAY = 30.0
+
+    # Execute a block with retry logic and exponential backoff.
+    #
+    # @param max_attempts [Integer] Maximum number of attempts (default: 3)
+    # @param base_delay [Float] Base delay in seconds for exponential backoff (default: 1.0)
+    # @param max_delay [Float] Maximum delay between retries in seconds (default: 30.0)
+    # @param rescue_errors [Array<Class>] Array of error classes to rescue (default: StandardError)
+    # @param on_retry [Proc] Optional callback called on each retry attempt with (error, attempt, delay)
+    # @yield Block to execute with retry logic
+    # @return Result of the block if successful
+    # @raise Last error encountered if all retries are exhausted
+    #
+    # @example
+    #   result = with_retry(max_attempts: 5) do
+    #     fetch_from_api
+    #   end
+    def with_retry(
+      max_attempts: DEFAULT_MAX_ATTEMPTS,
+      base_delay: DEFAULT_BASE_DELAY,
+      max_delay: DEFAULT_MAX_DELAY,
+      rescue_errors: [StandardError],
+      on_retry: nil
+    )
+      attempt = 0
+      last_error = nil
+
+      loop do
+        attempt += 1
+
+        begin
+          return yield
+        rescue *rescue_errors => e
+          last_error = e
+
+          raise e if attempt >= max_attempts
+
+          # Calculate delay with exponential backoff: base_delay * 2^(attempt-1)
+          delay = [base_delay * (2**(attempt - 1)), max_delay].min
+
+          # Call the retry callback if provided
+          on_retry&.call(e, attempt, delay)
+
+          sleep(delay)
+        end
+      end
+    end
+
+    # Execute a block with retry logic and return nil on failure instead of raising.
+    #
+    # @param max_attempts [Integer] Maximum number of attempts (default: 3)
+    # @param base_delay [Float] Base delay in seconds for exponential backoff (default: 1.0)
+    # @param max_delay [Float] Maximum delay between retries in seconds (default: 30.0)
+    # @param rescue_errors [Array<Class>] Array of error classes to rescue (default: StandardError)
+    # @param on_retry [Proc] Optional callback called on each retry attempt with (error, attempt, delay)
+    # @param on_failure [Proc] Optional callback called when all retries are exhausted with (error, attempts)
+    # @yield Block to execute with retry logic
+    # @return Result of the block if successful, nil if all retries failed
+    #
+    # @example
+    #   result = with_retry_or_nil(on_failure: ->(err, tries) { log_failure(err) }) do
+    #     optional_operation
+    #   end
+    #
+    #   return unless result
+    def with_retry_or_nil(
+      max_attempts: DEFAULT_MAX_ATTEMPTS,
+      base_delay: DEFAULT_BASE_DELAY,
+      max_delay: DEFAULT_MAX_DELAY,
+      rescue_errors: [StandardError],
+      on_retry: nil,
+      on_failure: nil
+    )
+      attempt = 0
+      last_error = nil
+
+      loop do
+        attempt += 1
+
+        begin
+          return yield
+        rescue *rescue_errors => e
+          last_error = e
+
+          if attempt >= max_attempts
+            on_failure&.call(e, attempt)
+            return nil
+          end
+
+          # Calculate delay with exponential backoff
+          delay = [base_delay * (2**(attempt - 1)), max_delay].min
+
+          # Call the retry callback if provided
+          on_retry&.call(e, attempt, delay)
+
+          sleep(delay)
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/tool_loader.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require_relative 'dsl'
+require 'mcp'
+require 'opentelemetry/sdk'
+
+module LanguageOperator
+  # Loads tool definitions from Ruby files
+  #
+  # Scans a directory for Ruby files containing tool definitions and loads them
+  # into a registry. Provides hot-reloading capability for development.
+  #
+  # @example Basic usage
+  #   registry = LanguageOperator::Dsl::Registry.new
+  #   loader = LanguageOperator::ToolLoader.new(registry, '/mcp/tools')
+  #   loader.load_tools
+  #   puts "Loaded #{registry.all.length} tools"
+  #
+  # @example With custom context
+  #   loader = LanguageOperator::ToolLoader.new(registry)
+  #   loader.load_tools
+  #   loader.reload  # Hot reload tools
+  #
+  # @example Start MCP server
+  #   LanguageOperator::ToolLoader.start  # Loads tools and starts MCP server
+  class ToolLoader
+    # Initialize tool loader
+    #
+    # @param registry [LanguageOperator::Dsl::Registry] Tool registry
+    # @param tools_dir [String] Directory containing tool definition files
+    def initialize(registry, tools_dir = '/mcp')
+      @registry = registry
+      @tools_dir = tools_dir
+    end
+
+    # Load all tool files from the tools directory
+    #
+    # @return [void]
+    def load_tools
+      @registry.clear
+
+      unless Dir.exist?(@tools_dir)
+        puts "Tools directory #{@tools_dir} does not exist. Skipping tool loading."
+        return
+      end
+
+      tool_files = Dir.glob(File.join(@tools_dir, '**', '*.rb'))
+
+      if tool_files.empty?
+        puts "No tool files found in #{@tools_dir}"
+        return
+      end
+
+      tool_files.each do |file|
+        load_tool_file(file)
+      end
+
+      puts "Loaded #{@registry.all.length} tools from #{tool_files.length} files"
+    end
+
+    # Load a single tool file
+    #
+    # @param file [String] Path to tool definition file
+    # @return [void]
+    def load_tool_file(file)
+      puts "Loading tools from: #{file}"
+
+      begin
+        context = LanguageOperator::Dsl::Context.new(@registry)
+        code = File.read(file)
+
+        # Execute in sandbox with validation
+        executor = LanguageOperator::Agent::Safety::SafeExecutor.new(context)
+        executor.eval(code, file)
+      rescue Agent::Safety::SafeExecutor::SecurityError, Agent::Safety::ASTValidator::SecurityError => e
+        # Re-raise security errors so they're not silently ignored
+        warn "Error loading tool file #{file}: #{e.message}"
+        warn e.backtrace.join("\n")
+        raise e
+      rescue StandardError => e
+        warn "Error loading tool file #{file}: #{e.message}"
+        warn e.backtrace.join("\n")
+      end
+    end
+
+    # Reload all tools (hot reload)
+    #
+    # @return [void]
+    def reload
+      puts 'Reloading tools...'
+      load_tools
+    end
+
+    # Start an MCP server with loaded tools
+    #
+    # This class method creates a registry, loads tools from /mcp directory,
+    # wraps them as MCP::Tool classes, and starts an MCP server.
+    #
+    # Transport mode is automatically detected:
+    # - If PORT environment variable is set: HTTP server mode (for Kubernetes)
+    # - Otherwise: stdio transport mode (for local development)
+    #
+    # @param tools_dir [String] Directory containing tool definition files (default: '/mcp')
+    # @param server_name [String] Name of the MCP server (default: 'language-operator-tool')
+    # @return [void]
+    def self.start(tools_dir: '/mcp', server_name: 'language-operator-tool')
+      # Create registry and load tools
+      registry = LanguageOperator::Dsl::Registry.new
+      loader = new(registry, tools_dir)
+      loader.load_tools
+
+      # Convert DSL tools to MCP::Tool classes
+      mcp_tools = registry.all.map do |tool_def|
+        create_mcp_tool(tool_def)
+      end
+
+      # Create MCP server
+      server = MCP::Server.new(
+        name: server_name,
+        tools: mcp_tools
+      )
+
+      # Auto-detect transport mode based on PORT environment variable
+      if ENV['PORT']
+        start_http_server(server, mcp_tools.length, ENV['PORT'].to_i)
+      else
+        start_stdio_server(server, mcp_tools.length)
+      end
+    end
+
+    # Start MCP server in HTTP mode
+    #
+    # @param server [MCP::Server] The MCP server instance
+    # @param tool_count [Integer] Number of tools loaded
+    # @param port [Integer] Port to bind to
+    # @return [void]
+    def self.start_http_server(server, tool_count, port)
+      require 'rack'
+      require 'rackup'
+
+      # Create the Streamable HTTP transport
+      transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+      server.transport = transport
+
+      # Create the Rack application
+      app = proc do |env|
+        request = Rack::Request.new(env)
+        transport.handle_request(request)
+      end
+
+      # Build the Rack application with middleware
+      rack_app = Rack::Builder.new do
+        use Rack::CommonLogger
+        use Rack::ShowExceptions
+        run app
+      end
+
+      puts "Starting MCP HTTP server on http://0.0.0.0:#{port}"
+      puts "Loaded #{tool_count} tools"
+
+      # Start the server with Puma
+      Rackup::Handler.get('puma').run(rack_app, Port: port, Host: '0.0.0.0')
+    end
+
+    # Start MCP server in stdio mode
+    #
+    # @param server [MCP::Server] The MCP server instance
+    # @param tool_count [Integer] Number of tools loaded
+    # @return [void]
+    def self.start_stdio_server(server, tool_count)
+      # Use stdio transport
+      transport = MCP::Server::Transports::StdioTransport.new(server)
+      puts "Starting MCP server with #{tool_count} tools (stdio mode)"
+      transport.open
+    end
+
+    # Convert a DSL tool definition to an MCP::Tool class
+    #
+    # @param tool_def [LanguageOperator::Dsl::ToolDefinition] Tool definition from DSL
+    # @return [Class] MCP::Tool subclass
+    # rubocop:disable Metrics/MethodLength
+    def self.create_mcp_tool(tool_def)
+      # Capture tool name and tracer for use in the dynamic class
+      tool_name = tool_def.name
+      tracer = OpenTelemetry.tracer_provider.tracer('language-operator-agent', LanguageOperator::VERSION)
+
+      # Create a dynamic MCP::Tool class
+      Class.new(MCP::Tool) do
+        description tool_def.description || "Tool: #{tool_def.name}"
+
+        # Build input schema from parameters
+        properties = {}
+        required_params = []
+
+        tool_def.parameters.each do |param_name, param_def|
+          properties[param_name] = {
+            type: param_def.type&.to_s || 'string',
+            description: param_def.description
+          }
+          required_params << param_name if param_def.required?
+        end
+
+        input_schema(
+          properties: properties,
+          required: required_params
+        )
+
+        # Store the execute block
+        @execute_block = tool_def.execute_block
+
+        # Define the call method with OpenTelemetry instrumentation
+        define_singleton_method(:call) do |**params|
+          tracer.in_span('agent.tool.execute', attributes: {
+                           'tool.name' => tool_name,
+                           'tool.type' => 'custom'
+                         }) do |span|
+            # Execute the tool's block
+            result = @execute_block.call(params)
+
+            # Set success attribute
+            span.set_attribute('tool.result', 'success')
+
+            # Return MCP response
+            MCP::Tool::Response.new([
+                                      {
+                                        type: 'text',
+                                        text: result.to_s
+                                      }
+                                    ])
+          rescue StandardError => e
+            # Record exception and set failure status
+            span.record_exception(e)
+            span.set_attribute('tool.result', 'failure')
+            span.status = OpenTelemetry::Trace::Status.error(e.message)
+            raise
+          end
+        end
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+  end
+end