language-operator 0.1.67 → 0.1.71

data/examples/hybrid_agent.rb

@@ -0,0 +1,227 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Hybrid Agent Example
+#
+# This demonstrates an agent that runs BOTH:
+# 1. Continuous autonomous work (background monitoring)
+# 2. Chat endpoint for interactive queries
+#
+# The agent will:
+# - Monitor system status every 30 seconds (autonomous mode)
+# - Expose chat endpoint at /v1/chat/completions (web server)
+# - Handle webhooks for alerts (reactive features)
+#
+# Usage:
+#   ruby examples/hybrid_agent.rb
+#
+# Test chat endpoint:
+#   curl -X POST http://localhost:8080/v1/chat/completions \
+#     -H "Content-Type: application/json" \
+#     -d '{
+#       "model": "system-monitor-v1",
+#       "messages": [
+#         {"role": "user", "content": "What is the current system status?"}
+#       ]
+#     }'
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'language_operator'
+
+# Define a hybrid agent
+LanguageOperator::Dsl.define do
+  agent "system-monitor" do
+    description "Autonomous system monitor with chat interface"
+    
+    # This agent runs in autonomous mode (continuous loop)
+    mode :autonomous
+    
+    # Define the main autonomous work
+    task :check_system_status,
+      instructions: "Check current system status (CPU, memory, disk, network)",
+      inputs: {},
+      outputs: { 
+        status: 'string',
+        cpu_usage: 'number',
+        memory_usage: 'number',
+        disk_usage: 'number',
+        timestamp: 'string'
+      }
+
+    task :analyze_trends,
+      instructions: "Analyze system trends and identify potential issues",
+      inputs: { 
+        status: 'string',
+        cpu_usage: 'number',
+        memory_usage: 'number',
+        disk_usage: 'number'
+      },
+      outputs: { 
+        analysis: 'string',
+        alerts: 'array'
+      }
+
+    task :log_status,
+      instructions: "Log the system status and analysis",
+      inputs: {
+        status: 'string',
+        analysis: 'string',
+        alerts: 'array',
+        timestamp: 'string'
+      },
+      outputs: { logged: 'boolean' }
+
+    # Main autonomous loop - runs continuously
+    main do |inputs|
+      puts "🔄 Running system monitoring cycle..."
+      
+      # Check system status
+      status_data = execute_task(:check_system_status)
+      puts "📊 System status: #{status_data[:status]} (CPU: #{status_data[:cpu_usage]}%)"
+      
+      # Analyze trends
+      analysis_data = execute_task(:analyze_trends, inputs: status_data)
+      
+      # Log results
+      execute_task(:log_status, inputs: status_data.merge(analysis_data))
+      
+      if analysis_data[:alerts].any?
+        puts "⚠️  Alerts: #{analysis_data[:alerts].join(', ')}"
+      end
+      
+      puts "😴 Sleeping for 30 seconds..."
+      sleep 30
+      
+      # Return data for next cycle
+      status_data.merge(analysis_data)
+    end
+
+    # Chat endpoint for interactive queries
+    as_chat_endpoint do
+      system_prompt <<~PROMPT
+        You are a system monitoring assistant with real-time access to system metrics.
+        
+        You can help with:
+        - Current system status and performance metrics
+        - Historical trends and analysis
+        - Performance optimization recommendations
+        - Alert investigation and troubleshooting
+        - System health assessments
+        
+        Provide clear, actionable insights about system performance.
+        Use technical terminology appropriately but explain complex concepts.
+      PROMPT
+
+      model "system-monitor-v1"
+      temperature 0.3  # More factual for system data
+      max_tokens 1500
+    end
+
+    # Webhook for external alerts
+    webhook "/alert" do
+      method :post
+      
+      on_request do |context|
+        alert_data = JSON.parse(context[:body])
+        puts "🚨 Received alert: #{alert_data['message']}"
+        
+        # Could trigger immediate system check or escalation
+        {
+          status: 'received',
+          alert_id: alert_data['id'],
+          processed_at: Time.now.iso8601
+        }
+      end
+    rescue JSON::ParserError => e
+      {
+        error: 'Invalid JSON in alert payload',
+        message: e.message
+      }
+    end
+
+    # MCP tools for system operations
+    as_mcp_server do
+      tool "get_current_metrics" do
+        description "Get real-time system metrics"
+        
+        execute do |params|
+          # Simulate system metrics collection
+          {
+            cpu_percent: rand(0.0..100.0).round(1),
+            memory_percent: rand(0.0..100.0).round(1), 
+            disk_percent: rand(0.0..100.0).round(1),
+            load_average: [rand(0.0..4.0), rand(0.0..4.0), rand(0.0..4.0)].map { |x| x.round(2) },
+            uptime_seconds: rand(3600..2_592_000),
+            timestamp: Time.now.iso8601
+          }
+        end
+      end
+
+      tool "restart_service" do
+        description "Restart a system service"
+        parameter "service_name", type: :string, required: true, description: "Name of service to restart"
+        
+        execute do |params|
+          service_name = params["service_name"]
+          puts "🔄 Restarting service: #{service_name}"
+          
+          # Simulate service restart
+          success = rand > 0.1  # 90% success rate
+          
+          {
+            service: service_name,
+            action: 'restart',
+            success: success,
+            message: success ? "Service restarted successfully" : "Failed to restart service",
+            timestamp: Time.now.iso8601
+          }
+        end
+      end
+    end
+
+    # Constraints for safety and resource management
+    constraints do
+      timeout '60s'
+      max_iterations 999999  # Run indefinitely
+      requests_per_minute 60  # For chat/webhook endpoints
+      daily_budget 2000      # $20/day
+    end
+  end
+end
+
+# Start the hybrid agent
+if __FILE__ == $PROGRAM_NAME
+  puts "🚀 Starting Hybrid System Monitor Agent"
+  puts ""
+  puts "This agent will:"
+  puts "  ✅ Run autonomous system monitoring every 30 seconds"
+  puts "  ✅ Expose chat endpoint at http://localhost:8080/v1/chat/completions"
+  puts "  ✅ Handle alerts via POST /alert webhook"
+  puts "  ✅ Provide MCP tools for system operations"
+  puts ""
+  puts "Available endpoints:"
+  puts "  POST /v1/chat/completions - Chat with the monitoring assistant"
+  puts "  GET  /v1/models          - List available models"
+  puts "  POST /alert              - Receive system alerts"
+  puts "  POST /mcp                - MCP protocol endpoint"
+  puts "  GET  /health             - Health check"
+  puts "  GET  /ready              - Readiness check"
+  puts ""
+  puts "Test commands:"
+  puts ""
+  puts "# Chat with the agent"
+  puts "curl -X POST http://localhost:8080/v1/chat/completions \\"
+  puts '  -H "Content-Type: application/json" \\'
+  puts '  -d \'{"model": "system-monitor-v1", "messages": [{"role": "user", "content": "What is the system status?"}]}\''
+  puts ""
+  puts "# Send an alert"  
+  puts "curl -X POST http://localhost:8080/alert \\"
+  puts '  -H "Content-Type: application/json" \\'
+  puts '  -d \'{"id": "alert-001", "message": "High CPU usage detected", "severity": "warning"}\''
+  puts ""
+  puts "Press Ctrl+C to stop"
+  puts "=" * 80
+  
+  LanguageOperator::Agent.run
+end

