language-operator 0.0.1 → 0.1.31

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

data/lib/language_operator/dsl.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+require_relative 'dsl/tool_definition'
+require_relative 'dsl/parameter_definition'
+require_relative 'dsl/registry'
+require_relative 'dsl/adapter'
+require_relative 'dsl/config'
+require_relative 'dsl/helpers'
+require_relative 'dsl/http'
+require_relative 'dsl/shell'
+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'
+
+module LanguageOperator
+  # DSL for defining MCP tools and autonomous agents
+  #
+  # Provides a clean, Ruby-like DSL for defining tools that can be served
+  # via the Model Context Protocol (MCP) and agents that can execute autonomously.
+  #
+  # @example Define a tool
+  #   LanguageOperator::Dsl.define do
+  #     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
+  #   end
+  #
+  # @example Access tools
+  #   registry = LanguageOperator::Dsl.registry
+  #   tool = registry.get("greet")
+  #   result = tool.call({"name" => "Alice"})
+  module Dsl
+    class << self
+      # Global registry for tools
+      #
+      # @return [Registry] The global tool registry
+      def registry
+        @registry ||= Registry.new
+      end
+
+      # Global registry for agents
+      #
+      # @return [AgentRegistry] The global agent registry
+      def agent_registry
+        @agent_registry ||= AgentRegistry.new
+      end
+
+      # Define tools using the DSL
+      #
+      # @yield Block containing tool definitions
+      # @return [Registry] The global registry with defined tools
+      #
+      # @example
+      #   LanguageOperator::Dsl.define do
+      #     tool "example" do
+      #       # ...
+      #     end
+      #   end
+      def define(&)
+        context = Context.new(registry)
+        context.instance_eval(&)
+        registry
+      end
+
+      # Define agents using the DSL
+      #
+      # @yield Block containing agent definitions
+      # @return [AgentRegistry] The global agent registry
+      #
+      # @example
+      #   LanguageOperator::Dsl.define_agents do
+      #     agent "news-summarizer" do
+      #       # ...
+      #     end
+      #   end
+      def define_agents(&)
+        context = AgentContext.new(agent_registry)
+        context.instance_eval(&)
+        agent_registry
+      end
+
+      # Load tools from a file
+      #
+      # @param file_path [String] Path to the tool definition file
+      # @return [Registry] The global registry with loaded tools
+      #
+      # @example
+      #   LanguageOperator::Dsl.load_file("mcp/tools.rb")
+      def load_file(file_path)
+        code = File.read(file_path)
+        context = Context.new(registry)
+
+        # Execute in sandbox with validation
+        executor = Agent::Safety::SafeExecutor.new(context)
+        executor.eval(code, file_path)
+
+        registry
+      end
+
+      # Load agents from a file
+      #
+      # @param file_path [String] Path to the agent definition file
+      # @return [AgentRegistry] The global agent registry
+      #
+      # @example
+      #   LanguageOperator::Dsl.load_agent_file("agents/news-summarizer.rb")
+      def load_agent_file(file_path)
+        code = File.read(file_path)
+        context = AgentContext.new(agent_registry)
+
+        # Execute in sandbox with validation
+        executor = Agent::Safety::SafeExecutor.new(context)
+        executor.eval(code, file_path)
+
+        agent_registry
+      end
+
+      # Clear all defined tools
+      #
+      # @return [void]
+      def clear!
+        registry.clear
+      end
+
+      # Clear all defined agents
+      #
+      # @return [void]
+      def clear_agents!
+        agent_registry.clear
+      end
+
+      # Create an MCP server from the defined tools
+      #
+      # @param server_name [String] Name of the MCP server
+      # @param server_context [Hash] Additional context for the server
+      # @return [MCP::Server] The MCP server instance
+      #
+      # @example
+      #   server = LanguageOperator::Dsl.create_server(server_name: "my-tools")
+      def create_server(server_name: 'langop-tools', server_context: {})
+        Adapter.create_mcp_server(registry, server_name: server_name, server_context: server_context)
+      end
+    end
+  end
+end

data/lib/language_operator/errors.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  # Standardized error formatting module for consistent error messages across tools
+  module Errors
+    # Resource not found error
+    # @param resource_type [String] Type of resource (e.g., "Pod", "LanguageAgent")
+    # @param identifier [String] Resource identifier (name, ID, etc.)
+    # @return [String] Formatted error message
+    def self.not_found(resource_type, identifier)
+      "Error: #{resource_type} not found - #{identifier}"
+    end
+
+    # Access denied error
+    # @param context [String] Additional context (default: "check RBAC permissions")
+    # @return [String] Formatted error message
+    def self.access_denied(context = 'check RBAC permissions')
+      "Error: Access denied - #{context}"
+    end
+
+    # Invalid JSON parameter error
+    # @param param_name [String] Name of the parameter
+    # @return [String] Formatted error message
+    def self.invalid_json(param_name)
+      "Error: Invalid JSON in #{param_name} parameter"
+    end
+
+    # Missing configuration error
+    # @param missing_vars [String, Array<String>] Missing variable(s)
+    # @return [String] Formatted error message
+    def self.missing_config(missing_vars)
+      vars = Array(missing_vars).join(', ')
+      "Error: Missing configuration: #{vars}"
+    end
+
+    # Invalid parameter value error
+    # @param param_name [String] Parameter name
+    # @param value [String] Invalid value
+    # @param expected [String] Expected format/value
+    # @return [String] Formatted error message
+    def self.invalid_parameter(param_name, value, expected)
+      "Error: Invalid #{param_name} '#{value}'. Expected: #{expected}"
+    end
+
+    # Generic operation failed error
+    # @param operation [String] Operation that failed
+    # @param reason [String] Reason for failure
+    # @return [String] Formatted error message
+    def self.operation_failed(operation, reason)
+      "Error: #{operation} failed - #{reason}"
+    end
+
+    # Empty/missing required field error
+    # @param field_name [String] Name of the field
+    # @return [String] Formatted error message
+    def self.empty_field(field_name)
+      "Error: #{field_name} cannot be empty"
+    end
+  end
+end