language-operator 0.1.46 → 0.1.47

data/components/tool/Makefile

@@ -0,0 +1,77 @@
+# Image configuration
+IMAGE_NAME := ghcr.io/language-operator/tool
+IMAGE_TAG := latest
+IMAGE_FULL := $(IMAGE_NAME):$(IMAGE_TAG)
+
+# Include shared targets
+include ../../Makefile.common
+
+# Default target
+.PHONY: help
+help:
+	@echo "Available targets:"
+	@echo "  build      - Build the Docker image"
+	@echo "  build-dev  - Build the Docker image with local gem"
+	@echo "  push-dev   - Build and push dev image to all k8s nodes"
+	@echo "  scan       - Scan the Docker image with Trivy"
+	@echo "  shell      - Run the image and exec into it with an interactive shell"
+	@echo "  env        - Display sorted list of environment variables in the image"
+	@echo "  run        - Run the MCP server on port 8080"
+	@echo "  run-dev    - Run with custom tools directory"
+	@echo "  test       - Run the server and test the endpoints"
+	@echo "  lint       - Run RuboCop linter"
+	@echo "  lint-fix   - Run RuboCop with auto-fix"
+	@echo "  doc        - Generate API documentation with YARD"
+	@echo "  doc-serve  - Serve documentation on http://localhost:8808"
+	@echo "  doc-clean  - Remove generated documentation"
+
+# Build development image with local gem
+.PHONY: build-dev
+build-dev:
+	@echo "Building local gem..."
+	cd ../../../language-operator-gem && gem build language-operator.gemspec
+	@echo "Copying gem to build context..."
+	cp ../../../language-operator-gem/*.gem .
+	@echo "Building Docker image..."
+	docker build -f Dockerfile.dev -t $(IMAGE_NAME):dev -t $(IMAGE_NAME):$(IMAGE_TAG)-dev .
+	@echo "Cleaning up gem file..."
+	rm language-operator-*.gem
+
+# Push development image to all k8s cluster nodes (containerd/k3s)
+.PHONY: push-dev
+push-dev: build-dev
+	@echo "Pushing development image to all k8s nodes..."
+	@for node in $$(kubectl get nodes -o jsonpath='{.items[*].metadata.name}'); do \
+		echo "==> Pushing to node: $$node"; \
+		docker save $(IMAGE_NAME):dev | ssh $$node 'sudo k3s ctr images import -' || echo "Failed to push to $$node"; \
+	done
+	@echo "✓ Development image pushed to all nodes!"
+
+# Display sorted list of environment variables in the image
+.PHONY: env
+env:
+	docker run --rm $(IMAGE_FULL) /bin/sh -c 'env | sort'
+
+# Run the MCP server
+.PHONY: run
+run:
+	docker run --rm -p 8080:80 --name mcp-server $(IMAGE_FULL)
+
+# Run with custom tools directory
+.PHONY: run-dev
+run-dev:
+	docker run --rm -p 8080:80 -v $(PWD)/examples:/mcp --name mcp-server $(IMAGE_FULL)
+
+# Override test to test server endpoints
+.PHONY: test
+test:
+	@echo "Testing health endpoint..."
+	@curl -s http://localhost:8080/health | jq .
+	@echo ""
+	@echo "Listing tools..."
+	@curl -s http://localhost:8080/tools | jq .
+	@echo ""
+	@echo "Calling calculator tool..."
+	@curl -s -X POST http://localhost:8080/tools/call \
+		-H "Content-Type: application/json" \
+		-d '{"name":"calculator","arguments":{"operation":"add","a":5,"b":3}}' | jq .

data/components/tool/README.md

@@ -0,0 +1,145 @@
+# based/server
+
+An extendable tool server based on [the official MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk).
+
+## Quick Start
+
+Run the server with example tools:
+
+```bash
+docker run -p 8080:80 based/server:latest
+```
+
+Test the server:
+
+```bash
+curl http://localhost:8080/health
+curl http://localhost:8080/tools
+```
+
+## Creating Your Own MCP Server
+
+### 1. Create Tool Definitions
+
+Create Ruby files using the MCP DSL to define your tools:
+
+```ruby
+# tools/hello.rb
+tool "greet" do
+  description "Greets a person by name"
+
+  parameter "name" do
+    type :string
+    required true
+    description "The name of the person to greet"
+  end
+
+  parameter "greeting" do
+    type :string
+    required false
+    description "Custom greeting (default: Hello)"
+    default "Hello"
+  end
+
+  execute do |params|
+    greeting = params["greeting"] || "Hello"
+    "#{greeting}, #{params['name']}!"
+  end
+end
+```
+
+### 2. Mount Your Tools Directory
+
+Run the container with your tools directory mounted at `/mcp/tools`:
+
+```bash
+docker run -p 8080:80 -v $(pwd)/tools:/mcp/tools based/server:latest
+```
+
+### 3. Use Your Tools
+
+Call your tools via the MCP protocol:
+
+```bash
+# List available tools
+curl -X POST http://localhost:8080/tools/list
+
+# Call a tool
+curl -X POST http://localhost:8080/tools/call \
+  -H "Content-Type: application/json" \
+  -d '{"name":"greet","arguments":{"name":"World"}}'
+```
+
+## DSL Reference
+
+### Defining a Tool
+
+```ruby
+tool "tool_name" do
+  description "What this tool does"
+
+  parameter "param_name" do
+    type :string              # :string, :number, :boolean, :array, :object
+    required true             # or false
+    description "Parameter description"
+    enum ["option1", "option2"]  # optional: restrict to specific values
+    default "default_value"   # optional: default value
+  end
+
+  execute do |params|
+    # Your tool logic here
+    # Access parameters via params["param_name"]
+    # Return a string result
+    "Result: #{params['param_name']}"
+  end
+end
+```
+
+### Parameter Types
+
+- `:string` - Text values
+- `:number` - Numeric values (integers or floats)
+- `:boolean` - true/false
+- `:array` - Lists of values
+- `:object` - Complex objects
+
+### Multiple Tools Per File
+
+You can define multiple tools in a single file:
+
+```ruby
+tool "add" do
+  # ... tool definition
+end
+
+tool "subtract" do
+  # ... tool definition
+end
+```
+
+## Example Tools
+
+See [examples/calculator.rb](examples/calculator.rb) for complete examples including:
+- Calculator with arithmetic operations
+- Echo tool for simple string operations
+
+## Configuration
+
+| Environment Variable | Default | Description |
+| -- | -- | -- |
+| PORT | 80 | Port to run HTTP server on |
+| RACK_ENV | production | Rack environment |
+
+## API Endpoints
+
+### MCP Protocol Endpoints
+
+- `POST /initialize` - Initialize MCP session
+- `POST /tools/list` - List available tools
+- `POST /tools/call` - Execute a tool
+
+### Debug Endpoints
+
+- `GET /health` - Health check
+- `GET /tools` - List loaded tools (simple format)
+- `POST /reload` - Reload tools from `/mcp` directory

data/components/tool/config.ru

@@ -0,0 +1,4 @@
+require_relative 'server'
+
+# Completely bypass Rack::Protection by not using Sinatra's run! method
+run Langop::Server

data/components/tool/examples/calculator.rb

@@ -0,0 +1,63 @@
+# Example tool: Calculator
+# This file demonstrates the MCP DSL for defining tools
+
+tool 'calculator' do
+  description 'Performs basic arithmetic operations on two numbers'
+
+  parameter 'operation' do
+    type :string
+    required true
+    description 'The arithmetic operation to perform'
+    enum %w[add subtract multiply divide]
+  end
+
+  parameter 'a' do
+    type :number
+    required true
+    description 'The first number'
+  end
+
+  parameter 'b' do
+    type :number
+    required true
+    description 'The second number'
+  end
+
+  execute do |params|
+    a = params['a']
+    b = params['b']
+
+    result = case params['operation']
+             when 'add'
+               a + b
+             when 'subtract'
+               a - b
+             when 'multiply'
+               a * b
+             when 'divide'
+               if b.zero?
+                 'Error: Division by zero'
+               else
+                 a / b.to_f
+               end
+             else
+               'Unknown operation'
+             end
+
+    "Result: #{result}"
+  end
+end
+
+tool 'echo' do
+  description 'Returns the input message'
+
+  parameter 'message' do
+    type :string
+    required true
+    description 'The message to echo back'
+  end
+
+  execute do |params|
+    params['message']
+  end
+end

data/components/tool/examples/example_tool.rb

@@ -0,0 +1,190 @@
+# Example tool demonstrating all the new helper features
+
+# Example 1: Using built-in parameter validators
+tool 'send_message' do
+  description 'Send a message to an email or phone number'
+
+  parameter 'recipient' do
+    type :string
+    required true
+    description 'Email address or phone number'
+    # You can use built-in validators
+    # email_format or phone_format
+  end
+
+  parameter 'message' do
+    type :string
+    required true
+    description 'The message to send'
+  end
+
+  execute do |params|
+    recipient = params['recipient']
+    message = params['message']
+
+    # Use validation helpers
+    if recipient.include?('@')
+      error = validate_email(recipient)
+      return error if error
+
+      "Email sent to #{recipient}: #{message}"
+    else
+      error = validate_phone(recipient)
+      return error if error
+
+      "SMS sent to #{recipient}: #{message}"
+    end
+  end
+end
+
+# Example 2: Using Config helper for environment variables
+tool 'check_smtp_config' do
+  description 'Check SMTP configuration with fallback keys'
+
+  execute do |_params|
+    # Get config with multiple fallback keys
+    host = Config.get('SMTP_HOST', 'MAIL_HOST', default: 'localhost')
+    port = Config.get_int('SMTP_PORT', 'MAIL_PORT', default: 587)
+    use_tls = Config.get_bool('SMTP_TLS', 'MAIL_TLS', default: true)
+
+    # Check required configs
+    missing = Config.check_required('SMTP_USER', 'SMTP_PASSWORD')
+    return error("Missing configuration: #{missing.join(', ')}") unless missing.empty?
+
+    success <<~CONFIG
+      SMTP Configuration:
+      Host: #{host}
+      Port: #{port}
+      TLS: #{use_tls}
+      User: #{Config.get('SMTP_USER')}
+    CONFIG
+  end
+end
+
+# Example 3: Using HTTP helper
+tool 'fetch_json' do
+  description 'Fetch JSON data from a URL'
+
+  parameter 'url' do
+    type :string
+    required true
+    description 'URL to fetch'
+    url_format # Built-in validator
+  end
+
+  execute do |params|
+    url = params['url']
+
+    # Use HTTP helper instead of curl
+    response = HTTP.get(url, headers: { 'Accept' => 'application/json' })
+
+    if response[:success]
+      if response[:json]
+        "Fetched JSON with #{response[:json].keys.length} keys"
+      else
+        "Response received but not JSON: #{truncate(response[:body])}"
+      end
+    else
+      error("Failed to fetch URL: #{response[:error]}")
+    end
+  end
+end
+
+# Example 4: Using Shell helper for safe command execution
+tool 'safe_grep' do
+  description 'Safely search for a pattern in a file'
+
+  parameter 'pattern' do
+    type :string
+    required true
+    description 'Search pattern'
+  end
+
+  parameter 'file' do
+    type :string
+    required true
+    description 'File to search in'
+  end
+
+  execute do |params|
+    # This is safe from injection attacks!
+    result = Shell.run('grep', params['pattern'], params['file'])
+
+    if result[:success]
+      "Found matches:\n#{result[:output]}"
+    else
+      'No matches found'
+    end
+  end
+end
+
+# Example 5: Using custom validation
+tool 'restricted_command' do
+  description 'Run a command from an allowed list'
+
+  parameter 'command' do
+    type :string
+    required true
+    description 'Command to run (must be in allowed list)'
+    validate lambda { |cmd|
+      allowed = %w[ls pwd whoami date]
+      allowed.include?(cmd) || "Command '#{cmd}' not allowed. Allowed: #{allowed.join(', ')}"
+    }
+  end
+
+  execute do |params|
+    result = Shell.run(params['command'])
+    result[:output]
+  end
+end
+
+# Example 6: Using multiple helpers together
+tool 'web_health_check' do
+  description 'Check if a web service is healthy'
+
+  parameter 'url' do
+    type :string
+    required true
+    description 'Service URL to check'
+    url_format
+  end
+
+  parameter 'expected_status' do
+    type :number
+    required false
+    description 'Expected HTTP status code'
+    default 200
+  end
+
+  execute do |params|
+    url = params['url']
+    expected = params['expected_status'] || 200
+
+    # Use HTTP helper
+    response = HTTP.head(url)
+
+    if response[:error]
+      error("Health check failed: #{response[:error]}")
+    elsif response[:status] == expected
+      success("✓ Service healthy (HTTP #{response[:status]})")
+    else
+      error("Service returned HTTP #{response[:status]}, expected #{expected}")
+    end
+  end
+end
+
+# Example 7: Using env_required helper
+tool 'database_info' do
+  description 'Show database connection info'
+
+  execute do |_params|
+    # Check required env vars
+    error = env_required('DATABASE_URL', 'DB_HOST')
+    return error if error
+
+    # Safe to use now
+    db_url = env_get('DATABASE_URL', 'DB_URL')
+
+    success("Database configured: #{db_url}")
+  end
+end

data/components/tool/lib/langop/dsl.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'language_operator'
+
+# Convenience - export LanguageOperator classes at top level for tool definitions
+#
+# This allows tool files to use simplified syntax:
+#   tool "example" do
+#     ...
+#   end
+#
+# Instead of:
+#   LanguageOperator::Dsl.define do
+#     tool "example" do
+#       ...
+#     end
+#   end
+
+# Alias ToolLoader at top level for convenience
+ToolLoader = LanguageOperator::ToolLoader

data/components/tool/server.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'language_operator/tool_loader'
+
+# Start the MCP server using LanguageOperator SDK
+# This will load all tools from /mcp and start the server on PORT (default 80)
+LanguageOperator::ToolLoader.start

data/lib/language_operator/agent/task_executor.rb

@@ -76,7 +76,9 @@ module LanguageOperator
         @config = default_config.merge(config)
         logger.debug('TaskExecutor initialized',
                      task_count: @tasks.size,
-                     timeout: @config[:timeout],
+                     timeout_symbolic: @config[:timeout_symbolic],
+                     timeout_neural: @config[:timeout_neural],
+                     timeout_hybrid: @config[:timeout_hybrid],
                      max_retries: @config[:max_retries])
       end
 
@@ -95,13 +97,11 @@ module LanguageOperator
       # @raise [TaskExecutionError] If task execution fails after retries
       def execute_task(task_name, inputs: {}, timeout: nil, max_retries: nil)
         execution_start = Time.now
-        timeout ||= @config[:timeout]
         max_retries ||= @config[:max_retries]
 
         with_span('task_executor.execute_task', attributes: {
                     'task.name' => task_name.to_s,
                     'task.inputs' => inputs.keys.map(&:to_s).join(','),
-                    'task.timeout' => timeout,
                     'task.max_retries' => max_retries
                   }) do
           # Find task definition
@@ -109,12 +109,19 @@ module LanguageOperator
           raise ArgumentError, "Task not found: #{task_name}. Available tasks: #{@tasks.keys.join(', ')}" unless task
 
           task_type = determine_task_type(task)
+
+          # Determine timeout based on task type if not explicitly provided
+          timeout ||= task_timeout_for_type(task)
+
           logger.info('Executing task',
                       task: task_name,
                       type: task_type,
                       timeout: timeout,
                       max_retries: max_retries)
 
+          # Add timeout to span attributes after it's determined
+          OpenTelemetry::Trace.current_span&.set_attribute('task.timeout', timeout)
+
           # Execute with retry logic
           execute_with_retry(task, task_name, inputs, timeout, max_retries, execution_start)
         end
@@ -335,10 +342,12 @@ module LanguageOperator
       # @return [Hash] Default configuration
       def default_config
         {
-          timeout: 30.0,           # Default timeout in seconds
-          max_retries: 3,          # Default max retry attempts
-          retry_delay_base: 1.0,   # Base delay for exponential backoff
-          retry_delay_max: 10.0    # Maximum delay between retries
+          timeout_symbolic: 30.0,     # Default timeout for symbolic tasks (seconds)
+          timeout_neural: 120.0,      # Default timeout for neural tasks (seconds)
+          timeout_hybrid: 120.0,      # Default timeout for hybrid tasks (seconds)
+          max_retries: 3,             # Default max retry attempts
+          retry_delay_base: 1.0,      # Base delay for exponential backoff
+          retry_delay_max: 10.0       # Maximum delay between retries
         }
       end
 
@@ -358,6 +367,29 @@ module LanguageOperator
         end
       end
 
+      # Determine appropriate timeout for a task based on its type
+      #
+      # Neural tasks typically require longer timeouts due to LLM API calls,
+      # while symbolic tasks (pure Ruby code) can use shorter timeouts.
+      #
+      # @param task [TaskDefinition] The task definition
+      # @return [Float] Timeout in seconds
+      def task_timeout_for_type(task)
+        if task.neural? && task.symbolic?
+          # Hybrid tasks use neural timeout (they may call LLM)
+          @config[:timeout_hybrid]
+        elsif task.neural?
+          # Neural tasks need longer timeout for LLM calls
+          @config[:timeout_neural]
+        elsif task.symbolic?
+          # Symbolic tasks use shorter timeout
+          @config[:timeout_symbolic]
+        else
+          # Default to symbolic timeout for undefined tasks
+          @config[:timeout_symbolic]
+        end
+      end
+
       # Execute task with retry logic and timeout
       #
       # @param task [TaskDefinition] The task definition

data/lib/language_operator/cli/commands/agent.rb

@@ -76,9 +76,6 @@ module LanguageOperator
 
             ctx = Helpers::ClusterContext.from_options(options.merge(cluster: cluster))
 
-            Formatters::ProgressFormatter.info("Creating agent in cluster '#{ctx.name}'")
-            puts
-
             # Generate agent name from description if not provided
             agent_name = options[:name] || generate_agent_name(description)
 

data/lib/language_operator/cli/commands/system.rb

@@ -1105,6 +1105,7 @@ module LanguageOperator
                 {
                   'name' => 'agent',
                   'image' => image,
+                  'imagePullPolicy' => 'Always',
                   'env' => env_vars,
                   'volumeMounts' => [
                     {