language-operator 0.1.61 → 0.1.62

data/docs/cli-reference.md

@@ -0,0 +1,274 @@
+# aictl CLI Reference
+
+Complete reference for the `aictl` command-line interface.
+
+## Global Commands
+
+### `aictl status`
+Show system status and overview of the current cluster.
+
+```bash
+aictl status
+```
+
+### `aictl version`
+Display aictl version and operator installation status.
+
+```bash
+aictl version
+```
+
+## Cluster Management
+
+### `aictl cluster`
+Manage Kubernetes clusters for Language Operator.
+
+```bash
+# Create a new cluster configuration
+aictl cluster create my-cluster
+
+# List configured clusters  
+aictl cluster list
+
+# Switch active cluster context
+aictl use my-cluster
+
+# Remove cluster configuration
+aictl cluster delete my-cluster
+```
+
+## Agent Management
+
+### `aictl agent`
+Create, deploy, and manage agents.
+
+```bash
+# Create a new agent
+aictl agent create my-agent
+
+# List agents in current cluster
+aictl agent list
+
+# Get detailed agent information
+aictl agent inspect my-agent
+
+# View agent logs
+aictl agent logs my-agent
+
+# Delete an agent
+aictl agent delete my-agent
+
+# Work with agent code
+aictl agent workspace my-agent
+```
+
+## Model Management
+
+### `aictl model`
+Manage language models in the cluster.
+
+```bash
+# Create a new model resource
+aictl model create
+
+# List available models
+aictl model list
+
+# Test model connectivity
+aictl model test my-model
+```
+
+## Persona Management
+
+### `aictl persona`
+Manage agent personas and system prompts.
+
+```bash
+# Create a new persona
+aictl persona create
+
+# List available personas
+aictl persona list
+
+# View persona details
+aictl persona inspect my-persona
+
+# Delete a persona
+aictl persona delete my-persona
+```
+
+## Tool Management
+
+### `aictl tool`
+Manage MCP tool servers.
+
+```bash
+# Deploy a tool server
+aictl tool deploy ./my-tool
+
+# List tool deployments
+aictl tool list
+
+# Test tool connectivity
+aictl tool test my-tool
+
+# View tool logs
+aictl tool logs my-tool
+
+# Search for tools
+aictl tool search database
+
+# Install a tool from registry
+aictl tool install calculator
+```
+
+## System Utilities
+
+### `aictl system`
+System-level operations and utilities.
+
+```bash
+# Validate system templates
+aictl system validate-template
+
+# Work with synthesis templates
+aictl system synthesis-template
+
+# Synthesize agent code
+aictl system synthesize
+
+# Execute system commands
+aictl system exec
+```
+
+## Setup and Installation
+
+### `aictl quickstart`
+Interactive wizard for first-time setup.
+
+```bash
+aictl quickstart
+```
+
+### `aictl install`
+Install Language Operator to a Kubernetes cluster.
+
+```bash
+aictl install
+```
+
+### `aictl upgrade`
+Upgrade Language Operator installation.
+
+```bash
+aictl upgrade
+```
+
+### `aictl uninstall`
+Remove Language Operator from cluster.
+
+```bash
+aictl uninstall
+```
+
+## Shell Completion
+
+### `aictl completion`
+Install shell completion for aictl.
+
+```bash
+# Bash completion
+aictl completion bash
+
+# Zsh completion  
+aictl completion zsh
+
+# Fish completion
+aictl completion fish
+```
+
+To install completion:
+
+```bash
+# Bash (add to ~/.bashrc)
+eval "$(aictl completion bash)"
+
+# Zsh (add to ~/.zshrc)  
+eval "$(aictl completion zsh)"
+
+# Fish
+aictl completion fish | source
+```
+
+## Common Workflows
+
+### Creating Your First Agent
+
+```bash
+# 1. Set up cluster
+aictl quickstart
+
+# 2. Create an agent
+aictl agent create my-agent
+
+# 3. Check status
+aictl agent list
+aictl agent inspect my-agent
+
+# 4. View logs
+aictl agent logs my-agent -f
+```
+
+### Working with Models
+
+```bash
+# 1. Create a model
+aictl model create
+
+# 2. Test connectivity
+aictl model test my-model
+
+# 3. List models
+aictl model list
+```
+
+### Tool Server Development
+
+```bash
+# 1. Deploy your tool
+aictl tool deploy ./my-custom-tools
+
+# 2. Test tool functionality
+aictl tool test my-custom-tools
+
+# 3. Monitor logs
+aictl tool logs my-custom-tools -f
+```
+
+## Environment Variables
+
+aictl respects these environment variables:
+
+- `KUBECONFIG` - Path to Kubernetes config file
+- `AICTL_CLUSTER` - Default cluster name
+- `AICTL_LOG_LEVEL` - Log level (debug, info, warn, error)
+- `NO_COLOR` - Disable colored output
+
+## Exit Codes
+
+- `0` - Success
+- `1` - General error
+- `2` - Configuration error
+- `3` - Connection error
+- `4` - Resource not found
+- `5` - Permission denied
+
+## Getting Help
+
+All commands support the `--help` flag for detailed usage:
+
+```bash
+aictl --help
+aictl agent --help
+aictl agent create --help
+```

