language-operator 0.1.70 → 0.1.71

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6a8a654ac7b3fea9f1d176029ba86153b44cc746dacb8173054c6c2e0740def
-  data.tar.gz: d67180ae9aa7e99ad55b0764936028348039359367320a7e76afad95d5cd84a6
+  metadata.gz: 11da2ddaf7396a49d94451edc45cd07a05b8ac2d9239b587f46cf7b5a938714f
+  data.tar.gz: 998d0061d7a4a7fee8a61de4b034766bceb4421363cf177b4e6e38ada37c04b0
 SHA512:
-  metadata.gz: 7244d148d067fb2733a23c193c499bb13bc336891cdd5fbbb932cc1ecf40111cf2bfb8f3e25ac9cd290b655915a3e2ab5e3c88bfb133063ba47991835d7e485e
-  data.tar.gz: d11fa46700dd377f76804c3808848b4ee321982db18c25611834b660c60babbffb80fbcfe26abc8e32d21e01b26776fdb97f699b7e769d6a7a2337fadea591ba
+  metadata.gz: 44f424c8f7ff4a5d147f86027a7e68e4bfacbda5ed3a0747793c35e5967d58e339b001dc421eb3826c6d1cd359343fc74ea9de96cc0e1d5eeefd45d101ca3d1e
+  data.tar.gz: b74bcaf2d2762cccb6c282041b3cd40d6c1ffd6635dfc1920855f68ffbf9bbe8c46e5e8bb052e77d4807d0ba2c28eaf92b516649be4891cd64ca1a04ceaf476f

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    language-operator (0.1.70)
+    language-operator (0.1.71)
       faraday (~> 2.0)
       json-schema (~> 5.0)
       k8s-ruby (~> 0.17)

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

@@ -26,27 +26,15 @@ require 'language_operator'
 # Define an agent with chat endpoint capabilities
 LanguageOperator::Dsl.define do
   agent "github-expert" do
-    description "GitHub API and workflow expert"
+    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
 
-    # This is the key - expose the agent 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
-
-      # Configure the endpoint parameters
-      model "github-expert-v1"  # Model name returned in API responses
-      temperature 0.7           # Balanced creativity and consistency
-      max_tokens 2000           # Limit response length
-    end
+    # 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

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