language-operator 0.0.1 → 0.1.30

data/examples/chat_endpoint_agent.rb

@@ -0,0 +1,118 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example agent that exposes an OpenAI-compatible chat completion endpoint
+#
+# This demonstrates Phase 4: Agents as Chat Completion Endpoints
+# The agent can be used as a drop-in replacement for OpenAI's API
+#
+# Usage:
+#   PORT=8080 ruby examples/chat_endpoint_agent.rb
+#
+# Test non-streaming:
+#   curl -X POST http://localhost:8080/v1/chat/completions \
+#     -H "Content-Type: application/json" \
+#     -d '{
+#       "model": "github-expert",
+#       "messages": [{"role": "user", "content": "How do I create a PR?"}]
+#     }'
+#
+# Test streaming:
+#   curl -X POST http://localhost:8080/v1/chat/completions \
+#     -H "Content-Type: application/json" \
+#     -d '{
+#       "model": "github-expert",
+#       "messages": [{"role": "user", "content": "How do I create a PR?"}],
+#       "stream": true
+#     }'
+#
+# Test with OpenAI SDK:
+#   require 'openai'
+#   client = OpenAI::Client.new(
+#     access_token: "not-needed",
+#     uri_base: "http://localhost:8080/v1/"
+#   )
+#   response = client.chat(
+#     parameters: {
+#       model: "github-expert",
+#       messages: [{role: "user", content: "How do I create a PR?"}]
+#     }
+#   )
+
+require 'bundler/setup'
+require 'language_operator'
+require 'language_operator/dsl'
+
+# Define an agent that acts as a GitHub expert LLM
+LanguageOperator::Dsl.define do
+  agent 'github-expert' do
+    description 'GitHub API and workflow expert'
+    mode :reactive
+
+    # Configure as an OpenAI-compatible chat endpoint
+    as_chat_endpoint do
+      system_prompt <<~PROMPT
+        You are a GitHub expert assistant with deep knowledge of:
+        - GitHub API and workflows
+        - Pull requests, issues, and code review
+        - GitHub Actions and CI/CD
+        - Repository management and best practices
+
+        Provide helpful, accurate answers about GitHub topics.
+        Keep responses concise but informative.
+      PROMPT
+
+      # Model parameters
+      model 'github-expert-v1'
+      temperature 0.7
+      max_tokens 2000
+    end
+
+    # Optionally, also expose as webhook
+    webhook '/github/webhook' do
+      method :post
+      on_request do |_context|
+        {
+          status: 'received',
+          message: 'GitHub webhook processed',
+          chat_endpoint: '/v1/chat/completions'
+        }
+      end
+    end
+  end
+end
+# Get the agent definition and run it
+agent_def = LanguageOperator::Dsl.agent_registry.get('github-expert')
+
+if agent_def
+  puts "Starting GitHub Expert agent on port #{ENV.fetch('PORT', '8080')}"
+  puts
+  puts 'OpenAI-Compatible Endpoints:'
+  puts '  POST /v1/chat/completions - Chat completion (streaming & non-streaming)'
+  puts '  GET  /v1/models           - List available models'
+  puts
+  puts 'Additional Endpoints:'
+  puts '  GET  /health              - Health check'
+  puts '  GET  /ready               - Readiness check'
+  puts '  POST /github/webhook      - GitHub webhook endpoint'
+  puts
+  puts 'Test with curl:'
+  puts <<~CURL
+    curl -X POST http://localhost:8080/v1/chat/completions \\
+      -H "Content-Type: application/json" \\
+      -d '{"model": "github-expert-v1", "messages": [{"role": "user", "content": "How do I create a PR?"}]}'
+  CURL
+  puts
+  puts 'Test streaming:'
+  puts <<~CURL
+    curl -N -X POST http://localhost:8080/v1/chat/completions \\
+      -H "Content-Type: application/json" \\
+      -d '{"model": "github-expert-v1", "messages": [{"role": "user", "content": "Explain GitHub Actions"}], "stream": true}'
+  CURL
+  puts "\nPress Ctrl+C to stop\n\n"
+
+  agent_def.run!
+else
+  puts 'Error: Agent definition not found'
+  exit 1
+end

data/examples/github_webhook_agent.rb

