language-operator 0.0.1 → 0.1.30

data/lib/language_operator/dsl/agent_definition.rb

@@ -0,0 +1,427 @@
+# frozen_string_literal: true
+
+require_relative 'workflow_definition'
+require_relative 'webhook_definition'
+require_relative 'mcp_server_definition'
+require_relative 'chat_endpoint_definition'
+require_relative '../logger'
+require_relative '../loggable'
+
+module LanguageOperator
+  module Dsl
+    # Agent definition for autonomous agents
+    #
+    # Defines an agent with objectives, workflow, schedule, and constraints.
+    # Used within the DSL to create agents that can be executed standalone
+    # or deployed to Kubernetes.
+    #
+    # @example Define a simple scheduled agent
+    #   agent "news-summarizer" do
+    #     description "Daily news summarization agent"
+    #
+    #     schedule "0 12 * * *"
+    #
+    #     objectives [
+    #       "Search for recent news",
+    #       "Summarize findings"
+    #     ]
+    #
+    #     workflow do
+    #       step :search, tool: "web_search", params: {query: "latest news"}
+    #       step :summarize, depends_on: :search
+    #     end
+    #   end
+    #
+    # @example Define a webhook agent
+    #   agent "github-webhook" do
+    #     description "Handle GitHub webhooks"
+    #     mode :reactive
+    #
+    #     webhook "/github/pr-opened" do
+    #       method :post
+    #       on_request do |context|
+    #         # Process webhook
+    #       end
+    #     end
+    #   end
+    class AgentDefinition
+      include LanguageOperator::Loggable
+
+      attr_reader :name, :description, :persona, :schedule, :objectives, :workflow,
+                  :constraints, :output_config, :execution_mode, :webhooks, :mcp_server, :chat_endpoint
+
+      def initialize(name)
+        @name = name
+        @description = nil
+        @persona = nil
+        @schedule = nil
+        @objectives = []
+        @workflow = nil
+        @constraints = {}
+        @output_config = {}
+        @execution_mode = :autonomous
+        @webhooks = []
+        @mcp_server = nil
+        @chat_endpoint = nil
+
+        logger.debug('Agent definition initialized',
+                     name: name,
+                     mode: @execution_mode)
+      end
+
+      # Set or get description
+      #
+      # @param val [String, nil] Description text
+      # @return [String] Current description
+      def description(val = nil)
+        return @description if val.nil?
+
+        @description = val
+      end
+
+      # Set persona/system prompt
+      #
+      # @param text [String] Persona text or system prompt
+      # @return [String] Current persona
+      def persona(text = nil)
+        return @persona if text.nil?
+
+        @persona = text
+      end
+
+      # Set schedule (cron expression)
+      #
+      # @param cron [String] Cron expression
+      # @return [String] Current schedule
+      def schedule(cron = nil)
+        return @schedule if cron.nil?
+
+        @schedule = cron
+        @execution_mode = :scheduled
+      end
+
+      # Set objectives (list of goals)
+      #
+      # @param list [Array<String>] List of objectives
+      # @return [Array<String>] Current objectives
+      def objectives(list = nil)
+        return @objectives if list.nil?
+
+        @objectives = list
+      end
+
+      # Define a single objective
+      #
+      # @param text [String] Objective text
+      # @return [void]
+      def objective(text)
+        @objectives << text
+      end
+
+      # Define workflow with steps
+      #
+      # @yield Workflow definition block
+      # @return [WorkflowDefinition] Current workflow
+      def workflow(&block)
+        return @workflow if block.nil?
+
+        @workflow = WorkflowDefinition.new
+        @workflow.instance_eval(&block) if block
+        @workflow
+      end
+
+      # Define constraints (max_iterations, timeout, etc.)
+      #
+      # @yield Constraints block
+      # @return [Hash] Current constraints
+      def constraints(&block)
+        return @constraints if block.nil?
+
+        constraint_builder = ConstraintBuilder.new
+        constraint_builder.instance_eval(&block) if block
+        @constraints = constraint_builder.to_h
+      end
+
+      # Define output configuration
+      #
+      # @yield Output configuration block
+      # @return [Hash] Current output config
+      def output(&block)
+        return @output_config if block.nil?
+
+        output_builder = OutputBuilder.new
+        output_builder.instance_eval(&block) if block
+        @output_config = output_builder.to_h
+      end
+
+      # Set execution mode
+      #
+      # @param mode [Symbol] Execution mode (:autonomous, :scheduled, :reactive)
+      # @return [Symbol] Current execution mode
+      def mode(mode = nil)
+        return @execution_mode if mode.nil?
+
+        @execution_mode = mode
+      end
+
+      # Define a webhook endpoint
+      #
+      # @param path [String] URL path for the webhook
+      # @yield Webhook configuration block
+      # @return [WebhookDefinition] The webhook definition
+      def webhook(path, &block)
+        webhook_def = WebhookDefinition.new(path)
+        webhook_def.instance_eval(&block) if block
+        @webhooks << webhook_def
+        @execution_mode = :reactive if @execution_mode == :autonomous
+        webhook_def
+      end
+
+      # Define MCP server capabilities
+      #
+      # Allows this agent to expose tools via MCP protocol.
+      # Other agents or MCP clients can discover and call these tools.
+      #
+      # @yield MCP server configuration block
+      # @return [McpServerDefinition] The MCP server definition
+      def as_mcp_server(&block)
+        @mcp_server = McpServerDefinition.new(@name)
+        @mcp_server.instance_eval(&block) if block
+        @execution_mode = :reactive if @execution_mode == :autonomous
+        @mcp_server
+      end
+
+      # Define chat endpoint capabilities
+      #
+      # Allows this agent to respond to OpenAI-compatible chat completion requests.
+      # Other systems can treat this agent as a language model.
+      #
+      # @yield Chat endpoint configuration block
+      # @return [ChatEndpointDefinition] The chat endpoint definition
+      def as_chat_endpoint(&block)
+        @chat_endpoint ||= ChatEndpointDefinition.new(@name)
+        @chat_endpoint.instance_eval(&block) if block
+        @execution_mode = :reactive if @execution_mode == :autonomous
+        @chat_endpoint
+      end
+
+      # Execute the agent
+      #
+      # @return [void]
+      def run!
+        logger.info('Starting agent',
+                    name: @name,
+                    mode: @execution_mode,
+                    objectives_count: @objectives.size,
+                    has_workflow: !@workflow.nil?)
+
+        case @execution_mode
+        when :scheduled
+          run_scheduled
+        when :autonomous
+          run_autonomous
+        when :reactive
+          run_reactive
+        else
+          logger.error('Unknown execution mode', mode: @execution_mode)
+          raise "Unknown execution mode: #{@execution_mode}"
+        end
+      end
+
+      private
+
+      def logger_component
+        "Agent:#{@name}"
+      end
+
+      def run_scheduled
+        require 'rufus-scheduler'
+
+        scheduler = Rufus::Scheduler.new
+
+        logger.info('Scheduling agent',
+                    name: @name,
+                    cron: @schedule)
+
+        scheduler.cron(@schedule) do
+          logger.timed('Scheduled execution') do
+            execute_objectives
+          end
+        end
+
+        scheduler.join
+      end
+
+      def run_autonomous
+        logger.info('Running agent in autonomous mode', name: @name)
+        execute_objectives
+      end
+
+      def run_reactive
+        logger.info('Running agent in reactive mode',
+                    name: @name,
+                    webhooks: @webhooks.size,
+                    mcp_tools: @mcp_server&.tools&.size || 0,
+                    chat_endpoint: !@chat_endpoint.nil?)
+
+        # Create an Agent::Base instance with this definition
+        require_relative '../agent/base'
+        require_relative '../agent/web_server'
+
+        # Build agent config
+        agent_config = build_agent_config
+
+        # Create agent instance
+        agent = LanguageOperator::Agent::Base.new(agent_config)
+        agent.instance_variable_set(:@mode, 'reactive')
+
+        # Create web server
+        web_server = LanguageOperator::Agent::WebServer.new(agent)
+
+        # Register webhooks
+        @webhooks.each do |webhook_def|
+          webhook_def.register(web_server)
+        end
+
+        # Register MCP tools
+        web_server.register_mcp_tools(@mcp_server) if @mcp_server&.tools?
+
+        # Register chat endpoint
+        web_server.register_chat_endpoint(@chat_endpoint, agent) if @chat_endpoint
+
+        # Start the server
+        web_server.start
+      end
+
+      # Build agent configuration hash
+      #
+      # @return [Hash] Agent configuration
+      def build_agent_config
+        {
+          'agent' => {
+            'name' => @name,
+            'instructions' => @description || "Process incoming requests for #{@name}",
+            'persona' => @persona
+          },
+          'llm' => {
+            'provider' => ENV['LLM_PROVIDER'] || 'anthropic',
+            'model' => ENV['LLM_MODEL'] || 'claude-3-5-sonnet-20241022',
+            'api_key' => ENV.fetch('ANTHROPIC_API_KEY', nil)
+          },
+          'mcp' => {
+            'servers' => {}
+          }
+        }
+      end
+
+      def execute_objectives
+        logger.info('Executing objectives',
+                    total: @objectives.size,
+                    has_workflow: !@workflow.nil?)
+
+        @objectives.each_with_index do |objective, index|
+          logger.info('Executing objective',
+                      index: index + 1,
+                      total: @objectives.size,
+                      objective: objective[0..100])
+
+          # If workflow defined, execute it; otherwise just log
+          if @workflow
+            logger.timed('Objective workflow execution') do
+              @workflow.execute(objective)
+            end
+          else
+            logger.warn('No workflow defined, skipping execution')
+          end
+        end
+
+        logger.info('All objectives completed', total: @objectives.size)
+      end
+    end
+
+    # Helper class for building constraints
+    class ConstraintBuilder
+      def initialize
+        @constraints = {}
+      end
+
+      def max_iterations(value)
+        @constraints[:max_iterations] = value
+      end
+
+      def timeout(value)
+        @constraints[:timeout] = value
+      end
+
+      def memory(value)
+        @constraints[:memory] = value
+      end
+
+      def rate_limit(value)
+        @constraints[:rate_limit] = value
+      end
+
+      # Budget constraints
+      def daily_budget(value)
+        @constraints[:daily_budget] = value
+      end
+
+      def hourly_budget(value)
+        @constraints[:hourly_budget] = value
+      end
+
+      def token_budget(value)
+        @constraints[:token_budget] = value
+      end
+
+      # Rate limiting
+      def requests_per_minute(value)
+        @constraints[:requests_per_minute] = value
+      end
+
+      def requests_per_hour(value)
+        @constraints[:requests_per_hour] = value
+      end
+
+      def requests_per_day(value)
+        @constraints[:requests_per_day] = value
+      end
+
+      # Content filtering
+      def blocked_patterns(patterns)
+        @constraints[:blocked_patterns] = patterns
+      end
+
+      def blocked_topics(topics)
+        @constraints[:blocked_topics] = topics
+      end
+
+      def to_h
+        @constraints
+      end
+    end
+
+    # Helper class for building output configuration
+    class OutputBuilder
+      def initialize
+        @config = {}
+      end
+
+      def workspace(path)
+        @config[:workspace] = path
+      end
+
+      def slack(channel:)
+        @config[:slack] = { channel: channel }
+      end
+
+      def email(to:)
+        @config[:email] = { to: to }
+      end
+
+      def to_h
+        @config
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/chat_endpoint_definition.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  module Dsl
+    # Chat endpoint definition for agents
+    #
+    # Allows agents to expose an OpenAI-compatible chat completion endpoint.
+    # Other systems can treat the agent as a language model.
+    #
+    # @example Define chat endpoint in an agent
+    #   agent "github-expert" do
+    #     as_chat_endpoint do
+    #       system_prompt "You are a GitHub API expert"
+    #       temperature 0.7
+    #       max_tokens 2000
+    #     end
+    #   end
+    class ChatEndpointDefinition
+      attr_reader :system_prompt, :temperature, :max_tokens, :model_name,
+                  :top_p, :frequency_penalty, :presence_penalty, :stop_sequences
+
+      def initialize(agent_name)
+        @agent_name = agent_name
+        @system_prompt = nil
+        @temperature = 0.7
+        @max_tokens = 2000
+        @model_name = agent_name
+        @top_p = 1.0
+        @frequency_penalty = 0.0
+        @presence_penalty = 0.0
+        @stop_sequences = nil
+      end
+
+      # Set system prompt for chat mode
+      #
+      # @param prompt [String] System prompt
+      # @return [String] Current system prompt
+      def system_prompt(prompt = nil)
+        return @system_prompt if prompt.nil?
+
+        @system_prompt = prompt
+      end
+
+      # Set temperature parameter
+      #
+      # @param value [Float] Temperature (0.0-2.0)
+      # @return [Float] Current temperature
+      def temperature(value = nil)
+        return @temperature if value.nil?
+
+        @temperature = value
+      end
+
+      # Set maximum tokens
+      #
+      # @param value [Integer] Max tokens
+      # @return [Integer] Current max tokens
+      def max_tokens(value = nil)
+        return @max_tokens if value.nil?
+
+        @max_tokens = value
+      end
+
+      # Set model name exposed in API
+      #
+      # @param name [String] Model name
+      # @return [String] Current model name
+      def model(name = nil)
+        return @model_name if name.nil?
+
+        @model_name = name
+      end
+
+      # Set top_p parameter
+      #
+      # @param value [Float] Top-p (0.0-1.0)
+      # @return [Float] Current top_p
+      def top_p(value = nil)
+        return @top_p if value.nil?
+
+        @top_p = value
+      end
+
+      # Set frequency penalty
+      #
+      # @param value [Float] Frequency penalty (-2.0 to 2.0)
+      # @return [Float] Current frequency penalty
+      def frequency_penalty(value = nil)
+        return @frequency_penalty if value.nil?
+
+        @frequency_penalty = value
+      end
+
+      # Set presence penalty
+      #
+      # @param value [Float] Presence penalty (-2.0 to 2.0)
+      # @return [Float] Current presence penalty
+      def presence_penalty(value = nil)
+        return @presence_penalty if value.nil?
+
+        @presence_penalty = value
+      end
+
+      # Set stop sequences
+      #
+      # @param sequences [Array<String>] Stop sequences
+      # @return [Array<String>] Current stop sequences
+      def stop(sequences = nil)
+        return @stop_sequences if sequences.nil?
+
+        @stop_sequences = sequences
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/config.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  module Dsl
+    # Configuration helper for managing environment variables
+    #
+    # Provides utilities for reading and managing environment variables with fallback support,
+    # type conversion, and validation. All methods are class methods.
+    #
+    # @example Basic usage
+    #   Config.get('SMTP_HOST', 'MAIL_HOST', default: 'localhost')
+    #   Config.require('DATABASE_URL')
+    #   Config.get_bool('USE_TLS', default: true)
+    class Config
+      # Get environment variable with multiple fallback keys
+      #
+      # @param keys [Array<String>] Environment variable names to try
+      # @param default [Object, nil] Default value if none found
+      # @return [String, nil] The first non-nil value or default
+      def self.get(*keys, default: nil)
+        keys.each do |key|
+          value = ENV.fetch(key.to_s, nil)
+          return value if value
+        end
+        default
+      end
+
+      # Get required environment variable with fallback keys
+      #
+      # @param keys [Array<String>] Environment variable names to try
+      # @return [String] The first non-nil value
+      # @raise [ArgumentError] If none of the keys are set
+      def self.require(*keys)
+        value = get(*keys)
+        raise ArgumentError, "Missing required configuration: #{keys.join(' or ')}" unless value
+
+        value
+      end
+
+      # Get environment variable as integer
+      #
+      # @param keys [Array<String>] Environment variable names to try
+      # @param default [Integer, nil] Default value if none found
+      # @return [Integer, nil] The value converted to integer, or default
+      def self.get_int(*keys, default: nil)
+        value = get(*keys)
+        return default if value.nil?
+
+        value.to_i
+      end
+
+      # Get environment variable as boolean
+      #
+      # Treats 'true', '1', 'yes', 'on' as true (case insensitive).
+      #
+      # @param keys [Array<String>] Environment variable names to try
+      # @param default [Boolean] Default value if none found
+      # @return [Boolean] The value as boolean
+      def self.get_bool(*keys, default: false)
+        value = get(*keys)
+        return default if value.nil?
+
+        value.to_s.downcase.match?(/^(true|1|yes|on)$/)
+      end
+
+      # Get environment variable as array (split by separator)
+      #
+      # @param keys [Array<String>] Environment variable names to try
+      # @param default [Array] Default value if none found
+      # @param separator [String] Character to split on (default: ',')
+      # @return [Array<String>] The value split into array
+      def self.get_array(*keys, default: [], separator: ',')
+        value = get(*keys)
+        return default if value.nil? || value.empty?
+
+        value.split(separator).map(&:strip).reject(&:empty?)
+      end
+
+      # Check if all required keys are present
+      #
+      # @param keys [Array<String>] Environment variable names to check
+      # @return [Array<String>] Array of missing keys (empty if all present)
+      def self.check_required(*keys)
+        keys.reject { |key| ENV.fetch(key.to_s, nil) }
+      end
+
+      # Check if environment variable is set (even if empty string)
+      #
+      # @param keys [Array<String>] Environment variable names to check
+      # @return [Boolean] True if any key is set
+      def self.set?(*keys)
+        keys.any? { |key| ENV.key?(key.to_s) }
+      end
+
+      # Get all environment variables matching a prefix
+      #
+      # @param prefix [String] Prefix to match
+      # @return [Hash<String, String>] Hash with prefix removed from keys
+      def self.with_prefix(prefix)
+        ENV.select { |key, _| key.start_with?(prefix) }
+           .transform_keys { |key| key.sub(prefix, '') }
+      end
+
+      # Build a configuration hash from environment variables
+      #
+      # @param mappings [Hash{Symbol => Array<String>, String}] Config key to env var(s) mapping
+      # @return [Hash{Symbol => String}] Configuration hash with values found
+      def self.build(mappings)
+        config = {}
+        mappings.each do |config_key, env_keys|
+          env_keys = [env_keys] unless env_keys.is_a?(Array)
+          value = get(*env_keys)
+          config[config_key] = value if value
+        end
+        config
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/context.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  module Dsl
+    # DSL context for defining tools
+    #
+    # Provides the evaluation context for tool definition files. Tools are
+    # defined using the `tool` method within this context.
+    #
+    # @example Tool definition file
+    #   tool "search" do
+    #     description "Search the web"
+    #
+    #     parameter :query do
+    #       description "Search query"
+    #       type :string
+    #       required true
+    #     end
+    #
+    #     execute do |params|
+    #       http_get("https://api.search.com?q=#{params[:query]}")
+    #     end
+    #   end
+    class Context
+      include LanguageOperator::Dsl::Helpers
+
+      # Provide access to HTTP and Shell helper classes as constants
+      HTTP = LanguageOperator::Dsl::HTTP
+      Shell = LanguageOperator::Dsl::Shell
+
+      # Initialize context with registry
+      #
+      # @param registry [LanguageOperator::Dsl::Registry] Tool registry
+      def initialize(registry)
+        @registry = registry
+      end
+
+      # Define a tool
+      #
+      # @param name [String] Tool name
+      # @yield Tool definition block
+      # @return [void]
+      def tool(name, &)
+        tool_def = ToolDefinition.new(name)
+        tool_def.instance_eval(&) if block_given?
+        @registry.register(tool_def)
+      end
+    end
+  end
+end