language-operator 0.1.67 → 0.1.71

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 189b6f8a2bcc795cbc29f0830bf31d6ce51e483ec2e6bb2fc42d43d79292db87
-  data.tar.gz: 0eb8429834de65902c51157eb2bfcf2eb8bc0d79937c8567110b2b60700a69e0
+  metadata.gz: 11da2ddaf7396a49d94451edc45cd07a05b8ac2d9239b587f46cf7b5a938714f
+  data.tar.gz: 998d0061d7a4a7fee8a61de4b034766bceb4421363cf177b4e6e38ada37c04b0
 SHA512:
-  metadata.gz: 0e7a055a00b4b5cd37c3a157f396b1d91daa863b0ce7857f12339f6d6ac30dd9bfff419abc8076d1434dd8ff736e68bef7302ce46f41f401be5d9c3ddc0b9bbe
-  data.tar.gz: 538c6d8df05f4a665b6a6bebaef5bd94933edf3c91eaf73c01739eaa0ba05fb9336b2659741250cdc9f2c4d75d554addf708d081fb8049a40679979eda67565c
+  metadata.gz: 44f424c8f7ff4a5d147f86027a7e68e4bfacbda5ed3a0747793c35e5967d58e339b001dc421eb3826c6d1cd359343fc74ea9de96cc0e1d5eeefd45d101ca3d1e
+  data.tar.gz: b74bcaf2d2762cccb6c282041b3cd40d6c1ffd6635dfc1920855f68ffbf9bbe8c46e5e8bb052e77d4807d0ba2c28eaf92b516649be4891cd64ca1a04ceaf476f

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    language-operator (0.1.67)
+    language-operator (0.1.71)
       faraday (~> 2.0)
+      json-schema (~> 5.0)
       k8s-ruby (~> 0.17)
       lru_redux (~> 1.1)
       mcp (~> 0.4)
@@ -27,14 +28,14 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
     benchmark (0.5.0)
     bigdecimal (3.3.1)
     coderay (1.1.3)
-    concurrent-ruby (1.3.5)
+    concurrent-ruby (1.3.6)
     crack (1.0.1)
       bigdecimal
       rexml
@@ -72,24 +73,24 @@ GEM
       logger
     faraday-multipart (1.1.1)
       multipart-post (~> 2.0)
-    faraday-net_http (3.4.1)
-      net-http (>= 0.5.0)
+    faraday-net_http (3.4.2)
+      net-http (~> 0.5)
     faraday-retry (2.3.2)
       faraday (~> 2.0)
-    google-protobuf (4.33.0)
+    google-protobuf (4.33.2)
       bigdecimal
       rake (>= 13)
-    google-protobuf (4.33.0-x86_64-linux-gnu)
+    google-protobuf (4.33.2-x86_64-linux-gnu)
       bigdecimal
       rake (>= 13)
     googleapis-common-protos-types (1.22.0)
       google-protobuf (~> 4.26)
     hashdiff (1.2.1)
     http-2 (1.1.1)
-    httpx (1.6.3)
+    httpx (1.7.0)
       http-2 (>= 1.0.0)
     ice_nine (0.11.2)
-    json (2.15.2)
+    json (2.18.0)
     json-schema (5.2.2)
       addressable (~> 2.8)
       bigdecimal (~> 3.1)
@@ -117,10 +118,10 @@ GEM
       json_rpc_handler (~> 0.1)
     memory_profiler (1.1.0)
     method_source (1.1.0)
-    multi_json (1.17.0)
+    multi_json (1.18.0)
     multipart-post (2.4.1)
-    net-http (0.7.0)
-      uri
+    net-http (0.9.1)
+      uri (>= 0.11.1)
     nio4r (2.7.5)
     opentelemetry-api (1.7.0)
     opentelemetry-common (0.23.0)
@@ -136,7 +137,7 @@ GEM
       opentelemetry-api (~> 1.7)
       opentelemetry-common (~> 0.21)
       opentelemetry-registry (~> 0.1)