@@ -0,0 +1,171 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# GitHub Webhook Agent Example
+#
+# This example shows how to create an agent that receives GitHub webhook events
+# with proper signature verification for security.
+#
+# Setup:
+# 1. Set GITHUB_WEBHOOK_SECRET environment variable
+# 2. Configure GitHub webhook to send events to https://<agent-url>/github/events
+# 3. Select events you want to receive (e.g., pull_request, issues, push)
+#
+# GitHub webhook documentation:
+# https://docs.github.com/en/webhooks
+
+require 'bundler/setup'
+require 'language_operator'
+
+LanguageOperator::Dsl.define_agents do
+  agent 'github-pr-reviewer' do
+    description 'Automatically reviews pull requests and provides feedback'
+
+    # Set to reactive mode to receive webhooks
+    mode :reactive
+
+    # GitHub Pull Request webhook
+    webhook '/github/pull_request' do
+      method :post
+
+      # Verify GitHub webhook signature
+      # GitHub sends signature in X-Hub-Signature-256 header
+      # Format: "sha256=<signature>"
+      authenticate do
+        verify_signature(
+          header: 'X-Hub-Signature-256',
+          secret: ENV.fetch('GITHUB_WEBHOOK_SECRET', nil),
+          algorithm: :sha256,
+          prefix: 'sha256='
+        )
+      end
+
+      # Validate request format
+      require_content_type 'application/json'
+      require_headers(
+        'X-GitHub-Event' => nil, # Just check presence, any value OK
+        'X-GitHub-Delivery' => nil
+      )
+
+      on_request do |context|
+        event = JSON.parse(context[:body])
+        action = event['action']
+        pr = event['pull_request']
+
+        case action
+        when 'opened'
+          handle_pr_opened(pr, context)
+        when 'synchronize'
+          handle_pr_updated(pr, context)
+        when 'closed'
+          handle_pr_closed(pr, context)
+        else
+          { status: 'ignored', action: action }
+        end
+      end
+    end
+
+    # GitHub Issue webhook
+    webhook '/github/issues' do
+      method :post
+
+      authenticate do
+        verify_signature(
+          header: 'X-Hub-Signature-256',
+          secret: ENV.fetch('GITHUB_WEBHOOK_SECRET', nil),
+          algorithm: :sha256,
+          prefix: 'sha256='
+        )
+      end
+
+      require_content_type 'application/json'
+
+      on_request do |context|
+        event = JSON.parse(context[:body])
+        action = event['action']
+        issue = event['issue']
+
+        case action
+        when 'opened'
+          {
+            status: 'processed',
+            message: "New issue: #{issue['title']}",
+            issue_number: issue['number']
+          }
+        when 'labeled'
+          {
+            status: 'processed',
+            message: "Issue labeled: #{event['label']['name']}"
+          }
+        else
+          { status: 'ignored', action: action }
+        end
+      end
+    end
+
+    # GitHub Push webhook
+    webhook '/github/push' do
+      method :post
+
+      authenticate do
+        verify_signature(
+          header: 'X-Hub-Signature-256',
+          secret: ENV.fetch('GITHUB_WEBHOOK_SECRET', nil),
+          algorithm: :sha256,
+          prefix: 'sha256='
+        )
+      end
+
+      require_content_type 'application/json'
+
+      on_request do |context|
+        event = JSON.parse(context[:body])
+        ref = event['ref']
+        commits = event['commits']
+
+        {
+          status: 'processed',
+          message: "Received #{commits.length} commits on #{ref}",
+          commits: commits.map { |c| c['message'] }
+        }
+      end
+    end
+  end
+end
+
+# Helper methods for PR handling
+def handle_pr_opened(pr, _context)
+  {
+    status: 'processed',
+    action: 'pr_opened',
+    pr_number: pr['number'],
+    pr_title: pr['title'],
+    pr_url: pr['html_url'],
+    message: "Reviewing PR ##{pr['number']}: #{pr['title']}"
+  }
+end
+
+def handle_pr_updated(pr, _context)
+  {
+    status: 'processed',
+    action: 'pr_updated',
+    pr_number: pr['number'],
+    message: "PR ##{pr['number']} was updated"
+  }
+end
+
+def handle_pr_closed(pr, _context)
+  {
+    status: 'processed',
+    action: 'pr_closed',
+    pr_number: pr['number'],
+    merged: pr['merged'],
+    message: "PR ##{pr['number']} was #{pr['merged'] ? 'merged' : 'closed'}"
+  }
+end
+
+# Run the agent if this file is executed directly
+if __FILE__ == $PROGRAM_NAME
+  agent = LanguageOperator::Dsl.agent_registry.get('github-pr-reviewer')
+  agent.run!
+end

data/examples/mcp_agent.rb

