language-operator 0.0.1 → 0.1.30

data/lib/language_operator/validators.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  # Common parameter validation utilities
+  #
+  # Provides reusable validators for common parameter validation patterns
+  # across tools. All validators follow the same convention:
+  # - Return `nil` if the value is valid
+  # - Return an error string if the value is invalid
+  #
+  # This allows for consistent usage in tools:
+  #   error = LanguageOperator::Validators.http_url(params['url'])
+  #   next error if error
+  #
+  # @example URL validation
+  #   error = Validators.http_url('https://example.com')
+  #   # => nil (valid)
+  #
+  #   error = Validators.http_url('ftp://example.com')
+  #   # => "Error: Invalid URL. Must start with http:// or https://"
+  #
+  # @example Enum validation
+  #   error = Validators.one_of('GET', %w[GET POST PUT DELETE], 'HTTP method')
+  #   # => nil (valid)
+  #
+  #   error = Validators.one_of('INVALID', %w[GET POST PUT DELETE], 'HTTP method')
+  #   # => "Error: Invalid HTTP method 'INVALID'. Expected: one of: GET, POST, PUT, DELETE"
+  module Validators
+    # Validate HTTP/HTTPS URL format
+    #
+    # @param url [String] URL to validate
+    # @return [String, nil] Error message if invalid, nil if valid
+    #
+    # @example Valid URLs
+    #   Validators.http_url('http://example.com')  # => nil
+    #   Validators.http_url('https://api.example.com/v1')  # => nil
+    #
+    # @example Invalid URLs
+    #   Validators.http_url('')  # => "Error: URL cannot be empty"
+    #   Validators.http_url('ftp://example.com')  # => "Error: Invalid URL..."
+    def self.http_url(url)
+      return 'Error: URL cannot be empty' if url.nil? || url.strip.empty?
+      return nil if url =~ %r{^https?://.+}
+
+      'Error: Invalid URL. Must start with http:// or https://'
+    end
+
+    # Validate that a value is not nil or empty
+    #
+    # @param value [Object] Value to check
+    # @param field_name [String] Name of the field for error message
+    # @return [String, nil] Error message if invalid, nil if valid
+    #
+    # @example Valid values
+    #   Validators.not_empty('value', 'Name')  # => nil
+    #   Validators.not_empty('  text  ', 'Name')  # => nil (has content after strip)
+    #
+    # @example Invalid values
+    #   Validators.not_empty(nil, 'Name')  # => "Error: Name cannot be empty"
+    #   Validators.not_empty('', 'Name')  # => "Error: Name cannot be empty"
+    #   Validators.not_empty('   ', 'Name')  # => "Error: Name cannot be empty"
+    def self.not_empty(value, field_name)
+      return nil if value && !value.to_s.strip.empty?
+
+      LanguageOperator::Errors.empty_field(field_name)
+    end
+
+    # Validate that a value is one of the allowed options
+    #
+    # @param value [String] Value to validate
+    # @param allowed [Array<String>] Allowed values
+    # @param field_name [String] Field name for error message
+    # @return [String, nil] Error message if invalid, nil if valid
+    #
+    # @example Valid choice
+    #   Validators.one_of('GET', %w[GET POST PUT], 'method')  # => nil
+    #
+    # @example Invalid choice
+    #   Validators.one_of('DELETE', %w[GET POST PUT], 'method')
+    #   # => "Error: Invalid method 'DELETE'. Expected: one of: GET, POST, PUT"
+    def self.one_of(value, allowed, field_name)
+      return nil if allowed.include?(value)
+
+      LanguageOperator::Errors.invalid_parameter(
+        field_name,
+        value,
+        "one of: #{allowed.join(', ')}"
+      )
+    end
+
+    # Validate numeric range
+    #
+    # @param value [Numeric] Value to validate
+    # @param min [Numeric, nil] Minimum value (inclusive)
+    # @param max [Numeric, nil] Maximum value (inclusive)
+    # @param field_name [String] Field name for error message
+    # @return [String, nil] Error message if invalid, nil if valid
+    #
+    # @example Valid ranges
+    #   Validators.numeric_range(5, min: 1, max: 10)  # => nil
+    #   Validators.numeric_range(100, min: 50)  # => nil
+    #   Validators.numeric_range(5, max: 10)  # => nil
+    #
+    # @example Invalid ranges
+    #   Validators.numeric_range('foo', min: 1)  # => "Error: value must be a number"
+    #   Validators.numeric_range(0, min: 1)  # => "Error: value must be at least 1"
+    #   Validators.numeric_range(100, max: 50)  # => "Error: value must be at most 50"
+    def self.numeric_range(value, min: nil, max: nil, field_name: 'value')
+      return "Error: #{field_name} must be a number" unless value.is_a?(Numeric)
+
+      return "Error: #{field_name} must be at least #{min}" if min && value < min
+
+      return "Error: #{field_name} must be at most #{max}" if max && value > max
+
+      nil
+    end
+
+    # Validate email address format (basic)
+    #
+    # Note: This is a basic format check, not full RFC 5322 validation.
+    # It checks for: something@domain.tld
+    #
+    # @param email [String] Email address to validate
+    # @return [String, nil] Error message if invalid, nil if valid
+    #
+    # @example Valid emails
+    #   Validators.email('user@example.com')  # => nil
+    #   Validators.email('test.user+tag@domain.co.uk')  # => nil
+    #
+    # @example Invalid emails
+    #   Validators.email('')  # => "Error: Email address cannot be empty"
+    #   Validators.email('invalid')  # => "Error: Invalid email address format"
+    #   Validators.email('@example.com')  # => "Error: Invalid email address format"
+    def self.email(email)
+      return 'Error: Email address cannot be empty' if email.nil? || email.strip.empty?
+      return nil if email =~ /\A[^@\s]+@[^@\s]+\.[^@\s]+\z/
+
+      'Error: Invalid email address format'
+    end
+
+    # Validate that a path doesn't contain directory traversal attempts
+    #
+    # Checks for:
+    # - Parent directory references (..)
+    # - Null bytes (\0)
+    #
+    # Note: This is a basic safety check. Tool-specific path validation
+    # (like workspace sandboxing) should still be implemented in the tools.
+    #
+    # @param path [String] Path to validate
+    # @return [String, nil] Error message if invalid, nil if valid
+    #
+    # @example Valid paths
+    #   Validators.safe_path('/absolute/path')  # => nil
+    #   Validators.safe_path('relative/path.txt')  # => nil
+    #
+    # @example Invalid paths
+    #   Validators.safe_path('')  # => "Error: Path cannot be empty"
+    #   Validators.safe_path('../../../etc/passwd')  # => "Error: Path contains..."
+    #   Validators.safe_path("file\0name")  # => "Error: Path contains..."
+    def self.safe_path(path)
+      return 'Error: Path cannot be empty' if path.nil? || path.strip.empty?
+
+      # Check for obvious traversal attempts
+      return 'Error: Path contains invalid characters or directory traversal' if path.include?('..') || path.include?("\0")
+
+      nil
+    end
+  end
+end

data/lib/language_operator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LanguageOperator
-  VERSION = "0.0.1"
+  VERSION = '0.1.30'
 end

data/lib/language_operator.rb

@@ -1,8 +1,70 @@
 # frozen_string_literal: true
 
-require_relative "language_operator/version"
+require 'language_operator/version'
+require 'language_operator/errors'
+require 'language_operator/retry'
+require 'language_operator/config'
+require 'language_operator/validators'
+require 'language_operator/dsl'
+require 'language_operator/client'
+require 'language_operator/tool_loader'
 
-# This is a placeholder gem to reserve the name "language-operator" on RubyGems.
-# The actual implementation will be released when the project is ready.
+# Agent module is optional - only load if dependencies are available
+# This allows the SDK to be used in environments without agent dependencies
+begin
+  require 'language_operator/agent'
+rescue LoadError => e
+  # Agent dependencies not available, skip loading
+  warn "LanguageOperator: Agent module not loaded (missing dependency: #{e.message})" if ENV['DEBUG']
+end
+
+# Langop - Ruby SDK for building MCP tools and language agents
+#
+# This gem provides:
+# - DSL for defining MCP tools with a clean, Ruby-like syntax
+# - Client library for connecting to MCP servers
+# - Agent framework for autonomous task execution
+# - CLI for generating and running tools and agents
+#
+# @example Define a tool
+#   LanguageOperator::Dsl.define do
+#     tool "greet" do
+#       description "Greet a user"
+#       parameter :name do
+#         type :string
+#         required true
+#       end
+#       execute do |params|
+#         "Hello, #{params['name']}!"
+#       end
+#     end
+#   end
+#
+# @example Use the client
+#   config = LanguageOperator::Client::Config.from_env
+#   client = LanguageOperator::Client::Base.new(config)
+#   client.connect!
+#   response = client.send_message("What can you do?")
+#
+# @example Run an agent
+#   agent = LanguageOperator::Agent::Base.new(config)
+#   agent.run
 module LanguageOperator
+  class Error < StandardError; end
+
+  # Convenience method to define tools
+  #
+  # @yield Block containing tool definitions
+  # @return [LanguageOperator::Dsl::Registry] The global tool registry
+  def self.define(&)
+    Dsl.define(&)
+  end
+
+  # Convenience method to load tools from a file
+  #
+  # @param file_path [String] Path to tool definition file
+  # @return [LanguageOperator::Dsl::Registry] The global tool registry
+  def self.load_file(file_path)
+    Dsl.load_file(file_path)
+  end
 end

data/requirements/tasks/challenge.md

@@ -0,0 +1,9 @@
+You are the public face, the user interface, of an extremely ambitious project called the Language Operator.
+
+It synthesizes code *in production* securely from any arbitrary instructions written in plain text.
+
+Read ../language-operator/README.md to understand your significance.
+
+In that light, I challenge you to ensure that we're matching that vision in quality and supporting the full power of its CRDs.
+
+Dive into this code, maybe into the language-operator itself.  What can **this gem** do better at?

data/requirements/tasks/iterate.md

@@ -0,0 +1,36 @@
+# Task
+
+## Persona
+
+Adopt the [ruby-engineer](../../../requirements/personas/ruby-engineer.md) persona while executing these instructions, please.
+
+## Inputs
+
+- id int -- A forgejo issue index ID.
+
+## Background
+
+This is a early-phase project that works exclusively in main.
+Issues are found using the Forgejo MCP tools for this project:
+- Owner: language-operator
+- Repository: language-operator-gem
+
+## Instructions
+
+Follow these directions closely:
+
+1. Use the ForgeJo tool to find the top issue for this repository.
+2. Investigate if it's valid, or a mis-use of the intended feature.
+3. **CRITICAL:** Switch to plan mode, and propose an implementation plan.  Await my feedback.
+4. Add your implementation plan as a comment on the issue.
+5. Implement the changes.
+6. Run existing tests, and add new ones if necessary.  Remember to include CI. Remember the linter and that bundler will fail if it's out of sync with its lockfile.
+7. **CRITICAL:** Test the actual functionality manually before committing. If it's a CLI command, run it. If it's library code, test it in the appropriate context. Never commit untested code.
+8. Commit the change and push to origin.
+9. **CRITICAL:** Halt while CI runs and await my feedback.
+10. Comment on your solution in the ForgeJo issue.
+11. Resolve the issue.
+
+## Output
+
+An implementation, test coverage, updated CI, and a closed ticket.

data/requirements/tasks/optimize.md

@@ -0,0 +1,21 @@
+
+# Task
+
+## Name
+
+Optimize
+
+## Persona
+
+Adopt the [ruby-engineer](../requirements/personas/ruby-engineer.md) persona while executing these instructions, please.
+
+## Instructions
+
+Suggest an improvement that could improve the quality of the codebase or developer experience.  Things like opportunities to reduce lines of code, DRYing up code, or eliminating dead code paths.
+
+An important thing to consider is that this code has been written by different agents with different contexts, who may not have been aware of overall patterns.  These kinds of optimizations are high priority.
+
+## Output
+
+Switch to Plan mode.
+A proposed list of three concrete optimizations.

data/requirements/tasks/tag.md

@@ -0,0 +1,5 @@
+Time to release a new version!
+
+1. Update the patch version in lib/language_operator/version.rb and re-run bundler to update the lockfile.
+2. Commit the version with the message "vX.Y.Z" and push to origin.
+3. Tag the new version and push to origin with the --tags argument.

data/test_agent_dsl.rb

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Quick test of the agent DSL without requiring full langop gem dependencies
+
+require_relative 'lib/langop/dsl/agent_definition'
+require_relative 'lib/langop/dsl/agent_context'
+require_relative 'lib/langop/dsl/workflow_definition'
+
+puts '=' * 70
+puts 'Agent DSL Test'
+puts '=' * 70
+puts
+
+# Create registry and context
+registry = Langop::Dsl::AgentRegistry.new
+context = Langop::Dsl::AgentContext.new(registry)
+
+# Define an agent using the DSL (this is what the operator will synthesize)
+context.agent 'kubernetes-news' do
+  description 'Daily Kubernetes news summarization agent'
+
+  # Persona (distilled by operator from LanguagePersona)
+  persona <<~PERSONA
+    You are a technical writer specializing in Kubernetes. When researching and
+    summarizing news, maintain a clear and precise tone, always cite your sources,
+    use proper technical terminology, and make complex topics accessible without
+    unnecessary jargon. Your summaries should be educational and well-structured.
+  PERSONA
+
+  # Schedule (extracted from: "once a day, preferably around lunchtime")
+  schedule '0 12 * * *'
+
+  # Objectives (extracted from instructions)
+  objectives [
+    'Search for recent Kubernetes news using web_search tool',
+    'Provide a concise summary of findings'
+  ]
+
+  # Workflow (synthesized by operator)
+  workflow do
+    step :search do
+      tool 'web_search'
+      params query: 'Kubernetes news latest'
+    end
+
+    step :summarize do
+      depends_on :search
+      prompt 'Provide a concise summary of these Kubernetes news items: {search.output}'
+    end
+  end
+
+  # Constraints (inferred by operator)
+  constraints do
+    max_iterations 20
+    timeout '5m'
+  end
+
+  # Output (inferred from workspace settings)
+  output do
+    workspace 'summaries/kubernetes-{date}.md'
+  end
+end
+
+# Retrieve and display the agent
+agent = registry.get('kubernetes-news')
+
+if agent
+  puts '✅ Agent Definition Loaded'
+  puts
+  puts "Name:         #{agent.name}"
+  puts "Description:  #{agent.description}"
+  puts "Mode:         #{agent.execution_mode}"
+  puts "Schedule:     #{agent.schedule}"
+  puts
+  puts '📋 Persona:'
+  puts agent.persona.lines.map { |l| "  #{l}" }.join
+  puts
+  puts "🎯 Objectives (#{agent.objectives.size}):"
+  agent.objectives.each_with_index do |obj, i|
+    puts "  #{i + 1}. #{obj}"
+  end
+  puts
+  puts "⚙️  Workflow Steps (#{agent.workflow.steps.size}):"
+  agent.workflow.steps.each do |name, step|
+    deps = step.dependencies.empty? ? '' : " [depends on: #{step.dependencies.join(', ')}]"
+    tool_info = step.tool ? " (tool: #{step.tool})" : ''
+    prompt_info = step.prompt ? " (prompt: #{step.prompt[0..50]}...)" : ''
+    puts "  - #{name}#{deps}#{tool_info}#{prompt_info}"
+  end
+  puts
+  puts '📊 Constraints:'
+  agent.constraints.each do |key, value|
+    puts "  #{key}: #{value}"
+  end
+  puts
+  puts '📤 Output:'
+  agent.output_config.each do |key, value|
+    puts "  #{key}: #{value}"
+  end
+  puts
+  puts '=' * 70
+  puts '✅ DSL Test Complete - Agent ready for execution!'
+  puts '=' * 70
+else
+  puts '❌ Failed to load agent'
+  exit 1
+end