-    opentelemetry-instrumentation-http (0.27.0)
+    opentelemetry-instrumentation-http (0.27.1)
       opentelemetry-instrumentation-base (~> 0.25)
     opentelemetry-instrumentation-rack (0.29.0)
       opentelemetry-instrumentation-base (~> 0.25)
@@ -158,18 +159,18 @@ GEM
       racc
     pastel (0.8.0)
       tty-color (~> 0.5)
-    prism (1.6.0)
+    prism (1.7.0)
     pry (0.15.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    public_suffix (6.0.2)
+    public_suffix (7.0.0)
     puma (6.6.1)
       nio4r (~> 2.0)
     racc (1.8.1)
     rack (3.2.4)
     rack-test (2.2.0)
       rack (>= 1.3)
-    rackup (2.2.1)
+    rackup (2.3.1)
       rack (>= 3)
     rainbow (3.1.1)
     rake (13.3.1)
@@ -191,7 +192,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.6)
-    rubocop (1.81.7)
+    rubocop (1.82.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -199,10 +200,10 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.47.1, < 2.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.1)
+    rubocop-ast (1.48.0)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-performance (1.26.1)
@@ -220,12 +221,12 @@ GEM
       marcel (~> 1.0)
       ruby_llm-schema (~> 0.2.1)
       zeitwerk (~> 2)
-    ruby_llm-mcp (0.7.0)
+    ruby_llm-mcp (0.8.0)
       httpx (~> 1.4)
       json-schema (~> 5.0)
       ruby_llm (~> 1.9)
       zeitwerk (~> 2)
-    ruby_llm-schema (0.2.1)
+    ruby_llm-schema (0.2.5)
     strings (0.2.1)
       strings-ansi (~> 0.2)
       unicode-display_width (>= 1.5, < 3.0)
@@ -262,8 +263,8 @@ GEM
     wisper (2.0.1)
     yajl-ruby (1.4.3)
     yaml-safe_load_stream3 (0.1.2)
-    yard (0.9.37)
-    zeitwerk (2.7.3)
+    yard (0.9.38)
+    zeitwerk (2.7.4)
 
 PLATFORMS
   ruby

data/components/agent/Gemfile

@@ -2,7 +2,7 @@
 
 source 'https://rubygems.org'
 
-gem 'language-operator', '~> 0.1.66'
+gem 'language-operator', '~> 0.1.70'
 
 # Agent-specific dependencies for autonomous execution
 gem 'concurrent-ruby', '~> 1.3'

data/docs/persona-driven-system-prompts.md