@@ -0,0 +1,158 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example agent that exposes tools via MCP protocol
+#
+# This demonstrates Phase 3: Agents as MCP Servers
+# The agent exposes tools that other agents or MCP clients can call
+#
+# Usage:
+#   PORT=8080 ruby examples/mcp_agent.rb
+#
+# Test MCP protocol:
+#   curl -X POST http://localhost:8080/mcp \
+#     -H "Content-Type: application/json" \
+#     -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
+#
+# Test webhook:
+#   curl -X POST http://localhost:8080/webhook \
+#     -H "Content-Type: application/json" \
+#     -d '{"message": "test"}'
+
+require 'bundler/setup'
+require 'language_operator'
+require 'language_operator/dsl'
+
+# Define an agent that acts as both a webhook receiver and MCP server
+# rubocop:disable Metrics/BlockLength
+LanguageOperator::Dsl.define do
+  agent 'data-processor-mcp' do
+    description 'Data processing agent that exposes MCP tools'
+    mode :reactive
+
+    # Define tools this agent exposes via MCP
+    as_mcp_server do
+      # Tool 1: Process CSV data
+      tool 'process_csv' do
+        description 'Process CSV data and return summary statistics'
+
+        parameter :csv_data do
+          type :string
+          required true
+          description 'CSV data as string'
+        end
+
+        execute do |params|
+          # Simple CSV processing example
+          lines = params['csv_data'].split("\n")
+          headers = lines.first&.split(',') || []
+          data_rows = lines[1..]
+
+          {
+            total_rows: data_rows&.length || 0,
+            total_columns: headers.length,
+            headers: headers,
+            sample: data_rows&.first || ''
+          }.to_json
+        end
+      end
+
+      # Tool 2: Calculate statistics
+      tool 'calculate_stats' do
+        description 'Calculate basic statistics for a list of numbers'
+
+        parameter :numbers do
+          type :array
+          required true
+          description 'Array of numbers'
+        end
+
+        execute do |params|
+          nums = params['numbers']
+          return { error: 'Empty array' }.to_json if nums.empty?
+
+          sum = nums.sum
+          mean = sum.to_f / nums.length
+          sorted = nums.sort
+          median = if nums.length.odd?
+                     sorted[nums.length / 2]
+                   else
+                     (sorted[(nums.length / 2) - 1] + sorted[nums.length / 2]) / 2.0
+                   end
+
+          {
+            count: nums.length,
+            sum: sum,
+            mean: mean,
+            median: median,
+            min: nums.min,
+            max: nums.max
+          }.to_json
+        end
+      end
+
+      # Tool 3: Format data
+      tool 'format_json' do
+        description 'Format and validate JSON data'
+
+        parameter :json_string do
+          type :string
+          required true
+          description 'JSON string to format'
+        end
+
+        parameter :indent do
+          type :number
+          required false
+          description 'Indentation spaces (default: 2)'
+        end
+
+        execute do |params|
+          indent = params['indent'] || 2
+          parsed = JSON.parse(params['json_string'])
+          JSON.pretty_generate(parsed, indent: ' ' * indent.to_i)
+        rescue JSON::ParserError => e
+          { error: "Invalid JSON: #{e.message}" }.to_json
+        end
+      end
+    end
+
+    # Also expose a webhook endpoint
+    webhook '/process' do
+      method :post
+      on_request do |_context|
+        {
+          status: 'processed',
+          message: 'Data received for processing',
+          tools_available: 3,
+          mcp_endpoint: '/mcp'
+        }
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/BlockLength
+
+# Get the agent definition and run it
+agent_def = LanguageOperator::Dsl.agent_registry.get('data-processor-mcp')
+
+if agent_def
+  puts "Starting MCP agent on port #{ENV.fetch('PORT', '8080')}"
+  puts 'Available endpoints:'
+  puts '  GET  /health        - Health check'
+  puts '  GET  /ready         - Readiness check'
+  puts '  POST /webhook       - Webhook endpoint'
+  puts '  POST /process       - Data processing endpoint'
+  puts '  POST /mcp           - MCP protocol endpoint'
+  puts
+  puts 'MCP Tools:'
+  puts '  - process_csv       - Process CSV data'
+  puts '  - calculate_stats   - Calculate statistics'
+  puts '  - format_json       - Format JSON data'
+  puts "\nPress Ctrl+C to stop\n\n"
+
+  agent_def.run!
+else
+  puts 'Error: Agent definition not found'
+  exit 1
+end