provisioning/docs/src/ai/natural-language-infrastructure.md

# Natural Language Infrastructure

Use natural language to describe infrastructure requirements and get automatically generated Nickel configurations and deployment plans.

## Overview

Natural Language Infrastructure (NLI) allows requesting infrastructure changes in plain English:

```bash
# Instead of writing complex Nickel...
provisioning ai "Deploy a 3-node HA PostgreSQL cluster with automatic backups in AWS"

# Or interactively...
provisioning ai interactive

# Interactive mode guides you through requirements
```

## How It Works

### Request Processing Pipeline

```text
User Natural Language Input
    ↓
Intent Recognition
    ├─ Extract resource type (server, database, cluster)
    ├─ Identify constraints (HA, region, size)
    └─ Detect options (monitoring, backup, encryption)
    ↓
RAG Knowledge Retrieval
    ├─ Find similar deployments
    ├─ Retrieve best practices
    └─ Get provider-specific guidance
    ↓
LLM Inference (GPT-4, Claude 3)
    ├─ Generate Nickel schema
    ├─ Calculate resource requirements
    └─ Create deployment plan
    ↓
Configuration Validation
    ├─ Type checking via Nickel compiler
    ├─ Schema validation
    └─ Constraint verification
    ↓
Infrastructure Deployment
    ├─ Dry-run simulation
    ├─ Cost estimation
    └─ User confirmation
    ↓
Execution & Monitoring
```

## Command Usage

### Simple Requests

```bash
# Web servers with load balancing
provisioning ai "Create 3 web servers with load balancer"

# Database setup
provisioning ai "Deploy PostgreSQL with 2 replicas and daily backups"

# Kubernetes cluster
provisioning ai "Create production Kubernetes cluster with Prometheus monitoring"
```

### Complex Requests

```bash
# Multi-cloud deployment
provisioning ai "
  Deploy:
  - 3 HA Kubernetes clusters (AWS, UpCloud, Hetzner)
  - PostgreSQL 15 with synchronous replication
  - Redis cluster for caching
  - ELK stack for logging
  - Prometheus for monitoring
  Constraints:
  - Cross-region high availability
  - Encrypted inter-region communication
  - Auto-scaling based on CPU (70%)
"

# Disaster recovery setup
provisioning ai "
  Set up disaster recovery for production environment:
  - Active-passive failover to secondary region
  - Daily automated backups (30-day retention)
  - Monthly DR tests with automated reports
  - RTO: 4 hours, RPO: 1 hour
  - Test failover every week
"
```

### Interactive Mode

```bash
# Start interactive mode
provisioning ai interactive

# System asks clarifying questions:
# Q: What type of infrastructure? (server, database, cluster, other)
# Q: Which cloud provider? (aws, upcloud, hetzner, local)
# Q: Production or development?
# Q: High availability required?
# Q: Expected load? (small, medium, large, enterprise)
# Q: Monitoring and logging?
# Q: Backup strategy?

# Shows generated configuration for approval
```

## Example: Web Application Deployment

### Request

```bash
provisioning ai "
  Deploy a production web application:
  - Frontend: 3 nginx servers with auto-scaling
  - API: 5 FastAPI instances behind load balancer
  - Database: HA PostgreSQL with read replicas
  - Cache: Redis cluster
  - Monitoring: Prometheus and Grafana
  - Logs: Elasticsearch + Kibana
  Environment: AWS
  Region: us-east-1 (primary), eu-west-1 (DR)
  Budget: $5000/month max
"
```

### Generated Configuration

The system generates:

**1. Nickel Infrastructure Definition**:

```nickel
{
  metadata = {
    generated_by = "provisioning-ai"
    timestamp = "2026-01-16T01:47:00Z"
    confidence = 0.94
  }

  infrastructure = {
    frontend = {
      servers = 3
      cpu = 4
      memory = 8
      type = "t3.large"
      auto_scaling = {
        min = 3
        max = 10
        target_cpu = 70
      }
    }

    api = {
      servers = 5
      cpu = 8
      memory = 16
      type = "t3.xlarge"
      load_balancer = {
        type = "application"
        health_check = "/health"
      }
    }

    database = {
      type = "postgresql"
      version = "15"
      replicas = 2
      backup = {
        enabled = true
        frequency = "daily"
        retention_days = 30
      }
    }

    cache = {
      type = "redis"
      nodes = 3
      cluster_mode = true
      replication = true
    }

    monitoring = {
      prometheus = true
      grafana = true
      retention_days = 30
    }

    logging = {
      elasticsearch = true
      kibana = true
      retention_days = 30
    }
  }

  provider = "aws"
  region_primary = "us-east-1"
  region_dr = "eu-west-1"

  cost_estimate = {
    monthly = "$4850"
    breakdown = {
      compute = "$2500"
      database = "$1200"
      cache = "$600"
      monitoring = "$400"
      networking = "$150"
    }
  }
}
```

**2. Deployment Plan**:

