language-operator 0.0.1 → 0.1.31

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

@@ -0,0 +1,452 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$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",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Unique agent identifier (lowercase, alphanumeric, hyphens)",
+      "pattern": "^[a-z0-9-]+$",
+      "minLength": 1,
+      "maxLength": 63
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of agent purpose"
+    },
+    "persona": {
+      "type": "string",
+      "description": "System prompt or persona defining agent behavior and expertise"
+    },
+    "schedule": {
+      "type": "string",
+      "description": "Cron expression for scheduled execution (sets mode to :scheduled)",
+      "pattern": "^\\s*(\\S+\\s+){4}\\S+\\s*$"
+    },
+    "mode": {
+      "type": "string",
+      "description": "Execution mode for the agent",
+      "enum": [
+        "autonomous",
+        "scheduled",
+        "reactive"
+      ]
+    },
+    "objectives": {
+      "type": "array",
+      "description": "List of goals the agent should achieve",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 0
+    },
+    "workflow": {
+      "$ref": "#/definitions/WorkflowDefinition"
+    },
+    "constraints": {
+      "$ref": "#/definitions/ConstraintsDefinition"
+    },
+    "output": {
+      "$ref": "#/definitions/OutputDefinition"
+    },
+    "webhooks": {
+      "type": "array",
+      "description": "Webhook endpoints for reactive agents",
+      "items": {
+        "$ref": "#/definitions/WebhookDefinition"
+      }
+    },
+    "mcp_server": {
+      "$ref": "#/definitions/McpServerDefinition"
+    },
+    "chat_endpoint": {
+      "$ref": "#/definitions/ChatEndpointDefinition"
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "definitions": {
+    "WorkflowDefinition": {
+      "type": "object",
+      "description": "Multi-step workflow with dependencies",
+      "properties": {
+        "steps": {
+          "type": "array",
+          "description": "Ordered list of workflow steps",
+          "items": {
+            "$ref": "#/definitions/StepDefinition"
+          }
+        }
+      }
+    },
+    "StepDefinition": {
+      "type": "object",
+      "description": "Individual workflow step",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Step identifier (symbol or string)"
+        },
+        "tool": {
+          "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": {
+          "type": "string",
+          "description": "LLM prompt template for this step"
+        }
+      },
+      "required": [
+        "name"
+      ]
+    },
+    "ConstraintsDefinition": {
+      "type": "object",
+      "description": "Execution constraints and limits",
+      "properties": {
+        "max_iterations": {
+          "type": "integer",
+          "description": "Maximum number of execution iterations",
+          "minimum": 1
+        },
+        "timeout": {
+          "type": "string",
+          "description": "Execution timeout (e.g., \"30s\", \"5m\", \"1h\")",
+          "pattern": "^\\d+[smh]$"
+        },
+        "memory": {
+          "type": "string",
+          "description": "Memory limit (e.g., \"512Mi\", \"1Gi\")"
+        },
+        "rate_limit": {
+          "type": "integer",
+          "description": "Maximum requests per time period",
+          "minimum": 1
+        },
+        "daily_budget": {
+          "type": "number",
+          "description": "Maximum daily cost in USD",
+          "minimum": 0
+        },
+        "hourly_budget": {
+          "type": "number",
+          "description": "Maximum hourly cost in USD",
+          "minimum": 0
+        },
+        "token_budget": {
+          "type": "integer",
+          "description": "Maximum total tokens allowed",
+          "minimum": 1
+        },
+        "requests_per_minute": {
+          "type": "integer",
+          "description": "Maximum requests per minute",
+          "minimum": 1
+        },
+        "requests_per_hour": {
+          "type": "integer",
+          "description": "Maximum requests per hour",
+          "minimum": 1
+        },
+        "requests_per_day": {
+          "type": "integer",
+          "description": "Maximum requests per day",
+          "minimum": 1
+        },
+        "blocked_patterns": {
+          "type": "array",
+          "description": "Content patterns to block",
+          "items": {
+            "type": "string"
+          }
+        },
+        "blocked_topics": {
+          "type": "array",
+          "description": "Topics to avoid",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "OutputDefinition": {
+      "type": "object",
+      "description": "Output destination configuration",
+      "properties": {
+        "workspace": {
+          "type": "string",
+          "description": "Workspace directory path for file outputs"
+        },
+        "slack": {
+          "type": "object",
+          "description": "Slack integration configuration",
+          "properties": {
+            "channel": {
+              "type": "string",
+              "description": "Slack channel name or ID"
+            }
+          },
+          "required": [
+            "channel"
+          ]
+        },
+        "email": {
+          "type": "object",
+          "description": "Email notification configuration",
+          "properties": {
+            "to": {
+              "type": "string",
+              "description": "Email recipient address",
+              "format": "email"
+            }
+          },
+          "required": [
+            "to"
+          ]
+        }
+      }
+    },
+    "WebhookDefinition": {
+      "type": "object",
+      "description": "Webhook endpoint configuration",
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "URL path for webhook endpoint",
+          "pattern": "^/"
+        },
+        "method": {
+          "type": "string",
+          "description": "HTTP method",
+          "enum": [
+            "get",
+            "post",
+            "put",
+            "delete",
+            "patch"
+          ],
+          "default": "post"
+        },
+        "authentication": {
+          "$ref": "#/definitions/WebhookAuthentication"
+        },
+        "validations": {
+          "type": "array",
+          "description": "Request validation rules",
+          "items": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "headers",
+                  "content_type",
+                  "custom"
+                ]
+              }
+            }
+          }
+        }
+      },
+      "required": [
+        "path"
+      ]
+    },
+    "WebhookAuthentication": {
+      "type": "object",
+      "description": "Webhook authentication configuration",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Authentication type",
+          "enum": [
+            "hmac",
+            "api_key",
+            "bearer",
+            "custom"
+          ]
+        },
+        "secret": {
+          "type": "string",
+          "description": "Secret key for authentication"
+        },
+        "header": {
+          "type": "string",
+          "description": "Header name containing signature/token"
+        },
+        "algorithm": {
+          "type": "string",
+          "description": "HMAC algorithm",
+          "enum": [
+            "sha1",
+            "sha256",
+            "sha512"
+          ]
+        },
+        "prefix": {
+          "type": "string",
+          "description": "Signature prefix (e.g., \"sha256=\")"
+        }
+      }
+    },
+    "McpServerDefinition": {
+      "type": "object",
+      "description": "MCP (Model Context Protocol) server configuration",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "MCP server name"
+        },
+        "tools": {
+          "type": "object",
+          "description": "Tools exposed via MCP",
+          "additionalProperties": {
+            "$ref": "#/definitions/ToolDefinition"
+          }
+        }
+      }
+    },
+    "ChatEndpointDefinition": {
+      "type": "object",
+      "description": "OpenAI-compatible chat endpoint configuration",
+      "properties": {
+        "system_prompt": {
+          "type": "string",
+          "description": "System prompt for chat mode"
+        },
+        "temperature": {
+          "type": "number",
+          "description": "Sampling temperature (0.0-2.0)",
+          "minimum": 0.0,
+          "maximum": 2.0,
+          "default": 0.7
+        },
+        "max_tokens": {
+          "type": "integer",
+          "description": "Maximum tokens in response",
+          "minimum": 1,
+          "default": 2000
+        },
+        "model_name": {
+          "type": "string",
+          "description": "Model name exposed in API"
+        },
+        "top_p": {
+          "type": "number",
+          "description": "Nucleus sampling parameter (0.0-1.0)",
+          "minimum": 0.0,
+          "maximum": 1.0,
+          "default": 1.0
+        },
+        "frequency_penalty": {
+          "type": "number",
+          "description": "Frequency penalty (-2.0 to 2.0)",
+          "minimum": -2.0,
+          "maximum": 2.0,
+          "default": 0.0
+        },
+        "presence_penalty": {
+          "type": "number",
+          "description": "Presence penalty (-2.0 to 2.0)",
+          "minimum": -2.0,
+          "maximum": 2.0,
+          "default": 0.0
+        },
+        "stop_sequences": {
+          "type": "array",
+          "description": "Sequences that stop generation",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "ToolDefinition": {
+      "type": "object",
+      "description": "MCP tool definition",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Tool name (lowercase, alphanumeric, underscores)",
+          "pattern": "^[a-z0-9_]+$"
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable tool description"
+        },
+        "parameters": {
+          "type": "object",
+          "description": "Tool parameters",
+          "additionalProperties": {
+            "$ref": "#/definitions/ParameterDefinition"
+          }
+        }
+      },
+      "required": [
+        "name",
+        "description"
+      ]
+    },
+    "ParameterDefinition": {
+      "type": "object",
+      "description": "Tool parameter definition",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Parameter type",
+          "enum": [
+            "string",
+            "number",
+            "integer",
+            "boolean",
+            "array",
+            "object"
+          ]
+        },
+        "description": {
+          "type": "string",
+          "description": "Parameter description"
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether parameter is required",
+          "default": false
+        },
+        "default": {
+          "description": "Default value if not provided"
+        },
+        "enum": {
+          "type": "array",
+          "description": "Allowed values",
+          "items": {}
+        }
+      },
+      "required": [
+        "type"
+      ]
+    }
+  }
+}

