language-operator 0.0.1 → 0.1.31

data/lib/language_operator/retry.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  # Retry utilities with exponential backoff for handling transient failures
+  module Retry
+    # Default retry configuration
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_BASE_DELAY = 1.0
+    DEFAULT_MAX_DELAY = 10.0
+    DEFAULT_JITTER_FACTOR = 0.1
+
+    # Common retryable HTTP status codes (transient errors)
+    RETRYABLE_HTTP_CODES = [429, 500, 502, 503, 504].freeze
+
+    # Execute a block with exponential backoff retry logic
+    # @param max_retries [Integer] Maximum number of retry attempts (default: 3)
+    # @param base_delay [Float] Initial delay in seconds (default: 1.0)
+    # @param max_delay [Float] Maximum delay cap in seconds (default: 10.0)
+    # @param jitter_factor [Float] Jitter randomization factor (default: 0.1)
+    # @param on_retry [Proc] Optional callback called before each retry (receives attempt number and exception)
+    # @yield Block to execute with retry logic
+    # @return [Object] Return value of the block
+    # @raise [StandardError] Re-raises the exception if all retries are exhausted
+    #
+    # @example Basic usage
+    #   LanguageOperator::Retry.with_backoff(max_retries: 5) do
+    #     client.get_resource(name)
+    #   end
+    #
+    # @example With callback
+    #   LanguageOperator::Retry.with_backoff(on_retry: ->(attempt, e) {
+    #     puts "Retry attempt #{attempt} after error: #{e.message}"
+    #   }) do
+    #     api_call
+    #   end
+    def self.with_backoff(max_retries: DEFAULT_MAX_RETRIES,
+                          base_delay: DEFAULT_BASE_DELAY,
+                          max_delay: DEFAULT_MAX_DELAY,
+                          jitter_factor: DEFAULT_JITTER_FACTOR,
+                          on_retry: nil)
+      attempt = 0
+      begin
+        yield
+      rescue StandardError => e
+        if attempt < max_retries
+          attempt += 1
+          delay = calculate_backoff(attempt, base_delay, max_delay, jitter_factor)
+          on_retry&.call(attempt, e)
+          sleep delay
+          retry
+        end
+        raise e
+      end
+    end
+
+    # Execute a block with retry for specific exception types
+    # @param exception_types [Array<Class>] Exception types to retry on
+    # @param max_retries [Integer] Maximum number of retry attempts
+    # @param base_delay [Float] Initial delay in seconds
+    # @param max_delay [Float] Maximum delay cap in seconds
+    # @param jitter_factor [Float] Jitter randomization factor
+    # @yield Block to execute
+    # @return [Object] Return value of the block
+    # @raise [StandardError] Re-raises the exception if all retries are exhausted
+    #
+    # @example
+    #   LanguageOperator::Retry.on_exceptions([Net::OpenTimeout, Errno::ECONNREFUSED]) do
+    #     smtp.connect
+    #   end
+    def self.on_exceptions(exception_types, max_retries: DEFAULT_MAX_RETRIES,
+                           base_delay: DEFAULT_BASE_DELAY,
+                           max_delay: DEFAULT_MAX_DELAY,
+                           jitter_factor: DEFAULT_JITTER_FACTOR)
+      attempt = 0
+      begin
+        yield
+      rescue *exception_types => e
+        if attempt < max_retries
+          attempt += 1
+          delay = calculate_backoff(attempt, base_delay, max_delay, jitter_factor)
+          sleep delay
+          retry
+        end
+        raise e
+      end
+    end
+
+    # Check if an HTTP status code is retryable (transient error)
+    # @param status [Integer] HTTP status code
+    # @return [Boolean] True if status code indicates a transient error
+    #
+    # @example
+    #   LanguageOperator::Retry.retryable_http_code?(503) # => true
+    #   LanguageOperator::Retry.retryable_http_code?(404) # => false
+    def self.retryable_http_code?(status)
+      RETRYABLE_HTTP_CODES.include?(status)
+    end
+
+    # Calculate exponential backoff delay with jitter
+    # @param attempt [Integer] Retry attempt number (1-based)
+    # @param base_delay [Float] Initial delay in seconds
+    # @param max_delay [Float] Maximum delay cap in seconds
+    # @param jitter_factor [Float] Jitter randomization factor (0.0 to 1.0)
+    # @return [Float] Delay in seconds
+    #
+    # @example
+    #   LanguageOperator::Retry.calculate_backoff(1) # => ~1.0 seconds
+    #   LanguageOperator::Retry.calculate_backoff(2) # => ~2.0 seconds
+    #   LanguageOperator::Retry.calculate_backoff(3) # => ~4.0 seconds
+    def self.calculate_backoff(attempt,
+                               base_delay = DEFAULT_BASE_DELAY,
+                               max_delay = DEFAULT_MAX_DELAY,
+                               jitter_factor = DEFAULT_JITTER_FACTOR)
+      # Exponential: base * 2^(attempt-1)
+      exponential = base_delay * (2**(attempt - 1))
+      # Cap at max
+      capped = [exponential, max_delay].min
+      # Add jitter: ±(delay * jitter_factor * random)
+      jitter = capped * jitter_factor * (rand - 0.5) * 2
+      capped + jitter
+    end
+  end
+end