```text
Deployment Plan: Web Application (Production)

Phase 1: Network & Storage (2-3 hours)
  - Create VPCs in us-east-1 and eu-west-1
  - Set up inter-region VPN
  - Create EBS volumes for database
  - Create EFS for shared storage

Phase 2: Compute Instances (4-5 hours)
  - Launch 3 frontend servers
  - Launch 5 API servers
  - Create load balancers
  - Set up auto-scaling groups

Phase 3: Databases (3-4 hours)
  - Create PostgreSQL primary
  - Create read replicas
  - Configure replication
  - Run initial backup

Phase 4: Cache & Services (2-3 hours)
  - Create Redis cluster
  - Deploy Prometheus
  - Deploy Grafana
  - Deploy Elasticsearch/Kibana

Phase 5: Configuration (2-3 hours)
  - Configure health checks
  - Set up monitoring alerts
  - Configure log shipping
  - Deploy TLS certificates

Total Estimated Time: 13-18 hours
```

**3. Cost Breakdown**:

```text
Monthly Cost Estimate: $4,850

Compute               $2,500  (EC2 instances)
Database              $1,200  (RDS PostgreSQL)
Cache                 $600    (ElastiCache Redis)
Monitoring            $400    (CloudWatch + Grafana)
Networking            $150    (NAT Gateway, VPN)
```

**4. Risk Assessment**:

```text
Warnings:
- Budget limit reached at $4,850 (max: $5,000)
- Cross-region networking latency: 80-100ms
- Database failover time: 1-2 minutes

Recommendations:
- Implement connection pooling in API
- Use read replicas for analytics queries
- Consider spot instances for non-critical services (30% cost savings)
```

## Output Formats

### Get Deployment Script

```bash
# Get Bash deployment script
provisioning ai "..." --output bash > deploy.sh

# Get Nushell script
provisioning ai "..." --output nushell > deploy.nu

# Get Terraform
provisioning ai "..." --output terraform > main.tf

# Get Nickel (default)
provisioning ai "..." --output nickel > infrastructure.ncl
```

### Save for Later

```bash
# Save configuration for review
provisioning ai "..." --save deployment-plan --review

# Deploy from saved plan
provisioning apply deployment-plan

# Compare with current state
provisioning diff deployment-plan
```

## Configuration

### LLM Provider Selection

```bash
# Use OpenAI (default)
export PROVISIONING_AI_PROVIDER=openai
export PROVISIONING_AI_MODEL=gpt-4

# Use Anthropic
export PROVISIONING_AI_PROVIDER=anthropic
export PROVISIONING_AI_MODEL=claude-3-opus

# Use local model
export PROVISIONING_AI_PROVIDER=local
export PROVISIONING_AI_MODEL=llama2:70b
```

### Response Options

```yaml
# ~/.config/provisioning/ai.yaml
natural_language:
  output_format: nickel              # nickel, terraform, bash, nushell
  include_cost_estimate: true
  include_risk_assessment: true
  include_deployment_plan: true
  auto_review: false                 # Require approval before deploy
  dry_run: true                       # Simulate before execution
  confidence_threshold: 0.85          # Reject low-confidence results

  style:
    verbosity: detailed
    include_alternatives: true
    explain_reasoning: true
```

## Advanced Features

### Conditional Infrastructure

```bash
provisioning ai "
  Deploy web cluster:
  - If environment is production: HA setup with 5 nodes
  - If environment is staging: Standard setup with 2 nodes
  - If environment is dev: Single node with development tools
"
```

### Cost-Optimized Variants

```bash
# Generate cost-optimized alternative
provisioning ai "..." --optimize-for cost

# Generate performance-optimized alternative
provisioning ai "..." --optimize-for performance

# Generate high-availability alternative
provisioning ai "..." --optimize-for availability
```

### Template-Based Generation

```bash
# Use existing templates as base
provisioning ai "..." --template kubernetes-ha

# List available templates
provisioning ai templates list
```

## Safety & Validation

### Review Before Deploy

```bash
# Generate and review (no auto-execute)
provisioning ai "..." --review

# Review generated Nickel
cat deployment-plan.ncl

# Validate configuration
provisioning validate deployment-plan.ncl

# Dry-run to see what changes
provisioning apply --dry-run deployment-plan.ncl

# Apply after approval
provisioning apply deployment-plan.ncl
```

### Rollback Support

```bash
# Create deployment with automatic rollback
provisioning ai "..." --with-rollback

# Manual rollback if issues
provisioning workflow rollback --to-checkpoint

# View deployment history
provisioning history list --type infrastructure
```

## Limitations

- **Context Window**: Very large infrastructure descriptions may exceed LLM limits
- **Ambiguity**: Unclear requirements may produce suboptimal configurations
- **Provider Specifics**: Some provider-specific features may require manual adjustment
- **Cost**: API calls incur per-token charges
- **Latency**: Processing takes 2-10 seconds depending on complexity

## Related Documentation

- [AI Architecture](./ai-architecture.md) - System design
- [AI Service Crate](./ai-service-crate.md) - Core microservice
- [RAG & Knowledge](./rag-and-knowledge.md) - Knowledge retrieval
- [TypeDialog Integration](./typedialog-integration.md) - Form AI
- [Nickel Guide](../infrastructure/nickel-guide.md) - Configuration syntax