language-operator 0.1.61 → 0.1.62

data/docs/quickstart.md

@@ -0,0 +1,299 @@
+# Quickstart Guide
+
+Get your first Language Operator agent running in 5 minutes.
+
+## Before You Begin
+
+- Install aictl: `gem install language-operator`
+- Have Kubernetes cluster access
+- Set up API keys for your preferred LLM provider
+
+## Step 1: Initial Setup
+
+Run the interactive setup wizard:
+
+```bash
+aictl quickstart
+```
+
+The wizard will guide you through:
+1. Cluster configuration
+2. Language Operator installation
+3. Model setup (OpenAI, Anthropic, or local)
+4. Creating your first agent
+
+## Step 2: Manual Setup (Alternative)
+
+If you prefer step-by-step setup:
+
+### Configure Your Cluster
+
+```bash
+# Create cluster configuration
+aictl cluster create my-cluster
+
+# Switch to it
+aictl use my-cluster
+
+# Check connectivity
+aictl status
+```
+
+### Install Language Operator
+
+```bash
+aictl install
+```
+
+Wait for installation to complete, then verify:
+
+```bash
+aictl status
+```
+
+### Create a Model
+
+```bash
+# For OpenAI (set OPENAI_API_KEY first)
+aictl model create gpt4 --provider openai --model gpt-4-turbo
+
+# For Anthropic (set ANTHROPIC_API_KEY first)  
+aictl model create claude --provider anthropic --model claude-3-sonnet
+
+# Verify model
+aictl model list
+```
+
+## Step 3: Create Your First Agent
+
+### Simple Scheduled Agent
+
+Create an agent that runs daily:
+
+```bash
+aictl agent create daily-reporter
+```
+
+You'll be prompted to describe what the agent should do. Try:
+> "Generate a daily summary of system status and send it via email"
+
+### Check Agent Status
+
+```bash
+# List all agents
+aictl agent list
+
+# Get detailed info
+aictl agent inspect daily-reporter
+
+# View logs
+aictl agent logs daily-reporter -f
+```
+
+## Step 4: Understanding What Was Created
+
+### View Generated Code
+
+```bash
+# Open agent workspace
+aictl agent workspace daily-reporter
+```
+
+This shows the synthesized agent definition that Language Operator created from your description.
+
+### Example Generated Agent
+
+```ruby
+agent "daily-reporter" do
+  description "Generate a daily summary of system status and send it via email"
+  
+  mode :scheduled
+  schedule "0 8 * * *"  # 8 AM daily
+  
+  task :collect_system_status do |inputs|
+    # AI-synthesized task to gather system information
+    { status: "healthy", uptime: "99.9%", alerts: [] }
+  end
+  
+  task :generate_report do |inputs|
+    # AI-synthesized task to create report
+    status = inputs[:status]
+    { report: "Daily Status: #{status}" }
+  end
+  
+  main do |inputs|
+    status = collect_system_status
+    report = generate_report(status)
+    report
+  end
+  
+  output do |outputs|
+    # AI-synthesized output handling
+    puts "Report generated: #{outputs[:report]}"
+  end
+  
+  constraints do
+    timeout "10m"
+    daily_budget 100  # $1.00 max per day
+  end
+end
+```
+
+## Step 5: Experiment with Different Agent Types
+
+### Webhook Agent
+
+Create an agent that responds to GitHub webhooks:
+
+```bash
+aictl agent create github-responder
+```
+
+Description: "Respond to GitHub pull request webhooks with automated code reviews"
+
+### Chat Agent  
+
+Create a conversational agent:
+
+```bash
+aictl agent create support-bot
+```
+
+Description: "Provide customer support through a chat interface"
+
+### Autonomous Agent
+
+Create an agent that runs continuously:
+
+```bash
+aictl agent create system-monitor
+```
+
+Description: "Continuously monitor system health and alert on issues"
+
+## Step 6: Monitor and Manage
+
+### View All Agents
+
+```bash
+aictl agent list
+```
+
+### Check Agent Logs
+
+```bash
+# Follow logs in real-time
+aictl agent logs daily-reporter -f
+
+# View recent logs
+aictl agent logs daily-reporter --since 1h
+```
+
+### Monitoring Agents
+
+Monitor your agent's execution and performance:
+
+```bash
+# View detailed agent information
+aictl agent inspect daily-reporter
+
+# Check recent execution logs
+aictl agent logs daily-reporter --since 1h
+```
+
+## Common Patterns
+
+### Scheduled Reporting
+
+```ruby
+agent "weekly-metrics" do
+  description "Generate weekly performance metrics"
+  schedule "0 9 * * 1"  # Mondays at 9 AM
+  
+  # Tasks will be synthesized based on description
+end
+```
+
+### Event Response
+
+```ruby
+agent "incident-responder" do  
+  description "Respond to system incidents"
+  mode :reactive
+  
+  webhook "/alerts/critical" do
+    method :post
+  end
+end
+```
+
+### Continuous Monitoring
+
+```ruby
+agent "health-monitor" do
+  description "Monitor application health continuously"
+  mode :autonomous
+  
+  constraints do
+    requests_per_minute 2
+    daily_budget 500  # $5 max per day
+  end
+end
+```
+
+## Troubleshooting
+
+### Agent Not Starting
+
+```bash
+# Check agent status
+aictl agent inspect my-agent
+
+# View detailed logs
+aictl agent logs my-agent
+
+# Check cluster status
+aictl status
+```
+
+### High Costs
+
+Agents use LLM APIs which have costs. Monitor usage:
+
+```bash
+# Check agent configuration
+aictl agent inspect my-agent
+
+# Look for budget constraints
+# Adjust constraints if needed
+```
+
+### Connection Issues
+
+```bash
+# Test cluster connectivity
+kubectl get nodes
+
+# Check Language Operator status
+kubectl get pods -n language-operator
+
+# Verify model connectivity
+aictl model test my-model
+```
+
+## Next Steps
+
+Now that you have a working agent:
+
+1. **[How Agents Work](how-agents-work.md)** - Understand the synthesis process
+2. **[Understanding Generated Code](understanding-generated-code.md)** - Learn to read agent definitions
+3. **[Using Tools](using-tools.md)** - Connect agents to external services
+4. **[Constraints](constraints.md)** - Control costs and behavior
+5. **[Best Practices](best-practices.md)** - Production deployment patterns
+
+## Getting Help
+
+- View command help: `aictl --help`
+- Check specific commands: `aictl agent --help`
+- Report issues: [GitHub Issues](https://github.com/language-operator/language-operator-gem/issues)
+- Join discussions: [GitHub Discussions](https://github.com/language-operator/language-operator/discussions)

data/docs/understanding-generated-code.md

@@ -0,0 +1,265 @@
+# Understanding Generated Code
+
+When you create an agent with Language Operator, it generates Ruby code that defines how your agent works. This guide helps you read and understand that generated code.
+
+## Agent Structure Overview
+
+Every synthesized agent has this basic structure:
+
+```ruby
+agent "my-agent" do
+  # Agent metadata
+  description "What this agent does"
+  mode :scheduled
+  schedule "0 9 * * *"  # 9 AM daily
+  
+  # Task definitions (work units)
+  task :task_name,
+    instructions: "what to do",
+    inputs: { param: 'type' },
+    outputs: { result: 'type' }
+  
+  # Main execution logic
+  main do |inputs|
+    result = execute_task(:task_name, inputs: inputs)
+    result
+  end
+  
+  # Output handling
+  output do |outputs|
+    # What to do with results
+  end
+  
+  # Optional constraints
+  constraints do
+    timeout "10m"
+    daily_budget 5.00
+  end
+end
+```
+
+## Agent Metadata
+
+### Description
+Plain English description of what the agent does:
+
+```ruby
+description "Monitors GitHub issues and alerts on critical bugs"
+```
+
+### Execution Mode
+How the agent is triggered:
+
+```ruby
+mode :scheduled    # Runs on a schedule
+mode :autonomous   # Runs continuously  
+mode :reactive     # Responds to webhooks/events
+```
+
+### Schedule (for scheduled agents)
+Cron expression defining when to run:
+
+```ruby
+schedule "0 9 * * *"      # 9 AM daily
+schedule "*/15 * * * *"   # Every 15 minutes
+schedule "0 0 * * 1"      # Every Monday at midnight
+```
+
+## Task Definitions
+
+Tasks are individual work units with clear contracts. They come in two types:
+
+### Task Definitions
+
+Tasks are Ruby blocks that process inputs and return outputs:
+
+```ruby
+task :analyze_logs do |inputs|
+  # Task implementation - this can be:
+  # 1. Simple Ruby code
+  # 2. Calls to AI for complex reasoning
+  # 3. MCP tool usage (when available)
+  
+  logs = inputs[:logs] || []
+  critical_issues = logs.select { |log| log[:level] == 'ERROR' }
+  
+  {
+    critical_issues: critical_issues,
+    summary: "Found #{critical_issues.length} critical issues"
+  }
+end
+```
+
+**Key parts:**
+- Task name (`:analyze_logs`)
+- Input parameter (`inputs` hash)
+- Ruby block with implementation
+- Return value (hash with results)
+
+### Task Evolution
+
+Tasks can evolve from simple implementations to more sophisticated ones:
+
+```ruby
+# Simple implementation
+task :fetch_recent_logs do |inputs|
+  hours = inputs[:hours] || 24
+  since_time = Time.now - (hours * 3600)
+  
+  # In a real implementation, this might call MCP tools
+  # or use AI synthesis for complex queries
+  { logs: [], since: since_time }
+end
+```
+
+## Main Logic
+
+The `main` block coordinates task execution and defines the agent's workflow:
+
+```ruby
+main do |inputs|
+  # Task execution - tasks are called as methods
+  logs = fetch_recent_logs(hours: 24)
+  analysis = analyze_logs(logs: logs[:logs])
+  
+  # Conditional logic
+  if analysis[:critical_issues].any?
+    send_alert(analysis)
+  end
+  
+  # Return final result
+  analysis
+end
+```
+
+**Important concepts:**
+- Tasks are called as method names
+- Task results are returned as hashes
+- Standard Ruby control flow (if/else, loops, variables)
+- The return value becomes the agent's output
+- Tasks can be chained together
+
+## Output Handling
+
+Defines what happens with the agent's final result:
+
+### Neural Output
+```ruby
+output instructions: "send results to team via Slack"
+```
+
+### Symbolic Output
+```ruby
+output do |outputs|
+  execute_tool('slack', 'post_message', {
+    channel: '#alerts',
+    text: "Found #{outputs[:critical_issues].length} critical issues"
+  })
+end
+```
+
+## Type System
+
+Tasks use a simple type system for validation:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `'string'` | Text data | `"hello world"` |
+| `'integer'` | Whole numbers | `42` |
+| `'number'` | Any number | `3.14` |
+| `'boolean'` | True/false | `true` |
+| `'array'` | List of items | `[1, 2, 3]` |
+| `'hash'` | Key-value pairs | `{name: "Alice"}` |
+| `'any'` | Any data type | anything |
+
+## Constraints
+
+Optional limits on agent behavior:
+
+```ruby
+constraints do
+  timeout "30m"           # Maximum execution time
+  max_iterations 100      # For autonomous agents
+  daily_budget 10.00      # Maximum cost per day
+  memory_limit "512Mi"    # Memory usage limit
+end
+```
+
+## Learning Progression Example
+
+Here's how a task evolves over time:
+
+### Initially (Neural)
+```ruby
+task :calculate_metrics,
+  instructions: "calculate average response time and error rate from logs",
+  inputs: { logs: 'array' },
+  outputs: { avg_response_time: 'number', error_rate: 'number' }
+```
+
+### After Learning (Symbolic)
+```ruby
+task :calculate_metrics,
+  inputs: { logs: 'array' },
+  outputs: { avg_response_time: 'number', error_rate: 'number' }
+do |inputs|
+  response_times = inputs[:logs].map { |log| log['response_time'] }.compact
+  total_requests = inputs[:logs].length
+  error_count = inputs[:logs].count { |log| log['status'] >= 400 }
+  
+  {
+    avg_response_time: response_times.sum / response_times.length.to_f,
+    error_rate: (error_count / total_requests.to_f) * 100
+  }
+end
+```
+
+## Common Patterns
+
+### Error Handling
+```ruby
+main do |inputs|
+  begin
+    result = execute_task(:risky_operation, inputs: inputs)
+    result
+  rescue => e
+    { error: e.message, success: false }
+  end
+end
+```
+
+### Conditional Execution
+```ruby
+main do |inputs|
+  data = execute_task(:fetch_data, inputs: inputs)
+  
+  if data[:records].any?
+    execute_task(:process_records, inputs: data)
+  else
+    { message: "No records to process" }
+  end
+end
+```
+
+### Parallel Task Execution
+```ruby
+main do |inputs|
+  # Run multiple tasks in parallel
+  results = execute_parallel([
+    { name: :fetch_source1 },
+    { name: :fetch_source2 }
+  ])
+  
+  # Merge results
+  execute_task(:merge_data, inputs: { 
+    source1: results[0], 
+    source2: results[1] 
+  })
+end
+```
+
+## Next Steps
+
+- **[How Agents Work](how-agents-work.md)** - Understanding the synthesis process
+- **[Agent Optimization](agent-optimization.md)** - How learning improves performance
+- **[Using Tools](using-tools.md)** - How agents interact with external services