data/docs/{dsl/constraints.md → constraints.md}

@@ -1,6 +1,6 @@
-# Constraints Reference
+# Agent Constraints Reference
 
-Complete reference for configuring agent constraints in the Language Operator DSL.
+Complete reference for configuring agent constraints to control behavior, resource usage, and costs.
 
 ## Table of Contents
 
@@ -665,7 +665,7 @@ end
 
 ## See Also
 
-- [Agent Reference](agent-reference.md) - Complete agent DSL reference
-- [Workflows](workflows.md) - Workflow definition guide
-- [Best Practices](best-practices.md) - Production deployment patterns
+- [Understanding Generated Code](understanding-generated-code.md) - Working with agent definitions
+- [Best Practices](best-practices.md) - Production deployment patterns  
 - [Webhooks](webhooks.md) - Reactive agent configuration
+- [CLI Reference](cli-reference.md) - Managing constraints via CLI

data/docs/how-agents-work.md

@@ -0,0 +1,156 @@
+# How Agents Work
+
+Language Operator transforms your natural language descriptions into working AI agents through a process called synthesis. This guide explains what happens when you create an agent.
+
+## The Agent Creation Process
+
+### 1. You Describe What You Want
+
+```bash
+aictl agent create daily-report
+# Interactive wizard asks:
+# - What should this agent do?
+# - When should it run?
+# - What tools does it need?
+```
+
+You describe your agent in plain English:
+- "Generate a daily sales report from our database"
+- "Respond to GitHub pull request webhooks with code reviews"  
+- "Monitor our API and alert on errors"
+
+### 2. Language Operator Synthesizes Code
+
+Behind the scenes, Language Operator creates a complete agent definition that includes:
+- **Tasks** - Individual work units with clear input/output contracts
+- **Main logic** - The execution flow that coordinates tasks
+- **Configuration** - Scheduling, constraints, and resource limits
+
+### 3. Your Agent Runs and Learns
+
+Initially, your agent uses AI to figure out how to accomplish tasks. Over time, it learns patterns and generates optimized code automatically.
+
+## Agent Structure
+
+When Language Operator synthesizes an agent, it creates code structured like this:
+
+### Tasks (Work Units)
+
+Each task has a clear contract defining what data goes in and what comes out:
+
+```ruby
+# A task that fetches sales data
+task :fetch_sales_data,
+  instructions: "get yesterday's sales from the database",
+  inputs: {},
+  outputs: { sales: 'array', total: 'number' }
+```
+
+### Main Logic (Coordination)
+
+The main block coordinates tasks and handles the overall flow:
+
+```ruby
+main do |inputs|
+  # Get the data
+  sales = execute_task(:fetch_sales_data)
+  
+  # Generate the report
+  report = execute_task(:generate_report, inputs: sales)
+  
+  # Return the result
+  report
+end
+```
+
+### Output Handling
+
+Defines what happens with the results:
+
+```ruby
+output do |outputs|
+  # Send the report via email
+  execute_tool('email', 'send', {
+    to: 'team@company.com',
+    subject: 'Daily Sales Report',
+    body: outputs[:report]
+  })
+end
+```
+
+## How Tasks Execute
+
+### Neural Tasks (AI-Powered)
+
+Initially, tasks use AI to figure out what to do:
+
+```ruby
+task :analyze_data,
+  instructions: "identify trends and anomalies in the sales data",
+  inputs: { data: 'array' },
+  outputs: { trends: 'array', anomalies: 'array' }
+
+# Language Operator uses AI to:
+# 1. Understand the instruction
+# 2. Call appropriate tools
+# 3. Process the results
+# 4. Return data matching the output schema
+```
+
+### Symbolic Tasks (Optimized Code)
+
+Over time, agents learn patterns and generate optimized code:
+
+```ruby
+task :analyze_data,
+  inputs: { data: 'array' },
+  outputs: { trends: 'array', anomalies: 'array' }
+do |inputs|
+  # Generated code based on learned patterns
+  trends = inputs[:data].group_by { |item| item[:category] }
+                        .map { |cat, items| { category: cat, total: items.sum { |i| i[:amount] } } }
+  
+  anomalies = inputs[:data].select { |item| item[:amount] > 10000 }
+  
+  { trends: trends, anomalies: anomalies }
+end
+```
+
+## Agent Lifecycle
+
+### Phase 1: Initial Synthesis
+- You describe what you want
+- Language Operator creates a working agent
+- All tasks start as neural (AI-powered)
+
+### Phase 2: Learning
+- Agent runs and accomplishes tasks using AI
+- Language Operator observes patterns in how tasks execute
+- System identifies opportunities for optimization
+
+### Phase 3: Optimization
+- Frequently-used patterns become optimized code
+- AI tasks gradually become efficient symbolic code
+- Performance improves and costs decrease
+
+### Phase 4: Continuous Improvement
+- Agent continues learning new patterns automatically
+- System continuously adapts to changing requirements
+- Optimization happens transparently in the background
+
+## Key Benefits
+
+**Immediate Functionality**: Your agent works right away, even for complex tasks
+
+**Automatic Optimization**: No manual performance tuning required
+
+**Cost Reduction**: AI usage decreases as agents learn efficient patterns
+
+**Reliability**: Learned patterns are more predictable than AI inference
+
+**Adaptability**: Agents can learn new patterns as requirements change
+
+## Next Steps
+
+- **[Understanding Generated Code](understanding-generated-code.md)** - Learn to read synthesized agents
+- **[Using Tools](using-tools.md)** - How agents interact with external services

