language-operator 0.1.30 → 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/README.md

@@ -0,0 +1,23 @@
+# Templates Directory
+
+This directory contains templates used by the Language Operator gem for various code generation and synthesis tasks.
+
+## Directory Structure
+
+- **`examples/`** - Example synthesis templates for agent and persona generation
+  - `agent_synthesis.tmpl` - Template for synthesizing agent definitions
+  - `persona_distillation.tmpl` - Template for distilling persona configurations
+
+- **`schema/`** - JSON Schema definitions and validation templates
+  - Reserved for future schema artifacts and validation templates
+
+## Usage
+
+Templates in this directory are used by:
+- The `aictl system synthesis-template` command for managing synthesis templates
+- Agent synthesis and persona distillation features
+- Schema validation and code generation tools
+
+## Template Format
+
+Templates use a simple variable substitution format compatible with the synthesis engine. Variables are typically specified in the template header and replaced during synthesis.

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

@@ -0,0 +1,133 @@
+You are generating Ruby DSL code for an autonomous agent in a Kubernetes operator.
+
+{{if .ErrorContext}}
+## IMPORTANT: Self-Healing Synthesis - Attempt {{.AttemptNumber}}
+
+The previous code synthesis encountered errors. Please analyze the errors below and generate CORRECTED code.
+
+### Previous Synthesis Failures
+
+{{if .ErrorContext.ValidationErrors}}
+**Validation Errors** (detected during code generation):
+{{range .ErrorContext.ValidationErrors}}
+- {{.}}
+{{end}}
+{{end}}
+
+{{if .ErrorContext.RuntimeErrors}}
+**Runtime Errors** (detected during execution):
+{{range .ErrorContext.RuntimeErrors}}
+- Time: {{.Timestamp}}
+- Type: {{.ErrorType}}
+- Message: {{.ErrorMessage}}
+{{if .StackTrace}}
+- Stack Trace:
+{{range .StackTrace}}
+  {{.}}
+{{end}}
+{{end}}
+- Exit Code: {{.ContainerExitCode}}
+{{end}}
+{{end}}
+
+{{if .ErrorContext.LastCrashLog}}
+**Last Container Logs** (before crash):
+```
+{{.ErrorContext.LastCrashLog}}
+```
+{{end}}
+
+### Your Task
+
+1. Carefully analyze each error above
+2. Identify the root cause of the failure
+3. Generate CORRECTED Ruby DSL code that addresses ALL errors
+4. Ensure the code:
+   - Fixes the specific errors mentioned
+   - Uses only available tools: {{.ToolsList}}
+   - Uses only available models: {{.ModelsList}}
+   - Follows the Language Operator DSL syntax exactly
+   - Does NOT use any dangerous Ruby methods (system, eval, etc.)
+
+This is attempt {{.AttemptNumber}} of {{.MaxAttempts}}. The user is counting on you to get it right!
+
+{{if .LastKnownGoodCode}}
+### Last Known Working Code (for reference)
+```ruby
+{{.LastKnownGoodCode}}
+```
+{{end}}
+
+{{else}}
+## Agent Synthesis Request
+{{end}}
+
+**User Instructions:**
+{{.Instructions}}
+
+**Available Tools:**
+{{.ToolsList}}
+
+**Available Models:**
+{{.ModelsList}}
+
+**Agent Name:** {{.AgentName}}
+
+**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
+require 'language_operator'
+
+agent "{{.AgentName}}" do
+  description "Brief description extracted from instructions"
+{{.PersonaSection}}{{.ScheduleSection}}
+  # Extract objectives from instructions
+  objectives [
+    "First objective",
+    "Second objective"
+  ]
+
+  # 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}}
+
+  # Output configuration (if workspace enabled)
+  output do
+    workspace "results/output.txt"
+  end
+end
+```
+
+**Rules:**
+1. Generate ONLY the Ruby code within triple-backticks, no explanations before or after
+{{.ScheduleRules}}
+5. Break down instructions into clear, actionable objectives
+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/examples/persona_distillation.tmpl

@@ -0,0 +1,19 @@
+Distill this persona into a single concise paragraph for an AI agent.
+
+**Persona Details:**
+Name: {{.PersonaName}}
+Description: {{.PersonaDescription}}
+System Prompt: {{.PersonaSystemPrompt}}
+Tone: {{.PersonaTone}}
+Language: {{.PersonaLanguage}}
+
+**Agent Context:**
+Goal: {{.AgentInstructions}}
+Available Tools: {{.AgentTools}}
+
+Generate a single paragraph (2-4 sentences) that captures the essence of this persona
+in the context of the agent's goal. Focus on tone, expertise, and key behaviors.
+
+Output ONLY the distilled persona paragraph, nothing else.
+
+Distilled persona:

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

@@ -0,0 +1,119 @@
+# Schema Changelog
+
+This file tracks changes to the Language Operator Agent DSL schema.
+
+## Schema Versioning
+
+The schema version is tied directly to the gem version and follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** version: Breaking changes to DSL structure or behavior
+- **MINOR** version: New features, backward-compatible additions
+- **PATCH** version: Bug fixes, documentation improvements
+
+## 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**
+
+This is the first release with auto-generated schema artifacts included in the gem package.
+
+**Schema Features:**
+- Complete JSON Schema v7 for Agent DSL
+- OpenAPI 3.0.3 specification for agent HTTP endpoints
+- Agent configuration properties (name, description, persona, mode, schedule, objectives)
+- Workflow definitions with step dependencies
+- Constraint definitions (budgets, rate limits, timeouts)
+- Output destinations (workspace, Slack, email)
+- Webhook definitions with authentication
+- MCP server configuration
+- Chat endpoint configuration (OpenAI-compatible)
+- Tool and parameter definitions
+
+**API Endpoints Documented:**
+- `GET /health` - Health check
+- `GET /ready` - Readiness check
+- `POST /v1/chat/completions` - OpenAI-compatible chat endpoint
+- `GET /v1/models` - List available models
+
+**Safe Methods:**
+- Agent DSL methods validated via `Agent::Safety::ASTValidator`
+- Tool DSL methods for parameter definitions
+- Helper methods for HTTP, Shell, validation, and utilities
+
+---
+
+## Future Versions
+
+### Template for New Entries
+
+```markdown
+### X.Y.Z (YYYY-MM-DD)
+
+**Summary of changes**
+
+**Breaking Changes:**
+- Description of any breaking changes
+
+**New Features:**
+- New DSL methods or capabilities added
+- New endpoint specifications
+
+**Improvements:**
+- Schema validation enhancements
+- Documentation updates
+
+**Bug Fixes:**
+- Schema corrections
+- Type definition fixes
+
+**Deprecated:**
+- Features marked for removal in future versions
+```
+
+---
+
+## Schema Validation
+
+The schema can be used for:
+- **Template Validation** - Ensuring synthesized agent code is valid
+- **Documentation Generation** - Auto-generating reference docs
+- **IDE Support** - Providing autocomplete and IntelliSense
+- **CLI Introspection** - Runtime validation of agent definitions
+
+## Schema Artifacts
+
+Generated artifacts are stored in this directory:
+- `agent_dsl_schema.json` - JSON Schema v7 specification
+- `agent_dsl_openapi.yaml` - OpenAPI 3.0.3 specification
+
+These are regenerated automatically during the build process via:
+```bash
+rake schema:generate
+```