@@ -0,0 +1,346 @@
+# Persona-Driven System Prompts
+
+Language Operator v0.1.71+ introduces **persona-driven system prompts** that transform agents from generic chatbots into context-aware entities with deep understanding of their identity, role, environment, and operational state.
+
+## Overview
+
+Traditional AI agents respond with generic outputs lacking awareness of their purpose or context. With persona-driven prompts, agents become intelligent entities that:
+
+- **Know their identity**: Name, role, and specific purpose
+- **Understand their environment**: Cluster, namespace, operational mode  
+- **Track operational state**: Uptime, status, capabilities, tools available
+- **Provide contextual responses**: References to their actual function and situation
+
+## Quick Example
+
+**Before (Generic Response):**
+```
+User: "hello" 
+Agent: "Hello! How can I assist you today?"
+```
+
+**After (Identity-Aware Response):**
+```
+User: "hello"
+Agent: "Hello! I'm say-something, running in the code-games cluster. 
+       I've been active for 3 hours now, helping log interesting messages 
+       and interactions. How can I assist you today?"
+```
+
+## Configuration
+
+### Basic Usage
+
+Enable identity awareness in your chat endpoint:
+
+```ruby
+agent "support-bot" do
+  description "Customer support assistant"
+  mode :reactive
+
+  as_chat_endpoint do
+    system_prompt "You are a helpful customer support assistant"
+    
+    # Enable persona-driven prompts
+    identity_awareness do
+      enabled true
+      prompt_template :standard
+      context_injection :standard
+    end
+  end
+end
+```
+
+### Template Levels
+
+Choose how much context to inject into system prompts:
+
+#### `:minimal` - Basic Identity Only
+```ruby
+identity_awareness do
+  enabled true
+  prompt_template :minimal
+end
+```
+
+**Generated prompt includes:**
+- Agent name and cluster location
+- Basic operational status
+
+#### `:standard` - Balanced Context (Default)
+```ruby
+identity_awareness do
+  enabled true
+  prompt_template :standard  # Default
+end
+```
+
+**Generated prompt includes:**
+- Agent identity (name, role, mode)
+- Basic operational context (uptime, cluster, status)
+- Behavioral guidelines
+
+#### `:detailed` - Full Context with Capabilities
+```ruby
+identity_awareness do
+  enabled true
+  prompt_template :detailed
+end
+```
+
+**Generated prompt includes:**
+- Complete identity and operational context
+- Available tools and capabilities
+- Workspace status and environment details
+- Detailed behavioral guidelines
+
+#### `:comprehensive` - Maximum Context
+```ruby
+identity_awareness do
+  enabled true
+  prompt_template :comprehensive
+end
+```
+
+**Generated prompt includes:**
+- All available metadata
+- Environment specifications
+- Complete capability listing
+- Full behavioral framework
+
+### Context Injection Levels
+
+Control how much operational context appears in ongoing conversations:
+
+```ruby
+identity_awareness do
+  enabled true
+  context_injection :standard  # Options: :none, :minimal, :standard, :detailed
+end
+```
+
+- **`:none`** - No conversation context injection
+- **`:minimal`** - Basic status only
+- **`:standard`** - Agent name, mode, uptime, status
+- **`:detailed`** - Full operational metrics
+
+## Implementation Details
+
+### Architecture
+
+The persona-driven prompt system consists of:
+
+1. **MetadataCollector** - Gathers agent runtime and configuration data
+2. **PromptBuilder** - Generates dynamic prompts from templates and metadata  
+3. **ChatEndpointDefinition** - Enhanced with identity awareness configuration
+4. **WebServer** - Integrates dynamic prompts into conversation handling
+
+### Available Metadata
+
+Agents can access the following runtime information:
+
+```ruby
+{
+  identity: {
+    name: "support-bot",
+    description: "Customer support assistant", 
+    persona: "helpful-assistant",
+    mode: "reactive",
+    version: "0.1.71"
+  },
+  runtime: {
+    uptime: "3h 45m",
+    started_at: "2024-01-15T10:30:00Z",
+    workspace_available: true,
+    mcp_servers_connected: 2
+  },
+  environment: {
+    cluster: "production", 
+    namespace: "support",
+    kubernetes_enabled: true,
+    telemetry_enabled: true
+  },
+  operational: {
+    status: "ready",
+    ready: true,
+    mode: "reactive"
+  },
+  capabilities: {
+    total_tools: 5,
+    tools: [
+      { server: "github-tools", tool_count: 3 },
+      { server: "slack-tools", tool_count: 2 }
+    ],
+    llm_provider: "anthropic",
+    llm_model: "claude-3-haiku"
+  }
+}
+```
+
+## Migration Guide
+
+### Existing Agents
+
+Persona-driven prompts are **backward compatible**. Existing agents continue working without changes.
+
+To enable for existing agents:
+
+```ruby
+# Before
+as_chat_endpoint do
+  system_prompt "You are a GitHub expert"
+  temperature 0.7
+end
+
+# After - Add identity awareness
+as_chat_endpoint do
+  system_prompt "You are a GitHub expert"
+  
+  identity_awareness do
+    enabled true          # Enable the feature
+    prompt_template :standard
+    context_injection :standard  
+  end
+  
+  temperature 0.7
+end
+```
+
+### Gradual Adoption
+
+1. **Start with `:minimal`** template to test basic identity awareness
+2. **Upgrade to `:standard`** for balanced context
+3. **Use `:detailed`** for rich conversational experiences
+4. **Apply `:comprehensive`** only when maximum context is needed
+
+### Disabling Features
+
+```ruby
+# Disable completely
+identity_awareness do
+  enabled false
+end
+
+# Disable conversation context only  
+identity_awareness do
+  enabled true
+  prompt_template :standard
+  context_injection :none
+end
+```
+
+## Best Practices
+
+### Template Selection
+
+- **Customer-facing agents**: Use `:standard` or `:detailed`
+- **Internal tools**: Use `:detailed` or `:comprehensive`  
+- **Simple utilities**: Use `:minimal`
+- **Legacy compatibility**: Use `enabled false`
+
+### Performance Considerations
+
+- Metadata collection is lightweight but cached
+- Higher template levels increase token usage
+- Context injection adds minimal overhead
+- Templates are generated once per conversation
+
+### Security
+
+- No sensitive information (secrets, keys) included in prompts
+- Environment details are cluster/namespace level only
+- PII detection prevents accidental exposure
+
+## Examples
+
+### Complete Identity-Aware Agent
+
+```ruby
+LanguageOperator::Dsl.define do
+  agent "customer-support" do
+    description "24/7 customer support specialist for SaaS platform"
+    mode :reactive
+
+    as_chat_endpoint do
+      system_prompt <<~PROMPT
+        You are a knowledgeable customer support specialist with expertise in:
+        - Account management and billing
+        - Product features and troubleshooting  
+        - Technical documentation and guides
+        
+        Provide helpful, accurate, and empathetic support to customers.
+      PROMPT
+
+      identity_awareness do
+        enabled true
+        prompt_template :detailed
+        context_injection :standard
+      end
+
+      model "customer-support-v1"
+      temperature 0.7
+      max_tokens 2000
+    end
+
+    constraints do
+      requests_per_minute 30
+      daily_budget 1000
+    end
+  end
+end
+```
+
+### Development vs Production Templates
+
+```ruby
+# Development - comprehensive context for debugging
+identity_awareness do
+  enabled true
+  prompt_template :comprehensive
+  context_injection :detailed
+end
+
+# Production - balanced context for performance
+identity_awareness do
+  enabled true  
+  prompt_template :standard
+  context_injection :standard
+end
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Agent still gives generic responses:**
+- Verify `enabled true` in identity_awareness block
+- Check agent has proper name and description
+- Ensure cluster environment variables are set
+
+**Prompts too long/expensive:**
+- Reduce template level (`:detailed` → `:standard` → `:minimal`)
+- Disable context injection (`:none`)
+
+**Missing environment context:**
+- Verify Kubernetes environment variables
+- Check cluster and namespace configuration
+- Ensure agent has proper metadata access
+
+### Debug Information
+
+Enable debug logging to see generated prompts:
+
+```bash
+DEBUG=true ruby examples/identity_aware_chat_agent.rb
+```
+
+## API Reference
+
+See the complete API documentation:
+- [`ChatEndpointDefinition`](api/chat-endpoint-definition.md)
+- [`MetadataCollector`](api/metadata-collector.md) 
+- [`PromptBuilder`](api/prompt-builder.md)
+
+---
+
+**Next Steps:** Try the [identity-aware chat agent example](../examples/identity_aware_chat_agent.rb) to see persona-driven prompts in action.

data/examples/basic_agent_with_default_chat.rb

@@ -0,0 +1,99 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Basic Agent with Default Chat Endpoint
+#
+# This example demonstrates that agents automatically expose chat endpoints
+# without explicitly defining them via as_chat_endpoint.
+#
+# This agent:
+# - Runs autonomous work (logging every 10 seconds)  
+# - Automatically exposes chat endpoint at /v1/chat/completions
+# - No explicit as_chat_endpoint block needed!
+#
+# Usage:
+#   ruby examples/basic_agent_with_default_chat.rb
+#
+# Test default chat endpoint:
+#   curl -X POST http://localhost:8080/v1/chat/completions \
+#     -H "Content-Type: application/json" \
+#     -d '{
+#       "model": "basic-worker",
+#       "messages": [
+#         {"role": "user", "content": "What are you doing right now?"}
+#       ]
+#     }'
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'language_operator'
+
+# Define a basic agent - NO explicit chat endpoint!
+agent "basic-worker" do
+  description "Simple worker that performs basic tasks"
+  mode :autonomous
+
+  # Simple main loop - this is the autonomous work
+  task :do_work,
+    instructions: "Perform some basic work and log progress",
+    inputs: {},
+    outputs: { 
+      work_done: 'boolean',
+      message: 'string',
+      timestamp: 'string'
+    }
+
+  main do |inputs|
+    puts "🔨 Performing autonomous work..."
+    
+    # Execute the work task
+    work_result = execute_task(:do_work)
+    
+    puts "✅ Work completed: #{work_result[:message]}"
+    puts "😴 Sleeping for 10 seconds..."
+    
+    sleep 10
+    
+    work_result
+  end
+
+  # Basic constraints
+  constraints do
+    max_iterations 999999
+    timeout '30s'
+  end
+end
+
+# Start the agent
+if __FILE__ == $PROGRAM_NAME
+  puts "🚀 Starting Basic Agent with Default Chat Endpoint"
+  puts ""
+  puts "This agent demonstrates automatic chat endpoint creation:"
+  puts "  ✅ Runs autonomous work every 10 seconds" 
+  puts "  ✅ Automatically exposes chat at /v1/chat/completions"
+  puts "  ✅ No explicit as_chat_endpoint block needed!"
+  puts ""
+  puts "Agent info:"
+  puts "  Name: basic-worker"
+  puts "  Description: Simple worker that performs basic tasks"
+  puts "  Mode: autonomous"
+  puts ""
+  puts "Available endpoints (auto-generated):"
+  puts "  POST /v1/chat/completions - Chat with basic-worker"
+  puts "  GET  /v1/models          - 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": "basic-worker", "messages": [{"role": "user", "content": "What are you doing?"}]}\''
+  puts ""
+  puts "Expected system prompt (auto-generated):"
+  puts '"You are simple worker that performs basic tasks. Provide helpful assistance based on your capabilities."'
+  puts ""
+  puts "Press Ctrl+C to stop"
+  puts "=" * 80
+  
+  LanguageOperator::Agent.run
+end

data/examples/chat_endpoint_agent.rb

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Chat Endpoint Agent Example
+#
+# This example demonstrates how to create an agent that exposes 
+# an OpenAI-compatible chat completion endpoint.
+#
+# Usage:
+#   ruby examples/chat_endpoint_agent.rb
+#
+# Then test with 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 pull request?"}
+#       ]
+#     }'
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'language_operator'
+
+# Define an agent with chat endpoint capabilities
+LanguageOperator::Dsl.define do
+  agent "github-expert" do
+    description "You are a GitHub expert assistant with deep knowledge of GitHub API, workflows, pull requests, issues, code review, GitHub Actions, CI/CD, and repository management best practices"
+    mode :reactive
+
+    # Chat endpoint is automatic! No configuration needed.
+    # Every agent automatically gets:
+    # - OpenAI-compatible chat endpoint at /v1/chat/completions
+    # - Identity-aware responses with agent context
+    # - Operational state awareness (uptime, cluster, etc.)
+    # - Professional, contextual conversation style
+
+    # Optional: Add constraints for safety and cost management
+    constraints do
+      timeout '30s'
+      requests_per_minute 30
+      daily_budget 1000  # $10/day
+    end
+  end
+end
+
+# Start the agent
+if __FILE__ == $PROGRAM_NAME
+  puts "Starting GitHub Expert Chat Endpoint Agent..."
+  puts "Server will be available at http://localhost:8080"
+  puts ""
+  puts "Endpoints available:"
+  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 with curl:"
+  puts '  curl -X POST http://localhost:8080/v1/chat/completions \\'
+  puts '    -H "Content-Type: application/json" \\'
+  puts '    -d \'{"model": "github-expert-v1", "messages": [{"role": "user", "content": "How do I create a pull request?"}]}\''
+  puts ""
+  
+  LanguageOperator::Agent.run
+end