data/examples/identity_aware_chat_agent.rb

@@ -0,0 +1,83 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Identity-Aware Chat Agent Example
+#
+# This example demonstrates automatic persona-driven system prompts that provide
+# ALL agents with awareness of their identity, role, environment, and operational context.
+#
+# Key Features (AUTOMATIC):
+# - Agent knows its name, role, and purpose
+# - Operational context (uptime, cluster, status) awareness  
+# - Environment information (namespace, tools available)
+# - Professional, contextual conversation style
+#
+# Usage:
+#   ruby examples/identity_aware_chat_agent.rb
+#
+# Test with:
+#   curl -X POST http://localhost:8080/v1/chat/completions \
+#     -H "Content-Type: application/json" \
+#     -d '{"model": "say-something-v2", "messages": [{"role": "user", "content": "hello"}]}'
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'language_operator'
+
+# Define an identity-aware agent
+LanguageOperator::Dsl.define do
+  agent "say-something" do
+    description "A helpful assistant that specializes in creating engaging, concise messages and interactions. You excel at understanding context and providing meaningful responses that fit the conversation."
+    mode :reactive
+
+    # Identity-aware chat endpoint is automatic! 
+    # No configuration needed - every agent gets it by default.
+
+    # Add some constraints for safety
+    constraints do
+      timeout '30s'
+      requests_per_minute 20
+      daily_budget 500  # $5/day
+    end
+  end
+end
+
+# Start the agent
+if __FILE__ == $PROGRAM_NAME
+  puts "🚀 Starting Identity-Aware Say-Something Agent..."
+  puts ""
+  puts "ALL agents automatically include persona-driven system prompts with:"
+  puts "  ✓ Agent identity awareness (name, role, purpose)"
+  puts "  ✓ Operational context (uptime, status, environment)"  
+  puts "  ✓ Dynamic prompt generation based on current state"
+  puts "  ✓ Professional, contextual conversation style"
+  puts ""
+  puts "Server will be available at http://localhost:8080"
+  puts ""
+  puts "📝 Example conversation:"
+  puts "  User: 'hello'"
+  puts "  Agent: 'Hello! I'm say-something, running in the code-games cluster."
+  puts "         I've been active for 15m now, helping log interesting messages"
+  puts "         and interactions. How can I assist you today?'"
+  puts ""
+  puts "🔧 Endpoints:"
+  puts "  POST /v1/chat/completions - Chat completion (OpenAI-compatible)"
+  puts "  GET  /v1/models          - List available models"
+  puts "  GET  /health             - Health check"
+  puts "  GET  /ready              - Readiness check"
+  puts ""
+  puts "🧪 Test command:"
+  puts "  curl -X POST http://localhost:8080/v1/chat/completions \\"
+  puts "    -H 'Content-Type: application/json' \\"
+  puts '    -d \'{"model": "say-something-v2", "messages": [{"role": "user", "content": "hello"}]}\''
+  puts ""
+  puts "💡 Try different questions to see automatic identity awareness:"
+  puts "  - 'hello' or 'hi there' for context-aware introductions"
+  puts "  - 'what are you?' or 'tell me about yourself'"
+  puts "  - 'how long have you been running?'"
+  puts "  - 'what can you do?' or 'what tools do you have?'"
+  puts "  - 'what cluster are you in?'"
+  puts ""
+  
+  LanguageOperator::Agent.run
+end

