language-operator 0.1.31 → 0.1.35

data/lib/language_operator/dsl/config.rb

@@ -4,8 +4,11 @@ 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.
+    # This class delegates to LanguageOperator::Config for all functionality.
+    # It exists for backwards compatibility with existing code that uses
+    # Dsl::Config.
+    #
+    # @deprecated Use LanguageOperator::Config directly instead
     #
     # @example Basic usage
     #   Config.get('SMTP_HOST', 'MAIL_HOST', default: 'localhost')
@@ -13,92 +16,45 @@ module LanguageOperator
     #   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
+      # Delegates to LanguageOperator::Config.get
       def self.get(*keys, default: nil)
-        keys.each do |key|
-          value = ENV.fetch(key.to_s, nil)
-          return value if value
-        end
-        default
+        LanguageOperator::Config.get(*keys, default: 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
+      # Delegates to LanguageOperator::Config.require
       def self.require(*keys)
-        value = get(*keys)
-        raise ArgumentError, "Missing required configuration: #{keys.join(' or ')}" unless value
-
-        value
+        LanguageOperator::Config.require(*keys)
       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
+      # Delegates to LanguageOperator::Config.get_int
       def self.get_int(*keys, default: nil)
-        value = get(*keys)
-        return default if value.nil?
-
-        value.to_i
+        LanguageOperator::Config.get_int(*keys, default: default)
       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
+      # Delegates to LanguageOperator::Config.get_bool
       def self.get_bool(*keys, default: false)
-        value = get(*keys)
-        return default if value.nil?
-
-        value.to_s.downcase.match?(/^(true|1|yes|on)$/)
+        LanguageOperator::Config.get_bool(*keys, default: default)
       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
+      # Get environment variable as array
+      # Delegates to LanguageOperator::Config.get_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?)
+        LanguageOperator::Config.get_array(*keys, default: default, separator: separator)
       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
+      # Check if environment variable is set
+      # Delegates to LanguageOperator::Config.set?
       def self.set?(*keys)
-        keys.any? { |key| ENV.key?(key.to_s) }
+        LanguageOperator::Config.set?(*keys)
       end
 
       # Get all environment variables matching a prefix
-      #
-      # @param prefix [String] Prefix to match
-      # @return [Hash<String, String>] Hash with prefix removed from keys
+      # Delegates to LanguageOperator::Config.with_prefix
       def self.with_prefix(prefix)
-        ENV.select { |key, _| key.start_with?(prefix) }
-           .transform_keys { |key| key.sub(prefix, '') }
+        LanguageOperator::Config.with_prefix(prefix)
       end
 
       # Build a configuration hash from environment variables
@@ -109,11 +65,19 @@ module LanguageOperator
         config = {}
         mappings.each do |config_key, env_keys|
           env_keys = [env_keys] unless env_keys.is_a?(Array)
-          value = get(*env_keys)
+          value = LanguageOperator::Config.get(*env_keys)
           config[config_key] = value if value
         end
         config
       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
     end
   end
 end

data/lib/language_operator/dsl/main_definition.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative '../loggable'
+
+module LanguageOperator
+  module Dsl
+    # Main execution block for agents (DSL v1)
+    #
+    # Defines the imperative entry point for agent execution. The main block receives
+    # agent inputs and returns agent outputs. Within the block, agents can call tasks
+    # using execute_task(), use standard Ruby control flow (if/else, loops), and handle
+    # errors with standard Ruby exceptions.
+    #
+    # This replaces the declarative workflow/step model with an imperative programming
+    # model centered on organic functions (tasks).
+    #
+    # @example Simple main block
+    #   main do |inputs|
+    #     result = execute_task(:fetch_data, inputs: inputs)
+    #     execute_task(:process_data, inputs: result)
+    #   end
+    #
+    # @example Main block with control flow
+    #   main do |inputs|
+    #     data = execute_task(:fetch_data, inputs: inputs)
+    #
+    #     if data[:count] > 100
+    #       execute_task(:send_alert, inputs: { count: data[:count] })
+    #     end
+    #
+    #     execute_task(:save_results, inputs: data)
+    #   end
+    #
+    # @example Main block with error handling
+    #   main do |inputs|
+    #     begin
+    #       result = execute_task(:risky_operation, inputs: inputs)
+    #       { success: true, result: result }
+    #     rescue => e
+    #       logger.error("Operation failed: #{e.message}")
+    #       { success: false, error: e.message }
+    #     end
+    #   end
+    class MainDefinition
+      include LanguageOperator::Loggable
+
+      attr_reader :execute_block
+
+      # Initialize a new main definition
+      def initialize
+        @execute_block = nil
+      end
+
+      # Define the main execution block
+      #
+      # @yield [inputs] Block that receives agent inputs and returns agent outputs
+      # @yieldparam inputs [Hash] Agent input parameters
+      # @yieldreturn [Object] Agent output (typically a Hash)
+      # @return [void]
+      # @example
+      #   execute do |inputs|
+      #     result = execute_task(:my_task, inputs: inputs)
+      #     result
+      #   end
+      def execute(&block)
+        raise ArgumentError, 'Main block is required' unless block
+
+        @execute_block = block
+        logger.debug('Main block defined', arity: block.arity)
+      end
+
+      # Execute the main block with given inputs
+      #
+      # @param inputs [Hash] Agent input parameters
+      # @param context [Object] Execution context that provides execute_task method
+      # @return [Object] Result from main block
+      # @raise [RuntimeError] If main block is not defined
+      # @raise [ArgumentError] If inputs is not a Hash
+      def call(inputs, context)
+        raise 'Main block not defined. Use execute { |inputs| ... } to define it.' unless @execute_block
+        raise ArgumentError, "inputs must be a Hash, got #{inputs.class}" unless inputs.is_a?(Hash)
+
+        logger.info('Executing main block', inputs_keys: inputs.keys)
+
+        result = logger.timed('Main execution') do
+          # Execute block in context to provide access to execute_task
+          context.instance_exec(inputs, &@execute_block)
+        end
+
+        logger.info('Main block completed')
+        result
+      rescue StandardError => e
+        logger.error('Main block execution failed',
+                     error: e.class.name,
+                     message: e.message,
+                     backtrace: e.backtrace&.first(5))
+        raise
+      end
+
+      # Check if main block is defined
+      #
+      # @return [Boolean] True if execute block is set
+      def defined?
+        !@execute_block.nil?
+      end
+
+      private
+
+      def logger_component
+        'Main'
+      end
+    end
+  end
+end

data/lib/language_operator/dsl/schema.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../version'
+require_relative '../constants'
 
 module LanguageOperator
   module Dsl
@@ -164,7 +165,7 @@ module LanguageOperator
           mode: {
             type: 'string',
             description: 'Execution mode for the agent',
-            enum: %w[autonomous scheduled reactive]
+            enum: Constants::PRIMARY_MODES
           },
           objectives: {
             type: 'array',
@@ -174,9 +175,19 @@ module LanguageOperator
             },
             minItems: 0
           },
