language-operator 0.1.31 → 0.1.35

data/lib/language_operator/synthesis_test_harness.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'json'
+require 'ruby_llm'
+require_relative 'agent/safety/ast_validator'
+
+module LanguageOperator
+  # SynthesisTestHarness replicates the Go operator's synthesis logic for local testing.
+  # This allows testing agent code generation without requiring a Kubernetes cluster.
+  #
+  # Usage:
+  #   harness = LanguageOperator::SynthesisTestHarness.new
+  #   code = harness.synthesize('synth/001/agent.yaml', model: 'claude-3-5-sonnet-20241022')
+  #   File.write('agent.rb', code)
+  #
+  class SynthesisTestHarness
+    attr_reader :template_content, :model
+
+    def initialize(model: nil)
+      @model = model || detect_default_model
+      @synthesis_endpoint = ENV.fetch('SYNTHESIS_ENDPOINT', nil)
+      @synthesis_api_key = ENV['SYNTHESIS_API_KEY'] || 'dummy'
+      @template_path = File.join(__dir__, 'templates', 'examples', 'agent_synthesis.tmpl')
+      load_template
+    end
+
+    # Synthesize agent code from a LanguageAgent YAML file
+    #
+    # @param yaml_path [String] Path to LanguageAgent YAML file
+    # @param model [String, nil] LLM model to use (overrides default)
+    # @return [String] Generated Ruby DSL code
+    def synthesize(yaml_path, model: nil)
+      agent_spec = load_agent_spec(yaml_path)
+
+      # Build synthesis request
+      request = build_synthesis_request(agent_spec)
+
+      # Build prompt from template
+      prompt = build_prompt(request)
+
+      # Call LLM
+      response = call_llm(prompt, model: model || @model)
+
+      # Extract code from markdown
+      code = extract_code_from_markdown(response)
+
+      # Validate code
+      validate_code(code)
+
+      code
+    end
+
+    private
+
+    def load_template
+      raise "Synthesis template not found at: #{@template_path}" unless File.exist?(@template_path)
+
+      @template_content = File.read(@template_path)
+    end
+
+    def load_agent_spec(yaml_path)
+      raise "Agent YAML file not found: #{yaml_path}" unless File.exist?(yaml_path)
+
+      yaml_content = File.read(yaml_path)
+      full_spec = YAML.safe_load(yaml_content, permitted_classes: [Symbol])
+
+      raise "Invalid kind: expected LanguageAgent, got #{full_spec['kind']}" unless full_spec['kind'] == 'LanguageAgent'
+
+      # Extract agent name from metadata and merge into spec
+      agent_spec = full_spec['spec'].dup
+      agent_spec['agentName'] = full_spec.dig('metadata', 'name') if full_spec.dig('metadata', 'name')
+
+      agent_spec
+    end
+
+    def build_synthesis_request(agent_spec)
+      # NOTE: agent_spec is the 'spec' section from the YAML
+      # The agent name comes from metadata.name, which we need to extract from the full YAML
+      {
+        instructions: agent_spec['instructions'],
+        agent_name: agent_spec['agentName'] || 'test-agent', # Will be overridden by metadata.name
+        tools: agent_spec['toolRefs'] || [],
+        models: agent_spec['modelRefs'] || [],
+        persona: agent_spec['personaRefs']&.first || nil
+      }
+    end
+
+    def build_prompt(request)
+      # Detect temporal intent from instructions
+      temporal_intent = detect_temporal_intent(request[:instructions])
+
+      # Format tools list
+      tools_list = format_list(request[:tools], 'No tools specified')
+
+      # Format models list
+      models_list = format_list(request[:models], 'No models specified')
+
+      # Build persona section
+      persona_section = ''
+      persona_section = "  persona <<~PERSONA\n    #{request[:persona]}\n  PERSONA\n" if request[:persona]
+
+      # Build schedule section
+      schedule_section = ''
+      schedule_rules = ''
+
+      # Build constraints section
+      constraints_section = build_constraints_section(temporal_intent)
+
+      case temporal_intent
+      when :scheduled
+        schedule_section = "\n  # Extract schedule from instructions (e.g., \"daily at noon\" -> \"0 12 * * *\")\n  schedule \"CRON_EXPRESSION\""
+        schedule_rules = "2. Schedule detected - extract cron expression from instructions\n3. Set schedule block with appropriate cron expression\n4. Use high max_iterations for continuous scheduled operation"
+      when :oneshot
+        schedule_rules = "2. One-shot execution detected - agent will run a limited number of times\n3. Do NOT include a schedule block for one-shot agents"
+      when :continuous
+        schedule_rules = "2. No temporal intent detected - defaulting to continuous execution\n3. Do NOT include a schedule block unless explicitly mentioned\n4. Use high max_iterations for continuous operation"
+      end
+
+      # Render template with variable substitution
+      rendered = @template_content.dup
+
+      # Handle conditional sections (simple implementation for {{if .ErrorContext}})
+      rendered.gsub!(/\{\{if \.ErrorContext\}\}.*?\{\{else\}\}/m, '')
+      rendered.gsub!('{{end}}', '')
+
+      # Replace variables
+      rendered.gsub!('{{.Instructions}}', request[:instructions])
+      rendered.gsub!('{{.ToolsList}}', tools_list)
+      rendered.gsub!('{{.ModelsList}}', models_list)
+      rendered.gsub!('{{.AgentName}}', request[:agent_name])
+      rendered.gsub!('{{.TemporalIntent}}', temporal_intent.to_s.capitalize)
+      rendered.gsub!('{{.PersonaSection}}', persona_section)
+      rendered.gsub!('{{.ScheduleSection}}', schedule_section)
+      rendered.gsub!('{{.ConstraintsSection}}', constraints_section)
+      rendered.gsub!('{{.ScheduleRules}}', schedule_rules)
+
+      rendered
+    end
+
+    def detect_temporal_intent(instructions)
+      return :continuous if instructions.nil? || instructions.strip.empty?
+
+      lower = instructions.downcase
+
+      # One-shot indicators
+      oneshot_keywords = ['run once', 'one time', 'single time', 'execute once', 'just once']
+      return :oneshot if oneshot_keywords.any? { |keyword| lower.include?(keyword) }
+
+      # Schedule indicators
+      schedule_keywords = %w[every daily hourly weekly monthly cron schedule periodically]
+      return :scheduled if schedule_keywords.any? { |keyword| lower.include?(keyword) }
+
+      # Default to continuous
+      :continuous
+    end
+
+    def build_constraints_section(temporal_intent)
+      case temporal_intent
+      when :oneshot
+        <<~CONSTRAINTS.chomp
+          # One-shot execution detected from instructions
+            constraints do
+              max_iterations 10
+              timeout "10m"
+            end
+        CONSTRAINTS
+      when :scheduled
+        <<~CONSTRAINTS.chomp
+          # Scheduled execution - high iteration limit for continuous operation
+            constraints do
+              max_iterations 999999
+              timeout "10m"
+            end
+        CONSTRAINTS
+      when :continuous
+        <<~CONSTRAINTS.chomp
+          # Continuous execution - no specific schedule or one-shot indicator found
+            constraints do
+              max_iterations 999999
+              timeout "10m"
+            end
+        CONSTRAINTS
+      end
+    end
+
+    def format_list(items, default_text)
+      return default_text if items.nil? || items.empty?
+
+      items.map { |item| "  - #{item}" }.join("\n")
+    end
+
+    def call_llm(prompt, model:)
+      # Priority 1: Use SYNTHESIS_ENDPOINT if configured (OpenAI-compatible)
+      return call_openai_compatible(prompt, model) if @synthesis_endpoint
+
+      # Priority 2: Detect provider from model name
+      provider, api_key = detect_provider(model)
+
+      unless api_key
+        raise "No API key found. Set either:\n  " \
+              "SYNTHESIS_ENDPOINT (for local/OpenAI-compatible)\n  " \
+              "ANTHROPIC_API_KEY (for Claude)\n  " \
+              'OPENAI_API_KEY (for GPT)'
+      end
+
+      # Configure RubyLLM for the provider
+      RubyLLM.configure do |config|
+        case provider
+        when :anthropic
+          config.anthropic_api_key = api_key
+        when :openai
+          config.openai_api_key = api_key
+        end
+      end
+
+      # Create chat and send message
+      chat = RubyLLM.chat(model: model, provider: provider)
+      response = chat.ask(prompt)
+
+      # Extract content
+      if response.respond_to?(:content)
+        response.content
+      elsif response.is_a?(Hash) && response.key?('content')
+        response['content']
+      elsif response.is_a?(String)
+        response
+      else
+        response.to_s
+      end
+    rescue StandardError => e
+      raise "LLM call failed: #{e.message}"
+    end
+
+    def call_openai_compatible(prompt, model)
+      # Configure RubyLLM for OpenAI-compatible endpoint
+      RubyLLM.configure do |config|
+        config.openai_api_key = @synthesis_api_key
+        config.openai_api_base = @synthesis_endpoint
+        config.openai_use_system_role = true # Better compatibility with local models
+      end
+
+      # Create chat with OpenAI provider (will use configured endpoint)
+      chat = RubyLLM.chat(model: model, provider: :openai, assume_model_exists: true)
+
+      # Send message
+      response = chat.ask(prompt)
+
+      # Extract content
+      if response.respond_to?(:content)
+        response.content
+      elsif response.is_a?(Hash) && response.key?('content')
+        response['content']
+      elsif response.is_a?(String)
+        response
+      else
+        response.to_s
+      end
+    rescue StandardError => e
+      raise "OpenAI-compatible endpoint call failed: #{e.message}"
+    end
+
+    def detect_provider(model)
+      if model.start_with?('claude')
+        [:anthropic, ENV.fetch('ANTHROPIC_API_KEY', nil)]
+      elsif model.start_with?('gpt')
+        [:openai, ENV.fetch('OPENAI_API_KEY', nil)]
+      else
+        # Default to Anthropic
+        [:anthropic, ENV.fetch('ANTHROPIC_API_KEY', nil)]
+      end
+    end
+
+    def detect_default_model
+      # Priority 1: Use SYNTHESIS_MODEL if configured
+      return ENV['SYNTHESIS_MODEL'] if ENV['SYNTHESIS_MODEL']
+
+      # Priority 2: Use cloud providers
+      if ENV['ANTHROPIC_API_KEY']
+        'claude-3-5-sonnet-20241022'
+      elsif ENV['OPENAI_API_KEY']
+        'gpt-4-turbo'
+      else
+        # Default to a reasonable model name for local endpoints
+        'mistralai/magistral-small-2509'
+      end
+    end
+
+    def extract_code_from_markdown(content)
+      content = content.strip
+
+      # Try ```ruby first
+      if (match = content.match(/```ruby\n(.*?)```/m))
+        return match[1].strip
+      end
+
+      # Try generic ``` blocks
+      if (match = content.match(/```\n(.*?)```/m))
+        return match[1].strip
+      end
+
+      # If no code blocks, return as-is and let validation catch it
+      content
+    end
+
+    def validate_code(code)
+      # Basic checks
+      raise 'Empty code generated' if code.strip.empty?
+      raise "Code does not contain 'agent' definition" unless code.include?('agent ')
+      raise "Code does not require 'language_operator'" unless code.match?(/require ['"]language_operator['"]/)
+
+      # AST validation for security
+      validator = LanguageOperator::Agent::Safety::ASTValidator.new
+      violations = validator.validate(code, '(generated)')
+
+      unless violations.empty?
+        error_msgs = violations.map { |v| v[:message] }.join("\n")
+        raise "Security validation failed:\n#{error_msgs}"
+      end
+
+      true
+    end
+  end
+end

data/lib/language_operator/templates/examples/agent_synthesis.tmpl

@@ -75,6 +75,11 @@ This is attempt {{.AttemptNumber}} of {{.MaxAttempts}}. The user is counting on
 
 **Detected Temporal Intent:** {{.TemporalIntent}}
 
+**Runtime Context:**
+- All agent messages and output are automatically logged to stdout
+- Agents have access to a workspace directory for file operations
+- LLM responses are captured and available in agent execution context
+
 Generate Ruby DSL code using this exact format (wrapped in triple-backticks with ruby):
 
 ```ruby
@@ -89,11 +94,22 @@ agent "{{.AgentName}}" do
     "Second objective"
   ]
 
-  # Define workflow if instructions mention specific steps
-  # workflow do
-  #   step :step_name, tool: "tool_name", params: {key: "value"}
-  #   step :another_step, depends_on: :step_name
-  # end
+  # REQUIRED: Define workflow with at least one step
+  workflow do
+    # Use tools when available
+    step :step_name, tool: "tool_name", params: {key: "value"}
+
+    # Or use execute blocks for custom Ruby code (simple logging, calculations, etc.)
+    step :custom_step do
+      execute do
+        puts "Custom output from Ruby code"
+        { result: "done" }
+      end
+    end
+
+    # Chain steps with dependencies if needed
+    step :another_step, depends_on: :step_name
+  end
 
 {{.ConstraintsSection}}
 
@@ -108,8 +124,10 @@ end
 1. Generate ONLY the Ruby code within triple-backticks, no explanations before or after
 {{.ScheduleRules}}
 5. Break down instructions into clear, actionable objectives
-6. Create workflow steps if instructions describe a process
-7. Use available tools in workflow steps
-8. Use the agent name: "{{.AgentName}}"
+6. REQUIRED: Always include a workflow block with at least one step (even for simple single-action agents)
+7. For simple tasks (logging, calculations), use a single step with an execute block containing Ruby code
+8. For complex tasks, use multiple steps with tools or execute blocks
+9. Use available tools in workflow steps when tools are provided
+10. Use the agent name: "{{.AgentName}}"
 
 Generate the code now:

data/lib/language_operator/templates/schema/CHANGELOG.md

@@ -12,6 +12,32 @@ The schema version is tied directly to the gem version and follows [Semantic Ver
 
 ## Version History
 
+### 0.1.34 (2025-11-14)
+
+**DSL v1: Task/Main Primitives Added**
+
+This release adds support for the new DSL v1 pattern with task/main primitives while maintaining backward compatibility with the workflow/step pattern.
+
+**New Features:**
+- Added `task()` DSL method to AgentDefinition for defining organic functions
+- Task definitions support neural (instructions), symbolic (code block), and hybrid implementations
+- Tasks stored in `@tasks` hash on AgentDefinition
+- Full input/output schema validation via TaskDefinition
+
+**Improvements:**
+- Added deprecation warning to `workflow()` method
+- Updated schema to include task definitions
+- Added comprehensive test coverage for task registration
+
+**Deprecated:**
+- `workflow` and `step` pattern (use `task` and `main` instead)
+- Migration guide available in requirements/proposals/dsl-v1.md
+
+**Backward Compatibility:**
+- Existing workflow-based agents continue to work
+- Both task and workflow can coexist in same agent during migration
+- No breaking changes to existing code
+
 ### 0.1.30 (2025-11-12)
 
 **Initial schema artifact generation**

data/lib/language_operator/templates/schema/agent_dsl_openapi.yaml

@@ -2,7 +2,7 @@
 :openapi: 3.0.3
 :info:
   :title: Language Operator Agent API
-  :version: 0.1.31
+  :version: 0.1.35
   :description: HTTP API endpoints exposed by Language Operator reactive agents
   :contact:
     :name: Language Operator

data/lib/language_operator/templates/schema/agent_dsl_schema.json

@@ -3,7 +3,7 @@
   "$id": "https://github.com/language-operator/language-operator-gem/schema/agent-dsl.json",
   "title": "Language Operator Agent DSL",
   "description": "Schema for defining autonomous AI agents using the Language Operator DSL",
-  "version": "0.1.31",
+  "version": "0.1.35",
   "type": "object",
   "properties": {
     "name": {
@@ -43,8 +43,16 @@
       },
       "minItems": 0
     },
-    "workflow": {
-      "$ref": "#/definitions/WorkflowDefinition"
+    "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)"
     },
     "constraints": {
       "$ref": "#/definitions/ConstraintsDefinition"
@@ -70,57 +78,91 @@
     "name"
   ],
   "definitions": {
-    "WorkflowDefinition": {
+    "TaskDefinition": {
       "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": [
+            "neural",
+            "symbolic",
+            "hybrid",
+            "undefined"
+          ]
         }
-      }
+      },
+      "required": [
+        "name",
+        "inputs",
+        "outputs"
+      ]
     },
-    "StepDefinition": {
+    "MainDefinition": {
       "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
+    },
+    "TypeSchema": {
+      "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": [
+            "string",
+            "integer",
+            "number",
+            "boolean",
+            "array",
+            "hash",
+            "any"
+          ]
         }
       },
-      "required": [
-        "name"
+      "additionalProperties": false,
+      "examples": [
+        {
+          "user_id": "integer",
+          "name": "string",
+          "active": "boolean"
+        },
+        {
+          "data": "array",
+          "metadata": "hash"
+        }
       ]
     },
     "ConstraintsDefinition": {