language-operator 0.1.31 → 0.1.35

data/lib/language_operator/cli/commands/use.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'thor'
+require_relative '../base_command'
 require 'pastel'
 require_relative '../formatters/progress_formatter'
 require_relative '../../config/cluster_config'
@@ -9,37 +9,34 @@ module LanguageOperator
   module CLI
     module Commands
       # Switch cluster context command
-      class Use < Thor
+      class Use < BaseCommand
         desc 'use CLUSTER', 'Switch to a different cluster context'
         def self.exit_on_failure?
           true
         end
 
         def switch(cluster_name)
-          unless Config::ClusterConfig.cluster_exists?(cluster_name)
-            Formatters::ProgressFormatter.error("Cluster '#{cluster_name}' not found")
-            puts "\nAvailable clusters:"
-            Config::ClusterConfig.list_clusters.each do |cluster|
-              puts "  - #{cluster[:name]}"
+          handle_command_error('switch cluster') do
+            unless Config::ClusterConfig.cluster_exists?(cluster_name)
+              Formatters::ProgressFormatter.error("Cluster '#{cluster_name}' not found")
+              puts "\nAvailable clusters:"
+              Config::ClusterConfig.list_clusters.each do |cluster|
+                puts "  - #{cluster[:name]}"
+              end
+              exit 1
             end
-            exit 1
-          end
-
-          Config::ClusterConfig.set_current_cluster(cluster_name)
-          cluster = Config::ClusterConfig.get_cluster(cluster_name)
 
-          Formatters::ProgressFormatter.success("Switched to cluster '#{cluster_name}'")
+            Config::ClusterConfig.set_current_cluster(cluster_name)
+            cluster = Config::ClusterConfig.get_cluster(cluster_name)
 
-          pastel = Pastel.new
-          puts "\nCluster Details"
-          puts '----------------'
-          puts "Name: #{pastel.bold.white(cluster[:name])}"
-          puts "Namespace: #{pastel.bold.white(cluster[:namespace])}"
-        rescue StandardError => e
-          Formatters::ProgressFormatter.error("Failed to switch cluster: #{e.message}")
-          raise if ENV['DEBUG']
+            Formatters::ProgressFormatter.success("Switched to cluster '#{cluster_name}'")
 
-          exit 1
+            pastel = Pastel.new
+            puts "\nCluster Details"
+            puts '----------------'
+            puts "Name: #{pastel.bold.white(cluster[:name])}"
+            puts "Namespace: #{pastel.bold.white(cluster[:namespace])}"
+          end
         end
       end
     end

data/lib/language_operator/cli/helpers/resource_dependency_checker.rb

@@ -50,24 +50,6 @@ module LanguageOperator
         def self.tool_usage_count(agents, tool_name)
           agents_using_tool(agents, tool_name).size
         end
-
-        # Count how many agents use a specific model
-        #
-        # @param agents [Array<Hash>] Array of agent resources
-        # @param model_name [String] Name of the model
-        # @return [Integer] Count of agents using this model
-        def self.model_usage_count(agents, model_name)
-          agents_using_model(agents, model_name).size
-        end
-
-        # Count how many agents use a specific persona
-        #
-        # @param agents [Array<Hash>] Array of agent resources
-        # @param persona_name [String] Name of the persona
-        # @return [Integer] Count of agents using this persona
-        def self.persona_usage_count(agents, persona_name)
-          agents_using_persona(agents, persona_name).size
-        end
       end
     end
   end

data/lib/language_operator/cli/wizards/quickstart_wizard.rb

@@ -413,7 +413,6 @@ module LanguageOperator
         end
 
         def create_model_resource(cluster_info, name, provider, model, api_key = nil, endpoint = nil)
