language-operator 0.0.1 → 0.1.30

data/lib/language_operator/dsl/tool_definition.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative 'parameter_definition'
+require_relative 'http'
+require_relative 'shell'
+require_relative 'helpers'
+
+module LanguageOperator
+  module Dsl
+    # Tool definition for MCP tools
+    #
+    # Defines an MCP tool with parameters, description, and execution logic.
+    # Used within the DSL to create tools that can be registered and served.
+    #
+    # @example Define a simple tool
+    #   tool "greet" do
+    #     description "Greet a user by name"
+    #
+    #     parameter :name do
+    #       type :string
+    #       required true
+    #       description "Name to greet"
+    #     end
+    #
+    #     execute do |params|
+    #       "Hello, #{params['name']}!"
+    #     end
+    #   end
+    class ToolDefinition
+      include LanguageOperator::Dsl::Helpers
+
+      # Provide access to HTTP and Shell helper classes as constants
+      HTTP = LanguageOperator::Dsl::HTTP
+      Shell = LanguageOperator::Dsl::Shell
+
+      attr_reader :name, :parameters, :execute_block
+
+      def initialize(name)
+        @name = name
+        @parameters = {}
+        @execute_block = nil
+        @description = nil
+      end
+
+      def description(val = nil)
+        return @description if val.nil?
+
+        @description = val
+      end
+
+      def parameter(name, &)
+        param = ParameterDefinition.new(name)
+        param.instance_eval(&) if block_given?
+        @parameters[name.to_s] = param
+      end
+
+      def execute(&block)
+        @execute_block = block
+      end
+
+      def call(params)
+        log_debug "Calling tool '#{@name}' with params: #{params.inspect}"
+
+        # Apply default values for missing optional parameters
+        @parameters.each do |name, param_def|
+          default_value = param_def.instance_variable_get(:@default)
+          params[name] = default_value if !params.key?(name) && !default_value.nil?
+
+          # Validate required parameters
+          raise ArgumentError, "Missing required parameter: #{name}" if param_def.required? && !params.key?(name)
+
+          # Validate parameter format if validator is set and value is present
+          if params.key?(name)
+            error = param_def.validate_value(params[name])
+            raise ArgumentError, error if error
+          end
+        end
+
+        # Call the execute block with parameters
+        result = @execute_block.call(params) if @execute_block
+
+        log_debug "Tool '#{@name}' completed: #{truncate_for_log(result)}"
+        result
+      end
+
+      def to_schema
+        {
+          'name' => @name,
+          'description' => @description,
+          'inputSchema' => {
+            'type' => 'object',
+            'properties' => @parameters.transform_values(&:to_schema),
+            'required' => @parameters.select { |_, p| p.required? }.keys
+          }
+        }
+      end
+
+      private
+
+      def log_debug(message)
+        puts "[DEBUG] #{message}" if ENV['DEBUG'] || ENV['MCP_DEBUG']
+      end
+
+      def truncate_for_log(text)
+        return text.inspect if text.nil?
+
+        str = text.to_s
+        str.length > 100 ? "#{str[0..100]}..." : str
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/webhook_authentication.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  module Dsl
+    # Defines authentication configuration for webhooks
+    class WebhookAuthentication
+      attr_reader :type, :config
+
+      def initialize
+        @type = nil
+        @config = {}
+      end
+
+      # Verify HMAC signature (GitHub/Stripe style)
+      # @param header [String] Header name containing the signature
+      # @param secret [String] Secret key for HMAC
+      # @param algorithm [Symbol] Hash algorithm (:sha1, :sha256, :sha512)
+      # @param prefix [String, nil] Optional prefix to strip from signature (e.g., "sha256=")
+      def verify_signature(header:, secret:, algorithm: :sha256, prefix: nil)
+        if @current_methods
+          # Inside any_of/all_of - create child auth object
+          auth = WebhookAuthentication.new
+          auth.verify_signature(header: header, secret: secret, algorithm: algorithm, prefix: prefix)
+          @current_methods << auth
+        else
+          @type = :signature
+          @config[:header] = header
+          @config[:secret] = secret
+          @config[:algorithm] = algorithm
+          @config[:prefix] = prefix
+        end
+      end
+
+      # Verify API key from header
+      # @param header [String] Header name containing the API key
+      # @param key [String] Expected API key value
+      def verify_api_key(header:, key:)
+        if @current_methods
+          auth = WebhookAuthentication.new
+          auth.verify_api_key(header: header, key: key)
+          @current_methods << auth
+        else
+          @type = :api_key
+          @config[:header] = header
+          @config[:key] = key
+        end
+      end
+
+      # Verify bearer token
+      # @param token [String] Expected bearer token value
+      def verify_bearer_token(token:)
+        if @current_methods
+          auth = WebhookAuthentication.new
+          auth.verify_bearer_token(token: token)
+          @current_methods << auth
+        else
+          @type = :bearer_token
+          @config[:token] = token
+        end
+      end
+
+      # Verify basic auth credentials
+      # @param username [String] Expected username
+      # @param password [String] Expected password
+      def verify_basic_auth(username:, password:)
+        if @current_methods
+          auth = WebhookAuthentication.new
+          auth.verify_basic_auth(username: username, password: password)
+          @current_methods << auth
+        else
+          @type = :basic_auth
+          @config[:username] = username
+          @config[:password] = password
+        end
+      end
+
+      # Custom authentication callback
+      # @yield [context] Block receives request context hash
+      # @yieldreturn [Boolean] true if authenticated, false otherwise
+      def verify_custom(&block)
+        if @current_methods
+          auth = WebhookAuthentication.new
+          auth.verify_custom(&block)
+          @current_methods << auth
+        else
+          @type = :custom
+          @config[:callback] = block
+        end
+      end
+
+      # Allow multiple authentication methods (any can succeed)
+      def any_of(&block)
+        @type = :any_of
+        @config[:methods] = []
+        @current_methods = @config[:methods]
+        instance_eval(&block) if block
+        @current_methods = nil
+        # Restore type in case it was overwritten by method calls
+        @type = :any_of
+      end
+
+      # Allow multiple authentication methods (all must succeed)
+      def all_of(&block)
+        @type = :all_of
+        @config[:methods] = []
+        @current_methods = @config[:methods]
+        instance_eval(&block) if block
+        @current_methods = nil
+        # Restore type in case it was overwritten by method calls
+        @type = :all_of
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/webhook_definition.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative 'webhook_authentication'
+
+module LanguageOperator
+  module Dsl
+    # Webhook Definition
+    #
+    # Defines webhook endpoints for reactive agents.
+    #
+    # @example Define a webhook with authentication
+    #   webhook "/github/pr-opened" do
+    #     method :post
+    #     authenticate do
+    #       verify_signature header: "X-Hub-Signature-256",
+    #                        secret: ENV['GITHUB_WEBHOOK_SECRET'],
+    #                        algorithm: :sha256,
+    #                        prefix: "sha256="
+    #     end
+    #     on_request do |context|
+    #       # Handle the webhook
+    #     end
+    #   end
+    class WebhookDefinition
+      attr_reader :path, :http_method, :handler, :authentication, :validations
+
+      # Initialize webhook definition
+      #
+      # @param path [String] URL path for the webhook
+      def initialize(path)
+        @path = path
+        @http_method = :post
+        @handler = nil
+        @authentication = nil
+        @validations = []
+      end
+
+      # Set HTTP method
+      #
+      # @param method_name [Symbol] HTTP method (:get, :post, :put, :delete, :patch)
+      # @return [void]
+      def method(method_name)
+        @http_method = method_name
+      end
+
+      # Define authentication for this webhook
+      #
+      # @yield Authentication configuration block
+      # @return [void]
+      def authenticate(&block)
+        @authentication = WebhookAuthentication.new
+        @authentication.instance_eval(&block) if block
+      end
+
+      # Require specific headers
+      #
+      # @param headers [Hash] Required headers and their expected values (nil = just check presence)
+      # @return [void]
+      def require_headers(headers)
+        @validations << { type: :headers, config: headers }
+      end
+
+      # Require specific content type
+      #
+      # @param content_type [String, Array<String>] Allowed content type(s)
+      # @return [void]
+      def require_content_type(*content_types)
+        @validations << { type: :content_type, config: content_types.flatten }
+      end
+
+      # Add custom validation
+      #
+      # @yield [context] Validation block
+      # @yieldreturn [Boolean, String] true if valid, or error message string if invalid
+      # @return [void]
+      def validate(&block)
+        @validations << { type: :custom, config: block }
+      end
+
+      # Define the request handler
+      #
+      # @yield [context] Request handler block
+      # @yieldparam context [Hash] Request context with :path, :method, :headers, :params, :body
+      # @return [void]
+      def on_request(&block)
+        @handler = block
+      end
+
+      # Register this webhook with a web server
+      #
+      # @param web_server [LanguageOperator::Agent::WebServer] Web server instance
+      # @return [void]
+      def register(web_server)
+        return unless @handler
+
+        web_server.register_route(
+          @path,
+          method: @http_method,
+          authentication: @authentication,
+          validations: @validations,
+          &@handler
+        )
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/workflow_definition.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require_relative '../logger'
+require_relative '../loggable'
+
+module LanguageOperator
+  module Dsl
+    # Workflow definition for agent execution
+    #
+    # Defines a series of steps that an agent executes to achieve objectives.
+    # Steps can depend on other steps, call tools, or perform LLM processing.
+    #
+    # @example Define a workflow
+    #   workflow do
+    #     step :search do
+    #       tool "web_search"
+    #       params query: "latest news"
+    #     end
+    #
+    #     step :summarize do
+    #       depends_on :search
+    #       prompt "Summarize: {search.output}"
+    #     end
+    #   end
+    class WorkflowDefinition
+      include LanguageOperator::Loggable
+
+      attr_reader :steps, :step_order
+
+      def initialize
+        @steps = {}
+        @step_order = []
+      end
+
+      # Define a workflow step
+      #
+      # @param name [Symbol] Step name
+      # @param tool [String, nil] Tool to use (optional)
+      # @param params [Hash] Tool parameters (optional)
+      # @param depends_on [Symbol, Array<Symbol>] Dependencies (optional)
+      # @yield Step definition block
+      # @return [void]
+      def step(name, tool: nil, params: {}, depends_on: nil, &block)
+        step_def = StepDefinition.new(name, logger: @logger)
+
+        if tool
+          step_def.tool(tool)
+          step_def.params(params) unless params.empty?
+        end
+
+        step_def.depends_on(depends_on) if depends_on
+
+        step_def.instance_eval(&block) if block
+        @steps[name] = step_def
+        @step_order << name
+      end
+
+      # Execute the workflow
+      #
+      # @param context [Object] Execution context
+      # @return [Hash] Results from each step
+      def execute(context = nil)
+        results = {}
+
+        logger.info('Executing workflow', step_count: @steps.size)
+
+        @step_order.each do |step_name|
+          step_def = @steps[step_name]
+
+          # Check dependencies
+          if step_def.dependencies.any?
+            logger.debug('Checking dependencies',
+                         step: step_name,
+                         dependencies: step_def.dependencies)
+            step_def.dependencies.each do |dep|
+              next if results.key?(dep)
+
+              logger.error('Dependency not satisfied',
+                           step: step_name,
+                           missing_dependency: dep)
+              raise "Step #{step_name} depends on #{dep}, but #{dep} has not been executed"
+            end
+          end
+
+          # Execute step
+          logger.info('Executing step',
+                      step: step_name,
+                      tool: step_def.tool_name,
+                      has_prompt: !step_def.prompt_template.nil?)
+
+          result = logger.timed('Step execution') do
+            step_def.execute(results, context)
+          end
+
+          results[step_name] = result
+          logger.info('Step completed', step: step_name)
+        end
+
+        logger.info('Workflow execution completed', total_steps: @steps.size)
+        results
+      end
+
+      private
+
+      def logger_component
+        'Workflow'
+      end
+    end
+
+    # Individual step definition
+    class StepDefinition
+      include LanguageOperator::Loggable
+
+      attr_reader :name, :dependencies, :tool_name, :tool_params, :prompt_template
+
+      def initialize(name, logger: nil)
+        @name = name
+        @tool_name = nil
+        @tool_params = {}
+        @prompt_template = nil
+        @dependencies = []
+        @execute_block = nil
+        @parent_logger = logger
+      end
+
+      # Set the tool to use
+      #
+      # @param name [String] Tool name
+      # @return [void]
+      def tool(name = nil)
+        return @tool_name if name.nil?
+
+        @tool_name = name
+      end
+
+      # Set tool parameters
+      #
+      # @param hash [Hash] Parameters
+      # @return [Hash] Current parameters
+      def params(hash = nil)
+        return @tool_params if hash.nil?
+
+        @tool_params = hash
+      end
+
+      # Set prompt template (for LLM processing)
+      #
+      # @param template [String] Prompt template
+      # @return [String] Current prompt
+      def prompt(template = nil)
+        return @prompt_template if template.nil?
+
+        @prompt_template = template
+      end
+
+      # Declare dependencies on other steps
+      #
+      # @param steps [Symbol, Array<Symbol>] Step names this depends on
+      # @return [Array<Symbol>] Current dependencies
+      def depends_on(*steps)
+        return @dependencies if steps.empty?
+
+        @dependencies = steps.flatten
+      end
+
+      # Define custom execution logic
+      #
+      # @yield Execution block
+      # @return [void]
+      def execute(&block)
+        @execute_block = block if block
+      end
+
+      # Execute this step
+      #
+      # @param results [Hash] Results from previous steps
+      # @param context [Object] Execution context
+      # @return [Object] Step result
+      def execute_step(results, context)
+        if @execute_block
+          # Custom execution logic
+          logger.debug('Executing custom logic', step: @name)
+          @execute_block.call(results, context)
+        elsif @tool_name
+          # Tool execution
+          params = interpolate_params(@tool_params, results)
+          logger.info('Calling tool',
+                      step: @name,
+                      tool: @tool_name,
+                      params: params)
+          # In real implementation, this would call the actual tool
+          "Tool #{@tool_name} executed with #{params.inspect}"
+        elsif @prompt_template
+          # LLM processing
+          prompt = interpolate_template(@prompt_template, results)
+          logger.debug('LLM prompt',
+                       step: @name,
+                       prompt: prompt[0..200])
+          # In real implementation, this would call the LLM
+          "LLM processed: #{prompt}"
+        else
+          # No-op step
+          logger.debug('No execution logic defined', step: @name)
+          nil
+        end
+      end
+
+      alias execute execute_step
+
+      private
+
+      def logger
+        @parent_logger || super
+      end
+
+      def logger_component
+        "Step:#{@name}"
+      end
+
+      # Interpolate parameters with results from previous steps
+      #
+      # @param params [Hash] Parameter template
+      # @param results [Hash] Previous results
+      # @return [Hash] Interpolated parameters
+      def interpolate_params(params, results)
+        params.transform_values do |value|
+          if value.is_a?(String) && value.match?(/\{(\w+)\.(\w+)\}/)
+            # Replace {step.field} with actual value
+            value.gsub(/\{(\w+)\.(\w+)\}/) do
+              step_name = Regexp.last_match(1).to_sym
+              field = Regexp.last_match(2)
+              results.dig(step_name, field) || value
+            end
+          else
+            value
+          end
+        end
+      end
+
+      # Interpolate template string with results
+      #
+      # @param template [String] Template string
+      # @param results [Hash] Previous results
+      # @return [String] Interpolated string
+      def interpolate_template(template, results)
+        template.gsub(/\{(\w+)(?:\.(\w+))?\}/) do
+          step_name = Regexp.last_match(1).to_sym
+          field = Regexp.last_match(2)
+
+          if field
+            results.dig(step_name, field)&.to_s || "{#{step_name}.#{field}}"
+          else
+            results[step_name]&.to_s || "{#{step_name}}"
+          end
+        end
+      end
+    end
+  end
+end