data/examples/pure_agent_test.rb

@@ -0,0 +1,26 @@
+# Pure Agent Definition (no Ruby setup code)
+# This demonstrates that agents automatically get chat endpoints by default
+
+agent "test-basic" do
+  description "Simple test agent to verify default chat endpoints"
+  mode :autonomous
+
+  # Simple task
+  task :do_work,
+    instructions: "Perform some basic work",
+    inputs: {},
+    outputs: { 
+      message: 'string',
+      timestamp: 'string'
+    }
+
+  main do |inputs|
+    work_result = execute_task(:do_work)
+    work_result
+  end
+
+  constraints do
+    max_iterations 5  # Just run a few times for testing
+    timeout '10s'
+  end
+end

data/lib/language_operator/agent/metadata_collector.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require_relative '../loggable'
+
+module LanguageOperator
+  module Agent
+    # Agent Metadata Collector
+    #
+    # Collects runtime and configuration metadata about an agent for use in
+    # persona-driven system prompts and conversation context.
+    #
+    # Provides information about:
+    # - Agent identity (name, description, persona)
+    # - Runtime environment (cluster, namespace, mode)
+    # - Operational state (uptime, workspace, status)
+    # - Configuration details (capabilities, constraints)
+    #
+    # @example
+    #   collector = MetadataCollector.new(agent)
+    #   metadata = collector.collect
+    #   puts metadata[:identity][:name]  # => "my-agent"
+    #   puts metadata[:runtime][:uptime] # => "2h 15m"
+    class MetadataCollector
+      include LanguageOperator::Loggable
+
+      attr_reader :agent, :start_time
+
+      # Initialize metadata collector
+      #
+      # @param agent [LanguageOperator::Agent::Base] The agent instance
+      def initialize(agent)
+        @agent = agent
+        @start_time = Time.now
+        @logger = logger
+      end
+
+      # Collect all available metadata
+      #
+      # @return [Hash] Complete metadata structure
+      def collect
+        {
+          identity: collect_identity,
+          runtime: collect_runtime,
+          environment: collect_environment,
+          operational: collect_operational,
+          capabilities: collect_capabilities
+        }
+      end
+
+      # Collect basic identity information
+      #
+      # @return [Hash] Identity metadata
+      def collect_identity
+        config = @agent.config || {}
+        agent_config = config.dig('agent') || {}
+
+        {
+          name: ENV.fetch('AGENT_NAME', agent_config['name'] || 'unknown'),
+          description: agent_config['instructions'] || agent_config['description'] || 'AI Agent',
+          persona: agent_config['persona'] || ENV.fetch('PERSONA_NAME', nil),
+          mode: @agent.mode || 'unknown',
+          version: LanguageOperator::VERSION
+        }
+      end
+
+      # Collect runtime environment information
+      #
+      # @return [Hash] Runtime metadata
+      def collect_runtime
+        {
+          uptime: calculate_uptime,
+          started_at: @start_time.iso8601,
+          process_id: Process.pid,
+          workspace_available: @agent.workspace_available?,
+          mcp_servers_connected: @agent.respond_to?(:servers_info) ? @agent.servers_info.length : 0
+        }
+      end
+
+      # Collect deployment environment information
+      #
+      # @return [Hash] Environment metadata
+      def collect_environment
+        {
+          cluster: ENV.fetch('AGENT_CLUSTER', nil),
+          namespace: ENV.fetch('AGENT_NAMESPACE', ENV.fetch('KUBERNETES_NAMESPACE', nil)),
+          workspace_path: @agent.workspace_path,
+          kubernetes_enabled: !ENV.fetch('KUBERNETES_SERVICE_HOST', nil).nil?,
+          telemetry_enabled: !ENV.fetch('OTEL_EXPORTER_OTLP_ENDPOINT', nil).nil?
+        }
+      end
+
+      # Collect operational state information
+      #
+      # @return [Hash] Operational metadata
+      def collect_operational
+        status = determine_agent_status
+
+        {
+          status: status,
+          ready: status == 'ready',
+          mode: @agent.mode,
+          workspace: {
+            path: @agent.workspace_path,
+            available: @agent.workspace_available?,
+            writable: workspace_writable?
+          }
+        }
+      end
+
+      # Collect agent capabilities and constraints
+      #
+      # @return [Hash] Capabilities metadata
+      def collect_capabilities
+        config = @agent.config || {}
+        
+        # Extract MCP server tools if available
+        tools = []
+        if @agent.respond_to?(:servers_info)
+          @agent.servers_info.each do |server|
+            tools << {
+              server: server[:name],
+              tool_count: server[:tool_count] || 0
+            }
+          end
+        end
+
+        # Extract constraints if configured
+        constraints = config.dig('constraints') || {}
+
+        {
+          tools: tools,
+          total_tools: tools.sum { |t| t[:tool_count] },
+          constraints: constraints.empty? ? nil : constraints,
+          llm_provider: config.dig('llm', 'provider') || ENV.fetch('LLM_PROVIDER', 'unknown'),
+          llm_model: config.dig('llm', 'model') || ENV.fetch('MODEL', 'unknown')
+        }
+      end
+
+      # Get formatted summary suitable for system prompts
+      #
+      # @return [Hash] Formatted summary for prompt injection
+      def summary_for_prompt
+        metadata = collect
+        identity = metadata[:identity]
+        runtime = metadata[:runtime]
+        environment = metadata[:environment]
+        operational = metadata[:operational]
+        capabilities = metadata[:capabilities]
+
+        {
+          agent_name: identity[:name],
+          agent_description: identity[:description],
+          agent_mode: identity[:mode],
+          uptime: runtime[:uptime],
+          cluster: environment[:cluster],
+          namespace: environment[:namespace],
+          status: operational[:status],
+          workspace_available: operational[:ready],
+          tool_count: capabilities[:total_tools],
+          llm_model: capabilities[:llm_model]
+        }
+      end
+
+      private
+
+      def logger_component
+        'Agent::MetadataCollector'
+      end
+
+      # Calculate human-readable uptime
+      #
+      # @return [String] Formatted uptime string
+      def calculate_uptime
+        seconds = Time.now - @start_time
+        return 'just started' if seconds < 60
+
+        minutes = (seconds / 60).floor
+        hours = (minutes / 60).floor
+        days = (hours / 24).floor
+
+        if days > 0
+          "#{days}d #{hours % 24}h #{minutes % 60}m"
+        elsif hours > 0
+          "#{hours}h #{minutes % 60}m"
+        else
+          "#{minutes}m"
+        end
+      end
+
+      # Determine current agent status
+      #
+      # @return [String] Status string
+      def determine_agent_status
+        return 'not_ready' unless @agent.workspace_available?
+        return 'starting' if calculate_uptime == 'just started'
+        
+        # Check if agent is connected and functional
+        if @agent.respond_to?(:servers_info) && @agent.servers_info.any?
+          'ready'
+        elsif @agent.respond_to?(:servers_info) && @agent.servers_info.empty?
+          'ready_no_tools'
+        else
+          'ready'
+        end
+      end
+
+      # Check if workspace is writable
+      #
+      # @return [Boolean] True if workspace is writable
+      def workspace_writable?
+        return false unless @agent.workspace_available?
+        
+        test_file = File.join(@agent.workspace_path, '.write_test')
+        File.write(test_file, 'test')
+        File.delete(test_file)
+        true
+      rescue StandardError
+        false
+      end
+    end
+  end
+end