data/docs/installation.md

@@ -0,0 +1,218 @@
+# Installation Guide
+
+Get started with Language Operator by installing the CLI and setting up your first cluster.
+
+## Prerequisites
+
+- Ruby >= 3.2.0
+- Kubernetes cluster (local or remote)
+- `kubectl` configured with cluster access
+
+## Install the CLI
+
+### Using RubyGems
+
+```bash
+gem install language-operator
+```
+
+### Verify Installation
+
+```bash
+aictl version
+```
+
+You should see the aictl version and operator status information.
+
+## Initial Setup
+
+### 1. Check System Status
+
+```bash
+aictl status
+```
+
+This command shows:
+- CLI version
+- Kubernetes connectivity
+- Language Operator installation status
+
+### 2. Run Quickstart Wizard
+
+For first-time users, the quickstart wizard guides you through setup:
+
+```bash
+aictl quickstart
+```
+
+The wizard will:
+- Configure your first cluster
+- Install Language Operator to Kubernetes
+- Set up basic models and personas
+- Create a sample agent
+
+### 3. Manual Setup (Alternative)
+
+If you prefer manual configuration:
+
+```bash
+# Create cluster configuration
+aictl cluster create my-cluster
+
+# Switch to the cluster
+aictl use my-cluster
+
+# Install Language Operator
+aictl install
+
+# Verify installation
+aictl status
+```
+
+## Kubernetes Setup
+
+### Local Development (minikube/kind)
+
+```bash
+# Start minikube
+minikube start
+
+# Or start kind cluster
+kind create cluster --name language-operator
+
+# Configure aictl
+aictl cluster create local --kubeconfig ~/.kube/config
+aictl use local
+```
+
+### Production Clusters
+
+```bash
+# Configure cluster with specific context
+aictl cluster create production \
+  --kubeconfig /path/to/kubeconfig \
+  --context production-context
+
+aictl use production
+```
+
+## Model Configuration
+
+Language Operator requires language model access. Configure your preferred provider:
+
+### OpenAI
+
+```bash
+export OPENAI_API_KEY="sk-your-api-key"
+aictl model create openai-gpt4 --provider openai --model gpt-4-turbo
+```
+
+### Anthropic (Claude)
+
+```bash
+export ANTHROPIC_API_KEY="sk-your-api-key"  
+aictl model create claude-sonnet --provider anthropic --model claude-3-sonnet
+```
+
+### Local Models (Ollama)
+
+```bash
+# Start Ollama locally
+ollama serve
+
+# Configure local model
+aictl model create local-llama --provider ollama --model llama3
+```
+
+## Verification
+
+### Test Your Setup
+
+```bash
+# Check overall status
+aictl status
+
+# List models
+aictl model list
+
+# Create a test agent
+aictl agent create test-agent
+
+# View agent status  
+aictl agent list
+aictl agent inspect test-agent
+```
+
+### Sample Output
+
+```bash
+$ aictl status
+
+Language Operator Status
+========================
+
+CLI Version:     0.1.30
+Cluster:         my-cluster (✓ connected)
+Operator:        v0.1.30 (✓ installed)
+Models:          2 configured
+Agents:          1 running
+
+✓ System ready
+```
+
+## Shell Completion (Optional)
+
+Enable command completion for better CLI experience:
+
+### Bash
+
+```bash
+echo 'eval "$(aictl completion bash)"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Zsh
+
+```bash
+echo 'eval "$(aictl completion zsh)"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### Fish
+
+```bash
+aictl completion fish | source
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Command not found: aictl**
+- Ensure Ruby gem bin directory is in PATH
+- Run `gem env` to check installation paths
+
+**Cannot connect to Kubernetes**
+- Verify `kubectl` works: `kubectl get nodes`
+- Check kubeconfig: `echo $KUBECONFIG`
+- Ensure cluster context is correct
+
+**Language Operator not found**
+- Run `aictl install` to install to current cluster
+- Check installation: `kubectl get pods -n language-operator`
+
+**Model configuration issues**
+- Verify API keys are set correctly
+- Test model connectivity: `aictl model test my-model`
+
+### Getting Help
+
+- Check command help: `aictl --help`
+- View logs: `aictl agent logs my-agent`
+- Report issues: [GitHub Issues](https://github.com/language-operator/language-operator-gem/issues)
+
+## Next Steps
+
+- **[Quickstart Guide](quickstart.md)** - Create your first agent
+- **[How Agents Work](how-agents-work.md)** - Understand the synthesis process
+- **[CLI Reference](cli-reference.md)** - Complete command documentation