-          # rubocop:disable Metrics/BlockLength
           Formatters::ProgressFormatter.with_spinner("Creating model '#{name}'") do
             k8s = Kubernetes::Client.new(
               kubeconfig: cluster_info[:kubeconfig],

data/lib/language_operator/client/config.rb

@@ -34,12 +34,13 @@ module LanguageOperator
         {
           'llm' => {
             'provider' => detect_provider_from_env,
-            'model' => ENV.fetch('LLM_MODEL') { default_model_from_env },
+            'model' => LanguageOperator::Config.get('LLM_MODEL', default: default_model_from_env),
             'endpoint' => parse_model_endpoint_from_env,
-            'api_key' => ENV.fetch('OPENAI_API_KEY') { ENV.fetch('ANTHROPIC_API_KEY', 'dummy-key-for-local-proxy') }
+            'api_key' => LanguageOperator::Config.get('OPENAI_API_KEY', 'ANTHROPIC_API_KEY',
+                                                      default: 'dummy-key-for-local-proxy')
           },
           'mcp_servers' => parse_mcp_servers_from_env,
-          'debug' => ENV['DEBUG'] == 'true'
+          'debug' => LanguageOperator::Config.get_bool('DEBUG', default: false)
         }
       end
 
@@ -49,15 +50,12 @@ module LanguageOperator
       #
       # @return [String, nil] Model endpoint URL
       def self.parse_model_endpoint_from_env
-        # Support MODEL_ENDPOINTS (operator sets this)
-        endpoints_env = ENV.fetch('MODEL_ENDPOINTS', nil)
-        if endpoints_env && !endpoints_env.empty?
-          # Take the first endpoint from comma-separated list
-          endpoints_env.split(',').first.strip
-        else
-          # Fallback to legacy OPENAI_ENDPOINT
-          ENV.fetch('OPENAI_ENDPOINT', nil)
-        end
+        # Support MODEL_ENDPOINTS (operator sets this) - take first from comma-separated list
+        endpoints = LanguageOperator::Config.get_array('MODEL_ENDPOINTS')
+        return endpoints.first unless endpoints.empty?
+
+        # Fallback to legacy OPENAI_ENDPOINT
+        LanguageOperator::Config.get('OPENAI_ENDPOINT')
       end
 
       # Load configuration with automatic fallback to environment variables
@@ -79,11 +77,11 @@ module LanguageOperator
       # @return [String] Provider name (openai_compatible, openai, or anthropic)
       # @raise [RuntimeError] If no API key or endpoint is found
       def self.detect_provider_from_env
-        if ENV['OPENAI_ENDPOINT'] || ENV['MODEL_ENDPOINTS']
+        if LanguageOperator::Config.set?('OPENAI_ENDPOINT', 'MODEL_ENDPOINTS')
           'openai_compatible'
-        elsif ENV['OPENAI_API_KEY']
+        elsif LanguageOperator::Config.set?('OPENAI_API_KEY')
           'openai'
-        elsif ENV['ANTHROPIC_API_KEY']
+        elsif LanguageOperator::Config.set?('ANTHROPIC_API_KEY')
           'anthropic'
         else
           raise 'No API key or endpoint found. Set OPENAI_ENDPOINT or MODEL_ENDPOINTS for local LLM, ' \
@@ -109,21 +107,22 @@ module LanguageOperator
       # @return [Array<Hash>] Array of MCP server configurations
       def self.parse_mcp_servers_from_env
         # Support both MCP_SERVERS (comma-separated) and legacy MCP_URL
-        servers_env = ENV.fetch('MCP_SERVERS', nil)
-        if servers_env && !servers_env.empty?
+        servers = LanguageOperator::Config.get_array('MCP_SERVERS')
+
+        if !servers.empty?
           # Parse comma-separated URLs
-          servers_env.split(',').map.with_index do |url, index|
+          servers.map.with_index do |url, index|
             {
               'name' => "default-tools-#{index}",
-              'url' => url.strip,
+              'url' => url,
               'transport' => 'streamable',
               'enabled' => true
             }
           end
-        elsif ENV['MCP_URL']
+        elsif (url = LanguageOperator::Config.get('MCP_URL'))
           [{
             'name' => 'default-tools',
-            'url' => ENV['MCP_URL'],
+            'url' => url,
             'transport' => 'streamable',
             'enabled' => true
           }]

data/lib/language_operator/config.rb

@@ -8,8 +8,9 @@ module LanguageOperator
   # - Key-to-env-var mappings
   # - Prefixes (e.g., SMTP_HOST from prefix: 'SMTP')
   # - Default values
-  # - Type conversion (string, integer, boolean, float)
+  # - Type conversion (string, integer, boolean, float, array)
   # - Required config validation
+  # - Multiple fallback keys
   #
   # @example Load SMTP configuration
   #   config = LanguageOperator::Config.load(
@@ -75,7 +76,8 @@ module LanguageOperator
     # Convert a string value to the specified type
     #
     # @param value [String, nil] Raw string value from environment
-    # @param type [Symbol] Target type (:string, :integer, :boolean, :float)
+    # @param type [Symbol] Target type (:string, :integer, :boolean, :float, :array)
+    # @param separator [String] Separator for array type (default: ',')
     # @return [Object] Converted value
     #
     # @example String conversion
@@ -92,7 +94,10 @@ module LanguageOperator
     #
     # @example Float conversion
     #   Config.convert_type('3.14', :float) # => 3.14
-    def self.convert_type(value, type)
+    #
+    # @example Array conversion
+    #   Config.convert_type('a,b,c', :array) # => ["a", "b", "c"]
+    def self.convert_type(value, type, separator: ',')
       return nil if value.nil?
 
       case type
@@ -104,6 +109,10 @@ module LanguageOperator
         value.to_f
       when :boolean
         %w[true 1 yes on].include?(value.to_s.downcase)
+      when :array
+        return [] if value.to_s.empty?
+
+        value.to_s.split(separator).map(&:strip).reject(&:empty?)
       else
         value
       end
@@ -134,5 +143,108 @@ module LanguageOperator
       validate_required!(config, required) unless required.empty?
       config
     end
+
+    # 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
+    #
+    # @example
+    #   Config.get('SMTP_HOST', 'MAIL_HOST', default: 'localhost')
+    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
+    #
+    # @example
+    #   Config.require('DATABASE_URL', 'DB_URL')
+    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
+    #
+    # @example
+    #   Config.get_int('MAX_WORKERS', default: 4)
+    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
+    #
+    # @example
+    #   Config.get_bool('USE_TLS', 'ENABLE_TLS', default: true)
+    def self.get_bool(*keys, default: false)
+      value = get(*keys)
+      return default if value.nil?
+
+      %w[true 1 yes on].include?(value.to_s.downcase)
+    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
+    #
+    # @example
+    #   Config.get_array('ALLOWED_HOSTS', separator: ',')
+    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 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
+    #
+    # @example
+    #   Config.set?('DEBUG', 'VERBOSE')
+    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
+    #
+    # @example
+    #   Config.with_prefix('DATABASE_')
+    #   # Returns { 'URL' => '...', 'POOL_SIZE' => '5' } for DATABASE_URL and DATABASE_POOL_SIZE
+    def self.with_prefix(prefix)
+      ENV.select { |key, _| key.start_with?(prefix) }
+         .transform_keys { |key| key.sub(prefix, '') }
+    end
   end
 end

data/lib/language_operator/constants.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  # Shared constants used across the Language Operator gem
+  module Constants
+    # Agent execution modes with their aliases
+    # Primary modes are the canonical forms used in CRD schemas
+    # Aliases are accepted for backwards compatibility and convenience
+    EXECUTION_MODES = {
+      autonomous: %w[autonomous interactive].freeze,
+      scheduled: %w[scheduled event-driven].freeze,
+      reactive: %w[reactive http webhook].freeze
+    }.freeze
+
+    # Primary (canonical) execution modes for schema definitions
+    PRIMARY_MODES = %w[autonomous scheduled reactive].freeze
+
+    # All valid mode strings (primary + aliases)
+    ALL_MODE_ALIASES = EXECUTION_MODES.values.flatten.freeze
+
+    # Normalizes a mode string to its primary canonical form
+    #
+    # @param mode_string [String] The mode string to normalize
+    # @return [String] The canonical primary mode
+    # @raise [ArgumentError] if the mode string is not recognized
+    #
+    # @example
+    #   Constants.normalize_mode('interactive') # => 'autonomous'
+    #   Constants.normalize_mode('webhook')     # => 'reactive'
+    #   Constants.normalize_mode('scheduled')   # => 'scheduled'
+    def self.normalize_mode(mode_string)
+      return nil if mode_string.nil?
+
+      mode_string = mode_string.to_s.downcase.strip
+
+      EXECUTION_MODES.each do |primary, aliases|
+        return primary.to_s if aliases.include?(mode_string)
+      end
+
+      raise ArgumentError, "Unknown execution mode: #{mode_string}. " \
+                           "Valid modes: #{ALL_MODE_ALIASES.join(', ')}"
+    end
+
+    # Validates that a mode string is recognized
+    #
+    # @param mode_string [String] The mode string to validate
+    # @return [Boolean] true if valid, false otherwise
+    def self.valid_mode?(mode_string)
+      return false if mode_string.nil?
+
+      ALL_MODE_ALIASES.include?(mode_string.to_s.downcase.strip)
+    end
+  end
+end

data/lib/language_operator/dsl/agent_context.rb

@@ -13,14 +13,14 @@ module LanguageOperator
     #
     #     schedule "0 12 * * *"
     #
-    #     objectives [
-    #       "Search for recent news",
-    #       "Summarize findings"
-    #     ]
+    #     task :search,
+    #       instructions: "search for recent news",
+    #       inputs: {},
+    #       outputs: { results: 'array' }
     #
-    #     workflow do
-    #       step :search, tool: "web_search"
-    #       step :summarize, depends_on: :search
+    #     main do |inputs|
+    #       results = execute_task(:search)
+    #       results
     #     end
     #   end
     class AgentContext

data/lib/language_operator/dsl/agent_definition.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'workflow_definition'
+require_relative 'main_definition'
+require_relative 'task_definition'
 require_relative 'webhook_definition'
 require_relative 'mcp_server_definition'
 require_relative 'chat_endpoint_definition'
@@ -11,7 +12,7 @@ module LanguageOperator
   module Dsl
     # Agent definition for autonomous agents
     #
-    # Defines an agent with objectives, workflow, schedule, and constraints.
+    # Defines an agent with objectives, tasks, main execution block, schedule, and constraints.
     # Used within the DSL to create agents that can be executed standalone
     # or deployed to Kubernetes.
     #
@@ -21,14 +22,14 @@ module LanguageOperator
     #
     #     schedule "0 12 * * *"
     #
-    #     objectives [
-    #       "Search for recent news",
-    #       "Summarize findings"
-    #     ]
+    #     task :search,
+    #       instructions: "search for latest news",
+    #       inputs: {},
+    #       outputs: { results: 'array' }
     #
-    #     workflow do
-    #       step :search, tool: "web_search", params: {query: "latest news"}
-    #       step :summarize, depends_on: :search
+    #     main do |inputs|
+    #       results = execute_task(:search)
+    #       results
     #     end
     #   end
     #
@@ -47,7 +48,7 @@ module LanguageOperator
     class AgentDefinition
       include LanguageOperator::Loggable
 
-      attr_reader :name, :description, :persona, :schedule, :objectives, :workflow,
+      attr_reader :name, :description, :persona, :schedule, :objectives, :main, :tasks,
                   :constraints, :output_config, :execution_mode, :webhooks, :mcp_server, :chat_endpoint
 
       def initialize(name)
@@ -56,7 +57,8 @@ module LanguageOperator
         @persona = nil
         @schedule = nil
         @objectives = []
-        @workflow = nil
+        @main = nil
+        @tasks = {}
         @constraints = {}
         @output_config = {}
         @execution_mode = :autonomous
@@ -118,16 +120,95 @@ module LanguageOperator
         @objectives << text
       end
 
-      # Define workflow with steps
+      # Define main execution block (DSL v1)
       #
-      # @yield Workflow definition block
-      # @return [WorkflowDefinition] Current workflow
-      def workflow(&block)
-        return @workflow if block.nil?
+      # The main block is the imperative entry point for agent execution.
+      # It receives agent inputs and returns agent outputs. Use execute_task()
+      # to call organic functions (tasks) defined with the task directive.
+      #
+      # @yield Main execution block
+      # @return [MainDefinition] Current main definition
+      # @example
+      #   main do |inputs|
+      #     result = execute_task(:fetch_data, inputs: inputs)
+      #     execute_task(:process_data, inputs: result)
+      #   end
+      def main(&block)
+        return @main if block.nil?
+
+        @main = MainDefinition.new
+        @main.execute(&block) if block
+        @main
+      end
+
+      # Define a task (organic function) - DSL v1
+      #
+      # Tasks are the core primitive of DSL v1, representing organic functions with
+      # stable input/output contracts. Tasks can be neural (instructions-based),
+      # symbolic (code-based), or hybrid (both).
+      #
+      # @param name [Symbol] Task name
+      # @param options [Hash] Task configuration
+      # @option options [Hash] :inputs Input schema (param => type)
+      # @option options [Hash] :outputs Output schema (field => type)
+      # @option options [String] :instructions Natural language instructions (neural)
+      # @yield [inputs] Symbolic implementation block (optional)
+      # @yieldparam inputs [Hash] Validated input parameters
+      # @yieldreturn [Hash] Output matching outputs schema
+      # @return [TaskDefinition] The task definition
+      #
+      # @example Neural task
+      #   task :analyze_data,
+      #     instructions: "Analyze the data for anomalies",
+      #     inputs: { data: 'array' },
+      #     outputs: { issues: 'array', summary: 'string' }
+      #
+      # @example Symbolic task
+      #   task :calculate_total,
+      #     inputs: { items: 'array' },
+      #     outputs: { total: 'number' }
+      #   do |inputs|
+      #     { total: inputs[:items].sum { |i| i['amount'] } }
+      #   end
+      #
+      # @example Hybrid task
+      #   task :fetch_user,
+      #     instructions: "Fetch user from database",
+      #     inputs: { user_id: 'integer' },
+      #     outputs: { user: 'hash' }
+      #   do |inputs|
+      #     execute_tool('database', 'get_user', id: inputs[:user_id])
+      #   end
+      def task(name, **options, &block)
+        # Create task definition
+        task_def = TaskDefinition.new(name)
+
+        # Configure from options (keyword arguments)
+        task_def.inputs(options[:inputs]) if options[:inputs]
+        task_def.outputs(options[:outputs]) if options[:outputs]
+        task_def.instructions(options[:instructions]) if options[:instructions]
+
+        # Symbolic implementation (if block provided)
+        task_def.execute(&block) if block
+
+        # Store in tasks collection
+        @tasks[name] = task_def
+
+        task_type = if task_def.neural? && task_def.symbolic?
+                      'hybrid'
+                    elsif task_def.neural?
+                      'neural'
+                    else
+                      'symbolic'
+                    end
+
+        logger.debug('Task defined',
+                     name: name,
+                     type: task_type,
+                     inputs: options[:inputs]&.keys || [],
+                     outputs: options[:outputs]&.keys || [])
 
-        @workflow = WorkflowDefinition.new
-        @workflow.instance_eval(&block) if block
-        @workflow
+        task_def
       end
 
       # Define constraints (max_iterations, timeout, etc.)
@@ -213,7 +294,7 @@ module LanguageOperator
                     name: @name,
                     mode: @execution_mode,
                     objectives_count: @objectives.size,
-                    has_workflow: !@workflow.nil?)
+                    has_main: !@main.nil?)
 
         case @execution_mode
         when :scheduled
@@ -317,7 +398,7 @@ module LanguageOperator
       def execute_objectives
         logger.info('Executing objectives',
                     total: @objectives.size,
-                    has_workflow: !@workflow.nil?)
+                    has_main: !@main.nil?)
 
         @objectives.each_with_index do |objective, index|
           logger.info('Executing objective',
@@ -325,13 +406,13 @@ module LanguageOperator
                       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)
+          # If main defined, execute it; otherwise just log
+          if @main
+            logger.timed('Objective main execution') do
+              @main.call({ objective: objective })
             end
           else
-            logger.warn('No workflow defined, skipping execution')
+            logger.warn('No main block defined, skipping execution')
           end
         end
 
@@ -353,6 +434,10 @@ module LanguageOperator
         @constraints[:timeout] = value
       end
 
+      def max_retries(value)
+        @constraints[:max_retries] = value
+      end
+
       def memory(value)
         @constraints[:memory] = value
       end