data/lib/language_operator/retryable.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  # Mixin module to provide retry logic with exponential backoff for operations
+  # that may fail transiently.
+  #
+  # @example Basic usage
+  #   class MyService
+  #     include LanguageOperator::Retryable
+  #
+  #     def connect
+  #       with_retry do
+  #         # Connection logic that might fail
+  #         make_connection
+  #       end
+  #     end
+  #   end
+  #
+  # @example Custom retry configuration
+  #   with_retry(max_attempts: 5, base_delay: 2.0) do
+  #     risky_operation
+  #   end
+  #
+  # @example With custom error handling
+  #   with_retry(on_retry: ->(error, attempt) { log_error(error, attempt) }) do
+  #     api_call
+  #   end
+  module Retryable
+    # Default retry configuration
+    DEFAULT_MAX_ATTEMPTS = 3
+    DEFAULT_BASE_DELAY = 1.0
+    DEFAULT_MAX_DELAY = 30.0
+
+    # Execute a block with retry logic and exponential backoff.
+    #
+    # @param max_attempts [Integer] Maximum number of attempts (default: 3)
+    # @param base_delay [Float] Base delay in seconds for exponential backoff (default: 1.0)
+    # @param max_delay [Float] Maximum delay between retries in seconds (default: 30.0)
+    # @param rescue_errors [Array<Class>] Array of error classes to rescue (default: StandardError)
+    # @param on_retry [Proc] Optional callback called on each retry attempt with (error, attempt, delay)
+    # @yield Block to execute with retry logic
+    # @return Result of the block if successful
+    # @raise Last error encountered if all retries are exhausted
+    #
+    # @example
+    #   result = with_retry(max_attempts: 5) do
+    #     fetch_from_api
+    #   end
+    def with_retry(
+      max_attempts: DEFAULT_MAX_ATTEMPTS,
+      base_delay: DEFAULT_BASE_DELAY,
+      max_delay: DEFAULT_MAX_DELAY,
+      rescue_errors: [StandardError],
+      on_retry: nil
+    )
+      attempt = 0
+      last_error = nil
+
+      loop do
+        attempt += 1
+
+        begin
+          return yield
+        rescue *rescue_errors => e
+          last_error = e
+
+          raise e if attempt >= max_attempts
+
+          # Calculate delay with exponential backoff: base_delay * 2^(attempt-1)
+          delay = [base_delay * (2**(attempt - 1)), max_delay].min
+
+          # Call the retry callback if provided
+          on_retry&.call(e, attempt, delay)
+
+          sleep(delay)
+        end
+      end
+    end
+
+    # Execute a block with retry logic and return nil on failure instead of raising.
+    #
+    # @param max_attempts [Integer] Maximum number of attempts (default: 3)
+    # @param base_delay [Float] Base delay in seconds for exponential backoff (default: 1.0)
+    # @param max_delay [Float] Maximum delay between retries in seconds (default: 30.0)
+    # @param rescue_errors [Array<Class>] Array of error classes to rescue (default: StandardError)
+    # @param on_retry [Proc] Optional callback called on each retry attempt with (error, attempt, delay)
+    # @param on_failure [Proc] Optional callback called when all retries are exhausted with (error, attempts)
+    # @yield Block to execute with retry logic
+    # @return Result of the block if successful, nil if all retries failed
+    #
+    # @example
+    #   result = with_retry_or_nil(on_failure: ->(err, tries) { log_failure(err) }) do
+    #     optional_operation
+    #   end
+    #
+    #   return unless result
+    def with_retry_or_nil(
+      max_attempts: DEFAULT_MAX_ATTEMPTS,
+      base_delay: DEFAULT_BASE_DELAY,
+      max_delay: DEFAULT_MAX_DELAY,
+      rescue_errors: [StandardError],
+      on_retry: nil,
+      on_failure: nil
+    )
+      attempt = 0
+      last_error = nil
+
+      loop do
+        attempt += 1
+
+        begin
+          return yield
+        rescue *rescue_errors => e
+          last_error = e
+
+          if attempt >= max_attempts
+            on_failure&.call(e, attempt)
+            return nil
+          end
+
+          # Calculate delay with exponential backoff
+          delay = [base_delay * (2**(attempt - 1)), max_delay].min
+
+          # Call the retry callback if provided
+          on_retry&.call(e, attempt, delay)
+
+          sleep(delay)
+        end
+      end
+    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,115 @@
+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}}
+
+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"
+  ]
+
+  # 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
+
+{{.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. Create workflow steps if instructions describe a process
+7. Use available tools in workflow steps
+8. 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,93 @@
+# 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.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
+```