data/lib/language_operator/tool_loader.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require_relative 'dsl'
+require 'mcp'
+require 'opentelemetry/sdk'
+
+module LanguageOperator
+  # Loads tool definitions from Ruby files
+  #
+  # Scans a directory for Ruby files containing tool definitions and loads them
+  # into a registry. Provides hot-reloading capability for development.
+  #
+  # @example Basic usage
+  #   registry = LanguageOperator::Dsl::Registry.new
+  #   loader = LanguageOperator::ToolLoader.new(registry, '/mcp/tools')
+  #   loader.load_tools
+  #   puts "Loaded #{registry.all.length} tools"
+  #
+  # @example With custom context
+  #   loader = LanguageOperator::ToolLoader.new(registry)
+  #   loader.load_tools
+  #   loader.reload  # Hot reload tools
+  #
+  # @example Start MCP server
+  #   LanguageOperator::ToolLoader.start  # Loads tools and starts MCP server
+  class ToolLoader
+    # Initialize tool loader
+    #
+    # @param registry [LanguageOperator::Dsl::Registry] Tool registry
+    # @param tools_dir [String] Directory containing tool definition files
+    def initialize(registry, tools_dir = '/mcp')
+      @registry = registry
+      @tools_dir = tools_dir
+    end
+
+    # Load all tool files from the tools directory
+    #
+    # @return [void]
+    def load_tools
+      @registry.clear
+
+      unless Dir.exist?(@tools_dir)
+        puts "Tools directory #{@tools_dir} does not exist. Skipping tool loading."
+        return
+      end
+
+      tool_files = Dir.glob(File.join(@tools_dir, '**', '*.rb'))
+
+      if tool_files.empty?
+        puts "No tool files found in #{@tools_dir}"
+        return
+      end
+
+      tool_files.each do |file|
+        load_tool_file(file)
+      end
+
+      puts "Loaded #{@registry.all.length} tools from #{tool_files.length} files"
+    end
+
+    # Load a single tool file
+    #
+    # @param file [String] Path to tool definition file
+    # @return [void]
+    def load_tool_file(file)
+      puts "Loading tools from: #{file}"
+
+      begin
+        context = LanguageOperator::Dsl::Context.new(@registry)
+        code = File.read(file)
+
+        # Execute in sandbox with validation
+        executor = LanguageOperator::Agent::Safety::SafeExecutor.new(context)
+        executor.eval(code, file)
+      rescue Agent::Safety::SafeExecutor::SecurityError, Agent::Safety::ASTValidator::SecurityError => e
+        # Re-raise security errors so they're not silently ignored
+        warn "Error loading tool file #{file}: #{e.message}"
+        warn e.backtrace.join("\n")
+        raise e
+      rescue StandardError => e
+        warn "Error loading tool file #{file}: #{e.message}"
+        warn e.backtrace.join("\n")
+      end
+    end
+
+    # Reload all tools (hot reload)
+    #
+    # @return [void]
+    def reload
+      puts 'Reloading tools...'
+      load_tools
+    end
+
+    # Start an MCP server with loaded tools
+    #
+    # This class method creates a registry, loads tools from /mcp directory,
+    # wraps them as MCP::Tool classes, and starts an MCP server.
+    #
+    # Transport mode is automatically detected:
+    # - If PORT environment variable is set: HTTP server mode (for Kubernetes)
+    # - Otherwise: stdio transport mode (for local development)
+    #
+    # @param tools_dir [String] Directory containing tool definition files (default: '/mcp')
+    # @param server_name [String] Name of the MCP server (default: 'language-operator-tool')
+    # @return [void]
+    def self.start(tools_dir: '/mcp', server_name: 'language-operator-tool')
+      # Create registry and load tools
+      registry = LanguageOperator::Dsl::Registry.new
+      loader = new(registry, tools_dir)
+      loader.load_tools
+
+      # Convert DSL tools to MCP::Tool classes
+      mcp_tools = registry.all.map do |tool_def|
+        create_mcp_tool(tool_def)
+      end
+
+      # Create MCP server
+      server = MCP::Server.new(
+        name: server_name,
+        tools: mcp_tools
+      )
+
+      # Auto-detect transport mode based on PORT environment variable
+      if ENV['PORT']
+        start_http_server(server, mcp_tools.length, ENV['PORT'].to_i)
+      else
+        start_stdio_server(server, mcp_tools.length)
+      end
+    end
+
+    # Start MCP server in HTTP mode
+    #
+    # @param server [MCP::Server] The MCP server instance
+    # @param tool_count [Integer] Number of tools loaded
+    # @param port [Integer] Port to bind to
+    # @return [void]
+    def self.start_http_server(server, tool_count, port)
+      require 'rack'
+      require 'rackup'
+
+      # Create the Streamable HTTP transport
+      transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+      server.transport = transport
+
+      # Create the Rack application
+      app = proc do |env|
+        request = Rack::Request.new(env)
+        transport.handle_request(request)
+      end
+
+      # Build the Rack application with middleware
+      rack_app = Rack::Builder.new do
+        use Rack::CommonLogger
+        use Rack::ShowExceptions
+        run app
+      end
+
+      puts "Starting MCP HTTP server on http://0.0.0.0:#{port}"
+      puts "Loaded #{tool_count} tools"
+
+      # Start the server with Puma
+      Rackup::Handler.get('puma').run(rack_app, Port: port, Host: '0.0.0.0')
+    end
+
+    # Start MCP server in stdio mode
+    #
+    # @param server [MCP::Server] The MCP server instance
+    # @param tool_count [Integer] Number of tools loaded
+    # @return [void]
+    def self.start_stdio_server(server, tool_count)
+      # Use stdio transport
+      transport = MCP::Server::Transports::StdioTransport.new(server)
+      puts "Starting MCP server with #{tool_count} tools (stdio mode)"
+      transport.open
+    end
+
+    # Convert a DSL tool definition to an MCP::Tool class
+    #
+    # @param tool_def [LanguageOperator::Dsl::ToolDefinition] Tool definition from DSL
+    # @return [Class] MCP::Tool subclass
+    # rubocop:disable Metrics/MethodLength
+    def self.create_mcp_tool(tool_def)
+      # Capture tool name and tracer for use in the dynamic class
+      tool_name = tool_def.name
+      tracer = OpenTelemetry.tracer_provider.tracer('language-operator-agent', LanguageOperator::VERSION)
+
+      # Create a dynamic MCP::Tool class
+      Class.new(MCP::Tool) do
+        description tool_def.description || "Tool: #{tool_def.name}"
+
+        # Build input schema from parameters
+        properties = {}
+        required_params = []
+
+        tool_def.parameters.each do |param_name, param_def|
+          properties[param_name] = {
+            type: param_def.type&.to_s || 'string',
+            description: param_def.description
+          }
+          required_params << param_name if param_def.required?
+        end
+
+        input_schema(
+          properties: properties,
+          required: required_params
+        )
+
+        # Store the execute block
+        @execute_block = tool_def.execute_block
+
+        # Define the call method with OpenTelemetry instrumentation
+        define_singleton_method(:call) do |**params|
+          tracer.in_span('agent.tool.execute', attributes: {
+                           'tool.name' => tool_name,
+                           'tool.type' => 'custom'
+                         }) do |span|
+            # Execute the tool's block
+            result = @execute_block.call(params)
+
+            # Set success attribute
+            span.set_attribute('tool.result', 'success')
+
+            # Return MCP response
+            MCP::Tool::Response.new([
+                                      {
+                                        type: 'text',
+                                        text: result.to_s
+                                      }
+                                    ])
+          rescue StandardError => e
+            # Record exception and set failure status
+            span.record_exception(e)
+            span.set_attribute('tool.result', 'failure')
+            span.status = OpenTelemetry::Trace::Status.error(e.message)
+            raise
+          end
+        end
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+  end
+end