# AI & Machine Learning

Provisioning includes comprehensive AI capabilities for infrastructure automation via natural
language, intelligent configuration suggestions, and anomaly detection.

## Overview

The AI system consists of three integrated components:

1. **TypeDialog AI Backends** - Interactive form intelligence and agent automation
2. **AI Service Microservice** - Central AI processing and coordination
3. **Core AI Libraries** - Nushell query processing and LLM integration

## Key Capabilities

### Natural Language Infrastructure

Request infrastructure changes in plain English:

```bash
# Natural language request
provisioning ai "Create 3 web servers with load balancing and auto-scaling"

# Returns:
# - Parsed infrastructure requirements
# - Generated Nickel configuration
# - Deployment confirmation
```

### Intelligent Configuration

AI suggests optimal configurations based on context:

- Database selection and tuning
- Network topology recommendations
- Security policy generation
- Resource allocation optimization

### Anomaly Detection

Continuous monitoring and intelligent alerting:

- Infrastructure health anomalies
- Performance pattern detection
- Security issue identification
- Predictive alerting

## Components at a Glance

| Component | Purpose | Technology |
| --- | --- | --- |
| **typedialog-ai** | Form intelligence & suggestions | HTTP server, SurrealDB |
| **typedialog-ag** | AI agents & workflow automation | Type-safe agents, Nickel transpilation |
| **ai-service** | Central AI microservice | Rust, LLM integration |
| **rag** | Knowledge base retrieval | Semantic search, embeddings |
| **mcp-server** | Model Context Protocol | AI tool interface |
| **detector** | Anomaly detection system | Pattern recognition |

## Quick Start

### Enable AI Features

```bash
# Install AI tools
provisioning install ai-tools

# Configure AI service
provisioning ai configure --provider openai --model gpt-4

# Test AI capabilities
provisioning ai test
```

### Use Natural Language

```bash
# Simple request
provisioning ai "Create a Kubernetes cluster"

# Complex request with options
provisioning ai "Deploy PostgreSQL HA cluster with replication in AWS, backup to S3"

# Get help on AI features
provisioning help ai
```

## Architecture

The AI system follows a layered architecture:

```text
┌─────────────────────────────────┐
│  User Interface Layer            │
│  • Natural language input        │
│  • TypeDialog AI forms           │
│  • Chat interface                │
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│  AI Orchestration Layer          │
│  • AI Service (Rust)             │
│  • Query processing (Nushell)    │
│  • Intent recognition            │
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│  Knowledge & Processing Layer    │
│  • RAG (Retrieval)               │
│  • LLM Integration               │
│  • MCP Server                    │
│  • Detector (anomalies)          │
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│  Infrastructure Layer            │
│  • Nickel configuration          │
│  • Deployment execution          │
│  • Monitoring & feedback         │
└─────────────────────────────────┘
```

## Topics

- [AI Architecture](./ai-architecture.md) - System design and components
- [TypeDialog Integration](./typedialog-integration.md) - AI forms and agents
- [AI Service Crate](./ai-service-crate.md) - Core AI microservice
- [RAG & Knowledge](./rag-and-knowledge.md) - Knowledge retrieval system
- [Natural Language Infrastructure](./natural-language-infrastructure.md) - LLM-driven IaC

## Configuration

### Environment Variables

```bash
# LLM Provider
export PROVISIONING_AI_PROVIDER=openai        # openai, anthropic, local
export PROVISIONING_AI_MODEL=gpt-4            # Model identifier
export PROVISIONING_AI_API_KEY=sk-...         # API key

# AI Service
export PROVISIONING_AI_SERVICE_PORT=9091      # AI service port
export PROVISIONING_AI_ENABLE_ANOMALY=true    # Enable detector
export PROVISIONING_AI_RAG_THRESHOLD=0.75     # Similarity threshold
```

### Configuration File

```yaml
# ~/.config/provisioning/ai.yaml
ai:
  enabled: true
  provider: openai
  model: gpt-4
  api_key: ${PROVISIONING_AI_API_KEY}

  service:
    port: 9091
    timeout: 30
    max_retries: 3

  typedialog:
    ai_enabled: true
    ag_enabled: true
    suggestions: true

  rag:
    enabled: true
    similarity_threshold: 0.75
    max_results: 5

  detector:
    enabled: true
    update_interval: 60
    alert_threshold: 0.8
```

## Use Cases

### 1. Infrastructure from Description

Describe infrastructure in natural language, get Nickel configuration:

```bash
provisioning ai deploy "
  Create a production Kubernetes cluster with:
  - 3 control planes
  - 5 worker nodes
  - HA PostgreSQL (3 nodes)
  - Prometheus monitoring
  - Encrypted networking
"
```

### 2. Configuration Assistance

Get AI suggestions while filling out forms:

```bash
provisioning setup profile
# TypeDialog shows suggestions based on context
# Database recommendations based on workload
# Security settings optimized for environment
```

### 3. Troubleshooting

AI analyzes logs and suggests fixes:

```bash
provisioning ai troubleshoot --service orchestrator

# Output:
# Issue detected: High memory usage
# Likely cause: Task queue backlog
# Suggestion: Scale orchestrator replicas to 3
# Command: provisioning orchestrator scale --replicas 3
```

### 4. Anomaly Detection

Continuous monitoring with intelligent alerts:

```bash
provisioning ai anomalies --since 1h

# Output:
# ⚠️  Unusual pattern detected
# Time: 2026-01-16T01:47:00Z
# Service: control-center
# Metric: API response time
# Baseline: 45ms → Current: 320ms (+611%)
# Likelihood: Query performance regression
```

## Limitations

- **LLM Dependency**: Requires external LLM provider (OpenAI, Anthropic, etc.)
- **Network Required**: Cloud-based LLM providers need internet connectivity
- **Context Window**: Large infrastructures may exceed LLM context limits
- **Cost**: API calls incur per-token charges
- **Latency**: Natural language processing adds response latency (2-5 seconds)

## Configuration Files

Key files for AI configuration:

| File | Purpose |
| --- | --- |
| `.typedialog/ai.db` | AI SurrealDB database (typedialog-ai) |
| `.typedialog/agent-*.yaml` | AI agent definitions (typedialog-ag) |
| `~/.config/provisioning/ai.yaml` | User AI settings |
| `provisioning/core/versions.ncl` | TypeDialog versions |
| `core/nulib/lib_provisioning/ai/` | Core AI libraries |
| `platform/crates/ai-service/` | AI service crate |

## Performance

### Typical Latencies

| Operation | Latency |
| --- | --- |
| Simple request parsing | 100-200ms |
| LLM inference | 2-5 seconds |
| Configuration generation | 500ms-1s |
| Anomaly detection | 50-100ms |

### Scalability

- **Concurrent requests**: 100+ (load balanced)
- **Query processing**: 10,000+ queries/second
- **RAG similarity search**: <50ms for 1M documents
- **Anomaly detection**: Real-time on 1000+ metrics

## Security

### API Keys

- Stored encrypted in vault-service
- Never logged or persisted in plain text
- Rotated automatically (configurable)
- Audit trail for all API usage

### Data Privacy

- Natural language queries not stored by default
- LLM provider agreements (OpenAI terms, etc.)
- Local-only RAG option available
- GDPR compliance support

## Related Documentation

- [Features Overview](../features/README.md) - AI feature list
- [MCP Server](../architecture/component-architecture.md#mcp-server) - LLM integration
- [Security System](../security/README.md) - API key management
- [Operations Guide](../operations/README.md) - AI service management