-          workflow: {
-            '$ref': '#/definitions/WorkflowDefinition'
+          # DSL v1 (task/main model)
+          tasks: {
+            type: 'array',
+            description: 'Task definitions (organic functions with stable contracts)',
+            items: {
+              '$ref': '#/definitions/TaskDefinition'
+            }
           },
+          main: {
+            '$ref': '#/definitions/MainDefinition',
+            description: 'Main execution block (imperative entry point)'
+          },
+          # Common properties
           constraints: {
             '$ref': '#/definitions/ConstraintsDefinition'
           },
@@ -204,8 +215,11 @@ module LanguageOperator
       # @return [Hash] Schema definitions for nested types
       def self.all_definitions
         {
-          WorkflowDefinition: workflow_definition_schema,
-          StepDefinition: step_definition_schema,
+          # DSL v1 (task/main model)
+          TaskDefinition: task_definition_schema,
+          MainDefinition: main_definition_schema,
+          TypeSchema: type_schema_definition,
+          # Common definitions
           ConstraintsDefinition: constraints_definition_schema,
           OutputDefinition: output_definition_schema,
           WebhookDefinition: webhook_definition_schema,
@@ -217,62 +231,89 @@ module LanguageOperator
         }
       end
 
-      # Workflow definition schema
+      # Task definition schema (DSL v1)
       #
-      # @return [Hash] Schema for workflow definitions
-      def self.workflow_definition_schema
+      # @return [Hash] Schema for task definitions (organic functions)
+      def self.task_definition_schema
         {
           type: 'object',
-          description: 'Multi-step workflow with dependencies',
+          description: 'Organic function with stable contract (inputs/outputs) and evolving implementation',
           properties: {
-            steps: {
-              type: 'array',
-              description: 'Ordered list of workflow steps',
-              items: {
-                '$ref': '#/definitions/StepDefinition'
-              }
+            name: {
+              type: 'string',
+              description: 'Task identifier (symbol)',
+              pattern: '^[a-z_][a-z0-9_]*$'
+            },
+            inputs: {
+              '$ref': '#/definitions/TypeSchema',
+              description: 'Input contract (parameter types)'
+            },
+            outputs: {
+              '$ref': '#/definitions/TypeSchema',
+              description: 'Output contract (return value types)'
+            },
+            instructions: {
+              type: 'string',
+              description: 'Natural language instructions for neural implementation (optional)'
+            },
+            implementation_type: {
+              type: 'string',
+              description: 'Implementation approach',
+              enum: %w[neural symbolic hybrid undefined]
             }
-          }
+          },
+          required: %w[name inputs outputs]
         }
       end
 
-      # Step definition schema
+      # Main definition schema (DSL v1)
       #
-      # @return [Hash] Schema for workflow steps
-      def self.step_definition_schema
+      # @return [Hash] Schema for main execution block
+      def self.main_definition_schema
         {
           type: 'object',
-          description: 'Individual workflow step',
+          description: 'Imperative entry point for agent execution',
           properties: {
-            name: {
+            type: {
               type: 'string',
-              description: 'Step identifier (symbol or string)'
+              description: 'Block type',
+              enum: ['main']
             },
-            tool: {
+            description: {
               type: 'string',
-              description: 'Tool name to execute in this step'
-            },
-            params: {
-              type: 'object',
-              description: 'Parameters to pass to the tool',
-              additionalProperties: true
-            },
-            depends_on: {
-              oneOf: [
-                { type: 'string' },
-                {
-                  type: 'array',
-                  items: { type: 'string' }
-                }
-              ],
-              description: 'Step dependencies (must complete before this step)'
-            },
-            prompt: {
+              description: 'Main block executes tasks using execute_task() with Ruby control flow'
+            }
+          },
+          additionalProperties: false
+        }
+      end
+
+      # Type schema definition (DSL v1)
+      #
+      # @return [Hash] Schema for type schemas used in task inputs/outputs
+      def self.type_schema_definition
+        {
+          type: 'object',
+          description: 'Type schema for task contract validation',
+          patternProperties: {
+            '^[a-z_][a-z0-9_]*$': {
               type: 'string',
-              description: 'LLM prompt template for this step'
+              description: 'Parameter type',
+              enum: %w[string integer number boolean array hash any]
             }
           },
-          required: %w[name]
+          additionalProperties: false,
+          examples: [
+            {
+              user_id: 'integer',
+              name: 'string',
+              active: 'boolean'
+            },
+            {
+              data: 'array',
+              metadata: 'hash'
+            }
+          ]
         }
       end