# AI Integration - Intelligent Infrastructure Provisioning\n\nThe provisioning platform integrates AI capabilities to provide intelligent assistance for infrastructure configuration, deployment, and\ntroubleshooting.\nThis section documents the AI system architecture, features, and usage patterns.\n\n## Overview\n\nThe AI integration consists of multiple components working together to provide intelligent infrastructure provisioning:\n\n- **typdialog-ai**: AI-assisted form filling and configuration\n- **typdialog-ag**: Autonomous AI agents for complex workflows\n- **typdialog-prov-gen**: Natural language to Nickel configuration generation\n- **ai-service**: Core AI service backend with multi-provider support\n- **mcp-server**: Model Context Protocol server for LLM integration\n- **rag**: Retrieval-Augmented Generation for contextual knowledge\n\n## Key Features\n\n### Natural Language Configuration\n\nGenerate infrastructure configurations from plain English descriptions:\n```\nprovisioning ai generate "Create a production PostgreSQL cluster with encryption and daily backups"\n```\n\n### AI-Assisted Forms\n\nReal-time suggestions and explanations as you fill out configuration forms via typdialog web UI.\n\n### Intelligent Troubleshooting\n\nAI analyzes deployment failures and suggests fixes:\n```\nprovisioning ai troubleshoot deployment-12345\n```\n\n###\n\n Configuration Optimization\nAI reviews configurations and suggests performance and security improvements:\n```\nprovisioning ai optimize workspaces/prod/config.ncl\n```\n\n### Autonomous Agents\nAI agents execute multi-step workflows with minimal human intervention:\n```\nprovisioning ai agent --goal "Set up complete dev environment for Python app"\n```\n\n## Documentation Structure\n\n- [Architecture](architecture.md) - AI system architecture and components\n- [Natural Language Config](natural-language-config.md) - NL to Nickel generation\n- [AI-Assisted Forms](ai-assisted-forms.md) - typdialog-ai integration\n- [AI Agents](ai-agents.md) - typdialog-ag autonomous agents\n- [Config Generation](config-generation.md) - typdialog-prov-gen details\n- [RAG System](rag-system.md) - Retrieval-Augmented Generation\n- [MCP Integration](mcp-integration.md) - Model Context Protocol\n- [Security Policies](security-policies.md) - Cedar policies for AI\n- [Troubleshooting with AI](troubleshooting-with-ai.md) - AI debugging workflows\n- [API Reference](api-reference.md) - AI service API documentation\n- [Configuration](configuration.md) - AI system configuration guide\n- [Cost Management](cost-management.md) - Managing LLM API costs\n\n## Quick Start\n\n### Enable AI Features\n\n```\n# Edit provisioning config\nvim provisioning/config/ai.toml\n\n# Set provider and enable features\n[ai]\nenabled = true\nprovider = "anthropic"  # or "openai" or "local"\nmodel = "claude-sonnet-4"\n\n[ai.features]\nform_assistance = true\nconfig_generation = true\ntroubleshooting = true\n```\n\n### Generate Configuration from Natural Language\n\n```\n# Simple generation\nprovisioning ai generate "PostgreSQL database with encryption"\n\n# With specific schema\nprovisioning ai generate \\n  --schema database \\n  --output workspaces/dev/db.ncl \\n  "Production PostgreSQL with 100GB storage and daily backups"\n```\n\n### Use AI-Assisted Forms\n\n```\n# Open typdialog web UI with AI assistance\nprovisioning workspace init --interactive --ai-assist\n\n# AI provides real-time suggestions as you type\n# AI explains validation errors in plain English\n# AI fills multiple fields from natural language description\n```\n\n### Troubleshoot with AI\n\n```\n# Analyze failed deployment\nprovisioning ai troubleshoot deployment-12345\n\n# AI analyzes logs and suggests fixes\n# AI generates corrected configuration\n# AI explains root cause in plain language\n```\n\n## Security and Privacy\n\nThe AI system implements strict security controls:\n\n- ✅ **Cedar Policies**: AI access controlled by Cedar authorization\n- ✅ **Secret Isolation**: AI cannot access secrets directly\n- ✅ **Human Approval**: Critical operations require human approval\n- ✅ **Audit Trail**: All AI operations logged\n- ✅ **Data Sanitization**: Secrets/PII sanitized before sending to LLM\n- ✅ **Local Models**: Support for air-gapped deployments\n\nSee [Security Policies](security-policies.md) for complete details.\n\n## Supported LLM Providers\n\n|  | Provider | Models | Best For |  |\n|  | ---------- | -------- | ---------- |  |\n|  | **Anthropic** | Claude Sonnet 4, Claude Opus 4 | Complex configs, long context |  |\n|  | **OpenAI** | GPT-4 Turbo, GPT-4 | Fast suggestions, tool calling |  |\n|  | **Local** | Llama 3, Mistral | Air-gapped, privacy-critical |  |\n\n## Cost Considerations\n\nAI features incur LLM API costs. The system implements cost controls:\n\n- **Caching**: Reduces API calls by 50-80%\n- **Rate Limiting**: Prevents runaway costs\n- **Budget Limits**: Daily/monthly cost caps\n- **Local Models**: Zero marginal cost for air-gapped deployments\n\nSee [Cost Management](cost-management.md) for optimization strategies.\n\n## Architecture Decision Record\n\nThe AI integration is documented in:\n- [ADR-015: AI Integration Architecture](../architecture/adr/adr-015-ai-integration-architecture.md)\n\n## Next Steps\n\n1. Read [Architecture](architecture.md) to understand AI system design\n2. Configure AI features in [Configuration](configuration.md)\n3. Try [Natural Language Config](natural-language-config.md) for your first AI-generated config\n4. Explore [AI Agents](ai-agents.md) for automation workflows\n5. Review [Security Policies](security-policies.md) to understand access controls\n\n---\n\n**Version**: 1.0\n**Last Updated**: 2025-01-08\n**Status**: Active
