# Natural Language Configuration Generation\n\n**Status**: 🔴 Planned (Q2 2025 target)\n\nNatural Language Configuration (NLC) is a planned feature that enables users to describe infrastructure requirements in plain English and have the\nsystem automatically generate validated Nickel configurations. This feature combines natural language understanding with schema-aware generation and\nvalidation.\n\n## Feature Overview\n\n### What It Does\n\nTransform infrastructure descriptions into production-ready Nickel configurations:\n\n```\nUser Input:\n  "Create a production PostgreSQL cluster with 100GB storage,\n   daily backups, encryption enabled, and cross-region replication\n   to us-west-2"\n\nSystem Output:\n  provisioning/schemas/database.ncl (validated, production-ready)\n```\n\n### Primary Use Cases\n\n1. **Rapid Prototyping**: From description to working config in seconds\n2. **Infrastructure Documentation**: Describe infrastructure as code\n3. **Configuration Templates**: Generate reusable patterns\n4. **Non-Expert Operations**: Enable junior developers to provision infrastructure\n5. **Configuration Migration**: Describe existing infrastructure to generate Nickel\n\n## Architecture\n\n### Generation Pipeline\n\n```\nInput Description (Natural Language)\n        ↓\n┌─────────────────────────────────────┐\n│ Understanding & Analysis             │\n│ - Intent extraction                  │\n│ - Entity recognition                 │\n│ - Constraint identification          │\n│ - Best practice inference            │\n└─────────────────────┬───────────────┘\n                      ↓\n┌─────────────────────────────────────┐\n│ RAG Context Retrieval                │\n│ - Find similar configs               │\n│ - Retrieve best practices            │\n│ - Get schema examples                │\n│ - Identify constraints               │\n└─────────────────────┬───────────────┘\n                      ↓\n┌─────────────────────────────────────┐\n│ Schema-Aware Generation              │\n│ - Map entities to schema fields      │\n│ - Apply type constraints             │\n│ - Include required fields            │\n│ - Generate valid Nickel              │\n└─────────────────────┬───────────────┘\n                      ↓\n┌─────────────────────────────────────┐\n│ Validation & Refinement              │\n│ - Type checking                      │\n│ - Schema validation                  │\n│ - Policy compliance                  │\n│ - Security checks                    │\n└─────────────────────┬───────────────┘\n                      ↓\n┌─────────────────────────────────────┐\n│ Output & Explanation                 │\n│ - Generated Nickel config            │\n│ - Decision rationale                 │\n│ - Alternative suggestions            │\n│ - Warnings if any                    │\n└─────────────────────────────────────┘\n```\n\n## Planned Implementation Details\n\n### 1. Intent Extraction\n\nExtract structured intent from natural language:\n\n```\nInput: "Create a production PostgreSQL cluster with encryption and backups"\n\nExtracted Intent:\n{\n  resource_type: "database",\n  engine: "postgresql",\n  environment: "production",\n  requirements: [\n    {constraint: "encryption", type: "boolean", value: true},\n    {constraint: "backups", type: "enabled", frequency: "daily"},\n  ],\n  modifiers: ["production"],\n}\n```\n\n### 2. Entity Mapping\n\nMap natural language entities to schema fields:\n\n```\nDescription Terms → Schema Fields:\n  "100GB storage" → database.instance.allocated_storage_gb = 100\n  "daily backups" → backup.enabled = true, backup.frequency = "daily"\n  "encryption" → security.encryption_enabled = true\n  "cross-region" → backup.copy_to_region = "us-west-2"\n  "PostgreSQL 15" → database.engine_version = "15.0"\n```\n\n### 3. Prompt Engineering\n\nSophisticated prompting for schema-aware generation:\n\n```\nSystem Prompt:\nYou are generating Nickel infrastructure configurations.\nGenerate ONLY valid Nickel syntax.\nFollow these rules:\n- Use record syntax: `field = value`\n- Type annotations must be valid\n- All required fields must be present\n- Apply best practices for [ENVIRONMENT]\n\nSchema Context:\n[Database schema from provisioning/schemas/database.ncl]\n\nExamples:\n[3 relevant examples from RAG]\n\nUser Request:\n[User natural language description]\n\nGenerate the complete Nickel configuration.\nStart with: let { database = {\n```\n\n### 4. Iterative Refinement\n\nHandle generation errors through iteration:\n\n```\nAttempt 1: Generate initial config\n  ↓ Validate\n  ✗ Error: field `version` type mismatch (string vs number)\n  ↓ Re-prompt with error\nAttempt 2: Fix with context from error\n  ↓ Validate\n  ✓ Success: Config is valid\n```\n\n## Command Interface\n\n### CLI Usage\n\n```\n# Simple generation\nprovisioning ai generate "PostgreSQL database for production"\n\n# With schema specification\nprovisioning ai generate \\n  --schema database \\n  "Create PostgreSQL 15 with encryption and daily backups"\n\n# Interactive generation (refine output)\nprovisioning ai generate --interactive \\n  "Kubernetes cluster on AWS"\n\n# Generate and validate\nprovisioning ai generate \\n  --validate \\n  "Production Redis cluster with sentinel"\n\n# Generate and save directly\nprovisioning ai generate \\n  --schema database \\n  --output workspaces/prod/database.ncl \\n  "PostgreSQL production setup"\n\n# Batch generation from file\nprovisioning ai generate --batch descriptions.yaml\n```\n\n### Interactive Refinement\n\n```\n$ provisioning ai generate --interactive\n> Describe infrastructure: Create production PostgreSQL cluster\n\nGenerated configuration shown.\n\n> Refine: Add cross-region backup to us-west-2\nConfiguration updated.\n\n> Refine: Use larger instance class for performance\nConfiguration updated.\n\n> Accept? [y/n]: y\nConfiguration saved to: workspaces/prod/database.ncl\n```\n\n## Example Generations\n\n### Example 1: Simple Database\n\n**Input**:\n```\n"PostgreSQL database with 50GB storage and encryption"\n```\n\n**Output**:\n```\nlet {\n  database = {\n    engine = "postgresql",\n    version = "15.0",\n    \n    instance = {\n      instance_class = "db.t3.medium",\n      allocated_storage_gb = 50,\n      iops = 1000,\n    },\n    \n    security = {\n      encryption_enabled = true,\n      tls_enabled = true,\n      tls_version = "1.3",\n    },\n    \n    backup = {\n      enabled = true,\n      retention_days = 7,\n    },\n  }\n}\n```\n\n**Rationale**:\n- PostgreSQL 15 is current stable version\n- db.t3.medium suitable for 50GB with general workload\n- Encryption enabled per requirement\n- Automatic backups with 7-day retention (default)\n\n### Example 2: Complex Kubernetes Setup\n\n**Input**:\n```\n"Production Kubernetes cluster in AWS with 3 availability zones,\nauto-scaling from 3 to 10 nodes, managed PostgreSQL, and monitoring"\n```\n\n**Output**:\n```\nlet {\n  kubernetes = {\n    version = "1.28.0",\n    \n    cluster = {\n      name = "prod-cluster",\n      region = "us-east-1",\n      availability_zones = ["us-east-1a", "us-east-1b", "us-east-1c"],\n    },\n    \n    node_group = {\n      min_size = 3,\n      max_size = 10,\n      desired_size = 3,\n      instance_type = "t3.large",\n      \n      auto_scaling = {\n        enabled = true,\n        target_cpu = 70,\n        scale_down_delay = 300,\n      },\n    },\n    \n    managed_services = {\n      postgres = {\n        enabled = true,\n        engine = "postgresql",\n        version = "15.0",\n        storage_gb = 100,\n      },\n    },\n    \n    monitoring = {\n      prometheus = {enabled = true},\n      grafana = {enabled = true},\n      cloudwatch_integration = true,\n    },\n    \n    networking = {\n      vpc_cidr = "10.0.0.0/16",\n      enable_nat_gateway = true,\n      enable_dns_hostnames = true,\n    },\n  }\n}\n```\n\n**Rationale**:\n- 3 AZs for high availability\n- t3.large balances cost and performance for general workload\n- Auto-scaling target 70% CPU (best practice)\n- Managed PostgreSQL reduces operational overhead\n- Full observability with Prometheus + Grafana\n\n## Configuration and Constraints\n\n### Configurable Generation Parameters\n\n```\n# In provisioning/config/ai.toml\n[ai.generation]\n# Which schema to use by default\ndefault_schema = "database"\n\n# Whether to require explicit environment specification\nrequire_environment = false\n\n# Optimization targets\noptimization_target = "balanced"  # or "cost", "performance"\n\n# Best practices to always apply\nbest_practices = [\n  "encryption",\n  "high_availability",\n  "monitoring",\n  "backup",\n]\n\n# Constraints that limit generation\n[ai.generation.constraints]\nmin_storage_gb = 10\nmax_instances = 100\nallowed_engines = ["postgresql", "mysql", "mongodb"]\n\n# Validation before accepting generated config\n[ai.generation.validation]\nstrict_mode = true\nrequire_security_review = false\nrequire_compliance_check = true\n```\n\n### Safety Guardrails\n\n1. **Required Fields**: All schema required fields must be present\n2. **Type Validation**: Generated values must match schema types\n3. **Security Checks**: Encryption/backups enabled for production\n4. **Cost Estimation**: Warn if projected cost exceeds threshold\n5. **Resource Limits**: Enforce organizational constraints\n6. **Policy Compliance**: Check against Cedar policies\n\n## User Workflow\n\n### Typical Usage Session\n\n```\n# 1. Describe infrastructure need\n$ provisioning ai generate "I need a database for my web app"\n\n# System generates basic config, suggests refinements\n# Generated config shown with explanations\n\n# 2. Refine if needed\n$ provisioning ai generate --interactive\n\n# 3. Review and validate\n$ provisioning ai validate workspaces/dev/database.ncl\n\n# 4. Deploy\n$ provisioning workspace apply workspaces/dev\n\n# 5. Monitor\n$ provisioning workspace logs database\n```\n\n## Integration with Other Systems\n\n### RAG Integration\n\nNLC uses RAG to find similar configurations:\n\n```\nUser: "Create Kubernetes cluster"\n  ↓\nRAG searches for:\n  - Existing Kubernetes configs in workspaces\n  - Kubernetes documentation and examples\n  - Best practices from provisioning/docs/guides/kubernetes.md\n  ↓\nContext fed to LLM for generation\n```\n\n### Form Assistance\n\nNLC and form assistance share components:\n\n- Intent extraction for pre-filling forms\n- Constraint validation for form field values\n- Explanation generation for validation errors\n\n### CLI Integration\n\n```\n# Generate then preview\n| provisioning ai generate "PostgreSQL prod" | \ |\n  provisioning config preview\n\n# Generate and apply\nprovisioning ai generate \\n  --apply \\n  --environment prod \\n  "PostgreSQL cluster"\n```\n\n## Testing and Validation\n\n### Test Cases (Planned)\n\n1. **Simple Descriptions**: Single resource, few requirements\n   - "PostgreSQL database"\n   - "Redis cache"\n\n2. **Complex Descriptions**: Multiple resources, constraints\n   - "Kubernetes with managed database and monitoring"\n   - "Multi-region deployment with failover"\n\n3. **Edge Cases**:\n   - Conflicting requirements\n   - Ambiguous specifications\n   - Deprecated technologies\n\n4. **Refinement Cycles**:\n   - Interactive generation with multiple refines\n   - Error recovery and re-prompting\n   - User feedback incorporation\n\n## Success Criteria (Q2 2025)\n\n- ✅ Generates valid Nickel for 90% of user descriptions\n- ✅ Generated configs pass all schema validation\n- ✅ Supports top 10 infrastructure patterns\n- ✅ Interactive refinement works smoothly\n- ✅ Error messages explain issues clearly\n- ✅ User testing with non-experts succeeds\n- ✅ Documentation complete with examples\n- ✅ Integration with form assistance operational\n\n## Related Documentation\n\n- [Architecture](architecture.md) - AI system overview\n- [AI-Assisted Forms](ai-assisted-forms.md) - Related form feature\n- [RAG System](rag-system.md) - Context retrieval\n- [Configuration](configuration.md) - Setup guide\n- [ADR-015](../architecture/adr/adr-015-ai-integration-architecture.md) - Design decisions\n\n---\n\n**Status**: 🔴 Planned\n**Target Release**: Q2 2025\n**Last Updated**: 2025-01-13\n**Architecture**: Complete\n**Implementation**: In Design Phase
